Requests

Requests is a Swift library focused on providing sugar for building and organising your application’s HTTP requests.

Requests is not concerned with performing network requests. You can use whatever you want to perform the requests. Requests simply provides some types that make building requests and keeping them organised more enjoyable.

⚠️ Requests is under active development and there are some areas of the API that will change. Until Requests reaches version 1.0, any non patch 0.x release can be API breaking.

---

Usage Guide

Core Types

Requests contains a few types that form the core of the library as well as many helper types. Complete reference documentation for all types can be found here.

The core types are:

• The RequestConvertible protocol — Conforming types declare the properties of a HTTP request and can be converted into Foundation URLRequest instances.
• The Request structure — A concrete implementation of the RequestConvertible protocol that provides a fluent interface for declaring API requests.
• The RequestProviding protocol — Conforming types declare the base URL of an API and can initialise base Request instances for a specific API.
• The ResponseDecoder structure — A type wrapping a function that decodes a type from a HTTP response.
• The BodyProvider structure — A type wrapping a function that encodes the body of a RequestConvertible type.

If you need to get started with Requests quickly, you should investigate the Request and RequestProviding types.

Installation

Requests supports installation using CocoaPods, Carthage or the Swift Package Manager. Requests supports macOS, iOS, tvOS and watchOS. Linux is not supported but may work.

⚠️ While Requests is in the 0.x release phase, use your package manager’s pessimistic operator to pin the version number to a minor release.

CocoaPods

Add the following to your Podfile:

pod "Requests", "~> 0.3.0"

Carthage

Add the following to your Cartfile:

github "alexjohnj/Requests" ~> 0.3.0

Swift Package Manager

Add the following to your Package.swift file’s dependencies:

dependencies: [
    .package(url: "https://github.com/alexjohnj/Requests.git", .upToNextMinor(from: "0.3.0"))
]

Create a Request Provider for an API

For each API in your application, create a type that conforms to the RequestProviding protocol. These types provide the base URL for an API:

enum ExampleAPI: RequestProviding {
    case development
    case production

    var baseURL: URL {
        switch self {
        case .development:
            return URL("https://dev.example.com/api")
        case .production:
            return URL("https://live.example.com/api")
        }
    }
}

let api = ExampleAPI.development

RequestProviding types form the entry point to building a Request for an API. A RequestProviding type has several methods that construct a base Request to an API.

GET a Resource

To build a request to retrieve a JSON encoded resource modelled as a Decodable structure, use the get(_:from:) method on a request provider:

struct User: Codable { }

let getUserRequest = api.get(.json(encoded: User.self), from: "/user/1/")

URLSession.shared.perform(getUserRequest) { result in
    switch result {
    case .success(let urlResponse, let user):
        // Do something with the user
        break

    case .failed(let response?, let error):
        // We got a HTTP response but also an error. Something probably went wrong decoding the JSON.
        break

    case .failed(nil, let error):
        // We didn't get a response. There was probably a network error.
        break
    }
}

This method constructs a GET request to https://dev.example.com/api/user/1 and configures it with a ResponseDecoder that tries to decode a User struct from the response’s body. The returned request is generic over its response’s body’s type (called the Resource to distinguish it from a HTTPURLResponse).

The perform(_:) method on URLSession performs a request and evaluates the ResponseDecoder with the response’s body. It then passes the decoded Resource to the completion block alongside a HTTPURLResponse if everything succeeds. Otherwise the block receives an Error and possibly a HTTPURLResponse.

POST Some Data

Sending data looks similar to retrieving a resource. To build a request that posts a JSON encoded User struct, use the post(_:to:) method on an API’s request provider:

let user = User()
let createUserRequest = api.post(.json(encoded: user), to: "/user/")
URLSession.shared.perform(createUserRequest) { result in
    // Handle the result
}

This method creates a POST request configured with a BodyProvider that encodes the user struct as JSON. The Resource type of the request is Void meaning the request’s response doesn’t have a body or the request doesn’t care about the body. Note that the BodyProvider will take care of updating the request’s headers to indicate the type of content it contains.

Authenticating a Request

Requests has basic support for authenticating requests. If a request can be authenticated using its header, use an AuthenticationProvider to update the header with the required credentials:

let authToken = "DEADBEEF-DEADBEEF-DEADBEEF"
let updateUserRequest = api.patch("/user/1", with: .json(encoded: user))
    .authenticated(with: .bearerToken(authToken))

URLSession.shared.perform(updateUserRequest) { _ in }

This builds a PATCH request that will include a bearer token in the header. Requests includes built in support for attaching:

• Bearer token headers
• HTTP Basic Auth headers

You can add additional header based authentication schemes by writing a new AuthenticationProvider.

Customising Headers

The Request type has several functions for setting the headers of a request. The Header type models a request’s header, consisting of multiple Fields. Fields consist of a name and a value.

To set the header of a request, use the with(header:) method:

let getBioRequest = api.get(.text, from: "/user/1/bio")
    .with(header: [
        .acceptLanguage("en-scouse"),
        .accept(.plainText)
        ])

This constructs a new Header from an array of Fields and replaces the request’s header with it.

To add a header to a request or replace a single field in a request’s header, use one of adding(headerField:), adding(headerFields:) or setting(headerField:).

⚠️ A request’s BodyProvider and AuthenticationProvider can both modify the fields of a request’s header. Any changes made by them will override the fields you specify when building the request.

Customising Query Parameters

Similar to headers, the Request type provides several functions that set the query parameters of a request:

let searchRequest = api.get(.text, from: "/users/search")
    .with(query: [
        "query": "alex",
        "limit": "30",
        ])

This produces a request to the URL https://dev.example.com/api/users/search?query=alex&limit=30. Note that Requests uses the Foundation URLQueryItem to represent query items but provides several extensions that makes building them neater.

Defining Custom Header Fields

Requests includes several predefined fields for common HTTP headers. You can easily add new ones by adding a static property on the Field and Field.Name types:

extension Field.Name {
    static let applicationKey = Field.Name("X-APPLICATION-KEY")
}

extension Field {
    static let applicationKey: (String) -> Field = { Field(name: .applicationKey, value: $0) }
}

Defining a Base Request for an API

Some APIs require common properties set on all API requests. For example, an API might require an application key in the header of each request. You can achieve this by implementing an optional method in a RequestProviding conforming type.

The request(to:using:) method is the core method of the RequestProviding protocol. It returns a new Request for an API and is the starting point for all other request building methods on RequestProviding.

A custom implementation of request(to:using:) can return a Request with a default set of values applied:

struct ExternalAPI: RequestProviding {
    let baseURL: URL = URL("https://api.external.org")

    func request(to endpoint: String, using method: HTTPMethod) -> Request<ExternalAPI, Void> {
        return Request(api: self, endpoint: endpoint, responseDecoder: .none, method: method)
            .adding(headerField: .applicationKey("DEAD-BEEF"))
    }
}

Now, any Request built from ExternalAPI will include the application key header field.

Writing a New Response Decoder

Requests ships with a couple of built in ResponseDecoders for JSON and text data. It’s possible to define a new ResponseDecoder if needed.

A ResponseDecoder is a structure generic over its Response that wraps a throwing function taking a HTTPURLResponse and some Data and producing a Response:

public struct ResponseDecoder<Response> {

    public init(_ decode: @escaping (HTTPURLResponse, Data) throws -> Response)

    ...
}

When adding a new response decoder, declare a static property or function in an extension of the ResponseDecoder type that returns a new ResponseDecoder. This provides unqualified access to a decoder when used with the Request building methods and goes a long way towards making request definitions readable.

As an example, the definition of .text(encoding:) response decoder is a static function on the ResponseDecoder<String> type:

extension ResponseDecoder where Response == String {

    public static let text = ResponseDecoder<String>.text(encoding: .utf8)

    public static func text(encoding: String.Encoding) -> ResponseDecoder<String> {
        return ResponseDecoder { _, data in
            guard let string = String(data: data, encoding: encoding) else {
                throw CocoaError(.fileReadInapplicableStringEncoding,
                                 userInfo: [NSStringEncodingErrorKey: encoding.rawValue])
            }

            return string
        }
    }
}

Using this, the call site for the response decoder looks incredibly neat:

let getBookRequest = api.get(.text(encoding: .ascii), from: "/book/1/contents")

// Or for UTF-8
let getOtherBookRequest = api.get(.text, from: "/book/2/contents")

This approach is a bit unconventional for Swift—a protocol would generally be the more Swifty solution. However, the goal here was to optimise for readability at the call site rather than in the implementation of the protocol. As you’ll be consuming request providers more often than you’ll be writing them (especially as Requests adds more built-ins), I believe this is a worthwhile trade-off.

Writing a New Authentication Provider

Like the ResponseDecoder type, an AuthenticationProvider is a struct wrapping a function. An authentication provider wraps a function that mutates an inout Header:

public struct AuthenticationProvider {

    public init(authenticate: @escaping (inout Header) -> Void)

    ...
}

Again, declare AuthenticationProviders as static properties or functions on the AuthenticationProvider type so that they read nicely with the Request type’s methods:

extension AuthenticationProvider {

    static let custom: (String) -> AuthenticationProvider = { customToken in
        AuthenticationProvider { header in
            header[.authorization] = "Custom \(customToken)"
        }
    }

}

Writing a New Body Provider

No surprises with this one. BodyProviders work the same way as AuthenticationProviders and ResponseDecoders. A body provider is a struct that wraps a throwing function that takes an inout Header and returns a RequestBody:

public struct BodyProvider {

    public init(encode: @escaping (inout Header) throws -> RequestBody)

    ...
}

In the body of the BodyProvider you should encode some data, update the ContentType of the Header and then return the body. Note that the returned RequestBody can wrap either raw Data or an InputStream.

Declare new body providers in static functions in an extension of BodyProvider:

extension BodyProvider {
    static func text(_ text: String) -> BodyProvider {
        return BodyProvider { header in
            guard let data = text.data(using: .utf8) else {
                throw TextBodyEncodingError.utf8EncodingFailed
            }

            header.set(.contentType(.plainText))
            return .data(data)
        }
    }
}

⚠️ Only update the header of a request after calling any throwing functions.

Advanced Usage

The RequestConvertible Protocol

The RequestConvertible protocol is really the core of Requests. Indeed, for a long time it was all there was to Requests. Everything else was built around the type to simplify its usage.

RequestConvertible types declare all the information needed to convert a request to a Foundation URLRequest. An extension method on the protocol (toURLRequest()) handles the actual conversion of conforming types. If you’re building any functions that operate on requests, you should consider constraining them to RequestConvertible conforming types instead of the Request type itself for maximum flexibility.

Most of the properties of the Request type map directly to a requirement in the RequestConvertible protocol. The only difference between Request and RequestConvertible is the absence of an associated API type in the protocol. RequestConvertible lacks this type because of the different usage model organising requests with it opens up.

With the RequestConvertible protocol, you can organise you application’s HTTP requests using protocol inheritance and composition. Each request in your application is a RequestConvertible type. Common properties for an API can be declared in a protocol that inherits from the base RequestConvertible protocol. This eliminates the need for an associated API type.

This organisation system has pros and cons. Some of the pros are:

• Ease of discoverability — Each API request is its own type (generally in its own file) and so can easily be searched for in a project.
• Easy definition of ad-hoc Resource types — You can satisfy the protocol’s Resource associated type requirement using a type nested inside the request definition. This is handy for one-off responses and keeps the model of the request and its associated resource in close proximity.

Some of its cons:

• Boilerplate — This approach leads to lots of boilerplate. Each API request needs a new type, a new file (normally) and then a protocol hiding the actual construction and execution of the network request.
• Protocol composition is not as composable as function composition — If you try and compose two RequestConvertible child protocols that both have default implementations of the same property, you will lose the default implementation. You will need knowledge of the default implementations of both the protocols you’re composing to implement the conforming type’s properties correctly.

Performing a Request

As has already been mentioned, Requests is not concerned with performing network requests, only constructing them. Saying that, Requests does come with a supported extension on URLSession to perform requests. This is there to help people get up and running with Requests but it is by no means meant to define how Requests should be used.

If you’re integrating Requests with another networking system, keep the following in mind:

• Constrain your functions to operate on RequestConvertible types, not Request.
• A Void resource type indicates the request either doesn’t expect or doesn’t care about the response’s body. Your functions should respect this and not treat a nil response body as an error for Void requests.
• ResponseDecoders only operate on HTTP responses. Your functions should treat non HTTPURLResponse instances as an error.
• Converting a RequestConvertible type to a URLRequest can fail.

License

Requests is released under the MIT license.