Table of Contents |
---|
Overview
The second API proposed under the Delta feature is to generate a delta between configuration stored under an Anchor and JSON payload provided by the user. All the responses and exceptions thrown by this API will be similar to the API to generate delta between 2 anchors to maintain consistency between the API's.
Issues & Decisions
Questions/Issues | Decisions/Answers |
---|---|
How should the reporting of xPaths of newly added data nodes in JSON payload be done in a schema free approach for delta feature | |
Should the "descendants" option be provided as part of the API? The JSON payload may or may not contain all the child data nodes. Hence there is always the uncertainty. So, would it be a better approach to fetch all descendants always from the anchor and compare them against the JSON payload? |
HTTP response codes for Delta between Anchor and Payload API
The proposed API will be part of the CPS Data Interface. The following response codes will be returned by the API:
# | Sub Interface | Method | Scenario | HTTP Response codes to be implemented | Notes |
---|---|---|---|---|---|
1 | Data | Proposed API: GET- /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/delta?xpath={xpath}&descendants={descendants} Proposed method name: CpsDataApi.getDeltaByDataspaceAnchorAndPayload() | Generate a delta report between an anchor and JSON payload |
|
Request parameters:
Parameter name | In | Required | Description |
---|---|---|---|
dataspace-name | Path | Yes | Dataspace name |
anchor | Path | Yes | Anchor Name/Reference Anchor |
xpath | Query | Yes | xpath of the node |
descendants | Query | No | Level of descendants for delta comparison. |
Response Body/Delta Report Format
Code Block | ||||
---|---|---|---|---|
| ||||
[ { "action": "ADD", "xpath": "/bookstore/categories/[@code=3]", "target-data": { "code": 3, "name": "kidz" } }, { "action": "DELETE", "xpath": "/bookstore/categories/[@code=1]", "source-data": { "code": 1, "name": "Fiction" } }, { "action": "UPDATE", "xpath": "/bookstore/categories/[@code=2]", "source-data": { "name": "Funny" }, "target-data": { "name": "Comic" } } ] |
Reporting of xpaths in Delta between Anchor and JSON payload
In the first API for delta report generation, we have fetch the data nodes from 2 anchors and perform a comparison between each data node present under both anchors. The advantage of this approach is that we get information about the xpaths from the respective data node and hence we can report the Removed, Updated and Added xpaths in the delta report.
For the second API, we will have one anchor and a JSON payload, and here we need to perform the comparison between the data from an anchor and the json payload.
- In order to do so we need to first parse the JSON string provided by the user to some Java Object for comparison with objects returned by the anchor.
- To parse the JSON data we have following options:
- Parse it to Data Nodes, but doing so requires us to provide the schema of the associated JSON data every time a request is made therefore making the approach schema dependent
- Parsing to a generic Java object, like a Map, parsing the json data to a Java object would make the approach schema independent but in the process we cannot generate the xpaths of the data nodes present in the JSON payload, as the generation on xpaths is dependent on the Yang data model associated to the JSON
- By not having the xpaths of all the data nodes of the JSON payload, we can only report the xpaths of Removed and Updated data nodes as those can be fetched from the data nodes present in the anchor. But the xpath of any data node newly added to the JSON payload cannot be generated without proper parsing against the schema model associated to the JSON.
Problems when parsing to a generic Java Object
- When parsing the JSON string directly to a java objects we cannot generate the xpaths of all the data nodes present in the JSON payload.
- Doing so brings its own challenges,
- The comparison is dependent on xpaths, because in the current algorithm we use xpaths to identify the data nodes that have been Removed, Updated or Added, and then check for the changes in data present as leaf node in each data node.
- So without the xpaths of the data nodes present in the JSON payload, we can only report the xpaths of data nodes that have been Removed or Updated, as those xpaths can be fetched from the data nodes present under the anchor, against which the JSON payload is being compared to.
- But the xpath of any data node newly added to the JSON payload cannot be generated without proper parsing against the schema model associated to the JSON.
Also, we want the approach to be schema free, whereas the xpath building is a schema dependent activity as can be seen from the method in CPS
Code Block public static String buildXpath(final YangInstanceIdentifier.PathArgument nodeIdentifier) { final StringBuilder xpathBuilder = new StringBuilder(); xpathBuilder.append("/").append(nodeIdentifier.getNodeType().getLocalName()); if (nodeIdentifier instanceof YangInstanceIdentifier.NodeIdentifierWithPredicates) { xpathBuilder.append(getKeyAttributesStatement( (YangInstanceIdentifier.NodeIdentifierWithPredicates) nodeIdentifier)); } return xpathBuilder.toString(); }
- A few workarounds to this approach can be:
- Limiting the delta between Anchor and JSON payload to only one DataNode, by doing so we can always know that the xpath is limited to one, as it is also provided as part of the request to fetch the data node from the anchor.
- using alternative paths for delta between anchor and JSON payload like JSON path
- Not reporting the xpaths in the delta report between anchor and JSON payload
Pros and Cons of each workaround
Workaround | Pros | Cons | Notes |
---|---|---|---|
Limiting the delta between Anchor and JSON payload to only one DataNode | The DeltaReport will be consistent with the existing API i.e., Delta between 2 anchors |
| |
Using alternative paths, like JSON path | The delta report will have xpaths replaced by JSON path |
| |
Not reporting the xpaths in the delta report between anchor and JSON payload | Can be implemented for multiple data nodes |
|