Declaring Endpoints

You will be declaring an Endpoint for every endpoint you will want to make a request to.

Endpoint Types

Every endpoint you declare must implement one and only one of the following protocols.

• EmptyEndpoint: This endpoint has no input or output and only succeeds or fails based on the default response validation.
• InEndpoint: This endpoint only has input.
• OutEndpoint: This endpoint only has output.
• InOutEndpoint: This endpoint has both input and output.

Basic Endpoint Attributes

There are a few things that all endpoints must define.

Service

The service defines which WebService the endpoint applies to. Declaring it is as simple as a type alias.

struct CheckStatus: EmptyEndpoint {
    typealias Service = MyService

    // ...
}

Method

This is the HTTP method used for the request.

struct CheckStatus: EmptyEndpoint {
    static let method = Method.get

    // ...
}

Path

This is the path to be appended to the base URL to form the final request URL.

struct CheckStatus: EmptyEndpoint {
    let path = "status"

    // ...
}

This will end up generating the URL "https://example.com/api/v1/status" when using the service defined on Declaring Web Services.

This is an instance property so that you can vary it for each call. For example, if you have a GetObject request that uses the object's id.

struct GetObject: OutEndpoint {
    let objectId: Int

    var path: String { return "object/\(objectId)" }

    // ...
}

Output Format

By default, output is expected to be in JSON, however we also support other formats. To declare a different output format expectation, set this property.

struct CheckStatus: EmptyEndpoint {
    static let outputFormat = OutputFormat.XML

    // ...
}

Note: This applies to all endpoints because it is also relevant to basic and error responses.

Authorization Requirement

You can declare 3 levels of authorization requirement for each endpoint:

• None: Never include authorization even if it is set on the service
• Optional: Include authorization if it is set on the service
• Required: Throw an error if authorization is not set on the service

The requirement defaults to Optional, but if you would like to change it, just declare this property.

struct CheckStatus: EmptyEndpoint {
    static let authorizationRequirement = AuthorizationRequirement.required

    // ...
}

Endpoints with Input (InEndpoint and InOutEndpoint)

Input endpoints have two attributes to be declared.

Input

This is the type to be uploaded with the request. It must be Encodable and cannot be a simple type like String, Int, etc because they're not representable alone by JSON.

struct Login: InOutEndpoint {
    struct Input: Encodable {
        let username: String
        let password: String
    }

    // ...
}

Input format

The input format can be set to JSON or urlQuery. URL Query will add the values to the URL instead of posting it as JSON in the request body.

struct Login: InOutEndpoint {
    static let inputFormat = InputFormat.JSON

    // ...
}

Endpoints with Output (OutEndpoint and InOutEndpoint)

A request with output must only declare one attribute.

Output

This is the type to be parsed from the response. It must be Decodable and cannot be a simple type like String, Int, etc because they're not representable alone by JSON.

struct Login: InOutEndpoint {
    struct Output: Decodable {
        let token: String
    }

    // ...
}