Patch Clarifications #312
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -373,7 +373,19 @@ path-suffix= $metadata/$value/$reference/$path or no suffix for normal | |
| ?extent=WithoutBLOBValue/WithBLOBValue | ||
|
|
||
| |PutSubmodel |PUT |/submodel | | ||
| |PatchSubmodel |PATCH |/submodel |path-suffix=/$metadata or /$value | ||
|
|
||
| For /$metadata: + | ||
| The serialised submodel in the request body must not contain any SubmodelElements. + | ||
| The server must overwrite all metadata-relevant Submodel fields with the received fields. This means in particular that previously used fields of the Submodel instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays. In particular, a client must therefore send the complete content of arrays (e.g. for `description` or `displayName`). | ||
|
|
||
| For /$value: + | ||
| The server must overwrite all ValueOnly-relevant Submodel fields with the received values. This means in particular that previously used fields of the Submodel instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays, for instance, for SubmodelElementLists. | ||
|
There was a problem hiding this comment. This seems to be a 1:1 copy from other sections but I think it would be better to write something different and more specific to modifying the value of a submodel. E.g., this text mentions SubmodelElementLists which are not relevant here because we are talking about modifying an array of SubmodelElements without the need to know what the elements are. More important, this won't work becaue valueOnly serialization does not contain all information to "create" new elements. Imaging a submodel without any child elements. Through PATCH on /$value we now send something like There was a problem hiding this comment.
Always open for better proposals There was a problem hiding this comment.
It was the outcome of the last group call to define it like that. Please raise the topic again there, together with a respective formulation, to cover also this case. There was a problem hiding this comment. This is not an issue of how to phrase things but a technical issue that this approach will not work. I don't know what else to tell you or what else to present besides the simple solution I already proposed which is following best practices for REST APIs and just go with RFC 7386 JSON Merge Patch |
||
|
|
||
| ==== | ||
| Note: The endpoint paths without any additional path-suffixes have been deprecated with version 3.1.0 | ||
| ==== | ||
|
|
||
| |GetAllSubmodelElements |GET |/submodel/submodel-elements a| | ||
| ?level=deep/core | ||
|
|
||
|
|
@@ -422,27 +434,28 @@ URL-encoded IdShortPath | |
| |PatchSubmodelElementByPath |PATCH |/submodel/submodel-elements/\{idShortPath} a| | ||
| use separated idShort path of this element | ||
|
|
||
| path-suffix=/$metadata or /$value | ||
|
|
||
| URL-encoded IdShortPath | ||
|
|
||
| For /$metadata: + | ||
| The serialised SubmodelElement in the request body must not contain any values. + | ||
|
|
||
| The server must overwrite all metadata-relevant SubmodelElement fields with the received fields. This means in particular that previously used fields of the SubmodelElement instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays. In particular, a client must therefore send the complete content of arrays (e.g. for `description` or `displayName`). | ||
|
|
||
| For /$value: + | ||
|
There was a problem hiding this comment. Similar to PATCH /submodel/$value, however, for certain cases this potentially might work, e.g. if limited to only work on elements of type There was a problem hiding this comment. This is a broader topic. We currently do not require the server to check whether the value |
||
| The server must overwrite all ValueOnly-relevant SubmodelElement fields with the received values. This means in particular that previously used fields of the SubmodelElement instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays, for instance, for SubmodelElementLists. | ||
|
|
||
| ==== | ||
| Note 1: The endpoint paths without any additional path-suffixes have been deprecated with version 3.1.0 | ||
| ==== | ||
|
|
||
| ==== | ||
| Note 2: See Clause 11.4.2 for values. | ||
| ==== | ||
|
|
||
| ==== | ||
| Note 3: values remain unchanged with content=metadata | ||
| ==== | ||
|
|
||
| |InvokeOperationSync |POST |/submodel/submodel-elements/\{idShortPath}/invoke a| | ||
| path-suffix=$value or no suffix for normal | ||
|
|
@@ -521,7 +534,19 @@ base64url-encoded identifier | |
|
|
||
| |PostSubmodel |POST |/submodels | | ||
| |PutSubmodelById |PUT |/submodels/\{submodelIdentifier} |base64url-encoded identifier | ||
| |PatchSubmodelById |PATCH |/submodels/\{submodelIdentifier} |path-suffix=/$metadata or /$value | ||
|
There was a problem hiding this comment. Same issues as for |
||
|
|
||
| For /$metadata: + | ||
| The serialised submodel in the request body must not contain any SubmodelElements. + | ||
| The server must overwrite all metadata-relevant Submodel fields with the received fields. This means in particular that previously used fields of the Submodel instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays. In particular, a client must therefore send the complete content of arrays (e.g. for `description` or `displayName`). | ||
|
|
||
| For /$value: + | ||
| The server must overwrite all ValueOnly-relevant Submodel fields with the received values. This means in particular that previously used fields of the Submodel instance that are missing in the request body indicate a deletion of them. It is not possible to change single items in contained arrays, for instance, for SubmodelElementLists. | ||
|
|
||
| ==== | ||
| Note: The endpoint paths without any additional path-suffixes have been deprecated with version 3.1.0 | ||
| ==== | ||
|
|
||
| |DeleteSubmodelById |DELETE |/submodels/\{submodelIdentifier} |base64url-encoded identifier | ||
| |SubmodelInterface |* |/submodels/\{submodelIdentifier}/* |superpath as defined in service specification or profile | ||
| | | | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Isn't that classical PUT behavior? How does this differ from PUT?