HttpService

public protocol HttpService

An HTTP service can be used to abstract a specific endpoint away from specific requests. Usually, you would have one HTTP service per API that you use and possibly different services for testing/staging and production. Intuitively, a specific implementation of an HTTP service represents a particular API.

Associated Types

  • The type of error that requests scheduled against this service emits. Defaults to Squid.Error.

    Declaration

    Swift

    associatedtype RequestError : Error = Squid.Error

API Configuration

  • The URL of the API represented by this HTTP service (e.g. “api.example.com”). This is the only field that needs to be provided by a particular implementation. This url should not contain the scheme (e.g. “https://”) as it might get overwritten unexpectedly by a request.

    Declaration

    Swift

    var apiUrl: UrlConvertible { get }
  • usesSecureProtocol Default implementation

    Whether requests scheduled against this service use secure protocols (e.g. “https” for HTTP requests, “wss” for WebSockets).

    Default Implementation

    By default, requests are secured.

    Declaration

    Swift

    var usesSecureProtocol: Bool { get }
  • header Default implementation

    A header that ought to be used by all requests issued against the API represented by this HTTP service. Most commonly, this header contains fields such as the API key or some form of Authorization. Request headers always overwrite header fields set by the HTTP service they are used with.

    Default Implementation

    By default, the HTTP service does not set any headers.

    Declaration

    Swift

    var header: HttpHeader { get }
  • asyncHeader Default implementation

    A header that is provided asynchronously. If possible, use the header property instead. Implementing this property might be useful if some third-party component is used to e.g. fetch access tokens asynchronously. It will overwrite any values set in the header property if keys conflict.

    Default Implementation

    Declaration

    Swift

    var asyncHeader: Future<HttpHeader, Error> { get }

Low-Level Configuration

  • sessionConfiguration Default implementation

    The session configuration to use for all requests using this service.

    Default Implementation

    By default, URLSessionConfiguration.default is used.

    Declaration

    Swift

    var sessionConfiguration: URLSessionConfiguration { get }

Error Handling

  • retrierFactory Default implementation

    The retrier factory provides retriers for requests.

    Note

    When scheduling a StreamRequest, retriers will be ignored.

    Default Implementation

    By default, the default factory of the stateless NilRetrier is used, i.e. requests are never retried.

    Declaration

    Swift

    var retrierFactory: RetrierFactory { get }

  • Maps errors retrieved from requests to this service’s custom error.

    Declaration

    Swift

    func mapError(_ error: Squid.Error) -> RequestError

Hooks

  • hook Default implementation

    The hook describes a component that is called whenever a request is scheduled for this service and a result was obtained for a request. If an error occurs during scheduling, an error is indicated.

    Note

    When scheduling a StreamRequest, only the onFailure of the hook will be called when an error occurs.

    Default Implementation

    By default, a hook that does nothing is used.

    Declaration

    Swift

    var hook: ServiceHook { get }

Available where RequestError == Squid.Error

  • mapError(_:) Default implementation

    Default Implementation

    If the default error type Squid.Error is used, it is simply returned without modification.

    Declaration

    Swift

    public func mapError(_ error: Squid.Error) -> RequestError