Подходы к REST API (rest / v1)

Схема API запроса к REST

Формат url path
/rest/v1/<CHAPTER>/<RESOURCE_PATH>

  • v1 – версия обратной совместимости раздела API;

  • <CHAPTER> – название раздела;

  • <RESOURCE_PATH> – путь в дереве ресурсов до endpoint’а, например /selectors/<SELECTOR_ID>/participants/<PARTICIPANT_ID>.

Базовые принципы

  • Имена коллекций в множественной форме (анг. plural);

  • Коллекции всегда содержат элементы одного типа;

  • Использование HTTP Verbs для операций создания/чтения/обновления/удаления (CRUD).

POST коллекции

Создает новый ресурс в коллекции и возвращает его в ответ на запрос.
В качестве тела запроса передается новый создаваемый ресурс в формате JSON (Content-Type: application/json) или JSON в параметре data (Content-Type: appication/x-www-form-urlencoded).
Состав полей должен включать все обязательные поля и может включать идентификатор.
В качестве ответа возвращается созданный ресурс, включающий значения автоматически сгенерированных полей.

Формат запроса
POST /rest/v1/<CHAPTER>/.../<COLLECTION> HTTP/1.1
Content-Type: application/json; charset=utf-8

<resource>
Формат успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

<resource>

GET коллекции

Возвращает список ресурсов из коллекции с ограниченным набором полей.
Может с помощью параметров быть дополнительно отфильтрован (filter), отсортирован (order), разделен на страницы (offset, limit), сужен состав возвращаемых полей (mask), преобразован формат выдачи (flat).

Формат запроса
GET /rest/v1/<CHAPTER>/.../<COLLECTION> HTTP/1.1
Формат успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  <resource>,
  <resource>,
  ...
]
Table 1. Параметры
Название Тип значения Описание

filter

object

Фильтр элементов по значениям полей. Задается в виде json структуры.
Будут возвращены ресурсы только с указанными значениями.
Если параметр не указан будут выведены все данные.

Примеры:

  • filter={"id":"some_id","name":"some_name"}

  • filter={"id":"some_id","opts":{"a":"some_value":}}

  • filter={"id":"some_id","opts.a":"some_value"}}

Поддерживает поисковые условия для строк:

  • "abc" – точное соответствие;

  • "a%bc%" – произвольная строка, начинающаяся на "a" и содержащее "bc" внутри;

  • "ab|cd|ef" – точное соответствие либо "ab", либо "cd", либо "ef";

  • "/reg/abc.+" – регулярное выражение: произвольная строка, содержащая "abc" и еще один символ;

  • "/reg/i/^abc.*" – регулярное выражение: произвольная строка, начинающаяся на "abc","ABC","aBC" и т.д.;

  • "/reg//a/bc$" – регулярное выражение: произвольная строка, заканчивающаяся на "a/bc".

Поддерживает поисковые условия для чисел:

  • 3 – точное значение числа;

  • 3.01 – точное значение числа;

  • "3.01" – точное значение числа;

  • "1~35" – диапазон значений числа из отрезка [1,35];

  • "~-5.01;-2~5;15~" – диапазон значений числа из множества (-inf,-5.01] U [-2,5] U [15,+inf).

Поддерживает поисковые условия для значений типа bool: false, 1, true, "true", "tRUe" и т.д.

Для списочных полей использует критерий включения списка из фильтра в список из значения: ["ab","cd"]

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

Альтернативно может использоваться формат фильтра, аналогичный /rest/v1/model.

  • filter=["==",["property","status"],"initial"]

  • filter=["or",["and",["in",["property","status"],["list",initial","active"]],[">",["property","count"],10]]]

  • filter=["equals",["integer",["property","rawMessage","attachments",0,"sticker","images",0,"height"]],64]

order

array<object|str>

Сортировка ресурсов в указанном порядке. Применяет последовательность полей, где по каждому определено направление сортировки, при совпадении значений применяет следующее поле.

Примеры:

  • order=[{"state":"desc"}]

  • order=[{"priority":"desc"},{"name":"asc"}]

  • order=["priority","name"]

mask

str

Список полей ресурса, подлежащих выдаче. По умолчанию выводятся все поля.
Допускается указывать композитные поля как целиком, так и с указанием интересующих вложенных опций через точку вне зависимости от значения параметра flat.

Примеры:

  • mask=id,name,ext

  • mask=id,name,ext.ct,ext.lwt

offset

int

Смещение при выдаче. Порядковый номер с нуля в отфильтрованном (filter) и отсортированном списке ресурсов (order), начиная с которого следует производить выдачу. Обычно используется совместно с параметром limit для постраничного вывода.

Пример:

  • offset=2

limit

int

Максимальное количество ресурсов, подлежащее выдаче из отфильтрованного (filter), отсортированного (order) и смещенного (offset) списка ресурсов. Обычно используется совместно с параметром offset для постраничного вывода. Если limit=0, то возвращает информацию о количестве обнаруженных элементов без применения параметра offset.

Пример:

  • limit=2

flat

bool

Преобразование в плоский вид: значения в виде набора опций раскрываются в вид ключей первого уровня:

"opts":{"a":true,"b":10} => "opts.a":true,"opts.b":10

Пример:

  • flat=true

countonly

bool

При установке значения true возвращается лишь количество обнаруженных ресурсов.

Пример возвращаемого значения:
{
  "count": 5
}

Пример: count=true

export

bool

При установке значения true объект возвращает значения полей в том виде, в котором они могут быть в дальнейшем импортированы.

Пример возвращаемого значения:
{
  "id": "e7adf0aa-05b7-8163-948c-3392a9660db9",
  "name": "Administrator",
  "login": "admin",
  "pwd": "ha_v=1;0307030703070309BFB39B099674A...",
  "timezone": "default",
  "opts":{
    "allow_script_crud": true,
    "roles":["admin", "crud", "scripteditor", "monitor"]
   }
}

Пример: export=true

GET ресурса

Возвращает конкретный ресурс. С помощью параметров может быть сужен состав возвращаемых полей (mask) и преобразован формат выдачи (flat).

Формат запроса
GET /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
Формат успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

<resource>
Table 2. Параметры
Название Тип значения Описание

mask

str

список полей для вывода. Задается перечисление полей. Если параметр не указан будут выведены все поля.
Пример: mask=id,name

flat

bool

преобразование в плоский вид.
Пример: flat=true

PUT ресурса

Изменяет ресурс с указанным идентификатором в коллекции полной заменой. Идентификатор заменить невозможно.
В качестве тела запроса целиком передается новый ресурс.

Применяется в основном для размещения файлов с указанным именем.

Формат запроса
PUT /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
Content-Type: application/json; charset=utf-8

<resource>
Формат fallback-запроса
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!put HTTP/1.1
Content-Type: application/json; charset=utf-8

<resource>
Формат успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

<resource>

PATCH ресурса

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

Формат запроса
PATCH /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
Content-Type: application/json; charset=utf-8

<resource>
Формат fallback-запроса
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!patch HTTP/1.1
Content-Type: application/json; charset=utf-8

<resource>
Формат успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

<resource>

DELETE ресурса

Удаляет ресурс с указанным идентификатором из коллекции. В содержании ответа ничего не возвращается.

Формат запроса
DELETE /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1
Формат fallback-запроса
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!delete HTTP/1.1
Формат успешного ответа
HTTP/1.1 204 No Content

Специфические методы

Выполняет указанный специфический метод над указанным ресурсом. Целевой ответ в формате JSON: значение, ресурс или коллекция. Параметры также специфические для каждого метода.

Формат запроса
<CUSTOM_METHOD> /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID> HTTP/1.1

Например, LOOKUP /rest/v1/iam/users HTTP/1.1.

Формат fallback запроса
POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!<CUSTOM_METHOD> HTTP/1.1

Например, POST /rest/v1/iam/users!lookup HTTP/1.1.

Часто используемые специфические методы коллекций

  • lookup – производит поиск ресурса в коллекции по ключевым (уникальным) указанным параметрам, возвращает идентификатор подходящего ресурса. Идентификатор используется в EndPoint ресурса.

Fallback запросы

Могут применяться в качестве дублеров при невозможности выполнения HTTP-методов PUT, PATCH, DELETE, HEAD.
Fallback url строится на основе endpoint’a с добавлением символа “!” после идентификатора ресурса или коллекции. Метод запроса – POST.

Формат fallback запроса
POST /rest/v1/<CHAPTER>/.../<COLLECTION>!<FALLBACK_SUFFIX> HTTP/1.1

POST /rest/v1/<CHAPTER>/.../<COLLECTION>/<ENTITY_ID>!<FALLBACK_SUFFIX> HTTP/1.1

  • FALLBACK_SUFFIX - целевой метод в нижнем регистре. Возможные значения:

    • put – для PUT

    • patch – для PATCH

    • delete – для DELETE

    • head – для HEAD

    • по аналогии для любых специфических методов (например, SWITCH <EndPoint> → POST <Endpoint>!switch)

Content-type в запросах

Content-Type запросов:

  • multipart/form-data и application/octet-stream для файлов;

  • application/json для ресурсов;

  • application/x-www-form-urlencoded для ресурсов, предполагает наличие параметра data, содержащего целевой ресурс.

Table 3. Возможные content-type запросов
HTTP Verb Content-Types

POST

  • application/json

  • application/x-www-form-urlencoded

  • multipart/form-data

  • application/octet-stream

PUT

  • application/json

  • application/x-www-form-urlencoded

  • multipart/form-data

  • application/octet-stream

PATCH

  • application/json

  • application/x-www-form-urlencoded

DELETE

  • No Content

  • application/json

  • application/x-www-form-urlencoded

Специфические методы и POST для их fallback-вариантов

  • application/json

  • application/x-www-form-urlencoded

  • multipart/form-data

  • application/octet-stream

Схема API ответа REST

Формат ошибочного ответа

Формат
{
  "error_code" : <INTERNAL_CODE>,
  "error_message" : <INTERNAL_MESSAGE>,
  "error_details" : <INTERNAL_DETAILS>
}

  • <INTERNAL_CODE> - внутренний(системный) код ошибки (int).

  • <INTERNAL_MESSAGE> - описание ошибки (str).

  • <INTERNAL_DETAILS> - опциональный атрибут, содержащий дополнительные параметры ошибки (object), например {"field": "name"}

Table 4. Возможные коды ошибок
HTTP code error_code Описание

400 Bad Request

Ошибка в параметрах запроса

401 Unauthorized

1401

Требуется аутентификация

403 Forbidden

1401

Доступ к ресурсу/endpoint запрещен

404 Not Found

1401

Ресурс/endpoint не найден

409 Conflict

1402

Ресурс уже существует

422 Unprocessible entity

1405

Указанные параметры ресурса не могут быть применены

500 Internal Server Error

1409

Ошибка сервера при обработке запроса

Content-type в ответах

Content-Type ответов:

  • application/json для выдачи ресурсов, в том числе ошибки, и файлов .json с соответствующим типом содержимого);

  • application/octet-stream для выдачи файлов в ответ на запрос на скачивание (с параметром GET-запроса attachment=1);

  • прочие mime-types для выдачи файлов в соответствии с их расширениями.

Table 5. Возможные content-type ответов
HTTP Verb Content-Types

GET

  • application/json

  • произвольный mime-type для файла

POST

  • application/json

PUT

  • application/json

PATCH

  • application/json
  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт