Introduction

Welcome to the Datacake API documentation.

Authentication

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Token mytoken"

Make sure to replace mytoken with your API key.

Datacake uses API keys to allow access to the API. You can register a new Datacake API key in your profile.

Datacake expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Token mytoken

You must replace mytoken with your personal API key.

Devices

Get all Devices

curl https://api.datacake.co/v1/devices/
  -H "Authorization: Token mytoken"

The above command returns JSON structured like this:

[
    {
        "id": "22h7c45f-2917-358-9db1-d8a544ab78ed",
        "serial_number": "22h7c45f-2917-358-9db1-d8a544ab78ed",
        "verbose_name": "Gerät 1",
        "online": false,
        "particle_id": "myparticleid",
        "claim_code": "1234"
    },
    {
        "id": "32h7c45f-2917-358-9db1-d8a544ab78ed",
        "serial_number": "32h7c45f-2917-358-9db1-d8a544ab78ed",
        "verbose_name": "Gerät 2",
        "online": true,
        "particle_id": "myparticleid",
        "claim_code": "1234"
    }
]

This endpoint retrieves all Devices the authenticated user can access.

HTTP Request

GET https://api.datacake.co/v1/devices/

Query Parameters

Parameter	Required	Description
serial_number	no	If set, the Devices will be filtered against this serial number
particle_id	no	If set, the Devices will be filtered against this Particle ID

To filter against the serial number:

curl https://api.datacake.co/v1/devices/?serial_number=22h7c45f-2917-358-9db1-d8a544ab78ed
  -H "Authorization: Token mytoken"

Which will return an array with either zero (no Devices found) or one Device:

[
    {
        "id": "22h7c45f-2917-358-9db1-d8a544ab78ed",
        "serial_number": "22h7c45f-2917-358-9db1-d8a544ab78ed",
        "verbose_name": "Gerät 1",
        "online": false,
        "particle_id": "myparticleid",
        "claim_code": "1234"
    }
]

Get a specific Device

curl https://api.datacake.co/v1/devices/22h7c45f-2917-358-9db1-d8a544ab78ed/
  -H "Authorization: Token mytoken"

The above command returns JSON structured like this:

{
    "id": "22h7c45f-2917-358-9db1-d8a544ab78ed",
    "serial_number": "22h7c45f-2917-358-9db1-d8a544ab78ed",
    "verbose_name": "Gerät 1",
    "online": false,
    "particle_id": "myparticleid",
    "claim_code": "1234"
}

HTTP Request

GET https://api.datacake.co/v1/devices/device/<ID>/

URL Parameters

Parameter	Description
ID	The ID of the Device to retrieve

Create a Device

curl https://api.datacake.co/v1/devices/
  -X POST
  -H "Authorization: Token mytoken"
  -H "Content-Type: application/json"
  --data '{\
    "verbose_name": "My Device",\
    "product": "22h7c45f-2917-358-9db1-d8a544ab78ed",\
    "in_workspace": "22h7c45f-2917-358-9db1-d8a544ab78ed",\
    "claim_code": "1234",\
    "serial_number": "myserial",\
    "particle_id": "1234567890"\
  }'

The above command returns JSON structured like this when the Device was created successfully:

{
    "id": "22h7c45f-2917-358-9db1-d8a544ab78ed",
    "serial_number": "myserial",
    "verbose_name": "My Device",
    "online": false,
    "particle_id": "myparticleid",
    "claim_code": "1234"
}

When a Device with the provided serial number already exists, the command will return a HTTP 400: Bad Request

Device with this serial number already exists.

When you don't have permissions on the provided Workspace, a HTTP 403: Forbidden will be returned

Workspace not allowed. Please check your permissions.

This endpoint will create a new Device.

HTTP Request

POST https://api.datacake.co/v1/devices/

Data

Parameter	Required	Description
verbose_name	yes	Human-readable name
product	yes	ID of the Product
in_workspace	yes	ID of the Workspace the Device should live in
claim_code	yes	Claim / PIN code
serial_number	yes	Unique serial number of the Device
particle_id	no	Particle ID that should be assigned to the Device

Update a Device

curl https://api.datacake.co/v1/devices/22h7c45f-2917-358-9db1-d8a544ab78ed/
  -X PATCH
  -H "Authorization: Token mytoken"
  -H "Content-Type: application/json"
  --data '{\
    "verbose_name": "My Device",\
    "product": "22h7c45f-2917-358-9db1-d8a544ab78ed",\
    "in_workspace": "22h7c45f-2917-358-9db1-d8a544ab78ed",\
    "claim_code": "1234",\
    "serial_number": "myserial",\
    "particle_id": "1234567890"\
  }'

The above command returns JSON structured like this when the Device was created successfully:

{
    "id": "22h7c45f-2917-358-9db1-d8a544ab78ed",
    "serial_number": "myserial",
    "verbose_name": "My Device",
    "online": false,
    "particle_id": "myparticleid",
    "claim_code": "1234"
}

When a Device with the provided serial number already exists, the command will return a HTTP 400: Bad Request

Device with this serial number already exists.

When you don't have permissions on the provided Workspace, a HTTP 403: Forbidden will be returned

Workspace not allowed. Please check your permissions.

This endpoint will update the Device.

HTTP Request

PATCH https://api.datacake.co/v1/devices/<ID>/

URL Parameters

Parameter	Description
ID	The ID of the Device to update

Data

Parameter	Required	Description
verbose_name	no	Human-readable name
product	no	ID of the Product
in_workspace	no	ID of the Workspace the Device should live in
claim_code	no	Claim / PIN code
serial_number	no	Unique serial number of the Device
particle_id	no	Particle ID that should be assigned to the Device

Delete a Device

curl https://api.datacake.co/v1/devices/22h7c45f-2917-358-9db1-d8a544ab78ed/
  -X DELETE
  -H "Authorization: Token mytoken"

Use this endpoint to permanently delete a Device and all of it's associated data.

HTTP Request

DELETE https://api.datacake.co/v1/devices/<ID>/

URL Parameters

Parameter	Description
ID	The ID of the Device to delete

Record Measurements

curl https://api.datacake.co/v1/devices/22h7c45f-2917-358-9db1-d8a544ab78ed/record/
  -X POST
  -H "Authorization: Token mytoken"
  -H "Content-Type: application/json"
  --data '{\
    "field": "TEMPERATURE",\
    "value": 23.5,\
    "timestamp": "1555570137"\
  }'

The endpoint will return a HTTP 201: Created with information about the recorded measurements

[
  {
    "field": "TEMPERATURE",
    "value": 23.5,
    "timestamp": 1555570137,
    "ok": true
  }
]

If you prefer to get the old text-representation of the number of recorded measurements, please set the Accept header to text/plain, this will return

Recorded 1 data points

To record a single measurement, you can use this endpoint.

HTTP Request

POST https://api.datacake.co/v1/devices/<ID>/record/

URL Parameters

Parameter	Description
ID	The ID of the Device

Data

Parameter	Required	Description
field	yes	Case-insensitive field identifier
value	yes	Measurement to record
timestamp	no	UNIX Timestamp of when the measurement occured

Record multiple Measurements

curl https://api.datacake.co/v1/devices/22h7c45f-2917-358-9db1-d8a544ab78ed/record/?batch=true
  -X POST
  -H "Authorization: Token mytoken"
  -H "Content-Type: application/json"
  --data '[\
    {\
        "field": "TEMPERATURE",\
        "value": 23.5,\
        "timestamp": "1555570137"\
    }\,
    {\
        "field": "TEMPERATURE",\
        "value": 23.5,\
        "timestamp": "1555570137"\
    }\,
    {\
        "field": "HUMIDITY",\
        "value": 42,\
        "timestamp": "1555570137"\
    }\
  ]'

The endpoint will return a HTTP 201: Created with information about the recorded measurements. If a field exceeds its rate limit (based on the timestamp, if will have an error attribute)

[
  {
    "field": "TEMPERATURE",
    "value": 23.5,
    "timestamp": 1555570137,
    "ok": true
  },
  {
    "field": "TEMPERATURE",
    "value": 23.5,
    "timestamp": 1555570137,
    "ok": false,
    "error": "Rate limit exceeded"
  },
  {
    "field": "HUMIDITY",
    "value": 40,
    "timestamp": 1555570137,
    "ok": true
  },
]

If you prefer to get the old text-representation of the number of recorded measurements, please set the Accept header to text/plain, this will return

Recorded 2 data points

To record multiple measurements in one call, add ?batch=true to the URL and POST an array of measurement objects instead.

HTTP Request

POST https://api.datacake.co/v1/devices/<ID>/record/?batch=true

URL Parameters

Parameter	Description
ID	The ID of the Device

Data

Array of:

Parameter	Required	Description
field	yes	Case-insensitive field identifier
value	yes	Measurement to record
timestamp	no	UNIX Timestamp of when the measurement occured

Export historic data

curl https://api.datacake.co/v1/devices/22h7c45f-2917-358-9db1-d8a544ab78ed/historic_data/?fields=TEMPERATURE,HUMIDITY&resolution=5m&timeframe_start=2019-01-01T00:00:00Z&timeframe_end=2019-12-01T00:00:00Z
  -H "Authorization: Token mytoken"

The endpoint will return the data in the specified format:

[
    {
        "time": "2019-01-01T00:00:00Z",
        "TEMPERATURE": 12.34,
        "HUMIDITY": 42
    },
    {
        "time": "2019-01-02T00:00:00Z",
        "TEMPERATURE": 12.34,
        "HUMIDITY": 42
    },
    {
        "time": "2019-01-03T00:00:00Z",
        "TEMPERATURE": 12.34,
        "HUMIDITY": 42
    }
]

When the timeframe or the resolution can not be parsed, the endpoint will return a HTTP 400: Bad Request

There was a problem parsing the timeframe

You can export historic data to JSON or CSV.

HTTP Request

GET https://api.datacake.co/v1/devices/<ID>/historic_data/

URL Parameters

Parameter	Required	Description
ID	yes	The ID of the Device
format	no	either json (default) or csv
fields	yes	comma-seperated list of the fields to include
resolution	yes	either `raw` or `x minutes/hours/days`
timeframe_start	yes	ISO 8601-formatted start of the timeframe
timeframe_end	yes	ISO 8601-formatted end of the timeframe