5. Requesting Push Message Delivery

An application server requests the delivery of a push message by sending an HTTP POST request to a push resource distributed to the application server by a user agent. The content of the push message is included in the body of the request.

POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
Host: push.example.net
TTL: 15
Content-Type: text/plain;charset=utf8
Content-Length: 36

iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB

A 201 (Created) response indicates that the push message was accepted. A URI for the push message resource that was created in response to the request MUST be returned in the Location header field. This does not indicate that the message was delivered to the user agent.

HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:56:55 GMT
Location: https://push.example.net/message/qDIYHNcfAIPP_5ITvURr-d6BGt

5.1. Requesting Push Message Receipts

An application server can include the Prefer header field [RFC7240] with the respond-async preference to request confirmation from the push service when a push message is delivered and then acknowledged by the user agent. The push service MUST support delivery confirmations.

POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
Host: push.example.net
Prefer: respond-async
TTL: 15
Content-Type: text/plain;charset=utf8
Content-Length: 36

iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB

When the push service accepts the message for delivery with confirmation, it MUST return a 202 (Accepted) response. A URI for the push message resource that was created in response to the request MUST be returned in the Location header field. The push service MUST also provide a URI for the receipt subscription resource in a link relation of type urn:ietf:params:push:receipt.

HTTP/1.1 202 Accepted
Date: Thu, 11 Dec 2014 23:56:55 GMT
Link: </receipt-subscription/3ZtI4YVNBnUUZhuoChl6omUvG4ZM>;
        rel="urn:ietf:params:push:receipt"
Location: https://push.example.net/message/qDIYHNcfAIPP_5ITvURr-d6BGt

For subsequent receipt requests to the same origin [RFC6454], the application server SHOULD include the returned receipt subscription in a link relation of type urn:ietf:params:push:receipt. This gives the push service the option to aggregate the receipts. The push service SHOULD return the same receipt subscription in its response, although it MAY return a new receipt subscription if it is unable to reuse the one provided by the application server.

An application server MAY omit the receipt subscription if it is unable to receive receipts in an aggregated way for the lifetime of the receipt subscription. This might be necessary if the application server is monitoring receipt subscriptions on behalf of the other push message senders.

A push service MUST return a 400 (Bad Request) status code for requests that contain an invalid receipt subscription. If a push service wishes to limit the number of receipt subscriptions that it maintains, it MAY return a 429 (Too Many Requests) status code [RFC6585] to reject receipt requests that omit a receipt subscription.

5.2. Push Message Time-To-Live

A push service can improve the reliability of push message delivery considerably by storing push messages for a period. User agents are often only intermittently connected, and so benefit from having short-term message storage at the push service.

Delaying delivery might also be used to batch communication with the user agent, thereby conserving radio resources.

Some push messages are not useful once a certain period of time elapses. Delivery of messages after they have ceased to be relevant is wasteful. For example, if the push message contains a call notification, receiving a message after the caller has abandoned the call is of no value; the application at the user agent is forced to suppress the message so that it does not generate a useless alert.

An application server MUST include the TTL (Time-To-Live) header field in its request for push message delivery. The TTL header field contains a value in seconds that suggests how long a push message is retained by the push service.

The TTL rule specifies a non-negative integer, representing time in seconds. A recipient parsing and converting a TTL value to binary form SHOULD use an arithmetic type of at least 31 bits of non-negative integer range. If a recipient receives a TTL value greater than the greatest integer it can represent, or if any of its subsequent calculations overflows, it MUST consider the value to be 2147483648 (2^31).

TTL = 1*DIGIT

A push service MUST return a 400 (Bad Request) status code in response to requests that omit the TTL header field.

A push service MAY retain a push message for a shorter duration than requested. It indicates this by returning a TTL header field in its response with the actual TTL. This TTL value MUST be less than or equal to the value provided by the application server.

Once the TTL period elapses, the push service MUST NOT attempt to deliver the push message to the user agent. A push service might adjust the TTL value to account for time accounting errors in processing. For instance, distributing a push message within a server cluster might accrue errors due to clock skew or propagation delays.

A push service is not obligated to account for time spent by the application server in sending a push message to the push service, or delays incurred while sending a push message to the user agent. An application server needs to account for transit delays in selecting a TTL header field value.

A Push message with a zero TTL is immediately delivered if the user agent is available to receive the message. After delivery, the push service is permitted to immediately remove a push message with a zero TTL. This might occur before the user agent acknowledges receipt of the message by performing an HTTP DELETE on the push message resource. Consequently, an application server cannot rely on receiving acknowledgement receipts for zero TTL push messages.

If the user agent is unavailable, a push message with a zero TTL expires and is never delivered.

5.3. Push Message Urgency

For a device that is battery-powered, it is often critical that it remains dormant for extended periods. Radio communication in particular consumes significant power and limits the length of time that the device can operate.

To avoid consuming resources to receive trivial messages, it is helpful if an application server can communicate the urgency of a message and if the user agent can request that the push server only forwards messages of a specific urgency.

An application server MAY include an Urgency header field in its request for push message delivery. This header field indicates the message urgency. The push service MUST NOT forward the Urgency header field to the user agent. A push message without the Urgency header field defaults to a value of normal.

A user agent MAY include the Urgency header field when monitoring for push messages to indicate the lowest urgency of push messages that it is willing to receive. A push service MUST NOT deliver push messages with lower urgency than the value indicated by the user agent in its monitoring request. Push messages of any urgency are delivered to a user agent that does not include an Urgency header field when monitoring for messages.

The grammar for the Urgency header field is as follows:

Urgency = urgency-option
urgency-option = ("very-low" / "low" / "normal" / "high")

In order of increasing urgency:

Urgency	Device State	Example Application Scenario
very-low	On power and Wi-Fi	Advertisements
low	On either power or Wi-Fi	Topic updates
normal	On neither power nor Wi-Fi	Chat or Calendar Message
high	Low battery	Incoming phone call or time-sensitive alert

Table 1: Illustrative Urgency Values

Multiple values for the Urgency header field MUST NOT be included in requests; otherwise, the push service MUST return a 400 (Bad Request) status code.

5.4. Replacing Push Messages

A push message that has been stored by the push service can be replaced with new content. If the user agent is offline during the time that the push messages are sent, updating a push message avoids the situation where outdated or redundant messages are sent to the user agent.

Only push messages that have been assigned a topic can be replaced. A push message with a topic replaces any outstanding push message with an identical topic.

A push message topic is a string carried in a Topic header field. A topic is used to correlate push messages sent to the same subscription and does not convey any other semantics.

The grammar for the Topic header field uses the token rule defined in [RFC7230].

Topic = token

For use with this protocol, the Topic header field MUST be restricted to no more than 32 characters from the URL and a filename-safe Base 64 alphabet [RFC4648]. A push service that receives a request with a Topic header field that does not meet these constraints MUST return a 400 (Bad Request) status code to the application server.

A push message replacement request creates a new push message resource and simultaneously deletes any existing message resource that has a matching topic. If an attempt was made to deliver the deleted push message, an acknowledgment could arrive at the push service after the push message has been replaced. Delivery receipts for such deleted messages SHOULD be suppressed.

The replacement request also replaces the stored TTL, Urgency, and any receipt subscription associated with the previous message in the matching topic.

A push message with a topic that is not shared by an outstanding message to the same subscription is stored or delivered as normal.

For example, the following message could cause an existing message to be replaced:

POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
Host: push.example.net
TTL: 600
Topic: upd
Content-Type: text/plain;charset=utf8
Content-Length: 36

ZuHSZPKa2b1jtOKLGpWrcrn8cNqt0iVQyroF

If the push service identifies an outstanding push message with a topic of upd, then that message resource is deleted. A 201 (Created) response indicates that the push message replacement was accepted. A URI for the new push message resource that was created in response to the request is included in the Location header field.

HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:57:02 GMT
Location: https://push.example.net/message/qDIYHNcfAIPP_5ITvURr-d6BGt

The value of the Topic header field MUST NOT be forwarded to user agents. Its value is neither encrypted nor authenticated.