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
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 specifies an object member that does not already exist, a new member is added to the object. Remove: The "remove" operation removes the value at the target location, given an object already exists at the location Replace/Update: If the target location specifies an object member that does exist, that member's value is replaced. Here target location is equivalent to the path of particular leaf So, there it should be Add/Delete. This approach is applicable when using JSON-P library. Also, libraries such as Jackson or Gson, have their own conventions and ways of generating a delta between 2 json.
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	The above scenarios need to be explored and documented in detail. Such as handling arrays within a json.
4	Need to decide what the action/operation should be called.	Proposed: Add/Delete/Update RFC-6902: add/remove/replace

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?firstAnchor={anchor-name}?secondAnchor={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
firstAnchor	Query	Yes	First Anchor Name/Reference Anchor
secondAnchor	Query	Yes	Second Anchor Name
xpath	Query	Yes	xpath of the node
descendants	Query	No	Number 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"
    }
  }
]

Space shortcuts

Page tree

CPS Delta feature Exceptions

Issues & Decisions

HTTP response codes for Delta API

Request parameters:

Response Body/Delta Report Format

Mechanism for Delta generation