Skip to main content

Push Server Spec

This is an overview spec document which details the endpoint and what they expect to receive and in turn what responses you can expect.

Security​

The details of Push Server's Security are in auth.md

Responses​

These are the default responses and are only different if otherwise specified.

Successful Response​

{
    "status": "OK"
}

Unsuccessful Response​

{
    "status": "FAILED",
    "errors": [
        { "name": "", description": "" }
    ]
    "fields": [
        { "field": "type", "description": "", "location": "" }
    ]
}

This is sent whenever push server encounters an error. The fields property will only be available if it is a user provided field that caused the error. The errors property will only be available when we can provide more generic errors e.g. Postgres error.

Note location should be treated as an enum (body, query, header, path) where body is the default unless otherwise specified.

Requests​

Health​

GET <PUSH_SERVER_URL>/health

Example Response​

OK, push-server v0.1.0

Register Client​

POST <PUSH_SERVER_URL>/clients
{
    "client_id": <CLIENT_ID>,
    "type": <TYPE>,
    "token": <DEVICE_TOKEN>
}
  • CLIENT_ID: The Client's ID from the Relay pairing.
  • TYPE: The push service to use e.g. APNS, FCM. This will be validated against the supported types on the Push Server's side.
  • DEVICE_TOKEN: The device's token for the push service e.g. FCM, APNS.

Unregister Client​

DELETE <PUSH_SERVER_URL>/clients/<CLIENT_ID>
  • CLIENT_ID: The Client's ID from the Relay pairing.

Send Notification​

POST <PUSH_SERVER_URL>/clients/<CLIENT_ID>
{
    "id": "0000-0000-0000-0000"
    "payload": {
      "topic": "<topic>",
      "flags": <flags>,
      "blob": "<blob>"
    }
  • CLIENT_ID: This is used to map to the device token
  • id: This is generated by the Relay to prevent duplicate notifications
  • payload: A string with 3 values encoded and split with a : as a delimiter.
    • topic: This is used by the SDKs to decrypt encrypted payloads on the client side
    • flags: an integer value that uses bitmasks to encode information about the payload for the SDKs, the flags are below
      Encrypted  = 1 << 0
      Sign       = 1 << 1
      Auth       = 1 << 2
      Chat       = 1 << 3
      Notify     = 1 << 4
    • blob: If the payload is encrypted this is just the encrypted blob, when this is cleartext it should be base64 encoded. The blob should follow the format from of the Notify Message