Общие принципы формирования запросов
При формировании запросов ключевыми методами являются:
- GET — получение данных из ресурса;
- POST — создание и размещение нового ресурса;
- PATCH — обновление ресурса, добавление одного или нескольких изменений в указанный фрагмент ресурса;
- DELETE — удаление ресурса.
Составляющие части пути запросов:
api/v1
— префикс, с которого начинается путь любого запроса;:store
— тип сущности:- models — модели;
- objects — объекты;
- automatons — логика;
- handlers — обработчики;
- labels — метки;
- geofences — геозоны;
- admin — администрирование проекта;
- links — связи;
- messages — сообщения;
- users — пользователи;
- groups — группы;
- invites — приглашения;
- roles — роли;
- tokens — API токены;
- geo — география.
:id
— идентификатор сущности, который представляет собой строку размером 12 байт (например,58238a935baa56173b24f0e4
). Он назначается системой в момент создания и в дальнейшем не может быть изменен. В API link каждой сущности этот идентификатор хранится в поле_id
.

Получение списка сущностей
Для получения списка сущностей отправьте запрос
GET /api/v1/:store
. Тело сообщения в данном случае не указывается.
Получение списка доступно для следующих :store:
models
— модели;objects
— объекты;automatons
— логика;handlers
— обработчики;labels
— метки;geofences
— геозоны;messages
— сообщения;users
— пользователи;groups
— группы;invites
— приглашения;roles
— роли;tokens
— API токены.
В процессе работы со списками сущностей может возникнуть необходимость в сужении выборки данных. Для этого в строке запроса вы можете указать дополнительные параметры:
offset
При запросе списка сущностей максимальное количество отдаваемых объектов составляет 10000. Для того чтобы выгрузить следующие данные, укажите отступ в параметре offset
.
Например, запрос /api/v1/:store?offset=20000
позволяет получить список из 10000 сущностей, начиная c 20001 включительно.
limit
Для того чтобы задать ограничение на количество выгружаемых сущностей, укажите лимит в параметре limit
.
Например, запрос /api/v1/:store?offset=3&limit=2
позволяет получить список из 2 сущностей, начиная c 4 включительно.
only
Для того чтобы задать список определенных полей для выдачи, укажите список в параметре only.
Например, запрос /api/v1/:store?limit=2&only=name,description
позволяет получить список из 2 сущностей, причем каждая сущность будет содержать только поля _id
(является обязательным), name
и description
.
from и to / begin и end
Для того чтобы запросить список сущностей, созданных в определенный период, укажите нижнюю и верхнюю границу интервала в параметрах from
и to
соответственно. Аналогично данным параметрам могут быть заданы begin
и end
. Границы интервала указываются в виде определенных моментов времени в одном из форматов:
1) Unix time — количество миллисекунд с полуночи (00:00:00 UTC) 1 января 1970 года;
2) ISO 8601 — дата и время в формате YYYY-MM-DDThh:mm.
Например, запросы /api/v1/:store?from=1640131200000&to=1640563200000
и /api/v1/:store?from=2021-12-22T00:00&to=2021-12-27T00:00
позволяют получить список сущностей, созданных в период с 22 по 27 декабря 2021 года.
Получение сущности
Для получения информации по одной сущности отправьте запрос
GET /api/v1/:store/:id
. Тело сообщения в данном случае не указывается.
Получение одной сущности доступно для следующих :store
:
models
— модели;objects
— объекты;automatons
— логика;handlers
— обработчики;labels
— метки;geofences
— геозоны;users
— пользователи;groups
— группы;roles
— роли.
Создание сущности
Для добавления новой сущности в платформу отправьте запрос POST /api/v1/:store
с указанием определенных полей.
Создание доступно для следующих :store:
models
— модели;objects
— объекты;automatons
— логика;handlers
— обработчики;labels
— метки;geofences
— геозоны;messages
— сообщения;groups
— группы;roles
— роли;tokens
— API токены.
Шаблон запроса
POST /api/v1/:store
{
«some_field»: «SOME_VALUE»,
«other_field»: «OTHER_VALUE»
}
Изменение сущности
Для изменения полей сущности отправьте запрос
PATCH /api/v1/:store/:id
с указанием желаемых полей.
Важно: Поле _id
является обязательным для каждой сущности и не может быть изменено подобным образом.
Создание доступно для следующих :store:
models
— модели;objects
— объекты;automatons
— логика;handlers
— обработчики;labels
— метки;geofences
— геозоны;groups
— группы;invites
— приглашения;roles
— роли.
Шаблон запроса
PATCH /api/v1/:store:id
{
«some_field»: «NEW_VALUE»,
«other_field»: «NEW_OTHER_VALUE»
}
Удаление сущности
Для удаления сущности отправьте запрос
DELETE /api/v1/:store/:id
. Тело сообщения в данном случае не указывается.
Удаление доступно для следующих :store:
models
— модели;objects
— объекты;automatons
— логика;handlers
— обработчики;labels
— метки;geofences
— геозоны;groups
— группы;roles
— роли;tokens
— API токены.