CPS Delta Feature API design

CPS Delta feature Exceptions

Where ever possible the Delta Feature will throw the same exceptions as defined in CPS core. If any new exception for the delta feature are required the following will be updated here.

Issues & Decisions

#

Issue

Notes

Decision

1

Add or Delete leaves (optional leaves) handle as UPDATE or ADD/DELETE ?

The delta report proposed follows the Json Patch format of representing the differences between 2 json. Going by the general convention, referring RFC-6902:

Add: If the target location in the source document specifies an object member that does not already exist, and a new member is added to the object, then its an add operation
Remove: if the target location in the source document already had a member and the member was removed from the target document then its remove operation
Replace/Update: If the target location specifies an object member that does exist, and that member's value is replaced, then its a replace operation
Here target location is equivalent to the path of particular leaf
So, there it should be Add/Delete.
Discussed in detail below

Add/Delete as per notes on the left

2

How to handle multiple changes at different levels?

Example:

if you compare multiple levels and say a grandchild of a the node you are comparing has been added or deleted is that an UPDATE or just a ADD/DELETE at that level

There could be Many more complex scenarios....

3

More scenarios need to be explored and documented in detail. Such as handling arrays within a json, handling child/grandchild changes.

HTTP response codes for Delta 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- /v1/dataspaces/{dataspace-name}/delta?anchor1={anchor-name}?anchor2={anchor-name}?xpath={xpath}&descendants={descendants}

Proposed method name: <decision pending>

Generate a delta report between 2 anchors in a given dataspace.

200 (OK)
- success
400
- dataspace not found
  DataspaceNotFoundException
- anchor not found
  AnchorNotFoundException
- Data node not found
  DataNodeNotFoundException
- invalid xpath
  CpsPathException
500
- unexpected error

AnchorNotFoundException should provide the name of missing anchor from the given two anchor names.

Request parameters:

Parameter name	In	Required	Description
dataspace-name	Path	Yes	Dataspace name
anchor1	Query	Yes	First Anchor Name/Reference Anchor
anchor2	Query	Yes	Second Anchor Name
xpath	Query	Yes	xpath of the node
descendants	Query	No	Level of descendants for delta comparison.

Response Body/Delta Report Format

Response body should contain anchors delta report (added/deleted/modified configuration) as below.

[
  {
    "action": "ADD",
    "xpath": "/bookstore/categories/[@code=3]",
    "payload": {
      "code": 3,
      "name": "kidz"
    }
  },
  {
    "action": "DELETE",
    "xpath": "/bookstore/categories/[@code=1]",
    "payload": {
      "code": 1,
      "name": "Fiction"
    }
  },
  {
    "action": "UPDATE",
    "xpath": "/bookstore/categories/[@code=2]",
    "payload": {
      "name": "Comic"
    }
  }
]

Mechanism for Delta generation

Additional Details

Format/Conventions to be used for Delta Report (not finalized)

There are several ways of representing the differences between JSON but here we discuss the JSON Patch format of representing these differences because the proposed Delta report closely represents JSON patch with a few differences. This approach focuses in producing another JSON document that represents the differences between the two JSON's that have been compared.

JSON Patch

JSON Patch defines a JSON document structure for expressing a sequence of operations to apply to a JavaScript Object Notation(JSON) document; it is suitable for use with the HTTP PATCH method. The "application/json-patch+json" media type is used to identify such patch documents.

But in it can also be used to get the differences between two JSON as the JSON patch document represents an array of objects. where each object represents a single operation(op), path and value.

Here the notation of operation is used as the same JSON Patch document can be used to perform HTTP Patch operations. But The operations field can be used as a reference to decide how the "action" field should function in the implementation of Delta report.

The operation "op" field in a JSON patch document can have following values:

Operation	Description	Delta report equivalent
`add`	Adds the value at the target location; if the value exists in the given location, it’s replaced	if the value is not present in the source json, but was found in the comparand json, then it should be considered an "add" action
`remove`	Removes the value at the target location	if a value was present at the source json, but was not found in the comparand json, then it should be considered as "delete" action
`replace`	Replaces the value at the target location	if a value is present in the source json, but an updated value is present in the comparand json, then it will be considered as "update" action
`move`	Removes the value at a specified location and adds it to the target location	N/A
`copy`	Copies the value at a specified location to the target location	N/A
`test`	Tests that a value at the target location is equal to a specified value	N/A

Sample JSON Patch

[
     { "op": "test", "path": "/a/b/c", "value": "foo" },
     { "op": "remove", "path": "/a/b/c" },
     { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
     { "op": "replace", "path": "/a/b/c", "value": 42 },
     { "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
     { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
   ]

Space shortcuts

Page tree