...
RESTful API Design Specification
Issues and Decisions
# | Issue | Notes | Decision |
---|---|---|---|
1 | How will hostname and port be provided when DMI-Plugin dmiPlugin 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-plugindmiPlugin" : { <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 |
2 | Additional information in request body duplicates cmHandleId this is redundant information | Suggested to remove from request body to avoid possible error scenarios. | Only the one with the additionalInformation is needed and remove body |
3 | No need for Sync method, this is basic | astandard read operation at the root level for that | cm-handle
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>
...
cmHandle | |||
4 | Use include 'location' property when request yang-module sources | Suggestion: do include it in the request but allow dmiPlugin to decide to use it or now. Location (this leaf is called schema in older RFC7895) is not mandatory to support in YANG library and nodes may not include it. Another alternative presumably used also by ODL itself is the <get-schema> RPC. The key difference is that the YANG module definition is sent directly over the NETCONF channel, not requiring separate file servers and clients. So this is maybe one more reason that the ONAP DMI plugin currently doesn’t need the location attribute. | Location is not needed for any plugin and could only lead to ambiguity therefore will NOT be included in this request |
5 | Inconsistent use of "Operation" and/or HTTP Methods to distinguish write operations | Currently this page proposes to use "Operation=update" request body parameter for restconf "Replace" and "Patch" operations and use the HTTP (RESTFul) operation to distinguish between them. It also proposes to use PUT HTTP for Read and Delete operations Basically a very confusing an unintuitive use of HTTP operations to distinguish ambiguous operations that instead easily could be defined by just using the 'operation' field in the request body. | Proposal Toine: For Consistent (restful) design I would suggest to think as the operation to DMI-Plugin (always with body) as "creating a new order to do something" toward DMI-Plugin. Ie always a HTTP POST (or PUT?) operation. The "operation " in the body can simple be extended to include both "update" and "patch" as required. If the 'operation' is NOT supplied "read" wil be assumed as the default operation See also CPS-NCMP - DMI - SDNC Request and Response Mapping Proposal agreed by stakeholders in meeting
|
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>
URI | Mandatory or Optional | Description |
---|---|---|
<OP> | mandatory | the HTTP method |
dmi | mandatory | the dmi root resource |
<v{vNumber}> | mandatory | version of the dmi interface is the target resource URI is the query parameter list |
<cmHandle> | mandatory | unique (string) identifier of a yang tree instance. |
<data|operations|dmiAction> | mandatory | yang data, rpc operation or a (non-modeled) dmi action |
{datastore} | mandatory | mandatory datastore |
<resourcePath> | optional | the 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> | optional | the 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 |
NCPS-NCMP - DMI Plugin Write Request Flow
See CPS-NCMP - DMI - SDNC Request and Response Mapping
Datastore
If the cmhandle metadata indicates that data is not synched in CPS then the request is forwarded to the dmiPlugin
RESTCONF/NETCONF relationship
Excerpt | |||||||
---|---|---|---|---|---|---|---|
Request Format for Data Access
|
Expand | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Below table shows the proposed interface, actual implementation might deviate from this but can be accessed from
|
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
Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
see example 2 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI | 8 | Read data resources with specified fields under a given data resource for a given cmHandle | PUT | {dmi-root}/dmi/v1/ch/<cm-handle> | operational/data/ds/ncmp-datastore: | resource-identifier}?fields={fields-expression}running/{
see example 12 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI | parentDataResourceIdentifier} { Content-Type: application/json "data" payload : yang-data+json 2 | Delete a data resource for a cmHandle | PUT | {dmiRoot | 9 | Get data resource with 'fileds' for a cmhandle with a given scope condition | PUT | {dmi-root}/dmi/v1/ch/{cm-handle}<cmHandle>/data/ds/ncmp-datastore:operationalrunning/{resourcepath}?fields={fields}&scope={scope} | see example 2 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI | 10 | Read descendant nodes to a given depth for a given cmHandle | PUT | resourceIdentifier} | 3 | Patch a data resource for a cmHandle | PATCH | {dmiRoot{dmi-root}/dmi/v1/ch/{cm-handle}<cmHandle>/data/ds/ncmp-datastore:operationalrunning/{resource-identifier}?depth={level}
see example 12 CPS-391Spike: Define and Agree NCMP REST Interface#RESTAPI | 11 | Replace data for a CMHandle | PUT | resourceIdentifier} { Content-Type: application/json "data" payload : yang-data+json 4 | Patch multiple child resources for a single cmHandle | PATCH | {dmiRoot{dmi-root}/dmi/v1/ch/<cm-handle><cmHandle>/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, Model & Data Sync API
|
DMI Inventory, Model & Data Sync API
View file | ||||
---|---|---|---|---|
|
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Below table shows the proposed interface, actual implementation might deviate from this but can be accessed from
*For response output, where applicable the yang-library format and conventions are used 'as is' or extended
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
# | Use Case | Rest Method | Service | URI | Example | 1 | DMI notifies NCMP of new , deleted or changed cmhandles DMI Plugin NCMP. Including initial registration | POST json attributes:
NCMP | | Scenario : DMI notifies NCMP of new cmhandles{ncmp-root}/ncmp/v1/ch/ 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" , ... ] } 2 | Get all the registered cmhandles for a given plugin | GET | NCMP | {ncmp-root}/ncmp/v1/dmi-plugins/{plugin-id}/ch | Scenario : Get all cmhandles from NCMP for a given dmi-plugin. May be usedfor 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" ] } ] } 3 | Get module set for a cmhandle | PUT | DMI-Plugin | {dmi-root}/dmi/v1/ch/cmhandle-001/module-sets | Header : Body :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 | Get yang module for a list of modules | POST | DMI-Plugin | {dmi-root}/dmi/v1/model/ch/<cmhandle> | Body :{ "operation" : "read", "cmhandle" : "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" : [ {
.... } 5 | Sync data to ncmp - NCMP requests sync of cmhandle yang data tree
|
...