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

Compare with Current View Page History

« Previous Version 16 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)


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

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/data/ch/{cm-handle}/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/data/ch/{cm-handle}/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

*TBD Check with similar method on CPS-Core
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 list of modulesPOSTDMI-Plugin{dmi-root}/dmi/v1/model/ch/<cmhandle>
Body : { [ "org:onap:cps:test:store:2020-12-09??", "org:onap:cps:test:bookstore" ] }
response : a list yang module sources

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