WebAPI/SimplePush: Difference between revisions

Jump to navigation Jump to search

WebAPI/SimplePush (view source)

Revision as of 01:04, 31 January 2013

9,452 bytes removed ,  31 January 2013
no edit summary
No edit summary
Line 162: Line 162:


Where <i>endpoint</i> is the value that was returned during App's registration.
Where <i>endpoint</i> is the value that was returned during App's registration.
=== Notes ===
* 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'''
* Calls will return standard HTTP status headers.
* Calls will return status 200 (unless otherwise noted below).
* 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> ====
Request a new endpoint.
If the <i>X-UserAgent-ID</i> is not provided, the UserAgent is presumed to be new and a new UAID will be generated for the UserAgent.
The PushServer '''SHOULD''':
* Ensure that the channelID is compliant with any formatting requirements the PushServer may have
* Ensure that the channelID is unique for the UAID.
===== Arguments =====
No additional arguments are required.
===== Success response =====
{ "channelID": "<channelID provided by UA>",
  "pushEndpoint": "http://pushserver.provider.tld/path/to/notify"
  "uaid": "UserAgent ID" (optional)
}
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.
pushEndpoint may incorporate channelID to simplify implementation and reduce state storage at server.
===== Errors =====
* 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.
* 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 =====
GET http://push.services.mozilla.org/v1/register/foo1234
---
{"channelID": "foo1234",
  "pushEndpoint": "http://push5.services.mozilla.org/v1/update/foo1234",
  "uaid": "bar5678"}
=== Unregistration ===
==== DELETE /v1/<ChannelID> ====
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
===== Arguments =====
There are no arguments for this call.
===== Success response =====
Empty JSON object
{}
===== Errors =====
* 403 - Wrong or missing UAID
* 410 - Server is in recovery mode. Start Registration Sync Protocol. See Server Recovery Mode.
===== Example =====
DELETE http://push.m.o/v1/foo1234
---
{}
=== Fetch updates ===
==== 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.
A client may provide a "If-Modified-Since" header (as specified in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html RFC2616]), in which case the server will only return channel IDs that have been modified since the specified time. If no channels have been modified, the server will return a <code>304 Not Modified</code> error.
If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
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 =====
There are no arguments for this call.
===== Success response =====
* 200 - The server should return an object with the following fields:
  {    // An association of ChannelIDs and versions that have changed
      // since the last time the UA called /update/.
    "updates": [{"channelID": "id",
                "version": "XXX"}, ...],
 
      // A list of ChannelIDs which have expired. The UA should remove
      // these from its own database, and ask applications to re-register.
    "expired": ["channelID1", "channelID2", ...]  }
* 304 - No modifications since time specified in <tt>If-Modified-Since</tt> header.
===== Errors =====
* 403 - Wrong or missing UAID
* 410 - Server is in recovery mode. Start Registration Sync Protocol. See Server Recovery Mode.
===== Example =====
GET http://push.m.o/v1/update/
---
{"updates": [{"channelID":"1ced595d7f6c9f60cc5c9395dc6b72aa7e1a69a7","version":"42"},
              {"channelID":"bf08e25861c900c3ab343670eee1873d0b724eef","version":"1"}],
  "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 ====
Refresh the server from the client. This request REQUIRES a X-UserAgent-ID header.
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.
The UserAgent '''SHOULD'''
# 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.
===== Arguments =====
The POST body is a JSON encoded block:
<pre>
{
  "channels": [{"channelID": "channelID1",
                "pushEndpoint": "...",
                "version": "version1"},
              {"channelID": "channelID2",
                "pushEndpoint": "...",
                "version": "version2"},
              ...]
}
</pre>
===== Success response =====
{}
===== Errors =====
* 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 =====
POST http://push.m.o/v1/update
{"channels":[{"channelID":"1ced595d7f6c9f60cc5c9395dc6b72aa7e1a69a7",
              "version":"42"},
              {"channelID":"bf08e25861c900c3ab343670eee1873d0b724eef",
              "version":"1"}]}
---
{}
=== Server recovery mode ===
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)
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.
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.
=Flow Diagram=
[[Image:SimplePushFlow.png|Simple Push flow]]
Jrconlin
Confirmed users
1,021

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/509487"

Navigation menu