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

HTTP response codes for Delta between Anchor and Payload API

Proposed API

The proposed API will be part of the CPS Data Interface. This API takes multipart form data as request body, using this the user can provide the JSON payload and its corresponding Schema Context in form of a Yang or ZIP file. This file will only be used to generate the data nodes from the JSON payload and will not be persisted in CPS DB. The following response codes will be returned by the API:

Request parameters:

Request body:

Content-Type: multipart/form-data

Response Body/Delta Report Format

[
  {
    "action": "ADDcreate",
    "xpath": "/bookstore/categories/[@code=3]",
    "target-data": {
      "code": 3,
      "name": "kidz"
    }
  },
  {
    "action": "DELETEremove",
    "xpath": "/bookstore/categories/[@code=1]",
    "source-data": {
      "code": 1,
      "name": "Fiction"
    }
  },
  {
    "action": "UPDATEreplace",
    "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

...

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

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();
    }

...

• 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 data node, as it is 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

...

• Limited to only 1 data node at a time

...

• CPS is dependent and built around xpath, hence this will be a major inconsistency
• If implemented, we will need to generate JSON paths for both, the data from anchor and the JSON payload,
• making the operation more expensive

...

• Delta report will be inconsistent and not as per the RFC standard
• It is inconsistent with respect to the existing API of delta report.

...

Functional Details about the API

The proposed API will be used to generate a delta between data fetched from an anchor against JSON payload provided by the user. The following are some key functional details about the API:

• The second Delta API utilizes the same algorithm which is used by the 1st CPS Delta API i.e. the API to generate delta between 2 anchors, by doing so we can ensure consistent results between both APIs, similar performance in delta generation and easier maintainability of code. 
• The second API fetches the data from the anchor provided as part of request and compares it to the raw JSON payload which is also sent as part of the request.
• In order to generate the delta report in the expected format, the JSON payload needs to be parsed into data nodes which would provide essential details such as xpath and leaf data.
• In order to parse the JSON payload to data nodes, the schema context of the JSON is required. The schema can be fetched using two approaches depending on the user's requirement:
  • The request body is of type multipart form data and accepts two parameters, one is the JSON payload as Text/String and the second is an optional parameter to provide the schema details in form of a yang or zip file. If the schema details are provided as part of request body, then the particular schema will be used to parse the JSON payload into data nodes.
  • If no Schema detail is provided as part of the request, then the algorithm will fetch the Schema Context using the anchor name, but here the assumption is that the JSON payload has same schema as that of the anchor.
  • If no schema is provided explicitly then the assumption is that the JSON payload has same schema as that of the anchor and it uses the anchor name to get the schema context which it, then uses to parse the JSON payload to data nodes. If in case, no schema is provided, and the schema of the anchor does not match the schema of the JSON payload then appropriate error message will be thrown.
• The descendants option is not provided as part of the request and is set to INCLUDE_ALL_DESCENDANTS by default, as one cannot be sure whether the JSON payload contains the descendants similar to the descendants in the anchor. So, the best-case scenario is to fetch all the descendants under the anchor and compare them to JSON payload.

Anchor
references references

References/Future Changes

• CPS-2310: Refactoring of CPS Delta APIs