Imporve api response schema #146

gaohoward · 2024-05-20T03:18:29Z

Currently the api definitions for most apis uses BrokerRespons as the response type.
It is too general. It should use a more specific type schema for each api.

The text was updated successfully, but these errors were encountered:

lavocatt · 2024-05-21T08:05:10Z

I will work on this change this week.

Define a failure response type in the openapi file and harmonise how the api-server answers when an failure has to be fired. (e.g always return the same fields)

SimpleResponse was the answer for the login and was used in several other places. Now there are ApiResponse, DummyResponse and LoginResponse instead that are used throughout the openapi definition.

Transform the BrokersResponse in multiple types in the openapi definition: - Broker - Acceptor - Address - Queue Updates the unit tests accordingly.

ComponentDetails is the new type used to type all the details endpoints.

The component ComponentAttribute types in depth the data return by the two readXXAttributes endpoints.

Add the missing two readAttributes from the queues and acceptors

Add a new set of demo components for jolokia to fetch attributes from the backend. The dev can now test fetching attributes from the broker, the queues, the acceptors and the addresses.

Instead of taking a string as the signature of the operation take an OperationRef object that is easier to use on frontend side.

Add a new component to allow the user to execute any broker operations. Each operation has its own form with a sub form per signature of the function and an execute button. When the user clicks on execute the request gets ran by the jolokia endpoint.

Add a new ExecResult type to correctly type the execution result. This type could be use for other execXXXOperation in the future.

Turn on the openapi validator for the response of the api-server to make sure it is in sync with the openapi definition.

Bring in fully qualified types for the swagger definition. Before Generic types were used. These had for main drawback to prevent us to generate proper types with the codegen to handle data returned by the api-server. The data was there but not named. So code like `OperationResult.Op.listSessions[0].args` wasn't possible. We would have needed to rely on json parsing. In turns meaning custom parsing code here and there with a higher bug exposure. Now that we have fully qualified names, we can rely on the generated typescript types to know what is inside the data we get back from the server. The api-server now needs to perform a few transformations to the data from jolokia in order to be compliant with the return spec. In an ideal world, the spec should have just needed to follow the jolokia output. But some roadblock forced us to consider transforming the data in some ways: * Strings like `org.apache.activemq.artemis:broker="amq-broker` are transformed to a json counterpart: ``` broker: { name: `amq-broker` } ``` * Operations, can be either an object or an array of objects in the jolokia response. The api-server transforms these into array of objects. This is necessary because there's a bug in the way the express-openapi-validator handles the `oneOf` property in the openapi definition. To follow this change of behavior from the api-server, the tests needed to be updated. Last but not least, the api-server validates the output json against the openapi definition too. So we're guaranteed that the result matches what we expect it to be.

Using the new typescrit types it gets possible to create dynamic forms from the ComponentDetails. These forms can be uses to query data for the addresses, acceptors and queues but also execute broker operations. These demo component will be helpful to discover what are the accessible values one can query and what are the available operations one can execute.