tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 8040

Proposed STD
Pages: 137
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: NETCONF

RESTCONF Protocol

Part 1 of 6, p. 1 to 15
None       Next Section

 


Top       ToC       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       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       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       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       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       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       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       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       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       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       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       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       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       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       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