HTTP REST API

Версия 1

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

При кодировании все даты и метки времени представляются в виде числа - количеством миллисекунд, прошедших с полуночи (00:00:00 UTC) 1 января 1970 года.

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

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

Сервис работает с учётом принципов REST, так все описанные методы делятся на:

  1. GET - получение информации, без изменения состояния системы
  2. POST, PATCH, DELETE - создание ресурса, обновление, удаление

Коды HTTP

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

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 недоступен пользователю c 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"
  ]
}

Общие принципы

Создание объектов

Для регистрации нового объекта в системе необходимо отправить запрос POST /api/v1/: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.

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

При запросе любого списка объектов максимальное количество отдаваемых объектов составляет 10 000. Последующая выгрузка осуществляется указанием отступа.

Например :store?offset=10000 выгрузит 10 000 объектов начиная c 10 001 включительно.

Параметр limit позволяет задавать ограничение количества выгружаемых объектов.

Например :store?offset=10000&limit=1000 выгрузит 1 000 объектов начиная c 10 001 включительно.

Параметр only позволяет определить список полей для выдачи.

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

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

Пример использования: :store?meta=true.

Для запроса списка объектов созданных, в определенный период используются параметры:

Изменение объекта

Для изменения какого-либо поля объекта необходимо отправить запрос 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.

Аутентификация

Cookie-based

Для авторизации пользователя с использованием механизма 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-based

Для авторизации пользователя с использованием токенов необходимо вызвать метод POST /api/v1/auth/token с указанием собственного логина и пароля. В случае успешной проверки учётных данных, сервер вернёт ответ с кодом 200 и значением изданного токена в поле token. Полученный токен должен добавляться к последующим запроcам в HTTP-заголовке Authorization:

Authorization: Bearer <ACESS 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": "<ACESS 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 секунд. Иначе соединение считается утерянным.

ws-ping

События будут описаны подробнее в соответствующих разделах документации.