Request

public protocol Request : NetworkRequest

The request protocol is the core building block of the Squid framework. The general idea of a request is that it declaratively defines the content of an HTTP request. It is then scheduled against an API that is represented by a HttpService. Scheduling the request returns a Response. This response is a shared publisher that can be subscribed to.

The reason for abstracting requests away from APIs, i.e. HTTP services, is that often, requests are issued against differing domains with differing security requirements during testing/staging and development. Hence, it makes sense to capture methods, routing paths, headers, etc. in the request itself but abstract away the actual URL and common API headers into the HttpService.

Types

  • The expected type of the server’s response upon a successful request.

    Declaration

    Swift

    associatedtype Result

Request Specification

  • method Default implementation

    The HTTP method of the request.

    Default Implementation

    Defaults to GET.

    Declaration

    Swift

    var method: HttpMethod { get }
  • body Default implementation

    The HTTP body of the request. May only be set to an instance of something other than HttpData.Empty if method is set to PUT or GET. By default, an instance of HttpData.Empty is returned.

    Default Implementation

    Defaults to an empty body.

    Declaration

    Swift

    var body: HttpBody { get }
  • prepare(_:) Default implementation

    Prepares the URL request that will be sent. The function is passed the request as assembled based on all other properties. You may modify the request as you wish.

    Note

    This function should only be used if it is not possible to specify the request in a fully declarative form.

    Attention

    For performance reasons, you should not modify the request’s body at the moment. When you modify it and debug statements are printed, the old body may be printed although this is not the body being sent.

    Default Implementation

    The default implementation returns the request without any modifications.

    Declaration

    Swift

    func prepare(_ request: URLRequest) -> URLRequest

    Parameters

    request

    The request, pre-populated with all properties specified in the request.

Expected Response

  • acceptedStatusCodes Default implementation

    The range of accepted status codes for the request. Whenever the response’s status code is not in the provided range, the request is considered to have failed.

    Default Implementation

    By default, all 2xx status codes are accepted.

    Declaration

    Swift

    var acceptedStatusCodes: CountableClosedRange<Int> { get }
  • Upon successful completion of the HTTP request itself, this method is responsible for transforming the raw Data returned by the HTTP response into the response’s result type. If this method throws an exception, the request is also considered to have failed. As a result, retriers are called and the Response publisher returned upon scheduling the request will not yield any value.

    This method has a default implementation if the request’s result type is either Void or Data. In the former case, this method does nothing and returns Void. In the latter case, it simply returns the data passed as parameter. As a result, in both cases, this method will never throw.

    In addition, it has a default implementation if the return type is String. The data is expected to be encoded with UTF-8.

    Declaration

    Swift

    func decode(_ data: Data) throws -> Result

    Parameters

    data

    The raw data returned by the raw HTTP response.

Scheduling Requests

  • schedule(with:) Extension method

    Schedules the request against the API specified by the given HTTP service. The response is a publisher that yields the request’s result type upon success or an error upon failure. The schedule method is the only method that may be used to obtain responses for requests. When the application is compiled in DEBUG mode and Squid.Logger has not been silenced, the request also prints debugging statements to the console: firstly, the request itself is printed as soon as it is scheduled. Secondly, the response (or an error) is printed as soon as it has been returned. Printing in RELEASE mode is not possible as the respective print statements are not included in the binary.

    Declaration

    Swift

    public func schedule<S>(with service: S) -> Response<Self, S> where S : HttpService

    Parameters

    service

    The service representing the API against which to schedule this request.

  • Schedules the request as paginated request against the API specified by the given HTTP service. The response is a PaginationResponse. Consult its documentation to know how to work with a paginated request.

    Declaration

    Swift

    public func schedule<P, S>(
        forPaginationWith service: S, chunk: Int, zeroBasedPageIndex: Bool = false,
        decode: @escaping (Data, Self) throws -> P
    ) -> Paginator<Self, P, S> where P: PaginatedData, P.DataType == Result, S: HttpService

    Parameters

    service

    The service representing the API against which to schedule paginated requests.

    chunk

    The (maximum) number of elements that are requested per page. The number of returned elements is only smaller than the given chunk if the given page index is the index of the last page and the number of elements is not divisible by the chunk.

    zeroBasedPageIndex

    Whether the API endpoint that the request is scheduled against indexes the first page with 0. By default, the first page is indexed by 1.

    decode

    A closure that is used to decode the received data to the defined type of PaginatedData. The closure receives both the body and the request as the original Request.decode(_:) method might want to be used.