You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 22 Next »

CPS-390 - Getting issue details... STATUS

Issues and Decisions


IssueNotesDecision
1How will hostname and port be provided when DMI-Plugin register itself and its list of cmHandles with NCMP

The team thinks that the information should instead be provided in the form of a ‘host-name’ and a ‘port’  (there was some debate on service-name v. host-name but it was settled on host-name)


e.g. "dmi-plugin" : { <host-name>,  <port> }


Where the host-name is unique. (the DB might assign an internal unique ID for each entry but that is just for indexing and x-referencing in a relation DB and this ID is not to be used/ exposed externally)

Instead of using ‘host-names’ and ‘ports’ parameters between java applications when in the cloud all we need is ‘service-names’ . The mapping of service-names to hosts and ports is done as part of the cloud configuration, in our case Kubernetes. And these are dynamic! The client application can then use a simple dns-lookup to connect to an instance of the service.

Using service names also allows any plugin to use implement scaling as they see fit e.g. partitioning


For the ONAP DMI Plugin which initial have only 1 instance we can simply hard-code the service-name and us the same name in the Kubernetes configuration e.g. “onap.cps.dmi-plugin"

DMI URI

DMI URI format to follow below pattern Sandeep Shah

<OP>dmi/<v{v-number}>/ch/<cm-handle>/<data|operations|dmi-action>/ds/{datastore}/[rp:]<resource-path>?<query>

URIMandatory or OptionalDescription
<OP>mandatorythe HTTP method
dmimandatorythe dmi root resource
<v{v-number}>mandatoryversion of the dmi interface is the target resource URI is the query parameter list
<cm-handle>mandatoryunique (string) identifier of a yang tree instance.
<data|operations|dmi-action>mandatoryyang data, rpc operation or a (non-modeled) ncmp api action
{datastore}optionaloptional datastore
<resource-path>optionalthe path expression identifying the resource that is
being accessed by the operation. If this field is not
present, then the target resource is the API itself.
<query>optionalthe set of parameters associated with the RESTCONF message;
see Section 3.4 of [RFC3986]. RESTCONF parameters have 
the familiar form of "name=value" pairs. Most query parameters are
optional to implement by the server and optional to use by the client. Each optional query parameter is identified by a URI

Datastore

If datastore (ds/{datastore}) is not included in the URL then the request is defaulted to ncmp-datastore:running/operational.

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

RESTCONF/NETCONF relationship


REST API

The examples in the below table refer back to the NCMP interface as the only difference is the  URI prefix /dmi instead of /ncmp



UsecaseREST MethodURIExample
1Add a data resource for a cmHandlePOST

{dmi-root}/dmi/v1/ch/<cmhandle>/data/ds/ncmp-datastore:running/{parent-data-resource-identifier}

{
<new-yang-data-resource>
}

Content-Type: application/json

"data" payload : yang-data+json

see example 4 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI
2Delete a data resource for a cmHandlePUT{dmi-root}/dmi/v1/ch/<cm-handle>/data/ds/ncmp-datastore:running/{resource-identifier}see example 7 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI
3Patch a data resource for a cmHandlePATCH

{dmi-root}/dmi/v1/ch/<cm-handle>/data/ds/ncmp-datastore:running/{resource-identifier}

{
<yang-data-for-merging>
}

Content-Type: application/json

"data" payload : yang-data+json

see example 5 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI
4Patch multiple child resources for a single cmHandlePATCH

{dmi-root}/dmi/v1/ch/<cm-handle>/data/ds/ncmp-datastore:running/{resource-identifier}


Content-Type: application/json

"data" payload : yang-patch+json

see example 6 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI
5Execute a yang action on a cmhandle instancePOST

{dmi-root}/dmi/v1/ch/<cm-handle>/data/ds/ncmp-datastore:operational/{resource-identifier}/{action}


input: {
         "param1Name" :"param1Value”,
          "param2Name" : "param2Value”

}


Note : If the "action" statement has no "input" section, the request message MUST NOT include a message-body

see example 10 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI
6Execute an rpc operationPOST

{dmi-root}/dmi/v1/operations/ch/<cm-handle>/ds/ncmp-datastore:operational/ {module-name}:{action}

{ input: {
            "param1Name" : "param1Value”,
             "param2Name" : "param2Value”
} }

Note: If there is no "input" section, the request MUST NOT include a message-body

see example 11 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI
7Read a filtered set of data under a data resource for a cmHandlePUT

{dmiroot}/dmi/v1/ch/<cm-handle>/data/ds/ncmp-datastore:operational/{resource-identifier}?fields={fields-expression}

OptionDescription
fieldsRequest a subset of the target
resource contents
see example 2 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI
8Read data resources with specified fields under a given data resource for a given cmHandlePUT

{dmi-root}/dmi/v1/ch/<cm-handle>/data/ds/ncmp-datastore:operational/{resource-identifier}?fields={fields-expression}


OptionDescription
fieldsRequest a subset of the target
resource contents
see example 12 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI
9Get data resource with 'fileds' for a cmhandle with a given scope conditionPUT{dmi-root}/dmi/v1/ch/{cm-handle}/data/ds/ncmp-datastore:operational/{resourcepath}?fields={fields}&scope={scope}see example 2 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI
10Read descendant nodes to a given depth for a given cmHandlePUT

{dmi-root}/dmi/v1/ch/{cm-handle}/data/ds/ncmp-datastore:operational/{resource-identifier}?depth={level}


OptionDescription
depthRequest limited sub-tree depth in
the reply content
If '1' then only immediate resource
is retrieved
If '2' then resource plus next level
resources are retrieved
see example 12 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI
11Replace data for a CMHandlePUT

{dmi-root}/dmi/v1/ch/<cm-handle>/data/ds/ncmp-datastore:running/{resource-identifier}

{data : {

            .... the complete tree config to be replaced

      }}

see example 12 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI

DMI Inventory and Sync of Inventory Changes


#Use CaseRest MethodServiceURIExample
1DMI notifies NCMP of new , deleted or changed cmhandles DMI Plugin NCMP. Including initial registration

POST

json attributes:

  • "dmi-plugin" resolvable servicename
  • "createdcmhandles" used for initial cm handle registrations or subsequent
    cmhandle creations
  • "updatedcmhandles"
    Used for updates to cmhandles. Same structure as for create handles
  • "removedcmhandles"  array of cmhandles that have been deleted
    from the network (no additional properties
NCMP

{ncmp-root}/ncmp/v1/ch/

Scenario : DMI notifies NCMP of new cmhandles
Method : POST
URI : {ncmp-root}/ncmp/v1/ch/
Header :
    Content-Type: application/json

Body : {
      "dmi-plugin" : "onap.dmi.plugin", 
      "createdcmhandles" : [ {   "cmhandle" : "rf4er5454",
                                 "additionalProperties" :
                                   { "subsystemId" : "system-001" }
                             }, {..} ],
      "updatedcmhandles" : [ .. ],
      "removedcmhandles" : [ "node-1", "node-2" , ... ]
  }
2Get all the registered cmhandles for a
given plugin		GETNCMP{ncmp-root}/ncmp/v1/dmi-plugins/{plugin-id}/ch
Scenario : Get all cmhandles from NCMP for a given dmi-plugin. May be used
    for conciliation
Method : GET
URI : {ncmp-root}/ncmp/v1/dmi-plugins/{dmi-plugin}/ch
Header :
    Content-Type: application/json

Success Response :
    HTTP/1.1 200 Ok
Date: Thu, 26 Jan 2021 20:56:30 GMT
Server: example-server
  { "cmhandles" : [ {
          "cmhandle" : "node-1",
          "additionalProperties" : [ "subSystem" : "system-001" ]
       } ]
   }
3Get model (schema set) for cmhandleGETDMI-Plugin{ncmp-root}/ncmp/v1/dmi-plugins/{plugin-id}/ch/<cm-handle>/schema-sets/{schema-set-name}Scenario : NCMP requests a list of modules for a cmhandle
Method : PUT
URI : {dmi-root}/dmi/v1/ch/cm-handle-001/schema-sets/cps-ran-schema-model
Header :
Content-Type: application/json


Response:
{
  "name": "cps-ran-schema-model",
  "cmHandle": "cm-handle-001",
  "moduleReferences": [
  {
    "name": "cps-ran-schema-model",
    "namespace": "org:onap:ccsdk:features:sdnr:northbound:cps-ran-schema-model",
    "revision": "2021-01-28"
  },
  {
    "name": "ietf-inet-types",
    "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types",
    "revision": "2013-07-15"
  },
  {
    "name": "ietf-yang-types",
    "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types",
    "revision": "2013-07-15"
  }
  ]
}
4Get yang module for a list of modulesPOSTDMI-Plugin{dmi-root}/dmi/v1/model/ch/<cmhandle>
Body : { [ "org:onap:cps:test:store:2020-12-09??", "org:onap:cps:test:store" ] }

Response : a list yang module sources 

{
  "org:onap:cps:test:store" : [
  {
    "module" : [ {
                       "name" : "books",
                       "module" : [
                       {
                         "name" : "books",
                         "revision" : "2020-12-09",
                         "namespace" : "org:onap:cps:test:bookstore",
                         "module-content" : "paper back",
                         "submodule" : [
                         {
                           "name" : "Fiction",
                           "revision" : "2020-12-17",
                           "namespace" : "org:onap:cps:test:fiction",
                           ]
                    ....
  }

Model API - WIP



Use CaseRest MethodURIExample
1Get model (module set) for cmhandlesPUT

{dmi-root}/dmi/v1/model/ch/<cm-handle>

Scenario: Get the model data for a given cmhandle

Method: PUT

URI : {dmi-root}/dmi/v1/model/ch/cmhandle-001?fields=ietf-yang-library:modules-set

Header :
Content-Type: application/json
Accept: application/json

Body :

{
  "operation" : "read",
  "cmhandle" : "cmhandle-001",
  "additionalProperties" : [
    "target" : "sample-target",
    "subSystem" : "subSystem-001"
  ]
}


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


  • No labels