Issues/Decisions/Open Questions
| Slogan | Notes | Decision | |
|---|---|---|---|
| 1 | Which alternative | ||
| 2 |
Introduction
Currently CPS Delta Feature provides 2 endpoints as follows:
- GET-/v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/deltaAnchors
- POST- /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/deltaByPayload
Objective
The objective of this proposal is to have a new singular delta endpoint which can provide the functionality of the above-mentioned endpoints. This new endpoint will be a POST operation and will accept the source anchor name as the path parameter, xpath as the query parameter and a request body which will serve 2 functions:
- first it can be used to provide the target anchor name as a replacement for query parameter of first API
- second it can be used to provide the JSON payload as defined in proposal of 2nd API
After determining whether an anchor name or JSON payload is provided in the request the respective underlying controller will be called. So only the endpoints will be merged to a singular endpoint, and the underlying logic will remain same.
Alternative 1: Single Endpoint
| # | Sub interface | Method | Scenario | HTTP response code | Notes |
|---|---|---|---|---|---|
| 1 | Data |
| Generate a delta report between a source anchor and target anchor or JSON payload |
|
Request parameters:
Parameter name | In | Required | Description |
|---|---|---|---|
| dataspace-name | Path | Yes | Dataspace name |
| anchor | Path | Yes | Source Anchor Name |
| xpath | Query | Yes | xpath of the node |
| descendants | Query | No | Level of descendants for delta comparison. Set to INCLUDE_ALL_DESCENDANTS by default. |
Request body:
Content-Type: multipart/form-data
Type | Format | Description |
|---|---|---|
| File | Yang file/Zip file | file containing the schema details. |
| Text/String | Target anchor name or JSON payload as plain text |
|
Alternative 2: One Endpoint with Two Operations
In RESTful interface we can have same endpoint for multiple APIs, given they are performing different operations, for example POST and GET.
So, we can have the following endpoints in CPS for the Delta feature:
- GET /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/delta
- POST /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/delta
Sample endpoints after change
After the update only the names of the endpoint will be updated, the path and query parameters will remain as it is. So, the updated APIs would be as follows:
| # | Existing Endpoint | Updated Endpoint | Path/Query Parameters | Response Codes | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | GET-/v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/deltaAnchors | GET-/v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta/{target-anchor-name} |
|
| ||||||||||||||||||||||||
| 2 | POST- /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/deltaPayload | POST- /v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta |
|