RTD update for delta API 2
- Documentation update for Delta Feature and Delta API 1
- Added documentation for API 2: Delta between anchor
and JSON payload
Issue-ID: CPS-2212
Signed-off-by: Arpit Singh <as00745003@techmahindra.com>
Change-Id: Id74cd930ce48e5cb414aa62c5381b79675346a37
diff --git a/docs/cps-delta-endpoints.rst b/docs/cps-delta-endpoints.rst
index ecb7550..47f52dc 100644
--- a/docs/cps-delta-endpoints.rst
+++ b/docs/cps-delta-endpoints.rst
@@ -1,38 +1,53 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-.. Copyright (C) 2021 Pantheon.tech
.. Copyright (C) 2024 TechMahindra Ltd.
.. _cpsDeltaEndpoints:
-.. toctree::
- :maxdepth: 1
-
CPS Delta Endpoints
###################
-The CPS Delta feature provides 1 endpoint:
+The CPS Delta feature provides two endpoints:
-- /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/delta
+1. GET /v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta
+2. POST /v2/dataspaces/{dataspace-name}/anchors/{source-anchor-name}/delta
-Description
------------
-The following is a Get endpoint, which allows the user to find the delta between configurations stored under two anchors within the same dataspace.
+Common Parameters of both the endpoints
+---------------------------------------
+Common Path Parameters
+^^^^^^^^^^^^^^^^^^^^^^
+The following parameters are common inputs between the two endpoints:
+ - **dataspace-name:** name of dataspace where the anchor(s) to be used for delta generation are stored.
+ - **source-anchor-name:** the source anchor name, the data under this anchor will be the reference data for delta report generation
-Path Parameters
----------------
-The endpoint takes 2 path parameters as input:
- - **dataspace-name:** name of dataspace where the 2 anchors to be used for delta generation are stored.
- - **anchor-name:** the source anchor name, the data under this anchor will be the reference data for delta report generation
+Common Query Parameter
+^^^^^^^^^^^^^^^^^^^^^^
+Both the endpoint need the following query parameters as input:
+ - **xpath:** the xpath to a particular data node.
+ - Example: /bookstore/categories[@code='1']
-Query Parameters
-----------------
-The endpoint takes 3 query parameters as input:
- - **target-anchor-name:** the data retrieved from target anchor gets compared against the data retrieved from source anchor
- - **xpath:** the xpath to a particular data node, Example: /bookstore/categories[@code='1']
+Description of API 1: Delta between 2 Anchors
+---------------------------------------------
+This API performs a GET operation, which allows the user to find the delta between configurations stored under two anchors within the same dataspace. The API has following input parameters:
+
+Specific Query Parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The endpoint takes following additional/specific query parameters as input:
+ - **target-anchor-name:** the data retrieved from target anchor is compared against the data retrieved from source anchor
- **descendants:** specifies the number of descendants to query.
+Description of API 2: Delta between Anchor and JSON payload
+-----------------------------------------------------------
+This API performs a POST operation, which allows the user to find the delta between configurations stored under an anchors and a JSON payload provided as part of the request. The API has the following input parameters:
+
+Request Body for Endpoint 2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The endpoint accepts a **multipart/form-data** input as part of request body. This allows the user to provide the following inputs as part of request body:
+ - **JSON payload:** this field accepts a valid JSON string as an input. The data provided as part of this JSON will be parsed using the schema, the schema is either retrieved using the anchor name or it can be provided as part of request body using the optional parameter of request body defined below. Once the JSON is parsed and validated, it is compared to the data fetched from the source anchor and the delta report is generated.
+ - **schema-context:** this is an optional parameter and allows the user to provide the schema of the JSON payload, as a yang or zip file, and this schema can be used to parse the JSON string in case the schema of JSON differs from the schema associated with source anchor. If the schema of JSON payload is similar to the schema associated with the anchor then this parameter can be left empty.
+
Sample Delta Report
-------------------
+Both the APIs have the same format for the delta report. The format is as follows:
.. code-block:: json
diff --git a/docs/cps-delta-feature.rst b/docs/cps-delta-feature.rst
index 34aa43d..ee3df45 100644
--- a/docs/cps-delta-feature.rst
+++ b/docs/cps-delta-feature.rst
@@ -1,6 +1,5 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-.. Copyright (C) 2021 Pantheon.tech
.. Copyright (C) 2024 TechMahindra Ltd.
.. _cpsDelta:
@@ -10,24 +9,26 @@
CPS Delta Feature
#################
-- The concept of CPS Delta Feature is to have the ability to find the delta or difference between two configurations stored in CPS DB.
+- The concept of CPS Delta Feature is to have the ability to find the delta or difference between two configurations in CPS.
-- The Delta feature brings a new functionality:
+- The Delta feature provides two new endpoints, providing the following functionalities:
- Ability to find the delta between the configurations stored in two anchors within the same dataspace.
+ - Ability to find the delta between the configurations stored under an anchor and a JSON payload provided as part of REST request.
-The calculated differences can then be used to generate a Delta Report which can be sent over the Kafka Notification Service to the user.
+The difference found are compiled into a Delta Report returned by the server. This report can be used in several different ways, one such use case is sending it over the Kafka Notification Service to the user.
Delta Report Format
-------------------
-The Delta Report is based on the RFC 9144, which defines a set of parameters to be included in the Delta Report. In CPS only the relevant parameters defined in RFC 9144 are used. These include:
- - **action:** This parameter defines how the data nodes changed between two configurations. If data nodes are added, deleted or modified then the 'action' parameter in the delta report will be set to 'create', 'remove' or 'replace' respectively for each data node.
+The Delta Report is based on the RFC 6902 and RFC 9144, which define a set of parameters to be included in the Delta Report. In CPS only the relevant parameters defined in the RFCs are used. These include:
+ - **action:** This parameter defines how the data nodes changed between two configurations. If data nodes are added, deleted or modified then the 'action' parameter in the delta report will be set to one of the following pre-defined operation values, i.e., 'create', 'remove' or 'replace' respectively for each data node.
- **xpath:** This parameter will provide the xpath of each data node that has been either added, deleted or modified.
- **source-data:** this parameter is added to the delta report when a data node is removed or updated, this represents the source/reference data against which the delta is being generated. In case of newly added data node this field is not included in the delta report.
- **target-data:** this parameter is added to the delta report when a data node is added or updated, this represents the data values that are being compared to the source data. In case of a data node being removed this field is not included in the delta report.
**Note.** In case of an existing data node being modified, both the source-data and target-data fields are present in the delta report.
+**Additional Information.** `Analysis of RFC 9144 and RFC 6902 for Delta Report generation <https://lf-onap.atlassian.net/wiki/spaces/DW/pages/16523520/Analysis+of+RFC+9144+and+RFC6902+for+Delta+Report+generation>`_
Mechanism for Delta generation
------------------------------