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) |
Spike CPS-
...
728: Inventory of HTTP Response Codes for all CPS interfaces
Jira | ||||||
---|---|---|---|---|---|---|
|
CPS-Core
(commit id 8c9b4a24b4841154a2d08f506e2f7beca4f6fc31)
# | Sub interface | Method | Scenario | Specified HTTP Response Code | Implemented HTTP Response Code | Changes 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:
|
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:
|
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 |
...
HTTP: GET - /v1/ch/{cm-handle}/data/ds/ncmp-datastore:passthrough-operational
NetworkCmProxyApi.getResourceDataOperationalForCmHandle()
...
Specified: 200, 400, 401, 403, 404
Implemented: 200, 500
...
GET - /v1/ch/{cm-handle}/data/ds/ncmp-datastore:passthrough-running
NetworkCmProxyApi.getResourceDataRunningForCmHandle()
...
Specified: 200, 400, 401, 403, 404
Implemented: 200, 500
...
PUT- /v1/ch/{cm-handle}/data/ds/ncmp-datastore:passthrough-running
NetworkCmProxyApi.updateResourceDataRunningForCmHandle()
...
Specified: 200, 400, 401, 403, 404
Implemented: 200, 500
...
POST - /v1/ch/{cm-handle}/data/ds/ncmp-datastore:passthrough-running
NetworkCmProxyApi.createResourceDataRunningForCmHandle()
...
Specified: 201, 400, 401, 403, 404
Implemented: 201, 500
...
PATCH - /v1/ch/{cm-handle}/data/ds/ncmp-datastore:passthrough-running
NetworkCmProxyApi.patchResourceDataRunningForCmHandle()
...
Specified: 200, 400, 401, 403, 404
Implemented: 200, 500
...
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
...
POST - /v1/ch/searches
NetworkCmProxyApi.executeCmHandleSearch
...
Specified: 200, 400, 401, 403
Implemented: 200, 500
...
POST /v1/ch
NetworkCmProxyInventoryApi.updateDmiPluginRegistration()
...
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
...
CPS-Temporal
# | Sub interface | Method | Scenario | Specified HTTP Response Code | Implemented HTTP Response Code | To Do | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
1 | Query | GET- /v1/dataspaces/{dataspace-name}/ | anchors/{anchor-name}/historyGet anchor data by name | 200schema-sets CpsAdminApi.createSchemaSet() | Create a new schema set in the given dataspace | 201 400 401 403 | 200 - ok 400 - for input data validation errors 500 - for unexpected system errors |
| 2 | Query | Get anchors data based on filter criteria | 200 400 401 403 | 200 - ok 400 - for input data validation errors 500 - for unexpected system errors | 201 (created)
400 (bad request)
409 (conflict)
500 (internal server error)
| Specification:
Implementation
|
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 | 200 (ok)
400 (bad request)
500 (internal server error)
| Specification:
| |||||||||
11 | Data | PUT - /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes CpsDataApi.replaceNode() | Replace a node with descendants for a given dataspace, anchor and a parent node xpath | 200 400 401 403 | 200 (ok)
400 (bad request)
500 (internal server error)
| Implementation:
| |||||||||
12 | Data | 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)
400 (bad request)
409 (conflict)
500 (internal server error)
| Specification:
| |||||||||
13 | Data | 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)
400 (bad request)
500 (internal server error)
| ||||||||||
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 | 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 | 200 400 401 403 | 200 (ok)
400 (bad request)
500 (internal server error)
| ||||||||||
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 | 201 (created)
400 (bad request)
500 (internal server error)
| ||||||||||
17 |
|
|
|
| |||||||||||
18 | Query | 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)
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: 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)
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 400 401 403 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 400 401 403 404 | 200 (ok)
500 (internal server error)
| Specification:
Implementation:
|
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 | 201 400 401 403 404 | 201 (created)
500 (internal server error)
| Specification:
Implementation:
|
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 (ok)
500 (internal server error)
| Specification:
Implementation:
|
6 | Model | 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)
500 (internal server error)
| Specification:
Implementation
|
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 (ok)
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)
| 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