| Table of Contents |
|---|
| minLevel | 1 |
|---|
| maxLevel | 4 |
|---|
| outline | false |
|---|
| style | default |
|---|
| type | list |
|---|
| printable | true |
|---|
|
Issues/Decisions
Introduction
There are few inconsistencies and missing features found within the CPS core APIs. This proposal aims to discuss these problems and suggest appropriate solutions for the same. The following list of APIs are found to be impacted by the findings:
Detailed Analysis
Get a Node
Problem Description
...
:
When a list is fetched using Get a node API then instead of returning
...
one list containing n-number of list
...
items, the API returns n-
...
JSON objects where each object contains one list item each.
For example: if there is a list named "Items" containing 10 items named Item 1, Item 2, ......, Item 10. Then when
...
this list is fetched using get a node API a total of 10 individual
...
JSON objects are returned where each
...
object contains one Item
...
xpath: /bookstore/categories[@code=1]/books
Response:
...
...
.
| Child pages (Children Display) |
|---|
| depth | 1 |
|---|
| allChildren | false |
|---|
| style | |
|---|
| sort | title |
|---|
| first | 1 |
|---|
| sortAndReverse | title |
|---|
|
| Expand |
|---|
Data Originally Stored| Code Block |
|---|
{
"book-store:bookstore": {
"bookstore-name": "Easons",
"categories": [
{
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
"lang": "English",
"price": 20
},
{
"title": "The Gruffalo",
"lang": |
|
|
...
"English",
"price": 15
}
]
}
]
} |
|
|
...
| Response when querying the list directly| Code Block |
|---|
[
{
"books": {
"title": "Matilda",
"lang": "English",
"price": |
|
|
...
20
}
},
{
"books": {
"title": "The Gruffalo",
"lang": "English",
"price": 15
}
}
] |
|
|
xpath: /bookstore/categories[@code=1]/books
...
...
[
{
"books": [
{
"title": "Matilda",
"lang": "English",
"price": 20
},
{
"title": "The Gruffalo",
"lang": "English",
|
|
|
...
Initial setup to try the sample requests up ahead
To tryout the sample curl requests below please create a simple bookstore entry in your local CPS deployment. Or just execute the following curl request
| Code Block |
|---|
curl --location 'http://localhost:8883/cps/api/v2/dataspaces/my-dataspace/anchors/bookstore-example/nodes?xpath=%2F' --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: ••••••' --data '{ "bookstore": { "bookstore-name": "Easons", "premises": { "addresses": [ { "house-number": 2, "street": "Main Street", "town": "Maynooth", "county": "Kildare" } ] }, "categories": [ { "code": 1, "name": "Children", "books" : [ { "title": "Matilda", "lang": "English", "authors": ["Roald Dahl"], "editions": [1988, 2000], "price": 20 }, { "title": "The Gruffalo", "lang": "English", "authors": ["Julia Donaldson"], "editions": [1999], "price": 15 } ] }, { "code": 2, "name": "Thriller", "books" : [ { "title": " |
...
Annihilation", "lang": "English", "authors": ["Jeff VanderMeer"], "editions": [2014], "price": 15 } ] } ] } } ' |
Update node leaves
Problem Description
...
...
When updating any data node, it's parent node xpath is provided as part of the update request. And the JSON payload contains the data of child node to be updated.
But
...
due to a user error the parent nodes data can be sent as part of
...
the JSON payload and even then,
...
instead of failing
...
the request is successfully executed with partial update Where only the child data node is updated, and the parent data node is not updated.
...
xpath: /bookstore/categories[@code=1]
...
Original JSON data: | JSON with updates | JSON data after update | Notes |
|---|
| Code Block |
|---|
{
"code": 1,
"name": "Children",
"books": [
{
"title": "Matilda",
"lang": "English",
"authors": ["Roald Dahl"],
"editions": [1988, 2000],
"price": 20
}
]
} |
| |
|
...
|
|---|
{
"code": 1,
"name": "Kids",
"books": [
{
"title": "Matilda",
"editions":
[1988, 2000, 2024],
"price": |
|
|
...
...
...
{
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
"lang": "English",
"authors": ["Roald Dahl"],
"editions":
[1988, 2000, 2024],
"price": 25
|
|
|
...
...
...
| The expected behavior should be to throw an exception as the Update a node API requires parent node xpath to update any child data. Which in this case should be "/bookstore" because the request is also updating the node with key "code=1" This situation can mainly occur due to user error, where user provides updated parent data along with parent node xpath as part of the request.
| Curl request to replicate the scenario| Code Block |
|---|
curl --location --globoff --request PATCH 'http://localhost:8883/cps/api/v2/dataspaces/my-dataspace/anchors/bookstore/nodes?xpath=%2Fbookstore%2Fcategories[%40code%3D1]' --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: ••••••' --data '{
"code": 1,
"name": "Kids",
"books": [
{
"title": "Matilda",
"editions":
[1988, 2000, 2024],
"price": 25
}
]
}' |
|
|
Problem Description 2
Update operation can only be done on one node at a time and when trying to update parent child in one request, then only the parent node is updated.
xpath: /bookstore
...
| Expand |
|---|
Original JSON data | JSON to be updated | Updated JSON data |
|---|
|
...
...
| Code Block |
|---|
{
"categories": {
"code": "1",
"name": "Children",
"books": [
{
"title": "Matilda",
"lang": "English",
"price": 200,
"authors":["Roald Dahl"],
"editions": [1988,2000]
}
]
}
} |
| |
|
...
|
|---|
{
"categories": {
"code": 1,
"name": "Kids",
"books": [
{
"title": "Matilda",
"price": |
|
|
...
20,
"editions":
[1988, 2000, 2022] |
|
|
...
...
...
...
{
"categories": {
"code": "1",
"name": "Kids",
"books": [
{
"title": "Matilda",
|
|
|
...
...
"lang": "English",
"price": 200,
"authors": ["Roald Dahl"],
"editions": [1988,2000] |
|
|
...
...
...
Curl request to replicate the scenario| Code Block |
|---|
curl --location --request PATCH 'http://localhost:8883/cps/api/v2/dataspaces/my-dataspace/anchors/bookstore/nodes?xpath=%2Fbookstore' --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: ••••••' --data '{
"categories": {
"code": 1,
"name": "Kids",
"books": [
{
"title": "Matilda",
"price": 20,
"editions":
[1988, 2000, 2022]
}
]
}
}' |
|
|
Replace a node with descendants
Problem Description
...
...
If a replace operation is performed on a list, where a new list item is also added to the list, then it results in a 200-response code, with a partial replace operation.
| Expand |
|---|
Original JSON data | Data to replace | Result after Replace operation | Notes |
|---|
| Code Block |
|---|
[
{
"book-store:books": {
"title": "Matilda",
"lang": "English",
"price": 20,
"authors": ["Roald Dahl"],
"editions": [1988,2000]
}
}
] |
| | Code Block |
|---|
{
"books": [
{
"title": "Matilda",
"lang": "English",
"authors": ["Roald Dahl"],
"editions": [2024]
},
{
"title": "The Gruffalo",
"lang": "English",
"authors": ["Julia Donaldson"],
"editions": [1999],
"price": 15
}
]
} |
| | Code Block |
|---|
[
{
"book-store:books": {
"title": "Matilda",
"lang": "English",
"authors": ["Roald Dahl"],
"editions": [2024]
}
}
] |
|
|
...
...
...
CPS provides a separate endpoint to Add a list element So, such a scenario should be handled by the API instead of returning a successful response.
| Curel request to replicate the scenario| Code Block |
|---|
curl --location --globoff --request PUT 'http://localhost:8883/cps/api/v2/dataspaces/my-dataspace/anchors/bookstore/nodes?xpath=%2Fbookstore%2Fcategories[%40code%3D1]' --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: ••••••' --data '{
"books": [
{
"title": "Matilda",
"lang": "English",
"authors": ["Roald Dahl"],
"editions": [2024]
},
{
"title": "The Gruffalo",
"lang": "English",
"authors": ["Julia Donaldson"],
"editions": [1999],
"price": 15
}
]
}' |
|
|