Request

public struct Request<API, Resource> : RequestConvertible where API : RequestProviding

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.

See also

RequestConvertible

See also

RequestProviding

Public Properties

api
Undocumented
Declaration
Swift

public let api: API
baseURL
Declaration
Swift

public var baseURL: URL { get }
endpoint
Declaration
Swift

public var endpoint: String
method
Declaration
Swift

public var method: HTTPMethod
header
Declaration
Swift

public var header: Header
queryItems
Declaration
Swift

public var queryItems: [URLQueryItem]


                    
                    
                    cachePolicy

Declaration

Swift

public var cachePolicy: URLRequest.CachePolicy


                    
                    
                    timeoutInterval

Declaration

Swift

public var timeoutInterval: TimeInterval

bodyProvider
Declaration
Swift

public var bodyProvider: BodyProvider


                    
                    
                    responseDecoder

Undocumented

Declaration

Swift

public var responseDecoder: ResponseDecoder<Resource>


                    
                    
                    authenticationProvider

Declaration

Swift

public var authenticationProvider: AuthenticationProvider

Initializers


                    
                    
                    init(api:endpoint:responseDecoder:method:header:queryItems:cachePolicy:timeoutInterval:bodyProvider:authenticationProvider:)

Initialises a new Request with the provided parameters. Default values for optional parameters are defined in the DefaultValue type.

See also

DefaultValue

See also

RequestConvertible

Declaration

Swift

public init(
  api: API,
  endpoint: String,
  responseDecoder: ResponseDecoder<Resource>,
  method: HTTPMethod = DefaultValue.method,
  header: Header = DefaultValue.header,
  queryItems: [URLQueryItem] = DefaultValue.queryItems,
  cachePolicy: URLRequest.CachePolicy = DefaultValue.cachePolicy,
  timeoutInterval: TimeInterval = DefaultValue.timeout,
  bodyProvider: BodyProvider = DefaultValue.bodyProvider,
  authenticationProvider: AuthenticationProvider = DefaultValue.authenticationProvider
)

Convenience Initializers


                    
                    
                    init(method:baseURL:endpoint:)

Initialises a new request using an AnonymousRequestProvider.

Warning

Use of this initializer outside of playgrounds and exploratory work is strongly discouraged.

Declaration

Swift

public init(method: HTTPMethod, baseURL: URL, endpoint: String = "")

Parameters

`method`	The HTTP method for the request.
`baseURL`	The base url of the request and the anonymous request provider.
`endpoint`	The endpoint of the request. Default `""`.

Method Manipulation


                    
                    
                    using(method:)

Changes the HTTP method used by a request.

Declaration

Swift

public func using(method: HTTPMethod) -> Request<API, Resource>

Parameters


                                method

The new method to use for the request.

Header Manipulation


                    
                    
                    with(header:)

Sets the header of the request to a new value.

See also

adding(headerField:) to preserve the current header.

See also

setting(headerField:) to preserve the current header.

Declaration

Swift

public func with(header newHeader: Header) -> Request<API, Resource>

Parameters


                                newHeader

The header to set for the request.


                    
                    
                    adding(headerField:)

Adds the provided field to the request’s header.

See also

setting(headerField:) to replace an existing field.

Declaration

Swift

public func adding(headerField: Field) -> Request<API, Resource>

Parameters


                                headerField

A field to add to the request.


                    
                    
                    adding(headerFields:)

Adds the provided fields to the request’s header.

Declaration

Swift

public func adding(headerFields: [Field]) -> Request<API, Resource>

Parameters


                                headerFields

The fields to add to the header of the request.


                    
                    
                    adding(headerFields:)

Undocumented

Declaration

Swift

public func adding(headerFields: Field...) -> Request<API, Resource>


                    
                    
                    setting(headerField:)

Sets the provided field in the request’s header.

See also

adding(headerField:) to merge an existing field.

Declaration

Swift

public func setting(headerField: Field) -> Request<API, Resource>

Parameters


                                headerField

A field to set in the request.

Query Manipulation


                    
                    
                    with(query:)

Sets the query for the request to a new value.

See also

adding(queryItem:) to update an existing query.

Declaration

Swift

public func with(query newQuery: [URLQueryItem]) -> Request<API, Resource>

Parameters


                                newQuery

Collection of query items to build the new query from.


                    
                    
                    adding(queryItem:)

Appends a new item to the query for the request.

See also

with(query:) to replace an existing query.

Declaration

Swift

public func adding(queryItem: URLQueryItem) -> Request<API, Resource>

Parameters


                                queryItem

The item to append.


                    
                    
                    adding(queryItems:)

Appends a collection of new query items to the request.

See also

with(query:) to replace an existing query.

Declaration

Swift

public func adding(queryItems newItems: [URLQueryItem]) -> Request<API, Resource>

Parameters


                                queryItems

The items to append.


                    
                    
                    adding(queryItems:)

Appends a collection of new query items to the request.

See also

with(query:) to replace an existing query.

Declaration

Swift

public func adding(queryItems: URLQueryItem...) -> Request<API, Resource>

Parameters


                                queryItems

The items to append.

Body Manipulation


                    
                    
                    sending(_:)

Sets the body provider of the request to body.

Declaration

Swift

public func sending(_ body: BodyProvider) -> Request<API, Resource>

Response Manipulation


                    
                    
                    receiving(_:)

Sets the response decoder of the request.

Declaration

Swift

public func receiving<NewResource>(_ resourceDecoder: ResponseDecoder<NewResource>) -> Request<API, NewResource>

Parameters


                                resourceDecoder

A decoder for the new request’s resource.

Request Configuration Manipulation


                    
                    
                    authenticated(with:)

Sets the authentication provider for the request.

Declaration

Swift

public func authenticated(with authenticator: AuthenticationProvider) -> Request<API, Resource>

Parameters


                                authenticator

An authentication provider for the request.


                    
                    
                    timeout(after:)

Sets the timeout interval for the request.

Declaration

Swift

public func timeout(after interval: TimeInterval) -> Request<API, Resource>

Parameters


                                interval

The new timeout interval for the request in seconds.