file "ietf-restconf@2017-01-26.yang"
module ietf-restconf {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf";
prefix "rc";
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web:
WG List:
Author: Andy Bierman
Author: Martin Bjorklund
Author: Kent Watsen
";
description
"This module contains conceptual YANG specifications
for basic RESTCONF media type definitions used in
RESTCONF protocol messages.
Note that the YANG definitions within this module do not
represent configuration data of any kind.
The 'restconf-media-type' YANG extension statement
provides a normative syntax for XML and JSON
message-encoding purposes.
Bierman, et al. Standards Track [Page 79]
RFC 8040 RESTCONF January 2017
Copyright (c) 2017 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC 8040; see
the RFC itself for full legal notices.";
revision 2017-01-26 {
description
"Initial revision.";
reference
"RFC 8040: RESTCONF Protocol.";
}
extension yang-data {
argument name {
yin-element true;
}
description
"This extension is used to specify a YANG data template that
represents conceptual data defined in YANG. It is
intended to describe hierarchical data independent of
protocol context or specific message-encoding format.
Data definition statements within a yang-data extension
specify the generic syntax for the specific YANG data
template, whose name is the argument of the 'yang-data'
extension statement.
Note that this extension does not define a media type.
A specification using this extension MUST specify the
message-encoding rules, including the content media type.
The mandatory 'name' parameter value identifies the YANG
data template that is being defined. It contains the
template name.
This extension is ignored unless it appears as a top-level
statement. It MUST contain data definition statements
that result in exactly one container data node definition.
An instance of a YANG data template can thus be translated
into an XML instance document, whose top-level element
corresponds to the top-level container.
Bierman, et al. Standards Track [Page 80]
RFC 8040 RESTCONF January 2017
The module name and namespace values for the YANG module using
the extension statement are assigned to instance document data
conforming to the data definition statements within
this extension.
The substatements of this extension MUST follow the
'data-def-stmt' rule in the YANG ABNF.
The XPath document root is the extension statement itself,
such that the child nodes of the document root are
represented by the data-def-stmt substatements within
this extension. This conceptual document is the context
for the following YANG statements:
- must-stmt
- when-stmt
- path-stmt
- min-elements-stmt
- max-elements-stmt
- mandatory-stmt
- unique-stmt
- ordered-by
- instance-identifier data type
The following data-def-stmt substatements are constrained
when used within a 'yang-data' extension statement.
- The list-stmt is not required to have a key-stmt defined.
- The if-feature-stmt is ignored if present.
- The config-stmt is ignored if present.
- The available identity values for any 'identityref'
leaf or leaf-list nodes are limited to the module
containing this extension statement and the modules
imported into that module.
";
}
rc:yang-data yang-errors {
uses errors;
}
rc:yang-data yang-api {
uses restconf;
}
Bierman, et al. Standards Track [Page 81]
RFC 8040 RESTCONF January 2017
grouping errors {
description
"A grouping that contains a YANG container
representing the syntax and semantics of a
YANG Patch error report within a response message.";
container errors {
description
"Represents an error report returned by the server if
a request results in an error.";
list error {
description
"An entry containing information about one
specific error that occurred while processing
a RESTCONF request.";
reference
"RFC 6241, Section 4.3.";
leaf error-type {
type enumeration {
enum transport {
description
"The transport layer.";
}
enum rpc {
description
"The rpc or notification layer.";
}
enum protocol {
description
"The protocol operation layer.";
}
enum application {
description
"The server application layer.";
}
}
mandatory true;
description
"The protocol layer where the error occurred.";
}
Bierman, et al. Standards Track [Page 82]
RFC 8040 RESTCONF January 2017
leaf error-tag {
type string;
mandatory true;
description
"The enumerated error-tag.";
}
leaf error-app-tag {
type string;
description
"The application-specific error-tag.";
}
leaf error-path {
type instance-identifier;
description
"The YANG instance identifier associated
with the error node.";
}
leaf error-message {
type string;
description
"A message describing the error.";
}
anydata error-info {
description
"This anydata value MUST represent a container with
zero or more data nodes representing additional
error information.";
}
}
}
}
grouping restconf {
description
"Conceptual grouping representing the RESTCONF
root resource.";
container restconf {
description
"Conceptual container representing the RESTCONF
root resource.";
Bierman, et al. Standards Track [Page 83]
RFC 8040 RESTCONF January 2017
container data {
description
"Container representing the datastore resource.
Represents the conceptual root of all state data
and configuration data supported by the server.
The child nodes of this container can be any data
resources that are defined as top-level data nodes
from the YANG modules advertised by the server in
the 'ietf-yang-library' module.";
}
container operations {
description
"Container for all operation resources.
Each resource is represented as an empty leaf with the
name of the RPC operation from the YANG 'rpc' statement.
For example, the 'system-restart' RPC operation defined
in the 'ietf-system' module would be represented as
an empty leaf in the 'ietf-system' namespace. This is
a conceptual leaf and will not actually be found in
the module:
module ietf-system {
leaf system-reset {
type empty;
}
}
To invoke the 'system-restart' RPC operation:
POST /restconf/operations/ietf-system:system-restart
To discover the RPC operations supported by the server:
GET /restconf/operations
In XML, the YANG module namespace identifies the module:
In JSON, the YANG module name identifies the module:
{ 'ietf-system:system-restart' : [null] }
";
}
Bierman, et al. Standards Track [Page 84]
RFC 8040 RESTCONF January 2017
leaf yang-library-version {
type string {
pattern '\d{4}-\d{2}-\d{2}';
}
config false;
mandatory true;
description
"Identifies the revision date of the 'ietf-yang-library'
module that is implemented by this RESTCONF server.
Indicates the year, month, and day in YYYY-MM-DD
numeric format.";
}
}
}
}
9. RESTCONF Monitoring
The "ietf-restconf-monitoring" module provides information about the
RESTCONF protocol capabilities and event streams available from the
server. A RESTCONF server MUST implement the
"ietf-restconf-monitoring" module.
YANG tree diagram for the "ietf-restconf-monitoring" module:
+--ro restconf-state
+--ro capabilities
| +--ro capability* inet:uri
+--ro streams
+--ro stream* [name]
+--ro name string
+--ro description? string
+--ro replay-support? boolean
+--ro replay-log-creation-time? yang:date-and-time
+--ro access* [encoding]
+--ro encoding string
+--ro location inet:uri
Bierman, et al. Standards Track [Page 85]
RFC 8040 RESTCONF January 2017
9.1. restconf-state/capabilities
This mandatory container holds the RESTCONF protocol capability URIs
supported by the server.
The server MAY maintain a last-modified timestamp for this container
and return the "Last-Modified" header field when this data node is
retrieved with the GET or HEAD methods. Note that the last-modified
timestamp for the datastore resource is not affected by changes to
this subtree.
The server SHOULD maintain an entity-tag for this container and
return the "ETag" header field when this data node is retrieved with
the GET or HEAD methods. Note that the entity-tag for the datastore
resource is not affected by changes to this subtree.
The server MUST include a "capability" URI leaf-list entry for the
"defaults" mode used by the server, defined in Section 9.1.2.
The server MUST include a "capability" URI leaf-list entry
identifying each supported optional protocol feature. This includes
optional query parameters and MAY include other capability URIs
defined outside this document.
Bierman, et al. Standards Track [Page 86]
RFC 8040 RESTCONF January 2017
9.1.1. Query Parameter URIs
A new set of RESTCONF Capability URIs are defined to identify the
specific query parameters (defined in Section 4.8) supported by the
server.
The server MUST include a "capability" leaf-list entry for each
optional query parameter that it supports.
+----------------+---------+---------------------------------------+
| Name | Section | URI |
| | | |
+----------------+---------+---------------------------------------+
| depth | 4.8.2 | urn:ietf:params:restconf:capability: |
| | | depth:1.0 |
| | | |
| fields | 4.8.3 | urn:ietf:params:restconf:capability: |
| | | fields:1.0 |
| | | |
| filter | 4.8.4 | urn:ietf:params:restconf:capability: |
| | | filter:1.0 |
| | | |
| replay | 4.8.7 | urn:ietf:params:restconf:capability: |
| | 4.8.8 | replay:1.0 |
| | | |
| with-defaults | 4.8.9 | urn:ietf:params:restconf:capability: |
| | | with-defaults:1.0 |
+----------------+---------+---------------------------------------+
RESTCONF Query Parameter URIs
9.1.2. The "defaults" Protocol Capability URI
This URI identifies the "basic-mode" default-handling mode that is
used by the server for processing default leafs in requests for data
resources. This protocol capability URI MUST be supported by the
server and MUST be listed in the "capability" leaf-list defined in
Section 9.3.
+----------+--------------------------------------------------+
| Name | URI |
+----------+--------------------------------------------------+
| defaults | urn:ietf:params:restconf:capability:defaults:1.0 |
+----------+--------------------------------------------------+
RESTCONF "defaults" Capability URI
Bierman, et al. Standards Track [Page 87]
RFC 8040 RESTCONF January 2017
The URI MUST contain a query parameter named "basic-mode" with one of
the values listed below:
+------------+------------------------------------------------------+
| Value | Description |
+------------+------------------------------------------------------+
| report-all | No data nodes are considered default |
| | |
| trim | Values set to the YANG default-stmt value are |
| | default |
| | |
| explicit | Values set by the client are never considered |
| | default |
+------------+------------------------------------------------------+
The "basic-mode" definitions are specified in "With-defaults
Capability for NETCONF" [RFC6243].
If the "basic-mode" is set to "report-all", then the server MUST
adhere to the default-handling behavior defined in Section 2.1 of
[RFC6243].
If the "basic-mode" is set to "trim", then the server MUST adhere to
the default-handling behavior defined in Section 2.2 of [RFC6243].
If the "basic-mode" is set to "explicit", then the server MUST adhere
to the default-handling behavior defined in Section 2.3 of [RFC6243].
Example (split for display purposes only):
urn:ietf:params:restconf:capability:defaults:1.0?
basic-mode=explicit
9.2. restconf-state/streams
This optional container provides access to the event streams
supported by the server. The server MAY omit this container if no
event streams are supported.
The server will populate this container with a "stream" list entry
for each stream type it supports. Each stream contains a leaf called
"events", which contains a URI that represents an event stream
resource.
Stream resources are defined in Section 3.8. Notifications are
defined in Section 6.
Bierman, et al. Standards Track [Page 88]
RFC 8040 RESTCONF January 2017
9.3. RESTCONF Monitoring Module
The "ietf-restconf-monitoring" module defines monitoring information
for the RESTCONF protocol.
The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991]
are used by this module for some type definitions.
file "ietf-restconf-monitoring@2017-01-26.yang"
module ietf-restconf-monitoring {
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring";
prefix "rcmon";
import ietf-yang-types { prefix yang; }
import ietf-inet-types { prefix inet; }
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web:
WG List:
Author: Andy Bierman
Author: Martin Bjorklund
Author: Kent Watsen
";
Bierman, et al. Standards Track [Page 89]
RFC 8040 RESTCONF January 2017
description
"This module contains monitoring information for the
RESTCONF protocol.
Copyright (c) 2017 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC 8040; see
the RFC itself for full legal notices.";
revision 2017-01-26 {
description
"Initial revision.";
reference
"RFC 8040: RESTCONF Protocol.";
}
container restconf-state {
config false;
description
"Contains RESTCONF protocol monitoring information.";
container capabilities {
description
"Contains a list of protocol capability URIs.";
leaf-list capability {
type inet:uri;
description
"A RESTCONF protocol capability URI.";
}
}
Bierman, et al. Standards Track [Page 90]
RFC 8040 RESTCONF January 2017
container streams {
description
"Container representing the notification event streams
supported by the server.";
reference
"RFC 5277, Section 3.4, element.";
list stream {
key name;
description
"Each entry describes an event stream supported by
the server.";
leaf name {
type string;
description
"The stream name.";
reference
"RFC 5277, Section 3.4, element.";
}
leaf description {
type string;
description
"Description of stream content.";
reference
"RFC 5277, Section 3.4, element.";
}
leaf replay-support {
type boolean;
default false;
description
"Indicates if replay buffer is supported for this stream.
If 'true', then the server MUST support the 'start-time'
and 'stop-time' query parameters for this stream.";
reference
"RFC 5277, Section 3.4, element.";
}
Bierman, et al. Standards Track [Page 91]
RFC 8040 RESTCONF January 2017
leaf replay-log-creation-time {
when "../replay-support" {
description
"Only present if notification replay is supported.";
}
type yang:date-and-time;
description
"Indicates the time the replay log for this stream
was created.";
reference
"RFC 5277, Section 3.4,
element.";
}
list access {
key encoding;
min-elements 1;
description
"The server will create an entry in this list for each
encoding format that is supported for this stream.
The media type 'text/event-stream' is expected
for all event streams. This list identifies the
subtypes supported for this stream.";
leaf encoding {
type string;
description
"This is the secondary encoding format within the
'text/event-stream' encoding used by all streams.
The type 'xml' is supported for XML encoding.
The type 'json' is supported for JSON encoding.";
}
Bierman, et al. Standards Track [Page 92]
RFC 8040 RESTCONF January 2017
leaf location {
type inet:uri;
mandatory true;
description
"Contains a URL that represents the entry point
for establishing notification delivery via
server-sent events.";
}
}
}
}
}
}
10. YANG Module Library
The "ietf-yang-library" module defined in [RFC7895] provides
information about the YANG modules and submodules used by the
RESTCONF server. Implementation is mandatory for RESTCONF servers.
All YANG modules and submodules used by the server MUST be identified
in the YANG module library.
10.1. modules-state/module
This mandatory list contains one entry for each YANG data model
module supported by the server. There MUST be an instance of this
list for every YANG module that is used by the server.
The contents of this list are defined in the "module" YANG list
statement in [RFC7895].
Note that there are no protocol-accessible objects in the
"ietf-restconf" module to implement, but it is possible that a server
will list the "ietf-restconf" module in the YANG library if it is
imported (directly or indirectly) by an implemented module.
Bierman, et al. Standards Track [Page 93]
RFC 8040 RESTCONF January 2017
11. IANA Considerations
11.1. The "restconf" Relation Type
This specification registers the "restconf" relation type in the
"Link Relation Types" registry defined by [RFC5988]:
Relation Name: restconf
Description: Identifies the root of the RESTCONF API as configured
on this HTTP server. The "restconf" relation
defines the root of the API defined in RFC 8040.
Subsequent revisions of RESTCONF will use alternate
relation values to support protocol versioning.
Reference: RFC 8040
11.2. Registrations for New URIs and YANG Modules
This document registers two URIs as namespaces in the "IETF XML
Registry" [RFC3688]:
URI: urn:ietf:params:xml:ns:yang:ietf-restconf
Registrant Contact: The IESG.
XML: N/A; the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
Registrant Contact: The IESG.
XML: N/A; the requested URI is an XML namespace.
This document registers two YANG modules in the "YANG Module Names"
registry [RFC6020]:
name: ietf-restconf
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf
prefix: rc
reference: RFC 8040
name: ietf-restconf-monitoring
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
prefix: rcmon
reference: RFC 8040
Bierman, et al. Standards Track [Page 94]
RFC 8040 RESTCONF January 2017
11.3. Media Types
11.3.1. Media Type "application/yang-data+xml"
Type name: application
Subtype name: yang-data+xml
Required parameters: None
Optional parameters: None
Encoding considerations: 8-bit
Each conceptual YANG data node is encoded according to the
XML Encoding Rules and Canonical Format for the specific
YANG data node type defined in [RFC7950].
Security considerations: Security considerations related
to the generation and consumption of RESTCONF messages
are discussed in Section 12 of RFC 8040.
Additional security considerations are specific to the
semantics of particular YANG data models. Each YANG module
is expected to specify security considerations for the
YANG data defined in that module.
Interoperability considerations: RFC 8040 specifies the
format of conforming messages and the interpretation
thereof.
Published specification: RFC 8040
Applications that use this media type: Instance document
data parsers used within a protocol or automation tool
that utilize YANG-defined data structures.
Fragment identifier considerations: Fragment identifiers for
this type are not defined. All YANG data nodes are
accessible as resources using the path in the request URI.
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): None
Macintosh file type code(s): "TEXT"
Person & email address to contact for further information: See
the Authors' Addresses section of RFC 8040.
Bierman, et al. Standards Track [Page 95]
RFC 8040 RESTCONF January 2017
Intended usage: COMMON
Restrictions on usage: N/A
Author: See the Authors' Addresses section of RFC 8040.
Change controller: Internet Engineering Task Force
(mailto:iesg@ietf.org).
Provisional registration? (standards tree only): no
11.3.2. Media Type "application/yang-data+json"
Type name: application
Subtype name: yang-data+json
Required parameters: None
Optional parameters: None
Encoding considerations: 8-bit
Each conceptual YANG data node is encoded according to
[RFC7951]. A metadata annotation is encoded according to
[RFC7952].
Security considerations: Security considerations related
to the generation and consumption of RESTCONF messages
are discussed in Section 12 of RFC 8040.
Additional security considerations are specific to the
semantics of particular YANG data models. Each YANG module
is expected to specify security considerations for the
YANG data defined in that module.
Interoperability considerations: RFC 8040 specifies the format
of conforming messages and the interpretation thereof.
Published specification: RFC 8040
Applications that use this media type: Instance document
data parsers used within a protocol or automation tool
that utilize YANG-defined data structures.
Fragment identifier considerations: The syntax and semantics
of fragment identifiers are the same as the syntax and semantics
specified for the "application/json" media type.
Bierman, et al. Standards Track [Page 96]
RFC 8040 RESTCONF January 2017
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): None
Macintosh file type code(s): "TEXT"
Person & email address to contact for further information: See
the Authors' Addresses section of RFC 8040.
Intended usage: COMMON
Restrictions on usage: N/A
Author: See the Authors' Addresses section of RFC 8040.
Change controller: Internet Engineering Task Force
(mailto:iesg@ietf.org).
Provisional registration? (standards tree only): no
11.4. RESTCONF Capability URNs
This document defines a registry for RESTCONF capability identifiers.
The name of the registry is "RESTCONF Capability URNs". The review
policy for this registry is "IETF Review" [RFC5226]. The registry
shall record the following for each entry:
o the name of the RESTCONF capability. By convention, this name
begins with the colon (":") character.
o the URN for the RESTCONF capability.
o the reference for the document registering the value.
Bierman, et al. Standards Track [Page 97]
RFC 8040 RESTCONF January 2017
This document registers several capability identifiers in the
"RESTCONF Capability URNs" registry:
Index Capability Identifier
---------------------------------------------------------------------
:defaults urn:ietf:params:restconf:capability:defaults:1.0
:depth urn:ietf:params:restconf:capability:depth:1.0
:fields urn:ietf:params:restconf:capability:fields:1.0
:filter urn:ietf:params:restconf:capability:filter:1.0
:replay urn:ietf:params:restconf:capability:replay:1.0
:with-defaults urn:ietf:params:restconf:capability:with-defaults:1.0
11.5. Registration of "restconf" URN Sub-namespace
IANA has registered a new URN sub-namespace within the "IETF URN
Sub-namespace for Registered Protocol Parameter Identifiers" registry
defined in [RFC3553].
Registry Name: restconf
Specification: RFC 8040
Repository: "RESTCONF Capability URNs" registry (Section 11.4)
Index value: Sub-parameters MUST be specified in UTF-8, using
standard URI encoding where necessary.
Bierman, et al. Standards Track [Page 98]
RFC 8040 RESTCONF January 2017
12. Security Considerations
Section 2.1 states that "a RESTCONF server MUST support the TLS
protocol [RFC5246]." This language leaves open the possibility that
a RESTCONF server might also support future versions of the TLS
protocol. Of specific concern, TLS 1.3 [TLS1.3] introduces support
for 0-RTT handshakes that can lead to security issues for RESTCONF
APIs, as described in Appendix B.1 of the TLS 1.3 document. It is
therefore RECOMMENDED that RESTCONF servers do not support 0-RTT at
all (not even for idempotent requests) until an update to this RFC
guides otherwise.
Section 2.5 recommends authentication based on TLS client
certificates but allows the use of any authentication scheme defined
in the "Hypertext Transfer Protocol (HTTP) Authentication Scheme
Registry". Implementations need to be aware that the strengths of
these methods vary greatly and that some may be considered
experimental. Selection of any of these schemes SHOULD be performed
after reading the Security Considerations section of the RFC
associated with the scheme's registry entry.
The "ietf-restconf-monitoring" YANG module defined in this memo is
designed to be accessed via the NETCONF protocol [RFC6241]. The
lowest NETCONF layer is the secure transport layer, and the
mandatory-to-implement secure transport is Secure Shell (SSH)
[RFC6242]. The NETCONF access control model [RFC6536] provides the
means to restrict access for particular NETCONF users to a
preconfigured subset of all available NETCONF protocol operations and
content.
The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement
secure transport is TLS [RFC5246]. The RESTCONF protocol uses the
NETCONF access control model [RFC6536], which provides the means to
restrict access for particular RESTCONF users to a preconfigured
subset of all available RESTCONF protocol operations and content.
This section provides security considerations for the resources
defined by the RESTCONF protocol. Security considerations for HTTPS
are defined in [RFC7230]. Aside from the "ietf-restconf-monitoring"
module (Section 9) and the "ietf-yang-library" module (Section 10),
RESTCONF does not specify which YANG modules a server needs to
support. Security considerations for the other modules manipulated
by RESTCONF can be found in the documents defining those YANG
modules.
Configuration information is by its very nature sensitive. Its
transmission in the clear and without integrity checking leaves
devices open to classic eavesdropping and false data injection
Bierman, et al. Standards Track [Page 99]
RFC 8040 RESTCONF January 2017
attacks. Configuration information often contains passwords, user
names, service descriptions, and topological information, all of
which are sensitive. There are many patterns of attack that have
been observed through operational practice with existing management
interfaces. It would be wise for implementers to research them and
take them into account when implementing this protocol.
Different environments may well allow different rights prior to, and
then after, authentication. When a RESTCONF operation is not
properly authorized, the RESTCONF server MUST return a "401
Unauthorized" status-line. Note that authorization information can
be exchanged in the form of configuration information, which is all
the more reason to ensure the security of the connection. Note that
it is possible for a client to detect configuration changes in data
resources it is not authorized to access by monitoring changes in the
"ETag" and "Last-Modified" header fields returned by the server for
the datastore resource.
A RESTCONF server implementation SHOULD attempt to prevent system
disruption due to excessive resource consumption required to fulfill
edit requests via the POST, PUT, and PATCH methods. On such an
implementation, it may be possible to construct an attack that
attempts to consume all available memory or other resource types.
13. References
13.1. Normative References
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
DOI 10.17487/RFC2046, November 1996,
.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
.
[RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
IETF URN Sub-namespace for Registered Protocol
Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553,
June 2003, .
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004,
.
Bierman, et al. Standards Track [Page 100]
RFC 8040 RESTCONF January 2017
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
.
[RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
.
[RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, DOI 10.17487/RFC5789, March 2010,
.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010,
.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
.
Bierman, et al. Standards Track [Page 101]
RFC 8040 RESTCONF January 2017
[RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for
NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011,
.
[RFC6415] Hammer-Lahav, E., Ed., and B. Cook, "Web Host Metadata",
RFC 6415, DOI 10.17487/RFC6415, October 2011,
.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536,
DOI 10.17487/RFC6536, March 2012,
.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012,
.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6991, DOI 10.17487/RFC6991, July 2013,
.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159,
March 2014, .
[RFC7230] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext
Transfer Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
.
[RFC7231] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext
Transfer Protocol (HTTP/1.1): Semantics and Content",
RFC 7231, DOI 10.17487/RFC7231, June 2014,
.
[RFC7232] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext
Transfer Protocol (HTTP/1.1): Conditional Requests",
RFC 7232, DOI 10.17487/RFC7232, June 2014,
.
[RFC7235] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext
Transfer Protocol (HTTP/1.1): Authentication", RFC 7235,
DOI 10.17487/RFC7235, June 2014,
.
Bierman, et al. Standards Track [Page 102]
RFC 8040 RESTCONF January 2017
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190,
RFC 7320, DOI 10.17487/RFC7320, July 2014,
.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525,
May 2015, .
[RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the
NETCONF Protocol over Transport Layer Security (TLS) with
Mutual X.509 Authentication", RFC 7589,
DOI 10.17487/RFC7589, June 2015,
.
[RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
.
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
RFC 7951, DOI 10.17487/RFC7951, August 2016,
.
[RFC7952] Lhotka, L., "Defining and Using Metadata with YANG",
RFC 7952, DOI 10.17487/RFC7952, August 2016,
.
[W3C.REC-eventsource-20150203]
Hickson, I., "Server-Sent Events", World Wide Web
Consortium Recommendation REC-eventsource-20150203,
February 2015,
.
Bierman, et al. Standards Track [Page 103]
RFC 8040 RESTCONF January 2017
[W3C.REC-xml-20081126]
Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E.,
and F. Yergeau, "Extensible Markup Language (XML) 1.0
(Fifth Edition)", World Wide Web Consortium Recommendation
REC-xml-20081126, November 2008,
.
[XPath] Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Recommendation
REC-xpath-19991116, November 1999,
.
13.2. Informative References
[REST-Dissertation]
Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
DOI 10.17487/RFC2818, May 2000,
.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008,
.
[TLS1.3] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", Work in Progress, draft-ietf-tls-tls13-18,
October 2016.
[YANG-Patch]
Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
Media Type", Work in Progress,
draft-ietf-netconf-yang-patch-14, November 2016.
Bierman, et al. Standards Track [Page 104]
RFC 8040 RESTCONF January 2017
Appendix A. Example YANG Module
The example YANG module used in this document represents a simple
media jukebox interface.
YANG tree diagram for the "example-jukebox" module:
+--rw jukebox!
+--rw library
| +--rw artist* [name]
| | +--rw name string
| | +--rw album* [name]
| | +--rw name string
| | +--rw genre? identityref
| | +--rw year? uint16
| | +--rw admin
| | | +--rw label? string
| | | +--rw catalogue-number? string
| | +--rw song* [name]
| | +--rw name string
| | +--rw location string
| | +--rw format? string
| | +--rw length? uint32
| +--ro artist-count? uint32
| +--ro album-count? uint32
| +--ro song-count? uint32
+--rw playlist* [name]
| +--rw name string
| +--rw description? string
| +--rw song* [index]
| +--rw index uint32
| +--rw id instance-identifier
+--rw player
+--rw gap? decimal64
rpcs:
+---x play
+--ro input
+--ro playlist string
+--ro song-number uint32
Bierman, et al. Standards Track [Page 105]
RFC 8040 RESTCONF January 2017
A.1. "example-jukebox" YANG Module
module example-jukebox {
namespace "http://example.com/ns/example-jukebox";
prefix "jbox";
organization "Example, Inc.";
contact "support at example.com";
description "Example Jukebox Data Model Module.";
revision "2016-08-15" {
description "Initial version.";
reference "example.com document 1-4673.";
}
identity genre {
description
"Base for all genre types.";
}
// abbreviated list of genre classifications
identity alternative {
base genre;
description
"Alternative music.";
}
identity blues {
base genre;
description
"Blues music.";
}
identity country {
base genre;
description
"Country music.";
}
identity jazz {
base genre;
description
"Jazz music.";
}
identity pop {
base genre;
description
"Pop music.";
}
Bierman, et al. Standards Track [Page 106]
RFC 8040 RESTCONF January 2017
identity rock {
base genre;
description
"Rock music.";
}
container jukebox {
presence
"An empty container indicates that the jukebox
service is available.";
description
"Represents a 'jukebox' resource, with a library, playlists,
and a 'play' operation.";
container library {
description
"Represents the 'jukebox' library resource.";
list artist {
key name;
description
"Represents one 'artist' resource within the
'jukebox' library resource.";
leaf name {
type string {
length "1 .. max";
}
description
"The name of the artist.";
}
list album {
key name;
description
"Represents one 'album' resource within one
'artist' resource, within the jukebox library.";
leaf name {
type string {
length "1 .. max";
}
description
"The name of the album.";
}
Bierman, et al. Standards Track [Page 107]
RFC 8040 RESTCONF January 2017
leaf genre {
type identityref { base genre; }
description
"The genre identifying the type of music on
the album.";
}
leaf year {
type uint16 {
range "1900 .. max";
}
description
"The year the album was released.";
}
container admin {
description
"Administrative information for the album.";
leaf label {
type string;
description
"The label that released the album.";
}
leaf catalogue-number {
type string;
description
"The album's catalogue number.";
}
}
list song {
key name;
description
"Represents one 'song' resource within one
'album' resource, within the jukebox library.";
leaf name {
type string {
length "1 .. max";
}
description
"The name of the song.";
}
Bierman, et al. Standards Track [Page 108]
RFC 8040 RESTCONF January 2017
leaf location {
type string;
mandatory true;
description
"The file location string of the
media file for the song.";
}
leaf format {
type string;
description
"An identifier string for the media type
for the file associated with the
'location' leaf for this entry.";
}
leaf length {
type uint32;
units "seconds";
description
"The duration of this song in seconds.";
}
} // end list 'song'
} // end list 'album'
} // end list 'artist'
leaf artist-count {
type uint32;
units "artists";
config false;
description
"Number of artists in the library.";
}
leaf album-count {
type uint32;
units "albums";
config false;
description
"Number of albums in the library.";
}
leaf song-count {
type uint32;
units "songs";
config false;
description
"Number of songs in the library.";
}
} // end library
Bierman, et al. Standards Track [Page 109]
RFC 8040 RESTCONF January 2017
list playlist {
key name;
description
"Example configuration data resource.";
leaf name {
type string;
description
"The name of the playlist.";
}
leaf description {
type string;
description
"A comment describing the playlist.";
}
list song {
key index;
ordered-by user;
description
"Example nested configuration data resource.";
leaf index { // not really needed
type uint32;
description
"An arbitrary integer index for this playlist song.";
}
leaf id {
type instance-identifier;
mandatory true;
description
"Song identifier. Must identify an instance of
/jukebox/library/artist/album/song/name.";
}
}
}
Bierman, et al. Standards Track [Page 110]
RFC 8040 RESTCONF January 2017
container player {
description
"Represents the jukebox player resource.";
leaf gap {
type decimal64 {
fraction-digits 1;
range "0.0 .. 2.0";
}
units "tenths of seconds";
description
"Time gap between each song.";
}
}
}
rpc play {
description
"Control function for the jukebox player.";
input {
leaf playlist {
type string;
mandatory true;
description
"The playlist name.";
}
leaf song-number {
type uint32;
mandatory true;
description
"Song number in playlist to play.";
}
}
}
}
Bierman, et al. Standards Track [Page 111]
RFC 8040 RESTCONF January 2017
Appendix B. RESTCONF Message Examples
The examples within this document use the normative YANG module
"ietf-restconf" as defined in Section 8 and the non-normative example
YANG module "example-jukebox" as defined in Appendix A.1.
This section shows some typical RESTCONF message exchanges.
B.1. Resource Retrieval Examples
B.1.1. Retrieve the Top-Level API Resource
The client starts by retrieving the RESTCONF root resource:
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
Bierman, et al. Standards Track [Page 112]
RFC 8040 RESTCONF January 2017
The server might respond as follows:
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
The client may then retrieve the top-level API resource, using the
root resource "/restconf".
GET /restconf HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"ietf-restconf:restconf" : {
"data" : {},
"operations" : {},
"yang-library-version" : "2016-06-21"
}
}
To request that the response content be encoded in XML, the "Accept"
header can be used, as in this example request:
GET /restconf HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
Bierman, et al. Standards Track [Page 113]
RFC 8040 RESTCONF January 2017
The server will return the same conceptual data either way, which
might be as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+xml
2016-06-21
B.1.2. Retrieve the Server Module Information
It is possible that the YANG library module will change over time.
The client can retrieve the revision date of the "ietf-yang-library"
module supported by the server from the API resource, as described in
the previous section.
In this example, the client is retrieving the module information from
the server in JSON format:
GET /restconf/data/ietf-yang-library:modules-state HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Bierman, et al. Standards Track [Page 114]
RFC 8040 RESTCONF January 2017
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Last-Modified: Thu, 26 Jan 2017 14:00:14 GMT
Content-Type: application/yang-data+json
{
"ietf-yang-library:modules-state" : {
"module-set-id" : "5479120c17a619545ea6aff7aa19838b036ebbd7",
"module" : [
{
"name" : "foo",
"revision" : "2012-01-02",
"schema" : "https://example.com/modules/foo/2012-01-02",
"namespace" : "http://example.com/ns/foo",
"feature" : [ "feature1", "feature2" ],
"deviation" : [
{
"name" : "foo-dev",
"revision" : "2012-02-16"
}
],
"conformance-type" : "implement"
},
{
"name" : "ietf-yang-library",
"revision" : "2016-06-21",
"schema" : "https://example.com/modules/\
ietf-yang-library/2016-06-21",
"namespace" :
"urn:ietf:params:xml:ns:yang:ietf-yang-library",
"conformance-type" : "implement"
},
{
"name" : "foo-types",
"revision" : "2012-01-05",
"schema" :
"https://example.com/modules/foo-types/2012-01-05",
"namespace" : "http://example.com/ns/foo-types",
"conformance-type" : "import"
},
Bierman, et al. Standards Track [Page 115]
RFC 8040 RESTCONF January 2017
{
"name" : "bar",
"revision" : "2012-11-05",
"schema" : "https://example.com/modules/bar/2012-11-05",
"namespace" : "http://example.com/ns/bar",
"feature" : [ "bar-ext" ],
"conformance-type" : "implement",
"submodule" : [
{
"name" : "bar-submod1",
"revision" : "2012-11-05",
"schema" :
"https://example.com/modules/bar-submod1/2012-11-05"
},
{
"name" : "bar-submod2",
"revision" : "2012-11-05",
"schema" :
"https://example.com/modules/bar-submod2/2012-11-05"
}
]
}
]
}
}
Bierman, et al. Standards Track [Page 116]
RFC 8040 RESTCONF January 2017
B.1.3. Retrieve the Server Capability Information
In this example, the client is retrieving the capability information
from the server in XML format, and the server supports all of the
RESTCONF query parameters, plus one vendor parameter:
GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
capabilities HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Last-Modified: Thu, 26 Jan 2017 16:00:14 GMT
Content-Type: application/yang-data+xml
\
urn:ietf:params:restconf:capability:defaults:1.0?\
basic-mode=explicit\
\
urn:ietf:params:restconf:capability:with-defaults:1.0\
\
urn:ietf:params:restconf:capability:depth:1.0\
\
urn:ietf:params:restconf:capability:fields:1.0\
\
urn:ietf:params:restconf:capability:filter:1.0\
\
urn:ietf:params:restconf:capability:start-time:1.0\
\
urn:ietf:params:restconf:capability:stop-time:1.0\
\
http://example.com/capabilities/myparam\
Bierman, et al. Standards Track [Page 117]
RFC 8040 RESTCONF January 2017
B.2. Data Resource and Datastore Resource Examples
B.2.1. Create New Data Resources
To create a new "artist" resource within the "library" resource, the
client might send the following request:
POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{
"example-jukebox:artist" : [
{
"name" : "Foo Fighters"
}
]
}
If the resource is created, the server might respond as follows:
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/library/artist=Foo%20Fighters
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b3830f23a4c"
Bierman, et al. Standards Track [Page 118]
RFC 8040 RESTCONF January 2017
To create a new "album" resource for this artist within the "jukebox"
resource, the client might send the following request:
POST /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
Wasting Light
2011
If the resource is created, the server might respond as follows:
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/library/artist=Foo%20Fighters/\
album=Wasting%20Light
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b8389233a4c"
B.2.2. Detect Datastore Resource Entity-Tag Change
In this example, the server just supports the datastore last-changed
timestamp. Assume that the client has cached the "Last-Modified"
header from the response to the previous request. This value is used
as in the "If-Unmodified-Since" header in the following request to
patch an "album" list entry with a key value of "Wasting Light".
Only the "genre" field is being updated.
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light/\
genre HTTP/1.1
Host: example.com
If-Unmodified-Since: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
{ "example-jukebox:genre" : "example-jukebox:alternative" }
Bierman, et al. Standards Track [Page 119]
RFC 8040 RESTCONF January 2017
In this example, the datastore resource has changed since the time
specified in the "If-Unmodified-Since" header. The server might
respond as follows:
HTTP/1.1 412 Precondition Failed
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 19:41:00 GMT
ETag: "b34aed893a4c"
Bierman, et al. Standards Track [Page 120]
RFC 8040 RESTCONF January 2017
B.2.3. Edit a Datastore Resource
In this example, assume that there is a top-level data resource named
"system" from the example-system module, and this container has a
child leaf called "enable-jukebox-streaming":
container system {
leaf enable-jukebox-streaming {
type boolean;
}
}
In this example, PATCH is used by the client to modify two top-level
resources at once, in order to enable jukebox streaming and add an
"album" sub-resource to each of two "artist" resources:
PATCH /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
true
Foo Fighters
One by One
2012
Nick Cave and the Bad Seeds
Tender Prey
1988
Bierman, et al. Standards Track [Page 121]
RFC 8040 RESTCONF January 2017
B.2.4. Replace a Datastore Resource
In this example, the entire configuration datastore contents are
being replaced. Any child nodes not present in the element
but present in the server will be deleted.
PUT /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
Foo Fighters
One by One
2012
Nick Cave and the Bad Seeds
Tender Prey
1988
B.2.5. Edit a Data Resource
In this example, the client modifies one data node by adding an
"album" sub-resource by sending a PATCH for the data resource:
PATCH /restconf/data/example-jukebox:jukebox/library/\
artist=Nick%20Cave%20and%20the%20Bad%20Seeds HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
Nick Cave and the Bad Seeds
The Good Son
1990
Bierman, et al. Standards Track [Page 122]
RFC 8040 RESTCONF January 2017
B.3. Query Parameter Examples
B.3.1. "content" Parameter
The "content" parameter is used to select the types of data child
resources (configuration and/or non-configuration) that are returned
by the server for a GET method request.
In this example, a simple YANG list is used that has configuration
and non-configuration child resources.
container events {
list event {
key name;
leaf name { type string; }
leaf description { type string; }
leaf event-count {
type uint32;
config false;
}
}
}
Bierman, et al. Standards Track [Page 123]
RFC 8040 RESTCONF January 2017
Example 1: content=all
To retrieve all of the child resources, the "content" parameter is
set to "all", or omitted, since this is the default value. The
client might send the following:
GET /restconf/data/example-events:events?\
content=all HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-events:events" : {
"event" : [
{
"name" : "interface-up",
"description" : "Interface up notification count",
"event-count" : 42
},
{
"name" : "interface-down",
"description" : "Interface down notification count",
"event-count" : 4
}
]
}
}
Bierman, et al. Standards Track [Page 124]
RFC 8040 RESTCONF January 2017
Example 2: content=config
To retrieve only the configuration child resources, the "content"
parameter is set to "config". Note that the "ETag" and
"Last-Modified" headers are only returned if the "content" parameter
value is "config".
GET /restconf/data/example-events:events?\
content=config HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 16:45:20 GMT
ETag: "eeeada438af"
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-events:events" : {
"event" : [
{
"name" : "interface-up",
"description" : "Interface up notification count"
},
{
"name" : "interface-down",
"description" : "Interface down notification count"
}
]
}
}
Bierman, et al. Standards Track [Page 125]
RFC 8040 RESTCONF January 2017
Example 3: content=nonconfig
To retrieve only the non-configuration child resources, the "content"
parameter is set to "nonconfig". Note that configuration ancestors
(if any) and list key leafs (if any) are also returned. The client
might send the following:
GET /restconf/data/example-events:events?\
content=nonconfig HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-events:events" : {
"event" : [
{
"name" : "interface-up",
"event-count" : 42
},
{
"name" : "interface-down",
"event-count" : 4
}
]
}
}
B.3.2. "depth" Parameter
The "depth" parameter is used to limit the number of levels of child
resources that are returned by the server for a GET method request.
The "depth" parameter starts counting levels at the level of the
target resource that is specified, so that a depth level of "1"
includes just the target resource level itself. A depth level of "2"
includes the target resource level and its child nodes.
Bierman, et al. Standards Track [Page 126]
RFC 8040 RESTCONF January 2017
This example shows how different values of the "depth" parameter
would affect the reply content for the retrieval of the top-level
"jukebox" data resource.
Example 1: depth=unbounded
To retrieve all of the child resources, the "depth" parameter is not
present or is set to the default value "unbounded".
GET /restconf/data/example-jukebox:jukebox?\
depth=unbounded HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-jukebox:jukebox" : {
"library" : {
"artist" : [
{
"name" : "Foo Fighters",
"album" : [
{
"name" : "Wasting Light",
"genre" : "example-jukebox:alternative",
"year" : 2011,
"song" : [
{
"name" : "Wasting Light",
"location" :
"/media/foo/a7/wasting-light.mp3",
"format" : "MP3",
"length" : 286
},
Bierman, et al. Standards Track [Page 127]
RFC 8040 RESTCONF January 2017
{
"name" : "Rope",
"location" : "/media/foo/a7/rope.mp3",
"format" : "MP3",
"length" : 259
}
]
}
]
}
]
},
"playlist" : [
{
"name" : "Foo-One",
"description" : "example playlist 1",
"song" : [
{
"index" : 1,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Rope']"
},
{
"index" : 2,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']"
}
]
}
],
"player" : {
"gap" : 0.5
}
}
}
Bierman, et al. Standards Track [Page 128]
RFC 8040 RESTCONF January 2017
Example 2: depth=1
To determine if one or more resource instances exist for a given
target resource, the value "1" is used.
GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-jukebox:jukebox" : {}
}
Bierman, et al. Standards Track [Page 129]
RFC 8040 RESTCONF January 2017
Example 3: depth=3
To limit the depth level to the target resource plus two child
resource layers, the value "3" is used.
GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-jukebox:jukebox" : {
"library" : {
"artist" : {}
},
"playlist" : [
{
"name" : "Foo-One",
"description" : "example playlist 1",
"song" : {}
}
],
"player" : {
"gap" : 0.5
}
}
}
B.3.3. "fields" Parameter
In this example, the client is retrieving the datastore resource in
JSON format, but retrieving only the "modules-state/module" list, and
only the "name" and "revision" nodes from each list entry. Note that
the top node returned by the server matches the target resource node
(which is "data" in this example). The "module-set-id" leaf is not
returned because it is not selected in the fields expression.
Bierman, et al. Standards Track [Page 130]
RFC 8040 RESTCONF January 2017
GET /restconf/data?fields=ietf-yang-library:modules-state/\
module(name;revision) HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"ietf-restconf:data" : {
"ietf-yang-library:modules-state" : {
"module" : [
{
"name" : "example-jukebox",
"revision" : "2016-08-15"
},
{
"name" : "ietf-inet-types",
"revision" : "2013-07-15"
},
{
"name" : "ietf-restconf-monitoring",
"revision" : "2017-01-26"
},
{
"name" : "ietf-yang-library",
"revision" : "2016-06-21"
},
{
"name" : "ietf-yang-types",
"revision" : "2013-07-15"
}
]
}
}
}
Bierman, et al. Standards Track [Page 131]
RFC 8040 RESTCONF January 2017
B.3.4. "insert" Parameter
In this example, a new first song entry in the "Foo-One" playlist is
being created.
Request from client:
POST /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One?insert=first HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{
"example-jukebox:song" : [
{
"index" : 1,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Rope']"
}
]
}
Response from server:
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/playlist=Foo-One/song=1
ETag: "eeeada438af"
Bierman, et al. Standards Track [Page 132]
RFC 8040 RESTCONF January 2017
B.3.5. "point" Parameter
In this example, the client is inserting a new song entry in the
"Foo-One" playlist after the first song.
Request from client:
POST /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One?insert=after&point=\
%2Fexample-jukebox%3Ajukebox\
%2Fplaylist%3DFoo-One%2Fsong%3D1 HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{
"example-jukebox:song" : [
{
"index" : 2,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']"
}
]
}
Response from server:
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/playlist=Foo-One/song=2
ETag: "abcada438af"
Bierman, et al. Standards Track [Page 133]
RFC 8040 RESTCONF January 2017
B.3.6. "filter" Parameter
The following URIs show some examples of notification filter
specifications:
// filter = /event/event-class='fault'
GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault'
// filter = /event/severity<=4
GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4
// filter = /linkUp|/linkDown
GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown
// filter = /*/reporting-entity/card!='Ethernet0'
GET /streams/NETCONF?\
filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0'
// filter = /*/email-addr[contains(.,'company.com')]
GET /streams/critical-syslog?\
filter=%2F*%2Femail-addr[contains(.%2C'company.com')]
// Note: The module name is used as the prefix.
// filter = (/example-mod:event1/name='joe' and
// /example-mod:event1/status='online')
GET /streams/NETCONF?\
filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and\
%20%2Fexample-mod%3Aevent1%2Fstatus%3D'online')
// To get notifications from just two modules (e.g., m1 + m2)
// filter=(/m1:* or /m2:*)
GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*)
B.3.7. "start-time" Parameter
The following URI shows an example of the "start-time" query
parameter:
// start-time = 2014-10-25T10:02:00Z
GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z
Bierman, et al. Standards Track [Page 134]
RFC 8040 RESTCONF January 2017
B.3.8. "stop-time" Parameter
The following URI shows an example of the "stop-time" query
parameter:
// start-time = 2014-10-25T10:02:00Z
// stop-time = 2014-10-25T12:31:00Z
GET /mystreams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z\
&stop-time=2014-10-25T12%3A31%3A00Z
B.3.9. "with-defaults" Parameter
Assume that the server implements the module "example" defined in
Appendix A.1 of [RFC6243], and assume that the server's datastore is
as defined in Appendix A.2 of [RFC6243].
If the server's "basic-mode" parameter in the "defaults" protocol
capability URI (Section 9.1.2) is "trim", the following request for
interface "eth1" might be as follows:
Without query parameter:
GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"example:interface" : [
{
"name" : "eth1",
"status" : "up"
}
]
}
Note that the "mtu" leaf is missing because it is set to the default
"1500", and the server's default-handling "basic-mode" parameter is
"trim".
Bierman, et al. Standards Track [Page 135]
RFC 8040 RESTCONF January 2017
With query parameter:
GET /restconf/data/example:interfaces/interface=eth1\
?with-defaults=report-all HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"example:interface" : [
{
"name" : "eth1",
"mtu" : 1500,
"status" : "up"
}
]
}
Note that the server returns the "mtu" leaf because the "report-all"
mode was requested with the "with-defaults" query parameter.
Bierman, et al. Standards Track [Page 136]
RFC 8040 RESTCONF January 2017
Acknowledgements
The authors would like to thank the following people for their
contributions to this document: Ladislav Lhotka, Juergen
Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford.
The authors would like to thank the following people for their
excellent technical reviews of this document: Mehmet Ersue, Mahesh
Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka,
Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint
Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise,
Dale Worley, and Lionel Morand.
Contributions to this material by Andy Bierman are based upon work
supported by the United States Army, Space & Terrestrial
Communications Directorate (S&TCD) under Contract
No. W15P7T-13-C-A616. Any opinions, findings, and conclusions or
recommendations expressed in this material are those of the author(s)
and do not necessarily reflect the views of the S&TCD.
Authors' Addresses
Andy Bierman
YumaWorks
Email: andy@yumaworks.com
Martin Bjorklund
Tail-f Systems
Email: mbj@tail-f.com
Kent Watsen
Juniper Networks
Email: kwatsen@juniper.net
Bierman, et al. Standards Track [Page 137]
gemini://gemini.bortzmeyer.org/rfc-mirror/rfc8040.txt -- Leo's gemini proxy
-- Connecting to gemini.bortzmeyer.org:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/plain
-- Response ended
-- Page fetched on Mon May 6 14:23:41 2024