Documentation update for Delta Feature

 - Documantation about Delta Feature
 - Documantation on API 1: Delta between 2 anchors

Issue-ID: CPS-2056
Signed-off-by: Arpit Singh <as00745003@techmahindra.com>
Change-Id: I9841ea166f7c57ab6218fefa5b577b4053e39490

diff --git a/docs/_static/cps-delta-mechanism.png b/docs/_static/cps-delta-mechanism.png
new file mode 100644 (file)
index 0000000..ab78ad9
Binary files /dev/null and b/docs/_static/cps-delta-mechanism.png differ

diff --git a/docs/cps-delta-endpoints.rst b/docs/cps-delta-endpoints.rst
new file mode 100644 (file)
index 0000000..b2e4e60
--- /dev/null
+++ b/docs/cps-delta-endpoints.rst
@@ -0,0 +1,66 @@
+.. 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:
+
+- /v2/dataspaces/{dataspace-name}/anchors/{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.
+
+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
+
+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']
+    - **descendants:** specifies the number of descendants to query.
+
+Sample Delta Report
+-------------------
+
+.. code-block:: json
+
+    [
+      {
+        "action": "ADD",
+        "xpath": "/bookstore/categories/[@code=3]",
+        "target-data": {
+          "code": "3,",
+          "name": "kidz"
+        }
+      },
+      {
+        "action": "REMOVE",
+        "xpath": "/bookstore/categories/[@code=1]",
+        "source-data": {
+          "code": "1,",
+          "name": "Fiction"
+        }
+      },
+      {
+        "action": "UPDATE",
+        "xpath": "/bookstore/categories/[@code=2]",
+        "source-data": {
+          "name": "Funny"
+        },
+        "target-data": {
+          "name": "Comic"
+        }
+      }
+    ]
\ No newline at end of file

diff --git a/docs/cps-delta-feature.rst b/docs/cps-delta-feature.rst
new file mode 100644 (file)
index 0000000..f3a2f94
--- /dev/null
+++ b/docs/cps-delta-feature.rst
@@ -0,0 +1,44 @@
+.. 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:
+
+.. toctree::
+   :maxdepth: 1
+
+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 Delta feature brings a new functionality:
+
+    - Ability to find the delta between the configurations stored in two anchors within the same dataspace.
+
+The calculated differences can then be used to generate a Delta Report which can be sent 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 ADD, DELETE or UPDATE 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 deleted 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 deleted 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.
+
+Mechanism for Delta generation
+------------------------------
+
+.. image:: _static/cps-delta-mechanism.png
+   :alt: Mechanism for Delta generation
+
+Endpoints provided as part of Delta Feature
+-------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   cps-delta-endpoints.rst
\ No newline at end of file

diff --git a/docs/modeling.rst b/docs/modeling.rst
index ceaaefd..7ebf6fe 100644 (file)
--- a/docs/modeling.rst
+++ b/docs/modeling.rst
@@ -63,6 +63,14 @@ Querying
    xpath.rst
    cps-path.rst
 
+Additional information on CPS-Core Interfaces
+---------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   cps-delta-feature.rst
+
 .. Below Label is used by documentation for other CPS components to link here, do not remove even if it gives a warning
 .. _cps_ncmp_modelling: