RestRequest

public class RestRequest

Object containing everything needed to build and execute HTTP requests.

  • The currently configured CircuitBreaker instance for this RestRequest. In order to create a CircuitBreaker you should set the circuitParameters property.

    Declaration

    Swift

    internal(set) public var circuitBreaker: CircuitBreaker<(HTTPClient.Request, (Result<HTTPClient.Response, RestError>) -> Void), String>? { get }

  • Parameters for a CircuitBreaker instance. When these parameters are set, a new circuitBreaker instance is created.

    Usage Example:

    let circuitParameters = CircuitParameters(timeout: 2000,
                                          maxFailures: 2,
                                          fallback: breakFallback)

let request = RestRequest(method: .GET, url: "http://myApiCall/hello")
request.circuitParameters = circuitParameters

    Declaration

    Swift

    public var circuitParameters: CircuitParameters<String>? { get set }

HTTP Request Parameters

  • The HTTP method specified in the request, defaults to GET.

    Usage Example:

    request.method = .PUT

    Declaration

    Swift

    public var method: HTTPMethod { get set }

  • The HTTP authentication credentials for the request.

    Usage Example:

    The example below uses an API key to specify the authentication credentials. You can also use .bearerAuthentication and pass in a base64 encoded String as the token, or .basicAuthentication where the username and password values to authenticate with are passed in.

    let request = RestRequest(url: "http://localhost:8080")
request.credentials = .basicAuthentication(username: "Hello", password: "World")

    Declaration

    Swift

    public var credentials: Credentials? { get set }

  • The HTTP header fields which form the header section of the request message.

    The header fields set using this parameter will be added to the existing headers.

    Usage Example:

    request.headerParameters = ["Cookie": "v1"]

    Declaration

    Swift

    public var headerParameters: [String : String] { get set }

  • The HTTP Accept header, i.e. the media type that is acceptable for the response, it defaults to “application/json”.

    Usage Example:

    request.acceptType = "text/html"

    Declaration

    Swift

    public var acceptType: String? { get set }

  • HTTP Content-Type header, i.e. the media type of the body of the request, it defaults to “application/json”.

    Usage Example:

    request.contentType = "application/x-www-form-urlencoded"

    Declaration

    Swift

    public var contentType: String? { get set }

  • HTTP User-Agent header, i.e. the user agent string of the software that is acting on behalf of the user. If you pass in <productName>/<productVersion> the value will be set to <productName>/<productVersion> <operatingSystem>/<operatingSystemVersion>.

    Usage Example:

    request.productInfo = "swiftyrequest-sdk/2.0.4"

    Declaration

    Swift

    public var productInfo: String? { get set }

  • The HTTP message body, i.e. the body of the request.

    Usage Example:

    request.messageBody = data
``

    Declaration

    Swift

    public var messageBody: Data? { get set }

  • The HTTP message body, i.e. the body of the request, as a JSON dictionary.

    Usage Example:

    let dict: [String:Any] = ["key": "value"]
request.messageBodyDictionary = dict
``

    Declaration

    Swift

    public var messageBodyDictionary: [String : Any]? { get set }

  • The HTTP message body, i.e. the body of the request, as a JSON array.

    Usage Example:

    let json: [Any] = ["value1", "value2"]
request.messageBodyArray = json
``

    Declaration

    Swift

    public var messageBodyArray: [Any]? { get set }

  • The HTTP query items to specify in the request URL. If there are query items already specified in the request URL they will be replaced.

    Usage Example:

    request.queryItems = [
                       URLQueryItem(name: "flamingo", value: "pink"),
                       URLQueryItem(name: "seagull", value: "white")
                     ]

    Declaration

    Swift

    public var queryItems: [URLQueryItem]? { get set }

  • Undocumented

    Declaration

    Swift

    public convenience init(method: HTTPMethod = .get, url: String, containsSelfSignedCert: Bool? = false, clientCertificate: ClientCertificate? = nil, timeout: HTTPClient.Configuration.Timeout? = nil, eventLoopGroup: EventLoopGroup? = nil)

  • Initialize a RestRequest instance.

    Usage Example:

    let request = RestRequest(method: .GET, url: "http://myApiCall/hello")

    Declaration

    Swift

    public init(method: HTTPMethod = .get, url: String, insecure: Bool = false, clientCertificate: ClientCertificate? = nil, timeout: HTTPClient.Configuration.Timeout? = nil, eventLoopGroup: EventLoopGroup? = nil)

    Parameters

    method

    The method specified in the request, defaults to GET.
    url

    URL string to use for the network request.
    insecure

    Pass True to accept invalid or self-signed certificates.
    clientCertificate

    An optional ClientCertificate for client authentication.
    timeout

    An optional HTTPClient.Configuration.Timeout specifying how long to wait for connection or response from a remote service before timing out. Defaults to nil, which means no timeout.
    eventLoopGroup

    An optional EventLoopGroup that should be used for requests, instead of the default MultiThreadedEventLoopGroup shared between all RestRequest instances.

  • Convenience function to encode an Encodable type as the request body, using a default JSONEncoder.

    Throws

    If the value cannot be encoded.

    Declaration

    Swift

    public func setBodyObject<T>(_ obj: T) throws where T : Encodable

    Parameters

    obj

    The value to encode as JSON

Response methods

  • Request response method that either invokes CircuitBreaker or executes the HTTP request. Note: this is equivalent to responseVoid(templateParams:queryItems:completionHandler:).

    Declaration

    Swift

    public func response(templateParams: [String: String]? = nil,
                     queryItems: [URLQueryItem]? = nil,
                     completionHandler: @escaping (Result<HTTPClient.Response, RestError>) -> Void)

    Parameters

    templateParams

    URL templating parameters used for substituion if possible.
    queryItems

    Sets the query parameters for this RestRequest, overwriting any existing parameters. Defaults to nil, which means that this parameter will be ignored, and RestRequest.queryItems will be used instead. Note that if you wish to clear any existing query parameters, then you should set request.queryItems = nil before calling this function.
    completionHandler

    Callback used on completion of operation.

  • Request response method with the expected result of a Data object.

    Declaration

    Swift

    public func responseData(templateParams: [String: String]? = nil,
                         queryItems: [URLQueryItem]? = nil,
                         completionHandler: @escaping (Result<RestResponse<Data>, RestError>) -> Void)

    Parameters

    templateParams

    URL templating parameters used for substituion if possible.
    queryItems

    Sets the query parameters for this RestRequest, overwriting any existing parameters. Defaults to nil, which means that this parameter will be ignored, and RestRequest.queryItems will be used instead. Note that if you wish to clear any existing query parameters, then you should set request.queryItems = nil before calling this function.
    completionHandler

    Callback used on completion of operation.

  • Request response method with the expected result of the object T specified.

    Declaration

    Swift

    public func responseObject<T: Decodable>(templateParams: [String: String]? = nil,
                                         queryItems: [URLQueryItem]? = nil,
                                         completionHandler: @escaping (Result<RestResponse<T>, RestError>) -> Void)

    Parameters

    templateParams

    URL templating parameters used for substitution if possible.
    queryItems

    Sets the query parameters for this RestRequest, overwriting any existing parameters. Defaults to nil, which means that this parameter will be ignored, and RestRequest.queryItems will be used instead. Note that if you wish to clear any existing query parameters, then you should set request.queryItems = nil before calling this function.
    completionHandler

    Callback used on completion of operation.

  • Request response method with the expected result of an array of Any JSON.

    Declaration

    Swift

    public func responseArray(templateParams: [String: String]? = nil,
                          queryItems: [URLQueryItem]? = nil,
                          completionHandler: @escaping (Result<RestResponse<[Any]>, RestError>) -> Void)

    Parameters

    templateParams

    URL templating parameters used for substitution if possible.
    queryItems

    Sets the query parameters for this RestRequest, overwriting any existing parameters. Defaults to nil, which means that this parameter will be ignored, and RestRequest.queryItems will be used instead. Note that if you wish to clear any existing query parameters, then you should set request.queryItems = nil before calling this function.
    completionHandler

    Callback used on completion of operation.

  • Request response method with the expected result of a [String: Any] JSON dictionary.

    Declaration

    Swift

    public func responseDictionary(templateParams: [String: String]? = nil,
                          queryItems: [URLQueryItem]? = nil,
                          completionHandler: @escaping (Result<RestResponse<[String: Any]>, RestError>) -> Void)

    Parameters

    templateParams

    URL templating parameters used for substitution if possible.
    queryItems

    Sets the query parameters for this RestRequest, overwriting any existing parameters. Defaults to nil, which means that this parameter will be ignored, and RestRequest.queryItems will be used instead. Note that if you wish to clear any existing query parameters, then you should set request.queryItems = nil before calling this function.
    completionHandler

    Callback used on completion of operation.

  • Request response method with the expected result of a String.

    Declaration

    Swift

    public func responseString(templateParams: [String: String]? = nil,
                           queryItems: [URLQueryItem]? = nil,
                           completionHandler: @escaping (Result<RestResponse<String>, RestError>) -> Void)

    Parameters

    templateParams

    URL templating parameters used for substituion if possible.
    queryItems

    Sets the query parameters for this RestRequest, overwriting any existing parameters. Defaults to nil, which means that this parameter will be ignored, and RestRequest.queryItems will be used instead. Note that if you wish to clear any existing query parameters, then you should set request.queryItems = nil before calling this function.
    completionHandler

    Callback used on completion of operation.

  • Request response method to use when there is no expected result.

    Declaration

    Swift

    public func responseVoid(templateParams: [String: String]? = nil,
                         queryItems: [URLQueryItem]? = nil,
                         completionHandler: @escaping (Result<HTTPClient.Response, RestError>) -> Void)

    Parameters

    templateParams

    URL templating parameters used for substituion if possible.
    queryItems

    Sets the query parameters for this RestRequest, overwriting any existing parameters. Defaults to nil, which means that this parameter will be ignored, and RestRequest.queryItems will be used instead. Note that if you wish to clear any existing query parameters, then you should set request.queryItems = nil before calling this function.
    completionHandler

    Callback used on completion of operation.

  • Utility method to download a file from a remote origin.

    Declaration

    Swift

    public func download(to destination: URL, completionHandler: @escaping (Result<HTTPResponseHead, RestError>) -> Void)

    Parameters

    destination

    URL destination to save the file to.
    completionHandler

    Callback used on completion of the operation.