Thingstream provides a rich Customer API to allow you to carry out the majority of functions that can be done in the portal in addition to providing the ability to Report Usage on your S2S devices.
Two endpoints are available to choose from for reporting S2S Device Usage records, a single record S2S Device Usage and also a bulk record S2S Device Usage endpoint.
Single device Usage
Sample Format for Customer API Post payload:
{
"periodStart": "2024-08-27T09:26:39.741Z",
"periodEnd": "2024-08-27T09:26:39.741Z",
"deviceId": "device:xxxx",
"count": 1
}
-
periodStart String values An effort is made to ensure that period start precedes periodEnd
-
periodEnd String values An effort is made to ensure that period start precedes periodEnd
-
deviceId String values This value is obtained from the Thing details pane in the Thingstream Portal or by making a call to /thing/search endpoint, the response contains the value as entityId.
-
count Integer values This value must be greater than 0 to ensure a record is created
Where date strings have been provided as examples, it is advised to follow the format as closely as possible. Attempts to use '2024/08/24' for example will result in a failure to parse the payload however '2024-08-24' will be honoured.
An attempt to use an identifier as deviceId that does not begin with the expected 'device:' prefix will similarly result in a failure to parse the payload.
Usage example with valid inputs:
Posting usage where the start date precedes the end date, deviceId is valid and count is > 0:
{
"periodStart": "2024-08-23",
"periodEnd": "2024-08-24",
"deviceId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 357
}
Results in a response code of 204 with no body.
Usage examples where there are errors with the inputs:
-
Posting usage where the end date precedes the start date:
{
"periodStart": "2024-08-29",
"periodEnd": "2024-08-27",
"deviceId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 1
}
Results in a response code of 422 with a body of:
{
"errors": [
"periodEnd must be after periodStart"
]
}
-
Posting usage where an invalid deviceId is supplied:
{
"periodStart": "2024-08-24",
"periodEnd": "2024-08-25",
"deviceId": "identity:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 1
}
Results in a response code of 403 with a body of:
'Device not found'
-
Posting usage with a zero count:
{
"periodStart": "2024-08-24",
"periodEnd": "2024-08-25",
"deviceId": "identity:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 0
}
Results in a response code of 422 with a body of:
{
"errors": [
"count must be greater than or equal to 1"
]
}
Bulk device Usage
Whilst employing an alternate endpoint for reporting S2S usage in bulk, the basic reporting content of the endpoint remains unchanged with one exception. That content is wrapped in an array of 'records' as per the example below.
The records are scanned to ensure the bulk action is capable of succeeding. Any single 'record' of usage that is in error due to dates, counts or errors in the deviceId will result in a failure to execute all records.
Sample Format for Customer API Post payload:
{
"records": [
{
"periodStart": "2024-08-27T10:12:07.589Z",
"periodEnd": "2024-08-28T10:12:07.589Z",
"deviceId": "device:xxxx",
"count": 1
},
{
"periodStart": "2024-08-27T10:12:07.589Z",
"periodEnd": "2024-08-28T10:12:07.589Z",
"deviceId": "device:xxxx",
"count": 1
}
]
}
Usage example with valid inputs:
Posting usage where the start date precedes the end date, deviceId is valid and count is > 0:
{
"records": [
{
"periodStart": "2024-08-23T00:00:00.1",
"periodEnd": "2024-08-24T23:59:59.589Z",
"deviceId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 531
},
{
"periodStart": "2024-08-23T00:00:00.1",
"periodEnd": "2024-08-24T23:59:59.589Z",
"deviceId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 217
}
]
}
Results in a response code of 204 with no body.
Usage examples where there are errors with the inputs:
-
Posting usage where the end date precedes the start date in at least one 'record':
{
"records": [
{
"periodStart": "2024-08-25T00:00:00.1",
"periodEnd": "2024-08-24T23:59:59.589Z",
"deviceId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 531
},
{
"periodStart": "2024-08-23T00:00:00.1",
"periodEnd": "2024-08-24T23:59:59.589Z",
"deviceId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 217
}
]
}
Results in a response code of 422 with a body of:
{
"errors": [
"periodEnd must be after periodStart"
]
}
-
Posting usage where an invalid deviceId is supplied in at least one 'record':
"records": [
{
"periodStart": "2024-08-23T00:00:00.1",
"periodEnd": "2024-08-24T23:59:59.589Z",
"deviceId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 531
},
{
"periodStart": "2024-08-23T00:00:00.1",
"periodEnd": "2024-08-24T23:59:59.589Z",
"deviceId": "my busy device",
"count": 217
}
]
}
Results in a response code of 403 with a body of:
''One or more device ids not found''
-
Posting usage with a zero count:
{
"records": [
{
"periodStart": "2024-08-23T00:00:00.1",
"periodEnd": "2024-08-24T23:59:59.589Z",
"deviceId": "device:3f6cdbf6-4f70-4aff-a715-443a8f496dfd",
"count": 222
},
{
"periodStart": "2024-08-23T00:00:00.1",
"periodEnd": "2024-08-24T23:59:59.589Z",
"deviceId": "device:52849152-0ee1-49b8-8bd6-acf874775944",
"count": 0
}
]
}
Results in a response code of 422 with a body of:
{
"errors": [
"records[1].count must be greater than or equal to 1"
]
}
The index position in the array of the record in error is provided where the count is invalid i.e. 0
Still need help?
If you need more help or have any questions, please send an email to services-support@u-blox.com.