ServiceProtocol

@objc public protocol ServiceProtocol

Protocol all services must implement to be considered a service

Important

You will notice all these methods are staticly defined. Services are expected to be completely static classes. This is done to emphasize and promote the stateless nature of service calls. Services should be stateless, reentrant, and thread-safe.

There are no guarentees for how, when, on what thread, or how often any service is called.

Protocol Implementation:

  • Unique identifier for this service.

    The serviceIdentifier string will make up the first part of the path for requests made to services.

    Example:

    If a serviceIdentifier is foo then a request to the service will look like:

    http://pmapi/foo

    Declaration

    Swift

    static var serviceIdentifier: String

  • The method called when the ServiceRouter detects a request was made for this service (as identified by the serviceIdentifier)

    Declaration

    Swift

    static func performRequest(_ request: URLRequest, response: HTTPURLResponse, responseReturn : @escaping responseReturnBlock, dataReturn : @escaping dataReturnBlock, requestComplete: @escaping requestCompleteBlock)

    Parameters

    request

    the URLRequest that was made to call this service.
    response

    a template response, preset to have a 200 status code.

    This response object can be used as-is or be used to create a new response.
    responseReturn

    First of three return closures. Used to return the response object back to the calling code.

    This closure must be called and must be called only once.
    dataReturn

    Second of the three return closures. Used to return data back to the calling code.

    This closure is may be skipped if no data is to be returned.

    If called, this closure must be called after the responseReturn closure, and before the requestComplete closure.
    requestComplete

    Third and final of the three return closures. This indicates the service request has completed.

    This closure must be called, or the service request will not be complete

    No additional code should be executed after this closure is called

  • Optional: if this method is implimented, the this method will be called when the service is registered with the service router.

    Declaration

    Swift

    @objc optional static func registered()

  • Optional: if this method is implimented, the this method will be called when the service is unregistered with the service router.

    Declaration

    Swift

    @objc optional static func unregistered()

Protocol Extension helper methods:

  • Shortcut helper method to return a provided status code for a given service request.

    Will construct a HTTPURLResponse object with provided status code, and will call the responseReturn, and requestComplete closures.

    Important

    since this method will call requestComplete, no additional code should be executed in the service after calling this method.

    Declaration

    Swift

    public static func respondWithErrorStatus(_ statusCode: Http.StatusCode, response: HTTPURLResponse, responseReturn: responseReturnBlock, requestComplete: requestCompleteBlock)

    Parameters

    statusCode

    Http.StatusCode enum for the status code the response object should use.
    response

    HTTPURLResponse base object used to construct the response.

    Headers in this object will be included in the HTTPURLResponse object returned in the responseReturn closure call.
    responseReturn

    responseReturn closure provided in the service’s performRequest method.
    requestComplete

    requestComplete closure provided in the service’s performRequest method.

  • Shortcut helper method to return a provided status code for a given service request with positional parameters.

    Will construct a HTTPURLResponse object with provided status code, and will call the responseReturn, and requestComplete closures.

    Important

    since this method will call requestComplete, no additional code should be executed in the service after calling this method.

    Headers in this object will be included in the HTTPURLResponse object returned in the responseReturn closure call.

    Declaration

    Swift

    public static func respondWithErrorStatus(_ statusCode: Http.StatusCode, _ response: HTTPURLResponse, _ responseReturn: responseReturnBlock, _ requestComplete: requestCompleteBlock)

    Parameters

    statusCode

    Http.StatusCode enum for the status code the response object should use.
    response

    HTTPURLResponse base object used to construct the response.
    responseReturn

    responseReturn closure provided in the service’s performRequest method.
    requestComplete

    requestComplete closure provided in the service’s performRequest method.

  • Shortcut helper method to return a provided status code and headers for a given service request.

    Will construct a HTTPURLResponse object with provided status code and headers, and will call the responseReturn, and requestComplete closures.

    Important

    since this method will call requestComplete, no additional code should be executed in the service after calling this method.

    Any headers in this object will be included in the HTTPURLResponse object returned in the responseReturn closure call, appended to the headers provided in the responseHeaders parameter.

    Declaration

    Swift

    public static func respondWithErrorStatus(_ statusCode: Http.StatusCode, response: HTTPURLResponse, responseReturn: responseReturnBlock, requestComplete: requestCompleteBlock, responseHeaders: [String : String]?)

    Parameters

    statusCode

    Http.StatusCode enum for the status code the response object should use.
    response

    HTTPURLResponse base object used to construct the response.
    responseReturn

    responseReturn closure provided in the service’s performRequest method.
    requestComplete

    requestComplete closure provided in the service’s performRequest method.
    responseHeaders

    Optional dictionary of headers to include in the response object.

  • Shortcut helper method to return a provided status code and headers for a given service request with positional parameters.

    Will construct a HTTPURLResponse object with provided status code and headers, and will call the responseReturn, and requestComplete closures.

    Important

    since this method will call requestComplete, no additional code should be executed in the service after calling this method.

    Any headers in this object will be included in the HTTPURLResponse object returned in the responseReturn closure call, appended to the headers provided in the responseHeaders parameter.

    Declaration

    Swift

    public static func respondWithErrorStatus(_ statusCode: Http.StatusCode, _ response: HTTPURLResponse, _ responseReturn: responseReturnBlock, _ requestComplete: requestCompleteBlock, _ responseHeaders: [String : String]?)

    Parameters

    statusCode

    Http.StatusCode enum for the status code the response object should use.
    response

    HTTPURLResponse base object used to construct the response.
    responseReturn

    responseReturn closure provided in the service’s performRequest method.
    requestComplete

    requestComplete closure provided in the service’s performRequest method.
    responseHeaders

    Optional dictionary of headers to include in the response object.

  • Shortcut helper method to return a provided status code and a data string for a given service request.

  • Will construct a HTTPURLResponse object with provided status code, and will call the responseReturn closure.

  • Then will encode the provided string and call the dataReturn closure.

  • Then will call the requestComplete closures.

    • Important

    since this method will call requestComplete, no additional code should be executed in the service after calling this method.

    Headers in this object will be included in the HTTPURLResponse object returned in the responseReturn closure call.

    Declaration

    Swift

    public static func respondWithErrorStatus(_ statusCode: Http.StatusCode, description: String, dataReturn: dataReturnBlock, response: HTTPURLResponse, responseReturn: responseReturnBlock, requestComplete: requestCompleteBlock)

    Parameters

    statusCode

    Http.StatusCode enum for the status code the response object should use.
    description

    string to encode and return as data
    dataReturn

    dataReturn closure provided in the service’s performRequest method.
    response

    HTTPURLResponse base object used to construct the response.
    responseReturn

    responseReturn closure provided in the service’s performRequest method.
    requestComplete

    requestComplete closure provided in the service’s performRequest method.

  • Shortcut helper method to return a provided status code and a data string for a given service request with positional parameters.

  • Will construct a HTTPURLResponse object with provided status code, and will call the responseReturn closure.

  • Then will encode the provided string and call the dataReturn closure.

  • Then will call the requestComplete closures.

    • Important

    since this method will call requestComplete, no additional code should be executed in the service after calling this method.

    Declaration

    Swift

    public static func respondWithErrorStatus(_ statusCode: Http.StatusCode, _ description: String, _ dataReturn: dataReturnBlock, _ response: HTTPURLResponse, _ responseReturn: responseReturnBlock, _ requestComplete: requestCompleteBlock)

    Parameters

    statusCode

    Http.StatusCode enum for the status code the response object should use.
    description

    string to encode and return as data
    dataReturn

    dataReturn closure provided in the service’s performRequest method.
    response

    HTTPURLResponse base object used to construct the response.

    Headers in this object will be included in the HTTPURLResponse object returned in the responseReturn closure call.
    responseReturn

    responseReturn closure provided in the service’s performRequest method.
    requestComplete

    requestComplete closure provided in the service’s performRequest method.
  • createResponse(_:response:) Extension method

    Helper method to create a HTTPURLResponse based on the provided response object, and containing the provided Http.StatusCode status code.

    Declaration

    Swift

    public static func createResponse(_ statusCode: Http.StatusCode, response: HTTPURLResponse) -> (HTTPURLResponse)

    Parameters

    statusCode

    Http.StatusCode enum for the status code the response object should use.
    response

    HTTPURLResponse base object used to construct the response.

    Headers in this object will be included in the HTTPURLResponse object returned.

  • Helper method to create a HTTPURLResponse based on the provided response object, and containing the provided Http.StatusCode status code.

    Declaration

    Swift

    public static func createResponse(_ statusCode: Http.StatusCode, response: HTTPURLResponse, responseHeaders responseHeadersOptional: [String : String]?) -> (HTTPURLResponse)

    Parameters

    statusCode

    Http.StatusCode enum for the status code the response object should use.
    response

    HTTPURLResponse base object used to construct the response.

    Any headers in this object will be included in the HTTPURLResponse object returned in the responseReturn closure call, appended to the headers provided in the responseHeaders parameter.
    responseHeaders

    Optional dictionary of headers to include in the returned HTTPURLResponse object.