A type that can add authentication fields to a Header.

AuthenticationProvider is simply a wrapper around a function that modifies a header so it is authenticated.

A type that produces the body of a request and updates the header of a request accordingly.

A BodyProvider implements a function that takes an inout Header and produces a RequestBody. In the body(updating:) method, the provider should construct the RequestBody and update the Content-Type of the provided Header. The provider can also set any other relevant fields in the header.

Several predefined BodyProviders are provided for text bodies and JSON bodies.

Creating a BodyProvider

The body(updating:) method is defined when the BodyProvider is initialised as a closure. The method is somewhat odd because it doesn’t take any data to convert to a RequestBody as input. In your BodyProviders you should capture the input data in the closure provided at initialization. This means that most BodyProviders will be provided by factory functions that take the input data and construct a new body provider using it.

When implementing a provider, ensure that updates to the provided header are only applied when any throwing functions have succeeded. Otherwise you may end up in the situation where the header of a request is updated but its body has not been created because an error was thrown during creation.

A String wrapper that implements case insensitive comparison, sorting and hashing methods.

A header field in a HTTP request. A field consists of a key-value pair mapping name onto value.

A method (AKA verb) to be sent in a HTTP request. The standard (HTTP/1.1) headers are implemented as static properties. New methods can be added in an extension on the HTTPMethod type.

Pattern Matching

HTTPMethod provides an overload of the ~= operator so methods can easily be pattern matched on in a switch statement.

A header in a HTTP request. A header consists of a series of fields containing a key and a value. Keys are represented by the Field.Name type while values are simply Strings.

A media type (MIME type) used to identify content.

Media types consist of a top level type a subtype and zero or more parameters (key-value pairs). The implementation in Requests is based on RFC 2045 and RFC 6838. The key take-aways from these RFCs are:

1. The type and subtype of a media type are case-insensitive.
2. The key of a parameter is case-insensitive but the value is case-sensitive.
3. The parameters of a media type do not effect its value.

The implications of these for MediaType are:

1. The implementations of Equatable and Hashable are case-insensitive.
2. Ditto for the parameters of a MediaType.
3. The parameters of a MediaType are not used in the Equatable and Hashable implementation of MediaType.

Defining New Media Types

Several common media types are defined as static properties on MediaType. You can add new types in an extension of MediaType. Define the new subtype in an extension of MediaType.SubType and the new media type in an extension of MediaType

For media types with required parameters (e.g., multipart/form-data), define the media type as a static function of its required parameters. For example, MediaType.formData is defined as:

static let formData: (String) -> MediaType = { boundary in
    MediaType(type: .multipart, subtype: .formData, parameters: ["boundary": boundary])
}

which will produce a new MediaType with the boundary parameter set to the provided String.

A RequestProviding type to a single API host.

Use an AnonymousRequestProvider for one-off API requests or when you do not care about the API parameter of the Request type.

A request for a resource from an API.

Overview

The Request structure is a concrete implementation of a RequestConvertible that provides a chainable builder-like interface to constructing requests. You rarely instantiate a Request directly. Instead, requests to a specific API are created by a RequestProviding type and are customised using the builder functions on Request.

The Request structure is generic over the API type and the Resource type. The API parameter is immutable and can be used to constrain extensions on Request to a specific API. The Resource parameter is mutable in the sense that it can be changed using the receiving(_:) builder function.

One-off Requests

A convenience initializer init(method:baseURL:endpoint:) is provided for one-off requests. This uses an AnonymousRequestProvider and is intended to be used for exploratory work with an API. Its use outside of this context is strongly discouraged.

Indicates a valid URL could not be constructed from a RequestConvertible type.

An error that wraps an error that occurred when executing a network request.

A type that can decode a response type from the raw body of a HTTP response.