Open Issues & Decisions

3Yml update with return types with

	Description	Notes	Decision
1	Priority of async calls
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.
23	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/opartionoperation
4	Parent data resource identifier can handle any path	using the same query parameter cpsPath RESTConf Path Proprietary Path
5	Yml should include return types and	4	examples of the payload

Principles

...

RESTCONF/NETCONF relationship

Image Removed

NCMP URI

NCMP URI format to follow below pattern

...


6	camel case or dash in URI
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>

URIMandatory or Optional<OP>the HTTP methodMandatoryncmp /the ncmp root resourceMandatory<v{v-number}>version of the ncmp interface <path> is the target resource URI <query> is the query parameter listMandatorycm-handle /<cm-handle>unique (string) identifier of a yang tree instance.Optional


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)

Principles

Follow principles/patterns of RESTCONF RFC-8040
Follow principles/patterns of yang-patch RFC-8072
Follow principles/patterns of RESTCONF NMDA RFC-8527

RESTCONF/NETCONF relationship

Image Added

NCMP URI

NCMP URI format to follow below pattern

<OP>/ncmp /<v{v-number}>/cmhandle/<cm-handle>/<data|operations|{ncmp-action}>

...

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

...

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 :

...

/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
cm-handle /<cm-handle>	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	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)	Read/Write to the CPS "intended" store (with validation). Then do subsequent write on DMI interface with ds ietf-datastores:running.
2	ncmp-datastores:operational (RO)	Read from the CPS "operational" store.
3	ncmp-datastores:passthrough-running (RW)	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 ncmp-datastores:passthrough-operational (RO) : Read from the live devices ietf-datastores:operational
2	ncmp-datastores:passthrough-candidate (RW)	Read from the live devices ietf-datastores:candidate

If datastore (ds/{datastore}) is omitted from URI AND the model/moduleSet is not available in NCMP, the datastore defaults to ncmp-datastores: passthrough-running

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

#	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						> Istanbul
12							> Istanbul
13	Action						Istanbul?
14							Istanbul?

Future datastores to be supported by NCMP include :

...

If datastore (ds/{datastore}) is omitted from URI AND the model/moduleSet is not available in NCMP, the datastore is defaulted to ncmp-datastores: passthrough-running

If datastore (ds/{datastore}) is omitted from URI AND the model/moduleSet exists, the datastore defaults to ncmp-datastores:running

...

REST API

21

Req/usecase

REST

Method

URI / Payload

Header Parameters

Request/Response Example

Status

1

Ericsson ref.NCMP-CM-001-2

Read a data resource directly from source (passthrough) for a cmHandle - async

GET

{ncmp-root}/ncmp/v1/cm-handle//ds /ncmp-datastores:passthrough-running/{data-resource-identifier}?fields={fields}&topic= {topicId{data-resource-identifier}

Note 'topic' and 'fields' are only supported in passthrough mode at this time (ONAP Release I). If not pass through then an exception is thrown from NCMP at this time.

Accept:
application/json

Scenario : Read the bookstore for cmhandle "335ff123" as passthrough
Method : GET
URI : {ncmp-root}/ncmp/v1/cm-handle/335ff123/ds/ncmp-datastores:
passthrough-running//bookstore
Header :
Accept: application/json

Event Response:

Expand

[
    {
        "xpath": "/bookstore",
        "leaves": {
            "bookstore-name": "Chapters"
        },
        "childDataNodes": [
            {
                "xpath": "/bookstore/categories[@code='01']",
                "leaves": {
                    "code": "01",
                    "name": "SciFi"
                },
                "childDataNodes": [
                    {
                        "xpath": "/bookstore/categories[@code='01']/books[@title='Far Horizons']",
                        "leaves": {
                            "lang": "en",
                            "price": {
                                "value": 1099.0
                            },
                            "title": "Far Horizons",
                            "authors": [
                                "david Brin",
                                "Ursula K. Le Guin",
                                "Rober Silverberg",
                                "Orson Scott Card",
                                "Greg Bear",
                                "Joe Haldeman",
                                "Dan Simmons"
                            ],
                            "pub_year": {
                                "value": 1999.0
                            }
                        },
                        "childDataNodes": []
                    },
                    {
                        "xpath": "/bookstore/categories[@code='01']/books[@title='Feersum Endjinn']",
                        "leaves": {
                            "lang": "en",
                            "price": {
                                "value": 895.0
                            },
                            "title": "Feersum Endjinn",
                            "authors": [
                                "Iain M. Banks"
                            ],
                            "pub_year": {
                                "value": 1994.0
                            }
                        },
                        "childDataNodes": []
                    }
                ]
            },
            {
                "xpath": "/bookstore/categories[@code='02']",
                "leaves": {
                    "code": "02",
                    "name": "kids"
                },
                "childDataNodes": [
                    {
                        "xpath": "/bookstore/categories[@code='02']/books[@title='The Golden Compass']",
                        "leaves": {
                            "lang": "en",
                            "price": {
                                "value": 699.0
                            },
                            "title": "The Golden Compass",
                            "authors": [
                                "Philip Pullman"
                            ],
                            "pub_year": {
                                "value": 1995.0
                            }
                        },
                        "childDataNodes": []
                    }
                ]
            }
        ]
    }
]

Under Review

2

Ericsson ref. NCMP-CM-001-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 bookstore.(categories,
title, authors, pub_year, price, lang) for cmhandle
"335ff" as passthrough
Method : GET
URI : {ncmp-root}/ncmp/v1/cm-handle/335ff/ds/ncmp-datastores:
passthrough-running//books?fields=title;
authors;pub_year;price;lang
Header :
Accept: application/json

Response

Expand

[
    {
        "xpath": "/bookstore/categories[@code='02']/books[@title='The Golden Compass']",
        "leaves": {
            "lang": "en",
            "price": {
                "value": 699.0
            },
            "title": "The Golden Compass",
            "authors": [
                "Philip Pullman"
            ],
            "pub_year": {
                "value": 1995.0
            }
        },
        "childDataNodes": []
    }
]

[
    {
        "xpath": "/bookstore/categories[@code='01']/books[@title='Feersum Endjinn']",
        "leaves": {
            "lang": "en",
            "price": {
                "value": 895.0
            },
            "title": "Feersum Endjinn",
            "authors": [
                "Iain M. Banks"
            ],
            "pub_year": {
                "value": 1994.0
            }
        },
        "childDataNodes": []
    }
]

[
    {
        "xpath": "/bookstore/categories[@code='01']/books[@title='Far Horizons']",
        "leaves": {
            "lang": "en",
            "price": {
                "value": 1099.0
            },
            "title": "Far Horizons",
            "authors": [
                "david Brin",
                "Ursula K. Le Guin",
                "Rober Silverberg",
                "Orson Scott Card",
                "Greg Bear",
                "Joe Haldeman",
                "Dan Simmons"
            ],
            "pub_year": {
                "value": 1999.0
            }
        },
        "childDataNodes": []
    }
]

Under Review

3

ALTERNATIVE OUTPUT TO ABOVE
SCENARIO
NCMP-CM-001-2
Read a data resource directly from
source (passthrough) for a
cmHandle. Only return specific field(s).
Synchronous call

GET

WIP

Accept:
application/json

WIP

Under Review

4

NCMP-CM-001-2
Read a data resource with some leaf value condition directly from the source (passthrough) for a cmHandle. Only return specific field(s).
Synchronous call

GET

{ncmp-root}/ncmp/v1/cm-handle//ds /ncmp-datastores:passthrough-running/{data-resource-identifier}?fields={fields} &topic={topicId}

Accept:
application/json

Scenario : Read

Read the price for cmhandle ="335ff" as passthrough

Method : GET
URI : {ncmp-root}/ncmp/v1/cm-handle/335ff/ds/ncmp-datastores:passthrough running//books[@title='Far Horizons']?fields=price
Header :
Accept: application/json

[
    {
        "xpath": "/bookstore/categories[@code='01']/books[@title='Far Horizons']",
        "leaves": {
            "price":  1099.0

}

]

Under Review

5

NCMP-CM-001-1

Get model (module set) for CMHandle

GET

{ncmp-root}/ncmp/v1/model/<handleId>

{ncmp-root}/ncmp/v1/model/cmhandle/<cm-handle>

Accept:
application/json

Scenario : Get the model data for CMHandle with id "335ff"
Method : GET
URI : {ncmp-root}/ncmp/v1/model/335ff
Header : Accept: application/yang-data+json

Response :

Expand

{
   "test:bookstore":{
      "bookstore-name": "Chapters",
      "categories": [
         {
            "code": "01",
            "name": "SciFi",
            "books": [
               {
                  "authors": [
                     "Iain M. Banks"
                  ],
                  "lang": "en",
                  "price": "895",
                  "pub_year": "1994",
                  "title": "Feersum Endjinn"
               },
               {
                  "authors": [
                     "Ursula K. Le Guin",
                     "Joe Haldeman",
                     "Orson Scott Card",
                     "david Brin",
                     "Rober Silverberg",
                     "Dan Simmons",
                     "Greg Bear"
                  ],
                  "lang": "en",
                  "price": "1099",
                  "pub_year": "1999",
                  "title": "Far Horizons"
               }
            ]
         },
         {
            "name": "kids",
            "code": "02",
            "books": [
               {
                  "authors": [
                     "Philip Pullman"
                  ],
                  "lang": "en",
                  "price": "699",
                  "pub_year": "1995",
                  "title": "The Golden Compass"
               }
            ]
         }
      ]
   }
}

Under Review

6

NCMP-CM-001-4
Create a data resource for a
cmhandle

POST

{ncmp-root}/ncmp/v1/cm-handle/<cmhandle>/ds/ncmp-datastores:passthrough-running/{parent-data-resource-identifier}
{
<new-yang-data-resource>
}OR with datastores defaults{ncmp-root}/ncmp/v1/cmhandle/<cm-hande>:passthrough-running/{parent-data-resource-identifier}
{
<new-yang-data-resource>
}

Accept:
application/ yang- data+json

Scenario : Create a data resource of the bookstore model for the given cmhandle.

Method : POST

RI : {ncmp-root}/ncmp/v1/cm-handle/34l5k32/bookstore

Header : Accept: application/yang-data+json

Body:

Expand
{ "test:bookstore":{ "bookstore-name": "Chapters", "categories": [ { "code": "01", "name": "SciFi", } ] } }

Under Review

7

NCMP-CM-001-5
Delete a data resource for a
cmHandle

DELETE

{ncmp-root}/ncmp/v1//ds/ncmp-datastores:passthrough-running/{data-resource-identifier}

OR with datastores defaults

{ncmp-root}/ncmp/v1/cmhandle// {parent-data-resource-identifier}

Accept:
application/ yang- data+json

Scenario : Delete categories=SciFi
Method : DELETE
URI : {ncmp-root}/ncmp/v1/cmhandle/<cm-handle>//categories[@name="SciFi"]

do we follow xpath syntax?

{adapter-root}???

Under Review

8

NCMP-CM-001-3
Update a data resource for a
cmHandle

PATCH

{ncmp-root}/ncmp/v1/data//ds/ncmp-datastores:passthrough-running/{data-resource-identifier}

{
<yang-data-sub-resource>
}

OR with datastores defaults

{ncmp-root}/ncmp/v1/cmhandle// {parent-data-resource-identifier}

{
<yang-data-sub-resource>
}

Accept:
application/ yang- data+json

Scenario : Add a book to categories SciFi if it doesn't already exist
Method : PATCH
URI : {ncmp-root}/ncmp/v1/cm-handle/d32455f/bookstore/categories:name=SciFi

Header :
Content-Type: application/yang-data+json

Body :

Expand
{ "categories": [ { "code": "01", "name": "SciFi", "books": [ { "authors": [ "Iain M. Banks" ], "lang": "en", "price": "895", "pub_year": "1994", "title": "Feersum Endjinn" } ] } ] }

Under Review

9

NCMP-CM-001-8

Multiple edits under a target data
resource for a single cmHandle

PATCH

{ncmp-root}/ncmp/v1/cm-handle//ds /ncmp-datastores:passthrough-running/{data-resource-identifier}

{

yang-patch payload

}

OR using datastores defaults

{ncmp-root}/ncmp/v1/cm-handle//{data-resource-identifier}

{

yang-patch payload

}

Content-Type:
application/yang-patch+json

Scenario: Make multiple updates under the bookstore/categories data resource

Method : PATCH

URI : {ncmp-root}/ncmp/v1/cm-handle/32rf234/bookstore/categories

Header :
Content-Type: application/yang-patch+json

Body:

Expand

{
   "ietf-restconf:yang-patch" : {
      "patch-id" : "change-categories-names",
      "edit" : [
         {
            "edit-id" : 1,
            "operation" : "create",
            "target" : "/bookstore/categories:code="01",
            "value" : {
               "/bookstore/categories:code" : {
                  "name" : "Biography"
               }
            }
         },
         {
            "edit-id" : 2,
            "operation" : "create",
            "target" :"/bookstore/categories:code="02"",
            "value" : {
               "/bookstore/categories:code" : {
                  "name" : "Detective"
               }
            }
         }
	]
}

Response :
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-patch+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "change-categories-names",
"ok" : [null]
}
}

Under Review

10

11

12

13

14

15

16

17

18

19

20

}
}

Under Review

10

11

12

13

14

15

16

17

18

19

20

21

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

Jira

server	ONAP JIRA
columns	key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId	425b2b0a-557c-3c0c-b515-579789cceedb
key	CPS-401

Space shortcuts

Page tree

Versions Compared

Old Version 7

New Version 8

Key

Open Issues & Decisions

Principles

RESTCONF/NETCONF relationship

NCMP URI

Principles

RESTCONF/NETCONF relationship

NCMP URI

Datastores

Datastores

REST API

Output Specification

Assynchronous

Required Task

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 7

New Version 8

Key

Open Issues & Decisions

Principles

RESTCONF/NETCONF relationship

NCMP URI

Principles

RESTCONF/NETCONF relationship

NCMP URI

Datastores

Datastores

REST API

Output Specification

Assynchronous

Required Task