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

Devices

Jump to bottom
Paddy Foran edited this page Jan 27, 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.

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
    }
  ]
}

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
    }
  ]
}

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
    }
  ]
}

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
    }
  ]
}
Clone this wiki locally