Налаштування доступу до публічних даних реєстру

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

1. Загальний опис

Сторонні системи та користувачі мають можливість отримувати публічну інформацію з реєстру в актуальному стані, обробляти та візуалізувати її без автентифікації, використовуючи публічні точки доступу API.

Цей документ складається з двох основних частин: створення та публікація точок доступу на рівні регламенту реєстру та налаштування доступу на рівні конфігурації реєстру.

2. Сценарії використання

Платформа надає наступну функціональність для роботи із публічними даними у реєстрі:

  • Публікація пошукових запитів

  • Конфігурація ресурсів публічного API

  • Створення точок інтеграції для публічного API технічним адміністратором реєстру

  • Отримання документації та використання публічного API

  • Моніторинг стану та використання публічних пошукових критеріїв

  • Зміна рейт-лімітів для наявних точок інтеграції

3. План дій з налаштування та використання

Скористайтеся наступним планом дій для налаштування та використання публічних API у реєстрі:

Налаштування на рівні регламенту:
Налаштування на рівні конфігурації реєстру:

4. Моделювання регламенту

  1. Відкрийте Адміністративний портал та створіть версію-кандидат.

    Детальніше про це читайте на сторінці Створення запитів на внесення змін.

  2. Перейдіть у Таблиці > Файл опису структури та додайте новий changeset із критерієм пошуку (Search Condition).

    expose public api 1

  3. Визначте, який саме пошуковий критерій ви хочете зробити публічним. Для цього додайте новий changeset із тегом exposeSearchCondition та атрибутом publicAccess.

    <exposeSearchCondition publicAccess="true" name="vpo_person_type_contains_name_public_test"/>
    Більш детально про exposeSearchCondition — див. Тег налаштування доступу до API реєстру.

    Рекомендуємо налаштувати посторінкову пагінацію (тип page) для управління відображенням повернутих з exposeSearchCondition даних (count). Також налаштуйте limit до кількості даних реєстру, які повертаються у відповіді.

    Дізнайтеся більше про limit та pagination у наступних розділах документації:

  4. Перейдіть до наступного розділу для публікації моделі даних у регламенті.

5. Публікація API у регламенті

Опублікуйте модель даних, застосувавши зміни до майстер-версії регламенту. API-точка доступу до даних буде згенерована на базі кожного визначеного пошукового критерію.

Детальніше про публікацію змін до регламенту читайте у розділі Застосування змін до майстер-версії.

6. Перегляд опублікованих API у Swagger

Після успішного проходження всіх етапів публікації, можна переглянути внесені пошукові запити, які доступні для публічного доступу, в OpenAPI-специфікації. Для цього:

  1. Перейдіть до вебінтерфейсу управління кластером OpenShift.

  2. Оберіть проєкт із вашим реєстром, відкрийте Networking > Routes та перейдіть за посиланням до сервісу platform-gateway-kong-proxy.

    Обов’язково додайте в кінець URL-адреси /openapi, інакше ви потрапите до sandbox-середовища із pet-точками доступу. Ваш URL у браузері має виглядати так:

    https://example.com/api/public/data-factory/openapi

  3. Відкрийте openapi та знайдіть опубліковані публічні точки доступу.

  4. Скопіюйте ім’я ендпоінту до буфера обміну та перейдіть до наступного кроку налаштувань.

    expose public api 2

Для зменшення навантаження на сервіс Kong API Gateway, для посилань до API-документації, для GET-запитів встановлюється TTL-based кешування. Відповідь кешується за допомогою плагіну proxy-cache.

Налаштувати значення кешу можна на рівні конфігурації плагіну через Gerrit. Значення за замовчуванням — 15 хв.

Кеш зберігається в пам’яті API Gateway.

7. Налаштування доступу до публічних даних

7.1. Налаштування доступу до публічних даних та встановлення рейт-лімітів

Відкрийте доступ до публічних даних та налаштуйте рейт-ліміти.

  1. Увійдіть до адміністративної панелі Control Plane.

  2. На вкладці Інформація про реєстр знайдіть секцію Публічний доступ.

  3. Натисніть кнопку Надати доступ.

  4. У новому вікні заповніть поля:

    • Службова назва запита: введіть службову назву запита. Наприклад, city-lab.

    • Точка інтеграції: вкажіть точку інтеграції, налаштовану розробником регламенту на етапі Моделювання регламенту та опубліковану в сервісі API реєстру. Наприклад, /search-laboratories-by-city.

    • Встановіть рейт-ліміти на доступ — кількість запитів від користувачів/систем за одиницю часу. Наприклад, за годину, місяць тощо.

  5. Натисніть кнопку Надати.

    expose public api 3

  6. Перейдіть до секції Запити на оновлення, відкрийте та підтвердьте новий запит. Запропоновані зміни будуть застосовані до налаштувань реєстру у файлі deploy-templates/values.yaml.

    expose public api 5

    Див. детальніше про підтвердження змін на сторінці Підтвердження запитів на внесення змін до реєстру.

    Після налаштування, конфігурація реєстру матиме такий вигляд:

    publicApi:
  - name: vpo-person-type-test
    url: /vpo-person-type-contains-name-public-test
    limits:
        second: 5
        hour: 100
    enabled: true
  - ...

    Після виконання пайплайну розгортання, публічний доступ до даних через вказаний API-ендпоінт буде відкритий.

7.2. Перевірка роботи публічного доступу

  1. Відкрийте браузер у режимі Інкогніто й вставте скопійоване у розділі Перегляд опублікованих API у Swagger посилання на доданий пошуковий запит.

    expose public api 6

  2. Неавтентифікований користувач/система отримає дані у форматі JSON.

    expose public api 6 1

    При досягненні ліміту, формується відповідь від API Gateway з кодом 429 та тілом

    { "message": "API rate limit exceeded" }

7.3. Керування доступом

  1. Редагуйте точки інтеграції та рейт-ліміти: ::

    1. Натисніть на іконку редагування 🖉 біля відповідного запита.

    2. Внесіть необхідні зміни та підтвердьте їх.

      expose public api 7

  2. Заблокуйте доступ натисканням іконки блокування 🔒. Технічно це означатиме призупинення доступу до певного API-ендпоінту.

    Доступ можна відновити, натиснувши на розблокування (повторний клік на заблокований елемент 🔒).

    expose public api 7 1

  3. Анулюйте доступ повністю натисканням іконки видалення 🚫.

    Після кожної дії перевірте та підтвердьте застосування змін у секції Запити на оновлення.
Якщо видалити наявні точки інтеграції або тимчасово вимкнути їх, користувач отримає повідомлення про помилку HTTP 404 при спробі доступу.

Зміна іконок статусу навпроти публічного API у секції Публічний доступ означає, що створений запит на оновлення застосовано до master-гілки, а внесені зміни потрапили до файлу конфігурації реєстру — deploy-templates/values.yml. Щоб перевірити успішність застосування змін і коректність налаштованого доступу до публічних ендпоінтів, технічний адміністратор реєстру повинен перевірити статус пайплайну master-гілки.

8. Моніторинг показників у Grafana

Платформа має Grafana-дашборд, призначений для моніторингу показників виконання і кількості запитів до публічних точок інтеграції від неавтентифікованих користувачів і сторонніх систем.

expose public api 4

Технічний адміністратор реєстру може користуватися даними з дашборду для відстеження динаміки й стану показників. Ці дані можуть допомогти у визначенні потреби в оптимізації налаштувань, таких як коригування лімітів на запити.

Детальну інформацію щодо моніторингу ви можете переглянути на сторінці Моніторинг метрик публічного API.

9. Створення сервісного облікового запису для виконання публічних запитів

Попри те, що формально точки інтеграції є публічними, для підтримання однорідності аудиту та логування в середині Платформи, такі запити будуть здійснюватись від імені службового користувача із Keycloak-реалму external-system. Система автоматично створить службового користувача public-user для авторизації на рівні platform-gateway.

Переконайтеся, що такий системний користувач створений у відповідному реалмі сервісу Keycloak. Для цього:

  1. Відкрийте сервіс автентифікації та авторизації Keycloak

  2. Знайдіть реалм -external-system для вашого реєстру.

  3. Відкрийте меню Clients > public-user.

© 2023 Платформа Реєстрів.