| Table of Contents |
|---|
Issues/Decisions/Open Questions
| Slogan | Notes | Decision | |
|---|---|---|---|
| 1 | Which alternative | changed target anchor name to a query parameter | Second approach of having one endpoint capable of performing 2 operations |
| 2 |
Introduction
Currently CPS Delta Feature provides 2 endpoints as follows:
- GET-/v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/delta?anchor2={anchor-name}?xpath={xpath}&descendants={descendants}deltaAnchors
- POST- /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/deltaByPayload?xpath={xpath}
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:
...
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.
...
- 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 GET-/v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta?target-anchor-name={target-anchor-name}&descendants={descendants}&xpath={xpath} |
|
| ||||||||||||||||||||||||
| 2 | POST- /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/deltaPayload | POST- /v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta POST- /v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta?xpath={xpath} Body file- yang schema ( Optional ) json - JSON payload as String ( Mandatory ) |
|
Changes and Justification for going with second approach
The second proposed approach is best suited for the scenario, but there are a few minor changes to it:
Changes
- It was proposed to have "target-anchor-name" as a path parameter of the endpoint, resulting in a new endpoint as follows: GET-/v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta/{target-anchor-name}
- but it is suggested to set it as a query parameter due to limitations and reasons listed below.
Limitations
An attempt to set "target-anchor-name" as path parameter was made and following limitations were found out:
The base endpoint was set to /v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta and when "target-anchor-name" is set as path parameter and appended towards the end of the base endpoint, it lead to a failure when executing the request because according to REST standards a path parameter should be part of the path and are always included in the base URI. So appending then towards the end of an URI is technically incorrect and throws the following error
Code Block title Error message collapse true { "status": "500 INTERNAL_SERVER_ERROR", "message": "Required URI template variable 'target-anchor-name' for method parameter type String is not present", "details": "Check logs for details." }Apart from this after setting "target-anchor-name" as path parameter the URI generated was "/v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta" instead of "/v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta/target-anchor-name/{target-anchor-name} because REST ignores any path parameter set after the base URI..
- So, alternatively an attempt to set "target-anchor-name" as part of base URI was made and this resulted in the following:
/v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/target-anchor-name/{target-anchor-name}/delta
But this approach brings us back to the original problem that is to have a singular endpoint for delta feature. And the above URI is clearly a different endpoint compared to the second operation, i.e. delta between an anchor and a payload having an endpoint as follows /v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta
Most viable approach
The best viable alternative is to set "target-anchor-name" as a query parameter. This resolves most of the problems mentioned above while solving the main issue, that is to have a singular endpoint for delta operation.
Justifications:
- since the operation is always same, i.e. delta, having a single endpoint makes more sense. So finalized endpoint is as follows /v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta
- this will also make the openapi doc more manageable
Decisions leading to above mentioned endpoint:
- we have two different ways to generate delta, so we can say the final operation is common that is "delta". So, the idea is to have the common components between the operations as path parameters, i.e dataspace name and first anchor name
- remaining components should be in query, that is target anchor name, and fetch descendants' option in first operation and JSON payload and schema in second operation.
- this approach is also consistent with existing CPS API's such as list-node APIs where a singular endpoint performs different operations while having similar parameters