References

CPS-390 - Getting issue details... STATUS

RESTful API Design Specification

Issues and Decisions

DMI URI

Below table shows the proposed interface, actual implementation might deviate from this but can be accessed from

• Gerrit Source 
• Read-the-docs: https://docs.onap.org/projects/onap-cps-ncmp-dmi-plugin/en/latest/design.html

DMI URI format to follow below pattern

<OP>dmi/<v{vNumber}>/ch/<cmHandle>/<data|operations|dmiAction>/ds/<datastore>/[rp:]<resourcePath>?<query>

NCPS-NCMP - DMI Plugin Write Request Flow

See CPS-577: Prepare the request from client and send write request to dmi-plugin

Datastore

If the cmhandle metadata indicates that data is not synched in CPS then the request is forwarded to the dmiPlugin

RESTCONF/NETCONF relationship

REST Data API

The DMI APIs for data access are similar to corresponding NCMP APIs. The following list is a summary of the main differences:

1. The URI prefix is /dmi instead of /ncmp.
2. For non-passthrough datastores, the resource path will be converted from cpsPath to RESTConfPath

3. The body for each request will contain additional information and any data provided on the NCMP interface (write operations) will be embedded in a larger JSON structure as described in example below.
   

4. Since all requests will have a message body, in some cases the HTTP method will be different to allow passing data. Thus PUT is used instead of GET and DELETE.

Request Format for Data Access

{
  “operation”: “<operation>”,         // Valid operations are: “create”, “read”, “update” and “delete”.
                                      // For update, replace and patch is distinguished by the HTTP method (PUT or PATCH).
  "dataType": "<dataType>",

    “data”: {                           // Embedded data as a String.
    <data>                            // required for create and update operations. Optional filter-data for read-operations
  },

  “cmHandleProperties”: {           // Additional properties for CM handle previously added by DMI plugin and stored in NCMP.
    <properties>
  }
}

DMI Inventory, Model & Data Sync API

 This presentation illustrates the API methods #1, #3 and #4 detailed below

{
  "operation": "read",
    "cmHandleProperties ": {
      "subSystemId": "system-001"
    }
  }
}

Response:  
     "schemas": [
                    {
                      "moduleName": "example-identifier",
                      "revision": "example-version",
                      "namespace": "example-namespace"
                    },
					{
						...
					}
                  ]
                }

{
  "operation": "read",
	"dataType": "application/json",
    "data": {
       "modules": [
        {
          "name": "pnf-sw-upgrade",
          "revision": "2019-12-03"
        }
      ]
    },
    "cmHandleProperties": {
      "subSystemId": "system-001"
    }
}

Response: a list yang module references and source for each

[ {
"name" : "pnf-sw-upgrade",
"revision" : "2019-12-03",
"yang-source": "some-source", {...} ]

GET Request with body

The HTTP libraries of certain languages (notably JavaScript) don’t allow GET requests to have a request body. In fact, some users are surprised that GET requests are ever allowed to have a body.

The truth is that RFC 7231—the RFC that deals with HTTP semantics and content—does not define what should happen to a GET request with a body! As a result, some HTTP servers allow it, and some—especially caching proxies—don’t.

The authors of Elasticsearch prefer using GET for a search request because they feel that it describes the action—retrieving information—better than the POST verb. However, because GET with a request body is not universally supported, the search API also accepts POST requests: }

The same rule applies to any other GET API that requires a request body.
See Elasticsearch details here for more info

yang-patch operations (see rfc8072)

"create", "delete", "insert", "merge", "move", "replace", and "remove"

YANG Data Structure Extensions

https://tools.ietf.org/html/rfc8791

References

Follow principles/patterns of RESTCONF RFC-8040 https://datatracker.ietf.org/doc/html/rfc8040
Follow principles/patterns of yang-patch RFC-8072 https://datatracker.ietf.org/doc/html/rfc8040
Follow principles/patterns of RESTCONF NMDA RFC-8527 https://datatracker.ietf.org/doc/html/rfc8527