Confirmed users
93
edits
WebAPI/SimplePush/Protocol: Difference between revisions
Jump to navigation
Jump to search
no edit summary
No edit summary |
No edit summary |
||
| Line 3: | Line 3: | ||
'''Status: Draft''' | '''Status: Draft''' | ||
'''Everything here applies to Version 1 of the protocol'''. | '''Everything here applies to Version 1 of the protocol'''. | ||
TODO: Possible pain points: | |||
* Versioning | |||
* Sec-WebSocket-Protocol - set to push-notification? | |||
== Purpose == | == Purpose == | ||
| Line 26: | Line 31: | ||
;ChannelID | ;ChannelID | ||
:Unique identifier for a Channel. Generated by UserAgent for a particular application. Opaque identifier for both UserAgent and PushServer | :Unique identifier for a Channel. Generated by UserAgent for a particular application. Opaque identifier for both UserAgent and PushServer. This MUST NOT be exposed to an application. | ||
;Endpoint | ;Endpoint | ||
;A REST-ful HTTP URL uniquely associated to a channel. Requests to this URL should update the PushServer state for the channel. | ;A REST-ful HTTP URL uniquely associated to a channel. Requests to this URL should update the PushServer state for the channel. MUST be exposed to applications. | ||
;Version | ;Version | ||
Monotonically increasing 64-bit integer describing the application state. This | Monotonically increasing 64-bit integer describing the application state. This | ||
holds meaning as a primary key or similar only to the AppServer. The PushServer | holds meaning as a primary key or similar only to the AppServer. The PushServer | ||
and UserAgent and App should use this only for detecting changes. | and UserAgent and App should use this only for detecting changes. MUST be exposed to applications. | ||
;Application | |||
A program which requires access to push notifications. The UserAgent acts on behalf of applications. | |||
== Protocol Overview == | == Protocol Overview == | ||
| Line 136: | Line 144: | ||
=== Register === | === Register === | ||
The Register message is used by the UserAgent to request that the PushServer notify it when a channel changes. Since channelIDs are associated with only one UAID, this effectively creates the channel, while unregister destroys the channel. | |||
The channelID is chosen by the UserAgent because it also acts like a nonce for the Register message itself. Because of this PushServers MAY respond out of order to multiple register messages or messages may be lost without compromising correctness of the protocol. | |||
The request is considered successful only after a response is received with a status code of 200. On success the UserAgent MUST: | |||
* Update it's persistent storage based on the response | |||
* Notify the application of a successful registration. | |||
On error, the UserAgent MUST notify the application as soon as possible. | |||
NOTE: The register call is made by the UserAgent on behalf of an application. The UserAgent SHOULD have reasonable timeouts in place so that the application is not kept waiting for too long if the server does not respond or the UserAgent has to retry the connection. | |||
==== UserAgent -> PushServer ==== | |||
;messageType = "register" | |||
;channelID string '''REQUIRED''' | |||
==== PushServer -> UserAgent ==== | |||
;messageType = "register" | |||
;channelID string '''REQUIRED''' | |||
:This MUST be the same as the channelID sent by the UserAgent in the register request that this message is a response to. | |||
;status number '''REQUIRED''' | |||
: Used to indicate success/failure. MUST be one of: | |||
* 200 - OK. Success | |||
* 409 - Conflict. The chosen ChannelID is already in use and not associated with this UserAgent. UserAgent SHOULD retry with a new ChannelID as soon as possible. | |||
* 500 - Internal server error. Database out of space or offline. Disk space full or whatever other reason due to which the PushServer could not grant this registration. UserAgent SHOULD avoid retrying immediately. | |||
;pushEndpoint string '''REQUIRED''' | |||
: Should be the URL sent to the application by the UserAgent. AppServer's will contact the PushServer at this URL to update the version of the channel identified by channelID. | |||
=== Unregister === | === Unregister === | ||
:messageType = "unregister" | |||
;channelID string '''REQUIRED''' | |||
=== Notification === | === Notification === | ||