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

Devices

Jump to bottom
Paddy Foran edited this page Apr 3, 2013 · 5 revisions

Devices describes a destination for other resources in the system. While Devices are intended to be a one-to-one relationship with physical devices (e.g., a phone or a single browser), there is nothing technically preventing them from being shared by many physical devices, although certain things (push notifications come to mind) may not work.

The Device Resource

The Device resource is represented in responses under the devices property. The devices property will be an array of Devices.

Devices appear as follows:

{
  "id": uint64,
  "name": string,
  "last_seen": datetime,
  "last_ip": string,
  "client_type": string,
  "created": datetime,
  "pushers": {
  	"gcm": {
  		"key": string,
  		"last_used": datetime
  	},
  	"websockets": {
  		"key": string,
  		"last_used": datetime
  	}
  },
  "user_id": uint64
}

Mutable Properties

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

  • name: A memorable, user-chosen identifier. This is not guaranteed to persist over time.
  • client_type: A string identifying the type of the device. Can be android_phone, android_tablet, website, or chrome_extension. This list may grow over time.
  • pushers.gcm.key: The token used to authenticate push notifications to this device using Google Cloud Messaging.
  • pushers.websockets.key: Not used at this time. A unique identifier for a websocket connection.

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 device.
  • created: The timestamp from when the device was first created in the system, expressed according to RFC 3339.
  • last_seen: The date and time a device last was observed to be actively engaging with the service, expressed according to RFC 3339.
  • last_ip: The IP address the device was using when it was last observed to be actively engaging with the service.
  • user_id: The ID of the User the Device belongs to.

Listing Devices

If the user authenticating the request is the same user whose devices are being listed, this request only requires authentcation. If the user authenticating the request is not the user whose devices are being listed, this request requires administrative authentication.

Request Format

Endpoint

GET /users/{username}/devices

Response Format

Header

This request sets the Last-Modified header to the latest last_seen property of the Devices returned.

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

Body

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

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

In the event no devices 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_ACCESS_DENIED User does not have access to the specified user's devices.
404 ERROR_NOT_FOUND user The specified user was not found.
500 ERROR_ACT_OF_GOD An unknown error occurred.

Getting Information About A Device

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

Request Format

Endpoint

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

Response Format

Header

This request sets the Last-Modified header to the last_seen property of the Device returned.

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

Body

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

{
  "code": 200,
  "msg": "Successfully retrieved device information",
  "devices": [
    {
      // See the User Resource for the contents of this part
    }
  ]
}

Errors

Status Code Field Explanation
400 ERROR_MISSING_PARAM username Username was not specified in the URL.
400 ERROR_ACCESS_DENIED User does not have access to the specified user's devices.
404 ERROR_NOT_FOUND user The specified user was not found.
500 ERROR_ACT_OF_GOD An unknown error occurred.
400 ERROR_MISSING_PARAM id Device ID was not specified in the URL.
400 ERROR_INVALID_FORMAT id Specified device ID was not an unsigned integer.
404 ERROR_NOT_FOUND id Specified device was not found.
400 ERROR_WRONG_OWNER id Specified device ID does not belong to specified user.

Creating A New Device

This request requires only authentication if it is creating a device that belongs to the authenticating user. If it is creating a device for another user, it requires administrative credentials.

Request Format

Endpoint

POST /users/{username}/devices

Request Body

The request body should be a Device Resource. Only the Mutable Properties will be used; the rest will be ignored.

A sample request body:

{
  "device": {
  	"name": "Nexus 4",
  	"client_type": "android_phone",
  	"pushers": {
  		"gcm": {
  			"key": "A random OAuth-esque key goes here, obtained from the device"
  		}
  	}
  }
}

Response Format

Header

This request sets the Last-Modified header to the last_seen property of the Device returned.

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

Body

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

{
  "code": 201,
  "msg": "Successfully created a device",
  "devices": [
    {
      // See the Device Resource for the contents of this part
    }
  ]
}

Errors

Status Code Field Explanation
400 ERROR_MISSING_PARAM username Username was not specified in the URL.
400 ERROR_BAD_REQUEST_FORMAT Request body is not valid JSON.
500 ERROR_ACT_OF_GOD An unknown error occurred.
400 ERROR_MISSING_PARAM device Body must contain a device.
400 ERROR_MISSING_PARAM device.name Device must have a name.
400 ERROR_MISSING_PARAM device.client_type Device must specify a client type.
400 ERROR_INVALID_VALUE device.client_type Device's client type is not a valid client type.
400 ERROR_ACCESS_DENIED User does not have access to the specified user's devices.
404 ERROR_NOT_FOUND user The specified user was not found.

Updating A Device's Information

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

Request Format

Endpoint

PUT /users/{username}/devices/{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 Device Resource. Only the Mutable Properties will be used; the rest will be ignored.

A sample request body:

{
  "device": {
  	"name": "Galaxy Nexus",
  }
}

Response Format

Header

This request sets the Last-Modified header to the last_seen property of the Device returned.

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

Body

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

{
  "code": 200,
  "msg": "Successfully updated the device",
  "devices": [
    {
      // See the Device Resource for the contents of this part
    }
  ]
}

Errors

Status Code Field Explanation
400 ERROR_BAD_REQUEST_FORMAT Request body is not valid JSON.
500 ERROR_ACT_OF_GOD An unknown error occurred.
400 ERROR_MISSING_PARAM device Body must contain a device.
400 ERROR_MISSING_PARAM username Username was not specified in the URL.
400 ERROR_MISSING_PARAM id Device ID was not specified in the URL.
400 ERROR_INVALID_FORMAT id Specified device ID was not an unsigned integer.
400 ERROR_ACCESS_DENIED User does not have access to the specified user's devices.
404 ERROR_NOT_FOUND user The specified user was not found.
404 ERROR_NOT_FOUND id The specified device was not found.
400 ERROR_WRONG_OWNER id The specified device does not belong to the specified user.
400 ERROR_INVALID_VALUE device.client_type Device's client type is not a valid client type.

Deleting A Device

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

Request Format

Endpoint

DELETE /users/{username}/devices/{id}

Response Format

Header

This request sets the Last-Modified header to the last_seen property of the Device returned.

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

Body

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

{
  "code": 200,
  "msg": "Successfully deleted the device",
  "devices": [
    {
      // See the Device Resource for the contents of this part
    }
  ]
}

Errors

Status Code Field Explanation
400 ERROR_MISSING_PARAM username Username was not specified in the URL.
400 ERROR_ACCESS_DENIED User does not have access to the specified user's devices.
404 ERROR_NOT_FOUND user The specified user was not found.
500 ERROR_ACT_OF_GOD An unknown error occurred.
400 ERROR_MISSING_PARAM id Device ID was not specified in the URL.
400 ERROR_INVALID_FORMAT id Specified device ID was not an unsigned integer.
404 ERROR_NOT_FOUND id The specified device was not found.
400 ERROR_WRONG_OWNER id The specified device does not belong to the specified user.
Clone this wiki locally