В данном разделе описана общая структура API, форматы запросов и ответов

Запросы к API осуществляются через протокол HTTPS, для авторизации используется протокол OAuth2, после получения токена через OAuth2, он передается в каждом API-запросе в заголовке Authorization. (См. Авторизация приложений).

При наличии тела запроса (запросы типа POST и PUT), его содержимое должно быть передано в формате JSON, заголовок Content-Type должен быть установлен в application/json. Исключение составляет загрузка файлов, например, звуковых файлов.

Методы для работы с ресурсами

Параметры пути

realm

Раздел API. Определяет набор доступных ресурсов и операций над ними. Определяется типом авторизованного пользователя. Может принимать значения

• client (соответствует пользователю типа "клиент")
• extension_group (соответствует пользователю типа "группа добавочных")
• extension (соответствует пользователю типа "добавочный"

Пользователь вышестоящего уровня может использовать ресурсы нижестоящего уровня. Например пользователь уровня "клиент" может использовать ресурс "GET /extension/{extension_id}/phone/"

realm_id

Идентификатор ресурса, к которому привязан авторизованный пользователь. Для пользователя типа "клиент"(/user/client/) - идентификатор ресурса /client/, для пользователя типа "группа добавочных"(/user/extension_group/) - идентификатор /extension_group/, для пользователя типа "добавочный"(/user/extension/ ) - идентификатор (/extension/).
Если realm и тип авторизованного пользователя совпадают, то в качестве  realm_id может выступать значение "@me". Например, пользователь типа "добавочный" может сделать запрос "GET /extension/@me/phone/", а для пользователя типа "клиент" этот запрос будет некорректен.

Для запросов на ресурсы раздела "добавочный" существует возможность вместо идентификатора добавочного указывать его имя в формате @extension_name:

• Имя добавочного в полном формате с префиксом клиента: GET /extension/@1844*101/phone/
• Имя добавочного в сокращенном формате: GET /extension/@101/phone/
  

resource

Название ресурса, например event или record.

resource_id

Уникальный идентификатор ресурса.

Некоторые ресурсы могут не содержать в пути realm и realm_id. Такие ресурсы не зависят от типа клиента, их использующего, например /timezone/ для получения списка поддерживаемых временных зон.

Набор методов не всегда полный и зависит от ресурса. 

Получение списка ресурсов

Запросы на получение списка ресурсов осуществляются запросом типа GET. В ответе возвращается JSON-массив, содержащий ресурсы. Если ресурсы отсутствуют или ни один из ресурсов не подходит под условия фильтрации (см. ниже), возвращается пустой массив.

HTTP-код ответа при успешной операции: 200.

Фильтрация

Многие запросы на получение списка ресурсов имеют дополнительные параметры запроса, которые указываются в строке запроса после символа "?". Эти параметры позволяют отфильтровать список, возвращаемый запросом по одному или нескольким полям.
Например, запрос ниже позволяет пользователю типа "клиент" получить список добавочных номеров типа "телефон", которые состоят в группе добавочных с идентификатором 1:

GET https://hostname/api/ver1.0/client/@me/extension/?extension_group_id=1&type=phone

Добавление ресурса

Новые ресурсы добавляются запросом типа POST, тело запроса – JSON-документ, содержащий параметры ресурса. Параметры могут быть обязательными и необязательными. Во втором случае, параметр ресурса примет значение по умолчанию. Некоторые параметры допускают значение null, которое означает отсутствие значения параметра.

HTTP-код ответа при успешной операции: 201. В случае успеха операции возвращается созданный ресурс. 

В случае неправильных параметров возвращаемый ответ имеет код 400, а телом ответа является JSON-документ, описывающий причину ошибки в поле message. Если поле message содержит сообщение "Bad Request", то ошибка заключается в формировании JSON-документа.

Получение ресурса

Получение конкретного ресурса по его идентификатору осуществляется запросом типа GET, при этом идентификатор ресурса содержится в URL, например пользователь типа "клиент" может получить данные о ресурсе "extension" с идентификатором "2"

GET https://hostname/api/ver1.0/client/@me/extension/2

HTTP-код ответа при успешной операции: 200. При этом возвращается ресурс в формате JSON-документа. В случае, если ресурс не найден, код ответа будет 404.

Изменение ресурса

Изменение (обновление) ресурса по его идентификатору осуществляется запросом типа PUT, при этом идентификатор ресурса содержится в URL.

Тело запроса, JSON-документ, содержащий параметры, которые требуется изменить. Параметры, не переданные в запросе, не изменяться.

HTTP-код ответа при успешной операции: 200. В случае успеха операции возвращается обновленный ресурс. Если ресурс отсутствует, код ответа будет 404.

В случае неправильных параметров возвращаемый ответ имеет код 400, а телом ответа является JSON-документ, описывающий причину ошибки в поле message.

Удаление ресурса

Получение конкретного ресурса по его идентификатору осуществляется запросом типа DELETE, при этом идентификатор ресурса содержится в URL.
HTTP-код ответа при успешной операции: 204. Если удаляемый ресурс отсутствует, код ответа будет 404.

Структура частей документации, описывающих ресурсы

• краткое описание назначения ресурса
• оглавление
• подробное описаниее параметров ресурса
• примеры использования
• формальное описание всех методов ресурса для:
  • раздела пользователей типа "клиент"
  • раздела пользователей типа "группа добавочных"
  • раздела пользователей типа "добавочный"
• теги по теме