RFC 8040
RESTCONF Protocol
Internet Engineering Task Force (IETF) A. Bierman Request for Comments: 8040 YumaWorks Category: Standards Track M. Bjorklund ISSN: 2070-1721 Tail-f Systems K. Watsen Juniper Networks January 2017 RESTCONF ProtocolAbstract
This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF). Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc8040. Copyright Notice Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Table of Contents
1. Introduction ....................................................5 1.1. Terminology ................................................5 1.1.1. NETCONF .............................................6 1.1.2. HTTP ................................................6 1.1.3. YANG ................................................7 1.1.4. NETCONF Notifications ...............................7 1.1.5. Terms ...............................................8 1.1.6. URI Template and Examples ..........................10 1.1.7. Tree Diagrams ......................................11 1.2. Subset of NETCONF Functionality ...........................11 1.3. Data-Model-Driven API .....................................12 1.4. Coexistence with NETCONF ..................................13 1.5. RESTCONF Extensibility ....................................14 2. Transport Protocol .............................................15 2.1. Integrity and Confidentiality .............................15 2.2. HTTPS with X.509v3 Certificates ...........................16 2.3. Certificate Validation ....................................16 2.4. Authenticated Server Identity .............................16 2.5. Authenticated Client Identity .............................16 3. Resources ......................................................17 3.1. Root Resource Discovery ...................................18 3.2. RESTCONF Media Types ......................................20 3.3. API Resource ..............................................20 3.3.1. {+restconf}/data ...................................21 3.3.2. {+restconf}/operations .............................22 3.3.3. {+restconf}/yang-library-version ...................22 3.4. Datastore Resource ........................................23 3.4.1. Edit Collision Prevention ..........................23 3.5. Data Resource .............................................24 3.5.1. Timestamp ..........................................25 3.5.2. Entity-Tag .........................................25 3.5.3. Encoding Data Resource Identifiers in the Request URI ........................................26 3.5.4. Default Handling ...................................29 3.6. Operation Resource ........................................30 3.6.1. Encoding Operation Resource Input Parameters .......31 3.6.2. Encoding Operation Resource Output Parameters ......36 3.6.3. Encoding Operation Resource Errors .................38 3.7. Schema Resource ...........................................40 3.8. Event Stream Resource .....................................41 3.9. "errors" YANG Data Template ...............................41 4. RESTCONF Methods ...............................................42 4.1. OPTIONS ...................................................43 4.2. HEAD ......................................................43 4.3. GET .......................................................43 4.4. POST ......................................................45
4.4.1. Create Resource Mode ...............................45
4.4.2. Invoke Operation Mode ..............................47
4.5. PUT .......................................................48
4.6. PATCH .....................................................50
4.6.1. Plain Patch ........................................50
4.7. DELETE ....................................................51
4.8. Query Parameters ..........................................52
4.8.1. The "content" Query Parameter ......................54
4.8.2. The "depth" Query Parameter ........................54
4.8.3. The "fields" Query Parameter .......................55
4.8.4. The "filter" Query Parameter .......................56
4.8.5. The "insert" Query Parameter .......................57
4.8.6. The "point" Query Parameter ........................57
4.8.7. The "start-time" Query Parameter ...................58
4.8.8. The "stop-time" Query Parameter ....................58
4.8.9. The "with-defaults" Query Parameter ................59
5. Messages .......................................................60
5.1. Request URI Structure .....................................61
5.2. Message Encoding ..........................................62
5.3. RESTCONF Metadata .........................................63
5.3.1. XML Metadata Encoding Example ......................64
5.3.2. JSON Metadata Encoding Example .....................65
5.4. Return Status .............................................65
5.5. Message Caching ...........................................66
6. Notifications ..................................................66
6.1. Server Support ............................................66
6.2. Event Streams .............................................67
6.3. Subscribing to Receive Notifications ......................68
6.3.1. NETCONF Event Stream ...............................70
6.4. Receiving Event Notifications .............................70
7. Error Reporting ................................................73
7.1. Error Response Message ....................................75
8. RESTCONF Module ................................................79
9. RESTCONF Monitoring ............................................85
9.1. restconf-state/capabilities ...............................86
9.1.1. Query Parameter URIs ...............................87
9.1.2. The "defaults" Protocol Capability URI .............87
9.2. restconf-state/streams ....................................88
9.3. RESTCONF Monitoring Module ................................89
10. YANG Module Library ...........................................93
10.1. modules-state/module .....................................93
11. IANA Considerations ...........................................94
11.1. The "restconf" Relation Type .............................94
11.2. Registrations for New URIs and YANG Modules ..............94
11.3. Media Types ..............................................95
11.3.1. Media Type "application/yang-data+xml" ............95
11.3.2. Media Type "application/yang-data+json" ...........96
11.4. RESTCONF Capability URNs .................................97
11.5. Registration of "restconf" URN Sub-namespace .............98
12. Security Considerations .......................................99
13. References ...................................................100
13.1. Normative References ....................................100
13.2. Informative References ..................................104
Appendix A. Example YANG Module ..................................105
A.1. "example-jukebox" YANG Module .............................106
Appendix B. RESTCONF Message Examples ............................112
B.1. Resource Retrieval Examples ...............................112
B.1.1. Retrieve the Top-Level API Resource ...................112
B.1.2. Retrieve the Server Module Information ................114
B.1.3. Retrieve the Server Capability Information ............117
B.2. Data Resource and Datastore Resource Examples .............118
B.2.1. Create New Data Resources .............................118
B.2.2. Detect Datastore Resource Entity-Tag Change ...........119
B.2.3. Edit a Datastore Resource .............................121
B.2.4. Replace a Datastore Resource ..........................122
B.2.5. Edit a Data Resource ..................................122
B.3. Query Parameter Examples ..................................123
B.3.1. "content" Parameter ...................................123
B.3.2. "depth" Parameter .....................................126
B.3.3. "fields" Parameter ....................................130
B.3.4. "insert" Parameter ....................................132
B.3.5. "point" Parameter .....................................133
B.3.6. "filter" Parameter ....................................134
B.3.7. "start-time" Parameter ................................134
B.3.8. "stop-time" Parameter .................................135
B.3.9. "with-defaults" Parameter .............................135
Acknowledgements .................................................137
Authors' Addresses ...............................................137
1. Introduction
There is a need for standard mechanisms to allow Web applications to access the configuration data, state data, data-model-specific Remote Procedure Call (RPC) operations, and event notifications within a networking device, in a modular and extensible manner. This document defines a protocol based on HTTP [RFC7230] called "RESTCONF", for configuring data defined in YANG version 1 [RFC6020] or YANG version 1.1 [RFC7950], using the datastore concepts defined in the Network Configuration Protocol (NETCONF) [RFC6241]. NETCONF defines configuration datastores and a set of Create, Read, Update, Delete (CRUD) operations that can be used to access these datastores. NETCONF also defines a protocol for invoking these operations. The YANG language defines the syntax and semantics of datastore content, configuration, state data, RPC operations, and event notifications. RESTCONF uses HTTP methods to provide CRUD operations on a conceptual datastore containing YANG-defined data, which is compatible with a server that implements NETCONF datastores. If a RESTCONF server is co-located with a NETCONF server, then there are protocol interactions with the NETCONF protocol; these interactions are described in Section 1.4. The RESTCONF server MAY provide access to specific datastores using operation resources, as described in Section 3.6. The RESTCONF protocol does not specify any mandatory operation resources. The semantics of each operation resource determine if and how datastores are accessed. Configuration data and state data are exposed as resources that can be retrieved with the GET method. Resources representing configuration data can be modified with the DELETE, PATCH, POST, and PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] or JSON [RFC7159]. Data-model-specific RPC operations defined with the YANG "rpc" or "action" statements can be invoked with the POST method. Data-model- specific event notifications defined with the YANG "notification" statement can be accessed.1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
1.1.1. NETCONF
The following terms are defined in [RFC6241]: o candidate configuration datastore o configuration data o datastore o configuration datastore o running configuration datastore o startup configuration datastore o state data o user1.1.2. HTTP
The following terms are defined in [RFC3986]: o fragment o path o query The following terms are defined in [RFC7230]: o header field o message-body o request-line o request URI o status-line
The following terms are defined in [RFC7231]: o method o request o resource The following term is defined in [RFC7232]: o entity-tag1.1.3. YANG
The following terms are defined in [RFC7950]: o action o container o data node o key leaf o leaf o leaf-list o list o mandatory node o ordered-by user o presence container o RPC operation o top-level data node1.1.4. NETCONF Notifications
The following term is defined in [RFC5277]: o notification replay
1.1.5. Terms
The following terms are used within this document: o API resource: the resource that models the RESTCONF root resource and the sub-resources to access YANG-defined content. It is defined with the YANG data template named "yang-api" in the "ietf-restconf" module. o client: a RESTCONF client. o data resource: a resource that models a YANG data node. It is defined with YANG data definition statements. o datastore resource: the resource that models a programmatic interface using NETCONF datastore concepts. By default, RESTCONF methods access a unified view of the underlying datastore implementation on the server. It is defined as a sub-resource within the API resource. o edit operation: a RESTCONF operation on a data resource using either a POST, PUT, PATCH, or DELETE method. This is not the same as the NETCONF edit operation (i.e., one of the values for the "nc:operation" attribute: "create", "replace", "merge", "delete", or "remove"). o event stream resource: a resource that represents an SSE (Server-Sent Events) event stream. The content consists of text using the media type "text/event-stream", as defined by the SSE specification [W3C.REC-eventsource-20150203]. Event stream contents are described in Section 3.8. o media type: HTTP uses Internet media types [RFC2046] in the "Content-Type" and "Accept" header fields in order to provide open and extensible data typing and type negotiation. o NETCONF client: a client that implements the NETCONF protocol. Called "client" in [RFC6241]. o NETCONF server: a server that implements the NETCONF protocol. Called "server" in [RFC6241]. o operation: the conceptual RESTCONF operation for a message, derived from the HTTP method, request URI, header fields, and message-body.
o operation resource: a resource that models a data-model-specific
operation that is in turn defined with a YANG "rpc" or "action"
statement. It is invoked with the POST method.
o patch: a PATCH method on the target datastore or data resource.
The media type of the message-body content will identify the patch
type in use.
o plain patch: a specific media type for use with the PATCH method;
see Section 4.6.1. It can be used for simple "merge" edit
operations. It is specified by a request Content-Type of
"application/yang-data+xml" or "application/yang-data+json".
o query parameter: a parameter (and its value, if any), encoded
within the query component of the request URI.
o resource type: one of the RESTCONF resource classes defined in
this document. One of "api", "datastore", "data", "operation",
"schema", or "event stream".
o RESTCONF capability: an optional RESTCONF protocol feature that is
advertised by a particular server if the feature is supported on
that server. The feature is identified by an IANA-registered
NETCONF Capability URI and advertised with an entry in the
"capability" leaf-list defined in Section 9.3.
o RESTCONF client: a client that implements the RESTCONF protocol.
o RESTCONF server: a server that implements the RESTCONF protocol.
o retrieval request: a request using the GET or HEAD methods.
o schema resource: a resource that is used by the client to retrieve
a YANG schema with the GET method. It has a representation with
the media type "application/yang".
o server: a RESTCONF server.
o "stream" list: the set of data resource instances that describe
the event stream resources available from the server. This
information is defined in the "ietf-restconf-monitoring" module as
the "stream" list. It can be retrieved using the target resource
"{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/
stream". The "stream" list contains information about each
stream, such as the URL to retrieve the event stream data.
o stream resource: an event stream resource.
o target resource: the resource that is associated with a particular
message, identified by the "path" component of the request URI.
o yang-data extension: a YANG external statement that conforms to
the "yang-data" extension statement, found in Section 8. The
yang-data extension is used to define YANG data structures that
are meant to be used as YANG data templates. These data
structures are not intended to be implemented as part of a
configuration datastore or as an operational state within the
server, so normal YANG data definition statements cannot be used.
o YANG data template: a schema for modeling protocol message
components as conceptual data structures using YANG. This allows
the messages to be defined in an encoding-independent manner.
Each YANG data template is defined with the "yang-data" extension,
found in Section 8. Representations of instances conforming to a
particular YANG data template can be defined for YANG. The XML
representation is defined in YANG version 1.1 [RFC7950] and
supported with the "application/yang-data+xml" media type. The
JSON representation is defined in "JSON Encoding of Data Modeled
with YANG" [RFC7951] and supported with the
"application/yang-data+json" media type.
1.1.6. URI Template and Examples
Throughout this document, the URI template [RFC6570] syntax
"{+restconf}" is used to refer to the RESTCONF root resource outside
of an example. See Section 3.1 for details.
For simplicity, all of the examples in this document use "/restconf"
as the discovered RESTCONF API root path. Many of the examples
throughout the document are based on the "example-jukebox" YANG
module defined in Appendix A.1.
Many protocol header lines and message-body text within examples
throughout the document are split into multiple lines for display
purposes only. When a line ends with a backslash ("\") as the last
character, the line is wrapped for display purposes. It is to be
considered to be joined to the next line by deleting the backslash,
the following line break, and the leading whitespace of the
next line.
1.1.7. Tree Diagrams
A simplified graphical representation of the data model is used in this document. The meanings of the symbols in these diagrams are as follows: o Brackets "[" and "]" enclose list keys. o Abbreviations before data node names: "rw" means configuration data (read-write), "ro" means state data (read-only), and "x" means operation resource (executable). o Symbols after data node names: "?" means an optional node, "!" means a presence container, and "*" denotes a list and leaf-list. o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":"). o Ellipsis ("...") stands for contents of subtrees that are not shown.1.2. Subset of NETCONF Functionality
RESTCONF does not need to mirror the full functionality of the NETCONF protocol, but it does need to be compatible with NETCONF. RESTCONF achieves this by implementing a subset of the interaction capabilities provided by the NETCONF protocol -- for instance, by eliminating datastores and explicit locking. RESTCONF uses HTTP methods to implement the equivalent of NETCONF operations, enabling basic CRUD operations on a hierarchy of conceptual resources. The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data resources represented by YANG data models. These basic edit operations allow the running configuration to be altered by a RESTCONF client. RESTCONF is not intended to replace NETCONF, but rather to provide an HTTP interface that follows Representational State Transfer (REST) principles [REST-Dissertation] and is compatible with the NETCONF datastore model.
1.3. Data-Model-Driven API
RESTCONF combines the simplicity of HTTP with the predictability and automation potential of a schema-driven API. Knowing the YANG modules used by the server, a client can derive all management resource URLs and the proper structure of all RESTCONF requests and responses. This strategy obviates the need for responses provided by the server to contain Hypermedia as the Engine of Application State (HATEOAS) links, originally described in Roy Fielding's doctoral dissertation [REST-Dissertation], because the client can determine the links it needs from the YANG modules. RESTCONF utilizes the YANG library [RFC7895] to allow a client to discover the YANG module conformance information for the server, in case the client wants to use it. The server can optionally support the retrieval of the YANG modules it uses, as identified in its YANG library. See Section 3.7 for details. The URIs for data-model-specific RPC operations and datastore content are predictable, based on the YANG module definitions. The RESTCONF protocol operates on a conceptual datastore defined with the YANG data modeling language. The server lists each YANG module it supports using the "ietf-yang-library" YANG module defined in [RFC7895]. The server MUST implement the "ietf-yang-library" module, which MUST identify all of the YANG modules used by the server, in the "modules-state/module" list. The conceptual datastore contents, data-model-specific RPC operations, and event notifications are identified by this set of YANG modules. The classification of data as configuration data or non-configuration data is derived from the YANG "config" statement. Behavior related to the ordering of data is derived from the YANG "ordered-by" statement. Non-configuration data is also called "state data". The RESTCONF datastore editing model is simple and direct, similar to the behavior of the :writable-running capability in NETCONF. Each RESTCONF edit of a data resource within the datastore resource is activated upon successful completion of the edit.
1.4. Coexistence with NETCONF
RESTCONF can be implemented on a device that supports the NETCONF protocol. The following figure shows the system components if a RESTCONF server is co-located with a NETCONF server: +-----------+ +-----------------+ | Web app | <-------> | | +-----------+ RESTCONF | network device | | | +-----------+ | +-----------+ | | NETCONF | <-------> | | datastore | | | Client | NETCONF | | | | +-----------+ | +-----------+ | +-----------------+ The following figure shows the system components if a RESTCONF server is implemented in a device that does not have a NETCONF server: +-----------+ +-----------------+ | Web app | <-------> | | +-----------+ RESTCONF | network device | | | +-----------------+ There are interactions between the NETCONF protocol and RESTCONF protocol related to edit operations. It is possible that locks are in use on a RESTCONF server, even though RESTCONF cannot manipulate locks. In such a case, the RESTCONF protocol will not be granted write access to data resources within a datastore. If the NETCONF server supports :writable-running, all edits to configuration nodes in {+restconf}/data are performed in the running configuration datastore. The URI template "{+restconf}" is defined in Section 1.1.6. Otherwise, if the device supports :candidate, all edits to configuration nodes in {+restconf}/data are performed in the candidate configuration datastore. The candidate MUST be automatically committed to running immediately after each successful edit. Any edits from other sources that are in the candidate datastore will also be committed. If a confirmed commit procedure is in progress by any NETCONF client, then any new commit will act as the confirming commit. If the NETCONF server is expecting a
"persist-id" parameter to complete the confirmed commit procedure, then the RESTCONF edit operation MUST fail with a "409 Conflict" status-line. The error-tag "in-use" is used in this case. If the NETCONF server supports :startup, the RESTCONF server MUST automatically update the non-volatile startup configuration datastore, after the "running" datastore has been altered as a consequence of a RESTCONF edit operation. If a datastore that would be modified by a RESTCONF operation has an active lock from a NETCONF client, the RESTCONF edit operation MUST fail with a "409 Conflict" status-line. The error-tag value "in-use" is returned in this case.1.5. RESTCONF Extensibility
There are two extensibility mechanisms built into RESTCONF: o protocol version o optional capabilities This document defines version 1 of the RESTCONF protocol. If a future version of this protocol is defined, then that document will specify how the new version of RESTCONF is identified. It is expected that a different RESTCONF root resource will be used, which will be located using a different link relation (see Section 3.1). The server will advertise all protocol versions that it supports in its host-meta data. In this example, the server supports both RESTCONF version 1 and a fictitious version 2. The client might send the following: GET /.well-known/host-meta HTTP/1.1 Host: example.com Accept: application/xrd+xml
The server might respond as follows:
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
<Link rel='restconf2' href='/restconf2'/>
</XRD>
RESTCONF also supports a server-defined list of optional
capabilities, which are listed by a server using the
"ietf-restconf-monitoring" module defined in Section 9.3. This
document defines several query parameters in Section 4.8. Each
optional parameter has a corresponding capability URI, defined in
Section 9.1.1, that is advertised by the server if supported.
The "capability" leaf-list can identify any sort of server extension.
Currently, this extension mechanism is used to identify optional
query parameters that are supported, but it is not limited to that
purpose. For example, the "defaults" URI defined in Section 9.1.2
specifies a mandatory URI identifying server default-handling
behavior.
A new sub-resource type could be identified with a capability if it
is optional to implement. Mandatory protocol features and new
resource types require a new revision of the RESTCONF protocol.
(page 15 continued on part 2)
