Inconstancy between Interface Definitions for PUT / PATCH and OpenAPI Description
sebbader-sap opened this issue · 2 comments
What happens?
The Interface Operations for Post, Put, and Patch , e.g. PutAssetAdministrationShellById, have the output parameter payload as mandatory/cardinality=1.
However, the OpenAPI operation describe the response with 204 (No Content) for Patch and Puts, while Posts, return a 201 AND the whole object.
Why is this wrong?
This is inconsistent with the Interface Operation pattern: Either all API Operations return the object, or the cardinality in the Interface operations is wrong.
How should it be fixed?
Option 1: Change the payload to "optional" (mandatory=false) in the Interface Operations.
Option 2: Change OpenAPI from 204 (No Content) to 200 (OK) and return the objects in the response.
Option 3: Introduce a new design decision in Chapter 12 explaining that Put and Patch have a different behaviour than the one defined in the Interface Operations.
- I have signed the required Developer Certificate of Origin (DCO) already.
I remember from very intense discussions during the API 1.0RC01 / 1.0RC03 discussions that the OpenAPI-described situation is the intended one. I was not able to find any notes from these discussion, though.
Nevertheless, with this as the background, Option 1 is feasible approach. Also regarding the current implementation streams that, correctly (see first sentence), used the OpenAPI files as their reference.
From the task force meeting from 19.03.2024, we agreed on Option 1.