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

Notifications

Jump to bottom
Paddy Foran edited this page Aug 18, 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.
    • 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

Status Code Field Explanation
400 ERROR_MISSING_PARAM username Username was not specified in the URL.
400 ERROR_INVALID_FORMAT after after param was set to a non-integer value.
400 ERROR_INVALID_FORMAT before before param was set to a non-integer value.
400 ERROR_INVALID_FORMAT count count param was set to a non-integer value.
400 ERROR_TOO_SHORT count count param was set to a value less than 1.
400 ERROR_TOO_LONG count count param was set to a value greater than 100.
403 ERROR_ACCESS_DENIED Authenticating user does not have access to the specified user's notifications.
404 ERROR_NOT_FOUND user Specified user not found.
500 ERROR_ACT_OF_GOD Internal server error.
400 ERROR_INVALID_FORMAT device Device param was set to a non-integer value.
404 ERROR_NOT_FOUND device Device was not found.
400 ERROR_WRONG_OWNER device 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

Status Code Field Explanation
400 ERROR_MISSING_PARAM username Username was not specified in the URL.
400 ERROR_INVALID_FORMAT after after param was set to a non-integer value.
400 ERROR_INVALID_FORMAT before before param was set to a non-integer value.
400 ERROR_INVALID_FORMAT count count param was set to a non-integer value.
400 ERROR_TOO_SHORT count count param was set to a value less than 1.
400 ERROR_TOO_LONG count count param was set to a value greater than 100.
403 ERROR_ACCESS_DENIED Authenticating user does not have access to the specified user's notifications.
404 ERROR_NOT_FOUND user Specified user not found.
500 ERROR_ACT_OF_GOD Internal server error.

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

Status Code Field Explanation
400 ERROR_MISSING_PARAM username Username was not specified in the URL.
403 ERROR_ACCESS_DENIED Authenticating user does not have access to the specified user's notifications.
404 ERROR_NOT_FOUND user Specified user not found.
500 ERROR_ACT_OF_GOD Internal server error.
400 ERROR_MISSING_PARAM id Notification ID was not specified in URL.
400 ERROR_INVALID_FORMAT id Specified notification ID was not an unsigned integer.
404 ERROR_NOT_FOUND id Specified notification was not found.
400 ERROR_WRONG_OWNER id Specified notification does not belong to specified user.
404 ERROR_NOT_FOUND device The device that owns the notification was not found.
400 ERROR_WRONG_OWNER device The device that owns the specified notification does not belong to the specified user.

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

Status Code Field Explanation
403 ERROR_ACCESS_DENIED Authenticating user does not have permission to send notifications.
400 ERROR_BAD_REQUEST_FORMAT Request body is not valid JSON.
500 ERROR_ACT_OF_GOD Internal server error.
400 ERROR_MISSING_PARAM notification.nature The nature of the notification was not specified.
400 ERROR_MISSING_PARAM notification.body The body of the notification was not specified.
404 ERROR_NOT_FOUND user The specified user was not found.
400 ERROR_INVALID_FORMAT device The specified device ID was not an unsigned integer.
404 ERROR_NOT_FOUND device The specified device was not found.
400 ERROR_WRONG_OWNER device The specified device does not belong to the specified user.
400 ERROR_INVALID_VALUE The specified broadcast filter was not valid.

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

Status Code Field Explanation
400 ERROR_MISSING_PARAM username Username was not specified in the URL.
403 ERROR_ACCESS_DENIED Authenticating user does not have access to the specified user's notifications.
404 ERROR_NOT_FOUND user The specified user was not found.
500 ERROR_ACT_OF_GOD Internal server error.
400 ERROR_MISSING_PARAM id The notification's ID was not specified in the URL.
400 ERROR_INVALID_FORMAT id The specified notification ID was not an unsigned integer.
404 ERROR_NOT_FOUND id The specified notification was not found.
400 ERROR_WRONG_OWNER id The specified notification does not belong to the specified user.
404 ERROR_NOT_FOUND device The device that owns the specified notification was not found.
400 ERROR_BAD_REQUEST_FORMAT Request body is not valid JSON.
400 ERROR_MISSING_PARAM notification No notification was included in the request body.
400 ERROR_MISSING_PARAM notification.unread The unread property of the notification was not specified.
400 ERROR_INVALID_VALUE notification.unread The unread property of the notification was set to true.

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

Status Code Field Explanation
400 ERROR_MISSING_PARAM username Username was not specified in the URL.
403 ERROR_ACCESS_DENIED Authenticating user does not have access to the specified user's notifications.
404 ERROR_NOT_FOUND user Specified user not found.
500 ERROR_ACT_OF_GOD Internal server error.
400 ERROR_MISSING_PARAM id Notification ID was not specified in URL.
400 ERROR_INVALID_FORMAT id Specified notification ID was not an unsigned integer.
404 ERROR_NOT_FOUND id Specified notification was not found.
400 ERROR_WRONG_OWNER id Specified notification does not belong to specified user.
404 ERROR_NOT_FOUND device The device that owns the notification was not found.
Clone this wiki locally