This page gives an overview of how the EVRYTHNG Platform API is structured, including the different types of resources that can be used, and the API keys, roles, and permissions governing access to them.
For information and technical details on all the different types of resources available in the EVRYTHNG Platform REST API, check out the API Reference section.
An account in the EVRYTHNG Platform is a Dashboard account. An account belongs to the person who created it, and is called an Operator. However, to allow collaboration within accounts other Operators can be added to any given account.
Accounts contain projects and applications, which are in turn interacted with by users. The table below details what the role of each of these 'actors' is within the platform:
Operators are account managers, they can create Thngs, products, projects and applications, read the stats, use the dashboard, etc.
Applications represent software programs you create that use the EVRYTHNG API. Usually they have a very limited set of permissions as they are not real people.
These are the end-users of your applications. They can be people or machines.
Both scopes and permissions control restricted access to data in a fine-grained modular way that's fit for the Internet of Things.
Scopes: define what you can see.
Permissions: define what you can do.
Permissions are the answer to questions like "can I modify a product?" or "can I list Thngs?". Scopes on the other hand ensure that you can see only what you are supposed to. As an example, when listing all Thngs in a Project A context, the scope ensures you only see the Thngs that are in Project A's scope.
There are two types of scopes: the project scopes and the user scopes. Every request is made within a specific scope. Each resource may be part of 0 or more scopes (of both types). For instance listing Thngs scoped to Project A will only return the Thngs that are part of Project A's scope.
The scope used for a request depends on the actor who makes that request (the type of API key used), as shown in the following table:
Operators see everything within an account, unless they use the project query parameter, which scopes the request to the specified project.
Requests made by applications are scoped to the project they belong to.
Like applications, Application Users cannot see resources that are outside of the project and application. Moreover, they only see resources that are within their own scope (the user scope).
The scopes that a resource is part of can be modified with the Scope and Permissions API.
There is a set of permissions attached to each API key type. These permissions allow the API to decide if the request is allowed to proceed or not. Should it decide to deny the request, a
403 Forbidden code is returned to the client. The decision is made based on the following request elements:
- HTTP verb
- URL path
- Query parameters
A Thng is the digital representation of an individual object in the physical world such as a car, an Arduino, a mobile phone, or a bottle of apple juice. Thngs live in our platform and can store any data about their physical counterpart (such as its current location, status, or properties etc.). Properties can be attached to Thngs and can be updated any time, while preserving the history of those changes. Thngs can also be grouped into collections to facilitate the management of many items at once.
A Thng is effectively a RESTful API for each physical object that multiple applications can talk to. Each Thng has its own URL, which acts as a globally unique and persistent identifier (and serial number) for the object.
A product is a generic description of a class of Thngs (akin to SKU-level information) and the metadata associated with those Thngs such as their size, weight, or description. Many Thngs can be linked to a single product. This means that each Thng can be thought of as an instance of a product.
A Thng can have multiple properties, which are simply typed key/value pairs used to model information about an object that can change over time (such as sensor readings). Properties can be updated any time, and the previous values are automatically persisted and can be retrieved via the API.
The type of a property is automatically determined at creation time and cannot be changed afterwards.
Custom fields are extensions of a resource in the EVRYTHNG API. They can be used to enhance the metadata of a Thng to incorporate your own data about the object. The value of a custom field can be a string, a boolean, a number, an array or a JSON object. Arrays can be composed of any allowed type previously listed.
Unlike a property, custom fields are used for aspects that do not change over time and thus the past values are not persisted.
Thngs also have a special type of property for storing snapshots of its geographic position over time. When updated, the previous locations are stored automatically in the platform.
An action is an event sent to the platform that was carried out by a user in an application or a Thng/product, at a given place and time. For example, the user scanned or checked into a product. Actions are used to record the activity of users and Thngs within applications.
A collection is a grouping of Thngs. Collections can be created by various users, and the same Thng can be in included in more than one collection.
A general term that refers to all the data types and resources stored in the platform that are related to the physical world. Thngs, collections, products, places, and actions are all resources.
To better understand the relationships between the types of resources of the EVRYTHNG Platform, please refer to the diagrams below. First, the relationships between accounts, projects, operators, Application Users, and applications:
What we see here is that operators can access multiple accounts if they were added to them as users. Accounts can have multiple projects, which can contain multiple applications, which in turn can have multiple Application Users.
Next, let's have a look at the relationships between accounts and their resources: Thngs, products, actions, locations, collections, and places:
As you can see, accounts can contain resources such as products and Thngs. Note, that they can add these resources to their projects, making them available to all applications within the project. Collections can contain a number of Thngs, and can be shared under a single account. Thngs can have locations. Thngs and products can have properties.
Finally, we look at the relationships between Application Users and other associated resources:
Users can create, read, and update products, collections, Thngs. Users can also perform actions.
To better understand "who can do what" and "who can see what" refer to API Scope and Key Permissions.