Устройство API¶
HTTP заголовки запроса¶
Каждый запрос может быть сопровожден следующими заголовками:
Accept - формат данных. Например
Accept: application/json
Authorization - авторизационный токен.
Authorization: OAuth {token}
X-UID - uid пользователя (смотри раздел Внутренние клиенты (TVM))
X-USER-IP - ipv4/ipv6 исходного клиента (смотри раздел Внутренние клиенты (TVM))
X-Request-ID - идентификатор запроса. Не более 60 символов. Валидация по регулярному выражению
^[\w\d-]+$
X-Debug - включение логирования отладочной информации: времени работы определенных участков кода, используемых соединений к базе и т.п.
HTTP заголовки ответа¶
Нужно отметить некоторые заголовки ответа:
Content-Type - всегда
application/json; charset=utf-8
WWW-Authenticate - в случае проблем с авторизацией предоставляет информацию о ошибке для клиентов. Например
WWW-Authenticate: OAuth error='expired_token'
Link - заголовок с информацией для пагинации. Удобно использовать в продвинутых клиентах (например, python-requests)
X-Revision - номер ревизии организации. Сейчас поббержано только в get users
X-Request-ID - идентификатор запроса. Если не передан в момент выполнения запроса, то вернется рандомно сгенерированная строка
Версионирование¶
Нужную версию API можно запросить с помощью указания префикса версии в пути, например: /v2/users/
.
В данный момент по умолчанию отдаётся первая версия ручек (v1
), но в будущем указание номера версии будет требоваться в обязательном порядке.
Формат полей¶
Даты представлены по стандарту iso-8601 в UTC
.
Каждая сущность (пользователь, группа, ресурс…) имеет поле id
, которое уникально в рамках сущностей этого типа. То есть, возможно существование отдела с id=1
и команды с id=1
.
Локализованные поля¶
Warning
Будет отменено к публичной версии API.
Некоторые поля представляют из себя объект с локализованными данными. Ключ такого объекта является сокращенным названием языка, а значение содержет локализованное представление. Например, название департамента:
{
"en": "Content-Services Maintenance Service",
"ru": "Служба эксплуатации контент-сервисов"
}
Дата и время¶
Datetime
поля представлены по стандарту iso-8601 с точностью до микросекунд, и могут включать в себя смещение относительно UTC
. Пример:
{
"created_at": "2016-11-02T16:33:27.482518+03:00",
}
Пример даты без времени:
{
"birthday": "1990-03-02"
}
Пейджинация по результатам¶
Пример ответа по запросу пользователей /users/
:
{
"links": {
"next": "https://dir.yandex.ru/users/page=4&per_page=10",
"prev": "https://dir.yandex.ru/users/page=2&per_page=10",
"last": "https://dir.yandex.ru/users/page=10&per_page=10",
"first": "https://dir.yandex.ru/users/page=1&per_page=10"
}
"page": 3,
"per_page": 10,
"pages": 10,
"total": 100,
"result": [
{
"department": {
"id": 1087,
"name": "Служба IT инфраструктуры датацентров"
},
"email": null,
"name": {
"first": {
"en": "Gennady",
"ru": "Геннадий"
},
"last": {
"en": "Chibisov",
"ru": "Чибисов"
}
},
"gender": "male",
"groups": [],
"id": 110947743,
"nickname": "nogoodi4"
},
...
]
}
links - объект с информацией о пагинации:
page - текущая страница
per_page - какое кол-во объектов выведено на странице
pages - общее кол-во страниц
total - общее кол-во сущностей
result - список сущностей
Пейджинация осуществляется за счёт словаря links
, в котором могут присутствовать ссылки на
следующую и предыдущую страницы, а так же на самую первую и самую последнюю страницы.
Эти же ссылки доступны и в HTTP заголовке Links
, а некоторые http библиотеки, например
python-requests,
умеют работать с этим заголовком.
Выборка вложенных объектов¶
Warning
В публичной версии API вложенные объекты не будут раскрываться по умолчанию и надо будет явно указать, что нужно раскрыть какое-то поле.
Все вложенные объекты должны по возможности раскрываться. Например, у пользователя есть список групп. Они будут выведены раскрытым списком объектов:
{
...
"email": "web-chib@ya.ru",
"groups": [
{
"id": 30141,
"name": {
"en": "Males",
"ru": "Мужчины"
}
},
...
]
...
}
В случае, если вложенный объект сам по себе содержит вложенный объект, то его не нужно раскрывать. Например, у пользователя есть департамент. Его нужно раскрыть. Но у самого департамента есть родительский департамент. Его нужно показать как идентификатор:
{
...
"email": "web-chib@ya.ru",
"department": { // объект департамента раскрыт
"id": 181,
"name": {
"en": "Group of entertainment services development",
"ru": "Группа разработки развлекательных сервисов"
},
"parent_id": 100 // объект следующей вложенности не раскрыт
},
...
}
В случае указания идентификатора объекта название атрибута должно оканчиваться на _id
. Например parent_id
.
Установка вложенных объектов¶
Установка связей с одних объектов с другими должна осуществляться через указание их идентификаторов. Например так, можно при создании пользователя указать id отдела, в котором он должен состоять:
POST /users/
{
...
"email": "web-chib@ya.ru",
"department_id": 181
...
}
Атрибут, содержащий идентификатор вложенного объекта, должен заканчиваться на _id
.
Если вложенный объект представляет из себя список объектов, то атрибут должен заканчиваться на _ids
:
PUT /users/
{
...
"email": "web-chib@ya.ru",
"group_ids": [1,2,3]
...
}
Фильтры¶
Фильтры списка сущностей должны осуществляться указанием GET
параметров. В случае фильтрации по вложенным объектам
название этих параметров должно оканчиваться на _id
:
/users/?department_id=1
Некоторые ресурсы поддерживают фильтрацию сразу по нескольким значениям одного атрибута. Для этого необходимо
перечислить значения через запятую, не изменяя названия параметра. Отношение в выборке между каждым значением OR
.
Ниже представлен пример выборки “вывести пользователей с департаментом 1 ИЛИ 2”:
/users/?department_id=1,2
В случае указания нескольких фильтрующих параметров отношение между ними AND
.
Ниже представлен пример выборки “вывести пользователей с (департаментом 1 ИЛИ 2) И (идентификатором 2 или 3)”:
/users/?department_id=1,2&id=2,3
Сортировка¶
При запросе списка сущностей можно указать порядок сортировки с помощью GET-параметра ordering
:
/departments/?ordering=name
Список полей, по которым можно сортировать данные можно узнать в описании конкретной ручки. Для обратной сортировки нужно указать название поля со знаком -
, например:
/departments/?ordering=-id
Можно указать список полей для сортировки через запятую:
/departments/?ordering=name,id
Если будет указано неподдерживаемое имя поля для сортировки, API вернет ошибку с кодом 422.
Ошибки¶
В случае ошибок ручки возращают ответ с HTTP кодом >= 400. В теле ответа содержится более подробная информация об ошибках:
{
"code": "some_error_happened",
"message": "Something happened with {obj} object",
"params": {
"obj": "The User",
}
}
При этом, params может отсутствовать, если ``message`` не содержит
плейсхолдеров, типа ``{obj}``.
Возможные коды ошибок, и их расшифровки описаны в разделе `Ошибки API`_.