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

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.de/v1/devices/

Query Parameters

ParameterRequiredDescription
serial_numbernoIf set, the Devices will be filtered against this serial number
particle_idnoIf 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.de/v1/devices/device/<ID>/

URL Parameters

ParameterDescription
IDThe 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.de/v1/devices/

Data

ParameterRequiredDescription
verbose_nameyesHuman-readable name
productyesID of the Product
in_workspaceyesID of the Workspace the Device should live in
claim_codeyesClaim / PIN code
serial_numberyesUnique serial number of the Device
particle_idnoParticle 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.de/v1/devices/<ID>/

URL Parameters

ParameterDescription
IDThe ID of the Device to update

Data

ParameterRequiredDescription
verbose_namenoHuman-readable name
productnoID of the Product
in_workspacenoID of the Workspace the Device should live in
claim_codenoClaim / PIN code
serial_numbernoUnique serial number of the Device
particle_idnoParticle 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.de/v1/devices/<ID>/

URL Parameters

ParameterDescription
IDThe 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 the number of measurements successfully recorded

Recorded 1 data points

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

HTTP Request

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

URL Parameters

ParameterDescription
IDThe ID of the Device

Data

ParameterRequiredDescription
fieldyesCase-insensitive field identifier
valueyesMeasurement to record
timestampnoUNIX 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": "HUMIDITY",\
"value": 42,\
"timestamp": "1555570137"\
}\
]'

The endpoint will return a HTTP 201: Created with the number of measurements successfully recorded. If a field can not be found, it will be ignored and not count into the result.

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.de/v1/devices/<ID>/record/?batch=true

URL Parameters

ParameterDescription
IDThe ID of the Device

Data

Array of:

ParameterRequiredDescription
fieldyesCase-insensitive field identifier
valueyesMeasurement to record
timestampnoUNIX 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.de/v1/devices/<ID>/historic_data/

URL Parameters

ParameterRequiredDescription
IDyesThe ID of the Device
formatnoeither json (default) or csv
fieldsyescomma-seperated list of the fields to include
resolutionyeseither raw or x minutes/hours/days
timestrame_startyesISO 8601-formatted start of the timeframe
timestrame_endyesISO 8601-formatted end of the timeframe