Inconsistencies with CPS Core API's

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:

Get a node
Update node leaves
Replace a node with descendants

Detailed Analysis

Get a Node

Problem Description

Current output

Expected Result

Notes

When a list is fetched using Get a node API then instead of returning a list containing n-number of list nodes, the API returns n-lists containing one data node in each list.

For example: if there is a list named "Items" containing 10 items named Item 1, Item 2, ......, Item 10. Then when fetching this list using get a node API a total of 10 individual lists are returned where each list contains one Item, i.e. List 1→Item 1, List 2→ Item 2, ......., List 10→ Item 10.

xpath: /bookstore/categories[@code=1]/books

Response:

[
  {
    "books": {
      "lang": "English",
      "price": 20,
      "title": "Matilda"
    }
  },
  {
    "books": {
      "lang": "English",
      "price": 15,
      "title": "The Gruffalo"
    }
  }
]

xpath: /bookstore/categories[@code=1]/books

Expected Response:

[
  {
    "books": [
      {
        "lang": "English",
        "price": 20,
        "title": "Matilda"
      },
      {
        "lang": "English",
        "price": 15,
        "title": "The Gruffalo"
      }
    ]
  }
]

This behavior extends to list items stored under root node as well. So, this case needs to be taken into consideration as well

Update node leaves

Problem Description

Existing Data

Data to be updated

Result after Update operation

Notes

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 if the JSON data of the parent node is provided as part of this payload, 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:

{
  "code": 1,
  "name": "Children",
  "books": [
    {
      "title": "Matilda",
      "lang": "English",
      "authors": ["Roald Dahl"],
      "editions": [1988, 2000],
      "price": 20
    }
  ]
}

JSON with updates

{
  "code": 1,
  "name": "Kids",
  "books": [
    {
      "title": "Matilda",
      "editions": 
		[1988, 2000, 2024],
      "price": 200
    }
  ]
}

JSON data after update

[
  {
    "code": "1",
    "name": "Children",
    "books": [
      {
	 	"title": "Matilda",
        "lang": "English",
        "authors": ["Roald Dahl"],
        "editions": 
			[1988, 2000, 2024],
		"price": 200       }
    ]
  }
]

It can be seen that the updated data of parent node i.e. code=1 is sent as part of JSON body. Where name is changed from Children to Kids
And the fields editions and price, of child node, i.e. title=Matilda are modified.
But after the request is executed only the child node is updated.
The expected behavior should be to throw an exception as the Update a node API requires parent node xpath to update any data. Which in this case should be "/bookstore" because the request is also updating the node with key "code=1"

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

Original JSON data

{
  "categories": {
    "code": "1",
    "name": "Children",
    "books": [
      {
	 	"title": "Matilda",
        "lang": "English",
        "price": 200,
        "authors":["Roald Dahl"],
        "editions": [1988,2000]
      }
    ]
  }
}

JSON to be updated

{
  "categories": {
    "code": 1,
    "name": "Kids",
    "books": [
      {
        "title": "Matilda",
        "editions": 
		[1988, 2000, 2022],
        "price": 20
      }
    ]
  }
}

Updated JSON data

{
  "categories": {
    "code": "1",
    "name": "Kids",
    "books": [
      {
        "title": "Matilda", 
		"editions": [1988,2000]
     	"lang": "English",
        "price": 200,
        "authors": ["Roald Dahl"], 
      }
    ]
  }
}

The request is executed successfully but only a partial update takes place in the database.
So, either the API should reject any request containing multiple nodes or support updating multiple nodes at once.

Updating multiple list items is possible in one request is possible. And there is no need to provide the entire list instead particular leaves of multiple list items can be updated in a single request.

Replace a node with descendants

Problem Description

Existing Data

Data to replace

Result after Replace operation

Notes

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.

[
  {
    "book-store:books": {
	  "title": "Matilda",
      "lang": "English",
      "price": 20,
      "authors": ["Roald Dahl"],
      "editions": [1988,2000]
    }
  }
]

{
  "books": [
    {
      "title": "Matilda",
      "lang": "English",
      "authors": ["Roald Dahl"],
      "editions": [2024]
    },
    {
      "title": "The Gruffalo",
      "lang": "English",
      "authors": ["Julia Donaldson"],
      "editions": [1999],
      "price": 15
    }
  ]
}

[
  {
    "book-store:books": {
	  "title": "Matilda",
      "lang": "English",
      "authors": ["Roald Dahl"],
      "editions": [2024]
    }
  }
]

The user request here is itself wrong, as it tries to add a new list element. But such a scenario should be handled by the API instead of returning a successful response.