CPS Core Rest API, Replace Node with List Items
- Arpit Singh
- Toine Siebelink
Use Discussion notes to capture meeting items, assign owners, and track actions and decisions.
Issues and Decisions
Date | Item | Owner | Notes | |
|---|---|---|---|---|
| 1 | Jan 15, 2025 |
|
| Action Item |
References
Problem Statement
The CPS Core API: Replace Node can only perform a replace operation on one data node at a time and in order to perform this request the user needs to provide the following parameters as part of the request:
the parent node xpath of the node being replaced
the JSON/XML payload containing the new data which will replace the existing data.
The following endpoint impacted and covered in this document
PUT: /{apiVersion}/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodesScenario 1: API accepts new list items
If a replace operation is performed on a list node, where an already existing list item is being replaced, then in this scenario a user induced error can take place where the user can send a new list item as part of the payload.
This results in a 200-response code being returned to the user but with a partial replace operation.
Because when the data is verified after the replace operation, it is seen that the data of existing list item is replaced, which is the expected behavior. But the data of the new list item is not added under the list node.
But since the API returns a 200-response code, it could create a false sense of security for the user that the request executed successfully, where in fact only a partial operation took place in the database.
A more detailed explanation with examples is as follows:
1. In the following data, the node titled “Matilda",under the list named “books",is to be replaced.
2. In order to do so the correct parent node xpath and JSON payload would be as follows:
3. API accepts extra/new list elements as part of request
If the user modifies an existing list item and along with that adds a new list item in the payload then once the request is executed the user receives a 200-response code.
4. The data queried after the above replace operation is executed is as follows:
It can be seen that only the existing list item, i.e. title: Matilda is replaced. Whereas the newly added list item with title: Book 2 is not added but user received a 200-response code.
Expected Behavior
Based on the RESTful principles a PUT operation should completely rewrite the data in the database with the new data provided in the payload.
So, the expected behavior is to replace all the data of the existing data node and if any new data node is provided as part of the request, then it should be added as a new entity. And the response code should be changed to 204-Created.
Based on the above observations the correct response after data is Replaced should be as follows
Proposed/Accepted Solutions
Proposed Solution
The API should replace the old data entirely with the new data, even when there are new data nodes in the payload.
In case there are new nodes present, the API should return a status code of 204-Created.