Skip to content
This repository was archived by the owner on Feb 24, 2020. It is now read-only.

Notifications

Jump to bottom
Paddy Foran edited this page Mar 12, 2013 · 6 revisions

Notifications describe a message from the server to a User or Device. They have their own metadata attached, and are used to communicate messages that prompt an automated behaviour from the client or that should be displayed to the end user.

The Notification Resource

The Notification resource is represented in responses under the notifications property. The notifications property will be an array of Notifications.

Notifications appear as follows:

{
  "id": uint64,
  "nature": string,
  "body": string,
  "unread": bool,
  "read_by": string,
  "time_read": datetime,
  "sent": datetime
}

Mutable Properties

Mutable properties are properties that can be modified through interactions with the API.

  • nature: The purpose of this Notification. The following natures are valid:
    • downtime: the server is entering planned downtime, and requests should be cached until the server sends an online Notification.
    • online: the server has resumed its normal functioning after a period of downtime, planned or unplanned. Queued requests should be reattempted now.
    • subscription_warning: The User's subscription has expired and needs user interaction to avoid service disruption.
    • subscription_expired: The User's subscription has left the grace period, and the User will no longer be able to use the service.
    • update_available: An update to the Device's client has been released, and the Device should prompt the user to update.
    • message: The Notification's body should be displayed to the user. This will be used by server administrators to communicate with users.
  • body: A string that may contain more details about the Notification; its most often use is to convey the message that should be displayed to the user.
  • unread: True if the Notification has not been marked as read by the receiving Device or User yet, False or omitted if the Notification has been marked as read by the receiving Device or User.

Immutable Properties

Immutable properties are properties that are created and modified only by the system; there is no way to modify them through the API.

  • id: A unique, immutable identifier for this Notification.
  • read_by: If unread is False or omitted, this will contain the ID of the device that marked it as read.
  • time_read: The date and time the Notification was marked as read by the receiving Device, expressed according to RFC 3339.
  • sent: The date and time the Notification was first sent, expressed according to RFC 3339.

Listing Notifications By Device

If the User authenticating the request owns the Device whose Notifications are being listed, this request only requires authentication. If the User authenticating the request does not own the Device whose Notifications are being listed, this request requires administrative authentication.

Request Format

Endpoint

GET /users/{username}/devices/{id}/notifications

Optional Parameters

The following URL parameters are accepted when listing Notifications, and will filter the list accordingly:

  • after: the ID of a Notification. Only Notifications sent after that Notification will be returned.
  • before: the ID of a Notification. Only Notifications sent before that Notification will be returned.
  • count: the maximum number of Notifications to return, as an integer. Defaults to 20, with a maximum of 100.

Response Format

Header

This request sets the Last-Modified header to the latest sent or time_read property of the Notifications returned, whichever is greater.

The Content-Type of this request will be notifications/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be notifications/json.

Body

This request returns a list of Notification resources as a JSON array:

{
  "code": 200,
  "msg": "Successfully retrieved a list of notifications",
  "notifications": [
    {
      // See the Notification Resource for the contents of this part
    },
    {
      // See the Notification Resource for the contents of this part
    }
  ]
}

In the event no notifications are to be returned, an empty array will be returned.

Errors

  • Username not specified
  • User not found
  • After not a valid ID
  • Before not a valid ID
  • Count not an integer
  • User does not have access to specified user's notifications
  • Device ID not valid
  • Device not found
  • Specified device does not belong to specified user

Listing Notifications By User

If the User authenticating the request is the User whose Notifications are being listed, this request only requires authentication. If the User authenticating the request is not the User whose Notifications are being listed, this request requires administrative authentication.

Request Format

Endpoint

GET /users/{username}/notifications

Optional Parameters

The following URL parameters are accepted when listing Users, and will filter the list accordingly:

  • after: the ID of a Notification. Only Notifications sent after that Notification will be returned.
  • before: the ID of a Notification. Only Notifications sent before that Notification will be returned.
  • count: the maximum number of Notifications to return, as an integer. Defaults to 20, with a maximum of 100.

Response Format

Header

This request sets the Last-Modified header to the latest sent or time_read property of the Notifications returned, whichever is greater.

The Content-Type of this request will be notifications/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be notifications/json.

Body

This request returns a list of Notification resources as a JSON array:

{
  "code": 200,
  "msg": "Successfully retrieved a list of notifications",
  "notifications": [
    {
      // See the Notification Resource for the contents of this part
    },
    {
      // See the Notification Resource for the contents of this part
    }
  ]
}

In the event no notifications are to be returned, an empty array will be returned.

Errors

  • Username not specified
  • User not found
  • After not a valid ID
  • Before not a valid ID
  • Count not an integer
  • User does not have access to specified user's notifications

Getting Information About A Notification

This request requires only authentication if it is run against a Notification that belongs to the authenticating User. If it is run against another User's Notification, it requires administrative credentials.

Request Format

Endpoint

GET /users/{username}/notifications/{id}

Response Format

Header

This request sets the Last-Modified header to the sent property of the Notification returned, or the time_read property of the Notification returned, if it is set.

The Content-Type of this request will be notifications/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be notifications/json.

Body

This request returns a list of Notification resources as a JSON array. The array will only have one item:

{
  "code": 200,
  "msg": "Successfully retrieved notification information",
  "notifications": [
    {
      // See the Notification Resource for the contents of this part
    }
  ]
}

Errors

  • Username not specified
  • User not found
  • User does not have access to specified user's notifications
  • Notification ID not specified
  • Notification ID not valid
  • Notification not found
  • Notification does not belong to specified user
  • Device notification belongs to not found

Creating New Notifications

This request requires administrative credentials.

Request Format

Endpoint

POST /users/{username}/devices/{id}/notifications
POST /users/{username}/notifications
POST /notifications

The first endpoint is to create a Notification for a specific Device. The second endpoint is to create a Notification for a specific User. The third endpoint is to broadcast a Notification to all Users or Devices, depending on the filtering options used in the request.

Request Body

The request body should be a JSON array of Notification Resources and a set of broadcast filters. Only the Mutable Properties will be used; the rest will be ignored.

Broadcast filters are just a JSON object with the following properties:

  • targets: either users or devices. Notifications will only be created for Users or their Devices. Notifications for Users will be considered "read" once a single Device marks them as read. Notifications for Devices will each have their own "read" state.
  • client_type: an array of the types of Devices that should receive the Notification, when target is set to devices. Can be android_phone, android_tablet, website, or chrome_extension. This list will grow to match its match in the Devices spec.

A sample request body:

{
	"notifications": [
		{
			"nature": "update_available"
			"body": "An update to the Android client has been released. Please update."
		}
	],
	"broadcast_filter": {
		"targets": "devices",
		"client_type": ["android_phone", "android_tablet"]
	}
}

Response Format

The request responds with the Notifications that were sent.

Header

This request sets the Last-Modified header to the latest sent property of the Notifications returned.

The Content-Type of this request will be notifications/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be notifications/json.

Body

This request returns a list of Notification resources as a JSON array. The array will be contain the Notifications that were created:

{
  "code": 201,
  "msg": "Successfully created notifications",
  "notifications": [
    {
      // See the Notification Resource for the contents of this part
    }
  ]
}

Errors

  • User not authorised to send notifications
  • Badly-formed JSON
  • Nature not specified
  • Body not specified
  • Device ID invalid
  • User does not have access to specified device's notifications
  • Specified device not found
  • User does not have access to specified user's notifications
  • Specified user not found
  • Invalid broadcast filter

Marking A Notification Read

This request requires only authentication if it belongs to the authenticating User. If it is run against another User's Notification, it requires administrative credentials.

Request Format

Endpoint

PUT /users/{username}/notifications/{id}

Request Headers

Because this request has a body, the Content-Type, and Content-Length headers need to be set.

Request Body

The request body should be a Notification Resource. Only the Mutable Properties will be used; the rest will be ignored. Furthermore, the url.address property will be ignored in this request.

A sample request body:

{
  "notification": {
    "unread": false
  }
}

Response Format

Header

This request sets the Last-Modified header to the time_read property of the Notification returned.

The Content-Type of this request will be notifications/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be notifications/json.

Body

This request returns a list of Notification resources as a JSON array. The array will only have one item—the Notification that was modified:

{
  "code": 200,
  "msg": "Successfully updated the notification",
  "notifications": [
    {
      // See the Notification Resource for the contents of this part
    }
  ]
}

Errors

  • Username not specified
  • User doesn't have access to specified user's notifications
  • Specified user not found
  • Notification ID not specified
  • Notification ID not valid
  • Notification not found
  • Specified notification doesn't belong to specified user
  • Device that owns the notification not found
  • Badly-formed JSON
  • Notification data not supplied
  • Notification's unread state can't be true or unset

Deleting A Notification

This request requires only authentication if it is run against a Notification that belongs to the authenticating User. If it is run against another User's Notification, it requires administrative credentials.

Request Format

Endpoint

DELETE /users/{username}/notifications/{id}

Response Format

Header

This request sets the Last-Modified header to the sent property of the Notification returned or (if it is set) the time_read property of the Notification returned.

The Content-Type of this request will be notifications/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be notifications/json.

Body

This request returns a list of Notification resources as a JSON array. The array will only have one item—the Notification that was just deleted:

{
  "code": 200,
  "msg": "Successfully deleted the notification",
  "notifications": [
    {
      // See the Notification Resource for the contents of this part
    }
  ]
}

Errors

  • Username not specified
  • User does not have access to specified user's notifications
  • Specified user not found
  • Notification ID not specified
  • Notification ID not valid
  • Notification not found
  • Specified notification does not belong to specified user
  • Device that owns the notification not found

Clone this wiki locally