Versions Compared

Old Version 54

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Toine Siebelink

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

ONAP ONAP Guidelines

Finally found general ONAP Advise:

...

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

Agreed CPS  API(SPI) Exception Hierarchy

...

#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 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

Vertical slice view of error scenarios

...

#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)

Spike CPS-728: Inventory of HTTP Response Codes for all CPS interfaces

Jira Legacy
serverSystem Jira
serverId4733707d-2057-3a0f-ae5e-4fd8aff50176
keyCPS-782

...

(commit id 8c9b4a24b4841154a2d08f506e2f7beca4f6fc31)

#Sub interfaceMethodScenarioSpecified HTTP Response CodeImplemented HTTP Response Code
CommentsGET - /
Changes required
1Admin

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
2Admin

DELETE - /v1/dataspaces

CpsAdminApi.deleteDataspace()

Delete a dataspace

204

400

401

403

409

3Admin

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

(tick)

3Admin

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

CpsAdminApi.getAnchors()

Read all anchors, given a dataspace

200

400

401

403

404

4AdminPOST - /v1/dataspaces/{dataspace-name}/anchorsCreate a new anchor in the given dataspace

201

400

401

403

5AdminGET

200 (ok)

  • for success

400 (bad request)

  • for dataspace not found (DataspaceNotFoundException)

500 (internal server error)

  • for unexpected system errors

Specification:

  • Remove 404
4Admin

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

/{anchor-name}Read an anchor given an anchor name and a dataspace200

CpsAdminApi.createAnchor()

Create a new anchor in the given dataspace

201

400

401

403

404

6AdminDELETE

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
5Admin

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

Delete an

CpsAdminApi.getAnchor()

Read an anchor given an anchor name and a dataspace
204

200

400

401

403

7

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
6Admin
POST

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

schema-setsCreate a new schema set in the given dataspace201

anchors/{anchor-name}

CpsAdminApi.deleteAnchor()

Delete an anchor given an anchor name and a dataspace

204

400

401

403

8

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
(tick)
7Admin
GET

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

/{schema-set-name}Read a schema set given a schema set name and a dataspace200

CpsAdminApi.createSchemaSet()

Create a new schema set in the given dataspace

201

400

401

403

404

9AdminDELETE - /v1/dataspaces/{dataspace-name}/schema-sets/{schema-set-name}Delete a schema set given a schema set name and a dataspace

204

400

401

403

409

10DataGET - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodeGet a node with an option to retrieve all the children for a given anchor and dataspace

200

400

401

403

404

11DataPUT - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodesReplace a node with descendants for a given dataspace, anchor and a parent node xpath

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

Implementation

  • Concurrency error is 500, but there is not much that can be done on the server side, the client would have to resend ... Should it be 400 instead ? => Decision made to keep 500
8Admin

GET - /v1/dataspaces/{dataspace-name}/schema-sets/{schema-set-name}

CpsAdminApi.getSchemaSet()


Read a schema set given a schema set name and a dataspace

200

400

401

403

12DataPOST

404

200 (ok)

  • for success

400 (bad request)

  • for dataspace not found (DataspaceNotFoundException)
  • for schema set not found (SchemaSetNotFoundException)

500 (internal server error)

  • for unexpected system errors

Specification:

  • Remove 404
9Admin

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

anchors

schema-sets/{

anchor

schema-set-name}

/nodesCreate a node for a given anchor and dataspace201PATCH

CpsAdminApi.deleteSchemaSet()

Delete a schema set given a schema set name and a dataspace

204

400

401

403

13DataDELETE - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodesDelete a datanode for a given dataspace and anchor given a node xpath.

204

400

401

403

14Data

409

204 (no content)

  • for success

400 (bad request)

  • for dataspace not found (DataspaceNotFoundException)
  • for schema set not found (SchemaSetNotFoundException)

409 (conflict)

  • for existence of anchors using the schema set (SchemaSetInUseException)

500 (internal server error)

  • for unexpected system errors
(tick)
10Data

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

nodesUpdate a data node leaves

node

CpsDataApi.getNodeByDataspaceAndAnchor()

Get a node with an option to retrieve all the children for a given
dataspace and
anchor and
a parent node xpath
dataspace

200

400

401

403

15

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
11Data

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

list-nodesReplace list content under a given parent, anchor and dataspace

nodes

CpsDataApi.replaceNode()

Replace a node with descendants for a given dataspace, anchor and a parent node xpath

200

400

401

403

16DataPOST - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/list-nodesAdd list element(s) to a list for a given anchor and dataspace

201

400

401

403

17DataDELETE - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/list-nodes

Deprecated

Delete one or all list element(s) for a given anchor and dataspace

204

400

401

403

18QueryGET - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes/queryQuery data nodes for the given dataspace and anchor using CPS path

200

400

401

403

404

CPS-NCMP

#Sub interfaceMethodScenarioSpecified HTTP Response CodeImplemented HTTP Response CodeCommentsBody
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

200

400

401

403

404

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

200

400

401

403

404

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

200 (ok)

  • for success

400 (bad request)

  • for error while parsing json data or not supported xpath (DataValidationException)
  • for dataspace not found (DataspaceNotFoundException)
  • for anchor not found (AnchorNotFoundException)
  • for data node not found (DataNodeNotFoundException)

500 (internal server error)

  • for concurrent transactions making data to be updated stale (ConcurrencyException)
  • for unexpected system errors

Implementation:

  • Concurrency error is 500, but there is not much that can be done on the server side, the client would have to resend ... Should it be 400 instead ? => Decision made to keep 500
12Data

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

CpsDataApi.createNode()

Create a node for a given anchor and dataspace

201

400

401

403

201 (created)

  • for success

400 (bad request)

  • for error while parsing json data or not supported xpath (DataValidationException)
  • for dataspace not found (DataspaceNotFoundException)
  • for anchor not found (AnchorNotFoundException)
  • for data node not found (DataNodeNotFoundException)

409 (conflict)

  • for data integrity violation when persisting (AlreadyDefinedException)

500 (internal server error)

  • for unexpected system errors

Specification:

  • Add 409
13Data

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

CpsDataApi.deleteDataNode()

Delete a datanode for a given dataspace and anchor given a node xpath.

204

400

401

403

204 (no content)

  • for success

400 (bad request)

  • for data node not found (DataNodeNotFoundException)

500 (internal server error)

  • for unexpected system errors
(tick)
14Data

PATCH - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes

CpsDataApi.updateNodeLeaves()

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

200

400

401

403404

200 (ok)

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

201

400

401

403

404

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
  • for success

400 (bad request)

  • for error while parsing json data or not supported xpath (DataValidationException)
  • for dataspace not found (DataspaceNotFoundException)
  • for anchor not found (AnchorNotFoundException)
  • for data node not found (DataNodeNotFoundException)

500 (internal server error)

  • for unexpected system errors
(tick)
15Data

PUT - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/list-nodes

CpsDataApi.replaceListContent()

Replace list content under a given parent, anchor and dataspace

200

400

401

403404

200 (ok)

500

6Model

GET - /v1/ch/{cm-handle}/modules

NetworkCmProxyApi.getModuleReferencesByCmHandle

Fetch all module references (name and revision) for a given cm handle

200

400

401

403

404

200

500

7Model
  • for success

400 (bad request)

  • for error while parsing json data or not supported xpath (DataValidationException)
  • for no data nodes provided (DataValidationException)
  • for dataspace not found (DataspaceNotFoundException)
  • for anchor not found (AnchorNotFoundException)
  • for data node not found (DataNodeNotFoundException)

500 (internal server error)

  • for unexpected system errors
(tick)
16Data

POST - /v1/ch/searches

NetworkCmProxyApi.executeCmHandleSearch

Execute cm handle searches using 'hasAllModules' condition to get all cm handles for the given module names

200dataspaces/{dataspace-name}/anchors/{anchor-name}/list-nodes

CpsDataApi.addListElements()

Add list element(s) to a list for a given anchor and dataspace

201

400

401

403

200

500

8Inventory

POST /v1/ch

NetworkCmProxyInventoryApi.updateDmiPluginRegistration()

Register, update or remove cm handles

201

400

401

403

201

500

Implementation:

  • 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

POST - /v1/inventory/cmHandles

DmiPluginInternalApi.registerCmHandles()

201201 created empty cm handles list from input parsing error when converting provided cm handles into JSON (DmiException)
  • for any response code from NCMP that is different form 201 (CmHandleRegistrationException)
  • for unexpected system errors
    • #Sub interfaceMethodScenarioSpecified HTTP Response CodeImplemented HTTP Response CodeComments
    1DMI Plugin InternalRegister given list of cm handles (internal use only)

    201 (created)

    • for success

    400 (bad request)

    • for error while parsing json data or not supported xpath (DataValidationException)
    • for no data nodes provided (DataValidationException)
    • for dataspace not found (DataspaceNotFoundException)
    • for anchor not found (AnchorNotFoundException)
    • for data node not found (DataNodeNotFoundException)

    500 (internal server error)

    • for unexpected system errors
    		(tick)
    17Data

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

    CpsDataApi.deleteListOrListElement()

    Delete one or all list element(s) for a given anchor and dataspace

    204

    400

    401

    403

    204 (

    no content)

    • for success

    400 (bad request)

    • for
    • targetprobably not a list (DataNodeNotFoundException)

    500 (internal server error)

    • for

    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
    • unexpected system errors
    		Deprecated, ignored
    18Query

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

    CpsQueryApi.getNodesByDataspaceAndAnchorAndCpsPath()

    		Query data nodes for the given dataspace and anchor using CPS path

    200

    400

    401

    403

    404

    200 (ok)

    • for success

    404 (400 (bad request)

    • for dataspace not found (DataspaceNotFoundException)
    • for anchor not found (AnchorNotFoundException)
    • for SDNC returning no modules for given cm handle (ModulesNotFoundExceptionfailure when parsing provided cps path (CpsPathException)
    • for failure when parsing retrieved fragment entity attributes (DataValidationException)

    500 (internal server error)

    POST
    • for SDNC response JSON format or processing failure (SdncException)
    • for unexpected system errors
    		3DMI Plugin
    • unexpected system errors

    Specification:

    • 404 not needed


    CPS-NCMP

    (commit id 8c9b4a24b4841154a2d08f506e2f7beca4f6fc31)

    cmHandlemoduleResources

    DmiPluginApi.retrieveModuleResources()

    Retrieve module resources for one or more modulesPOST
    • The exception ResourceDataNotFound is missing the Exception suffix
    200
    #Sub interfaceMethodScenarioSpecified HTTP Response CodeImplemented HTTP Response CodeChanges Required
    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

    200

    400

    401

    403

    404

    200 (ok)

    • for success

    404 (not found)

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

    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 500 (internal server error)

    • for error when parsing provided dmi request to json (NcmpException)
    • for dmi response code different from 2xx (NcmpException)
    • for unexpected system errors

    Specification:

    • Remove 404

    Implementation:

    • Parsing error for dmi request should be a 400 client error (Use ClientRequestNcmpExcpetion vs ServerNcmpException)
    2Data

    GET - /v1/ch/{cmHandlecm-handle}/data/ds/ncmp-datastore:passthrough-operationalrunning

    DmiPluginApiNetworkCmProxyApi.dataAccessPassthroughOperationalgetResourceDataRunningForCmHandle()

    		Get resource data from passthroughpass-operational through running for given cm handle. Will support read operations only.

    200

    400

    401

    403

    404

    200 (ok)

    • for success

    400 (bad request)

    • for input operation that is different from read

    500 (internal server error)

    for any SDNC response code that is different from 200 (ResourceDataNotFound

    500 (internal server error)

    • for error when parsing provided dmi request to json (NcmpException)
    • for dmi response code different from 2xx (NcmpException)
    • for unexpected system errors
    		5DMI Plugin

    Specification:

    • Remove 404

    Implementation:

    • Parsing error for dmi request should be a 400 client error (see 1. above)
    3Data

    PUT- /v1/ch/{cmHandlecm-handle}/data/ds/ncmp-datastore:passthrough-running

    DmiPluginApiNetworkCmProxyApi.dataAccessPassthroughRunningupdateResourceDataRunningForCmHandle()

    		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

    403from pass-through running for the given cm handle

    200

    400

    401

    403

    404

    #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 (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 when writing data (DmiException)
    • for any SDNC response code that is different from 200 when getting data (ResourceDataNotFound)
    • 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.
    • SDNC response codes are handled differently for getting and writing data

    CPS-Temporal

    200 ok400 (bad request)
    • for input data validation errors
    unexpected system errorsGET dataspacesdataspacenameanchors/historyCpsTemporalQueryApi.getAnchorsDataByFilterGet anchors data based on filter criteria

    400 (bad request)

    • for input data validation errors

    500 (internal server error)

    • for unexpected system errors

    500 (internal server error)

    • for error when parsing provided dmi request to json (NcmpException)
    • for dmi response code different from 2xx (NcmpException)
    • for unexpected system errors

    Specification:

    • Remove 404

    Implementation:

    • Parsing error for dmi request should be a 400 client error (see 1. above)
    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

    201

    400

    401

    403

    404

    201 (

    created)

    • for success

    500 (internal server error)

    • for
    		2Query
    • error when parsing provided dmi request to json (NcmpException)
    • for dmi response code different from 2xx (NcmpException)
    • for unexpected system errors

    Specification:

    • Remove 404

    Implementation:

    • Parsing error for dmi request should be a 400 client error (see 1. above)
    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

    200

    400

    401

    403

    404

    200 (ok)

    • for success

    ...

    500 (internal server error)

    • for error when parsing provided dmi request to json (NcmpException)
    • for dmi response code different from 2xx (NcmpException)
    • for unexpected system errors

    Specification:

    • Remove 404

    Implementation:

    • Parsing error for dmi request should be a 400 client error (see 1. above)
    6Model

    GET - /v1/ch/{cm-handle}/modules

    NetworkCmProxyApi.getModuleReferencesByCmHandle

    Fetch all module references (name and revision) for a given cm handle

    200

    400

    401

    403

    404

    200 (ok)

    • for success

    500 (internal server error)

    • for unexpected system errors

    Specification:

    • Remove 404

    Implementation

    • Check for incorrect or missing cm handle that should return 400
    7Model

    POST - /v1/ch/searches

    NetworkCmProxyApi.executeCmHandleSearch

    		Execute cm handle searches using 'hasAllModules' condition to get all cm handles for the given module names

    200

    400

    401

    403

    200 (ok)

    • for success

    500 (internal server error)

    • for no yang resources found for provided module (ModuleNamesNotFoundException)
    • for unexpected system errors

    Implementation:

    • Currently, 500 is returned when no matches found. This should be changed to a 400 response
    • Invalid body payload structure format returns 500 with the system error message, not really useful for the client. Should also returns 400.
    • Note: Simulate different kinds of bad requests that should return 400.
    8Inventory

    POST /v1/ch

    NetworkCmProxyInventoryApi.updateDmiPluginRegistration()

    		Register, update or remove cm handles

    201

    400

    401

    403

    201 (created)

    • for success

    500 (internal server error)

    • for dmi plugin service name not provided (NcmpException)
    • for invalid combination of dmi plugin service names (NcmpException)
    • for parsing error while processing dmi plugin registration (DataValidationException)
    • for unexpected system errors

    Specification:

    • Should success always be 200 (general ok) instead of 201 (created) that might look confusing for updates and removals ?

    Implementation:

    • Invalid requests should return 400 with an explanation message instead of 500 without information (ex: Invalid combination of plugin service names, URI is not absolute, ...)
    • Add more information in the logs when dmi plugin service is not reachable (not currently enough to support and investigate).

    DMI-Plugin

    (commit id 1954daa5d31b537a8838d1e11cb41cd6f40b58d9)

    #Sub interfaceMethodScenarioSpecified HTTP Response CodeImplemented HTTP Response CodeChanges Required
    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 (DmiException)
    • for any response code from NCMP that is different form 201 (CmHandleRegistrationException)
    • 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

    404 (not found)

    • for SDNC returning no modules for given cm handle (ModulesNotFoundException)

    500 (internal server error)

    • for SDNC response JSON format or processing failure (SdncException)
    • for unexpected system errors

    Specification:

    • Remove 400
    • Add 404
    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)

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

    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 (internal server error)

    • for any SDNC response code that is different from 200 (ResourceDataNotFound)
    • for unexpected system errors

    Implementation:

    • The exception ResourceDataNotFound is missing the Exception suffix
    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 when writing data (DmiException)
    • for any SDNC response code that is different from 200 when getting data (ResourceDataNotFound)
    • 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.
    • SDNC response codes are handled differently for getting and writing data


    CPS-Temporal

    (commit id 13483eacf395cae83239dd0f17114986b9476d19)

    #Sub interfaceMethodScenarioSpecified HTTP Response CodeImplemented HTTP Response CodeChanges Required
    1Query

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

    CpsTemporalQueryApi.getAnchorDataByName()

    		Get anchor data by name

    200

    400

    401

    403

    200 (ok)

    • for success

    400 (bad request)

    • for input data validation errors

    500 (internal server error)

    • for unexpected system errors

    (tick)

    2Query

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

    CpsTemporalQueryApi.getAnchorsDataByFilter()


    		Get anchors data based on filter criteria

    200

    400

    401

    403

    200 (ok)

    • for success

    400 (bad request)

    • for input data validation errors

    500 (internal server error)

    • for unexpected system errors

    (tick)

    General comments for all endpoints

    Specification

    2xx: Success - The action was successfully received, understood, and accepted

    4xx: Client Error - The request contains bad syntax or cannot be fulfilled

    5xx: Server Error - The server failed to fulfill an apparently valid request

    • Always ensure that client request related errors return 4xx along with a clear explanation provided to the client about the reason for the error. When 4xx errors occur, the system itself is behaving as expected.
    • 500 response codes should only correspond to unexpected errors that require support investigation and effort in order to be fixed (ex: network communication issue, dependent component or system down, corrupted data, application bug, ...). For 500 errors no details are really expected in the response for the client, all the information to investigate the problem should be available in the logs.
    • Review 401 and 403 responses code from specification that are not implemented yet.

    Implementation

    • Is NotFoundInDataspaceException used ? If not, could it be removed ?
    • Handling of DataNodeNotFoundException in CpsRestExceptionHandler supports a different return code (404) when http method is get. Is this implementation used ? If not, could it be removed ?

    Required Changes:

    • 500 needs to be added to the specification for all endpoints

    ...