URLEncoding

public struct URLEncoding : ParameterEncoding

Creates a url-encoded query string to be set as or appended to any existing URL query string or set as the HTTP body of the URL request. Whether the query string is set or appended to any existing URL query string or set as the HTTP body depends on the destination of the encoding.

The Content-Type HTTP header field of an encoded request with HTTP body is set to application/x-www-form-urlencoded; charset=utf-8.

There is no published specification for how to encode collection types. By default the convention of appending [] to the key for array values (foo[]=1&foo[]=2), and appending the key surrounded by square brackets for nested dictionary values (foo[bar]=baz) is used. Optionally, ArrayEncoding can be used to omit the square brackets appended to array keys.

BoolEncoding can be used to configure how boolean values are encoded. The default behavior is to encode true as 1 and false as 0.

Helper Types

  • Defines whether the url-encoded query string is applied to the existing query string or HTTP body of the resulting URL request.

    • methodDependent: Applies encoded query string result to existing query string for GET, HEAD and DELETE requests and sets as the HTTP body for requests with any other HTTP method.
    • queryString: Sets or appends encoded query string result to existing query string.
    • httpBody: Sets encoded query string result as the HTTP body of the URL request.
    See more

    Declaration

    Swift

    public enum Destination

  • Configures how Array parameters are encoded.

    • brackets: An empty set of square brackets is appended to the key for every value. This is the default behavior.
    • noBrackets: No brackets are appended. The key is encoded as is.
    See more

    Declaration

    Swift

    public enum ArrayEncoding

  • Configures how Bool parameters are encoded.

    • numeric: Encode true as 1 and false as 0. This is the default behavior.
    • literal: Encode true and false as string literals.
    See more

    Declaration

    Swift

    public enum BoolEncoding

Properties

  • Returns a default URLEncoding instance.

    Declaration

    Swift

    public static var `default`: URLEncoding { get }

  • Returns a URLEncoding instance with a .methodDependent destination.

    Declaration

    Swift

    public static var methodDependent: URLEncoding { get }

  • Returns a URLEncoding instance with a .queryString destination.

    Declaration

    Swift

    public static var queryString: URLEncoding { get }

  • Returns a URLEncoding instance with an .httpBody destination.

    Declaration

    Swift

    public static var httpBody: URLEncoding { get }

  • The destination defining where the encoded query string is to be applied to the URL request.

    Declaration

    Swift

    public let destination: Destination

  • The encoding to use for Array parameters.

    Declaration

    Swift

    public let arrayEncoding: ArrayEncoding

  • The encoding to use for Bool parameters.

    Declaration

    Swift

    public let boolEncoding: BoolEncoding

Initialization

  • Creates a URLEncoding instance using the specified destination.

    Declaration

    Swift

    public init(destination: Destination = .methodDependent, arrayEncoding: ArrayEncoding = .brackets, boolEncoding: BoolEncoding = .numeric)

    Parameters

    destination

    The destination defining where the encoded query string is to be applied.
    arrayEncoding

    The encoding to use for Array parameters.
    boolEncoding

    The encoding to use for Bool parameters.

    Return Value

    The new URLEncoding instance.

Encoding

  • Creates a URL request by encoding parameters and applying them onto an existing request.

    Throws

    An Error if the encoding process encounters an error.

    Declaration

    Swift

    public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest

    Parameters

    urlRequest

    The request to have parameters applied.
    parameters

    The parameters to apply.

    Return Value

    The encoded request.

  • Creates percent-escaped, URL encoded query string components from the given key-value pair using recursion.

    Declaration

    Swift

    public func queryComponents(fromKey key: String, value: Any) -> [(String, String)]

    Parameters

    key

    The key of the query component.
    value

    The value of the query component.

    Return Value

    The percent-escaped, URL encoded query string components.

  • Returns a percent-escaped string following RFC 3986 for a query string key or value.

    RFC 3986 states that the following characters are “reserved” characters.

    • General Delimiters: “:”, “#”, “[”, “]”, “@”, “?”, “/”
    • Sub-Delimiters: “!”, “$”, “&”, “‘”, “(”, “)”, “*”, “+”, “,”, “;”, “=”

    In RFC 3986 - Section 3.4, it states that the “?” and “/” characters should not be escaped to allow query strings to include a URL. Therefore, all “reserved” characters with the exception of “?” and “/” should be percent-escaped in the query string.

    Declaration

    Swift

    public func escape(_ string: String) -> String

    Parameters

    string

    The string to be percent-escaped.

    Return Value

    The percent-escaped string.