API-документация

Для документирования API используется Swagger.

Swagger-описание — это файл (YAML или JSON), содержащий API-спецификацию.

Для доступа к Swagger необходимо перейти по адресу:

для формирования json-файла: https://<IP_address>/api/v1/swagger.json
для формирования yaml-файла: https://<IP_address>/api/v1/swagger.yaml

где <IP_address> — IP-адрес сервера телефонии IVA CS

Требования для работы с API

Для работы с API на устройстве пользователя должен был установлен какой-либо инструмент, который позволяет отправлять запросы к сервисам и обрабатывать их ответы.

Взаимодействие с API IVA CS будет рассмотрено на примере работы с коллекцией запросов в Postman

Процесс работы с Postman

С помощью Postman можно протестировать корректность работы серверной части IVA CS.

Возможности Postman

сохранять запросы в папки и коллекции
изменять параметры запросов
изменять окружения (dev, test, production)
выполнять автотесты
импортировать и экспортировать коллекции запросов и наборы тестов, чтобы обмениваться данными

Преимущества Postman

поддержка различных API (REST, SOAP, GraphQL)
возможность легкой интеграции в CI/CD с помощью Newman
запуск на любых ОС
поддержка ручного и автоматизированного тестирования

Создание коллекции запросов

Для работы с запросами необходимо создать коллекцию (Collections), в которой они будут храниться.

В коллекцию необходимо импортировать yaml-файл, полученный с сервера IVA CS:

открыть Collections → нажать кнопку Import
вставить ссылку на yaml-файл в строку Paste cURL, Raw text or URL...
дождаться окончания подготовки данных для импортирования
в окне Choose how to import your Specification выбрать Postman Collection и нажать кнопку Import

В Collections будет создана новая коллекция с названием Some title here (название по умолчанию, может быть изменено: Нажать на название коллекции → Нажать Ctrl+E → Ввести новое название коллекции → Нажать Enter)

Для отображения всей API в рабочей области необходимо нажать ссылку View complete documentation

Работа с запросами

При работе с API можно использовать cURL — командную строку для HTTP-запросов

Настройка постоянных переменных

Для удобства работы с API рекомендуется настроить постоянные переменные, которые будут использоваться для авторизации при совершении запросов.

Для создания окружения (Enviroments) необходимо:

открыть вкладку Enviroments и выбрать Globals

добавить переменные окружения:

создать переменную в столбце Variable

задать значение переменной в столбце Value

Variable Value

Variable	Value
url	`https://<IP_address>` где <IP_address> — IP-адрес сервера телефонии IVA CS
login	логин для входа (например, `admin@example.ru`)
password	пароль для входа (например, `admin`)
bearerToken	указать токен доступа

url

https://<IP_address>

где <IP_address> — IP-адрес сервера телефонии IVA CS

логин для входа (например, admin@example.ru)

password

пароль для входа (например, admin)

bearerToken

указать токен доступа

Получение токена доступа (bearerToken)

Для получения токена доступа (bearerToken) необходимо выполнить следующий запрос:

нажать кнопку New → нажать HTTP. В рабочей области будет создан новый запрос Untitled Request
в окне запроса:
- выбрать метод запроса: Get
- в строке запроса Enter URL or paste text ввести URL-запроса: {{url}}/auth/login
- открыть вкладку Body, нажать raw, выбрать JSON и в теле запроса указать следующие данные:
  { "email": "{{login}}", "password": "{{password}}" }
  где,
  - url — переменная url
  - login — переменная login
  - password — переменная password
    
    В качестве переменных используются названия переменных, указанные в столбце Variable
    
    Пример запроса:
нажать кнопку Send

Если запрос был успешно завершен, то в теле запроса (Body) отобразится статус 200 OK.

Пример вывода:

Для получения значения токена bearerToken необходимо скопировать значение параметра "access" (без ") и вставить его в столбец Value в качестве значения переменной окружения bearerToken.

Переменную окружения bearerToken необходимо указывать во вкладке Authorization при совершении запросов:

Authorization → В выпадающем списке Auth Type выбрать Bearer Token → В поле Token вставить {{bearerToken}}

Выполнение запроса

Для выполнения запроса необходимо:

перейти в Collections → открыть созданную коллекцию
выбрать необходимый тип запроса и метод запроса
в окне запроса:
- выбрать метод запроса (по умолчанию метод запроса устанавливается при выборе типа запроса)
- в строке запроса ввести URL-запроса: {{url}}{{baseUrl}}/<NAME_REQUEST> (где <NAME_REQUEST> — название типа запроса)
- открыть вкладку Body, нажать raw, выбрать JSON и в теле запроса указать следующие данные
- открыть вкладку Authorization и убедиться что в качестве типа авторизации установлен Bearer Token
нажать кнопку Send

Если запрос был успешно завершен, то в теле запроса (Body) отобразится статус 200 OK.

Пример выполнения запроса для получения списка абонентов (запрос из коллекции Subscriber):