Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 51 Next »

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

#SloganRemarks

Decision

Who &When
1treatment 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
2Using different HTTP Response code (400 v 404) depending on type of operation, adding data/requesting dataIt 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 caseScenarioDB (Spring) Response SPI ResponseJava APIREST API Response CodeResponse BodyError Object Message
1Add dataspacedataspace already existsDataIntegrityViolationExceptionDataspaceAlreadyDefinedExceptionDataspaceAlreadyDefinedException400 (bad request)json error objectdataspace xyz already defined
2Add schema set to dataspace

schema set with same name already exists

DataIntegrityViolationException

SchemaSetAlreadyDefinedException

SchemaSetAlreadyDefinedException400 (bad request)json error objectschema set xyz already defined for dataspace abc
3Add schema set to dataspacedataspacename does not existNo records (Optional, not present)DataspaceNotFoundExceptionDataspaceNotFoundException400 (bad request)json error objectTBD
4Add 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/AN/A

ModelValidationException (e casue)

details should contain cause message

400 (bad request)json error object

message and details from the original exception.

5List anchors for dataspace namedataspacename does not existNo records (Optional, not present)

DataspaceNotFoundException

DataspaceNotFoundException

400 (bad request)

json error objectdataspace xyz not found
6List anchors for dataspace nameno anchor records in DB0 recordsempty collectionempty collection200 (ok)

empty list

N/A
7Add a fragmentInsert 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




8Remove schema setSchema 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/ASchemaSetInUseExceptionSchemaSetInUseException409 (Conflict)json error objectschama set abc in dataspace xyz is having anchor records associated.
9Get a fragment that does not existget fragment by xpath that does not existFragmentNotFoundExceptionDataNodeNotFoundExceptionDataNodeNotFoundException400 (bad request)json error objectdatanode with xpath xyz not found in dataspace xyz
10Invalid 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.
CpsPathExceptionCpsPathExceptionCpsPathException400 (bad request)json error objectmessage and details from the original exception.
11Data node already existsCreate the same data node twice
DataIntegrityViolationException
DataNodeAlreadyDefinedDataNodeAlreadyDefined409 (Conflict)json error objectData node already defined for dataspace abc
12Unsupported 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
400json error object
"Unsupported json data: " + jsonData
13Delete dataspace with anchor/s

Delete dataspace that still contains 1 or more anchor


DataspaceInUseException

DataspaceInUseException

409

(Conflict)

json error object

dataspace contains anchor(s)

14Delete dataspace with schemaset/sDelete dataspace that still contains 1 or more schemaset
DataspaceInUseExceptionDataspaceInUseException

409

(Conflict)

json error objectdataspace contains schemaset(s)

CPS-NCMP

#Sub interfaceMethodScenarioHTTP Response CodeBody
1Data

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


2Data

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


3Data

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


4Data

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


5Data

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


6Model

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


7Model

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


8Inventory

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 interfaceMethodScenarioSpecified HTTP Response CodeImplemented HTTP Response CodeComments
1DMI Plugin Internal

POST - /v1/inventory/cmHandles

DmiPluginInternalApi.registerCmHandles()



Register given list of cm handles (internal use only)

201

400

401

403

201 (created)

  • for success

400 (bad request)

  • for empty cm handles list from input

500 (internal server error)

  • for parsing error when converting provided cm handles into JSON
  • for any response code from NCMP that is different form 201
  • for unexpected system errors

Implementation

  • Input cm handle conversion error should return a 4xx client error
2DMI Plugin

POST - /v1/ch/{cmHandle}/modules

DmiPluginApi.getModuleReferences()

Get all modules for given cm handle

200

400

401

403

200 (ok)

  • for success

500 (internal server error)

  • for unexpected system errors

3DMI Plugin

POST - /v1/ch/{cmHandle}/moduleResources

DmiPluginApi.retrieveModuleResources()

Retrieve module resources for one or more modules

200

400

401

403

200 (ok)

  • for success

404 (not found)

  • module resource not found from SDNC for the given cm handle
  • error occurred when trying to parse the response body from SDNC

500 (internal server error)

  • for JSON parsing error when creating the module request from the given module reference (DmiException)
  • for any SDNC response code that is different from 200 or 404
  • for unexpected system errors

Implementation:

  • SDNC errors are not really consistent (404 and 500)
  • Error related to the given module reference should be 4xx ?
4DMI Plugin

POST - /v1/ch/{cmHandle}/data/ds/ncmp-datastore:passthrough-operational

DmiPluginApi.dataAccessPassthroughOperational()

Get resource data from passthrough-operational for cm handle. Will support read operations only.

200

400

401

403

200 (ok)

  • for success

400 (bad request)

  • for input operation that is different from read

500 - for unexpected system errors


5DMI Plugin

POST - /v1/ch/{cmHandle}/data/ds/ncmp-datastore:passthrough-running

DmiPluginApi.dataAccessPassthroughRunning()

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

200 (ok)

  • for success with read or update requested operation. Response body is SDNC body response.

201 (created)

  • for success with create requested operation. Response body is SDNC body response.

204 (no content)

  • for success with delete requested operation. Response body is SDNC body response.

400 (bad request)

  • for requested operation that is different from create, read, update or delete. Response body is SDNC body response.

500 (internal server error)

  • for any SDNC response code that is different from 2xx
  • for unexpected system errors

Specification

  • Should success always be 200 (general ok) instead of 201 (created) ?

Implementation

  • It does not seem consistent to return 404 with SDNC body response when operation is different from create, read update or delete.


CPS-Temporal

#Sub interfaceMethodScenarioSpecified HTTP Response CodeImplemented HTTP Response CodeComments
1Query

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 ?
2Query

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

CpsTemporalQueryApi.getAnchorsDataByFilter()


Get anchors data based on filter criteria

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 ?
  • No labels