A Thng is the central data structure in the EVRYTHNG Platform. Thngs are extensible data containers designed to model physical objects such as packaged consumer products, electronic devices, or other saleable goods that are manufactured in large quantities, etc. Thngs have various basic fields including name
, description
, tags
, etc. More dynamic data can be stored in the properties
, and specialised use-case specific data in customFields
, or identifiers
fields as required.
Thngs can be the target of actions describing events that happen to them, or they can be added to collections to express logical groupings, such as a box of individual items, as a unit. In addition to specifying a Thng in an action, it is also possible to create an action through the Thng itself using aliased actions.
API Status
General Availability:
/auth/evrythng/thngs
/thngs
/thngs/:thngId
/thngs/:thngIdentifier
/thngs/:thngId/actions/:actionType
/thngs/:thngId/location
/thngs/:thngId/properties
/auth/evrythng/thngs
/thngs
/thngs/:thngId
/thngs/:thngIdentifier
/thngs/:thngId/actions/:actionType
/thngs/:thngId/location
/thngs/:thngId/properties
ThngDocument Data Model
See also: ScopesDocument
, LocationDocument
Filterable Fields
This resource type can be filtered using the following fields and operators.
Create a Thng
Create a new Thng. It is recommended to link all Thngs to a product upon creation by specifying the product's ID in the product
field.
Read a Thng
Thng data is read using a GET
request on the Thng URL including the thngId
.
Read all Thngs
Read all available Thngs in scope of the authenticating API key. The result may be paginated if there are more than 30 items.
Update a Thng
Update a single Thng by ID.
NoteOnly the basic fields (
name
,description
,product
,identifiers
,tags
, andcustomFields
) can be updated in this manner. \n\nProperties, location and collections must be updated via their respective/thngs/:thngId/location
,/thngs/:thngId/properties
and/collections/:collectionId/thngs
endpoints.
Update Multiple Thngs
Using a suitable filter, it is possible to apply (PUT
) an updated ThngDocument
to multiple Thngs, providing they match the filter
query parameter. For example, all Thngs that begin with "Smart"
to contain the 'smart' tag.
The update will be applied asynchronously, and the response will be 204 'No Content'.
Delete a Thng
Delete a single Thng by ID. This action cannot be undone.
Thng Location
As Thngs model real-world resources, they have a special property called a location
to keep track of the actual position over time. See the Locations section for more information.
location
to keep track of the actual position over time. See the Locations section for more information.Create a Thng's Redirection
Use the appropriate short domain API to create a Thng redirection. This example uses tn.gg
.
Read a Thng's Redirection
Use the appropriate short domain redirection API to read a Thng redirection.
Update a Thng's Redirection
Use the appropriate short domain redirection API and short ID to update a Thng redirection.
Delete a Thng's Redirection
Thngs as Devices
In the connected devices world, devices can be autonomous and behave as sensors and/or actuators, communicating directly with the EVRYTHNG platform as an actor. A Thng can be registered as a device by creating a Device API key, with which the device can manage the details of its corresponding Thng in the EVRYTHNG platform.
Create Device API Key
Creates an API Key for a given Thng (Device API key), which is useful when an embedded device needs to talk to its Thng in the Platform (update its properties, subscribe to actions, etc.).
A Device API key can only be created by Application Users or Operators. If called multiple times for the same Thng, the existing API key will be returned (a new one will not be generated). If you want to create a new API key for a Thng, you must delete the existing one first (see below).
NoteDevice API Keys are currently created on a per-project basis. This means that a Device API Key created with a Thng with no project scope will not be available if the Thng is later moved to a different project scope. Similarly, if a Thng already in a given project is scoped to other projects, new Device API Keys will need to be created for each new project.\n\nIn the future, Device API Keys will inherit the scope of the Thng they represent. When this change occurs this page will be updated.
Read Device API Key
Can be done by Application Users or Operators that have access rights to the Thng.
Delete Device API Key
This revokes access for a given Device API key. Can be done by Application Users or Operator that have access rights to the Thng.
Using Evrythng.js in a Device
To make it easier for Javascript developers to write embedded device applications, we created the Device
scope. Remember that conceptually a device is a Thng. Therefore the Device
scope has direct access to everything related to the Thng (actions, properties, locations) - see API Key Scopes and Permissions for more information.
Example: evrythng.js
See Properties for more examples on using the property resource.
See Actions for more examples on using the /actions
resource.