Properties

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.

API Status General Availability: /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.

❗Note

Exceptionally, to cope with the limitations of mobile network providers you can use both POST and PUT to create/update multiple properties, which behave identically in this particular case. \n\nHowever, only the PUT 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.