Table of Contents

Jira Legacy

server	System Jira
columns	key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId	4733707d-2057-3a0f-ae5e-4fd8aff50176
key	CPS-391

Guiding Principles

NCMP REST Interface will follow/be inspired by RESTConf interface for easy acceptance of and transition to this interface
Will follow ONAP's RESTful API Design Specification
The interface will include the concept of data-stores inspired by Network Management Datastore Architecture (NMDA) and as used in RESTConf
The application should be able to easily switch between 'pass-through' and other datastores (also identical rest endpoint and responses)

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

Requirements

Note
Please note this section was added long after the implementation and focuses on characteristic only.

Characteristics - WIP

It is proposed that reported characteristics will be used as a baseline for NCMP when agreed and sign-off.

...

Expected duration

...

100 ms to get module references
1000 ms to get module resources

...

N/A

...

N/A

...

N/A

...

5

...

10

...

N/A

...

TDB e.g. 5 KB

...

25 op/sec

...

10

...

N/A

...

within 1 sec

...

10

...

N/A

...

13 ops/sec

...

10

...

Within 2 sec

Note

This is for mixed TCs
Single KPIs will be monitored in NCMP owned pipeline with our performance every day(2 hrs interval) - Performance
New BATCH KPI - TBD
Organise a call to walk through the code and TCs with //. Want to see the code of the Test Cases. Csaba Szabó to walkthrough TCs with CPS team
Check Registration & de-reg agree with //

Open Questions

Concurrent which number are we agreeing to test, 10 parallel op. according to the input load, the average response time as mentioned in comment is 20 parallel op
DMI delay - We need feed back from ETH on this
Better to have R, W use cases separated as in the FS for both throughput and response time or should we merge this on NCMP
Check Registration - Kolawole Adebisi-Adeolokun Refer to Michelle's email
Check DE-Registration if this was ever agreed

Ongoing Discussion

Share Test cases per KPI with CPS. AP @Csaba Szabó X to walkthrough TCs with Toine & Daniel(CPS)

Functional Specification document.

Confluence: Configuration Handling Functional Specification.

i. Current content shows mixed testcases, all TCs happening in parallel. AP @Csaba Kocsis Clarify what is being run in parallel and update table accordingly. - Waiting for feedback

ii. AP @Csaba Kocsis update UseCase_0005_IdSearch_NoFilter & UseCase_0008_Search_NoFilter to merge the Input Load column to show total of 5 parallel requests. - Waiting for feedback

iii. AP @Csaba Kocsis Notify Product Engineering (Dagda) about the change. - Waiting for feedback

AP , @Csaba Kocsis , @Toine Siebelink, @Kolawole Adeolokun: Review the FS and identify if additional information is required. ONGOING

...

Question about FS and Stability test strategy – what is expected to be supported in parallel or what is expected to be tested in series? How is that decided? AP Michelle & @Csaba Kocsis - Waiting for feedback

...

Table of Contents

Jira Legacy

server	System Jira
columns	key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId	4733707d-2057-3a0f-ae5e-4fd8aff50176
key	CPS-391

Guiding Principles

NCMP REST Interface will follow/be inspired by RESTConf interface for easy acceptance of and transition to this interface
Will follow ONAP's RESTful API Design Specification
The interface will include the concept of data-stores inspired by Network Management Datastore Architecture (NMDA) and as used in RESTConf
The application should be able to easily switch between 'pass-through' and other datastores (also identical rest endpoint and responses)

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

Requirements

Note
Please note this section was added long after the implementation and focuses on characteristic only.

Issues & Decisions

	Issues	Notes
1	De-registration of 100 CM-handles	This was mentioned. Was this ever agreed, is this a valid use case that needs to be covered together the Registration
2	DMI delay	Could we get some feedback on DMI-delays for other use cases as not mentioned in FS document
3	New BATCH KPI	TBD

Characteristics - WIP

It is proposed that reported characteristics will be used as a baseline for NCMP when agreed and sign-off.

	Operation	Total CM-handles registered	Concurrent requests/parallel	DMI Delay	Rest response size	Performance	Observed Rate (rate not measured)	Expected duration	Sign-Off
1	Registration of 100 CM-handles	20k Nodes	1 (requests are sequential)	100 ms to get module references 1000 ms to get module resources	N/A		1.6 ops/second	TBD	TDB
2	De-registration of 100 CM-handles	20k Nodes	1 (requests are sequential)	N/A	N/A
3	CM-handle ID search without filter	20k Nodes	5	N/A	TBD e.g. 1MB	Within 2 sec	7.1 ops/minute	42 seconds / operation	TDB
4	CM-handle search without filter	20k Nodes	5	N/A	TBD e.g. 10MB	Within 15 sec	5 ops/minute	1 minute / operation	TDB
5	Synchronous single CM-handle pass-through read	20k Nodes	10	N/A	TDB e.g. 5 KB	25 op/sec	50 ops/second	TBD	TDB
6	Synchronous single CM-handle response time read	20k Nodes	10	N/A		within 1 sec
7	Synchronous single CM-handle pass-through write (CUD)	20k Nodes	10	N/A	N/A	13 ops/sec	13 ops/second	TBD	TDB
8	Synchronous single CM-handle response time write (CUD)	20k Nodes	10	N/A		Within 2 sec

Notes

This is for mixed TCs
Single KPIs will be monitored in NCMP owned pipeline with our performance every day(2 hrs interval) - Performance

Synchronous single cm-handle pass-through (read) requests

...

Expand

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.

we should mainly support yang-data/json

controlled by "accept-header"

3

In the URI will we distinguish between data and operations (RFC calls) as part of the path?

e.g. http://localhost:8080/ncmp/v1/data

http://localhost:8080/ncmp/v1/operation

This only applies to pass-through

yes, we will distinguish between data and operation

4

Which query parameters will NCMP support?

Parent data resource identifier can handle any path using the same query parameter

cpsPath
RESTConf Path (pass-through)
Proprietary Path (pass-through)

5

Yml should include return types and examples of the payload

Legacy and new API documentation needs to include output examples.

Task created, see

Jira Legacy

server	System Jira
serverId	4733707d-2057-3a0f-ae5e-4fd8aff50176
key	CPS-401

6

camel case or dash in URI

We will use a dash for param names e.g. cmHandle (although it has since been agreed we use 'ch' in this particular case)

See no.3 https://restfulapi.net/resource-naming/

7

Insert /resourcePath in front of the resource path to prevent ambiguous paths

<OP>/ncmp/<v{vNumber}>/ch/<cmHandle>/<data|operations|{ncmp-operation}>/ds/{datastore}/[rp:]{resourcePath}?{query}

Optionally insert the resource path ('rp:') if it clashes with the current

8

Granularity of update scenarios (and priority)

Add child and its descendants (supported in cps core)
Add all list elements (supported in cps core)
Replace child and its descendants (supported in cps core)
Replace all list elements (pending in cps core)
Update single leaf (new)
Add list entry (new)

Priority is pass-through only so it depends on the RETSConf protocol that is supported.

In Jakarta or if required by other projects more fine-grained 'operation' datastore update options can be implemented

9

Fallback option for datastore in release I

No, explicit datastore options will be used in Istanbul

10

fields is a rest conf option, investigate is it fully supported by onap

Supported in pass-through for ONAP DMI plugin but depending on the support by the actual target. The intention is to increase support 'fields' in future requirements following RFC-8040 for operational datastore etc.

11

Agree on URI syntax

Proposed syntax by CPS team

<OP>/ncmp/<v{vNumber}>/ch/<cmHandle>/<data|operations|{ncmp-operation}>/ds/{datastore}/[rp:]{resourcePath}?{query}

review completed and proposed URI agreed

12

Will we combine query capabilities with update capabilities?

We have decided not to combine query capabilities with update capabilities

13

Description of header limitations

HTTP Header Limitations
Some servers put size limitations on HTTP headers, making them unsuitable for storing cmHandle information.

LIMITATION NOTE: server implementations put size limits on the headers meaning header contents should be designed carefully :
Apache - 8K
Nginx - 4K-8K
IIS - 8K-16K
Tomcat - 8K – 48K

14

Will NCMP support paths for pass-through:running

The plugin will not do transformation or validation of paths in the case of pass-through:running

15

Specification of path per cm handle

DMI Plugin can take cps paths or restconf paths and it needs to specify that per cm handle when cm handle is created

16

What is the default path for NCMP

In NCMP default will always be cps path and depending on the adapter we can change it as needed per cm handle

17

Fields parameter for ncmp/operational?

The fields parameter is ignored in ncmp/operational (in Istanbul release)

18

Is specifying the datastore mandatory?

Datastore is mandatory in Istanbul release

19

Register a DMI plugin with NCMP

DMI plugin is a part of cm handle registration. The rest endpoint on NCMP can be multiple calls

20

Retrieve list of modules (names) for a cmHandle

Retrieve a list of module names for cm handle - this will be used by ncmp to get the models. - assuming ncmp model discovery is complete and it is stored in cps core, this will come from cached information

21

Where will sync be implemented?

Implement sync in the dmi plugin and then have ncmp be able to pass on the request. This is not a bulk operation

22

Config-true only support (filter out config-false data)

Use datastore 'running' to select this but filtering not supported in I for cached data

23

Enable NCMP to convert cpsPath to mutliple options(RESTConf, netConf, leave as cpsPath)

When other DMI-Plugins are realized they might need a different conversion then the default from cspPath to RESTConf. This could be configured by using a known property for each cmHandle 

Not required in Istanbul. But DB model can easily be updated to cater for this when needed

24

Datastore conversion in NCMP or DMI-Plugin

DMI-Plugin will know best how to convert. This will also reduce future impacts on NCMP for new options.

NCMP will do now conversion of datastore names

25

What datastore/s (name/s) is/are supported by NCMP to referred to the cached data. 'Operational' or 'running'

'operational' would imply RO and config=false data is included. 'To also support 'running' using the same data a filter would have to be applied

see supported datastore in I : Datastores

26

Consider fallback option when user specifies ncmp/operational but data is NOT synced

NCMP will forward requests for un-synced cmHandles to the DMI Plugin
(Including required transformation of resource path etc.)

27

Support for &fields parameter when using cached data

not supported (ignored, not rejects, nice for future compatibility)
treat as 'no descendants'  (low cost)
use to filter cached data

&Fields parameter will be ignored for 'cached' data in Istanbul timeframe

long term expectation is to have support following RESTConf/ODL behavior as much as possible

28

Support for &fields parameter when forwarding to plugin for non-synced cmHandles

not supported (ignored, not rejects, nice for future compatibility)
treat as 'no descendants'  (low cost)
translate (insert module names) and forward

A spike

Jira Legacy

server	System Jira
serverId	4733707d-2057-3a0f-ae5e-4fd8aff50176
key	CPS-455

will be executed to determine the feasibility of option 3 and decide if it can make Istanbul scope

29

Response for Data Sync request (in Istanbul timeframe)

The action is blocking synchronous through whole stack (in I) so response could include the data returned by the node. However this seem incorrect for an 'action' so maybe the response should just be just an acknowledgment it is 'done'

No need to return data, just HTTP Code 200 (OK) will suffice

...

Expand

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/en/latest/design.html#offered-apis

#

Req/usecase

REST

Method

URI

Request/Response Example

1

DMI notifies NCMP of new , deleted or changed cmhandles DMI Plugin NCMP. Including initial registration

POST

{ncmpRoot}/ncmp/v1/ch/

Scenario : DMI notifies NCMP of new cmhandles
Method : POST
URI : {ncmpRoot}/ncmp/v1/ch/
Header :
    Content-Type: application/json

Code Block

language	xml
title	Request Body

Request Body : {
      "dmiPlugin" : "onap.dmi.plugin", 
      "createdCmHandles" : [ {   "cmHandle" : "rf4er5454",
                                 "cmHandleProperties" :
                                   { "subSystemId" : "system-001" }
                             }, {..} ],
      "updatedCmHandles" : [ .. ],
      "removedCmHandles" : [ "node-1", "node-2" , ... ]
  }

json attributes:

"dmiPlugin" 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

2

Get all cm handles that support all modules in a given list of modules

POST

{ncmpRoot}/ncmp/v1/ch/searches

URI : {ncmpRoot}/ncmp/v1/ch/searches

The minimal requirement is if we provide the AND query impl then for OR query the client can send multiple requests

Request Body

Content: application/json

Note: revision should be optional

{
  "modules": [
    {
      "moduleName": "", (Mandatory)
      "revision": "" (Optional)
    }
  ]
}

Header :
Accept: application/json
Response:

Should return an array of objects as we may add more data in the future
{
"cmHandles": [
{
"cmHandleId": "xxx"
}
]
}

3

Request (trigger) Data Sync

POST

{ncmpRoot}/ncmp/v1/ch/<cmHandle>/syncData

Scenario : Client requests to sync a node

URI : {ncmpRoot}/ncmp/v1/ch/node123/syncData

Response : HTTP-Status code (only, no body)

4

Get model info for CMHandle

GET

{ncmpRoot}/ncmp/v1/ch/{cmHandle}/modules

Scenario : Get the model data for CMHandle

URI :{ncmpRoot}/ncmp/v1/ch/2334dedf/modules

Header :
Accept: application/json

Response:

  [
        {
            "moduleName": "nc-notifications",
            "revision": "2008-07-14",
        },
        {
            "moduleName": "ietf-tls-server",
            "revision": "2016-11-02",
        },
        {
            "moduleName": "ietf-ssh-server",
            "revision": "2016-11-02",
        }
    ]

5

Get all the registered cmhandles for a given plugin

GET

{ncmpRoot}/ncmp/v1/dmiPlugins/{pluginId}/ch

Scenario : Get all cmhandles from NCMP for a given dmiPlugin. May be used
for conciliation
Method : GET
URI : {ncmpRoot}/ncmp/v1/dmiPlugins/{dmiPlugin}/ch
Header :
Content-Type: application/json

Code Block

language	xml
title	Response Body

Success Response :
    HTTP/1.1 200 Ok
Date: Thu, 26 Jan 2021 20:56:30 GMT
Server: example-server
  { "cmHandles" : [ {
          "cmHandle" : "node-1",
          "cmHandleProperties " : { "subSystem" : "system-001" }
       } ]
   }

...

Versions Compared

Old Version 161

New Version 162

Key

Guiding Principles

References

Requirements

Characteristics - WIP

Note

Open Questions

Ongoing Discussion

Guiding Principles

References

Requirements

Issues & Decisions

Characteristics - WIP

Notes

Synchronous single cm-handle pass-through (read) requests

Page Comparison

Versions Compared

Old Version 161

New Version 162

Key

Guiding Principles

References

Requirements

Characteristics - WIP

Note

Open Questions

Ongoing Discussion

Guiding Principles

References

Requirements

Issues & Decisions

Characteristics - WIP

Notes

Synchronous single cm-handle pass-through (read) requests