- Get the latest study information from Kieran Mccarthy <kieran.a.mccarthy@ericsson.com>
- Create a Wiki page with a clear diagram showing NCM and DMI and its interfaces detailing the scope of THIS (and other) spike
- Update V1 of the interface (communicate with E2E Slicing)
- Detail CRUD operations
- Detail Patch
- Include datastore options (pass-through)
- Agree on parameter names and use them consistently
- Agree on JSON output format
- Resource 'path' can cover cps-paths, rest-conf path (for pass-through), and any proprietary paths
- Only 'hint' at
- async options
- bulk operations
A/C
- Wiki page detailing points above
- Share an agreement with the team
- Present at community
Out of scope
- actual YAML definitions (separate user story)
- CPS-391Getting issue details... STATUS
Open Issues & Decisions
Description | Notes | Decision | |
---|---|---|---|
1 | Priority of async calls | In Istanbul, async calls are required only in pass-through cases. NCMP does not have to handle these requests | |
2 | Will we use the data node wrapper on GET rest operations? | Currently, we wrap the response of GET operations using the data node wrapper. | |
3 | In the URI will we distinguish between data and operations (RFC calls) as part of the path? | e.g. http://localhost:8080/cps/api/v1/data http://localhost:8080/cps/api/v1/operation | |
4 | Parent data resource identifier can handle any path using the same query parameter
| ||
5 | Yml should include return types and examples of the payload | ||
6 | camel case or dash in URI | we will use a dash for param names e.g. cm-handle | |
7 | Insert /resource-path in front of the resource path to prevent ambiguous paths | <OP>/ncmp /<v{v-number}>/cmhandle/<cm-handle>/<data|operations|{ncmp-action}>/ds/{datastore}/resource-path/<resource-path>?<query> | |
8 | Granularity of update scenarios (and priority) |
| |
9 | There is no automatic fallback to passthrough | The client will have the specify the default | |
10 | fields is a rest conf option, investigate is it fully supported by onap |
RESTCONF/NETCONF relationship
NCMP URI
NCMP URI format to follow below pattern
<OP>/ncmp /<v{v-number}>/cmhandles/<cm-handles>/<data|operations|{ncmp-operation}>/ds/{datastore}/{resource-path}?{query}
URI | Mandatory or Optional | |
---|---|---|
<OP> | the HTTP method | Mandatory |
ncmp / | the ncmp root resource | Mandatory |
<v{v-number}> | version of the ncmp interface <path> is the target resource URI <query> is the query parameter list | Mandatory |
cmhandles/<cm-handles> | unique (string) identifier of a yang tree instance. | Optional |
<data|operations|{ncmp-action}> | request category - yang data, rpc operation or a (non-modelled) ncmp api action. this could be data, operations or ncmp-action | Mandatory |
ds/{datastore} | optional datastore | Optional |
<resource-path> | 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. | Optional |
<query> | 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 | Optional |
Datastores
New datastores are defined for ncmp to access the CPS 'intended' or 'operational' datastore.
Alternatively, the request can be sent directly to the 'device' itself (bypassing CPS datastores) using one of the 'passthrough-*' datastores options as below
The new ncmp datastores required for ONAP Release I include :
1 | ncmp-datastores:running (RW / config=true/false) | Read/Write to the CPS "intended" store (with validation). |
2 | ncmp-datastores:operational (RO / config=true/false) | Read from the CPS "operational" store. |
3 | ncmp-datastores:passthrough-running (RW / config=true/false) | Read/Write to/from the live devices ietf-datastores:running (no local ncmp validation) |
Future datastores to be supported by NCMP include :
1 | ncmp-datastores:passthrough-intented (RO) | Read from the live devices ietf-datastores:intended |
2 | ncmp-datastores:passthrough-operational (RO) | Read from the live devices ietf-datastores:operational |
If datastore (ds/{datastore}) is omitted from URI, the datastore from cmhandle is used
If datastore (ds/{datastore}) is omitted from URI AND the model/moduleSet exists, the datastore defaults to ncmp-datastores:running
Yang data resource actions and RPC operations are run directly on the 'device' meaning ncmp-datastores:passthrough-running is used for these request
Different defaults for read and write
e.g. ncmp-datastores:operational for read requests
# | Usecase | NCMP Datastore | Path | ?fields | ?topic | Query | Time frame |
---|---|---|---|---|---|---|---|
1 | Read | passthrough-running | RESTConf Path only | Implemented by SDNC/Node | Implemented by DMI Plugin | Not supported | Istanbul |
2 | Read | ncmp-datastores:operational | CPSPath only | TBD | TBD | Limited xpath functionality | Istanbul |
3 | Create | passthrough-running | RESTConf Path only | N/A | N/A | N/A | Istanbul |
4 | Create | ncmp-datastores:running | CPSPath only | N/A | N/A | N/A | > Istanbul |
5 | Delete | passthrough-running | RESTConf Path only | N/A | N/A | Not supported | Istanbul |
6 | Delete | ncmp-datastores:running | CPSPath only | N/A | N/A | Not supported | > Istanbul |
7 | Update | passthrough-running | RESTConf Path only | N/A | N/A | N/A | Istanbul |
8 | Update | ncmp-datastores:running | CPSPath only | N/A | N/A | N/A | > Istanbul |
9 | Patches | passthrough-running | RESTConf Path only | N/A | N/A | N/A | Istanbul |
10 | Patches | ncmp-datastores:running | CPSPath only | N/A | N/A | N/A | > Istanbul |
11 | Bulk | passthrough-running | RESTConf Path only | N/A | N/A | N/A | > Istanbul |
12 | Bulk | ncmp-datastores:running | CPSPath only | N/A | N/A | N/A | > Istanbul |
13 | Action | passthrough-running | RESTConf Path only | N/A | N/A | N/A | Istanbul? |
14 | Action | ncmp-datastores:running | CPSPath only | N/A | N/A | N/A | Istanbul? |
REST API
Req/usecase | REST Method | URI / Payload | Header Parameters | Request/Response Example | Status | |||||
---|---|---|---|---|---|---|---|---|---|---|
1 | Read a data resource directly from source (passthrough) for a cmHandle - async | GET | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds
| Accept: application/json | Scenario : Read the GNBCUCPFunction for cmhandle "335ff" as passthrough Method : GET URI : {ncmp-root}/ncmp/v1/cm-handle/335ff/ds/ncmp-datastores: Header : Event Response: { [ } | |||||
2 | Read a data resource directly from source (passthrough) for a cmHandle. Only return specific field(s). Synchronous call | GET | {ncmp-root}/ncmp/v1/cm-handle//ds /ncmp-datastores:passthrough-running/{dataresource-identifier}?fields={fields} | Accept: application/json | Scenario : Read the EUtranCellFDD.(administrativeState, Method : GET URI : {ncmp-root}/ncmp/v1/cm-handle/335ff/ds/ncmp-datastores: Header : Response: HTTP/1.1 200 OK { [ | |||||
3 | ALTERNATIVE OUTPUT TO ABOVE Read a data resource directly from Synchronous call | GET | {ncmp-root}/ncmp/v1/cm-handle//ds /ncmp-datastores:passthrough-running/{dataresource-identifier}?fields={fields} | Accept: application/json | Scenario : Read the EUtranCellFDD.(administrativeState, Method : GET URI : {ncmp-root}/ncmp/v1/cm-handle/335ff/ds/ncmp-datastores: Header : Response: HTTP/1.1 200 OK { [ OR "/ManagedElement[@id="Kista-001"]/ENodeBFunction[@id="1"] OR "xpath": "/ManagedElement[@id="Kista-001"]/ENodeBFunction | Under Review Talk to Niamh and Toine on the different options | ||||
4 | Read a data resource with some leaf value condition directly from source (passthrough) for a cmHandle. Only Synchronous call | GET | {ncmp-root}/ncmp/v1/cm-handle//ds /ncmp-datastores:passthrough-running/{dataresource-identifier[]}?fields={fields} &topic={topicId} | ContentType: application /json | Scenario : Read the LocalSctpEndpoint.(interfaceUsed==X2, Method : GET URI : {ncmp-root}/ncmp/v1/cm-handle/335ff/ds/ncmp-datastores: Header : Response: HTTP/1.1 200 OK { [ } | Under Review | ||||
5 | Create a data resource for a cmhandle | POST | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds { OR with datastores defaults {ncmp-root}/ncmp/v1/cm-handle/<cmhande>/ { | ContentType: application /json | Scenario : Create ericsson-nrsectorcarrier-vdu-add:NRSectorCarrier=4 Method : POST URI : : {ncmp-root}/ncmp/v1/cm-handle/34l5k32/ManagedElement Header : Body : { | |||||
6 | Update a data resource for a cmhandle | PATCH | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds { OR with datastores defaults {ncmp-root}/ncmp/v1/cm-handle/<cmhande>/ { | ContentType: application /json | Scenario : Update ericsson-nrsectorcarrier-vdu-add:NRSectorCarrier=4 Method : PATCH URI : {ncmp-root}/ncmp/v1/cm-handle/34l5k32/ManagedElement Header : Body : { | |||||
7 | Delete a data resource for a cmhandle | DELETE | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds OR with datastores defaults {ncmp-root}/ncmp/v1/cm-handle/<cmhande>/ | ContentType: application /json | Scenario : Create ericsson-nrsectorcarrier-vdu-add:NRSectorCarrier=4 under _3gpp-common-managed-element:ManagedElement=Kista-001 /_3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1 Method : DELETE URI : {ncmp-root}/ncmp/v1/cm-handle/34l5k32/ManagedElement [@id=Kista-001]/GNBDUFunction[@id=1]/NRSectorCarrier[@id=4] OR {ncmp-root}/ncmp/v1/cm-handle/34l5k32//NRSectorCarrier[@id=4] Header : Accept: application/json Body : {} | |||||
8 | Get model (module set) for CMHandle | GET | {ncmp-root}/ncmp/v1/model/<handleId> | Accept: application/ yang- data+json | Scenario : Get the model data for CMHandle with id "335ff" Method : GET URI : {ncmp-root}/ncmp/v1/model/335ff Header : Response: { "ietf-yang-library:modules-state" : { | |||||
9 | Create a data resource for a cmhandle | POST | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds { OR with datastores defaults {ncmp-root}/ncmp/v1/cm-handle/<cmhande>/ { | Content- Type: application /yang- data+json | Scenario : Create ericsson-nrsectorcarrier-vdu-add:NRSectorCarrier=4 Method : POST URI : {ncmp-root}/ncmp/v1/cm-handle/34l5k32/_3gpp-commonmanaged-element:ManagedElement=Kista-001/_3gpp-nr-nrmgnbdufunction:GNBDUFunction=1 Header : Body : { | |||||
10 | Delete a data resource for a cmHandle | DELETE | {ncmp-root}/ncmp/v1/<handleId>/ds/ncmp- OR with datastores defaults {ncmp-root}/ncmp/v1/cm-handle/<cmhande>/ | Content-Type: application/yang- data+json | Scenario : Delete NRSectorCarrier=4 Method : DELETE URI : {adapter-root}/ncmp/v1/cm-handle/34l5k32/_3gpp-commonmanaged-element:ManagedElement=Kista-001/_3gpp-nr-nrmgnbdufunction:GNBDUFunction=1/_3gpp-nr-nrm-nrsectorcarrier: | |||||
11 | Update a data resource for a cmHandle | PATCH | {ncmp-root}/ncmp/v1/data/<handleId>/ds/ncmp- OR with datastores defaults {ncmp-root}/ncmp/v1/cmhandle/<cmhandle>/ | Content-Type: application/yang- data+json | Scenario : Add NRSectorCarrier=4 to GNBDUFunction=1 if it doesn't Method : PATCH URI : {ncmp-root}/ncmp/v1/cm-handle/d32455f/_3gpp-commonmanaged-element:ManagedElement=Kista-001/_3gpp-nr-nrmgnbdufunction:GNBDUFunction=1 Header Body { _3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1 : { | |||||
12 | Multiple edits under a target data | PATCH | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds OR using datastores defaults {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ | Content-Type: application/yang- patch+json | Scenario : Make multiple updates under the GNBDUFunction=1 data Method : PATCH URI : {ncmp-root}/ncmp/v1/cm-handle/32rf234/_3gpp-common- Header : Body : { "ietf-restconf:yang-patch" : { Response : HTTP/1.1 200 OK { | |||||
13 | Execute a yang action | POST | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds Note : If the "action" statement OR using datastores defaults {ncmp-root}/ncmp/v1/cm-handle { "param1Name" : } | Content-Type: application/yang- data+json | Method : POST URI : {ncmp-root}/ncmp/v1/cm-handle/3445fff/_3gpp-common- Header : Body : | |||||
14 | Execute an rpc operation | POST | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle> { Note : If there is no "input" OR using datastores defaults {ncmp-root}/ncmp/v1/cm-handle/<cmhandle> { | Content-Type: application/yang- data+json | Method : POST URI : {ncmp-root}/ncmp/v1/cm-handle/3445fff/operations/_3gpp- Header : Body : | |||||
15 | Read a filtered set of data under a data | GET | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds options
OR using datastores defaults {ncmp-root}/ncmp/v1/cm-handle/<cmhandle> | Accept: application /yang-data +json | Scenario : Read GNBDUFunction=1.userLabel and NRSectorCarrier with Method : GET URI : {ncmp-root}/ncmp/v1/cm-handle/3fsdfr3/_3gpp-common- {ncmp-root}/ncmp/v1/cm-handle/3fsdfr3/ManagedElement=Kista-001 Header : Body: Response : HTTP/1.1 200 OK _3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1 { "userLabel" : "myGnodeBFunction-1", _3gpp-nr-nrm-nrsectorcarrier:NRSectorCarrier=1 { _3gpp-nr-nrm-nrsectorcarrier:NRSectorCarrier=3{ _3gpp-nr-nrm-nrsectorcarrier:NRSectorCarrier=4 { } } | |||||
16 | Read descendant data resources with | GET | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds options
OR using datastores defaults {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ | Accept: application /yang-data+ json | Scenario : Read all NRCellDU MOs with attributes userLabel and id under Method : GET URI : {ncmp-root}/ncmp/v1/cmhandle/3445fff/_3gpp-common- Header : Response : HTTP/1.1 200 OK { _3gpp-nr-nrm-nrcelldu:NRCellDU=1 { _3gpp-nr-nrm-nrcelldu:NRCellDU=4 { _3gpp-nr-nrm-nrcelldu:NRCellDU=5 { | |||||
17 | Read data resources to a given depth | POST | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds
OR using datastores defaults {ncmp-root}/ncmp/v1/data/<cmhandle>/{data- | Accept: application /yang- data+json | Method : POST URI : {ncmp-root}/ncmp/v1/cm-handle/3445fff/_3gpp-common- Header : Body: Response : HTTP/1.1 200 OK _3gpp-nr-nrm-nrsectorcarrier: _3gpp-nr-nrm-nrsectorcarrier:NRSectorCarrier=3{ _3gpp-nr-nrm-nrsectorcarrier:NRSectorCarrier=4 { _3gpp-nr-nrm-nrcelldu:NRCellDU=1 { _3gpp-nr-nrm-nrcelldu:NRCellDU=4 { _3gpp-nr-nrm-nrcelldu:NRCellDU=5 { | |||||
18 | Create or replace the target data | PUT | {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds/ OR using datastores defaults {ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ | Accept: application /yang-data+ json | Method : PUT URI : {ncmp-root}/v1/cm-handle/3445fff/_3gpp-common-managed- Header : Body : | |||||
19 | Get data for list of CMHandles | PUT | {ncmp-root}/ncmp/v1/ds/{datastore}/{data- OR using datastores defaults {ncmp-root}/ncmp/v1/{data-resource-identifier} | Accept: (yangData | Scenario Get the NRCellDU=Cell-001 data for multiple cmhandles Method : PUT URI : {ncmp-root}/ncmp/v1/ds/ncmp-datastores:passthrough-running? Header : Body : Response : HTTP/1.1 200 OK "response" : [ "top3gpp:id" : "NR-Cell-001" }, _3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1 { "_3gpp-nr-nrm-nrcelldu:NRCellDU=NR- "top3gpp:id" : "NR-Cell-001" } } }, _3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1 { "_3gpp-nr-nrm-nrcelldu:NRCellDU=NR-Cell- } { "ietf-restconf:errors" : { } } ] | |||||
20 | Read resource data (with 'fields') for list | POST | {ncmp-root}/ncmp/v1/ds/{datastore}/{data- OR {ncmp-root}/ncmp/v1/{data-resource-identifier} | Accept: (yangData | Scenario Get the and select attributes GNBDUFunction.id of NRSectorCarrier and NRCellDUs Method : POST URI : {ncmp-root}/ncmp/v1//NRSectorCarrier?fields=top3gpp:id;_3gpp- Header : Body: { Response : HTTP/1.1 200 OK "response" : [ " : " cmHandle 1231", "yangData" : { "_3gpp-nr-nrm-nrsectorcarrier: "_3gpp-nr-nrm-nrsectorcarrier: "_3gpp-nr-nrm-nrsectorcarrier: "_3gpp-nr-nrm-nrcelldu:NRCellDU=1" : { "_3gpp-nr-nrm-nrcelldu:NRCellDU=4" : { "_3gpp-nr-nrm-nrcelldu:NRCellDU=5" : { } } }, { " : " cmHandle 1232", "data" : { "_3gpp-nr-nrm-nrsectorcarrier: "_3gpp-nr-nrm-nrsectorcarrier: } }, { "_3gpp-nr-nrm-nrsectorcarrier: "_3gpp-nr-nrm-nrcelldu:NRCellDU=1" : { } }, { " : " cmHandle 1234", "yangData" : { _3gpp-nr-nrm-gnbdufunction: "_3gpp-nr-nrm-nrcelldu:NRCellDU=1 { } } ] } | |||||
21 | Execute a yang action on multiple | POST | {ncmp-root}/ncmp/v1/data/{data-resource- input: { Note : If the "action" statement has no | Content-Type: (yangData | Method : POST URI : {ncmp-root}/ncmp/v1/data/_3gpp-common-managed-element: Header : Body : "yangData" : { Response Success HTTP/1.1 202 Accepted //EMPTY BODY Error Response : HTTP/1.1 202 Accepted response : [ { 1232", "yangData" : { ietf.org/html/rfc6241#section-4.3 "error-type" : "protocol", 1234", "yangData" : { "error" : [ | |||||
22 | Execute an rpc operation on multiple | POST | {ncmp-root}/ncmp/v1/operations/{module-name}: { Note : If there is no "input" | Content-Type: application/json | Method : POST URI :{ncmp-root}/ncmp/v1/operations/_3gpp-common-managedelement:ManagedElement=Kista-001/_3gpp-nr-nrm-gnbdufunction: Header : Body : operation : "action", | |||||
23 | GET/ POST/ PATCH /PUT/ DELETE | {ncmp-root}/ncmp/v1/cm-handle/ /data/ds/ncmp-datastores:passthrough-running/ {xpath}?topic=<dmaap-topic-Identifier> {ncmp-root}/ncmp/v1/cm-handle/ /data/ds/ncmp-datastores:running/{xpath}?topic=<dmaap-topic-Identifier> **Async communication channel is DMaaP Immediate response with a requestId is sent to the caller and the CRUD request is executed asynchronously where data is returned via the provided topic identifier. | Accept : application/json | Scenario : Async request to NCMP Method : GET/POST/PATCH/PUT/DELETE URI : {ncmp-root}/ncmp/v1/cm-handle/de3455/data/ds/ncmp-datastores: Body : // Include body where required Response : response data is published on the topic identified by <topicIdentifier> |
Output Specification
?fields={fields}&topic= {topicId}
Assynchronous
?fields={fields}&topic= {topicId}
Required Task
# | Description | Notes | Decision |
---|---|---|---|
1 | Yml update with return types with examples of the payload | ||
2 | Update CPS openAPI.yml with return types |
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