Service

public protocol Service

A protocol to define a REST API service

To define a service, implement the Service protocol. Each service has a distinct base URL, and all requests made to the service will use this base URL. Use services to logically group requests together for better organization and code reusability.

Note

For implementing dynamic base URLs (such as with different environments like Dev, Stage, Prod, etc), it is not necessary to define multiple services.

About the protocol

This protocol only has two properties- Service.baseURL and Service.session. The baseURL property is required to be implemented, and provides the base URL used for all requests (see Making Requests for more on requests). The session property is a URLSession instance that requests are made using. This property has a default implementation of URLSession.shared, but you can override this with your own. Additionally, when making requests, a session may be passed in per request.

Properties

  • The base URL of the service. This value is shared among all endpoints on the service.

    Declaration

    Swift

    var baseURL: URL { get }
  • session Default implementation

    The URLSession that requests to this service will use.

    The value of this property will be used for all requests made on this service, unless an override is provided to a given request.

    Default Implementation

    Returns URLSession.shared.

    Declaration

    Swift

    static var session: URLSession { get }

Handling Responses

  • Completion handler based response for an HTTP request

    • request: The request made
    • response: The response received
    • data: The data received, if any

    Declaration

    Swift

    typealias Response = (request: URLRequest, response: HTTPURLResponse, data: Data?)
  • Response for an HTTP request using a Combine publisher

    • request: The request made
    • response: The response received
    • data: Data received

    Declaration

    Swift

    typealias PublisherResponse = (request: URLRequest, response: HTTPURLResponse, data: Data)
  • Response for an async HTTP request

    • request: The request made
    • response: The response received
    • data: Data received

    Declaration

    Swift

    typealias AsyncResponse = (request: URLRequest, response: HTTPURLResponse, data: Data)
  • Completion handler for requests made

    Declaration

    Swift

    typealias RequestCompletion = (_ result: Result<Response, RequestError>) -> ()

    Parameters

    result

    Result receieved

Making Requests

  • request(_:session:) Extension method, asynchronous

    Make a request asyncrhonously

    Throws

    A RequestError of the error which occurred.

    Declaration

    Swift

    @available(iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0, *)
    public func request<Request>(_ request: Request, session: URLSession = session) async throws -> AsyncResponse where Request : ServiceRequest

    Parameters

    request

    The request to execute

    session

    The session to use. If not specified, the default provided by the session property of the Service will be used

    Return Value

    A tuple containing the request, response, and data.

  • requestPublisher(_:session:) Extension method

    Make a request using a Combine publisher.

    Declaration

    Swift

    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    public func requestPublisher<Request>(_ request: Request, session: URLSession = session) -> AnyPublisher<PublisherResponse, RequestError> where Request : ServiceRequest

    Parameters

    request

    The request to execute

    session

    The session to use. If not specified, the default provided by the session property of the Service will be used

    Return Value

    A Combine publisher of type PublisherResponse.

  • Make a request using the given ServiceRequest and parameters

    Call this method to create a URLSessionDataTask for a given request. By default, the resume() will be called on the task, executing the request immediately.

    Warning

    When autoResumeTask is true (this is the default value), calling resume() on the returned task will cause the request to be executed again.

    Declaration

    Swift

    @discardableResult
    func request<Request>(_ request: Request, session: URLSession = session, autoResumeTask: Bool = true, completion: @escaping RequestCompletion) -> URLSessionDataTask? where Request : ServiceRequest

    Parameters

    request

    The ServiceRequest to use

    session

    The session to use. If none is provided, the default session property on the service will be used.

    autoResumeTask

    If true, then resume() will be called automatically on the created URLSessionDataTask. Default value is true.

    completion

    A RequestCompletion handler which is executed when the task is completed.

    Return Value

    A URLSessionDataTask, or nil if there was a failure in creating the task.