RU

Общие принципы формирования запросов

При формировании запросов ключевыми методами являются:
  • GET — получение данных из ресурса;
  • POST — создание и размещение нового ресурса;
  • PATCH — обновление ресурса, добавление одного или нескольких изменений в указанный фрагмент ресурса;
  • DELETE — удаление ресурса.
Составляющие части пути запросов:
  • api/v1 - префикс, с которого начинается путь любого запроса;
  • :store - тип сущности:
  • :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 токены.