Versions Compared

Old Version 15

changes.mady.by.user Dmitri Savolainen

Saved on

compared with

New Version 16

changes.mady.by.user Роман Сухов

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

Table of Contents

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

Названиеhttps запроспутьпараметры пути
получение списка ресурсовGET/realm/{realm_id}/resource/
  • realm (раздел) определяет набор доступных ресурсов и операций над ними. Определяется типом авторизованного пользователя. Может принимать значения
    • 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/", а для пользователя типа "клиент" этот запрос будет не корректен 
  • resource название ресурса
  • resource_id уникальный идентификатор ресурса
добавление ресурса 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 и realm_id. Такие ресурсы не зависят от типа клиента, их использующего, например /timezone/ для получения списка поддерживаемых временных зон.

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

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

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

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

Фильтрация

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

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

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

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

...

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

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

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

...


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

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

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

...

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

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

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

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

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