Table of Contents |
---|
Issues and Decisions
Date | Issue/Questions | Decisions |
---|---|---|
| Should dry-run be a path parameter or a query parameter? | dry-run flag should be an optional query parameter, making it part of path parameter will result in change in multiple endpoints using this feature. List of these APIs can be found below. And changing the path/endpoint by using dry-run as path parameter may impact backwards compatibility of these APIs |
Overview
Currently when persisting any data in CPS the data validation is performed using the yang schema and upon successful validation the data is stored in CPS DB. But in case the data validation fails a 500 response is returned by CPS.
...
This is not very helpful for the user as it does not provide proper information about the root cause of failure.
Proposal
The idea here is to have a mechanism to validate the data and throw an appropriate response with message, before the data is persisted in the database. This validation check is not meant to be limited for new data but should also extend to sub-parts of a larger data set, such as data used in case of an update operation. So based on this the following approaches are proposed to perform a validation on data:
- A new endpoint to validate the JSON payload against an existing schema in CPS DB, this endpoint will only validate the data and never persist it.
- A dry-run flag in the existing CPS API's which would validate the data and return a response containing the details of validation failure. This flag can be implemented to multiple CPS APIs such as POST (Create a Node), PATCH (Update a Node) and PUT (Replace a node), where we can validate the entire data or parts of data and return the exact point of failure in the validation as part of response.
Implementation Ideas
In either case the endpoint should return a REST response with appropriate code and message.
- Response Code: 400
- Response Body: a JSON response providing details about the failure. (response body format to be finalized)
List of impacted APIs
Name | Endpoint | Issue | Required Action | |||||||
---|---|---|---|---|---|---|---|---|---|---|
1 | Create a Node | /{apiVersion}/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes | Returns 500 status on data validation failure | Return 400 status with updated and detailed error message. Updated Message:
| details": "Failed to parse JSON data.
Data
| Schema Node "categories"."
| ||||
2 | Update Node Leaves | /{apiVersion}/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes | Returns 400 status with entire JSON payload in error message | |||||||
3 | Replace Nodes | /{apiVersion}/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes | Returns 400 status with entire JSON payload in error message | |||||||
4 | Add List Element | /{apiVersion}/dataspaces/{dataspace-name}/anchors/{anchor-name}/list-nodes | Returns 500 status on data validation failure | |||||||
5 | Replace List element | /{apiVersion}/dataspaces/{dataspace-name}/anchors/{anchor-name}/list-nodes | Returns 400 status with entire JSON payload in error message | 6 | Get Delta between anchor and JSON payload | /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/deltaAnchors | Returns 400 status with entire JSON payload in error message |
Example
The following example shows the expected changes to existing APIs to implement a dry-run flag:
# | API | Request parameters | Response Codes | Scenarios | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
1 | Create a Node: /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes |
|
| Scenario 1: dry run set to false
Scenario 2: dry run set to true
|
|
|
|
|
|
References:
...