CPS Exceptions and REST APIs HTTP Response Codes

ONAP Guidelines

Finally found general ONAP Advise:

"The API specification should describe the right HTTP status code to return the client.

Status codes should align with IETF's HTTP Status Code Registry: https://www.ietf.org/assignments/http-status-codes/http-status-codes.xml"

Agreed CPS API(SPI) Exception Hierarchy

(see CCSDK-2871 DP: Long-term Java API(s)

CpsException
- CpsAdminException
  - DataspaceNotFoundException
  - DataspaceAlreadyDefinedException
  - SchemaSetNotFoundException
  - SchemaSetValidationException
  - SchemaSetAlreadyDefinedException (this is separate from SchemaSetValidationException as it could be ignored by the client)
  - AnchorAlreadyDefinedException
  - AnchorNotFoundException
- ModelValidationException (mainly applicable to schema set validation)
- DataValidationException
  - SpecificException3
  - SpecificException4
- PathValidationException
  - SpecificException5

*Note we might have to move these 'common' exceptions classes to the SPI just like we did with the common data objects

Issues & Decisions

#

Slogan

Remarks

Decision

Who &When

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)

Introduce specific exception for each extending new CPSAdminException class
re-use same exception in API (pass through)
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 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

Vertical slice view of error scenarios

CPS-Core

#	Use case	Scenario	DB (Spring) Response	SPI Response	Java API	REST API Response Code	Response Body	Error Object Message
1	Add dataspace	dataspace already exists	DataIntegrityViolationException	DataspaceAlreadyDefinedException	DataspaceAlreadyDefinedException	400 (bad request)	json error object	dataspace xyz already defined
2	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
3	Add schema set to dataspace	dataspacename does not exist	No records (Optional, not present)	DataspaceNotFoundException	DataspaceNotFoundException	400 (bad request)	json error object	TBD
4	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.
5	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
6	List anchors for dataspace name	no anchor records in DB	0 records	empty collection	empty collection	200 (ok)	empty list	N/A
7	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 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	NoSuchElementException 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)

CPS-NCMP

#	Sub interface	Method	Scenario	HTTP Response Code
1	Data	HTTP: GET - /v1/ch/{cm-handle}/data/ds/ncmp-datastore:passthrough-operational NetworkCmProxyApi.getResourceDataOperationalForCmHandle()	Get resource data from pass-through operational for given cm handle	Specified: 200, 400, 401, 403, 404 Implemented: 200, 500
2	Data	GET - /v1/ch/{cm-handle}/data/ds/ncmp-datastore:passthrough-running NetworkCmProxyApi.getResourceDataRunningForCmHandle()	Get resource data from pass-through running for given cm handle	Specified: 200, 400, 401, 403, 404 Implemented: 200, 500
3	Data	PUT- /v1/ch/{cm-handle}/data/ds/ncmp-datastore:passthrough-running NetworkCmProxyApi.updateResourceDataRunningForCmHandle()	Update resource data from pass-through running for the given cm handle	Specified: 200, 400, 401, 403, 404 Implemented: 200, 500
4	Data	POST - /v1/ch/{cm-handle}/data/ds/ncmp-datastore:passthrough-running NetworkCmProxyApi.createResourceDataRunningForCmHandle()	Create resource data from pass-through running for given cm handle	Specified: 201, 400, 401, 403, 404 Implemented: 201, 500
5	Data	PATCH - /v1/ch/{cm-handle}/data/ds/ncmp-datastore:passthrough-running NetworkCmProxyApi.patchResourceDataRunningForCmHandle()	Patch resource data from pass-through running for the given cm handle	Specified: 200, 400, 401, 403, 404 Implemented: 200, 500
6	Model	GET - /v1/ch/{cm-handle}/modules NetworkCmProxyApi.getModuleReferencesByCmHandle	Fetch all module references (name and revision) for a given cm handle	Specified: 200, 400, 401, 403, 404 Implemented: 200, 500
7	Model	POST - /v1/ch/searches NetworkCmProxyApi.executeCmHandleSearch	Execute cm handle searches using 'hasAllModules' condition to get all cm handles for the given module names	Specified: 200, 400, 401, 403 Implemented: 200, 500
8	Inventory	POST /v1/ch NetworkCmProxyInventoryApi.updateDmiPluginRegistration()	Register, update or remove cm handles	Specified: 201, 400, 401, 403 Implemented: 201, 500 Comment: Invalid requests should return 4xx with an explanation message instead of 500 without information (ex: Invalid combination of plugin service names, URI is not absolute, ...)

DMI-Plugin

#	Sub interface	Method	Scenario	Specified HTTP Response Code	Comments
1	DMI Plugin Internal	POST - /v1/inventory/cmHandles	Register given list of cm handles (internal use only)	201 400 401 403
2	DMI Plugin	POST - /v1/ch/{cmHandle}/modules	Get all modules for given cm handle	200 400 401 403
3	DMI Plugin	POST - /v1/ch/{cmHandle}/moduleResources	Retrieve module resources for one or more modules	200 400 401 403
4	DMI Plugin	POST - /v1/ch/{cmHandle}/data/ds/ncmp-datastore:passthrough-operational	Get resource data from passthrough-operational for cm handle. Will support read operations only.	200 400 401 403
5	DMI Plugin	POST - /v1/ch/{cmHandle}/data/ds/ncmp-datastore:passthrough-running	Post request to Get, Create or to Update resource data for a cm-handle. Since all requests need to include additional information in a request body HTTP Post is used for all use cases and the actual operation is defined in the request body instead.	201 400 401 403	Should success be 200 (general ok) instead of 201 (created) ?

CPS-Temporal

#

Sub interface

Method

Scenario

Specified HTTP Response Code

Implemented HTTP Response Code

Comments

1

Query

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

CpsTemporalQueryApi.getAnchorDataByName()

Get anchor data by name

200

400

401

403

200 - ok

400 - for input data validation errors

500 - for unexpected system errors

Add 500 to the specification
Review 401, 403 ?

2