HTTP Endpoints for Notifications

Autopush exposes three HTTP endpoints:

/push/...

This is tied to EndpointHandler (autopush.endpoint). This endpoint is returned by the Push registration process and is used by the AppServer to send Push alerts to the Application. See Send Notification.

/m/...

This is tied to MessageHandler (autopush.endpoint). This endpoint handles individual message operations on messages pending delivery, such as deleting the message or updating the contents or Time To Live (TTL). See Cancel Notification and Update Notification.

/v1/.../.../registration/...

This is tied to the RegistrationHandler (autopush.endpoint). This endpoint is used by apps that wish to use bridging protocols to register new channels. See Push Service Bridge HTTP Interface.

Push Service HTTP API

The following section describes how remote servers can send Push Notifications to apps running on remote User Agents.

Lexicon

{UAID}:The Push User Agent Registration ID

Push assigns each remote recipient a unique identifier. {UAID}s are UUIDs in lower case, dashed format. (e.g. ‘01234567-abcd-abcd-abcd-012345678abc’) This value is assigned during Registration

{CHID}:The Channel Subscription ID

Push assigns a unique identifier for each subscription for a given {UAID}. Like {UAID}s, {CHID}s are UUIDs in lower case, dashed format. This value is assigned during Channel Subscription

{message-id}:The unique Message ID

Push assigns each message for a given Channel Subscription a unique identifier. This value is assigned during Send Notification

Response

The responses will be JSON formatted objects. In addition, API calls will return valid HTTP error codes (see Error Codes sub-section for descriptions of specific errors).

For non-success responses, an extended error code object will be returned with the following format:

{
    "code": 404,  // matches the HTTP status code
    "errno": 103, // stable application-level error number
    "error": "Not Found", // string representation of the status
    "message": "No message found" // optional additional error information
}

Error Codes

Autopush uses error codes based on HTTP response codes. An error response will contain a JSON body including an additional error information (see Response).

Unless otherwise specified, all calls return one the following error statuses:

  • 20x - Success - The message was accepted for transmission to the client. Please note that the message may still be rejected by the User Agent if there is an error with the message’s encryption.

  • 301 - Moved + `Location:` if {client_token} is invalid (Bridge API Only) - Bridged services (ones that run over third party services like GCM and APNS), may require a new URL be used. Please stop using the old URL immediately and instead use the new URL provided.

  • 400 - Bad Parameters – One or more of the parameters specified is invalid. See the following sub-errors indicated by errno

    • errno 101 - Missing necessary crypto keys - One or more required crypto key elements are missing from this transaction. Refer to the appropriate specification for the requested content-type.

    • errno 108 - Router type is invalid - The URL contains an invalid router type, which may be from URL corruption or an unsupported bridge. Refer to Push Service Bridge HTTP Interface.

    • errno 110 - Invalid crypto keys specified - One or more of the crytpo key elements are invalid. Refer to the appropriate specification for the requested content-type.

    • errno 111 - Missing Required Header - A required crypto element header is missing. Refer to the appropriate specification for the requested content-type.

    • errno 112 - Invalid TTL header value - The Time To Live “TTL” header contains an invalid or unreadable value. Please change to a number of seconds that this message should live, between 0 (message should be dropped immediately if user is unavailable) and 2592000 (hold for delivery within the next approximately 30 days).

    • errno 113 - Invalid Topic header value - The Topic header contains an invalid or unreadable value. Please use only ASCII alphanumeric values [A-Za-z0-9] and a maximum length of 32 bytes..

  • 401 - Bad Authorization - Authorization header is invalid or missing. See the VAPID specification.

    • errno 109 - Invalid authentication
  • 404 - Endpoint Not Found - The URL specified is invalid and should not be used again.

    • errno 102 - Invalid URL endpoint
  • 410 - Endpoint Not Valid - The URL specified is no longer valid and should no longer be used. A User has become permanently unavailable at this URL.

    • errno 103 - Expired URL endpoint
    • errno 105 - Endpoint became unavailable during request
    • errno 106 - Invalid subscription
  • 413 - Payload too large - The body of the message to send is too large. The max data that can be sent is 4028 characters. Please reduce the size of the message.

    • errno 104 - Data payload too large
  • 500 - Unknown server error - An internal error occurred within the Push Server.

    • errno 999 - Unknown error
  • 503 - Server temporarily unavaliable. - The Push Service is currently unavailable. See the error number “errno” value to see if retries are available.

    • errno 201 - Use exponential back-off for retries
    • errno 202 - Immediate retry ok

Calls

Send Notification

Send a notification to the given endpoint identified by its push_endpoint. Please note, the Push endpoint URL (which is what is used to send notifications) should be considered “opaque”. We reserve the right to change any portion of the Push URL in future provisioned URLs.

Call:

POST {push_endpoint}

If the client is using webpush style data delivery, then the body in its entirety will be regarded as the data payload for the message per the WebPush spec.

Note

Some bridged connections require data transcription and may limit the length of data that can be sent. For instance, using a GCM/FCM bridge will require that the data be converted to base64. This means that data may be limited to only 2744 bytes instead of the normal 4096 bytes.

Parameters:

form version:(Optional) Version of notification, defaults to current time

Reply:

{"message-id": {message-id}}

Return Codes:

statuscode 404:Push subscription is invalid.
statuscode 202:Message stored for delivery to client at a later time.
statuscode 200:Message delivered to node client is connected to.

Cancel Notification

Delete the message given the message_id.

Call:

DELETE /m/{message_id}

Parameters:

None

Reply:

{}

Return Codes:

Update Notification

Update the message at the given {message_id}.

Call:

PUT /m/(string/message_id)

Parameters:

This method takes the same arguments as WebPush PUT, with values replacing that for the provided message.

Note

In the rare condition that the client is online, and has recieved the message but has not acknowledged it yet; then it is possible that the client will not get the updated message until reconnect. This should be considered a rare edge-case.

Reply:

{}

Return Codes:

statuscode 404:message_id is not found.
statuscode 200:Message has been updated.

Push Service Bridge HTTP Interface

Push allows for remote devices to perform some functions using an HTTP interface. This is mostly used by devices that are bridging via an external protocol like GCM/FCM or APNs. All message bodies must be UTF-8 encoded.

API methods requiring Authorization must provide the Authorization header containing the registration secret. The registration secret is returned as “secret” in the registration response.

Lexicon

For the following call definitions:

{type}:The bridge type.

Allowed bridges are gcm (Google Cloud Messaging), fcm (Firebase Cloud Messaging), and apns (Apple Push Notification system)

{app_id}:The bridge specific application identifier

Each bridge may require a unique token that addresses the remote application For GCM/FCM, this is the SenderID (or ‘project number’) and is pre-negotiated outside of the push service. You can find this number using the Google developer console. For APNS, this value is the “platform” or “channel” of development (e.g. “firefox”, “beta”, “gecko”, etc.) For our examples, we will use a client token of “33clienttoken33”.

{instance_id}:The bridge specific private identifier token

Each bridge requires a unique token that addresses the application on a given user’s device. This is the “Registration Token” for GCM/FCM or “Device Token” for APNS. This is usually the product of the application registering the {instance_id} with the native bridge via the user agent. For our examples, we will use an instance ID of “11-instance-id-11”.

{secret}:The registration secret from the Registration call.

Most calls to the HTTP interface require a Authorization header. The Authorization header is a simple bearer token, which has been provided by the Registration call and is preceded by the scheme name “Bearer”. For our examples, we will use a registration secret of “00secret00”.

An example of the Authorization header would be:

Authorization: Bearer 00secret00

Calls

Registration

Request a new UAID registration, Channel ID, and optionally set a bridge type and 3rd party bridge instance ID token for this connection.

Call:

POST /v1/{type}/{app_id}/registration

This call requires no Authorization header for first time use.

Parameters:

{“token”:{instance_id}}

Note

If additional information is required for the bridge, it may be included in the paramters as JSON elements. Currently, no additional information is required.

Reply:

`{"uaid": {UAID}, "secret": {secret},
"endpoint": "https://updates-push...", "channelID": {CHID}}`

example:

> POST /v1/fcm/33clienttoken33/registration
>
> {"token": "11-instance-id-11"}
< {"uaid": "01234567-0000-1111-2222-0123456789ab",
< "secret": "00secret00",
< "endpoint": "https://updates-push.services.mozaws.net/push/...",
< "channelID": "00000000-0000-1111-2222-0123456789ab"}

Return Codes:

See Error Codes.

Token updates

Update the current bridge token value. Note, this is a *PUT* call, since we are updating existing information.

Call:

PUT /v1/{type}/{app_id}/registration/{uaid}
Authorization: Bearer {secret}

Parameters:

{“token”: {instance_id}}

Note

If additional information is required for the bridge, it may be included in the paramters as JSON elements. Currently, no additional information is required.

Reply:

{}

example:

> PUT /v1/fcm/33clienttoken33/registration/abcdef012345
> Authorization: Bearer 00secret00
>
> {"token": "22-instance-id-22"}
< {}

Return Codes:

See Error Codes.

Channel Subscription

Acquire a new ChannelID for a given UAID.

Call:

POST /v1/{type}/{app_id}/registration/{uaid}/subscription
Authorization: Bearer {secret}

Parameters:

{}

Reply:

{"channelID": {CHID}, "endpoint": "https://updates-push..."}

example:

> POST /v1/fcm/33clienttoken33/registration/abcdef012345/subscription
> Authorization: Bearer 00secret00
>
> {}
< {"channelID": "01234567-0000-1111-2222-0123456789ab",
< "endpoint": "https://updates-push.services.mozaws.net/push/..."}

Return Codes:

See Error Codes.

Unregister UAID (and all associated ChannelID subscriptions)

Indicate that the UAID, and by extension all associated subscriptions, is no longer valid.

Call:

DELETE /v1/{type}/{app_id}/registration/{uaid}
Authorization: Bearer {secret}

Parameters:

{}

Reply:

{}

Return Codes:

See Error Codes.

Unsubscribe Channel

Remove a given ChannelID subscription from a UAID.

Call:

DELETE /v1/{type}/{app_id}/registration/{UAID}/subscription/{CHID}
Authorization: Bearer {secret}

Parameters:

{}

Reply:

{}

Return Codes:

See Error Codes.