Jira | ||||||
---|---|---|---|---|---|---|
|
Table of Contents |
---|
Purpose of spike
...
The purpose of this spike is to investigate how fields and depth can be implemented and used in conjunction with Restconf to gather attributes from xNFs and be able to determine the depth of information retrieved.
...
Code Block | ||||
---|---|---|---|---|
| ||||
{ "turing-machine": { "transition-function": { "delta": [ { "label": "separator", "input": { "state": 0, "symbol": "0" }, "output": { "state": 1, "symbol": "1" } }, { "label": "write separator", "input": { "state": 2, "symbol": "1" }, "output": { "state": 3, "symbol": "0", "head-move": "left" } }, { "label": "right summand", "input": { "state": 1, "symbol": "1" } }, { "label": "final step", "input": { "state": 3, "symbol": "" }, "output": { "state": 4 } }, { "label": "go home", "input": { "state": 3, "symbol": "1" }, "output": { "head-move": "left" } }, { "label": "right end", "input": { "state": 1, "symbol": "" }, "output": { "state": 2, "head-move": "left" } }, { "label": "left summand", "input": { "state": 0, "symbol": "1" } } ] } } } |
The capabilities of both parameters as defined by RESTConf
Fields
The "fields" query parameter is used to optionally identify data nodes within the target resource to be retrieved in a GET method. The client can use this parameter to retrieve a subset of all nodes in a resource.
Assumptions
# | Assumption | Notes |
---|---|---|
1 | rests bundle is enable by default | |
2 | node has been mounted |
Open Issues & Decisions
...
# | Question | Answer |
---|---|---|
1 | When field function is used to list attributes in child will the parent still be part of output? | Yes if we do not specifically use delta=separator/input?fields=state |
2 | When not supplied with the module, if one match is found then we can insert the module. If more than one submodule is found with the same top-level element then it becomes ambiguous and cannot be resolved. | The system will throw an exception in the scenario where more then one submodule |
The capabilities of both parameters as defined by RESTConf
...
Fields
The "fields" query parameter is used to optionally identify data nodes within the target resource to be retrieved in a GET method. The client can use this parameter to retrieve a subset of all nodes in a resource.
- ";" is used to select multiple nodes. For example, to retrieve only the "genre" and "year" of an album, use: "fields=genre;year".
- Parentheses are used to
- ";" is used to select multiple nodes. For example, to retrieve only the "genre" and "year" of an album, use: "fields=genre;year".
- Parentheses are used to specify sub-selectors of a node. For example, to retrieve only the "label" and "catalogue‑number" of an album, use: "fields=admin(label;catalogue‑number)".
- "/" is used in a path to retrieve a child node of a node. For example, to retrieve only the "label" of an album, use: "fields=admin/label".
- This parameter is only allowed for GET methods on api, datastore, and data resources. A 400 Bad Request error is returned if used for other methods or resource types.
Fields
...
Syntax
Code Block | ||||
---|---|---|---|---|
| ||||
'fields=' ( <module-name> ':' )? <container-name> ( '(' <leaf-name> ( ',' <leaf-name> )* ')' )?
( '/' ( <module-name> ':' )? <container-name> ( '(' <leaf-name> ( ',' <leaf-name> )* ')' )? )*
fields=/shops
fields=/shops/shop
fields=/shops/shop(postal-code,town)
fields=bookstore:/shops/shop
fields=bookstore:/shops/bookstore:shop(postal-code,town)
fields=bookstore:/shops/shop(postal-code,town)/bookmodule:book(title)
*<module-name> ':' is compulsory when 'changing' into a different module from the parent node
|
Depth
The "depth" parameter is used to specify the number of nest levels returned in a response for a GET method. The first nest-level consists of the requested data node itself. Any child nodes which are contained within a parent node have a depth value that is 1 greater than its parent.
- The value of the "depth" parameter is either an integer between 1 and 65535, or the string "unbounded"
Depth
The "depth" parameter is used to specify the number of nest levels returned in a response for a GET method. The first nest-level consists of the requested data node itself. Any child nodes which are contained within a parent node have a depth value that is 1 greater than its parent.
- The value of the "depth" parameter is either an integer between 1 and 65535, or the string "unbounded". "unbounded" is the default.
- This parameter is only allowed for GET methods on API, datastore, and data resources. A 400 Bad Request error is returned if it used for other methods or resource types.
- By default, the server will include all sub-resources within a retrieved resource, which have the same resource type as the requested resource. Only one level of sub-resources with a different media type than the target resource will be returned.
Depth Example
The support/limitations of both parameters as implemented by the 'rests' ODL module interface (SDN-C)
The "rests" odl interface supports fields and depth parameters
Assumptions
...
rests bundle is enable by default
...
node has been mounted
Info |
---|
rests interface supports application/yang-data+json format |
rests Interface Fields Examples
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{
"turing-machine:turing-machine": {
"transition-function": {
"delta": [
{
"output": {
"state": 1
}
},
{
"output": {
"state": 3
}
},
{},
{
"output": {
"state": 4
}
},
{},
{
"output": {
"state": 2
}
},
{}
]
}
}
} |
or
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{
"turing-machine:transition-function": {
"delta": [
{
"output": {
"state": 1,
"symbol": "1"
}
},
{
"output": {
"state": 3,
"symbol": "0"
}
},
{},
{
"output": {
"state": 4
}
},
{},
{
"output": {
"state": 2
}
},
{}
]
}
} |
Get specific fields for specific delta
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{
"turing-machine:input": {
"state": 0
}
} |
rests Interface Depth Examples
If the "fields" parameter is used to select descendant data nodes, then these nodes and all of their ancestor nodes have a "depth" value of "1".
Note: same response for depth=2
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{} |
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{
"transition-function": {
"delta": [
{},
{},
{},
{},
{},
{},
{}
]
}
} |
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{
"transition-function": {
"delta": [
{
"label": "separator"
},
{
"label": "write separator"
},
{
"label": "right summand"
},
{
"label": "final step"
},
{
"label": "go home"
},
{
"label": "right end"
},
{
"label": "left summand"
}
]
}
} |
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{
"transition-function": {
"delta": [
{
"label": "separator",
"input": {
"state": 0,
"symbol": "0"
},
"output": {
"state": 1,
"symbol": "1"
}
},
{
"label": "write separator",
"input": {
"state": 2,
"symbol": "1"
},
"output": {
"state": 3,
"symbol": "0",
"head-move": "left"
}
},
{
"label": "right summand",
"input": {
"state": 1,
"symbol": "1"
}
},
{
"label": "final step",
"input": {
"state": 3,
"symbol": ""
},
"output": {
"state": 4
}
},
{
"label": "go home",
"input": {
"state": 3,
"symbol": "1"
},
"output": {
"head-move": "left"
}
},
{
"label": "right end",
"input": {
"state": 1,
"symbol": ""
},
"output": {
"state": 2,
"head-move": "left"
}
},
{
"label": "left summand",
"input": {
"state": 0,
"symbol": "1"
}
}
]
}
} |
Note: Depth of 0 will result in a 400 (Bad Request)
...
language | xml |
---|
...
...
The support/limitations of both parameters as implemented by the 'rests' ODL module interface (SDN-C)
...
The "rests" odl interface supports fields and depth parameters
Info |
---|
rests interface supports application/yang-data+json format |
The feasibility/cost of NCMP 'translating' a fields-option without module information
...
The feasibility/cost of NCMP 'translating' a fields-option without module information into a RESTConf compatible fields value. High level user story view of cost.
Fields that come in via NCMP will need to be translated into Restconf compatible fields.
Alternatives
- Assume that the query is in one module and no module information is required - cost 0 but won't always work
- Insert module information at the start and each transition of module - might lead to unnecessarily long fields section
- Insert module information for each element - nicest option
Cost alternative three
- Combine the resource path and the fields path into a 'target' path
requires new interface/REST method on CPS core (assuming there is an anchor with this schema-set) - Walk schema context and check the module for each element
Throw exception when more than one solution is encountered - Insert module name where needed
Estimate: 1 or 2 user stories (1 or 2 weeks work)Can we delegate to rests interface and supply fields "as is"
The feasibility/cost of support a 'depth' parameter for CPS cached data and/or ONAP DMI Plugin
...
- At the moment we have code to to include all or no descendants
Estimate: 1 user story (1-2 days to modify existing all-or-nothing approach)Will need to determine what is meant by cps cached data
Interaction Between Fields & Depth Parameters
...
Note: Depth can be any value .> 0. However, all details above field in question will be added to output
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{ "transition-function": { "delta": [ { "output": { "state": 1 } }, { "output": { "state": 3 } }, {}, { "output": { "state": 4 } }, {}, { "output": { "state": 2 } }, {} ] } } |
Note: field take precedence so adding depth=2 is the same as depth=1
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{ "transition-function": { "delta": [ { "output": { "state": 1 } }, { "output": { "state": 3 } }, {}, { "output": { "state": 4 } }, {}, { "output": { "state": 2 } }, {} ] } } |
Can also work with multiple fields as aboveNote: field take precedence so adding depth=2 is the same as depth=1
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{ "transition-function": { "delta": [ { "output": { "state": 1, "symbol": "1" } }, { "output": { "state": 3, "symbol": "0" } }, {}, { "output": { "state": 4 } }, {}, { "output": { "state": 2 } }, {} ] } } |
Fields with module
...
examples
...
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{ "turing-machine": { "transition-function": { "delta": [ { "output": { "state": 1 } }, { "output": { "state": 3 } }, {}, { "output": { "state": 4 } }, {}, { "output": { "state": 2 } }, {} ] } } } |
Findings from Demo
- We can get the child by using http://localhost:8282/rests/data/network-topology:network-topology/topology=topology-netconf/node=PNFDemo/yang-ext:mount/turing-machine:turing-machine/transition-function/delta=separator
...
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{ "turing-machine:input": { "state": 0, "symbol": "0" } } |
- We can also get specific fields without ancestors in the tree http://localhost:8282/rests/data/network-topology:network-topology/topology=topology-netconf/node=PNFDemo/yang-ext:mount/turing-machine:turing-machine/transition-function/delta=separator/input?fields=state
JSON Viewer | ||||
---|---|---|---|---|
| ||||
{ "turing-machine:input": { "state": 0 } } |
Video of Demo
Questions
...
Setting up local netconf-pnp-simulator & SDNC environment
...
- Run docker load -i image.tar to unpack netconf docker image v2.8.6
- Unzip certs.tar to same folder as docker-compose.yml (SDNC docker)
- Unpack sim.zip
- Run docker-compose up -d
- Run sim/docker-compose -f docker-compose-sim.yml up -d (netconf-pnp-simulator docker)
- To access local SDNC/ODL use - http://localhost:8282/apidoc/explorer/index.html
- Credentials : - admin / Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
...