JSONTransaction

open class JSONTransaction<JSONIntermediateType, ResponseDataType>: HTTPTransaction<ResponseDataType>

Connects to a network service to retrieve a JSON document of the generic type JSONIntermediateType. The JSONPayloadProcessor then attempts to convert the JSON intermediate type into the final ResponseDataType.

  • The JSONEnvelopeUnwrapper that will be used to remove the JSON payload from any JSON envelope it may be wrapped in. The default implementation assumes there is no envelope, and simply returns the passed-in JSON object.

    Declaration

    Swift

    public var unwrapJSON: JSONEnvelopeUnwrapper = { _, jsonObject in

  • The signature of a JSON payload processing function. This function accepts a JSON object (of type JSONIntermediateType) and attempts to convert it to HTTPDataType.

    Declaration

    Swift

    public typealias JSONPayloadProcessor = (JSONTransaction<JSONIntermediateType, ResponseDataType>, JSONIntermediateType) throws -> ResponseDataType

  • The signature of a function to remove envelope wrapping from the JSON structure returned by the server. Certain JSON-based services embed the JSONIntermediateType payload inside envelope metadata about the transaction. In such cases, it is necessary to remove the envelope and return a JSONIntermediateType without it so the JSONPayloadProcessor can properly parse the JSON into the ResponseDataType.

    Declaration

    Swift

    public typealias JSONEnvelopeUnwrapper = (JSONTransaction<JSONIntermediateType, ResponseDataType>, JSONIntermediateType) throws -> JSONIntermediateType

  • The JSONPayloadProcessor that will be used to convert a JSON object (of type Any) to the DataType of the transaction. The default implementation calls extractPayloadFromParsedJSON(), which simply performs a typecast. If that is insufficient, you may either replace the function stored in processJSON or subclass to provide an alternate implementation of extractPayloadFromParsedJSON().

    Declaration

    Swift

    public var processJSON: JSONPayloadProcessor = { txn, jsonObject in

  • Initializes a JSONTransaction to connect to the network service at the given URL.

    Declaration

    Swift

    public init(url: URL, method: HTTPRequestMethod? = nil, upload data: Data? = nil, contentType: MIMEType? = nil, processingQueue queue: DispatchQueue = .transactionProcessing)

    Parameters

    url

    The URL to use for conducting the transaction.
    method

    The HTTP request method. When not explicitly set, defaults to .get unless data is non-nil, in which case the value defaults to .post.
    data

    Optional binary data to send to the network service.
    contentType

    The MIME type of data. If present, this value is sent as the Content-Type header for the HTTP request.
    queue

    A DispatchQueue to use for processing transaction responses.

  • The payload processing function used by default for JSONTransaction instances.

    This function extracts a JSON object from binary Data using the jsonObject(from:) function and—if successful—attempts to convert the result to type DataType using the JSONPayloadProcessor.

    Throws

    If content could not be interpreted into a JSON object, or if that JSON object could not be interpreted as an instance of type DataType.

    Declaration

    Swift

    open func extractPayloadFromData(transaction: HTTPTransaction<ResponseDataType>, content: Data, meta: HTTPResponseMetadata)
        throws
        -> ResponseDataType

    Parameters

    transaction

    The transaction for which the function is executing. Under normal circumstances, this is the same as self.
    content

    The content (body) of the HTTP response.
    meta

    The response metadata.

    Return Value

    The payload, an instance of DataType.

  • Attempts to convert the content of an HTTP response into a JSON object.

    This implementation calls JSONSerialization.jsonObject() with no options. Subclasses may override to provide different behavior.

    Throws

    If content could not be interpreted into a JSON object.

    Declaration

    Swift

    open func jsonObject(from content: Data)
        throws
        -> Any

    Parameters

    content

    The content (body) of the HTTP response.

    Return Value

    The JSON object.

  • Attempts to interpret a JSON object as an instance of ResponseDataType.

    The default implementation simply attempts to cast jsonObject as type DataType. This is sufficient if you’re expecting a JSONDictionary or a JSONArray. In other cases, subclassing or replacing the JSONPayloadProcessor function in the processJSON property is necessary.

    Throws

    If jsonObject could not be interpreted as an instance of type DataType.

    Declaration

    Swift

    open func extractPayloadFromParsedJSON(_ jsonObject: JSONIntermediateType)
        throws
        -> ResponseDataType

    Parameters

    jsonObject

    The JSON object.

    Return Value

    An instance DataType, representing the value extracted from the jsonObject.