HTTPClient

public class HTTPClient

HTTPClient class provides API for request execution.

Example:

    let client = HTTPClient(eventLoopGroupProvider: .createNew)
    client.get(url: "https://swift.org", deadline: .now() + .seconds(1)).whenComplete { result in
        switch result {
        case .failure(let error):
            // process error
        case .success(let response):
            if let response.status == .ok {
                // handle response
            } else {
                // handle remote error
            }
        }
    }

It is important to close the client instance, for example in a defer statement, after use to cleanly shutdown the underlying NIO EventLoopGroup:

    try client.syncShutdown()

Show on

eventLoopGroup
Undocumented
Declaration
Swift
public let eventLoopGroup: EventLoopGroup
Show on
init(eventLoopGroupProvider:configuration:)
Create an HTTPClient with specified EventLoopGroup provider and configuration.
Declaration
Swift
public convenience init(eventLoopGroupProvider: EventLoopGroupProvider, configuration: Configuration = Configuration())
Parameters
eventLoopGroupProvider
Specify how EventLoopGroup will be created.
configuration
Client configuration.
Show on
init(eventLoopGroupProvider:configuration:backgroundActivityLogger:)
Create an HTTPClient with specified EventLoopGroup provider and configuration.
Declaration
Swift
public required init(eventLoopGroupProvider: EventLoopGroupProvider, configuration: Configuration = Configuration(), backgroundActivityLogger: Logger)
Parameters
eventLoopGroupProvider
Specify how EventLoopGroup will be created.
configuration
Client configuration.
Show on
syncShutdown()
Shuts down the client and EventLoopGroup if it was created by the client.
Declaration
Swift
public func syncShutdown() throws
Show on
shutdown(queue:_:)
Shuts down the client and event loop gracefully. This function is clearly an outlier in that it uses a completion callback instead of an EventLoopFuture. The reason for that is that NIO’s EventLoopFutures will call back on an event loop. The virtue of this function is to shut the event loop down. To work around that we call back on a DisQueue instead.
Declaration
Swift
public func shutdown(queue: DisQueue = .global(), _ callback: @escaping (Error?) -> Void)
Show on
get(url:deadline:)
Execute GET request using specified URL.
Declaration
Swift
public func get(url: String, deadline: NIODeadline? = nil) -> EventLoopFuture<Response>
Parameters
url
Remote URL.
deadline
Point in time by which the request must complete.
Show on
get(url:deadline:logger:)
Execute GET request using specified URL.
Declaration
Swift
public func get(url: String, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response>
Parameters
url
Remote URL.
deadline
Point in time by which the request must complete.
logger
The logger to use for this request.
Show on
post(url:body:deadline:)
Execute POST request using specified URL.
Declaration
Swift
public func post(url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response>
Parameters
url
Remote URL.
body
Request body.
deadline
Point in time by which the request must complete.
Show on
post(url:body:deadline:logger:)
Execute POST request using specified URL.
Declaration
Swift
public func post(url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response>
Parameters
url
Remote URL.
body
Request body.
deadline
Point in time by which the request must complete.
logger
The logger to use for this request.
Show on
(url:body:deadline:)
Execute request using specified URL.
Declaration
Swift
public func (url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response>
Parameters
url
Remote URL.
body
Request body.
deadline
Point in time by which the request must complete.
Show on
(url:body:deadline:logger:)
Execute request using specified URL.
Declaration
Swift
public func (url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response>
Parameters
url
Remote URL.
body
Request body.
deadline
Point in time by which the request must complete.
logger
The logger to use for this request.
Show on
put(url:body:deadline:)
Execute PUT request using specified URL.
Declaration
Swift
public func put(url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response>
Parameters
url
Remote URL.
body
Request body.
deadline
Point in time by which the request must complete.
Show on
put(url:body:deadline:logger:)
Execute PUT request using specified URL.
Declaration
Swift
public func put(url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response>
Parameters
url
Remote URL.
body
Request body.
deadline
Point in time by which the request must complete.
logger
The logger to use for this request.
Show on
delete(url:deadline:)
Execute DELETE request using specified URL.
Declaration
Swift
public func delete(url: String, deadline: NIODeadline? = nil) -> EventLoopFuture<Response>
Parameters
url
Remote URL.
deadline
The time when the request must have been completed by.
Show on
delete(url:deadline:logger:)
Execute DELETE request using specified URL.
Declaration
Swift
public func delete(url: String, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response>
Parameters
url
Remote URL.
deadline
The time when the request must have been completed by.
logger
The logger to use for this request.
Show on
execute(_:url:body:deadline:logger:)
Execute arbitrary HTTP request using specified URL.
Declaration
Swift
public func execute(_ method: HTTPMethod = .GET, url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response>
Parameters
method
Request method.
url
Request url.
body
Request body.
deadline
Point in time by which the request must complete.
logger
The logger to use for this request.
Show on

execute(_:socketPath:urlPath:body:deadline:logger:)

Execute arbitrary HTTP+UNIX request to a unix domain socket path, using the specified URL as the request to send to the server.

Declaration

Swift

public func execute(_ method: HTTPMethod = .GET, socketPath: String, urlPath: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response>

Parameters

`method`	Request method.
`socketPath`	The path to the unix domain socket to connect to.
`urlPath`	The URL path and query that will be sent to the server.
`body`	Request body.
`deadline`	Point in time by which the request must complete.
`logger`	The logger to use for this request.

Show on

execute(_:secureSocketPath:urlPath:body:deadline:logger:)

Execute arbitrary HTTPS+UNIX request to a unix domain socket path over TLS, using the specified URL as the request to send to the server.

Declaration

Swift

public func execute(_ method: HTTPMethod = .GET, secureSocketPath: String, urlPath: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response>

Parameters

`method`	Request method.
`secureSocketPath`	The path to the unix domain socket to connect to.
`urlPath`	The URL path and query that will be sent to the server.
`body`	Request body.
`deadline`	Point in time by which the request must complete.
`logger`	The logger to use for this request.

Show on

execute(request:deadline:)
Execute arbitrary HTTP request using specified URL.
Declaration
Swift
public func execute(request: Request, deadline: NIODeadline? = nil) -> EventLoopFuture<Response>
Parameters
request
HTTP request to execute.
deadline
Point in time by which the request must complete.
Show on
execute(request:deadline:logger:)
Execute arbitrary HTTP request using specified URL.
Declaration
Swift
public func execute(request: Request, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response>
Parameters
request
HTTP request to execute.
deadline
Point in time by which the request must complete.
logger
The logger to use for this request.
Show on
execute(request:eventLoop:deadline:)
Execute arbitrary HTTP request using specified URL.
Declaration
Swift
public func execute(request: Request, eventLoop: EventLoopPreference, deadline: NIODeadline? = nil) -> EventLoopFuture<Response>
Parameters
request
HTTP request to execute.
eventLoop
NIO Event Loop preference.
deadline
Point in time by which the request must complete.
Show on
execute(request:eventLoop:deadline:logger:)
Execute arbitrary HTTP request and handle response processing using provided delegate.
Declaration
Swift
public func execute(request: Request, eventLoop eventLoopPreference: EventLoopPreference, deadline: NIODeadline? = nil, logger: Logger?) -> EventLoopFuture<Response>
Parameters
request
HTTP request to execute.
eventLoop
NIO Event Loop preference.
deadline
Point in time by which the request must complete.
logger
The logger to use for this request.
Show on

execute(request:delegate:deadline:)

Execute arbitrary HTTP request and handle response processing using provided delegate.

Declaration

Swift

public func execute<Delegate: HTTPClientResponseDelegate>(request: Request,
                                                          delegate: Delegate,
                                                          deadline: NIODeadline? = nil) -> Task<Delegate.Response>

Parameters

`request`	HTTP request to execute.
`delegate`	Delegate to process response parts.
`deadline`	Point in time by which the request must complete.

Show on

execute(request:delegate:deadline:logger:)

Execute arbitrary HTTP request and handle response processing using provided delegate.

Declaration

Swift

public func execute<Delegate: HTTPClientResponseDelegate>(request: Request,
                                                          delegate: Delegate,
                                                          deadline: NIODeadline? = nil,
                                                          logger: Logger) -> Task<Delegate.Response>

Parameters

`request`	HTTP request to execute.
`delegate`	Delegate to process response parts.
`deadline`	Point in time by which the request must complete.
`logger`	The logger to use for this request.

Show on

execute(request:delegate:eventLoop:deadline:)

Execute arbitrary HTTP request and handle response processing using provided delegate.

Declaration

Swift

public func execute<Delegate: HTTPClientResponseDelegate>(request: Request,
                                                          delegate: Delegate,
                                                          eventLoop eventLoopPreference: EventLoopPreference,
                                                          deadline: NIODeadline? = nil) -> Task<Delegate.Response>

Parameters

`request`	HTTP request to execute.
`delegate`	Delegate to process response parts.
`eventLoop`	NIO Event Loop preference.
`deadline`	Point in time by which the request must complete.
`logger`	The logger to use for this request.

Show on

execute(request:delegate:eventLoop:deadline:logger:)

Execute arbitrary HTTP request and handle response processing using provided delegate.

Declaration

Swift

public func execute<Delegate: HTTPClientResponseDelegate>(request: Request,
                                                          delegate: Delegate,
                                                          eventLoop eventLoopPreference: EventLoopPreference,
                                                          deadline: NIODeadline? = nil,
                                                          logger originalLogger: Logger?) -> Task<Delegate.Response>

Parameters

`request`	HTTP request to execute.
`delegate`	Delegate to process response parts.
`eventLoop`	NIO Event Loop preference.
`deadline`	Point in time by which the request must complete.

Show on

Configuration
HTTPClient configuration.
See more
Declaration
Swift
public struct Configuration
Show on
EventLoopGroupProvider
Specifies how EventLoopGroup will be created and establishes lifecycle ownership.
See more
Declaration
Swift
public enum EventLoopGroupProvider
Show on
EventLoopPreference
Specifies how the library will treat event loop passed by the user.
See more
Declaration
Swift
public struct EventLoopPreference
extension HTTPClient.EventLoopPreference: CustomStringConvertible
Show on
Decompression
Specifies decompression settings.
See more
Declaration
Swift
public enum Decompression
Show on
Cookie
A representation of an HTTP cookie.
See more
Declaration
Swift
public struct Cookie
Show on
Response
Represent HTTP response.
See more
Declaration
Swift
public struct Response
Show on
Body
Represent request body.
See more
Declaration
Swift
public struct Body
Show on
Request
Represent HTTP request.
See more
Declaration
Swift
public struct Request
Show on
Authorization
HTTP authentication
See more
Declaration
Swift
public struct Authorization : Hashable
Show on
Task
Response execution context. Will be created by the library and could be used for obtaining EventLoopFuture<Response> of the execution or cancellation of the execution.
See more
Declaration
Swift
public final class Task<Response>
Show on
NWPOSIXError
See more
NWTLSError
See more

`eventLoopGroupProvider`	Specify how `EventLoopGroup` will be created.
`configuration`	Client configuration.

`url`	Remote URL.
`deadline`	Point in time by which the request must complete.