Subscriptions¶

Subscriptions belongs to an user.

A user can have multiple subscriptions (one per browser session or device).

A subscription consist on the information that you can get from a requesting a Push subscription on the browser.

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

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"
        }
    }
}

Validation¶

If the posted values are invalid (e.g. field value is not an integer) an error response is returned with 400 Bad Request.

See details on error responses.

HTTP Status Codes¶

200 OK: This object already exists, the one stored on the database is returned
201 Created: The object was created
400 Bad Request: The request body is invalid
401 Unauthorized: The request is missing authentication headers
403 Forbidden: The user is not allowed to perform the operation, or the resource is not accessible
406 Not Acceptable: The client doesn’t accept supported responses Content-Type
412 Precondition Failed: List has changed since value in If-Match header
415 Unsupported Media Type: The client request was not sent with a correct Content-Type

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
    }
}