WebAPI/SimplePush

Client Side API

partial interface Navigator {
  PushNotification pushNotification;
};

interface PushNotification : EventTarget {

  // registers to receive push notifications for a given topic
  // DOMRequest.result is a PushRegistration in case of success
  DOMRequest register(DOMString topic);

  // registers to stop receiving push notifications for a given topic 
  // DOMRequest.result is a PushRegistration in case of success
  DOMRequest unregister(DOMString topic);

  // returns the list of all push registrations for this origin
  PushRegistration[] registered();

  // event MUST be of type PushEvent
  attribute EventHandler onmessage;
};

interface PushRegistration {

  // this is the string that was used when calling register()
  DOMString topic;

  // this is the URL to which push notifications from the web application
  // must be sent to.
  // application should send this and pushRequestID as a pair to the
  // application server
  DOMString pushEndpoint;

  // this is the push request id that must be sent to the push server with
  // every push notification update
  DOMString pushRequestID;

};

interface PushEvent : Event {

  // this is topic string used when registering for push notifications 
  DOMString topic;

  // this is the most current version 
  unsigned long long version;
}

Client Example

// all notifications will be sent to the system message handler.
// which is up to the U/A to implement

// apps can do something like
navigator.pushNotification.onmessage = function(e) {
  e.topic == This is the topic that is being observed
  e.version == This is the current version for this topic
});


// to register to listen for a notification,
// you simply call push.register and pass a
// topic of interest:

var req = navigator.pushNotifications.register("topic");


// success callback
req.onsuccess(e) = function() {
  // post to application server
  e.target.result.pushEndpoint
  e.target.result.pushRequestID
}

req.onerror() = function(e) {}

// to unregister, you simply call..

req = navigator.pushNotifications.unregister("topic");
req.onsuccess() = function() {}
req.onerror() = function() {}

Server API

We will use a RESTful API to interact with the Push Server.

The Push Server URL is returned to the client as a result of calling register(). The pushEndpoint is the URL to the Push Server.

Each request shall include a User Agent ID, which is a unique ID for a User Agent and sent with each request via a "X-UserAgent-ID" header.

Successful calls will return HTTP Status 200 with new content or 204 with no update change

Unless otherwise noted the following HTTP error codes:

401

Authorization failure

404

pushRequestID not found

500

Server error.

Registering with Push Server

GET pushEndpoint/register/[<network>]

These query parameters are optional with each registration:

• Network Association
  • network
  • 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:

  // if registering on "foonet"
  POST http://push.mozilla.org/register/foonet

or

  // if registering without a network
  POST http://push.mozilla.org/register

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:

// tbd
{
  "result": { "id": <pushRequestID> }
}

Un-registering with Push Server

DELETE pushEndpoint/register/[<network>/]<pushRequestID>

• pushRequestID
  • The value of pushRequestID must be the result returned to the client as a result of calling register().

Example:

  DELETE http://push.mozilla.org/register/foonet/<pushRequestID>

If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:

// tbd
{
  "result": {}
}

Client check for updates

GET pushEndpoint/update/[<network>/]<pushRequestID>?version=<lastPulledVersion>

• pushRequestID
  • The value of pushRequestID must be the result returned to the client as a result of calling register().

• network
  • Optional network specifier.

Example:

GET <i>pushEndpoint</i>/update/foonet/<pushRequestID>?version=12345

Returns:

200 Success

{
   "result": {"update": <newVersionNumber>}
}

204 Success (No content, no change in version.)

{
   "result": {}
}

Notify Push Server of a new version

PUT pushEndpoint/update/<network>/<pushRequestID>?version=<version>

These query parameters are required with each update:

• pushRequestID
  • The value of pushRequestID must be the result returned to the client as a result of calling register().
• Version
  • version is the query parameter name.
  • The value of version is the most current version number of the object referenced by pushRequestID

Example:

  PUT http://push.mozilla.org/update/<pushRequestID>?version=<version>

If the request succeeds, the server responds with a 200 OK HTTP status code and the following JSON:

{
  "result": {}
}