Inconstancy between Interface Definitions for PUT / PATCH and OpenAPI Description

[sebbader-sap]

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.

[sebbader-sap]

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.

[sebbader-sap]

From the task force meeting from 19.03.2024, we agreed on Option 1.

[mjacoby]

related to PR #312

[sebbader-sap]

fixed with v3.0.2