Inconsistencies with PUT requests in superpaths

[mjacoby]

What is the issue?

According to the specification there are the following API calls ralted to PUT a submodel:

• Submodel Interface PutSubmodel "Replaces the Submodel" , optionally returning the Submodel (cardinality=1, mandatory=false)
• SubmodelRepository Interface PutSubmodelById "Creates a new or replaces an existing Submodel", optionally returning the Submodel (cardinality=1, mandatory=false)

For AAS it follows the same pattern

• AssetAdministrationShell Interface PutAssetAdministrationShell "Replaces the Asset Administration Shell", optionally returning the AssetAdministrationShell (cardinality=1, mandatory=false)
• AssetAdministrationShellRepository Interface PutAssetAdministrationShellById "Creates or replaces an existing Asset Administration Shell", optionally returning the AssetAdministrationShell (cardinality=1, mandatory=false)

In the OpenAPI documentation for the complete API are following mappings of these operations:

• PUT /submodel returns 204 No Content
• PUT /submodels/{submodelIdentifier} returns 201 Created and the submodel as body

For AAS it follows mostly the same pattern but there are some minor differences

• PUT /aas returns 204 No Content or 201 Created with AAS as body
• PUT /shells/{aasIdentifier} returns 201 Created and the aas as body or 204 No Content

Why is this wrong?

The OpenAPI definition is inconsistent in two ways

1. The two submodel calls behave differently although they are, to my understanding, essentially the same call, at least in the SubmodelRepository interface because there no longer is a seperate /submodel call because of superpaths.
2. API for submodels (one call returns 204 and the other 201) is different than for AAS (both calls can return both 201 and 204)

How should it be fixed?

Apply the pattern used for AAS also for submodels, i.e., change PUT /submodel and PUT /submodels/{submodelIdentifier} to both support create and update and therefore return 201 resp. 204.

• I have signed the required Developer Certificate of Origin (DCO) already.