OpenAPI Output Design
OpenAPI as output by the wizard
OpenAPI output by the wizard is currently centered on generating one OpenAPI spec (OAS) for one message model version. The OpenAPI Spec generated is still an experimental feature, so keep that in mind when using the generated spec/ Also, any feedback is welcome.
It takes the JSON Schema generated for that message model as a starting point. It adds meta-information and it adds three operations: Post, Get and Put. The below picture shows an overview of the generated OAS as visualized by the 'editor-next' of swagger.io. So what users can do, is copy the output of the wizard OAS tab, into the editor-next window.
3 Operations
We generate 3 operations: a Post, Get and Put request. Roughly speaking, this stands for creating a new resource, retrieving an existing resource, and fully updating a resource that already exists. For example, a company can offer to create a new invoice using the API, retrieve an existing invoice, or fully update an existing invoice, using this OpenAPI spec. Designers who take the outgoing OpenAPI spec can remove any of the actions that are not applicable for their use case.
All of these operations include the notion of an identifier, so we discuss this topic next.
Identifier choice
REST operations require an identifier for a given message. Usually in REST operations the maintainer of a certain resource gives out this identifier after receiving a new resource creation. That party delivers the identifier of the newly created resource, back to the party who made the original request for the resource to be created.
So, the communications of this type of message can only happen when an agreed upon Identifier is shared between the parties. In Semantic Treehouse, we currently have no special indicator of the chosen identifier for a type of message. Of course there are Identifiers in the schemas of most messages, but there is no special annotation for which of the identifiers is the chosen one to use in the REST operations. The OpenAPI designer has to choose the identifier and has to clearly indicate this in the description of the API.
Use the OpenAPI Specification to configure an IDS connector (Work In Progress)
International Data Spaces (IDS) connectors can be generated from OpenAPI Spec files. When you're logged in to Semantic Treehouse, there is a specific URL for each message model version that directly offers the OpenAPI json. This is an example for a message model version that has internal Identifier "Message_2de0220c-7f22-4320-8c46-0ff658ace731":
https://tno.semantic-treehouse.nl/api/v1/fit/message/Message_2de0220c-7f22-4320-8c46-0ff658ace731/openapi
Calling that URL with a valid Session cookie will give the JSON format OpenAPI spec that the IDS Data Connector Generator App needs to build a connector. Note that most of the time, the metadata like Server Information needs to be edited before the Data Connector Generator App makes a useful IDS Connector out of the spec.
Open API best practice guidelines
The Dutch center for Standards has made a succinct, practical overview of best practices for any Open API, and we chose to incorporate some of these practices in the list. It is still a work-in-progress. The table below shows the status of implementation for each of these guidelines, note that the nubering scheme has gaps, but the table is complete for version 1.0 of the guidelines. Note that some are Not Applicable(N/A), so out of scope for the wizard generator.
| Rule | Status | Remark |
|---|---|---|
| API-01: Adhere to HTTP safety and idempotency semantics for operations | V | |
| API-02: Do not maintain session state on the server | N/A | |
| API-03: Only apply standard HTTP methods | V | |
| API-04: Define interfaces in Dutch unless there is an official English glossary available | N/A | Not applicable: Is up to the modeler to implement, may use Dutch names for resrouces. TODO include description of Spec (Message Model) in Paths. |
| API-05: Use nouns to name resources | N/A | Not applicable: Is up to the modeler |
| API-06: Use nested URIs for child resources | N/A | |
| API-10: Model resource operations as a sub-resource or dedicated resource | N/A | Applies to advanced operations that do not fit into CRUD, like Approve |
| API-16: Use OpenAPI Specification for documentation | V | Check is no errors in editor-next |
| API-17: Publish documentation in Dutch unless there is existing documentation in English | X | Not wanted |
| API-18: Include a deprecation schedule when publishing API changes | TODO Add placeholder for deprecation schedule. | |
| API-19: Schedule a fixed transition period for a new major API version | IDEM: TODO Where to place API policy change. | |
| API-20: Include the major version number in the URI | V | We provide example API, Is API version same as data model version? TODO Could be derived from OAS version, ie message model version. |
| API-48: Leave off trailing slashes from URIs | V | Done |
| API-51: Publish OAS document at a standard location in JSON-format | V | TODO Add File path routing for /openapi.json |
| API-53: Hide irrelevant implementation details | V | |
| API-54: Use plural nouns to name collection resources | X | Difficult to implement |
| API-55: Publish a changelog for API changes between versions | TODO New placeholder needed. | |
| API-56: Adhere to the Semantic Versioning model when releasing API changes | N/A | To be done by organisation. |
| API-57: Return the full version number in a response header | TODO |