SKRequest

public class SKRequest

An abstract class that represents a request to the Spotify Web API.

An SKRequest object encapsulates the properties of an HTTP request, providing a convenient template for you to create, prepare, and send requests to the Web API. See the API Requests Guide for more details.

Supporting Types

  • The HTTP verbs used by the Spotify Web API.

    See the API Requests Guide for more details.

    See more

    Declaration

    Swift

    public enum HTTPMethod : String

  • The MIME content types available for sending multipart requests to the Spotify Web API.

    Note

    The only content types currently accepted by the Spotify Web API are application/json and image/jpeg for all PUT, POST, or DELETE requests. If/when more content types become part of the API, they will be made available here.
    See more

    Declaration

    Swift

    public enum ContentType : String

Request Properties

  • The HTTP method used for this request.

    Declaration

    Swift

    public let method: HTTPMethod
  • url

    The destination URL for this request.

    Declaration

    Swift

    public let url: URL

  • The parameters for this request, if any. If no parameters are supplied, this will be an empty dictionary.

    Declaration

    Swift

    public let parameters: [String : Any]

  • The URL session used to perform the request.

    Set this property if you wish to provide a custom URL session object with which to perform the underlying network request. The default value is a URL session instance with the default configuration.

    Important

    Unless this property references the shared URL session singleton, the session will be invalidated upon deinitialization of the SKRequest instance.

    Declaration

    Swift

    public lazy var urlSession: URLSession { get set }

  • The authenticated Spotify API session used to authorize the request.

    Setting this property with your active SPTSession instance ensures your API request is accompanied by the appropriate OAuth access token.

    The default value is the current session object referenced by the SPTAuth class’s default instance.

    Declaration

    Swift

    public weak var apiSession: SPTSession?

  • The authorized URL request.

    Important

    Set the API session property beforehand to ensure this request is accompanied by the appropriate OAuth access token.

    Complexity

    O(n), where n is the number of elements in parameters.

    Declaration

    Swift

    public var preparedURLRequest: URLRequest { get }

Creating Requests

  • Creates a new request with the specified properties.

    If the URL provided does not contain either the Web API base URL (https://api.spotify.com), or the Web API accounts service URL (https://accounts.spotify.com), this initializer will fail.

    Note

    If the URL provided already contains a query string, those query items will be removed from the stored url property and made available through the parameters property instead. When both a parameters argument and a URL with existing query items are supplied, both are stored in the parameters property. Values supplied by the parameters argument will overwrite any conflicting values supplied by the URL query.

    Declaration

    Swift

    public init?(method: HTTPMethod, url: URL, parameters: [String: Any] = [:])

    Parameters

    method

    The HTTP verb to use for this API request. For possible values, see SKRequest.HTTPMethod.
    url

    The full destination URL for this API request, comprised of either the Web API base URL (https://api.spotify.com) or the accounts service URL (https://accounts.spotify.com) and the specific endpoint from which to request data.
    parameters

    The parameters to send along with the API request, if any. The values are encoded as a URL query string and appended to the destination URL.

  • Creates a new request by specifying the API endpoint from which to request.

    If a valid API URL cannot be derived from the given endpoint, this initializer will fail.

    Declaration

    Swift

    public convenience init?(method: HTTPMethod, endpoint: String, parameters: [String: Any] = [:])

    Parameters

    method

    The HTTP verb to use for this API request. For possible values, see SKRequest.HTTPMethod.
    endpoint

    The destination endpoint for this API request, relative to the Web API base URL (https://api.spotify.com).
    parameters

    The parameters to send along with the API request, if any. The values are encoded as a URL query string and appended to the destination URL.

Preparing Requests

  • Adds multipart request body data for a PUT, POST, or DELETE request.

    Declaration

    Swift

    public func add(_ data: Data, type: ContentType = .json)

    Parameters

    data

    The data for the request body, typically an encoded JSON object.
    type

    The MIME content type of the request body. The default value is .json.

Sending Requests

  • Performs the request, handling API-specific responses and calling the specified handler when complete.

    Declaration

    Swift

    public func perform(completion handler: @escaping SKRequestHandler)

    Parameters

    handler

    The callback handler for this request. The parameters for this handler are:

    • data: The data (typically an encoded JSON object) returned by the request, if any.
    • status: The API-specific HTTP status code associated with the response. If the underlying URL request could not be completed successfully, or the URL response contained an unexpected status code, this parameter will be nil.
    • error: An error identifying if and why the request or decoding failed, or nil if the request was successful.

  • Performs the request, decoding the JSON data returned by the request to the given type and calling the specified handler when complete.

    Declaration

    Swift

    public func perform<T: JSONDecodable>(completion handler: @escaping SKDecodableHandler<T>)

    Parameters

    handler

    The callback handler for this request. The parameters for this handler are:

    • type: The type decoded from the JSON data returned by the request.
    • error: An error object identifying if and why the request or decoding failed, or nil if the request was successful.

  • Performs the request, calling the specified handler when complete.

    Declaration

    Swift

    public func perform(completion handler: @escaping SKErrorHandler)

    Parameters

    handler

    The callback handler for the request, providing an error identifying if and why the request failed, or nil if the request was successful.