Introduction
Welcome to the Datacake API documentation.
Authentication
# With shell, you can just pass the correct header with each requestcurl "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.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 totext/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 anerror
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 totext/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 |