Dataplicity Developer Hub

Dataplicity Documentation

Here you'll find announcements for new features and comprehensive guides to help you integrate Dataplicity into your Raspberry Pi projects.

Get Started    Announcements

Overview

 

The Dataplicity Apps REST API allows for managing devices and account details. It accepts and returns data in the JSON format.

Things you can do with this API:

  • Programmatically query or update information about devices, including their description
  • Query device status
  • Trigger a device reboot
  • Manage your account details including password resets

NB: It is not possible to access the remote shell with this API.

We'd love to hear what we're getting right, and if there's anything more we could do. We're very open to feedback, so please let us know if we're missing something you need.

HTTP Requests and Responses

 

Each endpoint behaves differently depending on the request method that is used in a request to it.

To see what is accepted by a particular endpoint, make an OPTIONS request.

With curl, it will look like this:

curl -X OPTIONS https://apps.dataplicity.com

... or with httpie (recommended), it'll look like this:

http OPTIONS https://apps.dataplicity.com/

The response will inform you of what you can do on that endpoint:

HTTP/1.1 200 OK
Allow: POST, DELETE, OPTIONS
Content-Type: application/json
...

{
    "actions": {
        "POST": {...}
    },
    "description": "...",
    "name": "...",
    "parses": ["application/json"],
    "renders": ["application/json"]
}

In this case, the Allow header tells you that the accepted request types are POST, DELETE, and OPTIONS.

The description and name keys contain brief documentation of the endpoint. The description may contain newline characters encoded as \n.

If an action (PUT, POST, etc) requires particular data in the body of the request, it will provide information about the information that it expects.

Responses will use the standard HTTP response codes where possible. Of particular interest will be:

  • 200 OK. All went well. The body of the response contains information about the state of a resource.

  • 201 Created. The data you sent was used to create a resource. The body of the response will contain information about the created resource.

  • 202 Accepted. Your request was accepted for processing. This usually means that the requested action will be attempted, but does not guarantee that it will complete successfully.

  • 204 No Content. Your request was successful, but there is no appropriate data to respond with.

  • 301 Moved Permanently. This denotes that a resource is not in the location that you requested. Perhaps you forgot to add a trailing / onto the URL? The Location header should guide you to a new location.

  • 400 Bad Request. The data you've sent across does not conform to expectations. The body of the response will detail what went wrong.

  • 401 Unauthorized. Authentication is required, but has not been provided.

  • 403 Forbidden. Access denied. Authentication will not help.

  • 404 Not Found. You have tried to access a resource that doesn't exist or you do not have access to.

  • 405 Method Not Allowed. The request method you used (eg: POST) is not allowed for this resource. You should see the acceptable methods for a particular endpoint by inspecting the Allow header.

Authentication

 

In order to limit access to your details and devices, most parts of the API require that you authenticate with an auth token. To create a token, see the docs for /auth/.

To make authenticated requests, you will need to add the token to a header to your requests. The token should be included in the Authorization HTTP header and prefixed by the string literal Token (note the space). For example:

Authorization: Token example123

/auth/

 

This endpoint deals with authentication. It can be used to create a token that will grant access to the rest of the API, and to invalidate a token that is no longer desired.

POST

To create a new auth token, send your auth details with a POST request:

{
    "email": "example@example.com",
    "password": "your password"
}

On success, you will get a token with a response code of 201 (created):

{
    "token": "example123"
}

This token can be used to authenticate subsequent requests as described in Authentication.

DELETE

To invalidate a token, make an authenticated DELETE request to /auth/.

On success, you will get a response with code 204 (no content).

/change-password/

 

POST

To change the password of the authenticated user, submit your old and new passwords:

{
    "old_password": "...",
    "new_password": "...",
}

On success, you will get a response with code 204 (no content).

There are a number of password requirements:

  • It must be at least 8 characters long.
  • It cannot be too similar to your name, email, or install code.
  • It cannot be entirely numeric.
  • It cannot be a very popular password (eg "password").

/devices/

 

GET

Lists all your devices:

[
    {
        "agent_version": "0.4.0",
        "created_time": "2016-05-10T11:09:38",
        "description": "This is a lovely device",
        "disk_capacity": null,
        "disk_used": null,
        "machine_type": "rpi_1b_plus",
        "machine_type_display": "Raspberry Pi 1 Model B+",
        "name": "First Raspberry Pi",
        "online": true,
        "operating_system": "",
        "ports_url": "https://apps.dataplicity.com/devices/c0ffee7ea-cafe-cafe-cafe-c0ffeec0ffee/ports/",
        "processor_speed": 2201000,
        "ram_capacity": 8371830784,
        "reboot_url": "https://apps.dataplicity.com/devices/c0ffee7ea-cafe-cafe-cafe-coffeecoffee/reboot/",
        "serial": "c0dec0de-c0de-c0de-c0de-c0dec0dec0de",
        "uname": "",
        "url": "https://apps.dataplicity.com/devices/c0ffee7ea-cafe-cafe-cafe-c0ffeec0ffee/",
        "wormhole_slug": "example"
    },
    ...
]

/devices/{id}/

 

GET

Details a particular device. When authenticated, will return a 200 (OK) when you have access to a device, or 404 (Not Found) for devices you cannot access.

{
    "agent_version": "0.4.0",
    "created_time": "2016-05-10T11:09:38",
    "description": "This is a lovely device",
    "disk_capacity": null,
    "disk_used": null,
    "machine_type": "rpi_1b_plus",
    "machine_type_display": "Raspberry Pi 1 Model B+",
    "name": "First Raspberry Pi",
    "online": true,
    "operating_system": "",
    "ports_url": "https://apps.dataplicity.com/devices/c0ffee42-cafe-cafe-cafe-c0ffeec0ffee/ports/",
    "processor_speed": 2201000,
    "ram_capacity": 8371830784,
    "reboot_url": "https://apps.dataplicity.com/devices/c0ffee42-cafe-cafe-cafe-coffeecoffee/reboot/",
    "serial": "c0dec0de-c0de-c0de-c0de-c0dec0dec0de",
    "uname": "",
    "url": "https://apps.dataplicity.com/devices/c0ffee42-cafe-cafe-cafe-c0ffeec0ffee/",
    "wormhole_slug": "example"
}

/devices/{id}/reboot/

 

POST

To ask a device to reboot, make an authenticated POST request. No request body is required.

You should receive a 202 (Accepted) response. This indicates the reboot signal has been dispatched, but does not guarantee that the reboot succeeded.

/profile/

 

GET

Retrieves your details:

{
    "email": "example@example.com",
    "email_verified": true,
    "has_usable_password": true,
    "install_command": "curl https://www.dptestenv.com/example.py | sudo python",
    "install_token": "example",
    "name": "Maurice Micklewhite"
}

PUT

Change your details. You are currently only permitted to modify name.

{
    "name": "Michael Caine"
}

On success, you will receive a 200 (OK) with your new, updated, details:

{
    "email": "example@example.com",
    "email_verified": true,
    "has_usable_password": true,
    "install_command": "curl https://www.dptestenv.com/example.py | sudo python",
    "install_token": "example",
    "name": "Michael Caine"
}

/register/

 

POST

Creates a new user account. Requires only an email:

{
    "email": "example@example.com"
}

On success, you will receive a 201 (Created) response, and a token that can be used to make authenticated requests as described in Authentication.

Be sure to check your email and verify your account, otherwise you won't be able to log in later!

/reset-password/

 

POST

Dispatches an email that will contain a link that can be followed to set a new password. You should not be authenticated when making this request.

{
    "email": "forgotten@example.com"
}

On success, you will receive a 204 (No content) and should check your email for a password reset link.