Confirmed users
1,021
edits
WebAPI/SimplePush: Difference between revisions
→API
(→API) |
|||
| Line 111: | Line 111: | ||
UserAgent and AppServer will use a RESTful API to interact with the Push Server. | UserAgent and AppServer will use a RESTful API to interact with the Push Server. | ||
== API == | === API === | ||
* Requests from UserAgent to PushServer MUST provide a PushServer Generated UserAgentID (UAID) as the "X-UserAgent-ID" header. | * Requests from UserAgent to PushServer MUST provide a PushServer Generated UserAgentID (UAID) as the "X-UserAgent-ID" header. | ||
* UserAgent requests may include a /{network} prefix to indicate a request may be handled by a third party network | * UserAgent requests may include a /{network} prefix to indicate a request may be handled by a third party network | ||
| Line 119: | Line 119: | ||
* On Errors, calls will return a proper error code, and where permitted, a standard JSON block containing information regarding the error. The contents of this block are not intended for end user display and have yet to be finalized. | * On Errors, calls will return a proper error code, and where permitted, a standard JSON block containing information regarding the error. The contents of this block are not intended for end user display and have yet to be finalized. | ||
=== POST /register === | ==== POST /register ==== | ||
Request a new ChannelID. | Request a new ChannelID. | ||
If the <i>X-UserAgent-ID</i> is not provided, the UserAgent is presumed to be new and a new UserAgentID will be generated for the UserAgent. | If the <i>X-UserAgent-ID</i> is not provided, the UserAgent is presumed to be new and a new UserAgentID will be generated for the UserAgent. | ||
==== Arguments ==== | ===== Arguments ===== | ||
No additional arguments are required. | No additional arguments are required. | ||
==== Return Value ==== | ===== Return Value ===== | ||
{ "channelID": "New Channel ID", | { "channelID": "New Channel ID", | ||
"uaid": "UserAgent ID" | "uaid": "UserAgent ID" | ||
| Line 135: | Line 135: | ||
NOTE: The uaid is either the X-UserAgent-ID value echoed back, or a new X-UserAgent-ID value to be used for all subsequent calls if no X-UserAgent-ID was present. | NOTE: The uaid is either the X-UserAgent-ID value echoed back, or a new X-UserAgent-ID value to be used for all subsequent calls if no X-UserAgent-ID was present. | ||
==== Example ==== | ===== Example ===== | ||
GET http://push.m.o/register | GET http://push.m.o/register | ||
--- | --- | ||
{"channelID": "foo1234", "uaid": "bar5678"} | {"channelID": "foo1234", "uaid": "bar5678"} | ||
=== DELETE /<ChannelID> === | ==== DELETE /<ChannelID> ==== | ||
Delete an associated ChannelID. Subsequent calls to this ChannelID will result in a 404 status. | Delete an associated ChannelID. Subsequent calls to this ChannelID will result in a 404 status. | ||
NOTE: the X-UserAgent-ID Header must be present and match the one associated with this ChannelID | NOTE: the X-UserAgent-ID Header must be present and match the one associated with this ChannelID | ||
==== Arguments ==== | ===== Arguments ===== | ||
There are no arguments for this call. | There are no arguments for this call. | ||
==== Returns ==== | ===== Returns ===== | ||
This returns an empty JSON object | This returns an empty JSON object | ||
{} | {} | ||
==== Example ==== | ===== Example ===== | ||
DELETE http://push.m.o/delete/foo1234 | DELETE http://push.m.o/delete/foo1234 | ||
--- | --- | ||
{} | {} | ||
=== GET /update === | ==== GET /update ==== | ||
Return a list of known ChannelIDs and current versions. | Return a list of known ChannelIDs and current versions. | ||
NOTE: the X-UserAgent-ID must be provided and match the value returned by the <code>/register</code> call. | NOTE: the X-UserAgent-ID must be provided and match the value returned by the <code>/register</code> call. | ||
==== Arguments ==== | ===== Arguments ===== | ||
There are no arguments for this call. | There are no arguments for this call. | ||
==== Returns ==== | ===== Returns ===== | ||
This will return a hash containing a list of hashes defining the known, associated Channels and versions. | This will return a hash containing a list of hashes defining the known, associated Channels and versions. | ||
NOTE: If the server is unable to determine previous data for this X-UserAgent-ID, it will return a 410. | NOTE: If the server is unable to determine previous data for this X-UserAgent-ID, it will return a 410. | ||
See <code>POST /update</code> for details. | See <code>POST /update</code> for details. | ||
==== Example ==== | ===== Example ===== | ||
GET http://push.m.o/update | GET http://push.m.o/update | ||
| Line 176: | Line 176: | ||
{"channels":[{"foo1234","1.2"},{"gorp789","20121210164802-a"}]} | {"channels":[{"foo1234","1.2"},{"gorp789","20121210164802-a"}]} | ||
=== POST http://push.m.o/update === | ==== POST http://push.m.o/update ==== | ||
Refresh the server from the client. | Refresh the server from the client. | ||
| Line 182: | Line 182: | ||
This request requires a X-UserAgent-ID header. If the UserAgent attempts to POST information to the server which already has data for that X-UserAgent-ID, the server will deny the request with a 403 error. In that case, the UserAgent should request re-registration for all Channels. | This request requires a X-UserAgent-ID header. If the UserAgent attempts to POST information to the server which already has data for that X-UserAgent-ID, the server will deny the request with a 403 error. In that case, the UserAgent should request re-registration for all Channels. | ||
==== Arguments ==== | ===== Arguments ===== | ||
The POST body is a JSON encoded block which matches the form and structure of the GET /update/ request. | The POST body is a JSON encoded block which matches the form and structure of the GET /update/ request. | ||
==== Returns ==== | ===== Returns ===== | ||
This will return an empty object. | This will return an empty object. | ||
==== Example ==== | ===== Example ===== | ||
POST http://push.m.o/update | POST http://push.m.o/update | ||
| Line 195: | Line 195: | ||
{} | {} | ||
=== PUT http://push.m.o/update/<ChannelID> === | ==== PUT http://push.m.o/update/<ChannelID> ==== | ||
Update the version of a given channel. | Update the version of a given channel. | ||
| Line 202: | Line 202: | ||
This call does not require a X-UserAgent-ID, as it may be called by the AppServer. | This call does not require a X-UserAgent-ID, as it may be called by the AppServer. | ||
==== Arguments ==== | ===== Arguments ===== | ||
version=<version> | version=<version> | ||
| Line 210: | Line 210: | ||
* The ID should be UTF8 compliant. | * The ID should be UTF8 compliant. | ||
==== Returns ==== | ===== Returns ===== | ||
This call returns an empty JSON object. | This call returns an empty JSON object. | ||
==== Example ==== | ===== Example ===== | ||
PUT http://push.m.o/update/foo1234 | PUT http://push.m.o/update/foo1234 | ||
version=1.3 | version=1.3 | ||
--- | --- | ||
{} | {} | ||