Tech-invite3GPPspaceIETFspace
96959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8040

RESTCONF Protocol

Pages: 137
Proposed Standard
Errata
Updated by:  8527
Part 1 of 6 – Pages 1 to 15
None   None   Next

Top   ToC   RFC8040 - Page 1
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 Protocol

Abstract

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.
Top   ToC   RFC8040 - Page 2

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
Top   ToC   RFC8040 - Page 3
           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
Top   ToC   RFC8040 - Page 4
      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
Top   ToC   RFC8040 - Page 5

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].
Top   ToC   RFC8040 - Page 6

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 user

1.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
Top   ToC   RFC8040 - Page 7
   The following terms are defined in [RFC7231]:

   o  method

   o  request

   o  resource

   The following term is defined in [RFC7232]:

   o  entity-tag

1.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 node

1.1.4. NETCONF Notifications

The following term is defined in [RFC5277]: o notification replay
Top   ToC   RFC8040 - Page 8

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.
Top   ToC   RFC8040 - Page 9
   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.
Top   ToC   RFC8040 - Page 10
   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.
Top   ToC   RFC8040 - Page 11

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.
Top   ToC   RFC8040 - Page 12

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.
Top   ToC   RFC8040 - Page 13

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
Top   ToC   RFC8040 - Page 14
   "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
Top   ToC   RFC8040 - Page 15
   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)

Next Section