CPS Exceptions and REST APIs HTTP Response Codes

1

treatment of incorrect dataspace, schemaset (names) 

These are core concept of CPS and should be correct/exists (except in create use cases of course)

1. Introduce specific exception for each extending new CPSAdminException class

2. re-use same exception in API (pass through)

3. Treat as bad URL in REST interface

CPS Team Meeting 3 Dec

2

Using different HTTP Response code (400 v 404) depending on type of operation, adding data/requesting data

It might make sense to use 404 Not Found in a get scenario (ie like #3 scenario in the table below) 
But this would be wrong in a create/add data scenario. The Java API throws the same Exception so the REST Impl would need additional code to handle this distinction

Use 400 Bad requests in both scenarios for the following reasons

• Consistency 

• Simplicity of handling in REST Layer

• HTTP error codes are always ambiguous, we will add documentation for each REST call anyway to specify which errors are used in which scenario

CPS Team Meeting 3 Dec

1

Add dataspace

dataspace already exists

DataIntegrityViolationException

DataspaceAlreadyDefinedException

DataspaceAlreadyDefinedException

400 (bad request)

json error object

dataspace xyz already defined

Add schema set to dataspace

schema set with same name already exists

DataIntegrityViolationException

SchemaSetAlreadyDefinedException

SchemaSetAlreadyDefinedException

400 (bad request)

json error object

schema set xyz already defined for dataspace abc

Add schema set to dataspace

dataspacename does not exist

No records (Optional, not present)

DataspaceNotFoundException

DataspaceNotFoundException

400 (bad request)

json error object

TBD

Add schema set to dataspace

the schema set throws a validation exception when parsed with ODL Yang Parser e.g.

• No files (in zip)

• Missing (import) files 

• Incorrect yang in a module

• Duplicate namespaces

N/A

N/A

ModelValidationException (e casue)

details should contain cause message

400 (bad request)

json error object

message and details from the original exception.

List anchors for dataspace name

dataspacename does not exist

No records (Optional, not present)

DataspaceNotFoundException

DataspaceNotFoundException

400 (bad request)

json error object

dataspace xyz not found

List anchors for dataspace name

no anchor records in DB

0 records

empty collection

empty collection

200 (ok)

empty list

N/A

Add a fragment

Insert a fragment that violates the unique constraint e.g. when trying to insert a fragment with the same property values(dataspace_id,anchor_id,xpath) as an existing fragment. 

DataIntegrityViolationException

8

Remove schema set

Schema set removal is requested from REST (or via API/SPI with explicitly defined option prohibiting removal of associated anchors and data if found) and there is (are) associated anchor record(s) in database.

N/A

SchemaSetInUseException

SchemaSetInUseException

409 (Conflict)

json error object

schama set abc in dataspace xyz is having anchor records associated.

9

Get a fragment that does not exist

get fragment by xpath that does not exist

FragmentNotFoundException

DataNodeNotFoundException

DataNodeNotFoundException

400 (bad request)

json error object

datanode with xpath xyz not found in dataspace xyz

10

Invalid cps path

a cpsPath that cannot be parsed i.e. not recognized as a valid query

• 2021-03-08T14:57:19.343Z|main|| o.onap.cps.rest.exceptions.CpsRestExceptionHandler - An error has occurred : Invalid cps path. Status: 400 BAD_REQUEST Details: Cannot interpret or parse cps path.

• 2021-03-08 15:01:44.441 ERROR 21676 --- [ main] o.o.c.r.e.CpsRestExceptionHandler : An error has occurred : Unsupported leaf value. Status: 400 BAD_REQUEST Details: Unsupported leaf value in cps path.

CpsPathException

CpsPathException

CpsPathException

400 (bad request)

json error object

message and details from the original exception.

11

Data node already exists

Create the same data node twice

DataIntegrityViolationException

DataNodeAlreadyDefined

DataNodeAlreadyDefined

409 (Conflict)

json error object

Data node already defined for dataspace abc

12

Unsupported update node leaves

Unsupported json data when 

1. Conversion of a normalized node to a datanode within the datanode builder class.

private DataNode buildFromNormalizedNodeTree() {
final Collection<DataNode> dataNodeCollection = buildCollectionFromNormalizedNodeTree();
return dataNodeCollection.iterator().next(); }

2. Parsing list json data

1. NoSuchElementException

2. IllegalStateException

DataValidationException

DataValidationException

400

json error object

"Unsupported json data: " + jsonData

13

Delete dataspace with anchor/s

Delete dataspace that still contains 1 or more anchor

DataspaceInUseException

DataspaceInUseException

409

(Conflict)

json error object

dataspace contains anchor(s)

14

Delete dataspace with schemaset/s

Delete dataspace that still contains 1 or more schemaset

DataspaceInUseException

DataspaceInUseException

409

(Conflict)

json error object

dataspace contains schemaset(s)

Admin

POST - /v1/dataspaces

CpsAdminApi.createDataspace()

Create a new dataspace

201

400

401

403

201 (created)

• for success

409 (conflict)

• for data integrity violation when persisting (AlreadyDefinedException)

500 (internal server error)

• for unexpected system errors

Specification:

• Remove 400

• Add 409

Admin

DELETE - /v1/dataspaces

CpsAdminApi.deleteDataspace()

Delete a dataspace

204

400

401

403

409

204 (no content)

• for success

400 (bad request)

• for dataspace not found (DataspaceNotFoundException)

409 (conflict)

• for dataspace having anchors or schema sets (DataspaceInUseException)

500 (internal server error)

• for unexpected system errors

Admin

GET - /v1/dataspaces/{dataspace-name}/anchors

CpsAdminApi.getAnchors()

Read all anchors, given a dataspace

200

400

401

403

404

200 (ok)

• for success

400 (bad request)

• for dataspace not found (DataspaceNotFoundException)

500 (internal server error)

• for unexpected system errors

Specification:

• Remove 404

Admin

POST - /v1/dataspaces/{dataspace-name}/anchors

CpsAdminApi.createAnchor()

Create a new anchor in the given dataspace

201

400

401

403

201 (created)

• for success

400 (bad request)

• for dataspace not found (DataspaceNotFoundException)

• for schema set not found (SchemaSetNotFoundException)

409 (conflict)

• for data integrity violation when persisting (AlreadyDefinedException)

500 (internal server error)

• for unexpected system errors

Specification:

• Add 409

Admin

GET - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}

CpsAdminApi.getAnchor()

Read an anchor given an anchor name and a dataspace

200

400

401

403

404

200 (ok)

• for success

400 (bad request)

• for dataspace not found (DataspaceNotFoundException)

• for anchor not found (AnchorNotFoundException)

500 (internal server error)

• for unexpected system errors

Specification:

• Remove 404

Admin

DELETE - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}

CpsAdminApi.deleteAnchor()

Delete an anchor given an anchor name and a dataspace

204

400

401

403

204 (no content)

• for success

400 (bad request)

• for dataspace not found (DataspaceNotFoundException)

• for anchor not found (AnchorNotFoundException)

500 (internal server error)

• for unexpected system errors

Admin

POST - /v1/dataspaces/{dataspace-name}/schema-sets

CpsAdminApi.createSchemaSet()

Create a new schema set in the given dataspace

201

400

401

403

201 (created)

• for success

400 (bad request)

• for different errors related to input schema set file reading (CpsException)

• for zip schema set file size exceeding defined limit (ModelValidationException)

• for zip schema set file number entries exceeding defined limit (ModelValidationException)

• for zip schema set file containing no yang files (ModelValidationException)

• for multiple resources with same name contained in zip schema set file (ModelValidationException)

• for schema set file name extension different from yang or zip (ModelValidationException)

• for invalid Yang syntax (ModelValidationException)

• for dataspace not found (DataspaceNotFoundException)

409 (conflict)

• for data integrity violation when persisting (AlreadyDefinedException)

500 (internal server error)

• for concurrency error when several clients are requesting to create the exact same resource at the same time and that the automatic retry keeps failing (DuplicatedYangResourceException)

• for unexpected system errors

Specification:

• Add 409