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

Для управления ресурсами в API определены стандартные методы, позволяющие добавлять, получать, изменять и удалять ресурсы.

1 Получение списка ресурсов
2 Добавление ресурса
3 Получение ресурса
4 Изменение ресурса
5 Удаление ресурса

https	Название	Путь

https	Название	Путь
GET	получение списка ресурсов	/realm/{realm_id}/resource/
POST	добавление ресурса	/realm/{realm_id}/resource/
GET	получение ресурса по идентификатору	/realm/{realm_id}/resource/{resource_id}
PUT	изменение ресурса	/realm/{realm_id}/resource/{resource_id}
DELETE	удаление ресурса по идентификатору	/realm/{realm_id}/resource/{resource_id}

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

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.

В целях успешного выполнения запросов обратите внимание на наличие завершающего слеша "/" в адресах URL в запросах POST, PUT, GET c использованием массивов данных или его отсутствие в случаях, если отправляются запросы GET, PUT, DELETE с единичным объектом

← Правила запросов к API Ресурсы системы →