Endpoints

Endpoints is a small library for creating statically and strongly-typed definitions of endpoint with paths, methods, inputs and outputs.

Purpose

The purpose of Endpoints is to, in a type-safe way, define how to create a URLRequest from typed properties and, additionally, define how a response for the request should be handled. The library not only includes the ability to create these requests in a type-safe way, but also includes helpers to perform the requests using URLSession. Endpoints does not try to wrap the URL loading system to provide features on top of it like Alamofire. Instead, Endpoints focuses on defining requests and converting those requests into URLRequest objects to be plugged into vanilla URLSessions. However, this library could be used in conjunction with Alamofire if desired.

Getting Started

The basic process for defining an Endpoint starts with defining a value conforming to RequestType. With the RequestType protocol, you are encapsulating all the properties that are needed for making a request and the types for parsing the response. Within the RequestType, the endpoint static var serves as an immutable definition of the server's endpoint and how the variable pieces of the RequestType should fit together when making the full request.

To get started, first create a type (struct or class) conforming to RequestType. There are only two required elements to conform: defining the Response and creating the Endpoint.

Requests and Endpoints do not contain base URLs so that these requests can be used on different environments. Environments are defined as conforming to the EnvironmentType and implement a baseURL as well as an optional requestProcessor which has a final hook before URLRequest creation to modify the URLRequest to attach authentication or signatures.

To find out more about the pieces of the RequestType, check out Defining a ResponseType on the wiki.

Examples

The most basic example of defining an Endpoint is creating a simple GET request. This means defining a type that conforms to RequestType such as:

struct MyRequest: RequestType {
    static let endpoint: Endpoint<MyRequest> = Endpoint(
        method: .get,
        path: "path/to/resource"
    )

    struct Response: Decodable {
        let resourceId: String
        let resourceName: String
    }
}

This includes a Response associated type (can be typealiased to a more complex existing type) which defines how the response will come back from the request.

Then usage can employ the URLSession extensions:

Usage

URLSession.shared.endpointPublisher(in: .production, with: MyRequest())
    .sink { completion in
        guard case .failure(let error) = completion else { return }
        // handle error
    } receiveValue: { (response: MyRequest.Response) in
        // handle MyRequest.Response
    }
    .store(in: &cancellables)

To browse more complex examples, make sure to check out the Examples wiki page.