Push-Definitions/Sources/PushAPI/Push.swift

import Foundation

/**
 All routes available on the server.

 The raw values of the cases represent the path to the route.
 */
public enum Route: String {

    /**
     Register a device for push notifications.

     If the selected application requires approval, then the administrator must approve the device before it can receive push notifications.
     * HTTP Method: `POST`
     * HTTP Body: `DeviceRegistration` JSON object.
     * Response: The binary authentication token generated for the device. Status `417`, if the application does not exist.
     */
    case registerNewDevice = "register"

    /**
     Update the push token for a registered device.

     * HTTP Method: `POST`
     * HTTP Body: A `PushTokenUpdate` JSON object.
     * Response: A status of `200` is returned on success. `401` if the authorization fails.
     */
    case updatePushToken = "update"

    /**
     Get a list of unapproved devices for review.

     * HTTP Method: `POST`
     * HTTP Body: An `AdminRequest` JSON object with the SHA256 hash of the admin key and the application id
     * Response: An array of `DeviceRegistration` elements encoded in JSON. `401` if the master key is incorrect.
     */
    case listUnapprovedDevices = "check"

    /**
     Get a list of approved devices for the same application as the requestor.

     * HTTP Method: `POST`
     * HTTP Body: A `DeviceConfirmation` JSON object
     * Response: An array of `DeviceRegistration` with all devices registered for the same application. Status `401` if the authentication is incorrect. Status `417`, if the application does not allow device listing.
     */
    case listDevicesInApplication = "devices"

    /**
     Approve a device for an application.

     * HTTP Method: `POST`
     * HTTP Body: A `DeviceDecision` object with the push token of the approved device and the SHA256 hash of the master key.
     * Response: Status `200` on success, `401` for an invalid master key.

     - Note: If no device with the push token exists, then this call does nothing and returns `200`
     */
    case approveDevice = "approve"

    /**
     Reject a device.

     * HTTP Method: `POST`
     * HTTP Body: A `DeviceDecision` object with the push token of the rejected device and the SHA256 hash of the master key.
     * Response: Status `200` on success, `401` for an invalid master key.

     - Note: If no device with the push token exists, then this call does nothing and returns `200`
     */
    case rejectDevice = "reject"

    /**
     Check if a registered device is approved for usage.

     * HTTP Method: `POST`
     * HTTP Body: A `DeviceAuthentication` object
     * Response: Status `200` if the device is confirmed, and `401` if the device is not confirmed.
     */
    case isDeviceApproved = "approved"

    /**
     Send a push notification to a list of devices.

     * HTTP Method: `POST`
     * HTTP Body: An `AuthenticatedPushMessage` object
     * Response: `200` on success, `401` if authentication is invalid.
     */
    case sendPushNotification = "push"

    /// The HTTP method required for the route.
    public var httpMethod: String {
        // Currently all routes expect `POST` requests.
        return "POST"
    }

    /**
     Create the url for the route on a server.
     - Parameter server: The url of the server.
     - Returns: The url to the route.
     */
    public func url(for server: URL) -> URL {
        server.appendingPathComponent(rawValue)
    }
}

/**
 An apple push token (usually 32 byte).

 Push tokens are created when a device registers with the Apple Push Notification Service (APNS). The tokens act as identifiers to transmit push notifications to devices. The server uses the unique push tokens to identify devices and assign them to applications.
 */
public typealias PushToken = Data

/**
 An authentication token of a device.

 These tokens are created by the server during device registration, and used for all subsequent requests in combination with the push token.
 */
public typealias AuthenticationToken = Data

/**
 The name of an application.

 The push server can simultaneously handle multiple applications, which are identified by a unique string. Applications can require confirmation of new device registrations by the administrator. The server configuration also specifies if applications allow the retrieval of device lists for all registered devices, to directly send push notifications to the participants.
 */
public typealias ApplicationId = String

/**
 The SHA256 hash of the master key with a salt.
 */
public typealias MasterKeyHash = Data