Adding POST methods generation for data retrieval

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. General overview

In the current implementation, issues have arisen with searching data using GET requests, specifically related to the IN/NOT_IN type of search.

These problems are associated with the inability to correctly handle cases where a request of the form GET /search?inParam=value1,value2 is received, where the parameter inParam is a single value value1,value2, rather than an array of values ["value1", "value2"]. Spring Web framework parses such structures in the request as an array [value1, value2].

As a workaround, it became possible to format the request as GET /search?inParam=value1,value2&inParam=. In this case, Spring constructs the parameters as an array ["value1,value2", ""], which is valid for searching with the IN/NOT_IN type.

However, the use of such a workaround is only feasible for cases where the client can explicitly configure the HTTP request with the necessary search parameters in the correct format.

These scenarios include:

However, for scenarios where data search requests are generated programmatically within microservices of the system, such as:

This functionality is specific to the Ukrainian implementation and may not apply or function as described in other contexts or regions. Please consult the local guidelines or documentation if you are implementing this outside Ukraine.

  • Setting up data search endpoints through Trembita (UA-specific) secure exchange gateway (via soap-api)

  • Using data search endpoints through delegates in business processes (via bpms)

The existing workaround cannot be applied, or it will create significant issues for the development and maintenance of such a solution, potentially leading to blocking problems within development teams.

To address such issues, it was decided that in addition to generating a GET interface for data search, a POST interface should also be generated. When using the POST interface, the required search parameters will be formatted in the request body in JSON format, which allows for a proper differentiation between individual values and arrays.

2. General principles and provisions

  • GET and POST endpoints should be generated together

  • For internal integrations within the system, transition to using POST is recommended

  • The use of GET methods remains for backward compatibility when used by clients in scenarios such as Search with UI forms, Public API, and Integration with external systems.

  • The use of POST methods for scenarios involving Public API and Integration with external systems will become possible.

  • The use of POST requests for retrieving the data does not affect scenarios involving data modification, where the POST method is also used (all Network Policies remain valid, and HTTP header checks during data saving remain applicable).

  • Transitioning UI forms to use the POST method is currently not required and is beyond the scope

3. High-level development plan

3.1. Example

For the search criterion:

<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>

Together with the existing GET endpoint, a POST should be generated:

New API

3.2. Technical expertise

  • BE

3.3. Development plan

Component

Required extension

Goal

service-generation-utility

Add generation of POST endpoints for data search

Invoke new endpoints with soap-api and bpms

service-generation-utility

Change generation of soap-api code to send requests to rest-api, transition to POST

Avoid issues with setting up SC for IN/NOT_IN search through Trembita

service-generation-utility

Modify AuthPolicy for external integrations with rest-api-ext, allow handling of POST for data search endpoints (should not affect data modification endpoints)

Enable calling POST endpoint for Data search without Trembita scenario.

rest-api-core-base-image

Remove validation of specific headers (X-Digital-Signature, X-Source-Business-Process etc.)

In the current implementation, header validation is set based on the HTTP method, not the invoked endpoint. With the new approach, this logic needs to be changed

bpms

Modify search delegates (DataFactoryConnectorSearchDelegate, RegistryDataFactoryConnectorSearchDelegate), adding possibility to accept Map<String, Object> as a search parameter (now - Map<String, String>)

For proper IN type search in POST request, a list of valid values will need to be passed. These will be sent from bpms as a string key - list value. There should be no compatibility issues, as Map<String, Object> is broader than the current Map<String, String>.

ddm-data-factory-client

Update Feign clients used by delegates to use POST method

Use in bpms client

platform-gateway

Add handling of POST search requests instead of GET

As the Trembita-less search scenario switches to POST, the proxy service platform-gateway also needs to switch to handling requests of this method

It is also important to document the functionality:

  • Document the specifics of using GET methods for IN/NOT_IN search

  • Document recommendations for forming the body of a POST request (especially for IN/NOT_IN search)