Skip to main content

4. Subscribing for Push Messages

4. Subscribing for Push Messages​

A user agent sends a POST request to its configured push service resource to create a new subscription.

POST /subscribe HTTP/1.1
Host: push.example.net

A 201 (Created) response indicates that the push subscription was created. A URI for the push message subscription resource that was created in response to the request MUST be returned in the Location header field.

The push service MUST provide a URI for the push resource corresponding to the push message subscription in a link relation of type urn:ietf:params:push.

An application-specific method is used to distribute the push URI to the application server. Confidentiality protection and application server authentication MUST be used to ensure that this URI is not disclosed to unauthorized recipients (Section 8.3).

HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:56:52 GMT
Link: </push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV>;
        rel="urn:ietf:params:push"
Link: </subscription-set/4UXwi2Rd7jGS7gp5cuutF8ZldnEuvbOy>;
        rel="urn:ietf:params:push:set"
Location: https://push.example.net/subscription/LBhhw0OohO-Wl4Oi971UG

4.1. Collecting Subscriptions into Sets​

Collecting multiple push message subscriptions into a subscription set can represent a significant efficiency improvement for push services and user agents. The push service MAY provide a URI for a subscription set resource in a link relation of type urn:ietf:params:push:set.

When a subscription set is returned in a push message subscription response, the user agent SHOULD include this subscription set in a link relation of type urn:ietf:params:push:set in subsequent requests to create new push message subscriptions.

A user agent MAY omit the subscription set if it is unable to receive push messages in an aggregated way for the lifetime of the subscription. This might be necessary if the user agent is monitoring subscriptions on behalf of other push message receivers.

POST /subscribe HTTP/1.1
Host: push.example.net
Link: </subscription-set/4UXwi2Rd7jGS7gp5cuutF8ZldnEuvbOy>;
        rel="urn:ietf:params:push:set"

The push service SHOULD return the same subscription set in its response, although it MAY return a new subscription set if it is unable to reuse the one provided by the user agent.

HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:56:52 GMT
Link: </push/YBJNBIMwwA_Ag8EtD47J4A>;
        rel="urn:ietf:params:push"
Link: </subscription-set/4UXwi2Rd7jGS7gp5cuutF8ZldnEuvbOy>;
        rel="urn:ietf:params:push:set"
Location: https://push.example.net/subscription/i-nQ3A9Zm4kgSWg8_ZijV

A push service MUST return a 400 (Bad Request) status code for requests that contain an invalid subscription set. A push service MAY return a 429 (Too Many Requests) status code [RFC6585] to reject requests that omit a subscription set.

How a push service detects that requests originate from the same user agent is implementation-specific but could take ambient information into consideration, such as the TLS connection, source IP address, and port. Implementers are reminded that some heuristics can produce false positives and hence, cause requests to be rejected incorrectly.

Last updated on