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
...
# | 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) |
| 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
| CPS Team Meeting 3 Dec |
Vertical slice view of error scenarios
...
# | 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.
| 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
| 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Â
private DataNode buildFromNormalizedNodeTree() { |
| DataValidationException | DataValidationException | 400 | json error object |
|
|
|
|
|
|
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) |
...
# | Sub interface | Method | Scenario | Specified HTTP Response Code | Implemented HTTP Response Code | CommentsChanges required | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
1 | Admin | POST - /v1/dataspaces CpsAdminApi.createDataspace() | Create a new dataspace | 201 400 401 403 | 201 (created)
409 (conflict)
500 (internal server error)
| Specification:
| , add
| |||||||||
2 | Admin | DELETE - /v1/dataspaces CpsAdminApi.deleteDataspace() | Delete a dataspace | 204 400 401 403 409 | 204 (no content)
400 (bad request)
409 (conflict)
500 (internal server error)
| |||||||||||
3 | Admin | GET - /v1/dataspaces/{dataspace-name}/anchors CpsAdminApi.getAnchors() | Read all anchors, given a dataspace | 200 400 401 403 404 | 200 (ok)
400 (bad request)
500 (internal server error)
| Specification: | Keep only one of 400 or 404 when dataspace is not found.
| |||||||||
4 | Admin | POST - /v1/dataspaces/{dataspace-name}/anchors CpsAdminApi.createAnchor() | Create a new anchor in the given dataspace | 201 400 401 403 | 201 (created)
400 (bad request)
409 (conflict)
500 (internal server error)
| Specification:
| ||||||||||
5 | 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)
400 (bad request)
500 (internal server error)
| Specification:
| ||||||||||
6 | 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)
400 (bad request)
500 (internal server error)
| |||||||||||
7 | 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)
400 (bad request)
409 (conflict)
500 (internal server error)
| Specification:
Implementation
| ||||||||||
8 | Admin | GET - /v1/dataspaces/ | 8 | Admin | 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 404 | 200 (ok)
400 (bad request)
500 (internal server error)
| Specification:
| |||||||
9 | Admin | DELETE - /v1/dataspaces/{dataspace-name}/schema-sets/{schema-set-name} CpsAdminApi.deleteSchemaSet() | Delete a schema set given a schema set name and a dataspace | 204 400 401 403 409 | 204 (no content)
400 (bad request)
409 (conflict)
500 (internal server error)
| |||||||||||
10 | Data | GET - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/node CpsDataApi.getNodeByDataspaceAndAnchor() | Get a node with an option to retrieve all the children for a given anchor and dataspace | 200 400 401 403 404 | 11 | Data | PUT - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes CpsDataApi.replaceNode() | 200 (ok)
400 (bad request)
500 (internal server error)
| Specification:
| |||||||
11 | Data | PUT | Replace a node with descendants for a given dataspace, anchor and a parent node xpath | 200 400 401 403 | 12 | Data | POST - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes CpsDataApi.createNodereplaceNode() | Create Replace a node with descendants for a given dataspace, anchor and dataspacea parent node xpath | 200201 400 401 403 | 13 | Data | DELETE - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes CpsDataApi.deleteDataNode() | 200 (ok)
400 (bad request)
500 (internal server error)
| Implementation:
| ||
12 | Data | POST | Delete a datanode for a given dataspace and anchor given a node xpath. | 204 400 401 403 | 14 | Data | 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 403 | 15 | Data | PUT - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/list-nodes CpsDataApi.replaceListContentcreateNode() | Replace list content under Create a node for a given parent, anchor anchor and dataspace | 200201 400 401 403 | 201 (created)
400 (bad request)
409 (conflict)
500 (internal server error)
| Specification:
|
13 | 16 | Data | POST - /v1/dataspaces/{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 | 17 | Data | DELETE - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/list-nodes CpsDataApi.deleteListOrListElementdeleteDataNode() | Delete one or all list element(s) a datanode for a given dataspace and anchor given a node xpath. | anchor and dataspace204 400 401 403 | 204 (no content)
400 (bad request)
500 (internal server error)
| |||||
14 | Data | PATCH | 18 | Query | GET - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes/query CpsQueryApiCpsDataApi.getNodesByDataspaceAndAnchorAndCpsPathupdateNodeLeaves() | Query Update a data nodes node leaves for the a given dataspace and anchor using CPS pathand a parent node xpath | 200 400 401 403 404 |
CPS-NCMP
200 (ok)
400 (bad request)
500 (internal server error)
| ||||||||||||||
15 | Data | PUT - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/list-nodes CpsDataApi.replaceListContent() | Replace list content under a given parent, anchor and dataspace | |||||||||||
# | Sub interface | Method | Scenario | Specified HTTP Response Code | Implemented HTTP Response Code | Comments | Body | |||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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 handle200 400 401 403 404 | 200 (ok) 500 | 2 | Data |
400 (bad request)
500 (internal server error)
| |||||||
16 | Data | POST GET - /v1/chdataspaces/{cmdataspace-handlename}/data/ds/ncmp-datastore:passthrough-running NetworkCmProxyApi.getResourceDataRunningForCmHandle() | Get resource data from pass-through running for given cm handle | anchors/{anchor-name}/list-nodes CpsDataApi.addListElements() | Add list element(s) to a list for a given anchor and dataspace | 201200 400 401 403 404 | 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 | 201 (created)
400 (bad request)
500 (internal server error)
| ||
17 |
|
|
404 | 200 500 | 4 | Data |
| |||||||
18 | Query | GET POST - /v1/chdataspaces/{cmdataspace-handlename}/data/ds/ncmp-datastore:passthrough-runninganchors/{anchor-name}/nodes/query CpsQueryApi.getNodesByDataspaceAndAnchorAndCpsPathNetworkCmProxyApi.createResourceDataRunningForCmHandle() | Create resource data from pass-through running for given cm handle | Query data nodes for the given dataspace and anchor using CPS path | 200201 400 401 403 404 | 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 | 200 400 401 403 404 | 200 500 | 200 (ok)
400 (bad request)
500 (internal server error)
| Specification:
|
CPS-NCMP
(commit id 8c9b4a24b4841154a2d08f506e2f7beca4f6fc31)
# | Sub interface | Method | Scenario | Specified HTTP Response Code | Implemented HTTP Response Code | Changes Required | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
1 | Data | HTTP: | 6 | Model | GET - /v1/ch/{cm-handle} | /modules/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)
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 | 200 400 401 403 | 200 500 | (internal server error)
| Specification:
Implementation:
|
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 | 200 | 8 | Inventory | POST /v1/ch NetworkCmProxyInventoryApi.updateDmiPluginRegistration() | Register, update or remove cm handles | 201 400 401 403 | 201 500 | Implementation:
|
DMI-Plugin
404 | 200 (ok)
500 (internal server error)
| Specification:
Implementation:
| |||||||||
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 | 200 | |||||||
# | Sub interface | Method | Scenario | Specified HTTP Response Code | Implemented HTTP Response Code | Comments | |||||
---|---|---|---|---|---|---|---|---|---|---|---|
1 | DMI Plugin Internal | Register given list of cm handles (internal use only) | 201400 401 403 | 201 404 | 200 ( | createdok)
| 400 (bad request500 (internal server error)
| empty cm handles list from input
| any
| from NCMP that is different form 201 (CmHandleRegistrationException
| Specification:
Implementation:
|
4 | Data | 2 | DMI Plugin | POST - /v1/ch/{cmHandlecm-handle}/modules DmiPluginApi.getModuleReferences() data/ds/ncmp-datastore:passthrough-running NetworkCmProxyApi.createResourceDataRunningForCmHandle() | Create resource data from pass-through running Get all modules for given cm handle | 200201 400 401 403 404 | 201 200 (okcreated)
404 (not found)
500 (internal server error) 500 (internal server error)
| Specification:
Implementation:
| |||
5 | Data | PATCH | 3 | DMI Plugin | POST - /v1/ch/{cmHandlecm-handle}/moduleResources DmiPluginApi.retrieveModuleResources() data/ds/ncmp-datastore:passthrough-running NetworkCmProxyApi.patchResourceDataRunningForCmHandle() | Patch resource data from pass-through running for the given cm handleRetrieve module resources for one or more modules | 200 400 401 403 404 | 200 (ok)
404 (not found)
500 (internal server error)
| Specification: |
Implementation:
| |
6 | Model | GET | 4 | DMI 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.cm-handle}/modules NetworkCmProxyApi.getModuleReferencesByCmHandle | Fetch all module references (name and revision) for a given cm handle | 200 400 401 403 404 | 200 (ok)
400 (bad request)
500 (internal server error) for any SDNC response code that is different from 200 (ResourceDataNotFound)
| Specification: | 5 |
Implementation
|
7 | ModelDMI 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. | searches NetworkCmProxyApi.executeCmHandleSearch | Execute cm handle searches using 'hasAllModules' condition to get all cm handles for the given module names | 200201 400 401 403 | 200 (ok)
201 (created)
204 (no content)
400 (bad request)
500 (internal server error)
Specification
Implementation
|
CPS-Temporal
500 (internal server error)
| Implementation:
| |||||||||
8 | Inventory | POST /v1/ch NetworkCmProxyInventoryApi.updateDmiPluginRegistration() | Register, update or remove cm handles | 201 400 401 403 | 201 (created)
500 (internal server error)
| |||||
# | 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 |
| 2 | Query | Get anchors data based on filter criteria | 200 400 401 403 | 200 (ok)
400 (bad request)
500 (internal server error)
|
...
Specification:
Implementation:
|
DMI-Plugin
(commit id 1954daa5d31b537a8838d1e11cb41cd6f40b58d9)
# | Sub interface | Method | Scenario | Specified HTTP Response Code | Implemented HTTP Response Code | Changes Required |
---|---|---|---|---|---|---|
1 | DMI Plugin Internal | POST - /v1/inventory/cmHandles DmiPluginInternalApi.registerCmHandles() | Register given list of cm handles (internal use only) | 201 400 401 403 | 201 (created)
400 (bad request)
500 (internal server error)
| Implementation
|
2 | DMI Plugin | POST - /v1/ch/{cmHandle}/modules DmiPluginApi.getModuleReferences() | Get all modules for given cm handle | 200 400 401 403 | 200 (ok)
404 (not found)
500 (internal server error)
| Specification:
|
3 | DMI Plugin | POST - /v1/ch/{cmHandle}/moduleResources DmiPluginApi.retrieveModuleResources() | Retrieve module resources for one or more modules | 200 400 401 403 | 200 (ok)
404 (not found)
500 (internal server error)
| Implementation:
|
4 | DMI 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)
400 (bad request)
500 (internal server error)
| Implementation:
|
5 | DMI 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)
201 (created)
204 (no content)
400 (bad request)
500 (internal server error)
| Specification
Implementation
|
CPS-Temporal
(commit id 13483eacf395cae83239dd0f17114986b9476d19)
# | Sub interface | Method | Scenario | Specified HTTP Response Code | Implemented HTTP Response Code | Changes Required |
---|---|---|---|---|---|---|
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 (bad request)
500 (internal server error)
| |
2 | Query | GET - /v1/dataspaces/{dataspace-name}/anchors/history CpsTemporalQueryApi.getAnchorsDataByFilter() | Get anchors data based on filter criteria | 200 400 401 403 | 200 (ok)
400 (bad request)
500 (internal server error)
|
General comments for all endpoints
Specification
- Refer to https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml#http-status-codes-1
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
...