RESTCONF Extensions to Support the Network Management Datastore Architecture
updates
- rfc-8040 — RESTCONF Protocol
Extracted elements (17)
The solution is designed to be backwards compatible with RFC 8040 by only adding new resources and leaving the semantics of existing resources unchanged, so existing RESTCONF clients and servers continue to work without modification.
RFC 8040 Section 3.5.4 paragraph 3 does not apply when interacting with any resource under {+restconf}/ds, providing a specific carve-out from the base RESTCONF specification for NMDA datastore resources.
When encoding 'origin' metadata annotations for a hierarchy of returned nodes, the annotation can be omitted for a child node when its value matches the parent node's annotation, as described in the 'ietf-origin' YANG module.
When 'with-defaults' is set to 'report-all-tagged' on the operational datastore, 'in use' values are returned and any values matching the schema default are tagged with additional metadata as described in RFC 8040 Section 4.8.9.
An NMDA-compliant RESTCONF server MUST support the operational state datastore and MUST implement at least revision 2019-01-04 of the 'ietf-yang-library' module defined in RFC 8525.
An NMDA-compliant server MUST implement the resource {+restconf}/ds/ietf-datastores:operational. Other datastore resources MAY be implemented.
For read-only datastores (e.g., <intended>), any attempt to modify them MUST result in a '405 Method Not Allowed' response with an error-tag value of 'operation-not-supported'.
If the 'with-origin' query parameter is used on a datastore other than operational or a datastore derived from the 'operational' identity, the server MUST return a '400 Bad Request' response with an error-tag value of 'invalid-value'.
The <datastore> path component in the resource path {+restconf}/ds/<datastore> is encoded as an identityref per RFC 7951 JSON encoding rules; the namespace-qualified form MUST be used and the identity MUST be derived from the 'datastore' identity in the 'ietf-datastores' YANG module.
A new 'with-origin' query parameter is added to the GET operation for {+restconf}/ds/ietf-datastores:operational. When present, it requests that the server include 'origin' metadata annotations in its response. Support is OPTIONAL, identified by capability URI urn:ietf:params:restconf:capability:with-origin:1.0.
A RESTCONF client can test if a server supports the NMDA by using HEAD or GET on {+restconf}/ds/ietf-datastores:operational, and can discover supported datastores and YANG modules by reading the YANG library from the operational state datastore.
Dynamic configuration datastores are excluded from the standard protocol operations on datastore resources, as each dynamic configuration datastore definition must be reviewed for which operations it supports.
New datastore resources are defined at the path {+restconf}/ds/<datastore>, where <datastore> is a namespace-qualified identityref derived from the 'datastore' identity in 'ietf-datastores'. Defined resources include operational, running, and intended configuration datastores.
Support for the 'with-defaults' query parameter on the operational state datastore is OPTIONAL and identified by capability URI urn:ietf:params:restconf:capability:with-operational-defaults:1.0. Its semantics differ from non-operational datastores: values returned are 'in use' values regardless of YANG schema defaults.
YANG actions can only be invoked in the {+restconf}/ds/ietf-datastores:operational resource, not in other datastore resources.
Two capability identifier URNs are registered in the 'RESTCONF Capability URNs' registry defined in RFC 8040: ':with-origin' (urn:ietf:params:restconf:capability:with-origin:1.0) and ':with-operational-defaults' (urn:ietf:params:restconf:capability:with-operational-defaults:1.0).
The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS (RFC 8446). RESTCONF uses NACM (RFC 8341) to restrict access for particular users to a preconfigured subset of available protocol operations and content. Security constraints from RFC 8040 Section 12 apply to the new datastore resources.