RestingClient

open class RestingClient

RestingClient is the core class of RestingKit. It allows sending requests and receiving their responses as promises through a high-level API.

The RestingClient is configured with the following components:

  • baseUrl: The base URL of the server we want to connect. One client can only connect to a single base URL. Therefore, if you wish to use multiple APIs, you should use different clients for each of them.
  • decoder: The decoder to use for decoding responses.
  • requestConverter: The converter to use for converting RestingRequests to HTTPRequests.
  • interceptors: The interceptors to run for each request and response.
  • httpClient: The client responsible for sending the request and receiving its response.

There are two function families within the class: perform(_:) and upload(_:), each with several overloads for convenience. Even though they do the same thing in the core, The way to achieve their goal is different. perform(_:) sends the request by loading the request body into memory, while upload(_:) streams the body from a file without loading it. upload(_:) also allows tracking upload progress. For most requests perform(_:) should be good enough, but for cases when the request body is expected to be large, upload(_:) should be preferred.

The process within a RestingClient is the following:

  1. The request converter converts the RestingRequest into an HTTPRequest.
  2. The interceptors are run with the produced HTTPRequest in the order provided. At this point, one of the interceptors might decide to modify the request or stop the execution chain by returning a response or and error.
  3. If the interceptors doesn’t block the chain, the HTTPClient is called to perform the actual request.
  4. The response from HTTPClient is passed to the interceptors. At this point, an interceptor might decide to change the response or recover from an error.
  5. The response is then converted into an HTTPResponse by decoding the response body.

Cases when request promises might fail:

  1. The encoding of the request has failed.
  2. The decoding of the response has faied.
  3. Networking errors.
  4. The response status was not 2xx.
  5. An interceptor decided to raise an error.

  • Creates a RestingClient with the provided configuration.

    Declaration

    Swift

    public init(baseUrl: String,
            decoder: JSONDecoder = JSONDecoder(),
            httpClient: HTTPClient = AlamofireClient(),
            requestConverter: RequestConverter,
            interceptors: [RestingInterceptor] = [])

    Parameters

    baseUrl

    The base URL of the endpoint to use by the client (ex: https://api.example.com/v2). Each request’s path sent through the RestingClient will be relative to this URL.
    decoder

    The JSONDecoder to use when decoding responses from the requests.
    httpClient

    The HTTPClient to use for sending the requests.
    requestConverter

    The RequestConverter to use for converting RestingRequests to HTTPRequests.
    interceptors

    RestingInterceptors to run when sending each request and response.

  • Performs a request.

    Uses the RequestConverter to convert the request into an HTTPRequest, run the provided interceptors, call the HTTPClient to perform the request and finally decode the response using the provided decoder.

    Declaration

    Swift

    open func perform<RequestType: Encodable, ResponseType: Decodable>
    (_ request: RestingRequest<RequestType, ResponseType>) -> Promise<HTTPResponse<ResponseType>>

    Parameters

    request

    The request to perform.

    Return Value

    A promise for the response.

  • Performs a request. Overload for optional response type.

    Uses the RequestConverter to convert the request into an HTTPRequest, run the provided interceptors, call the HTTPClient to perform the request and finally decode the response using the provided decoder.

    Use this overload when the resposne might be empty. The returned promise will resolve with nil if and only if the HTTP response body is empty.

    Warning

    A response with a content-length greater then zero will try to decode the response to ResponseType.

    Declaration

    Swift

    open func perform<RequestType: Encodable, ResponseType: Decodable>
    (_ request: RestingRequest<RequestType, ResponseType?>) -> Promise<HTTPResponse<ResponseType?>>

    Parameters

    request

    The request to perform.

    Return Value

    A promise for the response.

  • Performs a request. Overload for empty response.

    Uses the RequestConverter to convert the request into an HTTPRequest, run the provided interceptors, call the HTTPClient to perform the request and finally decode the response using the provided decoder.

    Use this overload when the resposne is always empty or will always be discarded.

    Declaration

    Swift

    open func perform<RequestType: Encodable>(_ request: RestingRequest<RequestType, Nothing>)
    -> Promise<HTTPResponse<Void>>

    Parameters

    request

    The request to perform.

    Return Value

    A promise for the response.

  • Uploads a request.

    Uses the RequestConverter to convert the request into an HTTPRequest, run the provided interceptors, call the HTTPClient to perform the request and finally decode the response using the provided decoder.

    Prefer using upload over perform when the request body way me large as is will not be loaded into memory or you want to track the upload progress of the request.

    Warning

    The progress callback on the returned ProgressablePromise is not guarenteed to be called. This behavious depends on the implementation of the RequestConverter (as it needs to be converted to a streamed request) and the HTTPClient (as it is its responsibility to call the handler). Implementations provided by RestingKit supports the call to the progress callback.

    Declaration

    Swift

    open func upload<RequestType: Encodable, ResponseType: Decodable>
    (_ request: RestingRequest<RequestType, ResponseType>) -> ProgressablePromise<HTTPResponse<ResponseType>>

    Parameters

    request

    The request to perform.

    Return Value

    A promise with progress handler for the response.

  • Uploads a request. Overload for optional response type.

    Uses the RequestConverter to convert the request into an HTTPRequest, run the provided interceptors, call the HTTPClient to perform the request and finally decode the response using the provided decoder.

    Prefer using upload over perform when the request body way me large as is will not be loaded into memory or you want to track the upload progress of the request.

    Use this overload when the resposne might be empty. The returned promise will resolve with nil if and only if the HTTP response body is empty.

    Warning

    A response with a content-length greater then zero will try to decode the response to ResponseType.

    Warning

    The progress callback on the returned ProgressablePromise is not guarenteed to be called. This behavious depends on the implementation of the RequestConverter (as it needs to be converted to a streamed request) and the HTTPClient (as it is its responsibility to call the handler). Implementations provided by RestingKit supports the call to the progress callback.

    Declaration

    Swift

    open func upload<RequestType: Encodable, ResponseType: Decodable>
    (_ request: RestingRequest<RequestType, ResponseType?>) -> ProgressablePromise<HTTPResponse<ResponseType?>>

    Parameters

    request

    The request to perform.

    Return Value

    A promise with progress handler for the response.

  • Uploads a request. Overload for empty response.

    Uses the RequestConverter to convert the request into an HTTPRequest, run the provided interceptors, call the HTTPClient to perform the request and finally decode the response using the provided decoder.

    Prefer using upload over perform when the request body way me large as is will not be loaded into memory or you want to track the upload progress of the request.

    Use this overload when the resposne is always empty or will always be discarded.

    Warning

    The progress callback on the returned ProgressablePromise is not guarenteed to be called. This behavious depends on the implementation of the RequestConverter (as it needs to be converted to a streamed request) and the HTTPClient (as it is its responsibility to call the handler). Implementations provided by RestingKit supports the call to the progress callback.

    Declaration

    Swift

    open func upload<RequestType: Encodable>(_ request: RestingRequest<RequestType, Nothing>)
    -> ProgressablePromise<HTTPResponse<Void>>

    Parameters

    request

    The request to perform.

    Return Value

    A promise with progress handler for the response.