General principles of query generation

When forming queries, the key methods are:

• GET - getting data from a resource;
• POST - creating and placing a new resource;
• PATCH - updating a resource, adding one or more PATCH - update the resource, adding one or more changes to the specified fragment of the resource;
• DELETE - delete a resource.

The constituent parts of the query path:

• api/v1 - the prefix with which the path of any query begins;

• :store - entity type:

  • models - models;
  • objects - objects;
  • automatons - logic;
  • handlers - handlers;
  • labels - labels;
  • geofences - geofences;
  • admin - project administration;
  • links - links;
  • messages - messages;
  • users - users;
  • groups - groups;
  • invites;
  • roles;
  • tokens - API tokens;
  • geo - geography.

• :id - entity identifier, which is a a string of 12 bytes (e.g, 58238a935baa56173b24f0e4). It is assigned by the system at the time of it is assigned by the system at the time of creation and cannot be changed later. IN THE API link of each entity, this identifier is stored in the _id field.

Get a list of entities

To get a list of entities, send a request

GET /api/v1/:store. The message body is not specified in this case.

Retrieving the list is available for the following :store:

• models - models;
• objects - objects;
• automatons - logic;
• handlers - handlers;
• labels - labels;
• geofences - geofences;
• messages - messages;
• users - users;
• groups - groups;
• invites - invitations;
• roles - roles;
• tokens - API tokens.

In the process of working with lists of entities it may be necessary to to narrow down the data selection. For this purpose in the query line you can specify additional parameters:

• offset

When requesting a list of entities, the maximum number of objects that can be given away is 10000. In order to upload the following data, specify an offset in the offset parameter.

For example, the query /api/v1/:store?offset=20000 retrieves a list of of 10000 entities starting from 20001 inclusive.

• limit

To set a limit on the number of entities that can be uploaded, specify a limit in the limit parameter.

For example, the query /api/v1/:store?offset=3&limit=2 allows you to retrieve a list of 2 entities, starting from 4 inclusive.

• only

To specify a list of specific fields to be issued, specify the list in the only parameter.

For example, a query /api/v1/:store?limit=2\&only=name,description will produce a list of 2 entities. to get a list of 2 entities, and each entity will contain only the _id (mandatory), name and description fields.

• from and to / begin and end

To request a list of entities created in a particular period, specify the lower and upper boundary of the interval in the parameters from and to, respectively. Similarly, these parameters can be set to begin and end. Interval boundaries are specified in the form of specific moments of of time in one of the formats:

1) Unix time - number of milliseconds from midnight (00:00:00 UTC) on January 1, 1970; Unix time - number of milliseconds from midnight (00:00:00 UTC) on January 1, 1970 January 1, 1970;

2) ISO 8601 - date and time in YYYYY-MM-DDThh:mm format.

For example, the queries /api/v1/:store?from=1640131200000&to=1640563200000 and /api/v1/:store?from=2021-12-22T00:00&to=2021-12-27T00:00 позволяют to get a list of entities created between December 22nd and December 27th. 2021.

Retrieving an entity

To retrieve information on a single entity, send a request to

GET /api/v1/:store/:id. The message body is not specified in this case message body is not specified in this case.

Retrieving a single entity is available for the following :store:

• models - models;
• objects - objects;
• automatons - logic;
• handlers - handlers;
• labels - labels;
• geofences - geofences;
• users - users;
• groups - groups;
• roles - roles.

Creating an entity

To add a new entity to the platform, send the following request

POST /api/v1/:store specifying certain fields.

Creation is available for the following :store:

• models - models;
• objects - objects;
• automatons - logic;
• handlers - handlers;
• labels - labels;
• geofences - geofences;
• messages - messages;
• groups - groups;
• roles - roles;
• tokens - API tokens.

Request template

POST /api/v1/:store

{
  "some_field": "SOME_VALUE",
  "other_field": "OTHER_VALUE"
}

Change Entity

To change the fields of an entity, send a request

PATCH /api/v1/:store/:id specifying the desired fields.

Creation is available for the following :store:

• models - models;
• objects - objects;
• automatons - logic;
• handlers - handlers;
• labels - labels;
• geofences - geofences;
• groups - groups;
• invites - invitations;
• roles - roles.

Request template

PATCH /api/v1/:store:id

{
  "some_field": "NEW_VALUE",
  "other_field": "NEW_OTHER_VALUE"
}

Deleting an entity

To delete an entity, send a request

DELETE /api/v1/:store/:id. The message body is not specified in this case message body is not specified in this case.

Deletion is available for the following :store:

• models - models;
• objects - objects;
• automatons - logic;
• handlers - handlers;
• labels - labels;
• geofences - geofences;
• groups - groups;
• roles - roles;
• tokens - API tokens.