Перейти к основному содержимому

Добавить API и создать подключение

С помощью этого руководства вы добавите Swagger спецификацию API в Мапиус и откроете доступ к API потребителю.

Чтобы добавить API и подключиться к нему:

  1. Добавьте поставщика API
  2. Добавьте спецификацию API
  3. Укажите параметры аутентификации API Gateway
  4. Активируйте API
  5. Добавьте потребителя и создайте подключение к API
  6. Подключитесь к API

Добавьте поставщика​

  1. Перейдите в раздел Администрирование → Поставщики API.

  2. Нажмите кнопку Добавить поставщика.

  3. На вкладке Данные заполните обязательные поля в блоках:

    3.1. Бизнес данные:

    • Наименование
    • ГБЛ/ГФЛ (глобальная бизнес линия, глобальная функциональная линия)
    • Информационная система

    3.2. Контактное лицо:

    • Ф.И.О.
    • Адрес электронной почты

  4. (необязательно) Перейдите на вкладку Рабочая группа и добавьте участников

  5. Нажмите Сохранить.

примечание

У информационной системы может быть только один поставщик.

Созданный поставщик будет доступен в разделе Администрирование → Поставщики API.

Добавьте спецификацию API​

внимание

Имя API не должно совпадать с другими в рамках одного шлюза. Проверьте так ли это, перед добавлением API. Имя API - это поле title в вашей спецификации.

  1. Перейдите в раздел Администрирование → API.

  2. Нажмите кнопку Проверить и импортировать API.

  3. Выберите Спецификация в формате Swagger.

  4. Нажмите кнопку Выбрать.

  5. Загрузите описание API.

    Требования к спецификации:

    • Спецификация должна соответствовать стандарту OpenAPI 2.0 или OpenAPI 3.0.
    • Формат: .json или .yaml.
    • Размер файла не более 2МБ.

  6. Нажмите кнопку Проверить. Система проверит файл и сформирует отчет о проверке. При наличии ошибок в описании API, исправьте их и загрузите спецификацию заново.

  7. Нажмите кнопку Перейти к импорту.

  8. Введите версию API.

  9. Под полем ввода выберите Импорт нового API.

  10. Нажмите кнопку Далее.

  11. В выпадающем списке выберите поставщика, которого вы добавили ранее.

  12. Нажмите кнопку Далее.

  13. Укажите адрес сервиса в формате protocol://service-address.ru и базовый путь.

    внимание

    Базовый путь должен быть уникальным в рамках шлюза.

  14. (необязательно) Подключите балансировщик нагрузки:

    14.1. Включите свич Включить балансировку нагрузки. Поле Адрес сервиса заменится на Адрес целевого сервиса.
    14.2. Добавьте все адреса сервиса.

    примечание

    Балансировщик нагрузки использует алгоритм Round-robin.

  15. Нажмите кнопку Импортировать.

Далее откроется окно с добавленной спецификацией API. Не закрывайте его, оно потребуется вам на следующих шагах.

Укажите параметры аутентификации API Gateway​

  1. На вкладке Настройки в разделе Аутентификация выберите:

    1.1. Режим аутентификации: JWT (JSON Web Token)
    1.2. Название заголовка в запросе: sub

  2. В этом же разделе укажите Открытый ключ.

  3. В разделе Конфигурация аутентификации в поле Имя заголовка ключа аутентификации введите Authorization.

  4. На вкладке Расширенные настройки в разделе Прокси поставьте чекбокс Игнорировать проверку TLS.

Активируйте API​

  1. На вкладке Настройки в разделе Ограничение частоты запросов и квоты укажите количество запросов и единицу времени. Если ограничение частоты запросов не требуется, включите свич Отключить ограничение частоты запросов в этом же разделе.
  2. В верхней панели переведите тумблер Активировать API в положение включено.

примечание

Верхняя панель может быть скрыта. Чтобы раскрыть верхнюю панель, нажмите символ слева от вкладки Настройки.

  1. Нажмите кнопку Сохранить.
  2. Подтвердите изменение лимитов.

Справа сверху появится уведомление о том, что описание API сохранено. Проверить активирован ли API можно на странице Администрирование → API. В строке с API в колонке Статус должно быть значение Активен.

Создайте подключение к API​

  1. Перейдите в раздел Администрирование → Подключения.

  2. Нажмите кнопку Добавить.

  3. Выберите поставщика.

  4. Укажите API, который вы добавили ранее.

  5. Добавьте потребителя API:

    5.1. Включите свич Добавить нового потребителя.
    5.2. Заполните поля Информационная система потребителя и Client_id (ТУЗ).

    примечание

    Client_id — это логин из Единой платформы аутентификации или Keycloak. Используйте разные ТУЗ для каждого API.

    5.3. В блоке Рабочая группа ИС потребителя API добавьте в список минимум одного сотрудника. Для этого, нажмите кнопку Добавить и заполните все поля.
    5.4. В блоке Ответственный выберите одного из сотрудников.

    примечание

    Созданный потребитель будет доступен в разделе Администрирование → Потребители.

  6. Задайте лимиты или отключите их.

  7. Нажмите кнопку Подключить.

После создания подключения сгенерируются ключ к API и политика. Ключ будет доступен в разделе Администрирование → Ключи, а политика — Администрирование → Политики.

Подключитесь к API​

  1. Отправьте запрос на сервер и получите JWT-токен. Пример запроса:

    curl --location 'https://auth.YOURDOMAINHERE.ru/auth/realms/kubernetes/protocol/openid-connect/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_id=YOURLOGINHERE@domain.ru' \
    --data-urlencode 'client_secret=YOURSECRETHERE'

  2. Скопируйте значение из поля access_token.

  3. Отправьте запрос к вашему API через API Gateway. Вызовите тот же запрос, что вы использовали ранее но:

    • Поменяйте адрес сервиса на адрес, где развернут API Gateway Мапиус
    • Добавьте в заголовок поле Authorization и укажите в нем полученный ранее JWT-токен

  4. Отправьте запрос

Готово. Вы успешно добавили API в Мапиус и открыли доступ к API потребителю.