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

Result
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 }


                    
                    
                    decode(_:)

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.


                    
                    
                    schedule(forPaginationWith:chunk:zeroBasedPageIndex:decode:)

Extension method

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.