[Request] Add functionality to support exports to other types of APIs. Example: AsyncAPI

[Kostadin-Ivanov]

Is your task related to a problem? Please describe. For our projects, we want to create standard models for general RESTful APIs and AsyncAPIs. Currently we can use only exports to OpenAPI which as described in request: [Request] Add customization of OpenAPI exports is quite Digital Twin Registry focused.y

Could we have option to support other types of APIs by the API generation functionality. An example would be AsyncAPIs.

Describe the solution you'd like Best option would be if a user can provide some king of an API template and then SDK can build corresponding API, either OpenAPI, AsyncAPI or others, based on this template. Other solution would be if the export functionality, has a parameter: --api-type or similar which user can use to set the required API type from a list with supported APIs.

Describe alternatives you've considered N/A

Additional context Not available, but if required we can further discuss this and eventual implementation.

[chris-volk]

Dear @Kostadin-Ivanov , we have now designed the solution that we will implement: The java SDK will support AsyncAPI with MQTT using one topic per Aspect since Aspects are modular and the right standard "level of scope" for a topic. The topic structure will be well-defined to allow a hard-coded generation and easy tool support and let clients rely on this standard structure. The supported message format will be JSON only to reuse the existing SAMM JSON payload mapping in close alignment with the existing OpenAPI spec generation. Due to a lack of necessity, we will, at least initially, not realize the AsyncAPI concept of Operations, which could in the future be mapped to SAMM operations. For each message, a SAMM Event will be required so that it is possible to generate AsyncAPI in a unique way from the Aspect Model. Please note that this approach is flexible and covers very case:

Event triggers

Can be defined as required, e.g. onChange/interval based/other triggers

Payload choices

Can be defined as required, see as follows with example diagrams from the Movement example

• only one property (the "affected" property by e.g. a change)

• one Event for each property

• one Event for the entire Aspect

• other structure of Events, e.g. for certain properties that wrap Entities or to express entirely different relations as Events, e.g. in the Movement Aspect "when the current speed to exceeds the speed"

publication of Events via Aspect Model

With this approach, it is required to model Events before using AsyncAPIs in a conformant way, however this is still a flexible approach:

• One can create a new version of an existing Aspect with the desired Event structure which then applies to everyone using the new version of the Aspect Model
• One can also define a new "event capable" Aspect which reuses elements of an existing Aspect if it is believed that the original Aspect should or cannot be changed (e.g. standard catena-x model without Events). using this "AsyncAspect refers to non-event-Asepct" pattern, multiple parties could create different AsyncAspects for their choices. However, where possible it is recommended to use the previous approach which standardizes the events that can be triggered on an Aspect as part of itself (standardize this part of the semantics as well)

[github-actions[bot]]

Release v2.7.0 addresses this.