Додавання генерації POST-методів для пошуку даних

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

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

При поточній реалізації з виконанням GET-запитів для пошуку даних, виникли проблеми з пошуком по типу IN/NOT_IN.

Вони пов’язані з неможливістю коректно обробити випадок, коли приходить запит типу GET /search?inParam=value1,value2 , де параметр inParam є єдиним значенням value1,value2, а не масивом значень ["value1", "value2"]. Подібні структури в запиті Spring Web фреймворк парсить саме як масив [value1, value2].

В якості воркераунду можливим виявилось формувати запит у форматі GET /search?inParam=value1,value2&inParam=. В такому випадку Spring формує параметри у масив ["value1,value2", ""], що є коректним для пошуку за типом IN/NOT_IN.

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

Такими сценаріями є:

Проте для сценаріїв, де запити пошуку даних формуються програмно всередині мікросервісів системи, таких як:

  • виставлення ендпоінтів пошуку даних через Трембіту (через soap-api)

  • використання ендпоінтів пошуку даних через делегати у бізнес-процесах (через bpms)

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

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

2. Загальні принципи та положення

  • GET і POST ендпоінти мають генеруватись разом

  • Для внутрішніх інтеграцій всередині системи перейти на використання POST

  • Використання GET методів залишається для зворотньої сумісності при використанні клієнтами сценаріїв Пошук з UI-форм, Публічний API та Інтеграція з зовнішніми системами

  • Використання POST-методів для сценаріїв Публічний API та Інтеграція з зовнішніми системами стане можливим

  • Використання POST-запитів для пошуку даних не впливає на сценарії модифікації даних, де також використовується метод POST (залишаються актуальними усі Network Policy, а також перевірка HTTP-заголовків при збереженні даних)

  • Перехід UI-форм на використання POST методу наразі не потребується та є поза скоупом

3. Високорівневий план розробки

3.1. Приклад

Для критерію пошуку

<changeSet author="registry owner" id="create SC registration_equal_laboratory_id_solution">
    <ext:createSearchCondition name="some_sc">
        <ext:table name="some_table" alias="r">
            <ext:column name="some_id" />
            <ext:column name="some_equal_column" searchType="equal"/>
            <ext:column name="some_in_column" searchType="in"/>
        </ext:table>
    </ext:createSearchCondition>
</changeSet>

разом з існуючим GET-ендпоінтом повинен згенеруватись POST

Новий API

3.2. Технічні експертизи

  • BE

3.3. План розробки

Компонент

Необхідне розширення

Мета

service-generation-utility

додати генерацію POST ендпоінтів пошуку даних

виклик нових ендпоінтів з soap-api та bpms

service-generation-utility

змінити генерацію коду soap-api на відправку запитів до rest-api, перейти на POST

уникнути проблем з виставленням SC з пошуком через IN/NOT_IN через Трембіту

service-generation-utility

змінити AuthPolicy для зовнішніх інтеграцій з rest-api-ext, дозволити обробку POST для ендпоінтів пошуку даних (не має впливати на ендпоінти модифікації даних)

можливість викликати POST ендпоінт для сценарію Пошук даних без Трембіта

rest-api-core-base-image

для пошукових POST запитів прибрати валідацію специфічних заголовків (X-Digital-Signature, X-Source-Business-Process etc.)

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

bpms

змінити делегати пошуку (DataFactoryConnectorSearchDelegate, RegistryDataFactoryConnectorSearchDelegate), додавши можливість приймати як параметр пошуку Map<String, Object> (зараз - Map<String, String>)

для коректного пошуку за типом IN у POST запиті необхідно буде передати список допустимих значень, вони відправляться з bpms як string ключ - list значення. Не має виникнути проблем зі зворотньою сумісністю, оскільки Map<String, Object> є ширшим, ніж поточне Map<String, String>

ddm-data-factory-client

оновити Feign-клієнти, які використовуються делегатами, на POST метод

використання в bpms клієнту

platform-gateway

додати обробку POST-запитів пошуку замість GET

оскільки сценарій пошуку без Трембіти перемикається на POST метод, у проксі-сервісі platform-gateway теж необхідно перемкнутись на обробку запитів саме цього методу

Також важливим є документування функціональності:

  • Задокументувати особливості використання GET-методів при пошуку з IN/NOT_IN

  • Задокументувати рекомендації щодо формування тіла POST запиту (особливо при пошуку IN/NOT_IN)