...
| 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:
...
| # | 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 |
|
Changes and Justification for going for 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.