CPS-1128 Make CPS Core API more restful

Overview

The wiki discusses upon some of the missing API's in CPS core which can be included in future releases and also suggests some changes in the current API implementation to make CPS core API's more Restful.

The second part of this wiki discusses some inconsistencies noticed with the response codes returned by CPS core API's. and how it can be improved.

CPS API that can be added/updated

Jira Ticket- CPS-1128

List of new APIs

1. Get all dataspaces

   URL	GET  http://IP:PORT/cps/api/v1/dataspaces
   Response body	{“dataspace-names”: [“data-space1”,” data-space2”,” data-space3”] }
   Response body(ref. get anchors)	[    {        "dataspaceName": "testDataspace-1"    },    {        "dataspaceName": "testDataspace-2"    },    {        "dataspaceName": "testDataspace-3"    } ]

2. Get single dataspace

   URL	GET   http://IP:PORT/cps/api/v1/dataspaces/<dataspace-name>
   Response body	{    “dataspaceName”:”data-space1” }

3. Get all schema sets for a dataspaces

   URL	GET   http://IP:PORT/cps/api/v1/dataspaces/<dataspace-name>/schema-sets
   Response body (Reference get all dataspaces)	{“schema-set-names”: [“schemaset-1”,” schemaset-1”,” schemaset-1”] }
   Response body (Reference get schema-set)	[ {    "dataspaceName": "testDataspace",    "moduleReferences": [        {            "name": null,            "namespace": "http://example.com/example-2",            "revision": "2021-01-28"        }    ],    "name": "example-1-yang" }, {    "dataspaceName": "testDataspace",    "moduleReferences": [        {            "name": null,            "namespace": "http://example.com/example-2",            "revision": "2021-01-28"        }    ],    "name": "example-2-yang" } ]
   Response body(Reference :get anchors)	[    {        "dataspaceName": "testDataspace",        "schemaSetName": "testSchema"    },    {        "dataspaceName": "testDataspace",        "schemaSetName": "testSchema"    },    {        "dataspaceName": "testDataspace",        "schemaSetName": "testSchema"    } ]

List of existing API's that can be updated

This section discusses on existing API's that can be updated to make them more restful

1. Create multiple root nodes in parallel (ref. Jira- CPS-341)
   

   URL : POST http:// IP:PORT/cps/api/v1/dataspaces/<dataspace-name>/anchors/<anchor-name>/nodes?xpath=/

   Existing request payload	New request payload (ref JSON file in CPS-341)
   { "first-container": {    "a-leaf": "a-value",    "b-leaf": "b-value"   } }	{ "first-container": {    "a-leaf": "a-value",    "b-leaf": "b-value" }, "second-container": {    "x-leaf": "x-value",    "y-leaf": "y-value" }, "last-container": {    "x-leaf": "x-value",    "y-leaf": "y-value" } }

   Note: For get multiple nodes we will use same API for get singular node to return. Can we have new end point for getting all root nodes ‘/nodes’.
   
   

2. Create Dataspace should return JSON response
   

   URL : POST http://IP:PORT/cps/api/v1/dataspaces?dataspace-name=testDataspace

   Current response body	testDataspace
   Current response type	Text/plain
   New response body	{    “dataspaceName”: “testDataspace” }
   New response type	Application/json

3. Create schema-set should return JSON response
   

   URL : POST http://IP:PORT/cps/api/v1/dataspaces/<dataspace-name>/schema-sets

   Current response body	schema-set1
   Current response type	Text/plain
   New response body	{    "dataspaceName": "testDataspace",    "moduleReferences": [        {            "name": null,            "namespace": "http://example.com/example-2",            "revision": "2021-01-28"        }    ],    "name": "example-2-yang" }
   New response type	Application/json

4. Create an anchor should return JSON response
   

   URL : POST http://IP:PORT/cps/api/v1/dataspaces/<dataspace-name>/anchors?schema-set-name=<schema-set-name>&anchor-name=<anchor_name>

   Current response body	anchor-test1
   Current response type	Text/plain
   New response body	{     "name": "testAnchor",    "dataspaceName": "testDataspace",    "schemaSetName": "example-2-yang" }
   New response type	Application/json

5. Create Node should return JSON response
   

   URL:  POST http://IP:PORT/cps/api/v1/dataspaces/<dataspace-name>/anchors/<anchor-name>/nodes?xpath=/

   Current response body	No Content
   Current response type
   New response body	{     "nodeName": "sampleNode",     "anchorName": "testAnchor",      "dataspaceName": "testDataspace" }
   New response type	Application/json

6. Create Node: if leaf list has only one leaf, then don’t force to use [] in request payload?
   

   Current error message:

   Only error code 500 Internal Server Error is returned.

   The logs are as follows

   org.springframework.web.util.NestedServletException: Request processing failed; nested exception is java.lang.IllegalArgumentException: Node (org:onap:ccsdk:sample?revision=2020-09-15)authors is not a simple type

   here authors is name of leaf-list in schema/yang resource

     

   leaf-list authors {
                   type string;
               }

   Sample error message:

   Node (org:onap:ccsdk:sample?revision=2020-09-15)authors in schema is a leaf-list. Data received is of type list (or leaf).

   Note: We need to handle above error and add a leaf list if there is only one leaf in leaf-list without forcing []. Include list as it accepts data without [], so do we need the error or change leaf-list to accept without []

CPS API error responses

As per the discussion with CPS team, it was concluded that the proposal for changing the error code response for following API's is not required at the moment. This decision was made in reference to the research and decisions found at the following Epic CPS Exceptions and REST APIs HTTP Response Codes.  Although an inconsistency was found with the API "Create a Node"  which can be found below at point number 13. 

1. Query a node
   

2. Create Schema Set
   

3. Get a Schema Set
   

4. Delete Schema
   

5. Create Anchor
   

6. Get All Anchors
   

7. Get an Anchor
   

8. Delete an Anchor
   

9. Get a Node
   

10. Delete a Node
    

11. Replace Descendants of a Node
    

12. Update a data node leaves for a given dataspace and anchor and a parent node xpath

13. Create Node

    When an invalid json is passed (for example JSON with missing brackets) API returns 400 Bad Request without details.

    When a valid json is passed with typo (for example JSON having a misspelled key) then returns 500 server error, should return 400 with response message

    API: http://IP:PORT/cps/api/v1/dataspaces/<dataspace-name>/anchors/<anchor-name>/nodes?xpath=/
    Current Error Code	500 Internal Server Error
    Updated Error Code	{    "status": "400 BAD_REQUEST",    "message": "Dataspace not found",    "details": "Dataspace with name XYZ does not exist." }
    Current Error Code	500 Internal Server Error
    Updated Error Code	{    "status": "400 BAD_REQUEST",    "message": "Anchor not found",    "details": "Anchor with name ABC does not exist in dataspace XYZ." }