Tech-invite3GPPspaceIETF RFCsSIP
93929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8040

RESTCONF Protocol

Pages: 137
Proposed Standard
Errata
Part 2 of 6 – Pages 15 to 41
First   Prev   Next

Top   ToC   RFC8040 - Page 15   prevText

2. Transport Protocol

2.1. Integrity and Confidentiality

HTTP [RFC7230] is an application-layer protocol that may be layered on any reliable transport-layer protocol. RESTCONF is defined on top of HTTP, but due to the sensitive nature of the information conveyed, RESTCONF requires that the transport-layer protocol provide both data integrity and confidentiality. A RESTCONF server MUST support the Transport Layer Security (TLS) protocol [RFC5246] and SHOULD adhere to [RFC7525]. The RESTCONF protocol MUST NOT be used over HTTP without using the TLS protocol. RESTCONF does not require a specific version of HTTP. However, it is RECOMMENDED that at least HTTP/1.1 [RFC7230] be supported by all implementations.
Top   ToC   RFC8040 - Page 16

2.2. HTTPS with X.509v3 Certificates

Given the nearly ubiquitous support for HTTP over TLS [RFC7230], RESTCONF implementations MUST support the "https" URI scheme, which has the IANA-assigned default port 443. RESTCONF servers MUST present an X.509v3-based certificate when establishing a TLS connection with a RESTCONF client. The use of X.509v3-based certificates is consistent with NETCONF over TLS [RFC7589].

2.3. Certificate Validation

The RESTCONF client MUST either (1) use X.509 certificate path validation [RFC5280] to verify the integrity of the RESTCONF server's TLS certificate or (2) match the server's TLS certificate with a certificate obtained by a trusted mechanism (e.g., a pinned certificate). If X.509 certificate path validation fails and the presented X.509 certificate does not match a certificate obtained by a trusted mechanism, the connection MUST be terminated, as described in Section 7.2.1 of [RFC5246].

2.4. Authenticated Server Identity

The RESTCONF client MUST check the identity of the server according to Section 3.1 of [RFC2818].

2.5. Authenticated Client Identity

The RESTCONF server MUST authenticate client access to any protected resource. If the RESTCONF client is not authenticated, the server SHOULD send an HTTP response with a "401 Unauthorized" status-line, as defined in Section 3.1 of [RFC7235]. The error-tag value "access-denied" is used in this case. To authenticate a client, a RESTCONF server SHOULD require authentication based on TLS client certificates (Section 7.4.6 of [RFC5246]). If certificate-based authentication is not feasible (e.g., because one cannot build the required PKI for clients), then HTTP authentication MAY be used. In the latter case, one of the HTTP authentication schemes defined in the "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry" (Section 5.1 in [RFC7235]) MUST be used. A server MAY also support the combination of both client certificates and an HTTP client authentication scheme, with the determination of how to process this combination left as an implementation decision.
Top   ToC   RFC8040 - Page 17
   The RESTCONF client identity derived from the authentication
   mechanism used is hereafter known as the "RESTCONF username" and
   subject to the NETCONF Access Control Model (NACM) [RFC6536].  When a
   client certificate is presented, the RESTCONF username MUST be
   derived using the algorithm defined in Section 7 of [RFC7589].  For
   all other cases, when HTTP authentication is used, the RESTCONF
   username MUST be provided by the HTTP authentication scheme used.

3. Resources

The RESTCONF protocol operates on a hierarchy of resources, starting with the top-level API resource itself (Section 3.1). Each resource represents a manageable component within the device. A resource can be considered as a collection of data and the set of allowed methods on that data. It can contain nested child resources. The child resource types and the methods allowed on them are specific to the data model. A resource has a representation associated with a media type identifier, as represented by the "Content-Type" header field in the HTTP response message. A resource has one or more representations, each associated with a different media type. When a representation of a resource is sent in an HTTP message, the associated media type is given in the "Content-Type" header. A resource can contain zero or more nested resources. A resource can be created and deleted independently of its parent resource, as long as the parent resource exists. The RESTCONF resources are accessed via a set of URIs defined in this document. The set of YANG modules supported by the server will determine the data-model-specific RPC operations, top-level data nodes, and event notification messages supported by the server. The RESTCONF protocol does not include a data resource discovery mechanism. Instead, the definitions within the YANG modules advertised by the server are used to construct an RPC operation or data resource identifier.
Top   ToC   RFC8040 - Page 18

3.1. Root Resource Discovery

In line with the best practices defined by [RFC7320], RESTCONF enables deployments to specify where the RESTCONF API is located. When first connecting to a RESTCONF server, a RESTCONF client MUST determine the root of the RESTCONF API. There MUST be exactly one "restconf" link relation returned by the device. The client discovers this by getting the "/.well-known/host-meta" resource ([RFC6415]) and using the <Link> element containing the "restconf" attribute: Example returning /restconf: 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'/> </XRD> After discovering the RESTCONF API root, the client MUST use this value as the initial part of the path in the request URI, in any subsequent request for a RESTCONF resource. In this example, the client would use the path "/restconf" as the RESTCONF root resource. Example returning /top/restconf: 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 19
   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='/top/restconf'/>
      </XRD>

   In this example, the client would use the path "/top/restconf" as the
   RESTCONF root resource.

   The client can now determine the operation resources supported by the
   server.  In this example, a custom "play" operation is supported:

   The client might send the following:

      GET /top/restconf/operations 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
      Last-Modified: Thu, 26 Jan 2017 16:00:14 GMT
      Content-Type: application/yang-data+json

      { "operations" : { "example-jukebox:play" : [null] } }

   If the Extensible Resource Descriptor (XRD) contains more than one
   link relation, then only the relation named "restconf" is relevant to
   this specification.

   Note that any given endpoint (host:port) can only support one
   RESTCONF server, due to the root resource discovery mechanism.  This
   limits the number of RESTCONF servers that can run concurrently on a
   host, since each server must use a different port.
Top   ToC   RFC8040 - Page 20

3.2. RESTCONF Media Types

The RESTCONF protocol defines two application-specific media types to identify representations of data that conforms to the schema for a particular YANG construct. This document defines media types for XML and JSON serialization of YANG data. Other documents MAY define other media types for different serializations of YANG data. The "application/yang-data+xml" media type is defined in Section 11.3.1. The "application/yang-data+json" media type is defined in Section 11.3.2.

3.3. API Resource

The API resource contains the RESTCONF root resource for the RESTCONF datastore and operation resources. It is the top-level resource located at {+restconf} and has the media type "application/yang-data+xml" or "application/yang-data+json". YANG tree diagram for an API resource: +---- {+restconf} +---- data | ... +---- operations? | ... +--ro yang-library-version string The "yang-api" YANG data template is defined using the "yang-data" extension in the "ietf-restconf" module, found in Section 8. It specifies the structure and syntax of the conceptual child resources within the API resource. The API resource can be retrieved with the GET method. The {+restconf} root resource name used in responses representing the root of the "ietf-restconf" module MUST identify the "ietf-restconf" YANG module. For example, a request to GET the root resource "/restconf" in JSON format will return a representation of the API resource named "ietf-restconf:restconf".
Top   ToC   RFC8040 - Page 21
   This resource has the following child resources:

        +----------------------+---------------------------------+
        | Child Resource       | Description                     |
        +----------------------+---------------------------------+
        | data                 | Contains all data resources     |
        | operations           | Data-model-specific operations  |
        | yang-library-version | "ietf-yang-library" module date |
        +----------------------+---------------------------------+

                           RESTCONF API Resource

3.3.1. {+restconf}/data

This mandatory resource represents the combined configuration and state data resources that can be accessed by a client. It cannot be created or deleted by the client. The datastore resource type is defined in Section 3.4. Example: This example request by the client would retrieve only the non-configuration data nodes that exist within the "library" resource, using the "content" query parameter (see Section 4.8.1). GET /restconf/data/example-jukebox:jukebox/library\ ?content=nonconfig 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 Content-Type: application/yang-data+xml <library xmlns="https://example.com/ns/example-jukebox"> <artist-count>42</artist-count> <album-count>59</album-count> <song-count>374</song-count> </library>
Top   ToC   RFC8040 - Page 22

3.3.2. {+restconf}/operations

This optional resource is a container that provides access to the data-model-specific RPC operations supported by the server. The server MAY omit this resource if no data-model-specific RPC operations are advertised. Any data-model-specific RPC operations defined in the YANG modules advertised by the server MUST be available as child nodes of this resource. The access point for each RPC operation is represented as an empty leaf. If an operation resource is retrieved, the empty leaf representation is returned by the server. Operation resources are defined in Section 3.6.

3.3.3. {+restconf}/yang-library-version

This mandatory leaf identifies the revision date of the "ietf-yang-library" YANG module that is implemented by this server. In the example that follows, the revision date for the module version found in [RFC7895] is used. Example: GET /restconf/yang-library-version 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 Content-Type: application/yang-data+xml <yang-library-version xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">\ 2016-06-21\ </yang-library-version>
Top   ToC   RFC8040 - Page 23

3.4. Datastore Resource

The "{+restconf}/data" subtree represents the datastore resource, which is a collection of configuration data and state data nodes. This resource type is an abstraction of the system's underlying datastore implementation. The client uses it to edit and retrieve data resources, as the conceptual root of all configuration and state data that is present on the device. Configuration edit transaction management and configuration persistence are handled by the server and not controlled by the client. A datastore resource can be written directly with the POST and PATCH methods. Each RESTCONF edit of a datastore resource is saved to non-volatile storage by the server if the server supports non-volatile storage of configuration data, as described in Section 1.4. If the datastore resource represented by the "{+restconf}/data" subtree is retrieved, then the datastore and its contents are returned by the server. The datastore is represented by a node named "data" in the "ietf-restconf" module namespace.

3.4.1. Edit Collision Prevention

Two edit collision detection and prevention mechanisms are provided in RESTCONF for the datastore resource: a timestamp and an entity-tag. Any change to configuration data resources updates the timestamp and entity-tag of the datastore resource. In addition, the RESTCONF server MUST return an error if the datastore is locked by an external source (e.g., NETCONF server).
3.4.1.1. Timestamp
The last change time is maintained, and the "Last-Modified" header field (Section 2.2 of [RFC7232]) is returned in the response for a retrieval request. The "If-Unmodified-Since" header field (Section 3.4 of [RFC7232]) can be used in edit operation requests to cause the server to reject the request if the resource has been modified since the specified timestamp. The server SHOULD maintain a last-modified timestamp for the datastore resource, defined in Section 3.4. This timestamp is only affected by configuration child data resources and MUST NOT be updated for changes to non-configuration child data resources. Last-modified timestamps for data resources are discussed in Section 3.5.
Top   ToC   RFC8040 - Page 24
   If the RESTCONF server is co-located with a NETCONF server, then the
   last-modified timestamp MUST be for the "running" datastore.  Note
   that it is possible that other protocols can cause the last-modified
   timestamp to be updated.  Such mechanisms are out of scope for this
   document.

3.4.1.2. Entity-Tag
The server MUST maintain a unique opaque entity-tag for the datastore resource and MUST return it in the "ETag" (Section 2.3 of [RFC7232]) header in the response for a retrieval request. The client MAY use an "If-Match" header in edit operation requests to cause the server to reject the request if the resource entity-tag does not match the specified value. The server MUST maintain an entity-tag for the top-level {+restconf}/data resource. This entity-tag is only affected by configuration data resources and MUST NOT be updated for changes to non-configuration data. Entity-tags for data resources are discussed in Section 3.5. Note that each representation (e.g., XML vs. JSON) requires a different entity-tag. If the RESTCONF server is co-located with a NETCONF server, then this entity-tag MUST be for the "running" datastore. Note that it is possible that other protocols can cause the entity-tag to be updated. Such mechanisms are out of scope for this document.
3.4.1.3. Update Procedure
Changes to configuration data resources affect the timestamp and entity-tag for that resource, any ancestor data resources, and the datastore resource. For example, an edit to disable an interface might be done by setting the leaf "/interfaces/interface/enabled" to "false". The "enabled" data node and its ancestors (one "interface" list instance, and the "interfaces" container) are considered to be changed. The datastore is considered to be changed when any top-level configuration data node is changed (e.g., "interfaces").

3.5. Data Resource

A data resource represents a YANG data node that is a descendant node of a datastore resource. Each YANG-defined data node can be uniquely targeted by the request-line of an HTTP method. Containers, leafs, leaf-list entries, list entries, anydata nodes, and anyxml nodes are data resources.
Top   ToC   RFC8040 - Page 25
   The representation maintained for each data resource is the
   YANG-defined subtree for that node.  HTTP methods on a data resource
   affect both the targeted data node and all of its descendants,
   if any.

   A data resource can be retrieved with the GET method.  Data resources
   are accessed via the "{+restconf}/data" URI.  This subtree is used to
   retrieve and edit data resources.

3.5.1. Timestamp

For configuration data resources, the server MAY maintain a last-modified timestamp for the resource and return the "Last-Modified" header field when it is retrieved with the GET or HEAD methods. The "Last-Modified" header field can be used by a RESTCONF client in subsequent requests, within the "If-Modified-Since" and "If-Unmodified-Since" header fields. If maintained, the resource timestamp MUST be set to the current time whenever the resource or any configuration resource within the resource is altered. If not maintained, then the resource timestamp for the datastore MUST be used instead. If the RESTCONF server is co-located with a NETCONF server, then the last-modified timestamp for a configuration data resource MUST represent the instance within the "running" datastore. This timestamp is only affected by configuration data resources and MUST NOT be updated for changes to non-configuration data.

3.5.2. Entity-Tag

For configuration data resources, the server SHOULD maintain a resource entity-tag for each resource and return the "ETag" header field when it is retrieved as the target resource with the GET or HEAD methods. If maintained, the resource entity-tag MUST be updated whenever the resource or any configuration resource within the resource is altered. If not maintained, then the resource entity-tag for the datastore MUST be used instead. The "ETag" header field can be used by a RESTCONF client in subsequent requests, within the "If-Match" and "If-None-Match" header fields.
Top   ToC   RFC8040 - Page 26
   This entity-tag is only affected by configuration data resources and
   MUST NOT be updated for changes to non-configuration data.  If the
   RESTCONF server is co-located with a NETCONF server, then the
   entity-tag for a configuration data resource MUST represent the
   instance within the "running" datastore.

3.5.3. Encoding Data Resource Identifiers in the Request URI

In YANG, data nodes can be identified with an absolute XPath expression, defined in [XPath], starting from the document root to the target resource. In RESTCONF, URI-encoded path expressions are used instead. A predictable location for a data resource is important, since applications will code to the YANG data model module, which uses static naming and defines an absolute path location for all data nodes. A RESTCONF data resource identifier is encoded from left to right, starting with the top-level data node, according to the "api-path" rule in Section 3.5.3.1. The node name of each ancestor of the target resource node is encoded in order, ending with the node name for the target resource. If a node in the path is defined in a module other than its parent node or its parent is the datastore, then the module name followed by a colon character (":") MUST be prepended to the node name in the resource identifier. See Section 3.5.3.1 for details. If a data node in the path expression is a YANG leaf-list node, then the leaf-list value MUST be encoded according to the following rules: o The identifier for the leaf-list MUST be encoded using one path segment [RFC3986]. o The path segment is constructed by having the leaf-list name, followed by an "=" character, followed by the leaf-list value (e.g., /restconf/data/top-leaflist=fred). o The leaf-list value is specified as a string, using the canonical representation for the YANG data type. Any reserved characters MUST be percent-encoded, according to Sections 2.1 and 2.5 of [RFC3986].
Top   ToC   RFC8040 - Page 27
   o  YANG 1.1 allows duplicate leaf-list values for non-configuration
      data.  In this case, there is no mechanism to specify the exact
      matching leaf-list instance.

   o  The comma (",") character is percent-encoded [RFC3986], even
      though multiple key values are not possible for a leaf-list.  This
      is more consistent and avoids special processing rules.

   If a data node in the path expression is a YANG list node, then the
   key values for the list (if any) MUST be encoded according to the
   following rules:

   o  The key leaf values for a data resource representing a YANG list
      MUST be encoded using one path segment [RFC3986].

   o  If there is only one key leaf value, the path segment is
      constructed by having the list name, followed by an "=" character,
      followed by the single key leaf value.

   o  If there are multiple key leaf values, the path segment is
      constructed by having the list name, followed by the value of each
      leaf identified in the "key" statement, encoded in the order
      specified in the YANG "key" statement.  Each key leaf value except
      the last one is followed by a comma character.

   o  The key value is specified as a string, using the canonical
      representation for the YANG data type.  Any reserved characters
      MUST be percent-encoded, according to Sections 2.1 and 2.5 of
      [RFC3986].  The comma (",") character MUST be percent-encoded if
      it is present in the key value.

   o  All of the components in the "key" statement MUST be encoded.
      Partial instance identifiers are not supported.

   o  Missing key values are not allowed, so two consecutive commas are
      interpreted as a comma, followed by a zero-length string, followed
      by a comma.  For example, "list1=foo,,baz" would be interpreted as
      a list named "list1" with three key values, and the second key
      value is a zero-length string.

   o  Note that non-configuration lists are not required to define keys.
      In this case, a single list instance cannot be accessed.

   o  The "list-instance" Augmented Backus-Naur Form (ABNF) [RFC5234]
      rule defined in Section 3.5.3.1 represents the syntax of a list
      instance identifier.
Top   ToC   RFC8040 - Page 28
   Examples:

      container top {
          list list1 {
              key "key1 key2 key3";
               ...
               list list2 {
                   key "key4 key5";
                   ...
                   leaf X { type string; }
               }
           }
           leaf-list Y {
             type uint32;
           }
       }

   For the above YANG definition, the container "top" is defined in the
   "example-top" YANG module, and a target resource URI for leaf "X"
   would be encoded as follows:

       /restconf/data/example-top:top/list1=key1,key2,key3/\
          list2=key4,key5/X

   For the above YANG definition, a target resource URI for
   leaf-list "Y" would be encoded as follows:

       /restconf/data/example-top:top/Y=instance-value

   The following example shows how reserved characters are
   percent-encoded within a key value.  The value of "key1" contains
   a comma, single-quote, double-quote, colon, double-quote, space,
   and forward slash (,'":" /).  Note that double-quote is not a
   reserved character and does not need to be percent-encoded.  The
   value of "key2" is the empty string, and the value of "key3" is the
   string "foo".

   Example URL:

      /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo

3.5.3.1. ABNF for Data Resource Identifiers
The "api-path" ABNF [RFC5234] syntax is used to construct RESTCONF path identifiers. Note that this syntax is used for all resources, and the API path starts with the RESTCONF root resource. Data resources are required to be identified under the "{+restconf}/data" subtree.
Top   ToC   RFC8040 - Page 29
   An identifier is not allowed to start with the case-insensitive
   string "XML", according to YANG identifier rules.  The syntax for
   "api-identifier" and "key-value" MUST conform to the JSON identifier
   encoding rules in Section 4 of [RFC7951]: The RESTCONF root resource
   path is required.  Additional sub-resource identifiers are optional.
   The characters in a key value string are constrained, and some
   characters need to be percent-encoded, as described in Section 3.5.3.

   api-path = root *("/" (api-identifier / list-instance))

   root = string  ;; replacement string for {+restconf}

   api-identifier = [module-name ":"] identifier

   module-name = identifier

   list-instance = api-identifier "=" key-value *("," key-value)

   key-value = string  ;; constrained chars are percent-encoded

   string = <an unquoted string>

   identifier = (ALPHA / "_")
                *(ALPHA / DIGIT / "_" / "-" / ".")

3.5.4. Default Handling

RESTCONF requires that a server report its default-handling mode (see Section 9.1.2 for details). If the optional "with-defaults" query parameter is supported by the server, a client may use it to control the retrieval of default values (see Section 4.8.9 for details). If a leaf or leaf-list is missing from the configuration and there is a YANG-defined default for that data resource, then the server MUST use the YANG-defined default as the configured value. If the target of a GET method is a data node that represents a leaf or leaf-list that has a default value and the leaf or leaf-list has not been instantiated yet, the server MUST return the default value or values that are in use by the server. In this case, the server MUST ignore its "basic-mode", described in Section 4.8.9, and return the default value. If the target of a GET method is a data node that represents a container or list that has any child resources with default values, for the child resources that have not been given values yet, the
Top   ToC   RFC8040 - Page 30
   server MAY return the default values that are in use by the server in
   accordance with its reported default-handling mode and query
   parameters passed by the client.

3.6. Operation Resource

An operation resource represents an RPC operation defined with the YANG "rpc" statement or a data-model-specific action defined with a YANG "action" statement. It is invoked using a POST method on the operation resource. An RPC operation is invoked as: POST {+restconf}/operations/<operation> The <operation> field identifies the module name and rpc identifier string for the desired operation. For example, if "module-A" defined a "reset" RPC operation, then invoking the operation would be requested as follows: POST /restconf/operations/module-A:reset HTTP/1.1 Server: example.com An action is invoked as: POST {+restconf}/data/<data-resource-identifier>/<action> where <data-resource-identifier> contains the path to the data node where the action is defined, and <action> is the name of the action. For example, if "module-A" defined a "reset-all" action in the container "interfaces", then invoking this action would be requested as follows: POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 Server: example.com If the RPC operation is invoked without errors and if the "rpc" or "action" statement has no "output" section, the response message MUST NOT include a message-body and MUST send a "204 No Content" status-line instead. All operation resources representing RPC operations supported by the server MUST be identified in the "{+restconf}/operations" subtree, defined in Section 3.3.2. Operation resources representing YANG actions are not identified in this subtree, since they are invoked using a URI within the "{+restconf}/data" subtree.
Top   ToC   RFC8040 - Page 31

3.6.1. Encoding Operation Resource Input Parameters

If the "rpc" or "action" statement has an "input" section, then instances of these input parameters are encoded in the module namespace where the "rpc" or "action" statement is defined, in an XML element or JSON object named "input", which is in the module namespace where the "rpc" or "action" statement is defined. If the "rpc" or "action" statement has an "input" section and the "input" object tree contains any child data nodes that are considered mandatory nodes, then a message-body MUST be sent by the client in the request. If the "rpc" or "action" statement has an "input" section and the "input" object tree does not contain any child nodes that are considered mandatory nodes, then a message-body MAY be sent by the client in the request. If the "rpc" or "action" statement has no "input" section, the request message MUST NOT include a message-body. Examples: The following YANG module is used for the RPC operation examples in this section. module example-ops { namespace "https://example.com/ns/example-ops"; prefix "ops"; organization "Example, Inc."; contact "support at example.com"; description "Example Operations Data Model Module."; revision "2016-07-07" { description "Initial version."; reference "example.com document 3-3373."; }
Top   ToC   RFC8040 - Page 32
     rpc reboot {
       description "Reboot operation.";
       input {
         leaf delay {
           type uint32;
           units "seconds";
           default 0;
           description
             "Number of seconds to wait before initiating the
              reboot operation.";
         }
         leaf message {
           type string;
           description
             "Log message to display when reboot is started.";
         }
         leaf language {
           type string;
           description "Language identifier string.";
           reference "RFC 5646.";
         }
       }
     }
Top   ToC   RFC8040 - Page 33
     rpc get-reboot-info {
       description
         "Retrieve parameters used in the last reboot operation.";
       output {
         leaf reboot-time {
           type uint32;
           description
             "The 'delay' parameter used in the last reboot
              operation.";
         }
         leaf message {
           type string;
           description
             "The 'message' parameter used in the last reboot
              operation.";
         }
         leaf language {
           type string;
           description
             "The 'language' parameter used in the last reboot
              operation.";
         }
       }
     }
   }

   The following YANG module is used for the YANG action examples in
   this section.

   module example-actions {
     yang-version 1.1;
     namespace "https://example.com/ns/example-actions";
     prefix "act";
     import ietf-yang-types { prefix yang; }

     organization "Example, Inc.";
     contact "support at example.com";
     description "Example Actions Data Model Module.";
     revision "2016-07-07" {
       description "Initial version.";
       reference "example.com document 2-9973.";
     }
Top   ToC   RFC8040 - Page 34
     container interfaces {
       description "System interfaces.";
       list interface {
         key name;
         description "One interface entry.";
         leaf name {
           type string;
           description "Interface name.";
         }

         action reset {
           description "Reset an interface.";
           input {
             leaf delay {
               type uint32;
               units "seconds";
               default 0;
               description
                 "Number of seconds to wait before starting the
                  interface reset.";
             }
           }
         }

         action get-last-reset-time {
           description
             "Retrieve the last interface reset time.";
           output {
             leaf last-reset {
               type yang:date-and-time;
               mandatory true;
               description
                 "Date and time of the last interface reset, or
                  the last reboot time of the device.";
             }
           }
         }
       }
     }

   }
Top   ToC   RFC8040 - Page 35
   RPC Input Example:

   The client might send the following POST request message to invoke
   the "reboot" RPC operation:

      POST /restconf/operations/example-ops:reboot HTTP/1.1
      Host: example.com
      Content-Type: application/yang-data+xml

      <input xmlns="https://example.com/ns/example-ops">
       <delay>600</delay>
       <message>Going down for system maintenance</message>
       <language>en-US</language>
      </input>

   The server might respond as follows:

      HTTP/1.1 204 No Content
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server

   The same example request message is shown here using JSON encoding:

      POST /restconf/operations/example-ops:reboot HTTP/1.1
      Host: example.com
      Content-Type: application/yang-data+json

      {
        "example-ops:input" : {
          "delay" : 600,
          "message" : "Going down for system maintenance",
          "language" : "en-US"
        }
      }

   Action Input Example:

   The client might send the following POST request message to invoke
   the "reset" action:

      POST /restconf/data/example-actions:interfaces/\
         interface=eth0/reset HTTP/1.1
      Host: example.com
      Content-Type: application/yang-data+xml

      <input xmlns="https://example.com/ns/example-actions">
        <delay>600</delay>
      </input>
Top   ToC   RFC8040 - Page 36
   The server might respond as follows:

      HTTP/1.1 204 No Content
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server

   The same example request message is shown here using JSON encoding:

      POST /restconf/data/example-actions:interfaces/\
        interface=eth0/reset HTTP/1.1
      Host: example.com
      Content-Type: application/yang-data+json

      { "example-actions:input" : {
          "delay" : 600
        }
      }

3.6.2. Encoding Operation Resource Output Parameters

If the "rpc" or "action" statement has an "output" section, then instances of these output parameters are encoded in the module namespace where the "rpc" or "action" statement is defined, in an XML element or JSON object named "output", which is in the module namespace where the "rpc" or "action" statement is defined. If the RPC operation is invoked without errors, and if the "rpc" or "action" statement has an "output" section and the "output" object tree contains any child data nodes that are considered mandatory nodes, then a response message-body MUST be sent by the server in the response. If the RPC operation is invoked without errors, and if the "rpc" or "action" statement has an "output" section and the "output" object tree does not contain any child nodes that are considered mandatory nodes, then a response message-body MAY be sent by the server in the response. The request URI is not returned in the response. Knowledge of the request URI may be needed to associate the output with the specific "rpc" or "action" statement used in the request.
Top   ToC   RFC8040 - Page 37
   Examples:

   RPC Output Example:

   The "example-ops" YANG module defined in Section 3.6.1 is used for
   this example.

   The client might send the following POST request message to invoke
   the "get-reboot-info" operation:

      POST /restconf/operations/example-ops:get-reboot-info 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-ops:output" : {
          "reboot-time" : 30,
          "message" : "Going down for system maintenance",
          "language" : "en-US"
        }
      }

   The same response is shown here using XML encoding:

      HTTP/1.1 200 OK
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Content-Type: application/yang-data+xml

      <output xmlns="https://example.com/ns/example-ops">
        <reboot-time>30</reboot-time>
        <message>Going down for system maintenance</message>
        <language>en-US</language>
      </output>
Top   ToC   RFC8040 - Page 38
   Action Output Example:

   The "example-actions" YANG module defined in Section 3.6.1 is used
   for this example.

   The client might send the following POST request message to invoke
   the "get-last-reset-time" action:

      POST /restconf/data/example-actions:interfaces/\
         interface=eth0/get-last-reset-time 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-actions:output" : {
          "last-reset" : "2015-10-10T02:14:11Z"
        }
      }

3.6.3. Encoding Operation Resource Errors

If any errors occur while attempting to invoke the operation or action, then an "errors" media type is returned with the appropriate error status. If (1) the RPC operation input is not valid or (2) the RPC operation is invoked but errors occur, then a message-body containing an "errors" resource MUST be sent by the server, as defined in Section 3.9.
Top   ToC   RFC8040 - Page 39
   Using the "reboot" RPC operation from the example in Section 3.6.1,
   the client might send the following POST request message:

      POST /restconf/operations/example-ops:reboot HTTP/1.1
      Host: example.com
      Content-Type: application/yang-data+xml

      <input xmlns="https://example.com/ns/example-ops">
        <delay>-33</delay>
        <message>Going down for system maintenance</message>
        <language>en-US</language>
      </input>

   The server might respond with an "invalid-value" error:

      HTTP/1.1 400 Bad Request
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Content-Type: application/yang-data+xml

      <errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
        <error>
          <error-type>protocol</error-type>
          <error-tag>invalid-value</error-tag>
          <error-path xmlns:ops="https://example.com/ns/example-ops">
            /ops:input/ops:delay
          </error-path>
          <error-message>Invalid input parameter</error-message>
        </error>
      </errors>
Top   ToC   RFC8040 - Page 40
   The same response is shown here using JSON encoding:

      HTTP/1.1 400 Bad Request
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Content-Type: application/yang-data+json

      { "ietf-restconf:errors" : {
          "error" : [
            {
              "error-type" : "protocol",
              "error-tag" : "invalid-value",
              "error-path" : "/example-ops:input/delay",
              "error-message" : "Invalid input parameter"
            }
          ]
        }
      }

3.7. Schema Resource

The server can optionally support the retrieval of the YANG modules it uses. If retrieval is supported, then the "schema" leaf MUST be present in the associated "module" list entry, defined in [RFC7895]. To retrieve a YANG module, a client first needs to get the URL for retrieving the schema, which is stored in the "schema" leaf. Note that there is no required structure for this URL. The URL value shown below is just an example. The client might send the following GET request message: GET /restconf/data/ietf-yang-library:modules-state/\ module=example-jukebox,2016-08-15/schema 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-yang-library:schema" : "https://example.com/mymodules/example-jukebox/2016-08-15" }
Top   ToC   RFC8040 - Page 41
   Next, the client needs to retrieve the actual YANG schema.

   The client might send the following GET request message:

      GET https://example.com/mymodules/example-jukebox/\
         2016-08-15 HTTP/1.1
      Host: example.com
      Accept: application/yang

   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

         // entire YANG module contents deleted for this example...

3.8. Event Stream Resource

An event stream resource represents a source for system-generated event notifications. Each stream is created and modified by the server only. A client can retrieve a stream resource or initiate a long-poll server-sent event stream [W3C.REC-eventsource-20150203], using the procedure specified in Section 6.3. An event stream functions according to the "NETCONF Event Notifications" specification [RFC5277]. The available streams can be retrieved from the "stream" list, which specifies the syntax and semantics of the stream resources.

3.9. "errors" YANG Data Template

The "errors" YANG data template models a collection of error information that is sent as the message-body in a server response message if an error occurs while processing a request message. It is not considered as a resource type because no instances can be retrieved with a GET request. The "ietf-restconf" YANG module contains the "yang-errors" YANG data template, which specifies the syntax and semantics of an "errors" container within a RESTCONF response. RESTCONF error-handling behavior is defined in Section 7.


(next page on part 3)

Next Section