WebAPI/SimplePush/ServerAPI

From MozillaWiki
Jump to: navigation, search

Server API










THIS API IS OBSOLETE. Please look at SimplePush/Protocol










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. GET http:host/foonet/update 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 X-UserAgent-ID 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 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 304 Not Modified error.

If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT

NOTE: The UserAgent should not modify its own lastModified 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 If-Modified-Since 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 <pushEndpoint>

Update the version of a given channel. pushEndpoint is the endpoint URL that was returned by the server on registration.

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

  1. Send a list of <channelID, pushEndpoint, version> pairs capturing its current state to PushServer, along with the UAID.
  2. 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:

{
  "channels": [{"channelID": "channelID1", 
                "pushEndpoint": "...", 
                "version": "version1"}, 
               {"channelID": "channelID2", 
                "pushEndpoint": "...", 
                "version": "version2"}, 
               ...]
}

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 push-register

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.

Future Notes

Things to consider for future versions: http://en.wikipedia.org/wiki/Stream_Control_Transmission_Protocol