WebAPI/SimplePush: Difference between revisions

WebAPI/SimplePush (view source)

Revision as of 01:16, 11 December 2012

1,072 bytes added , 11 December 2012

→‎Server API

Jrconlin

Confirmed users

1,021

edits

@@ Line 90: / Line 90: @@
 == Server API ==
-We will use a RESTful API to interact with the Push Server.
+=== Definitions ===
+;UserAgent
+:The client acting on behalf of the user and consumer of update notices
-The Push Server URL is returned to the client as a result of calling register().  The <i>pushEndpoint</i> is the URL to the Push Server.
+;UAID
+:A server generated, globally unique UserAgent ID
-Each request shall include a User Agent ID, which is a unique ID for a User Agent and sent with each request via a "<b>X-UserAgent-ID</b>" header.
+;PushServer
+:The server managing interactions between AppServers and the UserAgent
-Successful calls will return HTTP Status 200 with new content or 204 with no update change
+;AppServer
+:The third party publisher of update notices
-Unless otherwise noted the following HTTP error codes:
+;Channel
-:401
+:The flow of information from AppServer through PushServer to UserAgent
-Authorization failure
-:404
+;ChannelID
-pushRequestID not found
+:Globally Unique identifier for a Channel
-:500
+UserAgent and AppServer will use a RESTful API to interact with the Push Server.
-Server error.
-=== Registering with Push Server ===
+== API ==
+* 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.
+* 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.
-GET <i>pushEndpoint</i>/register/[<network>]
+=== POST /register ===
+Request a new ChannelID.
-These query parameters are optional with each registration:
+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.
-* Network Association
+==== Arguments ====
-** <i>network</i>
-** This may be a identification string that represents where the the client can also be reached at.
-** We need some way to say this client can be notified on another network (via UDP instead of a long poll)
-** For example network = "foonet"
-Example:
+No additional arguments are required.
-<pre>
-  // if registering on "foonet"
-  POST http://push.mozilla.org/register/foonet
-</pre>
-or
-<pre>
-  // if registering without a network
-  POST http://push.mozilla.org/register
-</pre>
-Note: Other examples operate the same way with respect to the inclusion of the "network" element.
-If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:
+==== Return Value ====
+ { "channelID": "New Channel ID",
+   "uaid": "UserAgent ID"
+ }
-<pre>
+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.
-// tbd
-{
-  "result": { "id": <pushRequestID> }
-}
-</pre>
-=== Un-registering with Push Server ===
+==== Example ====
+ GET http://push.m.o/register
+ ---
+ {"channelID": "foo1234", "uaid": "bar5678"}
-DELETE <i>pushEndpoint</i>/register/[<network>/]<pushRequestID>
+=== DELETE /<ChannelID> ===
+Delete an associated ChannelID. Subsequent calls to this ChannelID will result in a 404 status.
-* pushRequestID
+NOTE: the X-UserAgent-ID Header must be present and match the one associated with this ChannelID
-** The value of pushRequestID must be the result returned to the client as a result of calling register().
-Example:
+==== Arguments ====
-<pre>
+There are no arguments for this call.
-  DELETE http://push.mozilla.org/register/foonet/<pushRequestID>
-</pre>
-If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:
+==== Returns ====
-<pre>
+This returns an empty JSON object
-// tbd
+ {}
-{
+==== Example ====
-  "result": {}
+ DELETE http://push.m.o/delete/foo1234
-}
+ ---
-</pre>
+ {}
-=== Client check for updates ===
+=== GET /update ===
+Return a list of known ChannelIDs and current versions.
-GET <i>pushEndpoint</i>/update/[<network>/]<pushRequestID>?version=<lastPulledVersion>
+NOTE: the X-UserAgent-ID must be provided and match the value returned by the <code>/register</code> call.
-* pushRequestID
+==== Arguments ====
-** The value of pushRequestID must be the result returned to the client as a result of calling register().
+There are no arguments for this call.
-* network
+==== Returns ====
-** Optional network specifier.
+This will return a hash containing a list of hashes defining the known, associated Channels and versions.
-Example:
+NOTE: If the server is unable to determine previous data for this X-UserAgent-ID, it will return a 410.
-<pre>GET <i>pushEndpoint</i>/update/foonet/<pushRequestID>?version=12345</pre>
+See <code>POST /update</code> for details.
+==== Example ====
-Returns:
+ GET http://push.m.o/update
+ ---
+ {"channels":[{"foo1234","1.2"},{"gorp789","20121210164802-a"}]}
-:200 Success
+=== POST http://push.m.o/update ===
-<pre>{
-   "result": {"update": <newVersionNumber>}
-}</pre>
-:204 Success (No content, no change in version.)
+Refresh the server from the client.
-<pre>{
-   "result": {}
-}</pre>
-=== Notify Push Server of a new version ===
+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.
-PUT <i>pushEndpoint</i>/update/<network>/<pushRequestID>?version=<version>
+==== Arguments ====
+The POST body is a JSON encoded block which matches the form and structure of the GET /update/ request.
-These query parameters are required with each update:
+==== Returns ====
+This will return an empty object.
-* pushRequestID
+==== Example ====
-** The value of pushRequestID must be the result returned to the client as a result of calling register().
-* Version
-** <i>version</i> is the query parameter name.
-** The value of version is the most current version number of the object referenced by pushRequestID
-Example:
+ POST http://push.m.o/update
-<pre>
+ {"channels":[{"foo1234","1.2"},{"gorp789","20121210164802-a"}]}
-  PUT http://push.mozilla.org/update/<pushRequestID>?version=<version>
+ ---
-</pre>
+ {}
-If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:
+=== PUT http://push.m.o/update/<ChannelID> ===
-<pre>
-{
+Update the version of a given channel.
-  "result": {}
-}
+Arguments should be passed as standard form data (enctype: multipart/form-data)
-</pre>
+This call does not require a X-UserAgent-ID, as it may be called by the AppServer.
+==== 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.
+==== Returns ====
+This call returns an empty JSON object.
+==== Example ====
+ PUT http://push.m.o/update/foo1234
+ version=1.3
+ ---
+ {}