Using the API

Devicehub is a REST API on the web that partially extends Schema.org’s ontology and it is formatted in JSON.

The main resource are devices. However, you do not perform operations directly against them (there is no POST /device), as you use an Action / Event to do so (you only GET /devices). For example, to upload information of devices with tests, erasures, etcetera, use the action/event POST /snapshot (devices-snapshot).

Login

To use the API, you need first to log in with an existing account from the DeviceHub. Perform POST /users/login/ with the email and password fields filled:

POST /users/login/
Content-Type: application/json
Accept: application/json
{
  "email": "user@dhub.com",
  "password: "1234"
}

Upon success, you are answered with the account object, containing a Token field:

{
  "id": "...",
  "token: "A base 64 codified token",
  "type": "User",
  "inventories": [{"type": "Inventory", id: "db1", ...}, ...],
  ...
}

From this moment, any other following operation against the API requires the following HTTP Header: Authorization: Basic token. This is, the word Basic followed with a space and then the token, obtained from the account object above, exactly as it is.

Authenticate requests

To explain how to operate with resources like events or devices, we use one as an example: obtaining devices. The template of a request is:

GET <inventory>/devices/
Accept: application/json
Authorization: Basic <token>

And an example is:

GET acme/devices/
Accept: application/json
Authorization: Basic myTokenInBase64

Let’s go through the variables:

• <inventory> is the name of the inventory where you operate. You get this value from the User object returned from the login. The inventories field contains a set of databases the account can operate with, being the first inventory the default one.

• <token> is the token of the account.

See Devices for more information on how to query devices.