Versions Compared

Old Version 25

changes.mady.by.user Niamh Core

Saved on

compared with

New Version 26

changes.mady.by.user Toine Siebelink

Saved on

Key

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

Table of Contents

References

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

RESTful API Design Specification

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"
2Additional information in request body duplicates cmHandleId this is redundant informationSuggested to remove from request body to avoid possible error scenarios.
3No need for Sync method, this is basic a standard read operation at root level for that cm-handle

DMI URI

DMI URI format to follow below pattern Sandeep Shah

...

Expand
titleDMI Inventory and Sync of Inventory Changes

DMI Inventory

and Sync of Inventory Changes

, Model & Data Sync


#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

Request 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 pluginGETNCMP{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 module set for a cmhandlePUTDMI-Plugin{dmi-root}/dmi/v1/ch/cmhandle-001/modelmodule-sets

Header :
Content-Type: application/json


Body :
  { "operation" : "read",
    "cmhandle"  :  "cmhandle-001",
    "additionalProperties"  : [
      "target" :  "Subnetwork=Stockholm,MeContext=Kista,ManagedElement=Kista-001",
      "subSystem" : "subsystem-001"]}

Response:
  {
    "ietf-yang-library:yang-library" : [ 
    { "module-set" : [ {
                         "name" : "sample-module",
                         "module" : [
                         {
                           "name" : "_3gpp-nr-nrm-nrsectorcarrier",
                           "revision" : "2020-12-09",
                           "namespace" : "urn:3gpp:sa5:_3gpp-nr-nrm-nrnetwork-nrsectorcarrier",
                          } 
            ...
    }
4

Sync data to ncmp - NCMP requests sync of cmhandle yang data tree

Get yang module for a list of modulesPOSTPUTDMI-Plugin{dmi-root}/dmi/v1/model/ch/<cmhandle>
Body :
{ "operation" : "read",
"cmhandle
-001/operations/ds/ncmp-datastore:operational/sync

NOTE the response needs to be considered 0 this could be quite a large tree and it would be better to return the data in an async manner rather than ALL in a single response body.

Header :
Content-Type: application/json
Body : { "additionalProperties" :
{ "subsystemId" : "subsystem-001"
 "targetId" : "Subnetwork=Stockholm,MeContext=Kista,ManagedElement=1"} }
Response :
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data-json
{
_3gpp-common-managed-element:ManagedElement [
{
"_3gpp-common-top:id" : "1",
...
_3gpp-nr-nrm-gnbdufunction:GNBDUFunction : [
{
"_3gpp-common-top:id" : "1",
nrsectcarr3gpp:NRSectorCarrier" : [
{
"_3gpp-common-top:id" : "NRSectorCarrier-1",
....
}		5Get yang module for a list of modulesPOSTDMI-Plugin{dmi-root}/dmi/v1/model/ch/<cmhandle>
Body : {" : "cmhandle-001",
"additionalProperties" : ["subSystem" : "subsystem-001"]
"modules" :  [ "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",
                           ]
                    ....
  }
5

Sync data to ncmp - NCMP requests sync of cmhandle yang data tree



Not separate URI required, this is equivalent to a read request at root level see #7 in previous table. See open issue #3



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.

...


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

...