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.

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.

   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.

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

   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.

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".

   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>

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>

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.

   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.

   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.

   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].

   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.

   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.

   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

   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.

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.";
     }

     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.";
         }
       }
     }

     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.";
     }

     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.";
             }
           }
         }
       }
     }

   }

   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>

   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.

   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>

   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.

   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>

   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"
      }

   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.