Versions Compared

Old Version 1

changes.mady.by.user Niamh Core

Saved on

compared with

New Version 2

changes.mady.by.user Niamh Core

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Jira
serverONAP Jira
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId425b2b0a-557c-3c0c-b515-579789cceedb
keyCPS-390

DMI URI

DMI URI format to follow below pattern 

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




<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
<data|operations|dmi-action>mandatoryyang data, rpc operation or a (non-modelled) ncmp api action
<cmHandle>mandatoryunique (string) identifier of a yang tree instance.
{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

Image Modified


REST API


UsecaseREST MethodURIExample
1Add a data resource

for a cmHandlePOST

dmi-root}/dmi/v1/data/ch/<cm-handle>/{parent-data-resource-identifier}

{

<new-yang-data-resource>

}

Content-Type: application/json

"data" payload : yang-data+json


2Delete a data

resource for a

cmHandlePUT{dmiroot}/dmi/v1/data/ch/<cm-handle>/{resource-identifier}
3Patch a data

resource for a

cmHandlePATCH

{dmi-root}/dmi/v1/data/ch/<cm-handle>/{resource-identifier}

{
<yang-data-for-merging>
}

Content-Type: application/json

"data" payload : yang-data+json


4
dmi-CM-001-8
Patch multiple child

resources for a

single cmHandlePATCH

{dmi-root}/dmi/v1/data/ch/<cm-handle>/{resource-identifier}


Content-Type: application/json

"data" payload : yang-patch+json


5Execute a yang

action on a

cmhandle instancePOST

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


6Execute an rpc

operationPOST

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

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

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


7Read a filtered set

of data under

a data resource for

a cmHandlePUT

dmiroot}/dmi/v1/data/ch/<cm-handle>/{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/data/ch/<cm-handle>/{resource-identifier}?fields={fields-expression}


OptionDescription
fieldsRequest a subset of the target
resource contents



9Get data resource with 'fileds' for a cmhandle with a given scope conditionPUT{dmi-root}/dmi/v1/data/ch/{cm-handle}/{resourcepath}?fields={fields}&scope={scope}
10Read descendant nodes to a given depth for a given cmHandlePUT

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



11Replace data for a CMHandlePUT

{dmi-root}/dmi/v1/data/ch/<cm-handle>/{resource-identifier}

{

   data : {

            .... the complete tree config to be replaced

           }

}



DMI Inventory



Use CaseRest MethodURIExample
1DMI registers a new data source with NCMP POST

{ncmp-root}/ncmp/v1/dmi-plugin/
{
    "dmi-plugin-id : { dmi-plugin-id }
     "dmi-source-id" : { unique-data-source-id }
}


dmi-plugin-id should be resolvable service name ink8s DNS


2Delete a data source from NCMP DMI Plugin NCMPDELETE{ncmp-root}/ncmp/v1/dmi-pluigin/ { dmi-plugin-id}/dmi-source/ { unique-data-source-id }
3NCMP requests cmhandles for a datasource (may be refresh of existing
datasource or for a newly registered datasource) NCMP DMI plugin		GET

{dmi-root}/v1/dmi-source/{unique-data-source-id}?topic={topic-id}


Content-Type: application/json

Note - the following will refresh ALL dmi data sources managed by a dmi plugin
{dmi-root}/v1/dmi-source?topic={topic-id}


4Notify of change to CMHandle(s)
Topic : 'NCMP_INVENTORY' / sync request topic
Topic name should come from Data Catalog OR should DMI registry store the topic from the initialNCMP sync request?)

Model API


14

Use CaseRest MethodURIExample
1Get model (module
set) for cmhandles		PUT

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

1213


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

...