Tech-invite3GPPspaceIETFspace
96959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8040

RESTCONF Protocol

Pages: 137
Proposed Standard
Errata
Part 4 of 6 – Pages 60 to 85
First   Prev   Next

Top   ToC   RFC8040 - Page 60   prevText

5. Messages

The RESTCONF protocol uses HTTP messages. A single HTTP message corresponds to a single protocol method. Most messages can perform a single task on a single resource, such as retrieving a resource or editing a resource. The exception is the PATCH method, which allows multiple datastore edits within a single message.
Top   ToC   RFC8040 - Page 61

5.1. Request URI Structure

Resources are represented with URIs following the structure for generic URIs in [RFC3986]. A RESTCONF operation is derived from the HTTP method and the request URI, using the following conceptual fields: <OP> /<restconf>/<path>?<query> ^ ^ ^ ^ | | | | method entry resource query M M O O M=mandatory, O=optional where: <OP> is the HTTP method <restconf> is the RESTCONF root resource <path> is the target resource URI <query> is the query parameter list o method: the HTTP method identifying the RESTCONF operation requested by the client, to act upon the target resource specified in the request URI. RESTCONF operation details are described in Section 4. o entry: the root of the RESTCONF API configured on this HTTP server, discovered by getting the "/.well-known/host-meta" resource, as described in Section 3.1. o resource: the path expression identifying the resource that is being accessed by the RESTCONF operation. If this field is not present, then the target resource is the API itself, represented by the YANG data template named "yang-api", found in Section 8. o query: the set of parameters associated with the RESTCONF message; see Section 3.4 of [RFC3986]. RESTCONF parameters have the familiar form of "name=value" pairs. Most query parameters are optional to implement by the server and optional to use by the client. Each optional query parameter is identified by a URI. The server MUST list the optional query parameter URIs it supports in the "capability" leaf-list defined in Section 9.3.
Top   ToC   RFC8040 - Page 62
   There is a specific set of parameters defined, although the server
   MAY choose to support query parameters not defined in this document.
   The contents of any query parameter value MUST be encoded according
   to Section 3.4 of [RFC3986].  Any reserved characters MUST be
   percent-encoded, according to Sections 2.1 and 2.5 of [RFC3986].

   Note that the fragment component is not used by the RESTCONF
   protocol.  The fragment is excluded from the target URI by a server,
   as described in Section 5.1 of [RFC7230].

   When new resources are created by the client, a "Location" header
   field is returned, which identifies the path of the newly created
   resource.  The client uses this exact path identifier to access the
   resource once it has been created.

   The target of a RESTCONF operation is a resource.  The "path" field
   in the request URI represents the target resource for the RESTCONF
   operation.

   Refer to Appendix B for examples of RESTCONF request URIs.

5.2. Message Encoding

RESTCONF messages are encoded in HTTP according to [RFC7230]. The "utf-8" character set is used for all messages. RESTCONF message content is sent in the HTTP message-body. Content is encoded in either JSON or XML format. A server MUST support one of either XML or JSON encoding. A server MAY support both XML and JSON encoding. A client will need to support both XML and JSON to interoperate with all RESTCONF servers. XML encoding rules for data nodes are defined in [RFC7950]. The same encoding rules are used for all XML content. JSON encoding rules are defined in [RFC7951]. Additional JSON encoding rules for metadata are defined in [RFC7952]. This encoding is valid JSON, but it also has special encoding rules to identify module namespaces and provide consistent type processing of YANG data.
Top   ToC   RFC8040 - Page 63
   The request input content encoding format is identified with the
   "Content-Type" header field.  This field MUST be present if a
   message-body is sent by the client.

   The server MUST support the "Accept" header field and the "406 Not
   Acceptable" status-line, as defined in [RFC7231].  The response
   output content encoding formats that the client will accept are
   identified with the "Accept" header field in the request.  If it is
   not specified, the request input encoding format SHOULD be used, or
   the server MAY choose any supported content encoding format.

   If there was no request input, then the default output encoding is
   XML or JSON, depending on server preference.  File extensions encoded
   in the request are not used to identify format encoding.

   A client can determine if the RESTCONF server supports an encoding
   format by sending a request using a specific format in the
   "Content-Type" and/or "Accept" header field.  If the server does not
   support the requested input encoding for a request, then it MUST
   return an error response with a "415 Unsupported Media Type"
   status-line.  If the server does not support any of the requested
   output encodings for a request, then it MUST return an error response
   with a "406 Not Acceptable" status-line.

5.3. RESTCONF Metadata

The RESTCONF protocol needs to support the retrieval of the same metadata that is used in the NETCONF protocol. Information about default leafs, last-modified timestamps, etc. is commonly used to annotate representations of the datastore contents. With the XML encoding, the metadata is encoded as attributes in XML, according to Section 3.3 of [W3C.REC-xml-20081126]. With the JSON encoding, the metadata is encoded as specified in [RFC7952].
Top   ToC   RFC8040 - Page 64
   The following examples are based on the example in Appendix B.3.9.
   The "report-all-tagged" mode for the "with-defaults" query parameter
   requires that a "default" attribute be returned for default nodes.
   These examples show that attribute for the "mtu" leaf.

5.3.1. XML Metadata Encoding Example

GET /restconf/data/interfaces/interface=eth1 ?with-defaults=report-all-tagged 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 Content-Type: application/yang-data+xml <interface xmlns="urn:example.com:params:xml:ns:yang:example-interface"> <name>eth1</name> <mtu xmlns:wd="urn:ietf:params:xml:ns:netconf:default:1.0" wd:default="true">1500</mtu> <status>up</status> </interface>
Top   ToC   RFC8040 - Page 65

5.3.2. JSON Metadata Encoding Example

Note that RFC 6243 defines the "default" attribute with the XML Schema Definition (XSD), not YANG, so the YANG module name has to be assigned instead of derived from the YANG module. The value "ietf-netconf-with-defaults" is assigned for JSON metadata encoding. GET /restconf/data/interfaces/interface=eth1\ ?with-defaults=report-all-tagged 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:interface" : [ { "name" : "eth1", "mtu" : 1500, "@mtu" : { "ietf-netconf-with-defaults:default" : true }, "status" : "up" } ] }

5.4. Return Status

Each message represents some sort of resource access. An HTTP "status-line" header field is returned for each request. If a status code in the "4xx" range is returned in the status-line, then the error information SHOULD be returned in the response, according to the format defined in Section 7.1. If a status code in the "5xx" range is returned in the status-line, then the error information MAY be returned in the response, according to the format defined in Section 7.1. If a status code in the "1xx", "2xx", or "3xx" range is returned in the status-line, then error information MUST NOT be returned in the response, since these ranges do not represent error conditions.
Top   ToC   RFC8040 - Page 66

5.5. Message Caching

Since the datastore contents change at unpredictable times, responses from a RESTCONF server generally SHOULD NOT be cached. The server MUST include a "Cache-Control" header field in every response that specifies whether the response should be cached. Instead of relying on HTTP caching, the client SHOULD track the "ETag" and/or "Last-Modified" header fields returned by the server for the datastore resource (or data resource, if the server supports it). A retrieval request for a resource can include the "If-None-Match" and/or "If-Modified-Since" header fields, which will cause the server to return a "304 Not Modified" status-line if the resource has not changed. The client MAY use the HEAD method to retrieve just the message header fields, which SHOULD include the "ETag" and "Last-Modified" header fields, if this metadata is maintained for the target resource. Note that access control can be applied to data resources, such that the values in the "Last-Modified" and "ETag" headers maintained for a data resource may not be reliable, as described in Section 4.3.

6. Notifications

The RESTCONF protocol supports YANG-defined event notifications. The solution preserves aspects of NETCONF event notifications [RFC5277] while utilizing the Server-Sent Events [W3C.REC-eventsource-20150203] transport strategy.

6.1. Server Support

A RESTCONF server MAY support RESTCONF notifications. Clients may determine if a server supports RESTCONF notifications by using the HTTP OPTIONS, HEAD, or GET method on the "stream" list. The server does not support RESTCONF notifications if an HTTP error code is returned (e.g., a "404 Not Found" status-line).
Top   ToC   RFC8040 - Page 67

6.2. Event Streams

A RESTCONF server that supports notifications will populate a stream resource for each notification delivery service access point. A RESTCONF client can retrieve the list of supported event streams from a RESTCONF server using the GET method on the "stream" list. The "restconf-state/streams" container definition in the "ietf-restconf-monitoring" module (defined in Section 9.3) is used to specify the structure and syntax of the conceptual child resources within the "streams" resource. For example: The client might send the following request: GET /restconf/data/ietf-restconf-monitoring:restconf-state/\ streams HTTP/1.1 Host: example.com Accept: application/yang-data+xml The server might send the following response: HTTP/1.1 200 OK Content-Type: application/yang-data+xml <streams xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> <stream> <name>NETCONF</name> <description>default NETCONF event stream</description> <replay-support>true</replay-support> <replay-log-creation-time>\ 2007-07-08T00:00:00Z\ </replay-log-creation-time> <access> <encoding>xml</encoding> <location>https://example.com/streams/NETCONF\ </location> </access> <access> <encoding>json</encoding> <location>https://example.com/streams/NETCONF-JSON\ </location> </access> </stream>
Top   ToC   RFC8040 - Page 68
         <stream>
            <name>SNMP</name>
            <description>SNMP notifications</description>
            <replay-support>false</replay-support>
            <access>
               <encoding>xml</encoding>
               <location>https://example.com/streams/SNMP</location>
            </access>
         </stream>
         <stream>
            <name>syslog-critical</name>
            <description>Critical and higher severity</description>
            <replay-support>true</replay-support>
            <replay-log-creation-time>
               2007-07-01T00:00:00Z
            </replay-log-creation-time>
            <access>
               <encoding>xml</encoding>
               <location>\
                 https://example.com/streams/syslog-critical\
               </location>
            </access>
         </stream>
      </streams>

6.3. Subscribing to Receive Notifications

RESTCONF clients can determine the URL for the subscription resource (to receive notifications) by sending an HTTP GET request for the "location" leaf with the "stream" list entry. The value returned by the server can be used for the actual notification subscription. The client will send an HTTP GET request for the URL returned by the server with the "Accept" type "text/event-stream". The server will treat the connection as an event stream, using the Server-Sent Events [W3C.REC-eventsource-20150203] transport strategy. The server MAY support query parameters for a GET method on this resource. These parameters are specific to each event stream.
Top   ToC   RFC8040 - Page 69
   For example:

   The client might send the following request:

      GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
          streams/stream=NETCONF/access=xml/location HTTP/1.1
      Host: example.com
      Accept: application/yang-data+xml

   The server might send the following response:

      HTTP/1.1 200 OK
      Content-Type: application/yang-data+xml

      <location
        xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">\
        https://example.com/streams/NETCONF\
      </location>

   The RESTCONF client can then use this URL value to start monitoring
   the event stream:

      GET /streams/NETCONF HTTP/1.1
      Host: example.com
      Accept: text/event-stream
      Cache-Control: no-cache
      Connection: keep-alive

   A RESTCONF client MAY request that the server compress the events
   using the HTTP header field "Accept-Encoding".  For instance:

      GET /streams/NETCONF HTTP/1.1
      Host: example.com
      Accept: text/event-stream
      Cache-Control: no-cache
      Connection: keep-alive
      Accept-Encoding: gzip, deflate
Top   ToC   RFC8040 - Page 70

6.3.1. NETCONF Event Stream

The server SHOULD support the NETCONF event stream defined in Section 3.2.3 of [RFC5277]. The notification messages for this stream are encoded in XML. The server MAY support additional streams that represent the semantic content of the NETCONF event stream, but using a representation with a different media type. The server MAY support the "start-time", "stop-time", and "filter" query parameters, defined in Section 4.8. Refer to Appendix B.3.6 for filter parameter examples.

6.4. Receiving Event Notifications

RESTCONF notifications are encoded according to the definition of the event stream. The structure of the event data is based on the <notification> element definition in Section 4 of [RFC5277]. It MUST conform to the schema for the <notification> element in Section 4 of [RFC5277], using the XML namespace as defined in the XSD as follows: urn:ietf:params:xml:ns:netconf:notification:1.0 For JSON-encoding purposes, the module name for the "notification" element is "ietf-restconf". Two child nodes within the "notification" container are expected, representing the event time and the event payload. The "eventTime" node is defined within the same XML namespace as the <notification> element. It is defined to be within the "ietf-restconf" module namespace for JSON-encoding purposes. The name and namespace of the payload element are determined by the YANG module containing the notification-stmt representing the notification message.
Top   ToC   RFC8040 - Page 71
   In the following example, the YANG module "example-mod" is used:

     module example-mod {
       namespace "http://example.com/event/1.0";
       prefix ex;

       organization "Example, Inc.";
       contact "support at example.com";
       description "Example Notification Data Model Module.";
       revision "2016-07-07" {
         description "Initial version.";
         reference "example.com document 2-9976.";
       }

       notification event {
         description "Example notification event.";
         leaf event-class {
           type string;
           description "Event class identifier.";
         }
         container reporting-entity {
           description "Event specific information.";
           leaf card {
             type string;
             description "Line card identifier.";
           }
         }
         leaf severity {
           type string;
           description "Event severity description.";
         }
       }
     }

   An example SSE event notification encoded using XML:

      data: <notification
      data:    xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
      data:    <eventTime>2013-12-21T00:01:00Z</eventTime>
      data:    <event xmlns="http://example.com/event/1.0">
      data:       <event-class>fault</event-class>
      data:       <reporting-entity>
      data:           <card>Ethernet0</card>
      data:       </reporting-entity>
      data:       <severity>major</severity>
      data:     </event>
      data: </notification>
Top   ToC   RFC8040 - Page 72
   An example SSE event notification encoded using JSON:

      data: {
      data:   "ietf-restconf:notification" : {
      data:     "eventTime" : "2013-12-21T00:01:00Z",
      data:     "example-mod:event" : {
      data:       "event-class" : "fault",
      data:       "reporting-entity" : { "card" : "Ethernet0" },
      data:       "severity" : "major"
      data:     }
      data:   }
      data: }

   Alternatively, since neither XML nor JSON is whitespace sensitive,
   the above messages can be encoded onto a single line.  For example:

      XML:

      data: <notification xmlns="urn:ietf:params:xml:ns:netconf:notif\
      ication:1.0"><eventTime>2013-12-21T00:01:00Z</eventTime><event \
      xmlns="http://example.com/event/1.0"><event-class>fault</event-\
      class><reportingEntity><card>Ethernet0</card></reporting-entity>\
      <severity>major</severity></event></notification>

      JSON:

      data: {"ietf-restconf:notification":{"eventTime":"2013-12-21\
      T00:01:00Z","example-mod:event":{"event-class": "fault","repor\
      tingEntity":{"card":"Ethernet0"},"severity":"major"}}}

   The SSE specification supports the following additional fields:
   "event", "id", and "retry".  A RESTCONF server MAY send the "retry"
   field, and if it does, RESTCONF clients SHOULD use it.  A RESTCONF
   server SHOULD NOT send the "event" or "id" fields, as there are no
   meaningful values that could be used for them that would not be
   redundant to the contents of the notification itself.  RESTCONF
   servers that do not send the "id" field also do not need to support
   the HTTP header field "Last-Event-ID" [W3C.REC-eventsource-20150203].
   RESTCONF servers that do send the "id" field SHOULD support the
   "start-time" query parameter as the preferred means for a client to
   specify where to restart the event stream.
Top   ToC   RFC8040 - Page 73

7. Error Reporting

HTTP status codes are used to report success or failure for RESTCONF operations. The error information that NETCONF error responses contain in the <rpc-error> element is adapted for use in RESTCONF, and <errors> data tree information is returned for the "4xx" and "5xx" classes of status codes. Since an operation resource is defined with a YANG "rpc" statement and an action is defined with a YANG "action" statement, a mapping from the NETCONF <error-tag> value to the HTTP status code is needed. The specific error-tag and response code to use are specific to the data model and might be contained in the YANG "description" statement for the "action" or "rpc" statement.
Top   ToC   RFC8040 - Page 74
              +-------------------------+------------------+
              | error-tag               | status code      |
              +-------------------------+------------------+
              | in-use                  | 409              |
              |                         |                  |
              | invalid-value           | 400, 404, or 406 |
              |                         |                  |
              | (request) too-big       | 413              |
              |                         |                  |
              | (response) too-big      | 400              |
              |                         |                  |
              | missing-attribute       | 400              |
              |                         |                  |
              | bad-attribute           | 400              |
              |                         |                  |
              | unknown-attribute       | 400              |
              |                         |                  |
              | bad-element             | 400              |
              |                         |                  |
              | unknown-element         | 400              |
              |                         |                  |
              | unknown-namespace       | 400              |
              |                         |                  |
              | access-denied           | 401 or 403       |
              |                         |                  |
              | lock-denied             | 409              |
              |                         |                  |
              | resource-denied         | 409              |
              |                         |                  |
              | rollback-failed         | 500              |
              |                         |                  |
              | data-exists             | 409              |
              |                         |                  |
              | data-missing            | 409              |
              |                         |                  |
              | operation-not-supported | 405 or 501       |
              |                         |                  |
              | operation-failed        | 412 or 500       |
              |                         |                  |
              | partial-operation       | 500              |
              |                         |                  |
              | malformed-message       | 400              |
              +-------------------------+------------------+

                  Mapping from <error-tag> to Status Code
Top   ToC   RFC8040 - Page 75

7.1. Error Response Message

When an error occurs for a request message on any resource type and the status code that will be returned is in the "4xx" range (except for status code "403 Forbidden"), the server SHOULD send a response message-body containing the information described by the "yang-errors" YANG data template within the "ietf-restconf" module found in Section 8. The Content-Type of this response message MUST be "application/yang-data", plus, optionally, a structured syntax name suffix. The client SHOULD specify the desired encoding(s) for response messages by specifying the appropriate media type(s) in the "Accept" header. If the client did not specify an "Accept" header, then the same structured syntax name suffix used in the request message SHOULD be used, or the server MAY choose any supported message-encoding format. If there is no request message, the server MUST select "application/yang-data+xml" or "application/yang-data+json", depending on server preference. All of the examples in this document, except for the one below, assume that XML encoding will be returned if there is an error. YANG tree diagram for <errors> data: +---- errors +---- error* +---- error-type enumeration +---- error-tag string +---- error-app-tag? string +---- error-path? instance-identifier +---- error-message? string +---- error-info? The semantics and syntax for RESTCONF error messages are defined with the "yang-errors" YANG data template extension, found in Section 8.
Top   ToC   RFC8040 - Page 76
   Examples:

   The following example shows an error returned for a "lock-denied"
   error that can occur if a NETCONF client has locked a datastore.  The
   RESTCONF client is attempting to delete a data resource.  Note that
   an "Accept" header field is used to specify the desired encoding for
   the error message.  There would be no response message-body content
   if this operation was successful.

      DELETE /restconf/data/example-jukebox:jukebox/\
         library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
      Host: example.com
      Accept: application/yang-data+json
Top   ToC   RFC8040 - Page 77
   The server might respond as follows:

      HTTP/1.1 409 Conflict
      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" : "lock-denied",
              "error-message" : "Lock failed; lock already held"
            }
          ]
        }
      }

   The following example shows an error returned for a "data-exists"
   error on a data resource.  The "jukebox" resource already exists, so
   it cannot be created.

   The client might send the following:

      POST /restconf/data/example-jukebox:jukebox HTTP/1.1
      Host: example.com
Top   ToC   RFC8040 - Page 78
   The server might respond as follows:

      HTTP/1.1 409 Conflict
      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>data-exists</error-tag>
          <error-path
            xmlns:rc="urn:ietf:params:xml:ns:yang:ietf-restconf"
            xmlns:jbox="https://example.com/ns/example-jukebox">\
            /rc:restconf/rc:data/jbox:jukebox
          </error-path>
          <error-message>
            Data already exists; cannot create new resource
          </error-message>
        </error>
      </errors>
Top   ToC   RFC8040 - Page 79

8. RESTCONF Module

The "ietf-restconf" module defines conceptual definitions within an extension and two groupings, which are not meant to be implemented as datastore contents by a server. For example, the "restconf" container is not intended to be implemented as a top-level data node (under the "/restconf/data" URI). Note that the "ietf-restconf" module does not have any protocol-accessible objects, so no YANG tree diagram is shown. <CODE BEGINS> file "ietf-restconf@2017-01-26.yang" module ietf-restconf { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; prefix "rc"; organization "IETF NETCONF (Network Configuration) Working Group"; contact "WG Web: <https://datatracker.ietf.org/wg/netconf/> WG List: <mailto:netconf@ietf.org> Author: Andy Bierman <mailto:andy@yumaworks.com> Author: Martin Bjorklund <mailto:mbj@tail-f.com> Author: Kent Watsen <mailto:kwatsen@juniper.net>"; description "This module contains conceptual YANG specifications for basic RESTCONF media type definitions used in RESTCONF protocol messages. Note that the YANG definitions within this module do not represent configuration data of any kind. The 'restconf-media-type' YANG extension statement provides a normative syntax for XML and JSON message-encoding purposes.
Top   ToC   RFC8040 - Page 80
        Copyright (c) 2017 IETF Trust and the persons identified as
        authors of the code.  All rights reserved.

        Redistribution and use in source and binary forms, with or
        without modification, is permitted pursuant to, and subject
        to the license terms contained in, the Simplified BSD License
        set forth in Section 4.c of the IETF Trust's Legal Provisions
        Relating to IETF Documents
        (http://trustee.ietf.org/license-info).

        This version of this YANG module is part of RFC 8040; see
        the RFC itself for full legal notices.";

     revision 2017-01-26 {
       description
         "Initial revision.";
       reference
         "RFC 8040: RESTCONF Protocol.";
     }

     extension yang-data {
       argument name {
         yin-element true;
       }
       description
         "This extension is used to specify a YANG data template that
          represents conceptual data defined in YANG.  It is
          intended to describe hierarchical data independent of
          protocol context or specific message-encoding format.
          Data definition statements within a yang-data extension
          specify the generic syntax for the specific YANG data
          template, whose name is the argument of the 'yang-data'
          extension statement.

          Note that this extension does not define a media type.
          A specification using this extension MUST specify the
          message-encoding rules, including the content media type.

          The mandatory 'name' parameter value identifies the YANG
          data template that is being defined.  It contains the
          template name.

          This extension is ignored unless it appears as a top-level
          statement.  It MUST contain data definition statements
          that result in exactly one container data node definition.
          An instance of a YANG data template can thus be translated
          into an XML instance document, whose top-level element
          corresponds to the top-level container.
Top   ToC   RFC8040 - Page 81
          The module name and namespace values for the YANG module using
          the extension statement are assigned to instance document data
          conforming to the data definition statements within
          this extension.

          The substatements of this extension MUST follow the
          'data-def-stmt' rule in the YANG ABNF.

          The XPath document root is the extension statement itself,
          such that the child nodes of the document root are
          represented by the data-def-stmt substatements within
          this extension.  This conceptual document is the context
          for the following YANG statements:

            - must-stmt
            - when-stmt
            - path-stmt
            - min-elements-stmt
            - max-elements-stmt
            - mandatory-stmt
            - unique-stmt
            - ordered-by
            - instance-identifier data type

          The following data-def-stmt substatements are constrained
          when used within a 'yang-data' extension statement.

            - The list-stmt is not required to have a key-stmt defined.
            - The if-feature-stmt is ignored if present.
            - The config-stmt is ignored if present.
            - The available identity values for any 'identityref'
              leaf or leaf-list nodes are limited to the module
              containing this extension statement and the modules
              imported into that module.
         ";
     }

     rc:yang-data yang-errors {
       uses errors;
     }

     rc:yang-data yang-api {
       uses restconf;
     }
Top   ToC   RFC8040 - Page 82
     grouping errors {
       description
         "A grouping that contains a YANG container
          representing the syntax and semantics of a
          YANG Patch error report within a response message.";

       container errors {
         description
           "Represents an error report returned by the server if
            a request results in an error.";

         list error {
           description
             "An entry containing information about one
              specific error that occurred while processing
              a RESTCONF request.";
           reference
             "RFC 6241, Section 4.3.";

           leaf error-type {
             type enumeration {
               enum transport {
                 description
                   "The transport layer.";
               }
               enum rpc {
                 description
                   "The rpc or notification layer.";
               }
               enum protocol {
                 description
                   "The protocol operation layer.";
               }
               enum application {
                 description
                   "The server application layer.";
               }
             }
             mandatory true;
             description
               "The protocol layer where the error occurred.";
           }
Top   ToC   RFC8040 - Page 83
           leaf error-tag {
             type string;
             mandatory true;
             description
               "The enumerated error-tag.";
           }

           leaf error-app-tag {
             type string;
             description
               "The application-specific error-tag.";
           }

           leaf error-path {
             type instance-identifier;
             description
               "The YANG instance identifier associated
                with the error node.";
           }

           leaf error-message {
             type string;
             description
               "A message describing the error.";
           }

           anydata error-info {
              description
                "This anydata value MUST represent a container with
                 zero or more data nodes representing additional
                 error information.";
           }
         }
       }
     }

     grouping restconf {
       description
         "Conceptual grouping representing the RESTCONF
          root resource.";

       container restconf {
         description
           "Conceptual container representing the RESTCONF
            root resource.";
Top   ToC   RFC8040 - Page 84
         container data {
           description
             "Container representing the datastore resource.
              Represents the conceptual root of all state data
              and configuration data supported by the server.
              The child nodes of this container can be any data
              resources that are defined as top-level data nodes
              from the YANG modules advertised by the server in
              the 'ietf-yang-library' module.";
         }

         container operations {
           description
             "Container for all operation resources.

              Each resource is represented as an empty leaf with the
              name of the RPC operation from the YANG 'rpc' statement.

              For example, the 'system-restart' RPC operation defined
              in the 'ietf-system' module would be represented as
              an empty leaf in the 'ietf-system' namespace.  This is
              a conceptual leaf and will not actually be found in
              the module:

                 module ietf-system {
                   leaf system-reset {
                     type empty;
                   }
                 }

              To invoke the 'system-restart' RPC operation:

                 POST /restconf/operations/ietf-system:system-restart

              To discover the RPC operations supported by the server:

                 GET /restconf/operations

              In XML, the YANG module namespace identifies the module:

                <system-restart
                   xmlns='urn:ietf:params:xml:ns:yang:ietf-system'/>

              In JSON, the YANG module name identifies the module:

                { 'ietf-system:system-restart' : [null] }
             ";
         }
Top   ToC   RFC8040 - Page 85
         leaf yang-library-version {
           type string {
             pattern '\d{4}-\d{2}-\d{2}';
           }
           config false;
           mandatory true;
           description
             "Identifies the revision date of the 'ietf-yang-library'
              module that is implemented by this RESTCONF server.
              Indicates the year, month, and day in YYYY-MM-DD
              numeric format.";
         }
       }
     }

   }

   <CODE ENDS>



(page 85 continued on part 5)

Next Section