HTTP REST API

API представляет собой программный интерфейс, который позволяет использовать функционал продукта в ходе обращения ко внешним системам. В данном случае, API платформы предоставляет возможность работы, взаимодействия и использования сущностей платформы и их данных в таких внешних системах, как CRM, ERP, веб-порталы, мобильные и веб-приложения и др.

Версия 1

Текущая версия API соотносится с версией 1. Обмен данными происходит при помощи закодированных в json сообщений по протоколам HTTP и WebSocket. Путь всех методов HTTP имеет префикс api/v1.

Каждый объект системы имеет собственный идентификатор ObjectId формата bson (24 шестнадцатеричных символа, например, 58238a935baa56173b24f0e4), который хранится в поле _id. Идентификатор назначается системой и присваивается ресурсу в момент его создания. Он не может быть изменен в дальнейшем, так как идентификация объектов и переход по ссылкам на них происходят по их идентификаторам.

Идентификатор сущности можно просмотреть в меню "Администрирование", во вкладке "Редактирование". При выборе конкретной сущности в левом верхнем углу будет отображен идентификатор данной сущности. Если кликнуть на него, то на отдельной странице будет открыта конфигурация сущности с указанием всех ее полей и их значений.

scheme

Помимо идентификатора, у всех объектов системы присутствуют четыре поля:

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

Внешние сервисы могут взаимодействовать с платформой посредством использования API платформы. Для этого формируются HTTP-запросы на стороне клиента и отправляются на сторону сервера, которая постоянно прослушивается. Когда запрос обработан, от веб-сервера на сторону клиента обратно приходит ответ, информирующий о состоянии выполнения запроса.

При формировании запросов для взаимодействия с платформой ключевыми методами являются:

При этом для всех методов всегда указываются только два HTTP-заголовка, приведенных в таблице ниже.

Заголовок Назначение
Content-Type: application/json Задается формат и способ представления сущности. В системе платформы все сущности сформированы в формате json, в котором они отображаются на графическом интерфейсе плаформы во вкладке "Код", задаются в HTTP-запросе и приводятся в ответе от сервера
Authorization: Bearer {token} Указываются данные для авторизации. Для передачи токена в запросе через заголовок применяется HTTP-схема Bearer, после наименования которой указывается изданный токен. Токен может быть издан через личный кабинет в разделе "Токены".

Реализация и фактическое применение данных методов описаны ниже.

Создание сущности

Для регистрации новой сущности в системе необходимо отправить запрос POST /api/v1/:store с указанием определенных полей. В префиксе :store указывается наименование сущности. Поля указываются в теле запроса, соответственно, могут быть указаны только необходимые пользователю. Однако стоит учитывать, что для некоторых сущностей существуют обязательные поля.

Запрос

POST /api/v1/:store HTTP/1.1
Content-Type: application/json

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

Получение сущности

Для получения сущности необходимо отправить запрос GET /api/v1/:store/:id. В данном запросе в префиксе :id указывается идентификатор сущности ObjectId, присвоенный ему системой. Тело сообщения указывать не нужно.

Работа со списками

В процессе работы с HTTP API платформы, получения и отправке данных посредством его использования может возникнуть необходимость в сужении выборки данных, к которым пользователь имеет доступ, в выборе более конкретной или, наоборот, более общей информации о сущностях системы. С этой целью в стартовой строке запроса могут быть указаны определенные параметры и их значения, позволяющие сузить или же расширить выборку.

При запросе любого списка сущностей максимальное количество отдаваемых объектов составляет 10000. Последующая выгрузка осуществляется с указанием отступа. Например, :store?offset=10000 выгрузит 10000 сущностей, начиная c 10001 включительно.

Параметр limit позволяет задавать ограничение по количеству выгружаемых объектов. Например, :store?offset=10000&limit=1000 выгрузит 1000 сущностей, начиная c 10001 включительно.

Параметр only позволяет определить список полей для выдачи. Например, :store?offset=10000&limit=1000&only=name,description выгрузит 1000 сущностей, начиная c 10001 включительно. При этом каждая сущность будет содержать только поля _id, так как оно является обязательным, name и description.

Параметр meta позволяет получить общее количество сущностей в коллекции, первую и последнюю сущность. Данный параметр нельзя использовать вместе с offset и limit. Пример использования: :store?meta=true.

Для запроса списка объектов созданных в определенный период используются параметры from и to - нижняя и верхняя граница интервала. Аналогично данным параметрам могут быть заданы параметры begin и end. Они имеют эквивалентное значение.

Для каждого из двух данных параметров указываются определенные моменты времени, которые могут быть заданы либо в формате Unix Timestamp, либо в формате ISO 8601. В первом случае указывается количество миллисекунд, прошедших с полуночи (00:00:00 UTC) 1 января 1970 года. Во втором случае в явном виде задаются дата и время с учетом формы YYYY-MM-DDThh:mm.

Пример

GET /api/v1/:store?from=1567285200000&to=1567285300000 HTTP/1.1

В приведенном примере будет возвращен список сущностей, введенных вместо префикса :store, с указанием всех необходимых полей. Использование данных временных параметров может оказаться полезным, если возникает необходимость в получении пакетов данных и обращении к ним.

Изменение сущности

Для изменения какого-либо поля сущности необходимо отправить запрос PATCH /api/v1/:store/:id с указанием желаемых полей. Стоит учитывать, что существуют поля, которые являются обязательными для каждой сущности и не могут быть изменены подобным образом. В их числе _id, access, owner, group, branch.

Запрос

PATCH /api/v1/:store/:id HTTP/1.1
Content-Type: application/json

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

Удаление сущности

Для удаления сущности необходимо отправить запрос DELETE /api/v1/:store/:id без указания дополнительных HTTP-заголовков и полей в теле запроса.

Аутентификация и авторизация

Авторизация с использованием Cookies

Для авторизации пользователя с использованием механизма HTTP Cookies необходимо вызвать метод POST /api/v1/auth с указанием собственного логина и пароля. В случае успешной проверки учетных данных сервер вернет ответ с кодом 200 и заголовком Set-Cookie. В нем будет указан идентификатор сессии и время ее истечения. Идентификатор этой сессии указывается в последующих запросах к сервису в заголовке Cookie с учетом указанного времени. После истечения срока действия сессии необходим повторный вызов метода POST /api/v1/auth.

Запрос

POST /api/v1/auth HTTP/1.1
Content-Type: application/json

{"login":"<API USER LOGIN>","password":"<API USER PASSWORD>"}

Ответ

HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: sid=<SESSION ID>; Path=/; Expires=Thu, 1 Jan 2015 00:00:00 GMT; HttpOnly

{"sucess":true}

Авторизация с использованием Token

Для авторизации пользователя с использованием токенов необходимо вызвать метод POST /api/v1/auth/token с указанием собственного логина и пароля. В случае успешной проверки учетных данных сервер вернет ответ с кодом 200 и значением изданного токена, указанного в поле token.

Полученный токен должен добавляться к последующим запроcам в HTTP-заголовке Authorization:

Authorization: Bearer <ACCESS TOKEN VALUE>

Запрос

POST /api/v1/auth/token HTTP/1.1
Content-Type: application/json

{"login":"<API USER LOGIN>", "password":"<API USER PASSWORD>"}

Ответ

HTTP/1.1 200 OK
Content-Type: application/json

{
  "sucess": true,
  "type": "access",
  "token": "<ACCESS TOKEN VALUE>",
  "issuedAt": 1494594580646,
  "expiresAt": 1494680980646
}

WebSocket

После проведения аутентификации может быть отправлен запрос сессии WebSocket. Для этого на адрес /socket.io/?EIO=3&transport=websocket посылается запрос по протоколу WSS c заголовками Connection:Upgrade и Cookie.

В установленное WebSocket-соединение придет сообщение типа 0 с параметрами соединения вида: 0{"pingInterval":25000,"pingTimeout":60000}

Согласно этому сообщению, клиент должен раз в 25 секунд посылать сообщение типа 2, на что сервер должен посылать сообщение типа 3 в течение 60 секунд, иначе соединение считается утерянным.

scheme

Коды состояний HTTP

В ответе, полученном от веб-сервера, помимо версии HTTP всегда отображается код состояния, который описывает результат выполнения отправленного на сервер запроса. Среди всех существующих кодов состояний выделяют пять классов, каждый из которых формирует определенную группу информативных сообщений в зависимости от текущего состояния выполнения запроса. Соответственно, кодов состояний, а вместе с тем и возможных ответов от сервера существует большое количество. Ниже приводятся четыре наиболее часто встречаемые.

В случае успешного исполнения HTTP-запроcа сервис ответит сообщением с кодом 200. При этом в HTTP-заголовке будет указан размер содержимого сущности в байтах, а в теле сообщения - данные ответа.

HTTP/1.1 200 OK
Content-Length: ~

{"sucess":true}

В случае если перед вызовом метода не была произведена аутентификация или полученная ранее сессия истекла, сервис ответит ошибкой с кодом 401.

HTTP/1.1 401 Unauthorized
Content-Length: ~

{
  "success": false,
  "code": "401",
  "message": "Unauthorized",
  "tags": [
    "error_unauthorized"
  ]
}

Когда HTTP-метод недоступен пользователю с предоставленными ему настройками доступа API, сервис ответит ошибкой с кодом 403.

HTTP/1.1 403 Forbidden
Content-Length: ~

{
  "success": false,
  "code": "403",
  "message": "Forbidden",
  "tags": [
    "error_credentials",
    "error_forbidden"
  ]
}

В случае если пользователь запросил несуществующий ресурс, сервис ответит ошибкой с кодом 404.

HTTP/1.1 404 Not Found
Content-Length: ~

{
  "success": false,
  "code": "404",
  "message": "Not Found",
  "tags": [
    "error_not_found"
  ]
}