view  

The 3taps Data Commons

The Notification API

The 3taps Notification API is responsible for notifying users when certain events occur. These notifications are generated by client systems that send the notification to the Notification API, which then sends the notification on to the user.

Users subscribe to a stream of notifications. These notifications then continue to be sent to the user until either the user unsubscribes or the notifications stop being sent.

Notifications can be sent to the user using different gateways, which are mechanisms for sending out notifications. The two gateways which will be supported initially are Apple Push Notifications, and email.

Subscriptions

When a user requests that they start receiving notifications, the client system must send a subscription request to the Notification API. This request identifies the user who will receive the notifications, and returns a subscription ID uniquely identifying the subscription.

Subscriptions remain active until the user unsubscribes, at which time the subscription is deleted.

Gateways

A gateway identifies the mechism by which the notification should be delivered. There are currently two gateways supported by the 3taps Notification API:

Notifications

A notification is basically a message sent to a user that a certain event has occurred. Each notification consists of the following information:

Using the 3taps Notification API

The Notification API is accessed via the following URL:

http://notification.3taps.com

All calls to the Notification API can be made using either HTTP POST or HTTP GET requests. The following API calls are currently supported:

subscribe

http://notification.3taps.com/subscribe

Create a new subscription to send out set of notifications. This API call takes the following parameter:

user_id (required)

The user ID string for the user who will be receiving the notifications, as returned by a call to the Identity API's identity/get endpoint.

We create a new subscription for the given user.

Upon completion, this API call will return an HTTP status code of 200 (OK), a content-type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error messages are currently supported:

Invalid user ID

The given user ID is not valid.

subscription_id

If the request was successful, this will be a string uniquely identifying the newly-created subscription.

unsubscribe

http://notification.3taps.com/unsubscribe

Remove an existing subscription. This API call takes the following parameter:

subscription_id (required)

The ID of the subscription to remove.

We delete the subscription with the given ID.

Upon completion, this API call will return an HTTP status code of 200 (OK), a content-type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error messages are currently supported:

No such subscription

There is no subscription with that ID.

Note that no additional information is returned when a subscription is deleted.

send

http://notification.3taps.com/send

Send a notification out to a subscribed user. This API call takes the following parameters:

message

The message to be displayed to the user. This message should be brief (one line) for push notifications, but can be much longer (and include HTML formatting codes) for email notifications.

link

The URL to use as the link for this notification. When the user clicks on the notification, the web page at the given URL will be displayed.

subscription_id

The ID of the subscription that we are sending notifications to. This identifies who the notification will go out to.

sender

A string identifying the system which is sending out this notification. Note that this string is used in various ways when sending out the notification, for example as part of the subject line when sending out an email notification.

gateway

A string identifying which gateway to use for sending the message. The following values are currently supported:

email

Send the notification out as an email message.

push

Send the notification out using Apple's Push Notification Service.

Upon completion, this API call will return an HTTP status code of 200 (OK), a content-type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error messages are currently supported:

No such subscription

There is no subscription with that ID.

No such gateway

The supplied gateway value is not known.

Note that notifications are "fire and forget" -- because of the nature of the notification process, there is no guarantee that the user actually received the notification. For example, if the user is not currently running the notifier app on their phone, the user will not receive the notification until the next time they start up the app. For this reason, the Notification API cannot tell the caller if the notification attempt was successful or not.