WebAPI/SimplePush: Difference between revisions

Jump to navigation Jump to search

WebAPI/SimplePush (view source)

Revision as of 19:14, 23 January 2013

1,467 bytes added ,  23 January 2013
→‎Clarifications and cleanup
Line 1: Line 1:
<h2> Client Side API </h2>
== Client Side API ==
<pre>
<pre>


Line 137: Line 137:
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 ===
=== Notes ===
* 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 (e.g. <code>GET http:<i>host</i>/foonet/update</code> will return update requests for elements provided by the "foonet" sub-provider. '''TODO: The semantics of this are woefully lacking in the current state of the protocol'''
* UserAgent requests may include a /{network} prefix to indicate a request may be handled by a third party network (e.g. <code>GET http:<i>host</i>/foonet/update</code> will return update requests for elements provided by the "foonet" sub-provider. '''TODO: The semantics of this are woefully lacking in the current state of the protocol'''
Line 144: Line 144:
* 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.


=== Registration ===
==== GET /v1/register/<channelID> ====
==== GET /v1/register/<channelID> ====
Request a new endpoint.  
Request a new endpoint.  
Line 157: Line 158:
No additional arguments are required.
No additional arguments are required.


===== Returns =====
===== Success response =====
 
  { "channelID": "<channelID provided by UA>",  
  { "channelID": "<channelID provided by UA>",  
   "pushEndpoint": "http://pushserver.provider.tld/path/to/notify"
   "pushEndpoint": "http://pushserver.provider.tld/path/to/notify"
Line 169: Line 171:
===== Errors =====
===== Errors =====


* Invalid Channel ID
* 200 and new UAID - If a server is not in recovery mode, but was in recovery mode before, it may return a new uaid that does not match the old UAID. If a UserAgent receives a new UAID, it should treat that as requiring a full Registration Sync step. In addition, it should throw away the pushEndpoint it received from the server.
* Duplicate Channel ID
* 409 - duplicate channelID. UserAgent should generate new ID and try again.
* 410 - Server is in recovery mode. Start Registration Sync Protocol. See Server Recovery Mode.
 


===== Example =====
===== Example =====
Line 177: Line 181:
  {"channelID": "foo1234", "pushEndpoint": "http://push5.services.mozilla.org/v1/update/foo1234", "uaid": "bar5678"}
  {"channelID": "foo1234", "pushEndpoint": "http://push5.services.mozilla.org/v1/update/foo1234", "uaid": "bar5678"}


=== Unregistration ===
==== DELETE /v1/<ChannelID> ====
==== DELETE /v1/<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.
Line 185: Line 190:
There are no arguments for this call.
There are no arguments for this call.


===== Returns =====
===== Success response =====


On success, this returns an empty JSON object
Empty JSON object
  {}
  {}


===== Errors =====
===== Errors =====


* Not Registered
* 403 - Wrong or missing UAID
* Invalid UAID
* 410 - Server is in recovery mode. Start Registration Sync Protocol. See Server Recovery Mode.


===== Example =====
===== Example =====
Line 200: Line 205:
  {}
  {}


=== Fetch updates ===
==== GET /v1/update ====
==== GET /v1/update ====
Return a list of known ChannelIDs and current versions. By default, this will return a list of ALL channels and known versions.  
Return a list of known ChannelIDs and current versions. By default, this will return a list of ALL channels and known versions.  
Line 207: Line 213:
  If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
  If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT


NOTE: the X-UserAgent-ID must be provided and match the value returned by the <code>/register</code> call.
NOTE: The UserAgent should not modify its own <tt>lastModified</tt> field until a successful response is received, otherwise reliable delivery of updates will fail.


===== Arguments =====
===== Arguments =====
There are no arguments for this call.
There are no arguments for this call.


===== Returns =====
===== Success response =====
The server should return an object with the following fields:
* 200 - The server should return an object with the following fields:
 
  { "updates": [{"channelID": "id", "version": "XXX"}, ...], An association of ChannelIDs and versions that have changed since the last time the UA called /update.
    "expired": ["channelID1", "channelID2", ...], A list of ChannelIDs which have expired. The UA should remove these from its own database, and ask applications to re-register.
  }


* <tt>updates</tt> - An association of ChannelIDs and versions that have changed since the last time the UA called /update.
* 304 - No modifications since time specified in <tt>If-Modified-Since</tt> header.
* <tt>expired</tt> - A list of ChannelIDs which have expired. The UA should remove these from its own database, and ask applications to re-register.


'''TODO''' We need acknowledgement of the /update from the UA. It is possible for the response to be lost in flight and we're trying for reliable delivery.
===== Errors =====


NOTE: If the server is unable to determine previous data for this X-UserAgent-ID, it will return a 410 leading to the Registration Sync Protocol occurring.  
* 403 - Wrong or missing UAID
See <code>POST /update</code> for details.
* 410 - Server is in recovery mode. Start Registration Sync Protocol. See Server Recovery Mode.


===== Example =====
===== Example =====
Line 230: Line 239:
               {"channelID":"bf08e25861c900c3ab343670eee1873d0b724eef","version":"1"}],
               {"channelID":"bf08e25861c900c3ab343670eee1873d0b724eef","version":"1"}],
   "expired": ["channelID1", "channelID2", ...]}
   "expired": ["channelID1", "channelID2", ...]}
=== Notify update ===
Used by App Servers '''ONLY'''. NOT to be used by UserAgents.
==== PUT /v1/update/<ChannelID> ====
Update the version of a given channel.
Arguments should be passed as standard form data (enctype: multipart/form-data)
This call does not require a X-UserAgent-ID.
===== Arguments  =====
version=<version>
The version is the AppServer specific VersionID to use. This ID is opaque to the PushServer, however it is suggested that:
* The ID be sequential.
* The ID be less than 100 characters.
* The ID should be UTF8 compliant.
===== Success response =====
This call returns an empty JSON object.
  {}
===== Errors =====
* 403 - Not authorized. May occur when the app server has been blocked because it is exhibiting suspicious behaviour. App developer should contact the push server administrator for details.
* 404 - No such push endpoint exists anymore. App Server's should remove the endpoint from their database. This can occur because the app unregistered itself, it was uninstalled, or for other reasons.
* 503 - In the event of a PushServer catastrophe, the PushServer will be in "Recovery" mode. During this time, unresolvable push endpoints will return a 503 error. App Server's SHOULD NOT consider the push endpoint as being deleted. They should continue to notify the Push Server of changes.
===== Example =====
PUT http://push.m.o/v1/update/foo1234
version=1.3
---
{}
=== Registration Sync Protocol ===
The Registration Sync Protocol is used by UserAgents to inform the Push Server of their current state in the unlikely event of a server failure. A registration sync step can only occur when the Push Server is in "recovery mode".


==== POST /v1/update ====
==== POST /v1/update ====
====== Registration Sync Protocol ======
Refresh the server from the client. This request REQUIRES a X-UserAgent-ID header.  
Refresh the server from the client. This request REQUIRES a X-UserAgent-ID header.  


This call SHOULD only be performed by the UA after a 410 response from GET /v1/update. This call presumes the PushServer is in "recovery" mode after a serious failure where data is unavailable. (e.g. after a node crash or other unexpected activity).
This call SHOULD only be performed by the UA after it receives a 410 response. This call presumes the PushServer is in "recovery mode" after a serious failure where data is unavailable. (e.g. after a node crash or other unexpected activity).


If the UserAgent attempts to POST information to the server which already has data for that X-UserAgent-ID, or the PushServer is no longer in "recovery" mode, the server will deny the request with a 403 error. In that case, the UserAgent should request re-registration for all Channels.  
If the UserAgent attempts to POST information to the server which already has data for that X-UserAgent-ID, or the PushServer is no longer in "recovery" mode, the server will deny the request with a 403 error. In that case, the UserAgent should request re-registration for all Channels.  
Line 242: Line 290:
# Send a list of <channelID, pushEndpoint, version> pairs capturing its current state to PushServer, along with the UAID.
# Send a list of <channelID, pushEndpoint, version> pairs capturing its current state to PushServer, along with the UAID.
# If the PushServer accepts the request, it replaces its records for the UAID with information from the client and begins accepting PUT /update/<ChannelID> requests from the AppServers.
# If the PushServer accepts the request, it replaces its records for the UAID with information from the client and begins accepting PUT /update/<ChannelID> requests from the AppServers.
# If the PushServer detects a duplicate UAID, it SHOULD respond with a 403 error.
# In this case, the client should invalidate its current state and ask apps application to re-register using the <tt>push-register</tt> system message. UserAgent and PushServer will now organically sync similar to standard /register calls.


===== Arguments =====
===== Arguments =====
Line 253: Line 299:
</pre>
</pre>


===== Returns =====
===== Success response =====
  {}
  {}
===== Errors =====
===== Errors =====


* 403 - The server may response with this for any reason, although usually it'll be due to duplicate UAID.
* 403 - The server may response with this for any reason, although usually it'll be due to duplicate UAID. The UserAgent should invalidate its current state and ask apps to re-register using <tt>push-register</tt>


===== Example =====
===== Example =====
Line 268: Line 315:
</pre>
</pre>


==== PUT /v1/update/<ChannelID> ====


Update the version of a given channel.
==== Server recovery mode ====


Arguments should be passed as standard form data (enctype: multipart/form-data)
When a server suffers data loss it goes into recovery mode. It maintains this recovery mode for a large window of time (1-2 days) to allow a majority of UserAgents to establish contact and rebuild state. In recovery mode the server responds to all requests from UserAgents with a 410 which indicates UserAgent should send state using POST /v1/update (See Registration Sync Protocol)
This call does not require a X-UserAgent-ID, as it may be called by the AppServer.


===== Arguments  =====
Once state is re-established for a given UAID, the server is no longer in "recovery mode" for that UAID and its associated ChannelIDs. So "recovery mode" is a UAID specific setting and not a global variable.
version=<version>


The version is the AppServer specific VersionID to use. This ID is opaque to the PushServer, however it is suggested that:
After the recovery period is up, the server goes back to "normal mode". Now, if a UserAgent (who has a prior UAID) contacts the server, the server is not aware of the UAID and responds with a new UAID. In this case, the UserAgent should invalidate all existing channelIDs and tell all apps to register again using the re-register system message.
* The ID be sequential.
* The ID be less than 100 characters.
* The ID should be UTF8 compliant.
 
===== Returns =====
In the event of a PushServer catastrophe, the PushServer will be in "Recovery" mode. During this time, unresolvable ChannelIDs will return a 503 error.
 
In non-recovery mode, unresolvable pushEndpoints will return a 404.
In this case, the app server should remove the endpoint association
 
A case can occur where the server starts in recovery mode, then after a sufficient period of time switches to non-recovery mode, but a particular UA has still not pinged it (perhaps because the UA does not have Internet access). In this case, application servers may have removed endpoint associations, so the push server needs to inform the UA about which channels were updated, but returned a 404. The UA will then request those apps to re-register.
 
The alternative to this 2 step recovery is to require all pushEndpoints to 404, and on Registration Sync, '''all apps''' are told to register again using 'push-register'.
 
This call returns an empty JSON object.
 
===== Example =====
PUT http://push.m.o/v1/update/foo1234
version=1.3
---
{}


=Flow Diagram=
=Flow Diagram=
[[Image:SimplePushFlow.png|Simple Push flow]]
[[Image:SimplePushFlow.png|Simple Push flow]]
Nikhilm
Confirmed users
93

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/504531"

Navigation menu