Thngs and products can have many properties, which are simple typed key/value pairs of data that are attached to a resource. What sets properties apart from custom fields, is the fact that each property update is timestamped and stored historically, which allows you to retrieve the set of all the values of a property during any specific time range and infer trends over time.
The most common use case of properties is to store dynamic information about a Thng, which is likely to change over time. This is particularly useful for items with frequently changing unique data, where such as sensor readings or item state. For longer-lived data that does not require a history, customFields
should be used instead.
customFields
should be used instead.API Status
General Availability:
/thngs/:thngId/properties
/thngs/:thngId/properties/:key
/products/:productId/properties
/products/:productId/properties/:key
/thngs/:thngId/properties
/thngs/:thngId/properties/:key
/products/:productId/properties
/products/:productId/properties/:key
PropertyDocument Data Model
Thng or product properties take the form of an array of PropertyDocument
objects that always contain a key (case-insensitive, gets converted to lowercase automatically by the API), a value, and a timestamp.
Property Units
If the property type is a number, then you can visualize it as a graph in the dashboard. For this reason, we suggest you don't include the unit in value, but rather encode it in the property name. For example:
If the optional timestamp is not provided when updating the property, it is automatically set by the API at the moment when the request has been processed. If multiple values are being uploaded in one request, they should differentiate each other by specifying timestamps to accompany each object in the payload showing when each value was created.
Create/Update Properties
Create
When a resource is created, you can specify an initial set of properties and their values with a POST
request.
POST /thngs/:thngId/properties
POST /products/:productId/properties
Update
To update those properties or to add new ones to the resource, use PUT
on the following endpoints, with an array of PropertyDocument
JSON object containing the changed fields.
PUT /thngs/:thngId/properties
PUT /products/:productId/properties
If the properties being updated do not exist, they are created automatically by this request and no error/notification will be returned.
NoteExceptionally, to cope with the limitations of mobile network providers you can use both
POST
andPUT
to create/update multiple properties, which behave identically in this particular case. \n\nHowever, only thePUT
method may be used to update properties by name.\n\nThe returned payload is an array of the properties updated, not all of the Thng's the properties.
Read All Properties
GET /thngs/:thngId/properties
GET /products/:productId/properties
Retrieve a list of all the properties of a Thng or product by its ID. The result may be paginated if there are more than 30 items.
The returned payload is the complete array of all the properties with the latest recorded value of each.
Create/Update a Single Property
Properties can be updated individually using their dedicated endpoints. If the property does not exist, it will be created automatically by this request and no error/notification will be returned.
PUT /thngs/:thngId/properties/:key
PUT /products/:productId/properties/:key
It's also possible to upload cached values of a property in batches by specifying timestamps for each data item object.
You can also provide data via three different payload types to the property()
update method:
Read a Property's History
To retrieve the history of values of a specific property, you must access the unique endpoint for each property. By default, all the updates of this property are returned using pagination in a reverse history fashion (the first element of the returned array is the latest update).
GET /thngs/:thngId/properties/:key
GET /products/:productId/properties/:key
If you attempt to fetch the history of values for a property that doesn't exist you will receive an HTTP 200
status code and an empty list as a result.
For accessing only a subset of all the updates to a single property, you can specify a time range using ?from=Timestamp
and ?to=Timestamp
to specify respectively the beginning and end of the time window. You will receive an array of all the property updates during this time.
Delete a Property
Property updates are not uniquely identified (do not have their own URL). Therefore, the only way to delete data points is to append the ?to=Timestamp
URL query parameter to specify a point in time before which all the data points will be removed.
DELETE /thngs/:thngId/properties/:key
DELETE /products/:productId/properties/:key
Delete all Properties
Delete all the properties of a Thng or product. Example below is for Thngs.
System Properties
In addition, the EVRYTHNG Platform automatically sets some system properties. They start with ~
(tilde) and are read-only. Apart from that they behave exactly like other properties.
The following lists the currently available system properties available on Thngs:
~connected
- Boolean
Set to true
if the Thng is updated with its own API key and if it is currently connected to the pub/sub broker through MQTT or WebSockets. The property is created on the Thng first connection and updated every time the Thng disconnects or connects again.