This API is designed to be accessed by regular end-users. Tags can only be viewed (not deleted or created). Captures can be created, but only by scanning a tag with a recognised serial and secretkey. Samples from multiple captures can be retrieved and de-duplicated.
Capture Creation
The create capture endpoint passes data extracted from a cuplURL to the decoder. Output is persisted in the database as a capture. Each is stored as a child of the tag that created the cuplURL. This list of captures constitutes a long-term record of the temperature and humidity measured by cuplTag. It extends datalogging capacity well beyond the on-board 1KB circular buffer.
The decoder requires a secret key to validate the HMAC part of the cuplURL. Without this, no capture is created and an error message is raised – the cuplURL could have originated from anywhere. The secret key is a random 16-character string assigned to each tag in production. It is looked up before the decoder is invoked.
Sample De-duplication
The cuplTag writes samples to a circular buffer at 10 minute intervals. It takes roughly one day for old samples to be overwritten. A subset of two captures taken within one day will be identical.
The user will want to view all samples stitched together on a timeline, with no duplicates. This is much better than viewing one capture at-a-time. cuplBackend facilitates this with the unique samples endpoint. It returns sample data between a start and end timestamp.
Physical Access Endpoints
When the create capture endpoint is called a tagtoken is returned, which expires after 10 minutes. This can then be passed to POST, PUT and DELETE endpoints described below. The token proves the user has physical access to one tag and is therefore likely to own it. Therefore, some write privileges are granted.
Description
Users can label cuplTags by making a PUT request to the tag description endpoint.
Webhooks
When a capture is created by cuplBackend, it can be transmitted to a 3rd party application by means of a reverse API call (webhook). In other words: cuplbackend can POST new captures to a URL of your choice.
Webhooks eliminate the need for 3rd party applications polling cuplBackend for new tag data. The URL is set from a frontend application. A tagtoken is required (see above).
Browse Tags, Captures and Samples
Without authentication, users are free to read non-sensitive data on tags, captures and samples. Rate limits are adjusted with environment variables.