A word about users¶

First of all, WebPush Channels doesn’t provide users management.

There is no such thing as user sign-up, password modification, etc.

However, users are uniquely identified.

OAuth Bearer token¶

If the configured authentication policy uses OAuth2 bearer tokens, authentication shall be done using this header:

Authorization: Bearer <oauth_token>

The policy will verify the provided OAuth2 bearer token on a remote server.

Register to a channel¶

PUT /channels/(channel_id)/registration¶

synopsis:	Subscribe the user to the channel

Requires authentication

Example Request

$ http PUT http://localhost:9999/v0/channels/formbuilder-collections-update/registration Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98" -v

PUT /v0/channels/formbuilder-collections-update/registration HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Portier dccd8ac07f3e45c9907da638e994ff98
Connection: keep-alive
Host: localhost:9999
User-Agent: HTTPie/0.9.2

Example Response

HTTP/1.1 202 Accepted
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Date: Thu, 18 Jun 2015 17:02:23 GMT
Server: waitress


{"code": 202, "message": "Accepted"}

Unsubscribing from a channel¶

DELETE /channels/(channel_id)/registration¶

synopsis:	Unsubscribe the user from the channel

Requires authentication

Example Request

$ http delete http://localhost:9999/v0/channels/formbuilder-collections-write/registration Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98" -v

DELETE /v0/channels/formbuilder-collections-update/registration HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Portier dccd8ac07f3e45c9907da638e994ff98
Connection: keep-alive
Host: localhost:9999
User-Agent: HTTPie/0.9.2

Example Response

HTTP/1.1 202 Accepted
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Date: Thu, 18 Jun 2015 17:02:23 GMT
Server: waitress


{"code": 202, "message": "Accepted"}

Getting channels informations¶

GET /channels/(channel_id)¶

Synopsis:	Retrieve channel informations

Example Request

$ http get http://localhost:9999/v0/channels/formbuilder-collection-write Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98" -v

GET /v0/channels/formbuilder-collection-write HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Basic Ym9iOg==
Connection: keep-alive
Host: localhost:9999
User-Agent: HTTPie/0.9.2

Example Response

HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Last-Modified, ETag
Content-Length: 211
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 17:29:59 GMT
Etag: "1434648599199"
Last-Modified: Thu, 18 Jun 2015 17:29:59 GMT
Server: waitress

{
    "data": {
        "id": "formbuilder-collection-write",
        "registrations": 1,
        "push": 0
    }
}

• registration contains the number of users that subscribed to the channel.
• push contains the number of push that were sent to the channel.

Broadcasting a push notification¶

For the first version, only users configured in the service configuration can broadcast notifications.

However in the future we aim at adding a permissions management feature to the channel.

POST /channels/(channel_id)¶

synopsis:	Push a notification

Requires authentication

Example Request

$ http post http://localhost:9999/v0/channels/formbuilder-collections-write Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98" -v

POST /v0/channels/formbuilder-collections-update HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic Ym9iOg==
Connection: keep-alive
Content-Length: 25
Content-Type: application/json
Host: localhost:9999
User-Agent: HTTPie/0.9.2

{
  "data": {
      "last_modified": 1434647996969
  }
}

Example Response

HTTP/1.1 202 Accepted
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Date: Thu, 18 Jun 2015 17:02:23 GMT
Server: waitress


{"code": 202, "message": "Accepted"}

The data payload will be encrypted for each subscriptions and sent authenticated through the endpoint.

Add a new user subscription¶

POST /subscriptions¶

synopsis:	Store a subscription. The ID will be assigned automatically.

Requires authentication

Example Request

$ echo '{"data": {"endpoint": "URL", "keys": {}}}' | http post http://localhost:9999/v0/subscriptions Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98" -v

POST /v0/subscriptions HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Portier dccd8ac07f3e45c9907da638e994ff98
Connection: keep-alive
Content-Length: 25
Content-Type: application/json
Host: localhost:9999
User-Agent: HTTPie/0.9.2

{
    "data": {
        "endpoint": "https://updates.push.services.mozilla.com/wpush/v1/gAAAAABYZNChoTLTAeA9vv-_zeqGuZiM4ESpiV7oiT5XtrN8aI01fiCQ7-_hC8lhqXanjUEWp5MFRoq35QmzdplCkRhp5nRgjwneGCGO8WXYH9psZaD_xInKLWm7K8-tzFAp-vRNHx79",
        "keys": {
            "auth": "pnipzxpMvKBNYZAcxc-MAA",
            "p256dh": "BEVoH6cOlNPuvYR0aVJo4GVv84nbymzpXxNff7hpKYjVIFcuIEtqiLtIe4rLOXF_A2w3KWRJoCYJEjUedrXcNpc"
        }
    }
}

Example Response

HTTP/1.1 201 Created
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Content-Length: 199
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 17:02:23 GMT
Server: waitress

{
    "data": {
        "endpoint": "https://updates.push.services.mozilla.com/wpush/v1/gAAAAABYZNChoTLTAeA9vv-_zeqGuZiM4ESpiV7oiT5XtrN8aI01fiCQ7-_hC8lhqXanjUEWp5MFRoq35QmzdplCkRhp5nRgjwneGCGO8WXYH9psZaD_xInKLWm7K8-tzFAp-vRNHx79",
        "keys": {
            "auth": "pnipzxpMvKBNYZAcxc-MAA",
            "p256dh": "BEVoH6cOlNPuvYR0aVJo4GVv84nbymzpXxNff7hpKYjVIFcuIEtqiLtIe4rLOXF_A2w3KWRJoCYJEjUedrXcNpc"
        }
    }
}

Retrieving user’s subscriptions¶

GET /subscriptions¶

Synopsis:	Retrieve all the subscriptions for the user.

Requires authentication

Example Request

$ http get http://localhost:9999/v0/subscriptions Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98"

GET /v0/subscriptions HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Portier dccd8ac07f3e45c9907da638e994ff98
Connection: keep-alive
Host: localhost:9999
User-Agent: HTTPie/0.9.2

HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Next-Page, Total-Records, Last-Modified, ETag
Content-Length: 110
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 17:24:38 GMT
Etag: "1434648278603"
Last-Modified: Thu, 18 Jun 2015 17:24:38 GMT
Server: waitress
Total-Records: 1

{
    "data": [
        {
            "endpoint": "https://updates.push.services.mozilla.com/wpush/v1/gAAAAABYZNChoTLTAeA9vv-_zeqGuZiM4ESpiV7oiT5XtrN8aI01fiCQ7-_hC8lhqXanjUEWp5MFRoq35QmzdplCkRhp5nRgjwneGCGO8WXYH9psZaD_xInKLWm7K8-tzFAp-vRNHx79",
            "keys": {
                "auth": "pnipzxpMvKBNYZAcxc-MAA",
                "p256dh": "BEVoH6cOlNPuvYR0aVJo4GVv84nbymzpXxNff7hpKYjVIFcuIEtqiLtIe4rLOXF_A2w3KWRJoCYJEjUedrXcNpc"
            },
            "id": "89881454-e4e9-4ef0-99a9-404d95900352",
            "last_modified": 1434647996969
        }
    ]
}

Delete user’s subscriptions¶

DELETE /subscriptions¶

Synopsis:	Delete all the user’s subscriptions

Requires authentication

Example Request

$ http delete http://localhost:9999/v0/subscriptions Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98"

DELETE /v0/subscriptions HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Portier dccd8ac07f3e45c9907da638e994ff98
Connection: keep-alive
Host: localhost:9999
User-Agent: HTTPie/0.9.2

Example Response

HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Last-Modified, ETag
Content-Length: 211
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 17:29:59 GMT
Etag: "1434648599199"
Last-Modified: Thu, 18 Jun 2015 17:29:59 GMT
Server: waitress

{
    "data": [{
        "deleted": true,
        "id": "89881454-e4e9-4ef0-99a9-404d95900352",
        "last_modified": 1434648749173
    }]
}

Deleting a single subscription¶

DELETE /subscriptions/(subscription_id)¶

Synopsis:	Delete a subscription by its ID.

Example Request

$ http delete http://localhost:9999/v0/subscriptions/89881454-e4e9-4ef0-99a9-404d95900352  Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98"

DELETE /v0/subscriptions/89881454-e4e9-4ef0-99a9-404d95900352 HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Portier dccd8ac07f3e45c9907da638e994ff98
Connection: keep-alive
Content-Length: 0
Host: localhost:9999
User-Agent: HTTPie/0.9.2

Example Response

HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Content-Length: 99
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 17:32:29 GMT
Server: waitress

{
    "data": {
        "deleted": true,
        "id": "89881454-e4e9-4ef0-99a9-404d95900352",
        "last_modified": 1434648749173
    }
}

GET /¶

The returned value is a JSON mapping containing:

• project_name: the name of the service (e.g. "reading list")

• project_docs: The URL to the service documentation. (this document!)

• project_version: complete application/project version ("3.14.116")

• http_api_version: the MAJOR.MINOR version of the exposed HTTP API ("1.1") defined in the project.

• url: absolute URI (without a trailing slash) of the API (can be used by client to build URIs)

• eos: date of end of support in ISO 8601 format ("yyyy-mm-dd", undefined if unknown)

• settings: a mapping with the values of relevant public settings for clients

  • batch_max_requests: Number of requests that can be made in a batch request.
  • readonly: Only requests with read operations are allowed.

• capabilities: a mapping used by clients to detect optional features of the API.

  • Example:

    {
      "fxa": {
        "description": "Firefox Account authentication",
        "url": "http://github.com/mozilla-services/kinto-fxa"
      }
    }
    

Optional

• user: A mapping with an id field and a list of principals for the currently connected user id. The field is not present when no Authorization header is provided.

GET /__heartbeat__¶

Return the status of each service the application depends on. The returned value is a JSON mapping containing:

• storage true if storage backend is operational
• cache true if cache backend operational

If kinto-fxa is installed, an additional key is present:

• oauth true if FxA authentication is operational

If kinto-portier is installed, an additional key is present:

• portier true if portier authentication is operational

Return 200 OK if the connection with each service is working properly and 503 Service Unavailable if something doesn’t work.

GET /__lbheartbeat__¶

Always return 200 OK with empty body.

Unlike the __heartbeat__ health check endpoint, which return an error when backends and other upstream services are unavailable, this should always return 200 OK.

This endpoint is suitable for a load balancer membership test. It the load balancer cannot obtain a response from this endpoint, it will stop sending traffic to the instance and replace it.

GET /contribute.json¶

The returned value is a JSON mapping containing open source contribution information as advocated by https://www.contributejson.org

GET /__version__¶

Return a JSON mapping containing information about what distribution has been deployed by OPs.

{
  "name":"webpush-channels",
  "version":"1.0.1",
  "commit":"ab8db089ee63dc8e14f4bcfc427a86f311dd7e52",
  "source":"https://github.com/mansimarkaur/webpush-channels.git"
}

The content of this view comes from a file, whose location is specified via the webpush_channels.version_json_path setting or WEBPUSH_CHANNELS_VERSION_JSON_PATH environment variable (default location is version.json in current working directory).

Return 404 Not Found if no version.json file is found.

Backoff header on heavy load¶

A Backoff header will be added to the success responses (>=200 and <400) when the server is under heavy load. It provides the client with a number of seconds during which it should avoid doing unnecessary requests.

Backoff: 30

Retry-After indicators¶

A Retry-After header will be added if response is an error (>=500). See more details about error responses.

API description¶

Every response is JSON.

If the HTTP status is not OK (<200 or >=400), the response contains a JSON mapping, with the following attributes:

• code: matches the HTTP status code (e.g 400)
• errno: stable application-level error number (e.g. 109)
• error: string description of error type (e.g. "Bad request")
• message: context information (e.g. "Invalid request parameters")
• info: online resource (e.g. URL to error details)
• details: additional details (e.g. list of validation errors)

Example response

{
    "code": 412,
    "errno": 114,
    "error": "Precondition Failed",
    "message": "Resource was modified meanwhile",
    "info": "https://server/docs/api.html#errors",
}

Refer yourself to the set of errors codes.

Retry-After indicators¶

A Retry-After header will be added to error responses (>=500), telling the client how many seconds it should wait before trying again.

Retry-After: 30

Validation errors¶

When multiple validation errors occur on a request, the first one is presented in the message.

The full list of validation errors is provided in the details field.

{
    "code": 400,
    "errno": 109,
    "error": "Bad Request",
    "message": "Invalid posted data",
    "info": "https://server/docs/api.html#errors",
    "details": [
        {
            "description": "42 is not a string: {'name': ''}",
            "location": "body",
            "name": "name"
        }
    ]
}