Network Working Group                                         A. Bierman
Internet-Draft                                                 YumaWorks
Intended status: Standards Track                            M. Bjorklund
Expires: June September 17, 2016                               Tail-f Systems
                                                               K. Watsen
                                                        Juniper Networks
                                                       December 15, 2015
                                                          March 16, 2016

                           RESTCONF Protocol
                     draft-ietf-netconf-restconf-09
                     draft-ietf-netconf-restconf-10

Abstract

   This document describes an HTTP-based protocol that provides a
   programmatic interface for accessing data defined in YANG, using the
   datastores defined in NETCONF.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on June September 17, 2016.

Copyright Notice

   Copyright (c) 2015 2016 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.1.  Simple Subset of NETCONF Functionality  Terminology . . . . . . . . . . . . . . . . . . . . . . .   5
     1.2.  Data Model Driven API
       1.1.1.  NETCONF . . . . . . . . . . . . . . . . . . . . . . .   6
     1.3.  Coexistence with NETCONF
       1.1.2.  HTTP  . . . . . . . . . . . . . . . . . .   7
     1.4.  Terminology . . . . . .   6
       1.1.3.  YANG  . . . . . . . . . . . . . . . . .   8
       1.4.1.  NETCONF . . . . . . .   7
       1.1.4.  Terms . . . . . . . . . . . . . . . .   8
       1.4.2.  HTTP . . . . . . . .   7
       1.1.5.  URI Template  . . . . . . . . . . . . . . . .   8
       1.4.3.  YANG . . . .   9
       1.1.6.  Tree Diagrams . . . . . . . . . . . . . . . . . . . .   9
       1.4.4.  Terms
     1.2.  Subset of NETCONF Functionality . . . . . . . . . . . . .   9
     1.3.  Data Model Driven API . . . . . . . . . . .  10
       1.4.5.  URI Template . . . . . . .  10
     1.4.  Coexistence with NETCONF  . . . . . . . . . . . . .  11
       1.4.6.  Tree Diagrams . . .  11
     1.5.  RESTCONF Extensibility  . . . . . . . . . . . . . . . . .  11  12
   2.  Transport Protocol Requirements . . . . . . . . . . . . . . .  12  13
     2.1.  Integrity and Confidentiality . . . . . . . . . . . . . .  12  13
     2.2.  HTTPS with X.509v3 Certificates . . . . . . . . . . . . .  12  13
     2.3.  Certificate Validation  . . . . . . . . . . . . . . . . .  12  13
     2.4.  Authenticated Server Identity . . . . . . . . . . . . . .  13  14
     2.5.  Authenticated Client Identity . . . . . . . . . . . . . .  13  14
   3.  Resources . . . . . . . . . . . . . . . . . . . . . . . . . .  13  14
     3.1.  Root Resource Discovery . . . . . . . . . . . . . . . . .  14  15
     3.2.  RESTCONF Resource Media Types  . . . . . . . . . . . . . . . . .  15 .  17
     3.3.  API Resource  . . . . . . . . . . . . . . . . . . . . . .  15  17
       3.3.1.  {+restconf}/data  . . . . . . . . . . . . . . . . . .  16  18
       3.3.2.  {+restconf}/operations  . . . . . . . . . . . . . . .  17  18
       3.3.3.  {+restconf}/yang-library-version  . . . . . . . . . .  19
     3.4.  Datastore Resource  . . . . . . . . . . . . . . . . . . .  17  19
       3.4.1.  Edit Collision Detection  . . . . . . . . . . . . . .  17  20
     3.5.  Data Resource . . . . . . . . . . . . . . . . . . . . . .  18  21
       3.5.1.  Encoding Data Resource Identifiers in the Request URI  19  22
       3.5.2.  Defaults Handling . . . . . . . . . . . . . . . . . .  22  25
     3.6.  Operation Resource  . . . . . . . . . . . . . . . . . . .  22  25
       3.6.1.  Encoding Operation Resource Input Parameters  . . . . . . . . .  23  26
       3.6.2.  Encoding Operation Resource Output Parameters . . . . . . . .  24  29
       3.6.3.  Encoding Operation Resource Errors  . . . . . . . . . . . . . .  25  31
     3.7.  Schema Resource . . . . . . . . . . . . . . . . . . . . .  26  32
     3.8.  Event Stream Resource . . . . . . . . . . . . . . . . . .  27  33
     3.9.  Errors Media Type . . . . . . . . . . . . . . . . . . . .  27  33
   4.  Operations  . . . . . . . . . . . . . . . . . . . . . . . . .  27  34
     4.1.  OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . .  28  35
     4.2.  HEAD  . . . . . . . . . . . . . . . . . . . . . . . . . .  29  35
     4.3.  GET . . . . . . . . . . . . . . . . . . . . . . . . . . .  29  35
     4.4.  POST  . . . . . . . . . . . . . . . . . . . . . . . . . .  30  37
       4.4.1.  Create Resource Mode  . . . . . . . . . . . . . . . .  30  37
       4.4.2.  Invoke Operation Mode . . . . . . . . . . . . . . . .  31  38
     4.5.  PUT . . . . . . . . . . . . . . . . . . . . . . . . . . .  32  39
     4.6.  PATCH . . . . . . . . . . . . . . . . . . . . . . . . . .  33  41
       4.6.1.  Plain Patch . . . . . . . . . . . . . . . . . . . . .  33  41
     4.7.  DELETE  . . . . . . . . . . . . . . . . . . . . . . . . .  34  42
     4.8.  Query Parameters  . . . . . . . . . . . . . . . . . . . .  35  43
       4.8.1.  The "content" Query Parameter . . . . . . . . . . . .  36  44
       4.8.2.  The "depth" Query Parameter . . . . . . . . . . . . .  36  45
       4.8.3.  The "fields" Query Parameter  . . . . . . . . . . . .  37  45
       4.8.4.  The "insert" Query Parameter  . . . . . . . . . . . .  38  46
       4.8.5.  The "point" Query Parameter . . . . . . . . . . . . .  39  47
       4.8.6.  The "filter" Query Parameter  . . . . . . . . . . . .  39  47
       4.8.7.  The "start‑time" "start-time" Query Parameter  . . . . . . .  40 . . .  48
       4.8.8.  The "stop‑time" "stop-time" Query Parameter . . . . . . . .  40 . . .  49
       4.8.9.  The "with‑defaults" "with-defaults" Query Parameter . . . . . .  41 . . .  50
   5.  Messages  . . . . . . . . . . . . . . . . . . . . . . . . . .  42  51
     5.1.  Request URI Structure . . . . . . . . . . . . . . . . . .  42  51
     5.2.  Message Headers . . . . . . . . . . . . . . . . . . . . .  43
     5.3.  Message Encoding  . . . . . . . . . . . . . . . . . . . .  45
     5.4.  52
     5.3.  RESTCONF Meta-Data  . . . . . . . . . . . . . . . . . . .  45
       5.4.1.  53
       5.3.1.  XML MetaData Encoding Example . . . . . . . . . . . .  45
       5.4.2.  53
       5.3.2.  JSON MetaData Encoding Example  . . . . . . . . . . .  46
     5.5.  54
     5.4.  Return Status . . . . . . . . . . . . . . . . . . . . . .  47
     5.6.  54
     5.5.  Message Caching . . . . . . . . . . . . . . . . . . . . .  47  54
   6.  Notifications . . . . . . . . . . . . . . . . . . . . . . . .  47  55
     6.1.  Server Support  . . . . . . . . . . . . . . . . . . . . .  47  55
     6.2.  Event Streams . . . . . . . . . . . . . . . . . . . . . .  48  55
     6.3.  Subscribing to Receive Notifications  . . . . . . . . . .  49  58
       6.3.1.  NETCONF Event Stream  . . . . . . . . . . . . . . . .  50  59
     6.4.  Receiving Event Notifications . . . . . . . . . . . . . .  51  59
   7.  Error Reporting . . . . . . . . . . . . . . . . . . . . . . .  53  61
     7.1.  Error Response Message  . . . . . . . . . . . . . . . . .  54  63
   8.  RESTCONF module . . . . . . . . . . . . . . . . . . . . . . .  56  65
   9.  RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . .  62  71
     9.1.  restconf-state/capabilities . . . . . . . . . . . . . . .  62  71
       9.1.1.  Query Parameter URIs  . . . . . . . . . . . . . . . .  63  72
       9.1.2.  The "defaults" Protocol Capability URI  . . . . . . .  64  72
     9.2.  restconf-state/streams  . . . . . . . . . . . . . . . . .  64  73
     9.3.  RESTCONF Monitoring Module  . . . . . . . . . . . . . . .  65  74
   10. YANG Module Library . . . . . . . . . . . . . . . . . . . . .  68  77
     10.1.  modules  . . . . . . . . . . . . . . . . . . . . . . . .  69  77
       10.1.1.  modules/module . . . . . . . . . . . . . . . . . . .  69  78

   11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  69  78
     11.1.  The "restconf" Relation Type . . . . . . . . . . . . . .  69  78
     11.2.  YANG Module Registry . . . . . . . . . . . . . . . . . .  70  78
     11.3.  application/yang Media Sub Types . . . . . . . . . . . .  70  79
     11.4.  RESTCONF Capability URNs . . . . . . . . . . . . . . . .  71  80
   12. Security Considerations . . . . . . . . . . . . . . . . . . .  72  81
   13. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  73  82
   14. References  . . . . . . . . . . . . . . . . . . . . . . . . .  73  82
     14.1.  Normative References . . . . . . . . . . . . . . . . . .  73  82
     14.2.  Informative References . . . . . . . . . . . . . . . . .  76  85
   Appendix A.  Change Log . . . . . . . . . . . . . . . . . . . . .  76  85
     A.1.  v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . .  85
     A.2.  v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . .  76
     A.2.  87
     A.3.  v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . .  76
     A.3.  88
     A.4.  v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . .  77
     A.4.  88
     A.5.  v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . .  77
     A.5.  88
     A.6.  v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . .  77
     A.6.  88
     A.7.  v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . .  78
     A.7.  89
     A.8.  v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . .  79
     A.8.  90
     A.9.  v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . .  79
     A.9.  90
     A.10. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . .  80
     A.10.  91
     A.11. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . .  81  92
   Appendix B.  Open Issues  . . . . . . . . . . . . . . . . . . . .  81  92
   Appendix C.  Example YANG Module  . . . . . . . . . . . . . . . .  81  92
     C.1.  example-jukebox YANG Module . . . . . . . . . . . . . . .  82  93
   Appendix D.  RESTCONF Message Examples  . . . . . . . . . . . . .  87  98
     D.1.  Resource Retrieval Examples . . . . . . . . . . . . . . .  87  99
       D.1.1.  Retrieve the Top-level API Resource . . . . . . . . .  87  99
       D.1.2.  Retrieve The Server Module Information  . . . . . . .  88 100
       D.1.3.  Retrieve The Server Capability Information  . . . . .  90 101
     D.2.  Edit Resource Examples  . . . . . . . . . . . . . . . . .  90 102
       D.2.1.  Create New Data Resources . . . . . . . . . . . . . .  91 102
       D.2.2.  Detect Resource Entity Tag Change . . . . . . . . . .  92 103
       D.2.3.  Edit a Datastore Resource . . . . . . . . . . . . . .  92 104
     D.3.  Query Parameter Examples  . . . . . . . . . . . . . . . .  93 104
       D.3.1.  "content" Parameter . . . . . . . . . . . . . . . . .  93 104
       D.3.2.  "depth" Parameter . . . . . . . . . . . . . . . . . .  96 107
       D.3.3.  "fields" Parameter  . . . . . . . . . . . . . . . . .  99 110
       D.3.4.  "insert" Parameter  . . . . . . . . . . . . . . . . . 100 111
       D.3.5.  "point" Parameter . . . . . . . . . . . . . . . . . . 100 112
       D.3.6.  "filter" Parameter  . . . . . . . . . . . . . . . . . 101 113
       D.3.7.  "start‑time"  "start-time" Parameter  . . . . . . . . . . . . 102 . . . 113
       D.3.8.  "stop‑time"  "stop-time" Parameter . . . . . . . . . . . . . 102 . . . 113
       D.3.9.  "with‑defaults"  "with-defaults" Parameter . . . . . . . . . . . 102 . . . 114
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . . 104 115

1.  Introduction
   There is a need for standard mechanisms to allow Web applications to
   access the configuration data, operational data, data-model specific
   protocol operations, and event notifications within a networking
   device, in a modular and extensible manner.

   This document describes defines an HTTP [RFC7230] based protocol called
   RESTCONF, for accessing configuring data defined in YANG version 1 [RFC6020] or
   YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using datastores
   defined in NETCONF [RFC6241].

   The

   NETCONF protocol defines configuration datastores and a set of Create,
   Retrieve, Update, Delete (CRUD) operations that can be used to access
   these datastores.  The YANG language defines the syntax and semantics
   of datastore content, operational data, protocol operations, and
   event notifications.

   RESTCONF uses HTTP operations to provide CRUD operations on a NETCONF
   conceptual datastore containing YANG-
   defined data.  Since YANG-defined data, which is
   compatible with a server which implements NETCONF protocol operations are not relevant,
   the user should not need any prior knowledge of datastores.

   If a RESTCONF server is co-located with a NETCONF server, then there
   are protocol interactions to be considered, as described in order
   Section 1.4.  The server MAY provide access to
   use RESTCONF. specific datastores
   using operation resources, as described in Section 3.6.

   Configuration data and state data are exposed as resources that can
   be retrieved with the GET method.  Resources representing
   configuration data can be modified with the DELETE, PATCH, POST, and
   PUT methods.  Data is encoded with either XML [W3C.REC-xml-20081126]
   or JSON [RFC7158]. [RFC7159].

   Data-model specific operations defined with the YANG "rpc" or
   "action" statements can be invoked with the POST method.  Data-model
   specific event notifications defined with the YANG "notification"
   statement can be accessed.

1.1.  Simple Subset of NETCONF Functionality

   An HTTP-based management protocol does not need to mirror the
   functionality of the NETCONF protocol, but it needs  Terminology

   The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be compatible
   with NETCONF.  A simplified transaction model is needed that allows
   basic CRUD operations on a hierarchy of conceptual resources.  This
   represents a limited subset of the transaction capabilities of the interpreted as described in BCP
   14, [RFC2119].

1.1.1.  NETCONF protocol.

   The HTTP POST, PUT, PATCH, and DELETE methods following terms are used to edit data
   resources represented by YANG defined in [RFC6241]:

   o  candidate configuration datastore

   o  client

   o  configuration data models.  These basic edit
   operations allow the

   o  datastore

   o  configuration datastore

   o  protocol operation

   o  running configuration to be altered datastore

   o  server

   o  startup configuration datastore

   o  state data

   o  user

1.1.2.  HTTP

   The following terms are defined in an all-
   or-none fashion.  This is similar to the "rollback-on-error"
   capability [RFC3986]:

   o  fragment

   o  path

   o  query

   The following terms are defined in NETCONF.  Edits [RFC7230]:

   o  header

   o  message-body

   o  request-line

   o  request URI

   o  status-line
   The following terms are usually applied to one data defined in [RFC7231]:

   o  method

   o  request

   o  resource instance at a time.

   The base RESTCONF protocol is intentionally simple to allow
   deployment for as many use cases as possible.  Additional
   functionality can be following terms are defined in external documents, outside the scope
   of this document.

   RESTCONF is not intended to replace NETCONF, but rather provide an
   additional simplified interface that follows REST principles and is
   compatible with a resource-oriented device abstraction. [RFC7232]:

   o  entity tag

1.1.3.  YANG

   The following figure shows the terms are defined in [I-D.ietf-netmod-rfc6020bis]:

   o  action

   o  container

   o  data node

   o  key leaf

   o  leaf

   o  leaf-list

   o  list

   o  non-presence container (or NP-container)

   o  ordered-by system components:

      +-----------+           +-----------------+
      |  Web app  | <-------> |                 |
      +-----------+   HTTP    | network device  |
                              |                 |
      +-----------+           |   +-----------+ |
      |  NMS app  | <-------> |   | datastore | |
      +-----------+  NETCONF  |   +-----------+ |
                              +-----------------+

1.2.  Data Model Driven

   o  ordered-by user

   o  presence container (or P-container)

   o  RPC operation

   o  top-level data node

1.1.4.  Terms

   The following terms are used within this document:

   o  API

   RESTCONF combines the simplicity of resource: a resource with the HTTP protocol media type "application/
      yang.api+xml" or "application/yang.api+json".

   o  data resource: a resource with the
   predictability media type "application/
      yang.data+xml" or "application/yang.data+json".  Containers,
      leafs, list entries, anydata and automation potential of anyxml nodes can be data
      resources.

   o  datastore resource: a schema-driven API.
   Using YANG, resource with the media type "application/
      yang.datastore+xml" or "application/yang.datastore+json".
      Represents a client can predict all datastore.

   o  edit operation: a RESTCONF operation on a data resource endpoints, much like using URI Templates [RFC6570], but in
      either a more holistic manner. POST, PUT, PATCH, or DELETE method.

   o  event stream resource: This
   strategy obviates the need for responses provided by the server to
   contain HATEOAS links, originally described in Roy Fielding's
   doctoral dissertation [rest-dissertation].

   In contrast, a REST client using HATEOAS principles would not use any
   data modeling language to define the application-specific resource represents an SSE (Server-
      Sent Events) event stream.  The content consists of text using the API.  The client would need to discover each new child resource
      media type "text/event-stream", as it traverses the URIs to discover the server capabilities.  This
   approach has the following significant weaknesses with regards to
   control of complex networking devices:

   o  inefficient performance: configuration APIs will be quite complex
      and may require thousands of protocol messages to discover all defined by the
      schema information.  Typically HTML5
      [W3C.REC-html5-20141028] specification.  Each event represents one
      <notification> message generated by the data type information has to be
      passed in the protocol messages, which server.  It contains a
      conceptual system or data-model specific event that is also wasteful overhead. delivered
      within an event notification stream.  Also called a "stream
      resource".

   o  no  media-type: HTTP uses Internet media types [RFC2046] in the
      Content-Type and Accept header fields in order to provide open and
      extensible data model richness: without typing and type negotiation.

   o  operation: the conceptual RESTCONF operation for a data model, message,
      derived from the schema-level
      semantics HTTP method, request URI, headers, and validation constraints are not available to message-
      body.

   o  operation resource: a resource with the
      application. media type "application/
      yang.operation+xml" or "application/yang.operation+json".

   o  no tool automation: API automation tools need some sort  patch: a generic PATCH request on the target datastore or data
      resource.  The media type of the message-body content
      schema to function.  Such tools can automate various programming
      and documentation tasks related to specific data models.

   Data models such as YANG modules serve as an "API contract" that will
   be honored by
      identify the server.  An application designer patch type in use.

   o  plain patch: a specific PATCH request type that can code to be used for
      simple merge operations.

   o  query parameter: a parameter (and its value if any), encoded
      within the
   data model, knowing in advance important details about query component of the exact
   protocol operations and datastore content a conforming server
   implementation will support. request URI.

   o  RESTCONF provides the YANG module capability information capability: An optional RESTCONF protocol feature
      supported by the server, in case the client wants to use it.  The URIs for custom
   protocol operations which is identified by an IANA registered
      NETCONF Capability URI, and datastore content are predictable, based on
   the YANG module definitions.

   Operational experience advertised with CLI and SNMP indicates that operators
   learn an entry in the location of specific service or device related data and do
   not expect such information to be arbitrary and discovered each time
   the client opens
      "capability" leaf-list in Section 9.3.

   o  retrieval request: a management session to request using the GET or HEAD methods.

   o  target resource: the resource that is associated with a server.

   The RESTCONF protocol operates on particular
      message, identified by the "path" component of the request URI.

   o  schema resource: a conceptual datastore defined resource with the YANG data modeling language. media type "application/
      yang".  The server lists each YANG module
   it supports using representation of the "ietf-yang-library" YANG module, defined in
   [I-D.ietf-netconf-yang-library].  The server MUST implement schema can be retrieved by
      the
   "ietf-yang-library" module, which MUST identify all client with the YANG modules
   used by GET method.

   o  stream list: the server.

   The conceptual datastore contents, data-model-specific operations and
   event notifications are identified by this set of YANG modules.  All
   RESTCONF content identified as either a data resource, operation
   resource, or resource instances that describe the
      event stream resource resources available from the server.  This
      information is defined with in the YANG language.

   The classification of data "ietf-restconf-monitoring" module as configuration or non-configuration is
   derived from
      the YANG "config" statement.  Data ordering behavior is
   derived from "stream" list.  It can be retrieved using the YANG "ordered-by" statement. target resource
      "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/
      stream".  The RESTCONF datastore editing model is simple and direct, similar stream list contains information about each stream,
      such as the URL to retrieve the behavior of event stream data.

1.1.5.  URI Template

   Throughout this document, the :writable-running capability in NETCONF.  Each
   RESTCONF edit of a datastore resource URI template [RFC6570] syntax
   "{+restconf}" is activated upon successful
   completion of used to refer to the transaction.

1.3.  Coexistence with NETCONF RESTCONF can be implemented on a device that supports NETCONF.

   If the device supports :writable-running, all edits to configuration
   nodes in {+restconf}/data are performed in the running configuration
   datastore.

   Otherwise, if the device supports :candidate, all edits to
   configuration nodes in {+restconf}/data are performed in the
   candidate configuration datastore.  The candidate is automatically
   committed to running after a successful edit.

   If the device supports :startup, the device automatically copies the
   content of running to startup after running has been updated as a
   consequence API entry point
   outside of a RESTCONF edit operation.

   If a datastore that would be modified by a RESTCONF operation has an
   active lock, example.  See Section 3.1 for details.

   For simplicity, all of the RESTCONF edit operation MUST fail with a 409
   (Conflict) error code.

1.4.  Terminology

   The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" examples in this document are to be interpreted assume "/
   restconf" as described the discovered RESTCONF API root path.

1.1.6.  Tree Diagrams

   A simplified graphical representation of the data model is used in BCP
   14, [RFC2119].

1.4.1.  NETCONF
   this document.  The following terms are defined meaning of the symbols in [RFC6241]:

   o  candidate configuration datastore these diagrams is as
   follows:

   o  client  Brackets "[" and "]" enclose list keys.

   o  configuration  Abbreviations before data

   o  datastore

   o  configuration datastore

   o  protocol operation

   o  running configuration datastore

   o  server

   o  startup node names: "rw" means configuration datastore

   o
      data (read-write) and "ro" state data (read-only).

   o  user

1.4.2.  HTTP
   The following terms are defined in [RFC3986]:

   o  fragment

   o  path

   o  query

   The following terms are defined in [RFC7230]:

   o  header

   o  message-body

   o  request-line

   o  request URI

   o  status-line

   The following terms are defined in [RFC7231]:

   o  method

   o  request

   o  resource

   The following terms are defined in [RFC7232]:

   o  entity tag

1.4.3.  YANG

   The following terms are defined in [I-D.ietf-netmod-rfc6020bis]:

   o  action

   o  container

   o  Symbols after data node

   o  key leaf

   o  leaf

   o  leaf-list
   o  list

   o  non-presence container (or NP-container)

   o  ordered-by system

   o  ordered-by user

   o  presence container (or P-container)

   o  RPC operation (now called protocol operation)

1.4.4.  Terms

   The following terms are used within this document:

   o  API resource: names: "?" means an optional node, "!"
      means a resource with the media type "application/
      yang.api+xml" or "application/yang.api+json".

   o  data resource: presence container, and "*" denotes a resource with the media type "application/
      yang.data+xml" or "application/yang.data+json".  Containers,
      leafs, list entries, anydata and anyxml nodes can be data
      resources. leaf-list.

   o  datastore resource: a resource  Parentheses enclose choice and case nodes, and case nodes are also
      marked with the media type "application/
      yang.datastore+xml" or "application/yang.datastore+json".
      Represents a datastore. colon (":").

   o  edit operation:  Ellipsis ("...") stands for contents of subtrees that are not
      shown.

1.2.  Subset of NETCONF Functionality

   RESTCONF does not need to mirror the full functionality of the
   NETCONF protocol, but it does need to be compatible with NETCONF.

   RESTCONF achieves this by implementing a subset of the interaction
   capabilities provided by the NETCONF protocol, for instance, by
   eliminating datastores and explicit locking.

   RESTCONF operation uses HTTP methods to implement the equivalent of NETCONF
   operations, enabling basic CRUD operations on a data resource using
      either a hierarchy of
   conceptual resources.

   The HTTP POST, PUT, PATCH, or and DELETE method.

   o  event stream resource: This resource represents an SSE (Server-
      Sent Events) event stream.  The content consists of text using the
      media type "text/event-stream", as defined by the HTML5
      specification.  Each event represents one <notification> message
      generated methods are used to edit data
   resources represented by YANG data models.  These basic edit
   operations allow the server.  It contains a conceptual system or data-
      model specific event that is delivered within an event
      notification stream.  Also called a "stream resource".

   o  media-type: HTTP uses Internet media types [RFC2046] in the
      Content-Type and Accept header fields running configuration to be altered in order an all-
   or-none fashion.

   RESTCONF is not intended to replace NETCONF, but rather provide open and
      extensible data typing an
   additional interface that follows Representational State Transfer
   (REST) principles and type negotiation.

   o  operation: the conceptual RESTCONF operation for is compatible with a message,
      derived from resource-oriented device
   abstraction.

   The following figure shows the HTTP method, request URI, headers, and message-
      body.

   o  operation resource: system components if a resource RESTCONF server
   is co-located with the media type "application/
      yang.operation+xml" or "application/yang.operation+json".

   o  patch: a generic PATCH request on the target NETCONF server:

      +-----------+           +-----------------+
      |  Web app  | <-------> |                 |
      +-----------+   HTTP    | network device  |
                              |                 |
      +-----------+           |   +-----------+ |
      |  NMS app  | <-------> |   | datastore or data
      resource. | |
      +-----------+  NETCONF  |   +-----------+ |
                              +-----------------+

   The media type of the message-body content will
      identify following figure shows the patch type system components if a RESTCONF server
   is implemented in use.

   o  plain patch: a specific PATCH request type device that can be used for
      simple merge operations.

   o  query parameter: does not have a parameter (and its value if any), encoded
      within NETCONF server:

      +-----------+           +-----------------+
      |  Web app  | <-------> |                 |
      +-----------+   HTTP    | network device  |
                              |                 |
                              +-----------------+

1.3.  Data Model Driven API
   RESTCONF combines the query component simplicity of the request URI.

   o  RESTCONF capability: An optional RESTCONF HTTP protocol feature
      supported by the server, which is identified by an IANA registered
      NETCONF Capability URI, and advertised with an entry in the
      "capability" leaf-list in Section 9.3.

   o  retrieval request:
   predictability and automation potential of a request schema-driven API.
   Using YANG, a client can predict all management resources, much like
   using the GET or HEAD methods.

   o  target resource: the resource that is associated with URI Templates [RFC6570], but in a particular
      message, identified by more holistic manner.  This
   strategy obviates the "path" component of need for responses provided by the request URI.

   o  schema resource: a resource with server to
   contain Hypermedia as the media type "application/
      yang".  The YANG representation Engine of Application State (HATEOAS)
   links, originally described in Roy Fielding's doctoral dissertation
   [rest-dissertation].

   RESTCONF provides the schema can be retrieved YANG module capability information supported by
   the server, in case the client with wants to use it.  The URIs for custom
   protocol operations and datastore content are predictable, based on
   the GET method.

   o  stream list: YANG module definitions.

   The RESTCONF protocol operates on a conceptual datastore defined with
   the set of YANG data resource instances that describe the
      event stream resources available from modeling language.  The server lists each YANG module
   it supports using the server.  This
      information is "ietf-yang-library" YANG module, defined in
   [I-D.ietf-netconf-yang-library].  The server MUST implement the "ietf-restconf-monitoring" module as
   "ietf-yang-library" module, which MUST identify all the "stream" list.  It can be retrieved using YANG modules
   used by the target resource
      "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/
      stream". server.

   The stream list contains information about each stream,
      such as the URL to retrieve the conceptual datastore contents, data-model-specific operations and
   event stream data.

1.4.5.  URI Template

   Throughout notifications are identified by this document, set of YANG modules.

   The classification of data as configuration or non-configuration is
   derived from the URI template [RFC6570] syntax
   "{+restconf}" YANG "config" statement.  Data ordering behavior is used to refer to
   derived from the YANG "ordered-by" statement.

   The RESTCONF API entry point
   outside of an example.  See Section 3.1 for details.

   For simplicity, all datastore editing model is simple and direct, similar to
   the behavior of the examples :writable-running capability in this document assume "/
   restconf" as the discovered NETCONF.  Each
   RESTCONF API root path.

1.4.6.  Tree Diagrams
   A simplified graphical representation edit of the data model a datastore resource is used in
   this document.  The meaning activated upon successful
   completion of the symbols transaction.

1.4.  Coexistence with NETCONF

   RESTCONF can be implemented on a device that supports NETCONF.

   If the device supports :writable-running, all edits to configuration
   nodes in these diagrams {+restconf}/data are performed in the running configuration
   datastore.  The URI template "{+restconf}" is as
   follows:

   o  Brackets "[" and "]" enclose list keys.

   o  Abbreviations before data node names: "rw" means defined in
   Section 1.1.5.

   Otherwise, if the device supports :candidate, all edits to
   configuration
      data (read-write) and "ro" state data (read-only).

   o  Symbols after data node names: "?" means an optional node, "!"
      means a presence container, and "*" denotes a list and leaf-list.

   o  Parentheses enclose choice and case nodes, and case nodes in {+restconf}/data are also
      marked with a colon (":").

   o  Ellipsis ("...") stands for contents of subtrees performed in the
   candidate configuration datastore.  The candidate MUST be
   automatically committed to running immediately after each successful
   edit.  Any edits from other sources that are not
      shown.

2.  Transport Protocol Requirements

2.1.  Integrity and Confidentiality

   HTTP [RFC7230] is an application layer protocol that may in the candidate
   datastore will also be layered
   on any reliable transport-layer protocol.  RESTCONF committed.  If a confirmed-commit procedure is defined on top
   of HTTP, but due to the sensitive nature of
   in progress, then this commit will act as the information conveyed,
   RESTCONF requires that confirming commit.  If
   the transport-layer protocol provides both
   data integrity and confidentiality, such as are provided by server is expecting a "persist-id" parameter to complete the TLS
   protocol [RFC5246].

2.2.  HTTPS with X.509v3 Certificates

   Given
   confirmed commit procedure then the nearly ubiquitous support for HTTP over TLS [RFC7230], RESTCONF implementations edit operation MUST support fail
   with a "409 Conflict" status-line.

   If the "https" URI scheme, which
   has device supports :startup, the IANA assigned default port 443.  Consistent with device automatically copies the
   exclusive use
   content of X.509v3 certificates for NETCONF over TLS [RFC7589],
   use running to startup after running has been updated as a
   consequence of certificates in a RESTCONF is also limited to X.509v3
   certificates.

2.3.  Certificate Validation

   When presented edit operation.

   If a datastore that would be modified by a RESTCONF operation has an X.509 certificate,
   active lock, the RESTCONF peer edit operation MUST use X.509
   certificate path validation [RFC5280] to verify the integrity fail with a "409
   Conflict" status-line.

1.5.  RESTCONF Extensibility

   There are two extensibility mechanisms built into RESTCONF:

   o  protocol version

   o  optional capabilities

   This document defines version 1 of the
   certificate.  The presented X.509 certificate MAY also be considered
   valid if it matches RESTCONF protocol.  If a locally configured certificate fingerprint.  If
   X.509 certificate path validation fails and
   future version of this protocol is defined, then that document will
   specify how the presented X.509
   certificate does not match new version of RESTCONF is identified.  It is
   expected that a locally configured certificate
   fingerprint, the connection MUST different entry point {+restconf2} would be terminated as defined in
   [RFC5246].

2.4.  Authenticated Server Identity defined.
   The RESTCONF client MUST carefully examine the certificate presented
   by the RESTCONF server to determine if will advertise all protocol versions that it meets supports in
   its host-meta data.

   In this example, the client's
   expectations.  The server supports both RESTCONF client MUST check the identity version 1 and a
   fictitious version 2.

      Request
      -------
      GET /.well-known/host-meta HTTP/1.1
      Host: example.com
      Accept: application/xrd+xml

      Response
      --------
      HTTP/1.1 200 OK
      Content-Type: application/xrd+xml
      Content-Length: nnn

   <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
       <Link rel='restconf' href='/restconf'/>
       <Link rel='restconf2' href='/restconf2'/>
   </XRD>
   RESTCONF also supports a server-defined list of the optional
   capabilities, which are listed by a server according to Section 6 of [RFC6125], including processing using the
   outcome as described
   "ietf-restconf-monitoring" module defined in Section 6.6 of [RFC6125].

2.5.  Authenticated Client Identity 9.3.  For
   example, this document defines several query parameters in
   Section 4.8.  Each optional parameter has a corresponding capability
   URI defined in Section 9.1.1 that is advertised by the server if
   supported.

   The RESTCONF "capabilities" list can identify any sort of server MUST authenticate client access extension.
   Typically this extension mechanism is used to any protected
   resource.  If the RESTCONF client identify optional query
   parameters but it is not authenticated limited to access a
   resource, that purpose.  For example, the server MUST send an HTTP response with status code 401
   (Unauthorized), as
   "defaults" URI defined in Section 3.1 of [RFC7235].

   RESTCONF client authentication MUST either use TLS client
   certificates, like NETCONF over TLS [RFC7589], or use 9.1.2 specifies a standard HTTP
   Authentication scheme, see Section 5.1 in [RFC7235]. mandatory URI
   identifying server defaults handling behavior.

   A combination new sub-resource type could be identified with a capability if it
   is optional to implement.  Mandatory protocol features and new
   resource types require a new revision of both client certificates the RESTCONF protocol.

2.  Transport Protocol Requirements

2.1.  Integrity and an Confidentiality

   HTTP Authentication scheme [RFC7230] is also
   allowed, with the determination of how to process this combination
   left as an implementation decision.

   The application layer protocol that may be layered
   on any reliable transport-layer protocol.  RESTCONF client identity derived from the authentication
   mechanism used is hereafter known as defined on top
   of HTTP, but due to the "RESTCONF username" sensitive nature of the information conveyed,
   RESTCONF requires that the transport-layer protocol provides both
   data integrity and
   subject to confidentiality.  A RESTCONF server MUST support
   the NETCONF Access Control Module (NACM) [RFC6536].  For
   when a client certificate is presented, this identity TLS protocol [RFC5246].  The RESTCONF protocol MUST NOT be derived used
   over HTTP without using the algorithm defined TLS protocol.

   HTTP/1.1 pipelining MUST be supported by the server.  Responses MUST
   be sent in Section 7 of [RFC7589].  For all the same order that requests are received.  No other
   cases, when
   versions of HTTP Authentication is used, the identity is provided by are supported for use with RESTCONF.

2.2.  HTTPS with X.509v3 Certificates

   Given the nearly ubiquitous support for HTTP Authentication scheme used.

3.  Resources

   The over TLS [RFC7230],
   RESTCONF protocol operates on a hierarchy of resources, starting
   with implementations MUST support the top-level API resource itself (Section 3.1).  Each resource
   represents a manageable component within "https" URI scheme, which
   has the device.

   A resource can be considered IANA assigned default port 443.

   RESTCONF servers MUST present an X.509v3 based certificate when
   establishing a collection of conceptual data and the
   set of allowed methods on that data.  It can contain nested child
   resources. TLS connection with a RESTCONF client.  The child resource types and methods allowed on them are
   data-model specific.

   A resource has its own media type identifier, represented by exclusive
   use the
   "Content-Type" header in X.509v3 based certificates is consistent with NETCONF over
   TLS [RFC7589].

2.3.  Certificate Validation
   The RESTCONF client MUST use X.509 certificate path validation
   [RFC5280] to verify the HTTP response message.  A resource can
   contain zero or more nested resources.  A resource can be created and
   deleted independently integrity of its parent resource, as long as the parent
   resource exists.

   All RESTCONF resources are defined in this document except specific
   datastore contents, protocol operations, and event notifications.
   The syntax and semantics for these resource types are defined in YANG
   modules. server's TLS
   certificate.  The RESTCONF resources are accessed via presented X.509 certificate MUST also be considered
   valid if it matches a set of URIs defined in this
   document.  The set of YANG modules supported by the server will
   determine the data model specific operations, top-level data node
   resources, locally configured certificate fingerprint.  If
   X.509 certificate path validation fails and event notification messages supported by the server.

   The RESTCONF protocol presented X.509
   certificate does not include match a resource discovery
   mechanism.  Instead, locally configured certificate
   fingerprint, the definitions within connection MUST be terminated as defined in
   [RFC5246].

2.4.  Authenticated Server Identity

   The RESTCONF client MUST check the YANG modules
   advertised by identity of the server are used according
   to construct a predictable
   operation or data resource identifier.

3.1.  Root Resource Discovery

   In line with Section 6 of [RFC6125], including processing the best practices defined by [RFC7320], outcome as
   described in Section 6.6 of [RFC6125].

2.5.  Authenticated Client Identity

   The RESTCONF
   enables deployments server MUST authenticate client access to specify where any protected
   resource.  If the RESTCONF API client is located.
   When first connecting not authorized to access a RESTCONF server,
   resource, the server MUST send an HTTP response with "401
   Unauthorized" status-line, as defined in Section 3.1 of [RFC7235].

   To authenticate a client, a RESTCONF server MUST use TLS based client
   certificates (Section 7.4.6 of [RFC5246]), or MUST
   determine use any HTTP
   authentication scheme defined in the root HTTP Authentication Scheme
   Registry (Section 5.1 in [RFC7235]).  A server MAY also support the
   combination of both client certificates and an HTTP client
   authentication scheme, with the RESTCONF API. determination of how to process this
   combination left as an implementation decision.

   The RESTCONF client discovers this by
   getting identity derived from the "/.well-known/host-meta" resource ([RFC6415]) and using authentication
   mechanism used is hereafter known as the <Link> element containing "RESTCONF username" and
   subject to the "restconf" attribute :

      Request
      -------
      GET /.well-known/host-meta HTTP/1.1
      Host: example.com
      Accept: application/xrd+xml

      Response
      --------
      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>

   Once discovering NETCONF Access Control Module (NACM) [RFC6536].  When
   a client certificate is presented, the RESTCONF API root, the client username MUST prepend it to
   any subsequent request to a RESTCONF resource.  For instance, be
   derived using the "/restconf" path discovered above, algorithm defined in Section 7 of [RFC7589].  For
   all other cases, when HTTP authentication is used, the client can now determine RESTCONF
   username MUST be provided by the operations supported by the the server.  In this example a custom
   "play" operation is supported:

      Request
      -------
      GET /restconf/operations  HTTP/1.1
      Host: example.com
      Accept: application/yang.api+json

      Response
      --------
      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:01:00 GMT
      Server: example-server
      Cache-Control: no-cache
      Pragma: no-cache
      Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT
      Content-Type: application/yang.api+json

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

3.2.  RESTCONF Resource Types HTTP authentication scheme used.

3.  Resources

   The RESTCONF protocol defines operates on a set of application specific media
   types to identify each hierarchy of resources, starting
   with the available resource types.  The
   following resource types are defined in RESTCONF:

              +-----------+---------------------------------+
              | Resource  | Media Type                      |
              +-----------+---------------------------------+
              | API       | application/yang.api+xml        |
              |           | application/yang.api+json       |
              | Datastore | application/yang.datastore+xml  |
              |           | application/yang.datastore+json |
              | Data      | application/yang.data+xml       |
              |           | application/yang.data+json      |
              | Errors    | application/yang.errors+xml     |
              |           | application/yang.errors+json    |
              | Operation | application/yang.operation+xml  |
              |           | application/yang.operation+json |
              | Schema    | application/yang                |
              +-----------+---------------------------------+

                           RESTCONF Media Types

3.3.  API Resource

   The top-level API resource contains the entry points for itself (Section 3.1).  Each resource
   represents a manageable component within the RESTCONF datastore device.

   A resource can be considered a collection of data and operation resources.  It is the top-level set of
   allowed methods on that data.  It can contain nested child resources.
   The child resource located at
   {+restconf} types and methods allowed on them are data-model
   specific.

   A resource has the a media type "application/yang.api+xml" or
   "application/yang.api+json".

   YANG Tree Diagram for an API Resource:

   +--rw restconf
      +--rw data
      +--rw operations

   The "application/yang.api" restconf-media-type extension in identifier, represented by the
   "ietf-restconf" module defined
   "Content-Type" header in Section 8 is used to specify the
   structure and syntax of the conceptual child resources within the API
   resource.

   The API HTTP response message.  A resource can
   contain zero or more nested resources.  A resource can be retrieved with created and
   deleted independently of its parent resource, as long as the GET method.

   This parent
   resource has the following child resources:

            +----------------+--------------------------------+
            | Child Resource | Description                    |
            +----------------+--------------------------------+
            | data           | Contains all data resources    |
            | operations     | Data-model specific operations |
            +----------------+--------------------------------+ exists.

   All RESTCONF API Resource

3.3.1.  {+restconf}/data

   This mandatory resource represents the combined configuration types are defined in this document except
   specific datastore contents, protocol operations, and
   operational data event
   notifications.  The syntax and semantics for these resource types are
   defined in YANG modules.

   The RESTCONF resources that can be are accessed by via a client.  It
   cannot be created or deleted by the client.  The datastore resource
   type is set of URIs defined in Section 3.4.

   Example:

   This example request this
   document.  The set of YANG modules supported 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:

   HTTP/1.1 200 OK
   Date: Mon, 23 Apr 2012 17:01:30 GMT
   Server: example-server
   Cache-Control: no-cache
   Pragma: 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 will
   determine the
   data-model data model specific protocol operations operations, top-level data nodes,
   and event notification messages supported by the server.

   The
   server MAY omit this resource if no data-model specific operations
   are advertised.

   Any data-model specific RESTCONF protocol operations defined in does not include a data resource discovery
   mechanism.  Instead, the definitions within the YANG modules
   advertised by the server MAY be available as child nodes of
   this resource.

   Operation resources are defined in Section 3.6.

3.4.  Datastore Resource

   The "{+restconf}/data" subtree represents the datastore resource
   type, which is used to construct a collection of configuration and operational predictable
   operation or data
   nodes.

   This resource type is an abstraction of identifier.

3.1.  Root Resource Discovery

   In line with the system's underlying
   datastore implementation.  It is used best practices defined by [RFC7320], RESTCONF
   enables deployments to simplify resource editing
   for specify where the client.  The RESTCONF datastore resource API is located.
   When first connecting to a conceptual
   collection RESTCONF server, a RESTCONF client MUST
   determine the root of all configuration and operational data that is present
   on the device.

   Configuration edit transaction management and configuration
   persistence are handled RESTCONF API.  The client discovers this by
   getting the server "/.well-known/host-meta" resource ([RFC6415]) and not controlled by using
   the
   client.  A datastore resource can only be written directly with <Link> element containing the "restconf" attribute :

   Example returning /restconf:

      Request
      -------
      GET /.well-known/host-meta HTTP/1.1
      Host: example.com
      Accept: application/xrd+xml

      Response
      --------
      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
   PATCH method.  Each RESTCONF edit of a datastore resource is saved API root, the client MUST prepend it
   to
   non-volatile storage by any subsequent request to a RESTCONF resource.  In this example,
   the server.

3.4.1.  Edit Collision Detection

   Two "edit collision detection" mechanisms are provided in RESTCONF,
   for datastore and data resources.

3.4.1.1.  Timestamp
   The last change time is maintained and client would use the "Last-Modified"
   ([RFC7232], Section 2.2) header is returned in the response for a
   retrieval request.  The "If-Unmodified-Since" header can be used in
   edit operation requests to cause path "/restconf" as the server to reject RESTCONF entry
   point.

   Example returning /top/restconf:

      Request
      -------
      GET /.well-known/host-meta HTTP/1.1
      Host: example.com
      Accept: application/xrd+xml

      Response
      --------
      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 request if client would use the resource has been modified since path "/top/restconf" as the specified timestamp.
   RESTCONF entry point.

   The server MUST maintain a last-modified timestamp for the top-level
   {+restconf}/data resource and SHOULD maintain last-modified
   timestamps for descendant resources.  For all resources, client can now determine the server
   MUST return operation resources supported by the "Last-Modified" header when
   the resource server.  In this example a custom "play" operation is retrieved
   with the supported:

      Request
      -------
      GET or HEAD methods. /top/restconf/operations  HTTP/1.1
      Host: example.com
      Accept: application/yang.api+json

      Response
      --------
      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:01:00 GMT
      Server: example-server
      Cache-Control: no-cache
      Pragma: no-cache
      Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT
      Content-Type: application/yang.api+json

      { "operations" : { "example-jukebox:play" : {} } }

   If the server does not maintain a
   timestamp for a resource, it MUST return the timestamp of XRD contains more than one link relation, then only the
   resource's ancestor, a process that may recurse up
   relation named "restconf" is relevant to the top-level
   {+restconf}/data resource.  Only changes this specification.

3.2.  RESTCONF Media Types

   The RESTCONF protocol defines a set of application specific media
   types to configuration data
   resources within the datastore affect the timestamp.

3.4.1.2.  Entity tag

   A unique opaque string is maintained and the "ETag" ([RFC7232],
   Section 2.3) header is returned in identify each of the response for a retrieval
   request. available resource types.  The "If-Match" header can be used
   following resource types are defined in edit operation
   requests to cause the server to reject the request if the RESTCONF:

              +-----------+---------------------------------+
              | Resource  | Media Type                      |
              +-----------+---------------------------------+
              | API       | application/yang.api+xml        |
              |           | application/yang.api+json       |
              | Datastore | application/yang.datastore+xml  |
              |           | application/yang.datastore+json |
              | Data      | application/yang.data+xml       |
              |           | application/yang.data+json      |
              | [none]    | application/yang.errors+xml     |
              |           | application/yang.errors+json    |
              | Operation | application/yang.operation+xml  |
              |           | application/yang.operation+json |
              | Schema    | application/yang                |
              +-----------+---------------------------------+

                           RESTCONF Media Types

3.3.  API Resource

   The API resource
   entity tag does not match contains the specified value.

   The server MUST maintain an entity tag entry points for the top-level {+restconf}/
   data resource RESTCONF datastore
   and SHOULD maintain entity tags for descendant operation resources.  For all resources, the server MUST return the "ETag"
   header when  It is the top-level resource is retrieved with located at
   {+restconf} and has the GET media type "application/yang.api+xml" or HEAD methods.
   If the server does not maintain an entity tag
   "application/yang.api+json".

   YANG Tree Diagram for a resource, it MUST
   return the entity tag of an API Resource:

   +--rw restconf
      +--rw data
      +--rw operations
      +--ro yang-library-version

   The "application/yang.api" restconf-media-type extension in the resource's ancestor, a process that may
   recurse up
   "ietf-restconf" module defined in Section 8 is used to specify the top-level {+restconf}/data resource.  Only changes
   to configuration data
   structure and syntax of the conceptual child resources within the datastore affect the
   entity tag.

3.5.  Data Resource

   A data resource represents a YANG data node that is a descendant node
   of a datastore API
   resource.  Each YANG-defined data node

   The API resource can be uniquely
   targeted by retrieved with the request-line of an HTTP operation.  Containers,
   leafs, list entries, anydata and anyxml nodes are data resources.

   The representation maintained for each data GET method.

   This resource is has the YANG
   defined subtree for that node.  HTTP operations on a 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
   affect both represents the targeted data node and all its descendants, if any.

   For combined configuration and
   operational data resources, the server MAY maintain resources that can be accessed by a last-
   modified timestamp for the resource, and return the "Last-Modified"
   header when it is retrieved with the GET client.  It
   cannot be created or HEAD methods.  If
   maintained, deleted by the client.  The datastore resource timestamp MUST be set to
   type is defined in Section 3.4.

   Example:

   This example request by the current time
   whenever client would retrieve only the resource or any non-
   configuration resource 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:

   HTTP/1.1 200 OK
   Date: Mon, 23 Apr 2012 17:01:30 GMT
   Server: example-server
   Cache-Control: no-cache
   Pragma: 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 altered.

   For configuration data resources, a container that provides access to the
   data-model specific protocol operations supported by the server.  The
   server MAY maintain a omit this resource
   entity tag for the resource, and return if no data-model specific operations
   are advertised.

   Any data-model specific protocol operations defined in the "ETag" header when it is
   retrieved YANG
   modules advertised by the server MUST be available as child nodes of
   this resource.

   Operation resources are defined in Section 3.6.

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

   This mandatory leaf identifies the target resource with revision date of the
   "ietf-yang-library" YANG module that is implemented by this server.

   Example:

   GET or HEAD methods.  If
   maintained, the resource entity tag MUST be updated whenever /restconf/yang-library-version  HTTP/1.1
   Host: example.com
   Accept: application/yang.data+xml

   The server might respond (response wrapped for display purposes):

   HTTP/1.1 200 OK
   Date: Mon, 23 Apr 2012 17:01:30 GMT
   Server: example-server
   Cache-Control: no-cache
   Pragma: no-cache
   Content-Type: application/yang.data+xml

   <yang-library-version
     xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
     2016-02-01
   </yang-library-version>

3.4.  Datastore Resource

   The "{+restconf}/data" subtree represents the datastore resource or any
   type, which is a collection of configuration and operational data
   nodes.

   This resource within type is an abstraction of the system's underlying
   datastore implementation.  It is used to simplify resource editing
   for the client.  The RESTCONF datastore resource is
   altered.

   A a conceptual
   collection of all configuration and operational data resource can be retrieved with that is present
   on the GET method.  Data resources device.

   Configuration edit transaction management and configuration
   persistence are accessed via handled by the "{+restconf}/data" entry point.  This sub-tree
   is used to retrieve server and edit data resources. not controlled by the
   client.  A configuration data datastore resource can be altered by the client written directly with some
   or all of the edit operations, depending on the target resource POST
   and
   the specific operation.  Refer to Section 4 for more details on PATCH methods.  Each RESTCONF edit
   operations.

   The resource definition version for of a data datastore resource is identified
   saved to non-volatile storage by the revision date of the YANG module containing the YANG definition
   for the data resource.

3.5.1.  Encoding Data Resource Identifiers in the Request URI

   In YANG, data nodes server.

3.4.1.  Edit Collision Detection

   Two "edit collision detection" mechanisms are named with an absolute XPath expression,
   defined provided in [XPath], starting from the document root to the target
   resource.  In RESTCONF, URL 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 datastore and defines an absolute path location for all data
   nodes.

   A RESTCONF data resource identifier is not an XPath expression.  It resources.

3.4.1.1.  Timestamp

   The last change time is encoded from left to right, starting with the top-level data node,
   according to maintained and the "api-path" rule in "Last-Modified"
   ([RFC7232], Section 3.5.1.1.  The node name
   of each ancestor of the target resource node 2.2) header is encoded returned in order,
   ending with the node name response for the target resource.  If a node
   retrieval request.  The "If-Unmodified-Since" header can be used in
   edit operation requests to cause the
   path is defined in another module than its parent node, then module
   name followed by a colon character (":") is prepended server to reject the node
   name in request if
   the resource identifier.  See Section 3.5.1.1 for details.

   If a data node in has been modified since the path expression is specified timestamp.

   The server MUST maintain a YANG list node, then the
   key values last-modified timestamp for the list (if any) top-level
   {+restconf}/data resource.  This timestamp is only affected by
   configuration data resources, and MUST NOT be encoded according updated for changes to
   non-configuration data.

3.4.1.2.  Entity tag

   A unique opaque string is maintained and 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 "ETag" ([RFC7232],
   Section 2.3) header is
      constructed by having returned in the list name followed by an "=" followed by response for a retrieval
   request.  The "If-Match" header can be used in edit operation
   requests to cause the single key leaf value.

   o  If there are multiple key leaf values, server to reject the value of each leaf
      identified in request if the "key" statement is encoded in resource
   entity tag does not match the order specified in the YANG "key" statement, with a comma separating
      them.

   o value.

   The key value is specified as a string, using the canonical
      representation server MUST maintain an entity tag for the YANG top-level {+restconf}/
   data type.  Any reserved characters resource.  This entity tag is only affected by configuration
   data resources, and MUST NOT be percent-encoded, according updated for changes to [RFC3986], section 2.1.

   o  All non-
   configuration data.

3.4.1.3.  Update Procedure

   Changes to configuration data resources affect the components in timestamp and
   entity tag to that resource, any ancestor data resources, and the "key" statement MUST
   datastore resource.

   For example, an edit to disable an interface might be encoded.
      Partial instance identifiers are not supported.

   o  A missing key value is interpreted a zero-length string.
      (example: list=foo,,baz).

   o  The "list-instance" ABNF rule defined in Section 3.5.1.1
      represents done by setting
   the syntax of a list instance identifier.

   o  Resource URI values returned in Location headers for leaf "/interfaces/interface/enabled" to "false".  The "enabled"
   data
      resources MUST identify node and its ancestors (one "interface" list instance, and the module name, even if there
   "interfaces" container) are no
      conflicting local names considered to be changed.  The datastore
   is considered to be changed when the resource any top-level configuration data
   node is created.  This
      ensures the correct changed (e.g., "interfaces").

3.5.  Data Resource

   A data resource will be identified even if the server
      loads represents a new module YANG data node that is a descendant node
   of a datastore resource.  Each YANG-defined data node can be uniquely
   targeted by the old client does not know about.

   Examples:

   container top {
       list list1 {
           key "key1 key2 key3";
            ... request-line of an HTTP operation.  Containers,
   leafs, leaf-list entries, list list2 {
                key "key4 key5";
                ...
                leaf X { type string; }
            }
        }
    }

   For entries, anydata and anyxml nodes are
   data resources.

   The representation maintained for each data resource is the above YANG definition, URI with key leaf values will be
   encoded as follows (line wrapped
   defined subtree for display purposes only):

    /restconf/data/example-top:top/list1=key1val,key2val,key3val/
       list2=key4val,key5val/X

   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 node.  HTTP operations on a reserved
   characters data resource
   affect both the targeted data node and does not need to be percent-encoded.  The value of
   "key2" is all its descendants, if any.

   For configuration data resources, the empty string, server SHOULD maintain a last-
   modified timestamp for the resource, and return the value of "key3" "Last-Modified"
   header when it is retrieved with the string
   "foo".

   Example URL:

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

3.5.1.1.  ABNF For Data Resource Identifiers

   The "api-path" ABNF syntax is used to construct RESTCONF path
   identifiers:

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

       api-identifier = [module-name ":"] identifier   ;; note 1

       module-name = identifier

       list-instance = api-identifier "=" key-value ["," key-value]*

       key-value = string      ;; note 1

       string = <a quoted GET or unquoted string>

       ;; An identifier MUST NOT start with
       ;; (('X'|'x') ('M'|'m') ('L'|'l'))
       identifier  = (ALPHA / "_")
                     *(ALPHA / DIGIT / "_" / "-" / ".")

   Note 1: The syntax for "api-identifier" and "key-value" HEAD methods.  If
   maintained, the resource timestamp MUST conform be set to the JSON identifier encoding rules in Section 4 of
   [I-D.ietf-netmod-yang-json].

3.5.2.  Defaults Handling

   RESTCONF requires that a server report its default handling mode (see
   Section 9.1.2 for details).  If current time
   whenever the optional "with-defaults" query
   parameter resource or any configuration resource within the
   resource is supported by altered.  If not maintained, then the server, a client may use it to control
   retrieval of default values (see Section 4.8.9 resource timestamp
   for details).

   If the target of a GET method datastore MUST be used instead.

   This timestamp is a only affected by configuration data node that represents a leaf
   that has a default value, resources, and
   MUST NOT be updated for changes to non-configuration data.

   For configuration data resources, the leaf has not been given server SHOULD maintain a value
   yet,
   resource entity tag for the server MUST resource, and return the default value that "ETag" header
   when it is in use by the
   server.

   If retrieved as the target of a resource with the GET method is a data node that represents a
   container or list that has any child resources with default values,
   for HEAD
   methods.  If maintained, the child resources that have resource entity tag MUST be updated
   whenever the resource or any configuration resource within the
   resource is altered.  If not been given value yet, maintained, then the
   server MAY return resource entity tag
   for the default values that are in use datastore MUST be used instead.

   This entity tag is only affected by the server,
   in accordance configuration data resources, and
   MUST NOT be updated for changes to non-configuration data.

   A data resource can be retrieved with its reported default handing mode the GET method.  Data resources
   are accessed via the "{+restconf}/data" entry point.  This sub-tree
   is used to retrieve and query
   parameters passed edit data resources.

   A configuration data resource can be altered by the client.

3.6.  Operation Resource

   An operation resource represents a protocol operation defined client with
   one some
   or all of the YANG "action" or "rpc" statements.  It is invoked using a
   POST method edit operations, depending on the operation resource.

   An RPC operation is invoked as:

   POST {+restconf}/operations/<operation>

   The <operation> field identifies the module name target resource and rpc identifier
   string for
   the desired specific operation.

   For example, if "module-A" defined a "reset" rpc operation, then
   invoking the operation from "module-A" 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>/<operation>

   where <data-resource-identifier> contains the path  Refer to the Section 4 for more details on edit
   operations.

   The resource definition version for a data node
   where the action is defined, and <operation> resource is identified by
   the name revision date of the
   action.

   For example, if "module-A" defined a "reset-all" action YANG module containing the YANG definition
   for the data resource.

3.5.1.  Encoding Data Resource Identifiers 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 "action" or "rpc" statement has Request URI

   In YANG, data nodes are named with an "input" section, then a
   message-body MAY be sent by the client absolute XPath expression,
   defined in [XPath], starting from the request, otherwise document root to the
   request message MUST NOT include target
   resource.  In RESTCONF, URL encoded path expressions are used
   instead.

   A predictable location for a message-body.

   If the operation data resource is successfully invoked, and if important, since
   applications will code to the "action" or
   "rpc" statement has YANG data model module, which uses
   static naming and defines an "output" section, then a message-body MAY be
   sent by absolute path location for all data
   nodes.

   A RESTCONF data resource identifier is not an XPath expression.  It
   is encoded from left to right, starting with the server in top-level data node,
   according to the response, otherwise "api-path" rule in Section 3.5.1.1.  The node name
   of each ancestor of the response message
   MUST NOT include a message-body target resource node is encoded in order,
   ending with the response message, and MUST
   send a "204 No Content" status-line instead. node name for the target resource.  If a node in the operation
   path is not successfully invoked, defined in another module than its parent node, then a message-body
   SHOULD be sent module
   name followed by a colon character (":") is prepended to the server, containing an "errors" resource, as
   defined node
   name in the resource identifier.  See Section 3.9.

3.6.1.  Encoding Operation Input Parameters 3.5.1.1 for details.

   If the "action" or "rpc" statement has an "input" section, then the
   "input" a data node is provided in the message-body, corresponding to the
   YANG data definition statements within the "input" section.

   Example:

   The following YANG definition path expression is used for a YANG leaf-list node, then
   the examples in this
   section.

     module example-ops {
      namespace "https://example.com/ns/example-ops";
      prefix "ops";

       rpc reboot {
         input {
           leaf delay {
             units seconds;
             type uint32;
             default 0;
           }
           leaf message { type string; }
           leaf language { type string; }
         }
       }
       rpc get-reboot-info {
         output {
           leaf reboot-time {
             units seconds;
             type uint32;
           }
           leaf message { type string; }
           leaf language { type string; }
         }
       }
     }

   The client might send leaf-list value MUST be encoded according to the following POST request message:

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

   <input xmlns="https://example.com/ns/example-ops">
    <delay>600</delay>
    <message>Going down rules:

   o  The instance-identifier for system maintenance</message>
    <language>en-US</language>
   </input> the leaf-list MUST be encoded using
      one path segment [RFC3986].

   o  The server might respond:

   HTTP/1.1 204 No Content
   Date: Mon, 25 Apr 2012 11:01:00 GMT
   Server: example-server

3.6.2.  Encoding Operation Output Parameters

   If path segment is constructed by having the "action" or "rpc" statement has leaf-list name,
      followed by an "output" section, then "=" character, followed by the
   "output" leaf-list value.
      (e.g., /restconf/data/top-leaflist=fred).

   If a data node is provided in the message-body, corresponding to the path expression is a YANG data definition statements within list node, then the "output" section.

   Example:

   The "example-ops" YANG module defined in Section 3.6.1 is used
   key values for the examples in this section.

   The client might send list (if any) MUST be encoded according to the
   following POST request message:

   POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1
   Host: example.com
   Accept: application/yang.operation+json rules:

   o  The server might respond:

      HTTP/1.1 200 OK
      Date: Mon, 25 Apr 2012 11:10:30 GMT
      Server: example-server
      Content-Type: application/yang.operation+json

      {
        "example-ops:output" : {
          "reboot-time" : 30,
          "message" : "Going down key leaf values for system maintenance",
          "language" : "en-US"
        }
      }

3.6.3.  Encoding Operation Errors a data resource representing a YANG list
      MUST be encoded using one path segment [RFC3986].

   o  If any errors occur while attempting to invoke there is only one key leaf value, the operation, then an
   "errors" data structure path segment is returned with
      constructed by having the appropriate error
   status.

   Using list name, followed by an "=" character,
      followed by the "reset" operation example above, single key leaf value.

   o  If there are multiple key leaf values, the client might send path segment is
      constructed by having the
   following POST request message:

   POST /restconf/operations/example-ops:reboot HTTP/1.1
   Host: example.com
   Content-Type: application/yang.operation+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: Mon, 25 Apr 2012 11:10:30 GMT
   Server: example-server
   Content-Type: application/yang.errors+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:err="https://example.com/ns/example-ops">
       err:input/err:delay
     </error-path>
     <error-message>Invalid input parameter</error-message>
    </error>
   </errors>

3.7.  Schema Resource

   The server can optionally support retrieval list name, followed by the value of each
      leaf identified in the YANG modules it
   supports, using "key" statement, encoded in the "ietf-yang-library" module, defined order
      specified in
   [I-D.ietf-netconf-yang-library].

   To retrieve a the YANG module, "key" statement.  Each key leaf value except
      the last one is followed by a client first needs to get comma character.

   o  The key value is specified as a string, using the URL canonical
      representation for
   retrieving the schema.

   The client might send the following GET request message:

   GET /restconf/data/ietf-yang-library:modules/module=
       example-jukebox,2014-07-03/schema HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond:

      HTTP/1.1 200 OK
      Date: Mon, 25 Apr 2012 11:10:30 GMT
      Server: example-server
      Content-Type: application/yang.data+json

      {
        "ietf-yang-library:schema":
         "https://example.com/mymodules/example-jukebox/2015-06-04"
      }

   Next the client needs YANG data type.  Any reserved characters
      MUST be percent-encoded, according to retrieve [RFC3986], section 2.1.

   o  All the actual YANG schema.

   The client might send components in the following GET request message:

   GET https://example.com/mymodules/example-jukebox/2015-06-04
      HTTP/1.1
   Host: example.com
   Accept: application/yang "key" statement MUST be encoded.
      Partial instance identifiers are not supported.

   o  Since missing key values are not allowed, two consecutive commas
      are interpreted as a zero-length string.  (example:
      list=foo,,baz).

   o  The server might respond:

      module example-jukebox {

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

      }

3.8.  Event Stream Resource

   An "event stream" resource "list-instance" ABNF rule defined in Section 3.5.1.1
      represents the syntax of a source list instance identifier.

   o  Resource URI values returned in Location headers for system generated
   event notifications.  Each stream is created and modified by data
      resources MUST identify the
   server only.  A client can retrieve a stream resource or initiate a
   long-poll server sent event stream, using module name, even if there are no
      conflicting local names when the procedure specified in
   Section 6.3.

   A notification stream functions according to resource is created.  This
      ensures the NETCONF
   Notifications specification [RFC5277].  The available streams can correct resource will be
   retrieved from the stream list, which specifies identified even if the syntax and
   semantics of a stream resource.

3.9.  Errors Media Type

   An "errors" media type is server
      loads a collection of error information new module that is
   sent as the message-body in a server response message, if an error
   occurs while processing a request message.  It is old client does not considered know about.

   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, a target resource type because no instances can URI for leaf "X"
   would be retrieved with encoded as follows (line wrapped for display purposes only):

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

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

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

   The "ietf-restconf" YANG module 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
   characters and does not need to be percent-encoded.  The value of
   "key2" is the "application/
   yang.errors" restconf-media-type extension which specifies the syntax empty string, and semantics the value of an "errors" media type.  RESTCONF error handling
   behavior "key3" is defined in Section 7.

4.  Operations

   The RESTCONF protocol uses HTTP methods to identify the CRUD
   operation requested for a particular resource. string
   "foo".

   Example URL:

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

3.5.1.1.  ABNF For Data Resource Identifiers

   The following table shows how the RESTCONF operations relate "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to
   NETCONF protocol operations:

         +----------+--------------------------------------------+
         |
   construct RESTCONF path identifiers:

       api-path = "/"  | NETCONF                                    |
         +----------+--------------------------------------------+
         | OPTIONS  | none                                       |
         | HEAD     | none                                       |
         | GET      | <get-config>, <get>                        |
         | POST     | <edit-config> (operation="create")         |
         | PUT      | <edit-config> (operation="create/replace") |
         | PATCH
                  ("/" api-identifier
                    0*("/" (api-identifier | <edit-config> (operation="merge")          |
         | DELETE   | <edit-config> (operation="delete")         |
         +----------+--------------------------------------------+

                     Table list-instance )))

       api-identifier = [module-name ":"] identifier   ;; note 1

       module-name = identifier

       list-instance = api-identifier "=" key-value ["," key-value]*

       key-value = string      ;; note 1

       string = <a quoted or unquoted string>

       ;; An identifier MUST NOT start with
       ;; (('X'|'x') ('M'|'m') ('L'|'l'))
       identifier  = (ALPHA / "_")
                     *(ALPHA / DIGIT / "_" / "-" / ".")

   Note 1: CRUD Methods The syntax for "api-identifier" and "key-value" MUST conform
   to the JSON identifier encoding rules in Section 4 of
   [I-D.ietf-netmod-yang-json].

3.5.2.  Defaults Handling

   RESTCONF

   The NETCONF "remove" operation attribute requires that a server report its default handling mode (see
   Section 9.1.2 for details).  If the optional "with-defaults" query
   parameter is not supported by the HTTP
   DELETE method.  The resource must exist or the DELETE method will
   fail.  The PATCH method is equivalent to a "merge" operation when
   using server, a plain patch (see Section 4.6.1), other media-types may
   provide more granular control.

   Access control mechanisms client may be used use it to limit what operations can be
   used.  In particular, RESTCONF control
   retrieval of default values (see Section 4.8.9 for details).

   If a leaf or leaf-list is compatible with missing from the NETCONF Access
   Control Model (NACM) [RFC6536], as configuration and there is
   a specific mapping
   between RESTCONF and NETCONF operations, defined in Table 1.  The
   resource path needs to be converted internally by YANG-defined default for that data resource, then the server to MUST
   use the
   corresponding YANG instance-identifier.  Using this information, YANG-defined default as the
   server can apply configured value.

   If the NACM access control rules to RESTCONF messages.

   The server MUST NOT allow any operation to any resources that the
   client is not authorized to access.

   Implementation target of all methods (except PATCH) are defined in
   [RFC7231].  This section defines the RESTCONF protocol usage for each
   HTTP method.

4.1.  OPTIONS

   The OPTIONS a GET method is sent by the client to discover which methods
   are supported by the server for a specific resource (e.g., GET, POST,
   DELETE, etc.).

   The server SHOULD implement this method, however the same information
   could be extracted from the YANG modules data node that represents a leaf
   that has a default value, and the RESTCONF protocol
   specification.

   If the PATCH method is supported, then leaf has not been given a value
   yet, the "Accept-Patch" header server MUST
   be supported and returned in the response to return the OPTIONS request, as
   defined in [RFC5789].

4.2.  HEAD

   The HEAD method default value that is sent in use by the client to retrieve just
   server.

   If the headers target of a GET method is a data node that would be returned represents a
   container or list that has any child resources with default values,
   for the comparable GET method, without child resources that have not been given value yet, the
   response message-body.  It is supported for all resource types,
   except operation resources.

   The request MUST contain a request URI
   server MAY return the default values that contains at least are in use by the
   entry point.  The same server,
   in accordance with its reported default handing mode and query
   parameters supported passed by the GET method
   are supported by client.

3.6.  Operation Resource

   An operation resource represents a protocol operation defined with
   the HEAD method.

   The access control behavior is enforced as if the method was GET
   instead of HEAD.  The server MUST respond the same as if the method
   was GET instead of HEAD, except that no response message-body YANG "rpc" statement or a data-model specific action defined with
   a YANG "action" statement.  It is
   included.

4.3.  GET

   The GET invoked using a POST method is sent by on the client to retrieve data and meta-data
   for a
   operation resource.  It is supported for all resource types, except

   An RPC operation resources. is invoked as:

   POST {+restconf}/operations/<operation>

   The request MUST contain a request URI that
   contains at least <operation> field identifies the entry point.

   The server MUST NOT return any data resources module name and rpc identifier
   string for which the user does
   not have read privileges.  If the user is not authorized to read the
   target resource, an error response containing desired operation.

   For example, if "module-A" defined a "403 Forbidden" or
   "404 Not Found" status-line is returned to the client.

   If "reset" rpc operation, then
   invoking the user operation from "module-A" would be requested as follows:

   POST /restconf/operations/module-A:reset HTTP/1.1
   Server example.com

   An action is authorized invoked as:

   POST {+restconf}/data/<data-resource-identifier>/<action>

   where <data-resource-identifier> contains the path to read some but not all of the target
   resource, data node
   where the unauthorized content action is omitted from the response
   message-body, defined, and the authorized content <action> is returned to the client.

   Example:

   The client might request the response headers for an XML
   representation name of the action.

   For example, if "module-A" defined a specific "album" resource:

   GET /restconf/data/example-jukebox:jukebox/
      library/artist=Foo%20Fighters/album=Wasting%20Light "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
   Host:
   Server example.com
   Accept: application/yang.data+xml

   The server might respond:

   HTTP/1.1 200 OK
   Date: Mon, 23 Apr 2012 17:02:40 GMT
   Server: example-server
   Content-Type: application/yang.data+xml
   Cache-Control: no-cache
   Pragma: no-cache
   ETag: a74eefc993a2b
   Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT

   <album xmlns="http://example.com/ns/example-jukebox">
    <name>Wasting Light</name>
    <genre xmlns:g="http://example.com/ns/example-jukebox">
      g:alternative
    </genre>
    <year>2011</2011>
   </album>

4.4.  POST

   The POST method is

   If the "rpc" or "action" statement has an "input" section, then a
   message-body MAY be sent by the client to create a data resource or
   invoke an operation resource.  The server uses in the target resource
   media type to determine how to process request, otherwise the request.

      +-----------+------------------------------------------------+
      | Type      | Description                                    |
      +-----------+------------------------------------------------+
      | Datastore | Create a top-level configuration data resource |
      | Data      | Create
   request message MUST NOT include a configuration data child resource     |
      | Operation | Invoke message-body.  If the "input"
   section contains mandatory parameters, then a protocol operation                    |
      +-----------+------------------------------------------------+

                     Resource Types that Support POST

4.4.1.  Create Resource Mode message-body MUST be
   sent by the client.

   If the target resource type operation is a datastore invoked without errors, and if the "rpc" or data resource,
   "action" statement has an "output" section, then the
   POST is treated as a request to create a top-level resource or child
   resource, respectively.  The message-body is expected to contain MAY
   be sent by the
   content of server in the response, otherwise the response message
   MUST NOT include a child resource to create within message-body in the parent (target
   resource).  The data-model for response message, and MUST
   send a "204 No Content" status-line instead.

   If the child tree operation input is not valid, or the subtree operation is
   defined invoked but
   errors occur, then a message-body MUST be sent by YANG for the child resource.

   The "insert" and "point" query parameters are supported by the POST
   method for datastore and data resource types, server,
   containing an "errors" resource, as specified in the
   YANG definition defined in Section 8.

   If the POST method succeeds, a "201 Created" status-line is returned
   and there is no response message-body. 3.9.  A "Location" header
   identifying the child
   detailed example of an operation resource that was created MUST error response can be present found
   in Section 3.6.3.

   All operation resources representing RPC operations supported by the response
   server MUST be identified in this case.

   If the user is not authorized to create the target resource, an error
   response containing a "403 Forbidden" or "404 Not Found" status-line
   is returned to the client.  All other error responses are handled
   according to the procedures {+restconf}/operations subtree
   defined in Section 7.

   Example:

   To create 3.3.2.  Operation resources representing YANG
   actions are not identified in this subtree since they are invoked
   using a new "jukebox" resource, the client might send:

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

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

   If the resource is created, the server might respond as follows.
   Note that URI within the "Location" header line is wrapped for display purposes
   only:

   HTTP/1.1 201 Created
   Date: Mon, 23 Apr 2012 17:01:00 GMT
   Server: example-server
   Location: https://example.com/restconf/data/
       example-jukebox:jukebox
   Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT
   ETag: b3a3e673be2

   Refer to Appendix D.2.1 for more resource creation examples.

4.4.2.  Invoke {+restconf}/data subtree.

3.6.1.  Encoding Operation Mode Resource Input Parameters

   If the target resource type is "rpc" or "action" statement has an operation resource, "input" section, then the POST
   method
   "input" node is treated as a request provided in the message-body, corresponding to invoke that operation.  The
   message-body (if any) is processed as the operation input parameters.
   Refer to Section 3.6 for details on operation resources.

   If the POST request succeeds, a "200 OK" status-line is returned if
   there is a response message-body, and a "204 No Content" status-line
   is returned if there is no response message-body.

   If the user is not authorized to invoke the target operation, an
   error response containing a "403 Forbidden" or "404 Not Found"
   status-line is returned to the client.  All other error responses are
   handled according to the procedures defined in Section 7.

   Example:

   In this example,
   YANG data definition statements within the client "input" section.

   Examples:

   The following YANG module is invoking used for the "play" RPC operation defined examples in the "example-jukebox" YANG module.

   A client might send a "play" request as follows:

      POST /restconf/operations/example-jukebox:play   HTTP/1.1
      Host: example.com
      Content-Type: application/yang.operation+json
   this section.

   module example-ops {
        "example-jukebox:input" :
     namespace "https://example.com/ns/example-ops";
     prefix "ops";
     revision "2016-03-10";

     rpc reboot {
          "playlist" : "Foo-One",
          "song-number" : 2
       input {
         leaf delay {
           units seconds;
           type uint32;
           default 0;
         }
         leaf message { type string; }

   The server might respond:

   HTTP/1.1 204 No Content
   Date: Mon, 23 Apr 2012 17:50:00 GMT
   Server: example-server

4.5.  PUT

   The PUT method is sent by the client to create or replace the target
   resource.

   The only target resource media
         leaf language { type that supports PUT is the data
   resource. string; }
       }
     }

     rpc get-reboot-info {
       output {
         leaf reboot-time {
           units seconds;
           type uint32;
         }
         leaf message { type string; }
         leaf language { type string; }
       }
     }
   }

   The message-body following YANG module is expected to contain the content used
   to create or replace the target resource.

   The "insert" (Section 4.8.4) and "point" (Section 4.8.5) query
   parameters are supported by the PUT method for data resources.

   Consistent with [RFC7231], if the PUT request creates a new resource,
   a "201 Created" status-line is returned.  If an existing resource is
   modified, either "200 OK" or "204 No Content" are returned.

   If the user is not authorized to create or replace the target
   resource an error response containing a "403 Forbidden" or "404 Not
   Found" status-line is returned to the client.  All other error
   responses are handled according to the procedures defined in
   Section 7.

   Example:

   An "album" child resource defined in the "example-jukebox" YANG action examples in
   this section.

   module is replaced or created if it does not already exist.

   To replace the "album" resource contents, the example-actions {
     yang-version 1.1;
     namespace "https://example.com/ns/example-actions";
     prefix "act";
     import ietf-yang-types { prefix yang; }
     revision "2016-03-10";

     container interfaces {
       list interface {
         key name;
         leaf name { type string; }

         action reset {
           input {
             leaf delay {
               units seconds;
               type uint32;
               default 0;
             }
           }
         }

         action get-last-reset-time {
           output {
             leaf last-reset {
               type yang:date-and-time;
               mandatory true;
             }
           }
         }
       }
     }

   }

   RPC Input Example:

   The client might send as
   follows.  Note that the request-line is wrapped for display purposes
   only:

      PUT /restconf/data/example-jukebox:jukebox/
          library/artist=Foo%20Fighters/album=Wasting%20Light 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+json

      {
        "example-jukebox:album" : {
          "name" : "Wasting Light",
          "genre" : "example-jukebox:alternative",
          "year" : 2011
        }
      }

   If the resource is updated, the application/yang.operation+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:

   HTTP/1.1 204 No Content
   Date: Mon, 23 25 Apr 2012 17:04:00 11:01:00 GMT
   Server: example-server
   Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT
   ETag: b27480aeda4c

4.6.  PATCH

   RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide
   an extensible framework for resource patching mechanisms.  It

   The same example request message is
   optional to implement by the server.  Each patch type needs a unique
   media type.  Zero or more PATCH media types MAY be supported by the
   server. shown here using JSON encoding:

      POST /restconf/operations/example-ops:reboot HTTP/1.1
      Host: example.com
      Content-Type: application/yang.operation+json
      {
        "example-ops:input" : {
          "delay" : 600,
          "message" : "Going down for system maintenance",
          "language" : "en-US"
        }
      }

   Action Input Example:

   The media types supported by a server can be discovered by
   the client by sending an OPTIONS request (see Section 4.1).

   If might send the target resource instance does not exist, following POST request message to invoke
   the "reset" action (text wrap for display purposes):

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

   <input xmlns="https://example.com/ns/example-actions">
     <delay>600</delay>
   </input>

   The server MUST NOT
   create it.

   If the PATCH request succeeds, a "200 OK" status-line is returned if
   there is a message-body, and "204 might respond:

   HTTP/1.1 204 No Content" is returned if no
   response message-body Content
   Date: Mon, 25 Apr 2012 11:01:00 GMT
   Server: example-server

   The same example request message is sent. shown here using JSON encoding
   (text wrap for display purposes):

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

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

3.6.2.  Encoding Operation Resource Output Parameters

   If the user is not authorized to alter the target resource an error
   response containing a "403 Forbidden" "rpc" or "404 Not Found" status-line "action" statement has an "output" section, then the
   "output" node is returned to provided in the client.  All other error responses are handled
   according message-body, corresponding to the procedures defined in Section 7.

4.6.1.  Plain Patch
   The plain patch mechanism merges the contents of the message body
   with the target resource.  If the target resource is a datastore
   resource (see Section 3.4), the message body MUST be either
   application/yang.datastore+xml or application/yang.datastore+json.
   If then the target resource is a
   YANG data resource (see Section 3.5),
   then the message body MUST be either application/yang.data+xml or
   application/yang.data+json.

   Plain patch can used to create or update, but not delete, a child
   resource definition statements within the target resource.  Please see
   [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting
   more granular control. "output" section.

   Examples:

   RPC Output Example:

   The "example-ops" YANG Patch Media Type allows multiple
   sub-operations (e.g., merge, delete) within a single PATCH operation.

   Example:

   To replace just the "year" field module defined in the "album" resource (instead of
   replacing the entire resource with the PUT method), the Section 3.6.1 is used for
   this example.

   The client might send a plain patch as follows.  Note that the request-line is wrapped
   for display purposes only:

   PATCH /restconf/data/example-jukebox:jukebox/
       library/artist=Foo%20Fighters/album=Wasting%20Light 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
   If-Match: b8389233a4c
   Content-Type: application/yang.data+xml

   <album xmlns="http://example.com/ns/example-jukebox">
    <year>2011</year>
   </album>

   If the field is updated, the
   Accept: application/yang.operation+json

   The server might respond:

      HTTP/1.1 204 No Content 200 OK
      Date: Mon, 23 25 Apr 2012 17:49:30 11:10:30 GMT
      Server: example-server
   Last-Modified:
      Content-Type: application/yang.operation+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: Mon, 23 25 Apr 2012 17:49:30 11:10:30 GMT
   ETag: b2788923da4c

4.7.  DELETE
   Server: example-server
   Content-Type: application/yang.operation+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 DELETE method "example-actions" YANG module defined in Section 3.6.1 is used to delete the target resource.  If
   for this example.

   The client might send the
   DELETE following POST request succeeds, a "204 No Content" status-line is returned,
   and there is no response message-body.

   If message to invoke
   the user is not authorized "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.operation+json

   The server might respond:

      HTTP/1.1 200 OK
      Date: Mon, 25 Apr 2012 11:10:30 GMT
      Server: example-server
      Content-Type: application/yang.operation+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 delete invoke the target resource operation or
   action, then an
   error response containing a "403 Forbidden" or "404 Not Found"
   status-line "errors" media type is returned to with the client.  All other appropriate
   error responses are
   handled according to status.

   Using the procedures defined "reboot" operation from the example in Section 7.

   Example:

   To delete a resource such as the "album" resource, 3.6.1, the
   client might
   send:

   DELETE /restconf/data/example-jukebox:jukebox/
       library/artist=Foo%20Fighters/album=Wasting%20Light send the following POST request message:

   POST /restconf/operations/example-ops:reboot HTTP/1.1
   Host: example.com

   If the resource is deleted, the
   Content-Type: application/yang.operation+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: respond with an "invalid-value" error:

   HTTP/1.1 204 No Content 400 Bad Request
   Date: Mon, 23 25 Apr 2012 17:49:40 11:10:30 GMT
   Server: example-server

4.8.  Query Parameters

   Each RESTCONF operation allows zero or more query parameters to be
   present in the request URI.
   Content-Type: application/yang.errors+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 specific parameters that are allowed
   depends on the resource type, and sometimes the specific target
   resource used, same response is shown here in the request.

   +-------------------+-------------+---------------------------------+
   | Name              | Methods     | Description                     |
   +-------------------+-------------+---------------------------------+
   | content           | GET         | Select config and/or non-config |
   |                   |             | data resources                  |
   | depth             | GET         | Request limited sub-tree depth  |
   |                   |             | in the reply content            |
   | fields            | GET         | JSON encoding:

      HTTP/1.1 400 Bad Request a subset
      Date: Mon, 25 Apr 2012 11:10:30 GMT
      Server: example-server
      Content-Type: application/yang.errors+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 retrieval of the target  |
   |                   |             | resource contents               |
   | filter            | GET         | Boolean notification filter for |
   |                   |             | event stream resources          |
   | insert            | POST, PUT   | Insertion mode for user-ordered |
   |                   |             | data resources                  |
   | point             | POST, PUT   | Insertion point for user-       |
   |                   |             | ordered data resources          |
   | start-time        | GET         | Replay buffer start time for    |
   |                   |             | event stream resources          |
   | stop-time         | GET         | Replay buffer stop time for     |
   |                   |             | event stream resources          |
   | with-defaults     | GET         | Control YANG modules it
   supports.  If retrieval of default    |
   |                   |             | values                          |
   +-------------------+-------------+---------------------------------+

                         RESTCONF Query Parameters

   Query parameters can is supported, then the "schema" leaf MUST be given
   present in any order.  Each parameter can
   appear at most once the associated "module" list entry, defined in
   [I-D.ietf-netconf-yang-library].

   To retrieve a request URI.  A default value may apply if
   the parameter is missing.

   Refer YANG module, a client first needs to Appendix D.3 get the URL for examples of query parameter usage.

   If vendors define additional query parameters, they SHOULD use a
   prefix (such as
   retrieving the enterprise or organization name) for query
   parameter names in order to avoid collisions with other parameters.

4.8.1.  The "content" Query Parameter

   The "content" parameter controls how descendant nodes of the
   requested data nodes will be processed schema, which is stored in the reply.

   The allowed values are:

    +-----------+-----------------------------------------------------+
    | Value     | Description                                         |
    +-----------+-----------------------------------------------------+
    | config    | Return only configuration descendant data nodes     |
    | nonconfig | Return only non-configuration descendant data nodes |
    | all       | Return all descendant data nodes                    |
    +-----------+-----------------------------------------------------+

   This parameter is only allowed for GET methods on datastore and data
   resources.  A 400 Bad Request error "schema" leaf.  Note
   that there is returned if used no required structure for other
   methods or resource types. this URL.  The default value is determined by the "config" statement value of
   the requested data nodes.  If the "config" URL value
   shown below is "false", then the
   default for the "content" parameter is "nonconfig".  If "config" is
   "true" then just an example.

   The client might send the default for following GET request message:

   GET /restconf/data/ietf-yang-library:modules/module=
       example-jukebox,2015-04-04/schema HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond:

      HTTP/1.1 200 OK
      Date: Thu, 11 Feb 2016 11:10:30 GMT
      Server: example-server
      Content-Type: application/yang.data+json

      {
        "ietf-yang-library:schema":
         "https://example.com/mymodules/example-jukebox/2015-04-04"
      }

   Next the "content" parameter is "config".

   This query parameter MUST be supported by client needs to retrieve the server.

4.8.2.  The "depth" Query Parameter actual YANG schema.

   The "depth" parameter is used to specify client might send the number of nest levels
   returned in a response for a following GET method. request message:

   GET https://example.com/mymodules/example-jukebox/2015-04-04
      HTTP/1.1
   Host: example.com
   Accept: application/yang

   The first nest-level
   consists of the requested data node itself.  If the "fields"
   parameter (Section 4.8.3) is used to select descendant data nodes,
   these nodes all have a depth value server might respond:

      HTTP/1.1 200 OK
      Date: Thu, 11 Feb 2016 11:10:31 GMT
      Server: example-server
      Content-Type: application/yang

      module example-jukebox {

         // contents of 1.  Any child nodes which are
   contained within a parent node have YANG module deleted for this example...

      }

3.8.  Event Stream Resource

   An "event stream" resource represents a depth value that is 1 greater
   than its parent.

   The value of the "depth" parameter source for system generated
   event notifications.  Each stream is either an integer between 1 created and
   65535, or the string "unbounded".  "unbounded" is modified by the default.

   This parameter is only allowed for GET methods on API, datastore, and
   data resources.
   server only.  A 400 Bad Request error is returned if it used for
   other methods or client can retrieve a stream resource types.

   By default, the server will include all sub-resources within or initiate a
   long-poll server sent event stream, using the procedure specified in
   Section 6.3.

   A notification stream functions according to the NETCONF
   Notifications specification [RFC5277].  The available streams can be
   retrieved resource, which have from the same resource type as stream list, which specifies the
   requested resource.  Only one level syntax and
   semantics of sub-resources with a different stream resource.

3.9.  Errors Media Type
   An "errors" media type than the target resource will be returned.

   If the "depth" query parameter URI is listed in a collection of error information that is
   sent as the "capability"
   leaf-list message-body in Section 9.3, then the a server supports the "depth" query
   parameter.

4.8.3.  The "fields" Query Parameter

   The "fields" query parameter is used to optionally identify data
   nodes within the target response message, if an error
   occurs while processing a request message.  It is not considered a
   resource to type because no instances can be retrieved in with a GET method.
   request.

   The client can use this parameter to retrieve a subset of all nodes
   in a resource.

   A value of "ietf-restconf" YANG module contains the "fields" query parameter matches "application/
   yang.errors" restconf-media-type extension which specifies the following rule:

   fields-expr = path '(' fields-expr ')' /
                 path ';' fields-expr /
                 path
   path = api-identifier [ '/' path ]

   "api-identifier" syntax
   and semantics of an "errors" media type.  RESTCONF error handling
   behavior is defined in Section 3.5.1.1.

   ";" is used to select multiple nodes.  For example, 7.

4.  Operations

   The RESTCONF protocol uses HTTP methods to retrieve only identify the "genre" and "year" of an album, use: "fields=genre;year".

   Parentheses are used to specify sub-selectors of CRUD
   operation requested for a node.

   For example, assume particular resource.

   The following table shows how the target resource RESTCONF operations relate to
   NETCONF protocol operations:

         +----------+--------------------------------------------+
         | RESTCONF | NETCONF                                    |
         +----------+--------------------------------------------+
         | OPTIONS  | none                                       |
         | HEAD     | none                                       |
         | GET      | <get-config>, <get>                        |
         | POST     | <edit-config> (operation="create")         |
         | POST     | invoke any operation                       |
         | PUT      | <edit-config> (operation="create/replace") |
         | PATCH    | <edit-config> (operation="merge")          |
         | DELETE   | <edit-config> (operation="delete")         |
         +----------+--------------------------------------------+

                         CRUD Methods in RESTCONF

   The NETCONF "remove" operation attribute is not supported by the "album" list.  To
   retrieve only the "label" and "catalogue-number" of HTTP
   DELETE method.  The resource must exist or the "admin"
   container within an album, use:
   "fields=admin(label;catalogue-number)".

   "/" DELETE method will
   fail.  The PATCH method is used in a path equivalent to retrieve a child node of "merge" operation when
   using a node.  For
   example, plain patch (see Section 4.6.1); other media-types may
   provide more granular control.

   Access control mechanisms MUST be used to retrieve only limit what operations can
   be used.  In particular, RESTCONF is compatible with the "label" of an album, use: "fields=admin
   /label".

   This parameter NETCONF
   Access Control Model (NACM) [RFC6536], as there is only allowed for GET methods on api, datastore, a specific mapping
   between RESTCONF and
   data resources.  A 400 Bad Request error is returned if used for
   other methods or NETCONF operations, defined in Section 4.  The
   resource types.

   If path needs to be converted internally by the "fields" query parameter URI is listed in server to the "capability"
   leaf-list in Section 9.3, then
   corresponding YANG instance-identifier.  Using this information, the
   server supports can apply the "fields"
   parameter.

4.8.4.  The "insert" Query Parameter NACM access control rules to RESTCONF messages.

   The "insert" parameter server MUST NOT allow any operation to any resources that the
   client is used not authorized to access.

   Operations are applied to specify how a single data resource should instance at once.
   The server MUST NOT allow any operation to be
   inserted within applied to multiple
   instances of a user-ordered list. YANG list or leaf-list.

   Implementation of all methods (except PATCH) are defined in
   [RFC7231].  This section defines the RESTCONF protocol usage for each
   HTTP method.

4.1.  OPTIONS

   The allowed values are:

   +-----------+-------------------------------------------------------+
   | Value     | Description                                           |
   +-----------+-------------------------------------------------------+
   | first     | Insert OPTIONS method is sent by the new data as client to discover which methods
   are supported by the new first entry.           |
   | last      | Insert server for a specific resource (e.g., GET, POST,
   DELETE, etc.).  The server MUST implement this method.

   If the new data as PATCH method is supported, then the new last entry.            |
   | before    | Insert "Accept-Patch" header MUST
   be supported and returned in the new data before response to the insertion point, OPTIONS request, as    |
   |           | specified
   defined in [RFC5789].

4.2.  HEAD

   The HEAD method is sent by the value of client to retrieve just the "point" parameter.      |
   | after     | Insert headers
   that would be returned for the new data after comparable GET method, without the insertion point, as     |
   |           | specified
   response message-body.  It is supported for all resource types,
   except operation resources.

   The request MUST contain a request URI that contains at least the
   entry point.  The same query parameters supported by the value of GET method
   are supported by the "point" parameter.      |
   +-----------+-------------------------------------------------------+ HEAD method.

   The default value access control behavior is "last".

   This parameter enforced as if the method was GET
   instead of HEAD.  The server MUST respond the same as if the method
   was GET instead of HEAD, except that no response message-body is only supported for
   included.

4.3.  GET

   The GET method is sent by the POST client to retrieve data and PUT methods. meta-data
   for a resource.  It is
   also only supported if the target for all resource is types, except
   operation resources.  The request MUST contain a data resource, and request URI that
   contains at least the entry point.

   The server MUST NOT return any data represents a YANG list or leaf-list that is ordered by resources for which the
   user. user does
   not have read privileges.  If the values "before" or "after" are used, then a "point" query
   parameter for the insertion parameter MUST also be present, or a 400
   Bad Request error is returned.

   The "insert" query parameter MUST be supported by the server.

4.8.5.  The "point" Query Parameter

   The "point" parameter user is used not authorized to specify read the insertion point for
   target resource, an error response containing a
   data resource that is being created or moved within "403 Forbidden"
   status-line SHOULD be returned.  A server MAY return a user ordered
   list or leaf-list.

   The value of "404 Not
   Found" status-line, as described in section 6.5.3 in [RFC7231].

   If the "point" parameter user is a string that identifies the
   path authorized to read some but not all of the insertion point object.  The format is the same as a target resource URI string.

   This parameter
   resource, the unauthorized content is only supported for omitted from the POST response
   message-body, and PUT methods.  It the authorized content is
   also only supported if returned to the target resource client.

   If any content is returned to the client, then the server MUST send a
   valid response message-body.  More than one element MUST NOT be
   returned for XML encoding.

   If a retrieval request for a data resource, and
   that data represents resource representing a YANG leaf-
   list or leaf-list that list object identifies more than one instance, and XML
   encoding is ordered by the
   user.

   If used in the "insert" query parameter is not present, or has a value other
   than "before" or "after", response, then an error response containing a 400
   "400 Bad Request error is returned.

   This parameter contains Request" status-line MUST be returned by the instance identifier of server.

   If the target resource to be
   used as the insertion point of a retrieval request is for an operation
   resource then a POST or PUT method.

   The "point" query parameter "405 Method Not Allowed" status-line MUST be supported returned
   by the server.

4.8.6.  The "filter" Query Parameter

   The "filter" parameter

   Note that the way that access control is used applied to indicate which subset of all
   possible events data resources is
   completely incompatible with HTTP caching.  The Last-Modified and
   ETag headers maintained for a data resource are of interest.  If not present, all events not
   precluded affected by other parameters will be sent.

   This parameter is only allowed
   changes to the access control rules for GET methods on a text/event-stream that data resource.  A 400 Bad Request error  It is returned if used
   possible for other
   methods or resource types.

   The format the representation of this parameter is an XPath 1.0 expression, and a data resource that is
   evaluated in visible to
   a particular client to be changed without detection via the following context:

   o Last-
   Modified or ETag values.

   Example:

   The set of namespace declarations is client might request the set of prefix and
      namespace pairs response headers for all supported YANG modules, where the prefix
      is the YANG module name, and an XML
   representation of the namespace a specific "album" resource:

   GET /restconf/data/example-jukebox:jukebox/
      library/artist=Foo%20Fighters/album=Wasting%20Light  HTTP/1.1
   Host: example.com
   Accept: application/yang.data+xml

   The server might respond:

   HTTP/1.1 200 OK
   Date: Mon, 23 Apr 2012 17:02:40 GMT
   Server: example-server
   Content-Type: application/yang.data+xml
   Cache-Control: no-cache
   Pragma: no-cache
   ETag: a74eefc993a2b
   Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT

   <album xmlns="http://example.com/ns/example-jukebox"
          xmlns:jbox="http://example.com/ns/example-jukebox">
     <name>Wasting Light</name>
     <genre>jbox:alternative</genre>
     <year>2011</year>
   </album>

4.4.  POST

   The POST method is as defined sent by the
      "namespace" statement in the YANG module.

   o client to create a data resource or
   invoke an operation resource.  The function library is server uses the core function library defined in XPath
      1.0.

   o  The set of variable bindings is empty.

   o  The context node target resource
   media type to determine how to process the request.

      +-----------+------------------------------------------------+
      | Type      | Description                                    |
      +-----------+------------------------------------------------+
      | Datastore | Create a top-level configuration data resource |
      | Data      | Create a configuration data child resource     |
      | Operation | Invoke a protocol operation                    |
      +-----------+------------------------------------------------+

                     Resource Types that Support POST

4.4.1.  Create Resource Mode

   If the target resource type is a datastore or data resource, then the root node.

   The filter
   POST is used treated as defined in [RFC5277], Section 3.6.  If a request to create a top-level resource or child
   resource, respectively.  The message-body is expected to contain the
   boolean result
   content of the expression is true when applied a child resource to create within the
   conceptual "notification" document root, then parent (target
   resource).  The message-body MUST NOT contain more than one instance
   of the event notification expected data resource.  The data-model for the child tree is delivered to
   the client.

   If subtree as defined by YANG for the "filter" child resource.

   The "insert" and "point" query parameter URI is listed in parameters are supported by the "capability"
   leaf-list in Section 9.3, then POST
   method for datastore and data resources.  If the server supports the "filter" query
   parameter.

4.8.7.  The "start-time" Query Parameter

   The "start-time" parameter implements
   any YANG module that contains a configuration data node that is used to trigger
   "ordered-by" user, then the notification replay
   feature "insert" and indicate that the replay should start at the time
   specified. "point" query parameters
   MUST be supported.  If the stream does not, then these parameters are not support replay, per applicable.

   If the
   "replay-support" attribute POST method succeeds, a "201 Created" status-line is returned by stream list entry for the
   stream resource, then
   and there is no response message-body.  A "Location" header
   identifying the server child resource that was created MUST return the HTTP error code 400
   Bad Request.

   The value of be present in
   the "start-time" parameter is of type "date-and-time",
   defined response in this case.

   If the "ietf-yang" YANG module [RFC6991].

   This parameter is only allowed for GET methods on a text/event-stream data resource.  A 400 Bad Request error is returned if used for other
   methods or resource types.

   If this parameter is not present, already exists, then a replay subscription is not
   being requested.  It is not valid to specify start times that are
   later than the current time. POST request MUST fail
   and a "409 Conflict" status-line MUST be returned.

   If the value specified is earlier than
   the log can support, the replay will begin with the earliest
   available notification.

   If this query parameter user is supported by the server, then not authorized to create the "replay"
   query parameter URI MUST target resource, an error
   response containing a "403 Forbidden" status-line SHOULD be listed returned.
   A server MAY return a "404 Not Found" status-line, as described in
   section 6.5.3 in [RFC7231].  All other error responses are handled
   according to the "capability" leaf-list procedures defined in Section 9.3.  The "stop-time" query parameter MUST also be supported
   by 7.

   Example:

   To create a new "jukebox" resource, the server. client might send:

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

      { "example-jukebox:jukebox" : {} }

   If the "replay-support" leaf resource is present in the "stream" entry
   (defined in Section 9.3) then created, the server MUST support the
   "start-time" and "stop-time" query parameters for might respond as follows.
   Note that stream.

4.8.8.  The "stop-time" Query Parameter

   The "stop-time" parameter is used with the replay feature "Location" header line is wrapped for display purposes
   only:

   HTTP/1.1 201 Created
   Date: Mon, 23 Apr 2012 17:01:00 GMT
   Server: example-server
   Location: https://example.com/restconf/data/
       example-jukebox:jukebox
   Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT
   ETag: b3a3e673be2

   Refer to indicate Appendix D.2.1 for more resource creation examples.

4.4.2.  Invoke Operation Mode

   If the newest notifications of interest.  This parameter MUST be used
   with and have a value later than target resource type is an operation resource, then the "start-time" parameter. POST
   method is treated as a request to invoke that operation.  The value of the "stop-time" parameter
   message-body (if any) is of type "date-and-time",
   defined in processed as the "ietf-yang" YANG module [RFC6991].

   This parameter is only allowed operation input parameters.
   Refer to Section 3.6 for GET methods details on operation resources.

   If the POST request succeeds, a text/event-stream
   data resource.  A 400 Bad Request error "200 OK" status-line is returned if used for other
   methods or resource types.
   there is a response message-body, and a "204 No Content" status-line
   is returned if there is no response message-body.

   If this parameter the user is not present, the notifications will continue
   until authorized to invoke the subscription target operation, an
   error response containing a "403 Forbidden" status-line is terminated.  Values in returned
   to the future client.  All other error responses are
   valid.

   If handled according to
   the procedures defined in Section 7.

   Example:

   In this query parameter is supported by example, the server, then client is invoking the "replay"
   query parameter URI MUST be listed "play" operation defined
   in the "capability" leaf-list in
   Section 9.3. "example-jukebox" YANG module.

   A client might send a "play" request as follows:

      POST /restconf/operations/example-jukebox:play   HTTP/1.1
      Host: example.com
      Content-Type: application/yang.operation+json

      {
        "example-jukebox:input" : {
          "playlist" : "Foo-One",
          "song-number" : 2
        }
      }

   The "start-time" query parameter MUST also be supported server might respond:

   HTTP/1.1 204 No Content
   Date: Mon, 23 Apr 2012 17:50:00 GMT
   Server: example-server

4.5.  PUT

   The PUT method is sent by the server.

   If client to create or replace the "replay-support" leaf is present in target
   data resource.  A request message-body MUST be present, representing
   the "stream" entry
   (defined in Section 9.3) then new data resource, or the server MUST support the
   "start-time" and "stop-time" query parameters for that stream.

4.8.9. return "400 Bad Request"
   status-line.

   The "with-defaults" Query Parameter only target resource media type that supports PUT is the data
   resource.  The "with-defaults" parameter message-body is used expected to specify how information
   about default data nodes should be returned in response contain the content used
   to GET
   requests on create or replace the target resource.

   The "insert" (Section 4.8.4) and "point" (Section 4.8.5) query
   parameters are supported by the PUT method for data resources.

   Consistent with [RFC7231], if the PUT request creates a new resource,
   a "201 Created" status-line is returned.  If an existing resource is
   modified, a "204 No Content" status-line is returned.

   If the user is not authorized to create or replace the target
   resource an error response containing a "403 Forbidden" status-line
   SHOULD be returned.  A server supports this capability, then it MUST implement MAY return a "404 Not Found" status-
   line, as described in section 6.5.3 in [RFC7231].  All other error
   responses are handled according to the
   behavior procedures defined in
   Section 4.5.1 of [RFC6243], except applied to the
   RESTCONF GET operation, instead of the NETCONF operations.

   +---------------------------+---------------------------------------+
   | Value                     | Description                           |
   +---------------------------+---------------------------------------+
   | report-all                | All data nodes are reported           |
   | trim                      | Data nodes set to the YANG default    |
   |                           | are not reported                      |
   | explicit                  | Data nodes set by the client are not  |
   |                           | reported                              |
   | report-all-tagged         | All data nodes are reported and       |
   |                           | defaults are tagged                   |
   +---------------------------+---------------------------------------+ 7.

   If the "with-defaults" parameter is set to "report-all" target resource represents a YANG leaf-list, then the
   server PUT
   method MUST adhere to not change the defaults reporting behavior defined in
   Section 3.1 value of [RFC6243]. the leaf-list instance.

   If the "with-defaults" parameter is set to "trim" target resource represents a YANG list instance, then the server PUT
   method MUST adhere to the defaults reporting behavior defined NOT change any key leaf values in Section 3.2
   of [RFC6243]. the message-body
   representation.

   If the "with-defaults" parameter server implements any YANG module that contains a
   configuration data node that is set to "explicit" "ordered-by" user, then the server "insert"
   and "point" query parameters MUST adhere to the defaults reporting behavior defined in Section 3.3
   of [RFC6243]. be supported.  If the "with-defaults" parameter is set to "report-all-tagged" not, then
   the server MUST adhere to the defaults reporting behavior these
   parameters are not applicable.

   Example:

   An "album" child resource defined in
   Section 3.4 of [RFC6243].

   If the "with-defaults" parameter "example-jukebox" YANG
   module is replaced or created if it does not present then already exist.

   To replace the server MUST
   adhere to "album" resource contents, the defaults reporting behavior defined in its "basic-mode"
   parameter for client might send as
   follows.  Note that the "defaults" protocol capability URI, defined in
   Section 9.1.2. request-line is wrapped for display purposes
   only:

      PUT /restconf/data/example-jukebox:jukebox/
          library/artist=Foo%20Fighters/album=Wasting%20Light   HTTP/1.1
      Host: example.com
      Content-Type: application/yang.data+json

      {
        "example-jukebox:album" : {
          "name" : "Wasting Light",
          "genre" : "example-jukebox:alternative",
          "year" : 2011
        }
      }

   If the server includes the "with-defaults" query parameter URI in the
   "capability" leaf-list in Section 9.3, then resource is updated, the "with-defaults" query
   parameter MUST be supported.

5.  Messages server might respond:

   HTTP/1.1 204 No Content
   Date: Mon, 23 Apr 2012 17:04:00 GMT
   Server: example-server
   Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT
   ETag: b27480aeda4c

   The same request is shown here using XML encoding:

   PUT /restconf/data/example-jukebox:jukebox/
       library/artist=Foo%20Fighters/album=Wasting%20Light   HTTP/1.1
   Host: example.com
   Content-Type: application/yang.data+xml
   <album xmlns="http://example.com/ns/example-jukebox"
          xmlns:jbox="http://example.com/ns/example-jukebox">
     <name>Wasting Light</name>
     <genre>jbox:alternative</genre>
     <year>2011</year>
   </album>

4.6.  PATCH

   RESTCONF protocol uses the HTTP entities PATCH method defined in [RFC5789] to provide
   an extensible framework for messages.  A single HTTP
   message corresponds resource patching mechanisms.  It is
   optional to implement by the server.  Each patch mechanism needs a single protocol method.  Most messages can
   perform a single task on a single resource, such as retrieving a
   resource
   unique media type.  Zero or editing more patch media types MAY be supported
   by the server.  The media types supported by a resource. server can be
   discovered by the client by sending an OPTIONS request (see
   Section 4.1).

   This document defines one patch mechanism (Section 4.6.1).  The exception YANG
   PATCH mechanism is defined in [I-D.ietf-netconf-yang-patch].  Other
   patch mechanisms may be defined by future specifications.

   If the target resource instance does not exist, the server MUST NOT
   create it.

   If the PATCH method,
   which allows multiple datastore edits within request succeeds, a single message.

5.1.  Request URI Structure

   Resources are represented with URIs following the structure for
   generic URIs in [RFC3986].

   A RESTCONF operation "200 OK" status-line is derived from the HTTP method returned if
   there is a message-body, and "204 No Content" is returned if no
   response message-body is sent.

   If the request
   URI, using the following conceptual fields:

     <OP> /<restconf>/<path>?<query>#<fragment>

         ^       ^        ^       ^         ^
         |       |        |       |         |
       method  entry  resource  query    fragment

         M       M        O        O         I

       M=mandatory, O=optional, I=ignored

    <text> replaced by client with real values

   o  method: the HTTP method identifying the RESTCONF operation
      requested by the client, user is not authorized to act upon alter the target resource specified an error
   response containing a "403 Forbidden" status-line SHOULD be returned.
   A server MAY return a "404 Not Found" status-line, as described in the request URI.  RESTCONF operation details
   section 6.5.3 in [RFC7231].  All other error responses are described handled
   according to the procedures defined in Section 4.

   o  entry: 7.

4.6.1.  Plain Patch

   The plain patch mechanism merges the root contents 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: message body
   with the path expression identifying target resource.  If the target resource that is
      being accessed by a datastore
   resource (see Section 3.4), the operation. message body MUST be either
   application/yang.datastore+xml or application/yang.datastore+json.
   If this field is not present, then the target resource is a data resource (see Section 3.5),
   then the API itself, represented by the
      media type "application/yang.api".

   o  query: the set of parameters associated with the RESTCONF message.
      These have the familiar form of "name=value" pairs.  Most query
      parameters are optional to implement by the server and optional message body MUST be either application/yang.data+xml or
   application/yang.data+json.

   Plain patch can be used to
      use by the client.  Each optional query parameter is identified by create or update, but not delete, a URI.  The server MUST list child
   resource within the optional query parameter URIs it
      supports in target resource.  Please see
   [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting
   more granular control.  The YANG Patch Media Type allows multiple
   sub-operations (e.g., merge, delete) within a single PATCH operation.

   If the "capabilities" list defined in Section 9.3.

   There is target resource represents a specific set of parameters defined, although YANG leaf-list, then the server
   MAY choose to support query parameters PATCH
   method MUST not defined in this document.
   The contents of change the any query parameter value MUST be encoded
   according to [RFC3986], Section 3.4.  Any reserved characters MUST be
   percent-encoded, according to [RFC3986], section 2.1.

   o  fragment: This field is not used by of the RESTCONF protocol.

   When new resources are created by leaf-list instance.

   If the client, target resource represents a "Location" header is
   returned, which identifies the path of YANG list instance, then the newly created resource.
   The client
   PATCH method MUST use this exact path identifier to access NOT change any key leaf values in the resource
   once it has been created.

   The "target" of an operation is a resource.  The "path" message-body
   representation.

   Example:

   To replace just the "year" field in the
   request URI represents "album" resource (instead of
   replacing the target entire resource for with the operation.

5.2.  Message Headers

   There are several HTTP header lines utilized in RESTCONF messages.
   Messages are not limited to PUT method), the HTTP headers listed in this section.

   HTTP defines which header lines are required for particular
   circumstances.  Refer to each operation definition section in
   Section 4 for examples on how particular headers are used.

   There are some request headers client might
   send a plain patch as follows.  Note that are the request-line is wrapped
   for display purposes only:

   PATCH /restconf/data/example-jukebox:jukebox/
       library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
   Host: example.com
   If-Match: b8389233a4c
   Content-Type: application/yang.data+xml

   <album xmlns="http://example.com/ns/example-jukebox">
    <year>2011</year>
   </album>

   If the field is updated, the server might respond:

   HTTP/1.1 204 No Content
   Date: Mon, 23 Apr 2012 17:49:30 GMT
   Server: example-server
   Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT
   ETag: b2788923da4c

4.7.  DELETE

   The DELETE method is used within RESTCONF, usually
   applied to data resources.  The following tables summarize delete the
   headers most relevant in RESTCONF message requests:

   +-----------------------------+-------------------------------------+
   | Name                        | Description                         |
   +-----------------------------+-------------------------------------+
   | Accept                      | Response Content-Types that are     |
   |                             | acceptable                          |
   | Content-Type                | The media type of target resource.  If the
   DELETE request body  |
   | Host                        | The host address of succeeds, a "204 No Content" status-line is returned,
   and there is no response message-body.

   If the server      |
   | If-Match                    | Only perform user is not authorized to delete the action if target resource then an
   error response containing a "403 Forbidden" status-line SHOULD be
   returned.  A server MAY return a "404 Not Found" status-line, as
   described in section 6.5.3 in [RFC7231].  All other error responses
   are handled according to the      |
   |                             | entity matches ETag                 |
   | If-Modified-Since           | Only perform procedures defined in Section 7.

   If the action if modified |
   |                             | since time                          |
   | If-Unmodified-Since         | Only perform target resource represents a YANG leaf-list or list, then the action
   PATCH method SHOULD NOT delete more than one such instance.  The
   server MAY delete more than one instance if un-      |
   |                             | modified since time                 |
   +-----------------------------+-------------------------------------+ a query parameter is used
   requesting this behavior.  (Definition of this query parameter is
   outside the scope of this document.)

   Example:

   To delete a resource such as the "album" resource, the client might
   send:

   DELETE /restconf/data/example-jukebox:jukebox/
       library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
   Host: example.com

   If the resource is deleted, the server might respond:

   HTTP/1.1 204 No Content
   Date: Mon, 23 Apr 2012 17:49:40 GMT
   Server: example-server

4.8.  Query Parameters

   Each RESTCONF Request Headers operation allows zero or more query parameters to be
   present in the request URI.  The following tables summarize specific parameters that are allowed
   depends on the headers most relevant resource type, and sometimes the specific target
   resource used, in RESTCONF
   message responses:

   +-----------------------+-------------------------------------------+ the request.

   +-------------------+-------------+---------------------------------+
   | Name              | Description                               |
   +-----------------------+-------------------------------------------+ Methods     | Allow Description                     | Valid actions when 405 error returned
   +-------------------+-------------+---------------------------------+
   | content           | Cache-Control GET         | The cache control parameters for the Select config and/or non-config |
   |                   | response             | data resources                  | Content-Type
   | The media type of the response message- depth             | GET         | Request limited sub-tree depth  | body
   |                   | Date             | The date and time in the message was sent reply content            |
   | ETag fields            | An identifier for GET         | Request a specific version subset of a the target  |
   |                   |             | resource contents               |
   | Last-Modified filter            | The last modified date and time of a GET         | Boolean notification filter for |
   | resource                   |             | Location event stream resources          | The resource identifier
   | insert            | POST, PUT   | Insertion mode for a newly user-ordered |
   |                   | created resource             |
   +-----------------------+-------------------------------------------+

                         RESTCONF Response Headers

5.3.  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 XML or JSON encoding.  XML encoding rules data resources                  |
   | point             | POST, PUT   | Insertion point for user-       |
   |                   |             | ordered data nodes are
   defined in [I-D.ietf-netmod-rfc6020bis].  The same encoding rules are
   used resources          |
   | start-time        | GET         | Replay buffer start time for all XML content.  JSON encoding rules are defined in
   [I-D.ietf-netmod-yang-json].  JSON encoding    |
   |                   |             | event stream resources          |
   | stop-time         | GET         | Replay buffer stop time for     |
   |                   |             | event stream resources          |
   | with-defaults     | GET         | Control retrieval of meta-data is defined default    |
   |                   |             | values                          |
   +-------------------+-------------+---------------------------------+

                         RESTCONF Query Parameters

   Query parameters can be given in [I-D.ietf-netmod-yang-metadata].  This encoding any order.  Each parameter can
   appear at most once in a request URI.  A default value may apply if
   the parameter is valid JSON, but
   also has special encoding rules missing.

   Refer to identify module namespaces and
   provide consistent type processing Appendix D.3 for examples of YANG data.

   Request input content encoding format is identified with the Content-
   Type header.  This field MUST be present if query parameter usage.

   If vendors define additional query parameters, they SHOULD use a message-body is sent by
   the client.

   The server MUST support the "Accept" header and "406 Not Acceptable"
   status code,
   prefix (such as defined the enterprise or organization name) for query
   parameter names in [RFC7231].  Response output content
   encoding format is identified order to avoid collisions with other parameters.

4.8.1.  The "content" Query Parameter

   The "content" parameter controls how descendant nodes of the Accept header
   requested data nodes will be processed in the request.
   If is not specified, the request input encoding format reply.

   The allowed values are:

    +-----------+-----------------------------------------------------+
    | Value     | Description                                         |
    +-----------+-----------------------------------------------------+
    | config    | Return only configuration descendant data nodes     |
    | nonconfig | Return only non-configuration descendant data nodes |
    | all       | Return all descendant data nodes                    |
    +-----------+-----------------------------------------------------+

   This parameter is used. only allowed for GET methods on datastore and data
   resources.  A "400 Bad Request" status-line is returned if used for
   other methods or resource types.

   If
   there was no request input, then this query parameter is not present, the default output encoding value is XML
   or JSON, depending or server preference.  File extensions encoded in "all".
   This query parameter MUST be supported by the request are not used to identify format encoding.

5.4.  RESTCONF Meta-Data server.

4.8.2.  The RESTCONF protocol needs to retrieve the same meta-data that "depth" Query Parameter

   The "depth" parameter is used in the NETCONF protocol.  Information about default leafs, last-
   modified timestamps, etc. are commonly used to annotate
   representations of specify the datastore contents.  This meta-data is not
   defined number of nest levels
   returned in a response for a GET method.  The first nest-level
   consists of the YANG schema because it applies to requested data node itself.  If the datastore, and "fields"
   parameter (Section 4.8.3) is common across all used to select descendant data nodes. nodes,
   these nodes all have a depth value of 1.  This information is encoded as attributes in XML.  JSON encoding has the effect of
   meta-data is defined in [I-D.ietf-netmod-yang-metadata].

   The following examples are based on
   including the example in Appendix D.3.9.
   The "report-all-tagged" mode for nodes specified by the "with-defaults" query parameter
   requires that a "default" attribute be returned for default nodes.
   This example shows that attribute for fields, even if the "mtu" leaf .

5.4.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: Mon, 23 Apr 2012 17:01:00 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>

5.4.2.  JSON MetaData Encoding Example

   Note that RFC 6243 defines "depth"
   value is less than the "default" attribute with XSD, not
   YANG, so actual depth level of the YANG module name has to be assigned manually. specified fields.
   Any child nodes which are contained within a parent node have a depth
   value that is 1 greater than its parent.

   The value
   "ietf-netconf-with-defaults" of the "depth" parameter is assigned either an integer between 1 and
   65535, or the string "unbounded".  "unbounded" is the default.

   This parameter is only allowed for JSON meta-data 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: Mon, 23 Apr 2012 17:01:00 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.5.  Return Status

   Each message represents some sort of resource access.  An HTTP
   "status-line" header line methods on API, datastore, and
   data resources.  A "400 Bad Request" status-line is returned if it
   used for each other methods or resource types.

   More than one "depth" query parameter MUST NOT appear in a request.
   If a 4xx or
   5xx range status code more than one instance is present, then a "400 Bad Request"
   status-line MUST be returned in by the status-line, then server.

   By default, the error
   information server will be returned in the response, according to include all sub-resources within a
   retrieved resource, which have the format
   defined in Section 7.1.

5.6.  Message Caching

   Since same resource type as the datastore contents change at unpredictable times, responses
   from a RESTCONF server generally SHOULD NOT be cached.

   The server SHOULD include
   requested resource.  Only one level of sub-resources with a "Cache-Control" header in every response
   that specifies whether different
   media type than the response should be cached.  A "Pragma"
   header specifying "no-cache" MAY also target resource will be sent in case returned.

   If the
   "Cache-Control" header "depth" query parameter URI is not supported.

   Instead of using HTTP caching, the client SHOULD track listed in the "ETag" and
   /or "Last-Modified" headers returned by "capability"
   leaf-list in Section 9.3, then the server for supports the datastore
   resource (or "depth" query
   parameter.

4.8.3.  The "fields" Query Parameter

   The "fields" query parameter is used to optionally identify data resource if
   nodes within the server supports it).  A retrieval
   request for a target resource can include the "If-None-Match" and/or
   "If-Modified-Since" headers, which will cause the server to return be retrieved in a
   "304 Not Modified" status-line if the resource has not changed. GET method.
   The client MAY can use the HEAD method this parameter to retrieve just the message headers,
   which SHOULD include the "ETag" and "Last-Modified" headers, if this
   meta-data is maintained for the target a subset of all nodes
   in a resource.

6.  Notifications

   The RESTCONF protocol supports YANG-defined event notifications.  The
   solution preserves aspects

   A value of NETCONF Event Notifications [RFC5277]
   while utilizing the Server-Sent Events [W3C.CR-eventsource-20121211]
   transport strategy.

6.1.  Server Support

   A RESTCONF server is not required "fields" query parameter matches the following rule:

   fields-expr = path '(' fields-expr ')' /
                 path ';' fields-expr /
                 path
   path = api-identifier [ '/' path ]

   "api-identifier" is defined in Section 3.5.1.1.

   ";" is used to support RESTCONF notifications.
   Clients may determine if select multiple nodes.  For example, to retrieve only
   the "genre" and "year" of an album, use: "fields=genre;year".

   Parentheses are used to specify sub-selectors of a server supports RESTCONF notifications by
   using node.

   For example, assume the HTTP operation OPTIONS, HEAD, or GET on target resource is the stream "album" list.
   The server does not support RESTCONF notifications if  To
   retrieve only the "label" and "catalogue-number" of the "admin"
   container within an HTTP error
   code album, use:
   "fields=admin(label;catalogue-number)".

   "/" is returned (e.g., 404 Not Found).

6.2.  Event Streams

   A RESTCONF server that supports notifications will populate used in a stream
   resource for each notification delivery service access point.  A
   RESTCONF client can path to retrieve the list a child node of supported event streams from a RESTCONF server using node.  For
   example, to retrieve only the "label" of an album, use: "fields=admin
   /label".

   This parameter is only allowed for GET operation methods on api, datastore, and
   data resources.  A "400 Bad Request" status-line is returned if used
   for other methods or resource types.

   More than one "fields" query parameter MUST NOT appear in a request.
   If more than one instance is present, then a "400 Bad Request"
   status-line MUST be returned by the stream list.

   The "restconf-state/streams" container definition server.

   If the "fields" query parameter URI is listed in the
   "ietf-restconf-monitoring" module (defined "capability"
   leaf-list in Section 9.3) is used to
   specify the structure and syntax of 9.3, then the conceptual child resources
   within server supports the "streams" resource.

   For example: "fields"
   parameter.

4.8.4.  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 "insert" Query Parameter

   The server might send the following response:

   HTTP/1.1 200 OK
   Content-Type: application/yang.api+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>
      <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 "insert" parameter is used to Receive Notifications

   RESTCONF clients can determine the URL for the subscription specify how a resource
   (to receive notifications) by sending an HTTP GET request for should be
   inserted within a user-ordered list.

   The allowed values are:

   +-----------+-------------------------------------------------------+
   | Value     | Description                                           |
   +-----------+-------------------------------------------------------+
   | first     | Insert the
   "location" leaf with new data as the stream list new first entry.  The value returned by           |
   | last      | Insert the server can be used for new data as the actual notification subscription.

   The client will send an HTTP GET request for new last entry.            |
   | before    | Insert the URL returned new data before the insertion point, as    |
   |           | specified by the
   server with value of the "Accept" type "text/event-stream".

   The server will treat "point" parameter.      |
   | after     | Insert the connection new data after the insertion point, as an event stream, using     |
   |           | specified by the
   Server Sent Events [W3C.CR-eventsource-20121211] transport strategy. value of the "point" parameter.      |
   +-----------+-------------------------------------------------------+

   The server MAY support query parameters default value is "last".

   This parameter is only supported for the POST and PUT methods.  It is
   also only supported if the target resource is a GET method on this
   resource.  These parameters data resource, and
   that data represents a YANG list or leaf-list that is ordered by the
   user.

   More than one "insert" query parameter MUST NOT appear in a request.
   If more than one instance is present, then a "400 Bad Request"
   status-line MUST be returned by the server.

   If the values "before" or "after" are specific to each notification stream.

   For example:

   The client might send used, then a "point" query
   parameter for 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 insertion parameter MUST also be present, or a "400
   Bad Request" status-line is returned.

   The server might send "insert" query parameter MUST be supported by the following response:

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

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

4.8.5.  The RESTCONF client can then use this URL value "point" Query Parameter

   The "point" parameter is used to start monitoring specify 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 insertion point for a
   data resource that is being created or moved within a user ordered
   list or leaf-list.

   The value of the server compress "point" parameter is a string that identifies the events using
   path to 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

6.3.1.  NETCONF Event Stream insertion point object.  The server SHOULD support format is the "NETCONF" notification stream defined
   in [RFC5277].  For this stream, RESTCONF notification subscription
   requests MAY specify parameters indicating same as a
   target resource URI string.

   This parameter is only supported for the events it wishes to
   receive.  These query parameters are optional to implement, POST and PUT methods.  It is
   also only
   available supported if the server supports them.

            +------------+---------+-------------------------+
            | Name       | Section | Description             |
            +------------+---------+-------------------------+
            | start-time | 4.8.7   | replay event start time |
            | stop-time  | 4.8.8   | replay event stop time  |
            | filter     | 4.8.6   | boolean content filter  |
            +------------+---------+-------------------------+

                      NETCONF Stream Query Parameters

   The semantics target resource is a data resource, and syntax for these
   that data represents a YANG list or leaf-list that is ordered by the
   user.

   If the "insert" query parameters are defined parameter is not present, or has a value other
   than "before" or "after", then a "400 Bad Request" status-line is
   returned.

   More than one "point" query parameter MUST NOT appear in
   the sections listed above.  The YANG encoding a request.
   If more than one instance is present, then a "400 Bad Request"
   status-line MUST be converted to
   URL-encoded string for use in returned by the request URI.

   Refer to Appendix D.3.6 for filter server.

   This parameter examples.

6.4.  Receiving Event Notifications

   RESTCONF notifications are encoded according to the definition of contains the
   event stream.  The NETCONF stream defined in [RFC5277] is encoded in
   XML format.

   The structure instance identifier of the event data is based on the "notification"
   element definition in Section 4 of [RFC5277].  It MUST conform resource to be
   used as the
   schema insertion point for the "notification" element in Section 4 of [RFC5277],
   except the XML namespace a POST or PUT method.

   The "point" query parameter MUST be supported by the server.

4.8.6.  The "filter" Query Parameter

   The "filter" parameter is used to indicate which subset of all
   possible events are of interest.  If not present, all events not
   precluded by other parameters will be sent.

   This parameter is only allowed for GET methods on a text/event-stream
   data resource.  A "400 Bad Request" status-line is returned if used
   for other methods or resource types.

   The format of this element parameter is defined as:

   urn:ietf:params:xml:ns:yang:ietf-restconf

   For JSON encoding purposes, an XPath 1.0 expression, and is
   evaluated in the module name following context:

   o  The set of namespace declarations is the set of prefix and
      namespace pairs for all supported YANG modules, where the "notification"
   element prefix
      is "ietf-restconf".

   Two child nodes within the "notification" container are expected,
   representing the event time YANG module name, and the event payload.  The "event-time"
   node namespace is as defined within by the "ietf-restconf" module namespace.
      "namespace" statement in the YANG module.

   o  The
   name and namespace function library is the core function library defined in XPath
      1.0.

   o  The set of variable bindings is empty.

   o  The context node is the payload element are determined root node.

   More than one "filter" query parameter MUST NOT appear in a request.
   If more than one instance is present, then a "400 Bad Request"
   status-line MUST be returned by the YANG
   module containing server.

   The filter is used as defined in [RFC5277], Section 3.6.  If the notification-stmt.

   In
   boolean result of the following example, expression is true when applied to the YANG module "example-mod"
   conceptual "notification" document root, then the event notification
   is used:

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

       notification event {
        leaf event-class { type string; }
        container reporting-entity {
          leaf card { type string; }
        }
        leaf severity { type string; }
       }
     }

   An example SSE event notification encoded using XML:

   data: <notification
   data:    xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
   data:    <event-time>2013-12-21T00:01:00Z</event-time>
   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>

   An example SSE event notification encoded using JSON:

   data: {
   data:   "ietf-restconf:notification": {
   data:     "event-time": "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 are whitespace sensitive, delivered to the above messages can be encoded onto a single line.  For example:

   For example: ('\' line wrapping added for formatting only)

      XML:

      data: <notification xmlns="urn:ietf:params:xml:ns:yang:ietf-rest\
      conf"><event-time>2013-12-21T00:01:00Z</event-time><event xmlns="\
      http://example.com/event/1.0"><event-class>fault</event-class><re\
      portingEntity><card>Ethernet0</card></reporting-entity><severity>\
      major</severity></event></notification>

      JSON:

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

   The SSE specifications supports client.

   If the following additional fields:
   event, id and retry.  A RESTCONF server MAY send "filter" query parameter URI is listed in the "capability"
   leaf-list in Section 9.3, then the "retry" field
   and, if it does, RESTCONF clients SHOULD use it.  A RESTCONF server
   SHOULD NOT send supports the "event" or "id" fields, as there are no
   meaningful values that could be "filter" query
   parameter.

4.8.7.  The "start-time" Query Parameter

   The "start-time" parameter is used for them that would not be
   redundant to the contents of trigger the notification itself.  RESTCONF
   servers replay
   feature and indicate that do not send the "id" field also do replay should start at the time
   specified.  If the stream does not need to support replay, per the HTTP header "Last-Event-Id".  RESTCONF servers that do send
   "replay-support" attribute returned by stream list entry for the
   "id" field
   stream resource, then the server MUST still support return a "400 Bad Request"
   status-line.

   The value of the "startTime" query "start-time" parameter as is of type "date-and-time",
   defined in the
   preferred means "ietf-yang" YANG module [RFC6991].

   This parameter is only allowed for GET methods on a client to specify where to restart the event
   stream.

7.  Error Reporting

   HTTP status-lines are used to report success or failure for RESTCONF
   operations.  The <rpc-error> element returned in NETCONF error
   responses contains some useful information.  This error information text/event-stream
   data resource.  A "400 Bad Request" status-line is adapted returned if used
   for use other methods or resource types.

   More than one "start-time" query parameter MUST NOT appear in RESTCONF, and error information a
   request.  If more than one instance is present, then a "400 Bad
   Request" status-line MUST be returned for
   "4xx" class of status codes.

   The following table summarizes the return status codes used
   specifically by RESTCONF operations:

   +----------------------------+--------------------------------------+
   | Status-Line                | Description                          |
   +----------------------------+--------------------------------------+
   | 100 Continue               | POST accepted, 201 should follow     |
   | 200 OK                     | Success with response message-body   |
   | 201 Created                | POST to create a resource success    |
   | 202 Accepted               | POST to create the server.

   If this parameter is not present, then a resource accepted   |
   | 204 No Content             | Success without response message-    |
   |                            | body                                 |
   | 304 Not Modified           | Conditional operation replay subscription is not done       |
   | 400 Bad Request            | Invalid request message              |
   | 403 Forbidden              | Access
   being requested.  It is not valid to resource denied            |
   | 404 Not Found              | Resource target or resource node not |
   |                            | found                                |
   | 405 Method Not Allowed     | Method not allowed for target        |
   |                            | resource                             |
   | 409 Conflict               | Resource or lock in use              |
   | 412 Precondition Failed    | Conditional method is false          |
   | 413 Request Entity Too     | too-big error                        |
   | Large                      |                                      |
   | 414 Request-URI Too Large  | too-big error                        |
   | 415 Unsupported Media Type | non RESTCONF media type              |
   | 500 Internal Server Error  | operation-failed                     |
   | 501 Not Implemented        | unknown-operation                    |
   | 503 Service Unavailable    | Recoverable server error             |
   +----------------------------+--------------------------------------+

                    HTTP Status Codes used in RESTCONF

   Since an operation resource is defined with a YANG "action" or "rpc"
   statement, a mapping between specify start times that are
   later than the current time.  If the NETCONF <error-tag> value and specified is earlier than
   the
   HTTP status code log can support, the replay will begin with the earliest
   available notification.

   If this query parameter is needed. supported by the server, then the "replay"
   query parameter URI MUST be listed in the "capability" leaf-list in
   Section 9.3.  The specific error condition and
   response code to use are data-model specific and might "stop-time" query parameter MUST also be contained supported
   by the server.

   If the "replay-support" leaf is present in the YANG "description" statement "stream" entry
   (defined in Section 9.3) then the server MUST support the
   "start-time" and "stop-time" query parameters for that stream.

4.8.8.  The "stop-time" Query Parameter

   The "stop-time" parameter is used with the "action" or "rpc"
   statement.

                 +-------------------------+-------------+
                 | <error&#8209;tag>       | status code |
                 +-------------------------+-------------+
                 | in-use                  | 409         |
                 | invalid-value           | 400         |
                 | too-big                 | 413         |
                 | missing-attribute       | 400         |
                 | bad-attribute           | 400         |
                 | unknown-attribute       | 400         |
                 | bad-element             | 400         |
                 | unknown-element         | 400         |
                 | unknown-namespace       | 400         |
                 | access-denied           | 403         |
                 | lock-denied             | 409         |
                 | resource-denied         | 409         |
                 | rollback-failed         | 500         |
                 | data-exists             | 409         |
                 | data-missing            | 409         |
                 | operation-not-supported | 501         |
                 | operation-failed        | 500         |
                 | partial-operation       | 500         |
                 | malformed-message       | 400         |
                 +-------------------------+-------------+

                   Mapping from error-tag replay feature to status code

7.1.  Error Response Message

   When an error occurs for a request message on a data resource or an
   operation resource, and a "4xx" class of status codes (except for
   status code "403 Forbidden"), then the server SHOULD send a response
   message-body containing the information described by the "errors"
   container definition within indicate
   the YANG module Section 8.  The Content-
   Type newest notifications of this response message interest.  This parameter MUST be application/yang.errors (see
   example below).

   The client MAY specify the desired encoding for error messages by
   specifying the appropriate media-type in the Accept header.  If no
   error media is specified, then used
   with and have a value later than the media type "start-time" parameter.

   The value of the request message
   is used.  If there "stop-time" parameter is no request message the server MUST select
   "application/yang.errors+xml" or "application/yang.errors+json",
   depending on server preference.  All of the examples type "date-and-time",
   defined in this
   document, except for the one below, assume that XML encoding will be
   returned if there is an error. "ietf-yang" YANG Tree Diagram module [RFC6991].

   This parameter is only allowed for <errors> data:

   +--ro errors
      +--ro error*
         +--ro error-type       enumeration
         +--ro error-tag        string
         +--ro error-app-tag?   string
         +--ro error-path?      instance-identifier
         +--ro error-message?   string
         +--ro error-info

   The semantics and syntax GET methods on a text/event-stream
   data resource.  A "400 Bad Request" status-line is returned if used
   for RESTCONF error messages other methods or resource types.

   More than one "stop-time" query parameter MUST NOT appear in a
   request.  If more than one instance is present, then a "400 Bad
   Request" status-line MUST be returned by the server.

   If this parameter is not present, the notifications will continue
   until the subscription is terminated.  Values in the future are defined
   valid.

   If this query parameter is supported by the server, then the "replay"
   query parameter URI MUST be listed in the "application/yang.errors" restconf-media-type extension "capability" leaf-list in
   Section 8.

   Examples: 9.3.  The following example shows an error returned "start-time" query parameter MUST also be supported
   by the server.

   If the "replay-support" leaf is present in the "stream" entry
   (defined in Section 9.3) then the server MUST support the
   "start-time" and "stop-time" query parameters for an "lock-denied"
   error that can occur if a NETCONF client has locked a datastore. stream.

4.8.9.  The
   RESTCONF client is attempting to delete a data resource.  Note that
   an Accept header "with-defaults" Query Parameter

   The "with-defaults" parameter is used to specify how information
   about default data nodes should be returned in response to GET
   requests on data resources.

   If the desired encoding for server supports this capability, then it MUST implement the
   error message.  This example's use
   behavior in Section 4.5.1 of [RFC6243], except applied to the Accept header is especially
   notable since
   RESTCONF GET operation, instead of the DELETE method typically doesn't return a message-
   body and hence Accept headers are typically not passed.

   DELETE /restconf/data/example-jukebox:jukebox/
      library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
   Host: example.com
   Accept: application/yang.errors+json

   The server might respond:

      HTTP/1.1 409 Conflict
      Date: Mon, 23 Apr 2012 17:11:00 GMT
      Server: example-server
      Content-Type: application/yang.errors+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 NETCONF operations.

   +---------------------------+---------------------------------------+
   | Value                     | Description                           |
   +---------------------------+---------------------------------------+
   | report-all                | All data resource.  The "jukebox" resource already exists so
   it cannot be created.

   The client might send:

   POST /restconf/data/example-jukebox:jukebox HTTP/1.1
   Host: example.com

   The server might respond (some lines wrapped for display purposes):

   HTTP/1.1 409 Conflict
   Date: Mon, 23 Apr 2012 17:11:00 GMT
   Server: example-server
   Content-Type: application/yang.errors+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:jb="https://example.com/ns/example-jukebox">
         /rc:restconf/rc:data/jb:jukebox
       </error-path>
       <error-message> nodes are reported           |
   | trim                      | Data already exists, cannot create new resource
       </error-message>
     </error>
   </errors>

8.  RESTCONF module

   The "ietf-restconf" module defines conceptual definitions within an
   extension and two groupings, which nodes set to the YANG default    |
   |                           | are not meant reported                      |
   | explicit                  | Data nodes set to be implemented as
   datastore contents the YANG default by a server.  E.g., |
   |                           | the "restconf" container client are reported               |
   | report-all-tagged         | All data nodes are reported and       |
   |                           | defaults are tagged                   |
   +---------------------------+---------------------------------------+

   If the "with-defaults" parameter is
   not intended set to be implemented as a top-level data node (under the "/
   restconf/data" entry point).

   RFC Ed.: update "report-all" then the date below with
   server MUST adhere to the date of RFC publication and
   remove this note.

   <CODE BEGINS> file "ietf-restconf@2015-10-18.yang"
   module ietf-restconf {
     namespace "urn:ietf:params:xml:ns:yang:ietf-restconf";
     prefix "rc";

     organization
       "IETF NETCONF (Network Configuration) Working Group";

     contact
       "WG Web:   <http://tools.ietf.org/wg/netconf/>
        WG List:  <mailto:netconf@ietf.org>

        WG Chair: Mehmet Ersue
                  <mailto:mehmet.ersue@nsn.com>

        WG Chair: Mahesh Jethanandani
                  <mailto:mjethanandani@gmail.com>

        Editor:   Andy Bierman
                  <mailto:andy@yumaworks.com>

        Editor:   Martin Bjorklund
                  <mailto:mbj@tail-f.com>

        Editor:   Kent Watsen
                  <mailto:kwatsen@juniper.net>";

     description
       "This module contains conceptual YANG specifications
        for basic RESTCONF media type definitions used defaults reporting behavior defined 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.

        Copyright (c) 2015 IETF Trust and the persons identified as
        authors
   Section 3.1 of [RFC6243].

   If the code.  All rights reserved.

        Redistribution and use in source and binary forms, with or
        without modification, "with-defaults" parameter is permitted pursuant to, and subject set to "trim" then the license terms contained in, server
   MUST adhere to the Simplified BSD License
        set forth defaults reporting behavior defined in Section 4.c 3.2
   of [RFC6243].

   If the IETF Trust's Legal Provisions
        Relating "with-defaults" parameter is set to IETF Documents
        (http://trustee.ietf.org/license-info).

        This version "explicit" then the server
   MUST adhere to the defaults reporting behavior defined in Section 3.3
   of this YANG module [RFC6243].

   If the "with-defaults" parameter is part of RFC XXXX; see set to "report-all-tagged" then
   the RFC itself for full legal notices.";

     // RFC Ed.: replace XXXX with actual RFC number and remove this
     // note.

     // RFC Ed.: remove this note
     // Note: extracted from draft-ietf-netconf-restconf-08.txt

     // RFC Ed.: update the date below with server MUST adhere to the date defaults reporting behavior defined in
   Section 3.4 of RFC publication
     // and remove this note.
     revision 2015-10-18 {
       description
         "Initial revision.";
       reference
         "RFC XXXX: RESTCONF Protocol.";
     }

     extension restconf-media-type {
      argument media-type-id {
        yin-element true;
      }
      // RFC Ed.: replace draft-ietf-netmod-yang-json with RFC number
      // [RFC6243].

   More than one "with-defaults" query parameter MUST NOT appear in the description below, and remove this note.
      description
        "This extension is used to specify a YANG data structure which
         represents
   request.  If more than one instance is present, then a conceptual RESTCONF media type.
         Data definition statements within this extension specify "400 Bad
   Request" status-line MUST be returned by the generic syntax for server.

   If the specific media type.

         YANG "with-defaults" parameter is mapped to specific encoding formats outside not present then the
         scope of this extension statement. RFC 6020 defines XML
         encoding rules for all RESTCONF media types that use server MUST
   adhere to the '+xml' suffix. draft-ietf-netmod-yang-json defines
         JSON encoding rules defaults reporting behavior defined in its "basic-mode"
   parameter for all RESTCONF media types that
         use the '+json' suffix.

         The 'media-type-id' parameter value identifies "defaults" protocol capability URI, defined in
   Section 9.1.2.

   If the media type
         that is being defined. It contains server includes the string associated
         with "with-defaults" query parameter URI in the generic media type, i.e., no suffix is specified.

         This extension is ignored unless it appears as a top-level
         statement. It SHOULD contain data definition statements
         that result
   "capability" leaf-list in exactly one container data node definition.
         This allows compliant translation to an XML instance
         document Section 9.3, then the "with-defaults" query
   parameter MUST be supported.

5.  Messages

   The RESTCONF protocol uses HTTP entities for each media type. 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 module name and namespace value exception is the PATCH method,
   which allows multiple datastore edits within a single message.

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 YANG module HTTP method and the request
   URI, using the extension statement following conceptual fields:

     <OP> /<restconf>/<path>?<query>#<fragment>

         ^       ^        ^       ^         ^
         |       |        |       |         |
       method  entry  resource  query    fragment

         M       M        O        O         I

       M=mandatory, O=optional, I=ignored

       where:

      <OP> is assigned to instance document data
         conforming to the data definition statements within
         this extension.

         The sub-statements of this extension MUST follow HTTP method
      <restconf> is the
         'data-def-stmt' rule in RESTCONF entry point
      <path> is the YANG ABNF.

         The XPath document root Target Resource URI
      <query> is the extension statement itself,
         such that query parameter list
      <fragment> is not used in RESTCONF

   o  method: the child nodes of HTTP method identifying the document root are
         represented RESTCONF operation
      requested by the data-def-stmt sub-statements within
         this extension. This conceptual document is client, to act upon the context
         for target resource specified
      in 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 sub-statements have special
         meaning when used within a restconf-resource extension
         statement.

         - The list-stmt is not required to have a key-stmt defined.
         - The if-feature-stmt 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 ignored if present.
         - The config-stmt
      being accessed by the operation.  If this field is ignored if present.
         - The available identity values for any 'identityref'
           leaf or leaf-list nodes not present,
      then the target resource is limited to the module
           containing this extension statement, and API itself, represented by the modules
           imported into that module.
         ";
     }

     rc:restconf-media-type "application/yang.errors" {
       uses errors;
     }

     rc:restconf-media-type "application/yang.api" {
       uses restconf;
     }

     grouping errors {
       description
         "A grouping that contains a YANG container
          representing
      media type "application/yang.api".

   o  query: the syntax and semantics set of a
          YANG Patch errors report within a response message.";

       container errors {
         description
           "Represents an error report returned parameters associated with the RESTCONF message.
      These have the familiar form of "name=value" pairs.  Most query
      parameters are optional to implement by the server if and optional to
      use by the client.  Each optional query parameter is identified by
      a request results URI.  The server MUST list the optional query parameter URIs it
      supports in an error."; the "capabilities" list error {
           description
             "An entry containing information about one
              specific error that occurred while processing
              a RESTCONF request.";
           reference "RFC 6241, defined in 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.";
           }

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

   There is a specific set of parameters defined, although the error node.";
           }

           leaf error-message {
             type string;
             description
               "A message describing server
   MAY choose to support query parameters not defined in this document.
   The contents of the error.";
           }

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

     grouping restconf {
       description
         "Conceptual container representing the
          application/yang.api resource type.";

       container restconf {
         description
           "Conceptual container representing be encoded
   according to [RFC3986], Section 3.4.  Any reserved characters MUST be
   percent-encoded, according to [RFC3986], section 2.1.

   o  fragment: This field is not used by the
            application/yang.api resource type.";

         container data {
           description
             "Container representing RESTCONF protocol.

   When new resources are created by the application/yang.datastore
              resource type. Represents client, a "Location" header is
   returned, which identifies the conceptual root path of all
              operational data and configuration data supported by the server. newly created resource.
   The child nodes of client uses this container can be
              any data exact path identifier to access the resource (application/yang.data), which are
              defined as top-level data nodes from the YANG modules
              advertised by the server in the ietf-restconf-monitoring
              module.";
         }

         container operations {
           description
             "Container for all
   once it has been created.

   The "target" of an operation resources
              (application/yang.operation),
              Each resource is represented as an empty leaf with the
              name of a resource.  The "path" field in the RPC operation from
   request URI represents the YANG rpc statement.

              E.g.;

                 POST /restconf/operations/show-log-errors

                 leaf show-log-errors {
                   type empty;
                 }
             ";
         }
       }
     }

   }

   <CODE ENDS>

9.  RESTCONF Monitoring

   The "ietf-restconf-monitoring" module provides information about target resource for the operation.

   Refer to Appendix D for examples of RESTCONF protocol capabilities and event notification streams
   available from the server.  A Request URIs.

5.2.  Message Encoding

   RESTCONF server MUST implement the "/
   restconf-state/capabilities" container messages are encoded in this module.

   YANG Tree Diagram HTTP according to [RFC7230].  The
   "utf-8" character set is used for "ietf-restconf-monitoring" module:

   +--ro restconf-state
      +--ro capabilities
      |  +--ro capability*   inet:uri
      +--ro streams
         +--ro stream* [name]
            +--ro name                        string
            +--ro description?                string
            +--ro replay-support?             boolean
            +--ro replay-log-creation-time?   yang:date-and-time
            +--ro access* [encoding]
               +--ro encoding  string
               +--ro location  inet:uri

9.1.  restconf-state/capabilities

   This mandatory container holds the all messages.  RESTCONF protocol capability URIs
   supported by message
   content is sent in the server.

   The HTTP message-body.

   Content is encoded in either JSON or XML format.  A server MUST maintain a last-modified timestamp
   support XML or JSON encoding.  XML encoding rules for this
   container, and return the "Last-Modified" header when this data node
   is retrieved with the GET or HEAD methods. nodes are
   defined in [I-D.ietf-netmod-rfc6020bis].  The server SHOULD maintain an entity-tag same encoding rules are
   used for this container, and
   return the "ETag" header when this data node all XML content.  JSON encoding rules are defined in
   [I-D.ietf-netmod-yang-json].  JSON encoding of meta-data is retrieved defined
   in [I-D.ietf-netmod-yang-metadata].  This encoding is valid JSON, but
   also has special encoding rules to identify module namespaces and
   provide consistent type processing of YANG data.

   Request input content encoding format is identified with the
   GET or HEAD methods.

   The server Content-
   Type header.  This field MUST include be present if a "capability" URI leaf-list entry for the
   "defaults" mode used message-body is sent by
   the server, defined in Section 9.1.2. client.

   The server MUST include a "capability" URI leaf-list entry
   identifying each supported optional protocol feature.  This includes
   optional query parameters support the "Accept" header and MAY include other capability URIs
   defined outside this document.

9.1.1.  Query Parameter URIs

   A new set of RESTCONF Capability URIs are "406 Not Acceptable"
   status-line, as defined to identify in [RFC7231].  Response output content
   encoding format is identified with the
   specific query parameters (defined Accept header in Section 4.8) the request.
   If it is not specified, the request input encoding format SHOULD be
   used, or the server MAY choose any supported by content encoding format.

   If there was no request input, then the
   server.

   The default output encoding is
   XML or JSON, depending on server MUST include a "capability" leaf-list entry for each
   optional query parameter that it supports.

   +-------------+-------+---------------------------------------------+
   | Name        | Secti | URI                                         |
   |             | on    |                                             |
   +-------------+-------+---------------------------------------------+
   | depth       | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 |
   |             |       | .0                                          |
   | fields      | 4.8.3 | urn:ietf:params:restconf:capability:fields: |
   |             |       | 1.0                                         |
   | filter      | 4.8.6 | urn:ietf:params:restconf:capability:filter: |
   |             |       | 1.0                                         |
   | replay      | 4.8.7 | urn:ietf:params:restconf:capability:replay: |
   |             | 4.8.8 | 1.0                                         |
   | with-       | 4.8.9 | urn:ietf:params:restconf:capability:with-   |
   | defaults    |       | defaults:1.0                                |
   +-------------+-------+---------------------------------------------+

                       RESTCONF Query Parameter URIs

9.1.2.  The "defaults" Protocol Capability URI

   This URI identifies the defaults handling mode preference.  File extensions encoded
   in the request are not used to identify format encoding.

5.3.  RESTCONF Meta-Data

   The RESTCONF protocol needs to retrieve the same meta-data that is
   used by in the
   server for processing NETCONF protocol.  Information about default leafs in requests for data resources.
   A parameter named "basic-mode" is required for this capability URI.
   The "basic-mode" definitions leafs, last-
   modified timestamps, etc. are specified in commonly used to annotate
   representations of the "With-Defaults
   Capability for NETCONF" [RFC6243].

      +----------+--------------------------------------------------+
      | Name     | URI                                              |
      +----------+--------------------------------------------------+
      | defaults | urn:ietf:params:restconf:capability:defaults:1.0 |
      +----------+--------------------------------------------------+

                     RESTCONF defaults capability URI datastore contents.  This protocol capability URI MUST be supported by the server, and
   MUST be listed in the "capability" leaf-list meta-data is not
   defined in Section 9.3.

   +------------------+------------------------------------------------+
   | Value            | Description                                    |
   +------------------+------------------------------------------------+
   | report-all       | No data nodes are considered default           |
   | trim             | Values set to the YANG default-stmt value are  |
   |                  | default                                        |
   | explicit         | Values set by the client are never considered  |
   |                  | default                                        |
   +------------------+------------------------------------------------+

   If the "basic-mode" is set to "report-all" then the server MUST
   adhere schema because it applies to the defaults handling behavior defined datastore, and
   is common across all data nodes.

   This information is encoded as attributes in Section 2.1 XML.  JSON encoding of
   [RFC6243].

   If the "basic-mode"
   meta-data is set to "trim" then the server MUST adhere to
   the defaults handling behavior defined in Section 2.2 of [RFC6243].

   If the "basic-mode" is set to "explicit" then the server MUST adhere
   to [I-D.ietf-netmod-yang-metadata].

   The following examples are based on the defaults handling behavior defined example in Section 2.3 of
   [RFC6243].

   Example: (split Appendix D.3.9.
   The "report-all-tagged" mode for display purposes only)

   urn:ietf:params:restconf:capability:defaults:1.0?
        basic-mode=explicit

9.2.  restconf-state/streams
   This optional container provides access to the event notification
   streams supported by the server.  The server MAY omit this container
   if no event notification streams are supported.

   The server will populate this container with "with-defaults" query parameter
   requires that a stream list entry "default" attribute be returned for
   each stream type it supports.  Each stream contains a leaf called
   "events" which contains a URI default nodes.
   This example shows that represents an event stream
   resource.

   Stream resources are defined in Section 3.8.  Notifications are
   defined in Section 6.

9.3.  RESTCONF Monitoring Module

   The "ietf-restconf-monitoring" module defines monitoring information attribute for the RESTCONF protocol. "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 "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991]
   are used by this module for some type definitions. server might respond as follows.

   HTTP/1.1 200 OK
   Date: Mon, 23 Apr 2012 17:01:00 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>

5.3.2.  JSON MetaData Encoding Example

   Note that RFC Ed.: update 6243 defines the date below "default" attribute with XSD, not
   YANG, so the date of RFC publication and
   remove this note.

   <CODE BEGINS> file "ietf-restconf-monitoring@2015-06-19.yang" YANG module ietf-restconf-monitoring {
     namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring";
     prefix "rcmon";

     import ietf-yang-types { prefix yang; }
     import ietf-inet-types { prefix inet; }

     organization
       "IETF NETCONF (Network Configuration) Working Group";

     contact
       "WG Web:   <http://tools.ietf.org/wg/netconf/>
        WG List:  <mailto:netconf@ietf.org>

        WG Chair: Mehmet Ersue
                  <mailto:mehmet.ersue@nsn.com>

        WG Chair: Mahesh Jethanandani
                  <mailto:mjethanandani@gmail.com>

        Editor:   Andy Bierman
                  <mailto:andy@yumaworks.com>

        Editor:   Martin Bjorklund
                  <mailto:mbj@tail-f.com>

        Editor:   Kent Watsen
                  <mailto:kwatsen@juniper.net>";

     description
       "This module contains monitoring information name has to be assigned manually.  The value
   "ietf-netconf-with-defaults" is assigned for the
        RESTCONF protocol.

        Copyright (c) 2015 IETF Trust and the persons identified JSON meta-data 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
        authors follows.

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:01:00 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 the code.  All rights reserved.

        Redistribution and use in source and binary forms, with resource access.  An HTTP
   "status-line" header line is returned for each request.  If a 4xx or
        without modification,
   5xx range status code is permitted pursuant to, and subject
        to returned in the license terms contained in, status-line, then the Simplified BSD License
        set forth error
   information will be returned in Section 4.c of the IETF Trust's Legal Provisions
        Relating response, according to IETF Documents
        (http://trustee.ietf.org/license-info).

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

     // RFC Ed.: replace XXXX with actual RFC number and remove this
     // note.

     // RFC Ed.: remove this note
     // Note: extracted from draft-ietf-netconf-restconf-08.txt

     // RFC Ed.: update the date below with format
   defined in Section 7.1.

5.5.  Message Caching

   Since the date of RFC publication
     // and remove this note.
     revision 2015-06-19 {
       description
         "Initial revision.";
       reference
         "RFC XXXX: RESTCONF Protocol.";
     }

     container restconf-state {
       config false;
       description
         "Contains datastore contents change at unpredictable times, responses
   from a RESTCONF protocol monitoring information.";

       container capabilities {
         description
           "Contains server generally SHOULD NOT be cached.

   The server SHOULD include a list "Cache-Control" header in every response
   that specifies whether the response should be cached.  A "Pragma"
   header specifying "no-cache" MAY also be sent in case the
   "Cache-Control" header is not supported.

   Instead of protocol capability URIs";

         leaf-list capability {
           type inet:uri;
           description "A RESTCONF protocol capability URI.";
         }
       }

       container streams {
         description
           "Container representing relying on HTTP caching, the notification event streams
            supported by client SHOULD track the server.";
          reference
            "RFC 5277, Section 3.4, <streams> element.";

         list stream {
           key name;
           description
             "Each entry describes an event stream supported
   "ETag" and/or "Last-Modified" headers returned by the server.";

           leaf name {
             type string;
             description "The stream name";
             reference "RFC 5277, Section 3.4, <name> element.";
           }

           leaf description {
             type string;
             description "Description of stream content";
             reference
               "RFC 5277, Section 3.4, <description> element.";
           }

           leaf replay-support {
             type boolean;
             description
               "Indicates server for the
   datastore resource (or data resource if replay buffer supported the server supports it).  A
   retrieval request for this stream.
                If 'true', then a resource can include the "If-None-Match" and/
   or "If-Modified-Since" headers, which will cause the server MUST support to return
   a "304 Not Modified" status-line if the 'start-time' resource has not changed.
   The client MAY use the HEAD method to retrieve just the message
   headers, which SHOULD include the "ETag" and 'stop-time' query parameters for this stream.";
             reference
               "RFC 5277, Section 3.4, <replaySupport> element.";
           }

           leaf replay-log-creation-time {
             when "../replay-support" {
               description
                 "Only present "Last-Modified" headers,
   if notification replay this meta-data is supported";
             }
             type yang:date-and-time;
             description
               "Indicates maintained for the time target resource.

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.CR-eventsource-20121211]
   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 operation OPTIONS, HEAD, or GET on the replay log for this stream
                was created.";
             reference
               "RFC 5277, Section 3.4, <replayLogCreationTime>
                element.";
           }

           list access {
             key encoding;
             min-elements 1;
             description
               "The list.  The server will create
   does not support RESTCONF notifications if an entry in this list HTTP error code is
   returned (e.g., "404 Not Found" status-line).

6.2.  Event Streams

   A RESTCONF server that supports notifications will populate a stream
   resource for each
                encoding format that is notification delivery service access point.  A
   RESTCONF client can retrieve the list of supported for this stream.
                The media type 'application/yang.stream' is expected
                for all event streams. This list identifies streams from
   a RESTCONF server using the
                sub-types supported for this stream.";

             leaf encoding {
               type string;
               description
                 "This GET operation 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 secondary encoding format structure and syntax of the conceptual child resources
   within the
                  'text/event-stream' encoding used by all streams. "streams" resource.

   For example:

   The type 'xml' is supported for client might send the media type
                  'application/yang.stream+xml'. following request:

   GET /restconf/data/ietf-restconf-monitoring:restconf-state/
       streams HTTP/1.1
   Host: example.com
   Accept: application/yang.data+xml

   The type 'json'
                  is supported for server might send the media type
                  'application/yang.stream+json'.";

             }

             leaf location {
               type inet:uri;
               mandatory true;
               description
                 "Contains a URL that represents following response:

   HTTP/1.1 200 OK
   Content-Type: application/yang.api+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>
      <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 entry point URL for establishing notification delivery via server
                  sent events.";
             }
           }
         }
       }
     }

   }

   <CODE ENDS>

10.  YANG Module Library
   The "ietf-yang-library" module defined in
   [I-D.ietf-netconf-yang-library] provides information about the YANG
   modules and submodules used subscription resource
   (to receive notifications) by the RESTCONF server.  Implementation
   is mandatory sending an HTTP GET request for RESTCONF servers.  All YANG modules and submodules
   used the
   "location" leaf with the stream list entry.  The value returned by
   the server MUST can be identified in the YANG module library.

10.1.  modules

   This mandatory container holds used for the identifiers actual notification subscription.

   The client will send an HTTP GET request for the YANG data
   model modules supported URL returned by the server.

   The
   server MUST maintain a last-modified timestamp for this
   container, and return the "Last-Modified" header when this data node
   is retrieved with the GET or HEAD methods. "Accept" type "text/event-stream".

   The server SHOULD maintain will treat the connection as an entity-tag for this container, and
   return event stream, using the "ETag" header when this data node is retrieved with the
   GET or HEAD methods.

10.1.1.  modules/module

   This mandatory list contains one entry for each YANG data model
   module supported by the server.  There MUST be an instance of this
   list for every YANG module that is used by the server.

   The contents of this list are defined in the "module" YANG list
   statement in [I-D.ietf-netconf-yang-library].
   Server Sent Events [W3C.CR-eventsource-20121211] transport strategy.

   The server MAY maintain a last-modified timestamp support query parameters for each instance
   of this list entry, and return the "Last-Modified" header when a GET method on this
   data node is retrieved with
   resource.  These parameters are specific to each notification stream.

   For example:

   The client might send the following request:

   GET or HEAD methods.  If not
   supported then the timestamp for the parent "modules" container MAY
   be used instead. /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 MAY maintain an entity-tag for each instance of this list
   entry, and return might send the "ETag" header when following response:

   HTTP/1.1 200 OK
   Content-Type: application/yang.api+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 data node is retrieved
   with URL value to start monitoring
   the event stream:

   GET or HEAD methods.  If not supported then the timestamp
   for the parent "modules" container /streams/NETCONF HTTP/1.1
   Host: example.com
   Accept: text/event-stream
   Cache-Control: no-cache
   Connection: keep-alive

   A RESTCONF client MAY be used instead.

11.  IANA Considerations

11.1.  The "restconf" Relation Type

   This specification registers request the "restconf" relation type in server compress the Link
   Relation Type Registry defined by [RFC5988]:

      Relation Name:  restconf
      Description:  Identifies events using
   the root of RESTCONF API as configured
                    on this HTTP server. 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

6.3.1.  NETCONF Event Stream

   The "restconf" relation
                    defines the root of server SHOULD support the API "NETCONF" notification stream defined
   in RFCXXXX.
                    Subsequent revisions of [RFC5277].  For this stream, RESTCONF will use alternate
                    relation values notification subscription
   requests MAY specify parameters indicating the events it wishes to support protocol versioning.

      Reference:  RFC XXXX

   `

11.2.  YANG Module Registry

   This document registers two URIs in
   receive.  These query parameters are optional to implement, and only
   available if the IETF XML registry [RFC3688].
   Following server supports them.

            +------------+---------+-------------------------+
            | Name       | Section | Description             |
            +------------+---------+-------------------------+
            | start-time | 4.8.7   | replay event start time |
            | stop-time  | 4.8.8   | replay event stop time  |
            | filter     | 4.8.6   | boolean content filter  |
            +------------+---------+-------------------------+

                      NETCONF Stream Query Parameters

   The semantics and syntax for these query parameters are defined in
   the format sections listed above.  The YANG encoding MUST be converted to
   URL-encoded string for use in RFC 3688, the following registration is
   requested request URI.

   Refer to Appendix D.3.6 for filter parameter examples.

6.4.  Receiving Event Notifications

   RESTCONF notifications are encoded according to be made.

        URI: urn:ietf:params:xml:ns:yang:ietf-restconf
        Registrant Contact: The NETMOD WG of the IETF.
        XML: N/A, definition of the requested URI
   event stream.  The NETCONF stream defined in [RFC5277] is an encoded in
   XML namespace.

        URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
        Registrant Contact: format.

   The NETMOD WG structure of the IETF.
        XML: N/A, the requested URI event data is an XML namespace.

   This document registers two YANG modules in based on the YANG Module Names
   registry [RFC6020].

     name:         ietf-restconf
     namespace:    urn:ietf:params:xml:ns:yang:ietf-restconf
     prefix:       rc
     // RFC Ed.: replace XXXX with RFC number and remove this note
     reference:    RFC XXXX

     name:         ietf-restconf-monitoring
     namespace:    urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
     prefix:       rcmon
     // RFC Ed.: replace XXXX with RFC number and remove this note
     reference:    RFC XXXX

11.3.  application/yang Media Sub Types

   The parent MIME media type for RESTCONF resources is application/
   yang, which is defined "notification"
   element definition in [RFC6020].  This document defines Section 4 of [RFC5277].  It MUST conform to the
   following sub-types
   schema for this media type.

      - api
      - data
      - datastore
      - errors
      - operation
      - stream

      Type name: application

      Subtype name: yang.xxx

      Required parameters: none

      Optional parameters: See section 4.8 the "notification" element in RFC XXXX

      Encoding considerations: 8-bit

      Security considerations: See Section 12 in RFC XXXX

      Interoperability considerations: none

      // RFC Ed.: replace XXXX with RFC number and remove this note
      Published specification: RFC XXXX

11.4.  RESTCONF Capability URNs

   [Note to RFC Editor:
    The RESTCONF Protocol Capability Registry does not yet exist;
    Need to ask IANA to create it; remove this note for publication
   ]

   This document defines a registry for RESTCONF capability identifiers.
   The name 4 of [RFC5277],
   except the registry is "RESTCONF Capability URNs".  The registry
   shall record XML namespace for each entry:

   o this element is defined as:

   urn:ietf:params:xml:ns:yang:ietf-restconf

   For JSON encoding purposes, the module name of for the RESTCONF capability.  By convention, this name "notification"
   element is
      prefixed with "ietf-restconf".

   Two child nodes within the colon ':' character.

   o "notification" container are expected,
   representing the URN for event time and the RESTCONF capability.

   This document registers several capability identifiers in "RESTCONF
   Capability URNs" registry:

     Index
        Capability Identifier
     ------------------------

     :defaults
         urn:ietf:params:restconf:capability:defaults:1.0

     :depth
         urn:ietf:params:restconf:capability:depth:1.0

     :fields
         urn:ietf:params:restconf:capability:fields:1.0

     :filter
         urn:ietf:params:restconf:capability:filter:1.0

     :replay
         urn:ietf:params:restconf:capability:replay:1.0

     :with-defaults
         urn:ietf:params:restconf:capability:with-defaults:1.0

12.  Security Considerations

   This section provides security considerations for the resources event payload.  The "event-time"
   node is defined by within the RESTCONF protocol.  Security considerations for HTTPS
   are defined in [RFC2818].  Security considerations for "ietf-restconf" module namespace.  The
   name and namespace of the content
   manipulated payload element are determined by RESTCONF can be found in the documents defining data
   models.

   This document does not specify an authentication scheme, but it does
   require that an authenticated NETCONF username be associated with
   each HTTP request.  The authentication scheme MAY be implemented in the underlying transport layer (e.g., client certificates) or within YANG
   module containing the HTTP layer (e.g., Basic Auth, OAuth, etc.).  RESTCONF does not
   itself define an authentication mechanism.  Authentication MUST occur
   in a lower layer.  Implementors SHOULD provide a comprehensive
   authorization scheme with RESTCONF and ensure that notification-stmt.

   In the resulting
   NETCONF username is made available to following example, the RESTCONF server.

   Authorization of individual user access to operations and data MAY be
   configured via NETCONF Access Control Model (NACM) [RFC6536], as
   specified in Section 4.

   Configuration information YANG module "example-mod" is by its very nature sensitive.  Its
   transmission in the clear and without integrity checking leaves
   devices open to classic eavesdropping and false data injection
   attacks.  Configuration information often contains passwords, user
   names, service descriptions, and topological information, all of
   which are sensitive.  Because of this, this protocol SHOULD be
   implemented carefully with adequate attention to all manner of attack
   one might expect to experience with other management interfaces.

   Different environments may well allow different rights prior to and
   then after authentication.  When an operation is not properly
   authorized, used:

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

       notification event {
        leaf event-class { type string; }
        container reporting-entity {
          leaf card { type string; }
        }
        leaf severity { type string; }
       }
     }

   An example SSE event notification encoded using XML:

   data: <notification
   data:    xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
   data:    <event-time>2013-12-21T00:01:00Z</event-time>
   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>

   An example SSE event notification encoded using JSON:

   data: {
   data:   "ietf-restconf:notification": {
   data:     "event-time": "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 are whitespace sensitive,
   the RESTCONF server MUST return HTTP error status code
   401 Unauthorized.  Note that authorization information above messages can be
   exchanged in encoded onto a single line.  For example:

   For example: ('\' line wrapping added for formatting only)

      XML:

      data: <notification xmlns="urn:ietf:params:xml:ns:yang:ietf-rest\
      conf"><event-time>2013-12-21T00:01:00Z</event-time><event xmlns="\
      http://example.com/event/1.0"><event-class>fault</event-class><re\
      portingEntity><card>Ethernet0</card></reporting-entity><severity>\
      major</severity></event></notification>

      JSON:

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

   The SSE specifications supports the form of configuration information, which is all following additional fields:
   event, id and retry.  A RESTCONF server MAY send the
   more reason "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 ensure the security contents of the connection.

13.  Acknowledgements

   The authors would like notification itself.  RESTCONF
   servers that do not send the "id" field also do not need to thank support
   the following people HTTP header "Last-Event-Id".  RESTCONF servers that do send the
   "id" field MUST still support the "startTime" query parameter as the
   preferred means for their
   contributions a client to this document: Ladislav Lhotka, Juergen
   Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford.

   Contributions specify where to this material by Andy Bierman are based upon work
   supported by restart the The Space & Terrestrial Communications Directorate
   (S&TCD) under Contract No.  W15P7T-13-C-A616.  Any opinions, findings
   and conclusions or recommendations expressed in this material event
   stream.

7.  Error Reporting

   HTTP status-lines are
   those of the author(s) and do not necessarily reflect the views of used to report success or failure for RESTCONF
   operations.  The Space & Terrestrial Communications Directorate (S&TCD).

14.  References

14.1.  Normative References

   [I-D.ietf-netconf-yang-library]
              Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
              Library", draft-ietf-netconf-yang-library-01 (work in
              progress), July 2015.

   [I-D.ietf-netmod-rfc6020bis]
              Bjorklund, M., "The YANG 1.1 Data Modeling Language",
              draft-ietf-netmod-rfc6020bis-07 (work in progress),
              September 2015.

   [I-D.ietf-netmod-yang-json]
              Lhotka, L., "JSON Encoding of Data Modeled with YANG",
              draft-ietf-netmod-yang-json-06 (work in progress), October
              2015.

   [I-D.ietf-netmod-yang-metadata]
              Lhotka, L., "Defining and Using Metadata with YANG",
              draft-ietf-netmod-yang-metadata-02 (work <rpc-error> element returned in progress),
              September 2015.

   [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part Two: Media Types", RFC 2046,
              November 1996.

   [RFC2119]  Bradner, S., "Key words NETCONF error
   responses contains some useful information.  This error information
   is adapted for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2818]  Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              January 2004.

   [RFC3986]  Berners-Lee, T., Fielding, RESTCONF, and error information is returned for
   "4xx" class of status codes.

   The following table summarizes the return status codes used
   specifically by RESTCONF operations:

   +----------------------------+--------------------------------------+
   | Status-Line                | Description                          |
   +----------------------------+--------------------------------------+
   | 100 Continue               | POST accepted, 201 should follow     |
   | 200 OK                     | Success with response message-body   |
   | 201 Created                | POST to create a resource success    |
   | 204 No Content             | Success without response message-    |
   |                            | body                                 |
   | 304 Not Modified           | Conditional operation not done       |
   | 400 Bad Request            | Invalid request message              |
   | 401 Unauthorized           | Client cannot be authenticated       |
   | 403 Forbidden              | Access to resource denied            |
   | 404 Not Found              | Resource target or resource node not |
   |                            | found                                |
   | 405 Method Not Allowed     | Method not allowed for target        |
   |                            | resource                             |
   | 409 Conflict               | Resource or lock in use              |
   | 412 Precondition Failed    | Conditional method is false          |
   | 413 Request Entity Too     | too-big error                        |
   | Large                      |                                      |
   | 414 Request-URI Too Large  | too-big error                        |
   | 415 Unsupported Media Type | non RESTCONF media type              |
   | 500 Internal Server Error  | operation-failed                     |
   | 501 Not Implemented        | unknown-operation                    |
   | 503 Service Unavailable    | Recoverable server error             |
   +----------------------------+--------------------------------------+

                    HTTP Status Codes used in RESTCONF

   Since an operation resource is defined with a YANG "rpc" statement,
   and an action is defined with a YANG "action" statement, a mapping
   between the NETCONF <error-tag> value and the HTTP status code is
   needed.  The specific error condition and response code to use are
   data-model specific and might be contained in the YANG "description"
   statement for the "action" or "rpc" statement.

                 +-------------------------+-------------+
                 | <error&#8209;tag>       | status code |
                 +-------------------------+-------------+
                 | in-use                  | 409         |
                 | invalid-value           | 400         |
                 | too-big                 | 413         |
                 | missing-attribute       | 400         |
                 | bad-attribute           | 400         |
                 | unknown-attribute       | 400         |
                 | bad-element             | 400         |
                 | unknown-element         | 400         |
                 | unknown-namespace       | 400         |
                 | access-denied           | 403         |
                 | lock-denied             | 409         |
                 | resource-denied         | 409         |
                 | rollback-failed         | 500         |
                 | data-exists             | 409         |
                 | data-missing            | 409         |
                 | operation-not-supported | 501         |
                 | operation-failed        | 500         |
                 | partial-operation       | 500         |
                 | malformed-message       | 400         |
                 +-------------------------+-------------+

                   Mapping from error-tag to status code

7.1.  Error Response Message

   When an error occurs for a request message on a data resource or an
   operation resource, and a "4xx" class of status codes will be
   returned (except for status code "403 Forbidden"), then the server
   SHOULD send a response message-body containing the information
   described by the "errors" container definition within the YANG module
   Section 8.  The Content-Type of this response message MUST be
   application/yang.errors (see example below).

   The client MAY specify the desired encoding for error messages by
   specifying the appropriate media-type in the Accept header.  If no
   error media is specified, then the media type of 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.errors+xml" or "application/
   yang.errors+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:

   +--ro errors
      +--ro error*
         +--ro error-type       enumeration
         +--ro error-tag        string
         +--ro error-app-tag?   string
         +--ro error-path?      instance-identifier
         +--ro error-message?   string
         +--ro error-info

   The semantics and syntax for RESTCONF error messages are defined in
   the "application/yang.errors" restconf-media-type extension in
   Section 8.

   Examples:

   The following example shows an error returned for an "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 is used to specify the desired encoding for the
   error message.  This example's use of the Accept header is especially
   notable since the DELETE method typically doesn't return a message-
   body and hence Accept headers are typically not passed.

   DELETE /restconf/data/example-jukebox:jukebox/
      library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
   Host: example.com
   Accept: application/yang.errors+json

   The server might respond:

      HTTP/1.1 409 Conflict
      Date: Mon, 23 Apr 2012 17:11:00 GMT
      Server: example-server
      Content-Type: application/yang.errors+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:

   POST /restconf/data/example-jukebox:jukebox HTTP/1.1
   Host: example.com

   The server might respond (some lines wrapped for display purposes):

   HTTP/1.1 409 Conflict
   Date: Mon, 23 Apr 2012 17:11:00 GMT
   Server: example-server
   Content-Type: application/yang.errors+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>

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.  E.g., the "restconf" container is
   not intended to be implemented as a top-level data node (under the "/
   restconf/data" entry point).

   RFC Ed.: update the date below with the date of RFC publication and
   remove this note.

   <CODE BEGINS> file "ietf-restconf@2016-03-16.yang"

   module ietf-restconf {
     namespace "urn:ietf:params:xml:ns:yang:ietf-restconf";
     prefix "rc";

     organization
       "IETF NETCONF (Network Configuration) Working Group";

     contact
       "WG Web:   <http://tools.ietf.org/wg/netconf/>
        WG List:  <mailto:netconf@ietf.org>

        WG Chair: Mehmet Ersue
                  <mailto:mehmet.ersue@nsn.com>

        WG Chair: Mahesh Jethanandani
                  <mailto:mjethanandani@gmail.com>

        Editor:   Andy Bierman
                  <mailto:andy@yumaworks.com>

        Editor:   Martin Bjorklund
                  <mailto:mbj@tail-f.com>

        Editor:   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.

        Copyright (c) 2016 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 XXXX; see
        the RFC itself for full legal notices.";

     // RFC Ed.: replace XXXX with actual RFC number and remove this
     // note.

     // RFC Ed.: remove this note
     // Note: extracted from draft-ietf-netconf-restconf-10.txt

     // RFC Ed.: update the date below with the date of RFC publication
     // and remove this note.
     revision 2016-03-16 {
       description
         "Initial revision.";
       reference
         "RFC XXXX: RESTCONF Protocol.";
     }

     extension restconf-media-type {
      argument media-type-id {
        yin-element true;
      }
      // RFC Ed.: replace draft-ietf-netmod-yang-json with RFC number
      // in the description below, and remove this note.

      description
        "This extension is used to specify a YANG data structure which
         represents a conceptual RESTCONF media type.
         Data definition statements within this extension specify
         the generic syntax for the specific media type.

         YANG is mapped to specific encoding formats outside the
         scope of this extension statement. RFC 6020 defines XML
         encoding rules for all RESTCONF media types that use
         the '+xml' suffix. draft-ietf-netmod-yang-json defines
         JSON encoding rules for all RESTCONF media types that
         use the '+json' suffix.

         The 'media-type-id' parameter value identifies the media type
         that is being defined. It contains the string associated
         with the generic media type, i.e., no suffix is specified.

         This extension is ignored unless it appears as a top-level
         statement. It SHOULD contain data definition statements
         that result in exactly one container data node definition.
         This allows compliant translation to an XML instance
         document for each media type.

         The module name and namespace value for the YANG module using
         the extension statement is assigned to instance document data
         conforming to the data definition statements within
         this extension.

         The sub-statements 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 sub-statements 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 sub-statements have special
         meaning when used within a restconf-resource 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 is limited to the module
           containing this extension statement, and the modules
           imported into that module.
         ";
     }

     rc:restconf-media-type "application/yang.errors" {
       uses errors;
     }

     rc:restconf-media-type "application/yang.api" {
       uses restconf;
     }

     grouping errors {
       description
         "A grouping that contains a YANG container
          representing the syntax and semantics of a
          YANG Patch errors 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.";
           }

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

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

     grouping restconf {
       description
         "Conceptual container representing the
          application/yang.api resource type.";

       container restconf {
         description
           "Conceptual container representing the
            application/yang.api resource type.";

         container data {
           description
             "Container representing the application/yang.datastore
              resource type. Represents the conceptual root of all
              operational data and configuration data supported by
              the server.  The child nodes of this container can be
              any data resource (application/yang.data), which are
              defined as top-level data nodes from the YANG modules
              advertised by the server in the ietf-restconf-monitoring
              module.";
         }

         container operations {
           description
             "Container for all operation resources
              (application/yang.operation),

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

              E.g.;

                 POST /restconf/operations/show-log-errors

                 leaf show-log-errors {
                   type empty;
                 }
             ";
         }

         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>

9.  RESTCONF Monitoring

   The "ietf-restconf-monitoring" module provides information about the
   RESTCONF protocol capabilities and event notification streams
   available from the server.  A RESTCONF server MUST implement the "/
   restconf-state/capabilities" container in this module.

   YANG Tree Diagram for "ietf-restconf-monitoring" module:

   +--ro restconf-state
      +--ro capabilities
      |  +--ro capability*   inet:uri
      +--ro streams
         +--ro stream* [name]
            +--ro name                        string
            +--ro description?                string
            +--ro replay-support?             boolean
            +--ro replay-log-creation-time?   yang:date-and-time
            +--ro access* [encoding]
               +--ro encoding  string
               +--ro location  inet:uri

9.1.  restconf-state/capabilities

   This mandatory container holds the RESTCONF protocol capability URIs
   supported by the server.

   The server MUST maintain a last-modified timestamp for this
   container, and return the "Last-Modified" header when this data node
   is retrieved with the GET or HEAD methods.

   The server SHOULD maintain an entity-tag for this container, and
   return the "ETag" header when this data node is retrieved with the
   GET or HEAD methods.

   The server MUST include a "capability" URI leaf-list entry for the
   "defaults" mode used by the server, defined in Section 9.1.2.

   The server MUST include a "capability" URI leaf-list entry
   identifying each supported optional protocol feature.  This includes
   optional query parameters and MAY include other capability URIs
   defined outside this document.

9.1.1.  Query Parameter URIs

   A new set of RESTCONF Capability URIs are defined to identify the
   specific query parameters (defined in Section 4.8) supported by the
   server.

   The server MUST include a "capability" leaf-list entry for each
   optional query parameter that it supports.

   +-------------+-------+---------------------------------------------+
   | Name        | Secti | URI                                         |
   |             | on    |                                             |
   +-------------+-------+---------------------------------------------+
   | depth       | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 |
   |             |       | .0                                          |
   | fields      | 4.8.3 | urn:ietf:params:restconf:capability:fields: |
   |             |       | 1.0                                         |
   | filter      | 4.8.6 | urn:ietf:params:restconf:capability:filter: |
   |             |       | 1.0                                         |
   | replay      | 4.8.7 | urn:ietf:params:restconf:capability:replay: |
   |             | 4.8.8 | 1.0                                         |
   | with-       | 4.8.9 | urn:ietf:params:restconf:capability:with-   |
   | defaults    |       | defaults:1.0                                |
   +-------------+-------+---------------------------------------------+

                       RESTCONF Query Parameter URIs

9.1.2.  The "defaults" Protocol Capability URI

   This URI identifies the defaults handling mode that is used by the
   server for processing default leafs in requests for data resources.
   A parameter named "basic-mode" is required for this capability URI.
   The "basic-mode" definitions are specified in the "With-Defaults
   Capability for NETCONF" [RFC6243].

      +----------+--------------------------------------------------+
      | Name     | URI                                              |
      +----------+--------------------------------------------------+
      | defaults | urn:ietf:params:restconf:capability:defaults:1.0 |
      +----------+--------------------------------------------------+

                     RESTCONF defaults capability URI

   This protocol capability URI MUST be supported by the server, and
   MUST be listed in the "capability" leaf-list in Section 9.3.

   +------------------+------------------------------------------------+
   | Value            | Description                                    |
   +------------------+------------------------------------------------+
   | report-all       | No data nodes are considered default           |
   | trim             | Values set to the YANG default-stmt value are  |
   |                  | default                                        |
   | explicit         | Values set by the client are never considered  |
   |                  | default                                        |
   +------------------+------------------------------------------------+

   If the "basic-mode" is set to "report-all" then the server MUST
   adhere to the defaults handling behavior defined in Section 2.1 of
   [RFC6243].

   If the "basic-mode" is set to "trim" then the server MUST adhere to
   the defaults handling behavior defined in Section 2.2 of [RFC6243].

   If the "basic-mode" is set to "explicit" then the server MUST adhere
   to the defaults handling behavior defined in Section 2.3 of
   [RFC6243].

   Example: (split for display purposes only)

   urn:ietf:params:restconf:capability:defaults:1.0?
        basic-mode=explicit

9.2.  restconf-state/streams

   This optional container provides access to the event notification
   streams supported by the server.  The server MAY omit this container
   if no event notification streams are supported.

   The server will populate this container with a stream list entry for
   each stream type it supports.  Each stream contains a leaf called
   "events" which contains a URI that represents an event stream
   resource.

   Stream resources are defined in Section 3.8.  Notifications are
   defined in Section 6.

9.3.  RESTCONF Monitoring Module

   The "ietf-restconf-monitoring" module defines monitoring information
   for the RESTCONF protocol.

   The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991]
   are used by this module for some type definitions.

   RFC Ed.: update the date below with the date of RFC publication and
   remove this note.

   <CODE BEGINS> file "ietf-restconf-monitoring@2016-03-16.yang"

   module ietf-restconf-monitoring {
     namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring";
     prefix "rcmon";

     import ietf-yang-types { prefix yang; }
     import ietf-inet-types { prefix inet; }

     organization
       "IETF NETCONF (Network Configuration) Working Group";

     contact
       "WG Web:   <http://tools.ietf.org/wg/netconf/>
        WG List:  <mailto:netconf@ietf.org>

        WG Chair: Mehmet Ersue
                  <mailto:mehmet.ersue@nsn.com>

        WG Chair: Mahesh Jethanandani
                  <mailto:mjethanandani@gmail.com>

        Editor:   Andy Bierman
                  <mailto:andy@yumaworks.com>

        Editor:   Martin Bjorklund
                  <mailto:mbj@tail-f.com>

        Editor:   Kent Watsen
                  <mailto:kwatsen@juniper.net>";

     description
       "This module contains monitoring information for the
        RESTCONF protocol.

        Copyright (c) 2016 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 XXXX; see
        the RFC itself for full legal notices.";

     // RFC Ed.: replace XXXX with actual RFC number and remove this
     // note.

     // RFC Ed.: remove this note
     // Note: extracted from draft-ietf-netconf-restconf-10.txt

     // RFC Ed.: update the date below with the date of RFC publication
     // and remove this note.
     revision 2016-03-16 {
       description
         "Initial revision.";
       reference
         "RFC XXXX: RESTCONF Protocol.";
     }

     container restconf-state {
       config false;
       description
         "Contains RESTCONF protocol monitoring information.";

       container capabilities {
         description
           "Contains a list of protocol capability URIs";

         leaf-list capability {
           type inet:uri;
           description "A RESTCONF protocol capability URI.";
         }
       }

       container streams {
         description
           "Container representing the notification event streams
            supported by the server.";
          reference
            "RFC 5277, Section 3.4, <streams> element.";

         list stream {
           key name;
           description
             "Each entry describes an event stream supported by
              the server.";

           leaf name {
             type string;
             description "The stream name";
             reference "RFC 5277, Section 3.4, <name> element.";
           }

           leaf description {
             type string;
             description "Description of stream content";
             reference
               "RFC 5277, Section 3.4, <description> element.";
           }

           leaf replay-support {
             type boolean;
             description
               "Indicates if replay buffer supported for this stream.
                If 'true', then the server MUST support the 'start-time'
                and 'stop-time' query parameters for this stream.";
             reference
               "RFC 5277, Section 3.4, <replaySupport> element.";
           }

           leaf replay-log-creation-time {
             when "../replay-support" {
               description
                 "Only present if notification replay is supported";
             }
             type yang:date-and-time;
             description
               "Indicates the time the replay log for this stream
                was created.";
             reference
               "RFC 5277, Section 3.4, <replayLogCreationTime>
                element.";
           }

           list access {
             key encoding;
             min-elements 1;
             description
               "The server will create an entry in this list for each
                encoding format that is supported for this stream.

                The media type 'application/yang.stream' is expected
                for all event streams. This list identifies the
                sub-types supported for this stream.";

             leaf encoding {
               type string;
               description
                 "This is the secondary encoding format within the
                  'text/event-stream' encoding used by all streams.
                  The type 'xml' is supported for the media type
                  'application/yang.stream+xml'. The type 'json'
                  is supported for the media type
                  'application/yang.stream+json'.";

             }

             leaf location {
               type inet:uri;
               mandatory true;
               description
                 "Contains a URL that represents the entry point
                  for establishing notification delivery via server
                  sent events.";
             }
           }
         }
       }
     }

   }

   <CODE ENDS>

10.  YANG Module Library

   The "ietf-yang-library" module defined in
   [I-D.ietf-netconf-yang-library] provides information about the YANG
   modules and submodules used by the RESTCONF server.  Implementation
   is mandatory for RESTCONF servers.  All YANG modules and submodules
   used by the server MUST be identified in the YANG module library.

10.1.  modules

   This mandatory container holds the identifiers for the YANG data
   model modules supported by the server.

   The server MUST maintain a last-modified timestamp for this
   container, and return the "Last-Modified" header when this data node
   is retrieved with the GET or HEAD methods.

   The server SHOULD maintain an entity-tag for this container, and
   return the "ETag" header when this data node is retrieved with the
   GET or HEAD methods.

10.1.1.  modules/module

   This mandatory list contains one entry for each YANG data model
   module supported by the server.  There MUST be an instance of this
   list for every YANG module that is used by the server.

   The contents of this list are defined in the "module" YANG list
   statement in [I-D.ietf-netconf-yang-library].

   The server SHOULD maintain a last-modified timestamp for each
   instance of this list entry, and return the "Last-Modified" header
   when this data node is retrieved with the GET or HEAD methods.

   The server SHOULD maintain an entity-tag for each instance of this
   list entry, and return the "ETag" header when this data node is
   retrieved with the GET or HEAD methods.

11.  IANA Considerations

11.1.  The "restconf" Relation Type

   This specification registers the "restconf" relation type in the Link
   Relation Type Registry defined by [RFC5988]:

      Relation Name:  restconf

      Description:  Identifies the root of RESTCONF API as configured
                    on this HTTP server.  The "restconf" relation
                    defines the root of the API defined in RFCXXXX.
                    Subsequent revisions of RESTCONF will use alternate
                    relation values to support protocol versioning.

      Reference:  RFCXXXX

   `

11.2.  YANG Module Registry
   This document registers two URIs in the IETF XML registry [RFC3688].
   Following the format in RFC 3688, the following registration is
   requested to be made.

        URI: urn:ietf:params:xml:ns:yang:ietf-restconf
        Registrant Contact: The NETMOD WG of the IETF.
        XML: N/A, the requested URI is an XML namespace.

        URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
        Registrant Contact: The NETMOD WG of the IETF.
        XML: N/A, the requested URI is an XML namespace.

   This document registers two YANG modules in the YANG Module Names
   registry [RFC6020].

     name:         ietf-restconf
     namespace:    urn:ietf:params:xml:ns:yang:ietf-restconf
     prefix:       rc
     // RFC Ed.: replace XXXX with RFC number and remove this note
     reference:    RFCXXXX

     name:         ietf-restconf-monitoring
     namespace:    urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
     prefix:       rcmon
     // RFC Ed.: replace XXXX with RFC number and remove this note
     reference:    RFCXXXX

11.3.  application/yang Media Sub Types

   The parent MIME media type for RESTCONF resources is application/
   yang, which is defined in [RFC6020].  This document defines the
   following sub-types for this media type.

      - api
      - data
      - datastore
      - errors
      - operation
      - stream

      Type name: application

      Subtype name: yang.xxx, where "xxx" is 1 of "api",
      "data", "datastore", "errors", "operation", or "stream"

      Required parameters: none

      Optional parameters: See section 4.8 in RFC XXXX
      Encoding considerations: 8-bit

      Security considerations: See Section 12 in RFC XXXX

      Interoperability considerations: none

      // RFC Ed.: replace XXXX with RFC number and remove this note
      Published specification: RFC XXXX

11.4.  RESTCONF Capability URNs

   [Note to RFC Editor:
    The RESTCONF Protocol Capability Registry does not yet exist;
    Need to ask IANA to create it; remove this note for publication
   ]

   This document defines a registry for RESTCONF capability identifiers.
   The name of the registry is "RESTCONF Capability URNs".  The registry
   shall record for each entry:

   o  the name of the RESTCONF capability.  By convention, this name is
      prefixed with the colon ':' character.

   o  the URN for the RESTCONF capability.

   This document registers several capability identifiers in "RESTCONF
   Capability URNs" registry:

     Index
        Capability Identifier
     ------------------------

     :defaults
         urn:ietf:params:restconf:capability:defaults:1.0

     :depth
         urn:ietf:params:restconf:capability:depth:1.0

     :fields
         urn:ietf:params:restconf:capability:fields:1.0

     :filter
         urn:ietf:params:restconf:capability:filter:1.0

     :replay
         urn:ietf:params:restconf:capability:replay:1.0

     :with-defaults
         urn:ietf:params:restconf:capability:with-defaults:1.0

12.  Security Considerations

   This section provides security considerations for the resources
   defined by the RESTCONF protocol.  Security considerations for HTTPS
   are defined in [RFC2818].  RESTCONF does not specify which YANG
   modules a server needs to support.  Security considerations for the
   YANG-defined content manipulated by RESTCONF can be found in the
   documents defining those YANG modules.

   This document does not require use of a specific client
   authentication mechanism or authorization model, but it does require
   that a client authentication mechanism and authorization model is
   used whenever a client accesses a protected resource.  Client
   authentication MUST be implemented using client certificates or MUST
   be implemented using an HTTP authentication scheme.  Client
   authorization MAY be configured using the NETCONF Access Control
   Model (NACM) [RFC6536].

   Configuration information is by its very nature sensitive.  Its
   transmission in the clear and without integrity checking leaves
   devices open to classic eavesdropping and false data injection
   attacks.  Configuration information often contains passwords, user
   names, service descriptions, and topological information, all of
   which are sensitive.  Because of this, this protocol SHOULD be
   implemented carefully with adequate attention to all manner of attack
   one might expect to experience with other management interfaces.

   Different environments may well allow different rights prior to and
   then after authentication.  When an operation is not properly
   authorized, the RESTCONF server MUST return a "401 Unauthorized"
   status-line.  Note that authorization information can be exchanged in
   the form of configuration information, which is all the more reason
   to ensure the security of the connection.

13.  Acknowledgements

   The authors would like to thank the following people for their
   contributions to this document: Ladislav Lhotka, Juergen
   Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford.

   The authors would like to thank the following people for their
   excellent review comments and contributions to this document: Qin Wu,
   Joe Clarke, Bert Wijnen, Ladislav Lhotka, Rodney Cummings, Frank
   Xialiang, Tom Petch, Robert Sparks, Balint Uveges, Randy Presuhn, and
   Sue Hares.

   Contributions to this material by Andy Bierman are based upon work
   supported by the The Space & Terrestrial Communications Directorate
   (S&TCD) under Contract No.  W15P7T-13-C-A616.  Any opinions, findings
   and conclusions or recommendations expressed in this material are
   those of the author(s) and do not necessarily reflect the views of
   The Space & Terrestrial Communications Directorate (S&TCD).

14.  References

14.1.  Normative References

   [I-D.ietf-netconf-yang-library]
              Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
              Library", draft-ietf-netconf-yang-library-01 (work in
              progress), July 2015.

   [I-D.ietf-netmod-rfc6020bis]
              Bjorklund, M., "The YANG 1.1 Data Modeling Language",
              draft-ietf-netmod-rfc6020bis-11 (work in progress),
              February 2016.

   [I-D.ietf-netmod-yang-json]
              Lhotka, L., "JSON Encoding of Data Modeled with YANG",
              draft-ietf-netmod-yang-json-06 (work in progress), October
              2015.

   [I-D.ietf-netmod-yang-metadata]
              Lhotka, L., "Defining and Using Metadata with YANG",
              draft-ietf-netmod-yang-metadata-02 (work in progress),
              September 2015.

   [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part Two: Media Types", RFC 2046,
              November 1996.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2818]  Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              January 2004.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66, RFC
              3986, January 2005.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246, August 2008.

   [RFC5277]  Chisholm, S. and H. Trevino, "NETCONF Event
              Notifications", RFC 5277, July 2008.

   [RFC5280]  Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
              Housley, R., and T. Polk, "Internet X.509 Public Key
              Infrastructure Certificate and Certificate Revocation List
              (CRL) Profile", RFC 5280, May 2008.

   [RFC5789]  Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC
              5789, March 2010.

   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988, October 2010.

   [RFC6020]  Bjorklund, M., "YANG - A Data Modeling Language for the
              Network Configuration Protocol (NETCONF)", RFC 6020,
              October 2010.

   [RFC6125]  Saint-Andre, P. and J. Hodges, "Representation and
              Verification of Domain-Based Application Service Identity
              within Internet Public Key Infrastructure Using X.509
              (PKIX) Certificates in the Context of Transport Layer
              Security (TLS)", RFC 6125, March 2011.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, June 2011.

   [RFC6243]  Bierman, A. and B. Lengyel, "With-defaults Capability for
              NETCONF", RFC 6243, June 2011.

   [RFC6415]  Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC
              6415, October 2011.

   [RFC6536]  Bierman, A. and M. Bjorklund, "Network Configuration
              Protocol (NETCONF) Access Control Model", RFC 6536, March
              2012.

   [RFC6570]  Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
              and D. Orchard, "URI Template", RFC 6570, March 2012.

   [RFC6991]  Schoenwaelder, J., "Common YANG Data Types", RFC 6991,
              July 2013.

   [RFC7158]

   [RFC7159]  Bray, T., Ed., "The JSON JavaScript Object Notation (JSON) Data
              Interchange Format", RFC
              7158, 7159, DOI 10.17487/RFC7159, March 2013.
              2014, <http://www.rfc-editor.org/info/rfc7159>.

   [RFC7230]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Message Syntax and Routing", RFC 7230, June
              2014.

   [RFC7231]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Semantics Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Semantics and Content", RFC 7231, June 2014.

   [RFC7232]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Conditional Requests", RFC 7232, June 2014.

   [RFC7235]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Authentication", RFC 7235, June 2014.

   [RFC7320]  Nottingham, M., "URI Design and Ownership", BCP 190, RFC
              7320, July 2014.

   [RFC7589]  Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the
              NETCONF Protocol over Transport Layer Security (TLS) with
              Mutual X.509 Authentication", RFC 7589, DOI 10.17487/
              RFC7589, June 2015,
              <http://www.rfc-editor.org/info/rfc7589>.

   [W3C.CR-eventsource-20121211]
              Hickson, I., "Server-Sent Events", World Wide Web
              Consortium CR CR-eventsource-20121211, December 2012,
              <http://www.w3.org/TR/2012/CR-eventsource-20121211>.

   [W3C.REC-html5-20141028]
              Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
              Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", World
              Wide Web Consortium Recommendation REC-html5-20141028,
              October 2014,
              <http://www.w3.org/TR/2014/REC-html5-20141028>.

   [W3C.REC-xml-20081126]
              Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C.,
              and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth
              Edition)", World Wide Web Consortium Recommendation REC-
              xml-20081126, November 2008,
              <http://www.w3.org/TR/2008/REC-xml-20081126>.

   [XPath]    Clark, J. and Content", RFC 7231, June 2014.

   [RFC7232]  Fielding, R. S. DeRose, "XML Path Language (XPath)
              Version 1.0", World Wide Web Consortium Recommendation
              REC-xpath-19991116, November 1999,
              <http://www.w3.org/TR/1999/REC-xpath-19991116>.

14.2.  Informative References

   [I-D.ietf-netconf-yang-patch]
              Bierman, A., Bjorklund, M., and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Conditional Requests", RFC 7232, June 2014.

   [RFC7235] K. Watsen, "YANG Patch
              Media Type", draft-ietf-netconf-yang-patch-06 (work in
              progress), October 2015.

   [rest-dissertation]
              Fielding, R. R., "Architectural Styles and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Authentication", RFC 7235, June 2014.

   [RFC7320]  Nottingham, M., "URI the Design of
              Network-based Software Architectures", 2000.

Appendix A.  Change Log

    -- RFC Ed.: remove this section before publication.

   The RESTCONF issue tracker can be found here: https://github.com/
   netconf-wg/restconf/issues

A.1.  v09 - v10

   o  address review comments: github issue #36

   o  removed intro text about no knowledge of NETCONF needed

   o  clarified candidate and Ownership", BCP 190, confirmed-commit behavior in sec. 1.3
   o  clarified that a RESTCONF server MUST support TLS

   o  clarified choice of 403 or 404 error

   o  fixed forward references to URI template (w/reference at first
      use)

   o  added reference to HTML5

   o  made error terminology more consistent

   o  clarified that only 1 list or leaf-list instance can be returned
      in an XML response message-body

   o  clarified that more than 1 instance must not be created by a POST
      method

   o  clarified that PUT cannot be used to change a leaf-list value or
      any list key values

   o  clarified that PATCH cannot be used to change a leaf-list value or
      any list key values

   o  clarified that DELETE should not be used to delete more than one
      instance of a leaf-list or list

   o  update JSON RFC
              7320, July 2014.

   [RFC7589]  Badra, M., Luchuk, A., and J. Schoenwaelder, "Using reference

   o  specified that leaf-list instances are data resources

   o  specified how a leaf-list instance identifier is constructed

   o  fixed get-schema example

   o  clarified that if no Accept header the
              NETCONF Protocol over Transport Layer Security (TLS) with
              Mutual X.509 Authentication", RFC 7589, DOI 10.17487/
              RFC7589, June 2015,
              <http://www.rfc-editor.org/info/rfc7589>.

   [W3C.CR-eventsource-20121211]
              Hickson, I., "Server-Sent Events", World Wide Web
              Consortium CR CR-eventsource-20121211, December 2012,
              <http://www.w3.org/TR/2012/CR-eventsource-20121211>.

   [W3C.REC-xml-20081126]
              Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C.,
              and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth
              Edition)", World Wide Web Consortium Recommendation REC-
              xml-20081126, November 2008,
              <http://www.w3.org/TR/2008/REC-xml-20081126>.

   [XPath]    Clark, J. server SHOULD return the
      type specified in RESTCONF, but MAY return any media-type,
      according to HTTP rules

   o  clarified that server SHOULD maintain timestamp and S. DeRose, "XML Path Language (XPath)
              Version 1.0", World Wide Web Consortium Recommendation
              REC-xpath-19991116, November 1999,
              <http://www.w3.org/TR/1999/REC-xpath-19991116>.

14.2.  Informative References

   [I-D.ietf-netconf-yang-patch]
              Bierman, A., Bjorklund, M., etag for data
      resources

   o  clarified default for content query parameter

   o  moved terminology section earlier in doc to avoid forward usage

   o  clarified intro text wrt/ interactions with NETCONF and K. Watsen, "YANG Patch
              Media Type", draft-ietf-netconf-yang-patch-06 (work access to
      specific datastores

   o  clarified server implementation requirements for YANG defaults

   o  clarified that Errors is not a resource, just a media type

   o  clarified that HTTP without TLS MUST NOT be used

   o  add RESTCONF Extensibility section to make it clear how RESTCONF
      will be extended in
              progress), October 2015.

   [rest-dissertation]
              Fielding, R., "Architectural Styles and the Design future

   o  add text warning that NACM does not work with HTTP caching

   o  remove sec. 5.2 Message Headers

   o  remove 202 Accepted from list of
              Network-based Software Architectures", 2000.

Appendix A.  Change Log used status-lines -- RFC Ed.: remove this section before publication.

   The RESTCONF issue tracker can be found here: https://github.com/
   netconf-wg/restconf/issues

A.1. not allowed

   o  made implementation of OPTIONS MUST instead of SHOULD

   o  clarified that successful PUT for altering data returns 204

   o  fixed "point" parameter example

   o  added example of alternate value for root resource discovery

   o  added YANG action examples

   o  fixed some JSON examples

   o  changed default value for content query parameter to "all"

   o  changed empty container JSON encoding from "[null]" to "{}"

   o  added mandatory /restconf/yang-library-version leaf to advertise
      revision-date of the YANG library implemented by the server

   o  clarified URI encoding rules for leaf-list

   o  clarified sec. 2.2 wrt/ certificates and TLS

   o  added update procedure for entity tag and timestamp

A.2.  v08 - v09

   o  fix introduction text regarding implementation requirements for
      the ietf-yang-library

   o  clarified HTTP authentication requirements

   o  fix host-meta example
   o  changed list key encoding to clarify that quoted strings are not
      allowed.  Percent-encoded values are used if quotes would be
      required.  A missing key is treated as a zero-length string

   o  Fixed example of percent-encoded string to match YANG model

   o  Changed streams examples to align with naming already used

A.2.

A.3.  v07 - v08

   o  add support for YANG 1.1 action statement

   o  changed mandatory encoding from XML to XML or JSON

   o  fix syntax in fields parameter definition

   o  add meta-data encoding examples for XML and JSON

   o  remove RFC 2396 references and update with 3986

   o  change encoding of a key so quoted string are not used, since they
      are already percent-encoded.  A zero-length string is not encoded
      (/list=foo,,baz)

   o  Add example of percent-encoded key value

A.3.

A.4.  v06 - v07

   o  fixed all issues identified in email from Jernej Tuljak in netconf
      email 2015-06-22

   o  fixed error example bug where error-urlpath was still used.
      Changed to error-path.

   o  added mention of YANG Patch and informative reference

   o  added support for YANG 1.1, specifically support for anydata and
      actions

   o  removed the special field value "*", since it is no longer needed

A.4.

A.5.  v05 - v06

   o  fixed RESTCONF issue #23 (ietf-restconf-monitoring bug)

A.5.

A.6.  v04 - v05

   o  changed term 'notification event' to 'event notification'
   o  removed intro text about framework and meta-model

   o  removed early mention of API resources

   o  removed term unified datastore and cleaned up text about NETCONF
      datastores

   o  removed text about not immediate persistence of edits

   o  removed RESTCONF-specific data-resource-identifier typedef and its
      usage

   o  clarified encoding of key leafs

   o  changed several examples from JSON to XML encoding

   o  made 'insert' and 'point' query parameters mandatory to implement

   o  removed ":insert" capability URI

   o  renamed stream/encoding to stream/access

   o  renamed stream/encoding/type to stream/access/encoding

   o  renamed stream/encoding/events to stream/access/location

   o  changed XPath from informative to normative reference

   o  changed rest-dissertation from normative to informative reference

   o  changed example-jukebox playlist 'id' from a data-resource-
      identifier to a leafref pointing at the song name

A.6.

A.7.  v03 - v04

   o  renamed 'select' to 'fields' (#1)

   o  moved collection resource and page capability to draft-ietf-
      netconf-restconf-collection-00 (#3)

   o  added mandatory "defaults" protocol capability URI (#4)

   o  added optional "with-defaults" query parameter URI (#4)

   o  clarified authentication procedure (#9)

   o  moved ietf-yang-library module to draft-ietf-netconf-yang-
      library-00 (#13)

   o  clarified that JSON encoding of module name in a URI MUST follow
      the netmod-yang-json encoding rules (#14)

   o  added restconf-media-type extension (#15)

   o  remove "content" query parameter URI and made this parameter
      mandatory (#16)

   o  clarified datastore usage

   o  changed lock-denied error example

   o  added with-defaults query parameter example

   o  added term "RESTCONF Capability"

   o  changed NETCONF Capability URI registry usage to new RESTCONF
      Capability URI Registry usage

A.7.

A.8.  v02 - v03

   o  added collection resource

   o  added "page" query parameter capability

   o  added "limit" and "offset" query parameters, which are available
      if the "page" capability is supported

   o  added "stream list" term

   o  fixed bugs in some examples

   o  added "encoding" list within the "stream" list to allow different
      <events> URLs for XML and JSON encoding.

   o  made XML MUST implement and JSON MAY implement for servers

   o  re-add JSON notification examples (previously removed)

   o  updated JSON references

A.8.

A.9.  v01 - v02

   o  moved query parameter definitions from the YANG module back to the
      plain text sections

   o  made all query parameters optional to implement
   o  defined query parameter capability URI

   o  moved 'streams' to new YANG module (ietf-restconf-monitoring)

   o  added 'capabilities' container to new YANG module (ietf-restconf-
      monitoring)

   o  moved 'modules' container to new YANG module (ietf-yang-library)

   o  added new leaf 'module-set-id' (ietf-yang-library)

   o  added new leaf 'conformance' (ietf-yang-library)

   o  changed 'schema' leaf to type inet:uri that returns the location
      of the YANG schema (instead of returning the schema directly)

   o  changed 'events' leaf to type inet:uri that returns the location
      of the event stream resource (instead of returning events
      directly)

   o  changed examples for yang.api resource since the monitoring
      information is no longer in this resource

   o  closed issue #1 'select parameter' since no objections to the
      proposed syntax

   o  closed "encoding of list keys" issue since no objection to new
      encoding of list keys in a target resource URI.

   o  moved open issues list to the issue tracker on github

A.9.

A.10.  v00 - v01

   o  fixed content=nonconfig example (non-config was incorrect)

   o  closed open issue 'message-id'.  There is no need for a message-id
      field, and RFC 2392 does not apply.

   o  closed open issue 'server support verification'.  The headers used
      by RESTCONF are widely supported.

   o  removed encoding rules from section on RESTCONF Meta-Data.  This
      is now defined in "I-D.lhotka-netmod-yang-json".

   o  added media type application/yang.errors to map to errors YANG
      grouping.  Updated error examples to use new media type.

   o  closed open issue 'additional datastores'.  Support may be added
      in the future to identify new datastores.

   o  closed open issue 'PATCH media type discovery'.  The section on
      PATCH has an added sentence on the Accept-Patch header.

   o  closed open issue 'YANG to resource mapping'.  Current mapping of
      all data nodes to resources will be used in order to allow
      mandatory DELETE support.  The PATCH operation is optional, as
      well as the YANG Patch media type.

   o  closed open issue '_self links for HATEOAS support'.  It was
      decided that they are redundant because they can be derived from
      the YANG module for the specific data.

   o  added explanatory text for the 'select' parameter.

   o  added RESTCONF Path Resolution section for discovering the root of
      the RESTCONF API using the /.well-known/host-meta.

   o  added an "error" media type to for structured error messages

   o  added Secure Transport section requiring TLS

   o  added Security Considerations section

   o  removed all references to "REST-like"

A.10.

A.11.  bierman:restconf-04 to ietf:restconf-00

   o  updated open issues section

Appendix B.  Open Issues

    -- RFC Ed.: remove this section before publication.

   The RESTCONF issues are tracked on github.com:

   https://github.com/netconf-wg/restconf/issues [1]

Appendix C.  Example YANG Module

   The example YANG module used in this document represents a simple
   media jukebox interface.

   YANG Tree Diagram for "example-jukebox" Module
   +--rw jukebox!
      +--rw library
      |  +--rw artist* [name]
      |  |  +--rw name     string
      |  |  +--rw album* [name]
      |  |     +--rw name     string
      |  |     +--rw genre?   identityref
      |  |     +--rw year?    uint16
      |  |     +--rw admin
      |  |     |  +--rw label?              string
      |  |     |  +--rw catalogue-number?   string
      |  |     +--rw song* [name]
      |  |        +--rw name        string
      |  |        +--rw location    string
      |  |        +--rw format?     string
      |  |        +--rw length?     uint32
      |  +--ro artist-count?   uint32
      |  +--ro album-count?    uint32
      |  +--ro song-count?     uint32
      +--rw playlist* [name]
      |  +--rw name           string
      |  +--rw description?   string
      |  +--rw song* [index]
      |     +--rw index    uint32
      |     +--rw id       leafref
      +--rw player
         +--rw gap?   decimal64

   rpcs:

   +---x play
      +--ro input
         +--ro playlist       string
         +--ro song-number    uint32

C.1.  example-jukebox YANG Module

   module example-jukebox {

      namespace "http://example.com/ns/example-jukebox";
      prefix "jbox";

      organization "Example, Inc.";
      contact "support at example.com";
      description "Example Jukebox Data Model Module";
      revision "2015-04-04" {
        description "Initial version.";
        reference "example.com document 1-4673";

      }

      identity genre {
        description "Base for all genre types";
      }

      // abbreviated list of genre classifications
      identity alternative {
        base genre;
        description "Alternative music";
      }
      identity blues {
        base genre;
        description "Blues music";
      }
      identity country {
        base genre;
        description "Country music";
      }
      identity jazz {
        base genre;
        description "Jazz music";
      }
      identity pop {
        base genre;
        description "Pop music";
      }
      identity rock {
        base genre;
        description "Rock music";
      }

      container jukebox {
        presence
          "An empty container indicates that the jukebox
           service is available";

        description
          "Represents a jukebox resource, with a library, playlists,
           and a play operation.";

        container library {

          description "Represents the jukebox library resource.";

          list artist {
            key name;
            description
              "Represents one artist resource within the
               jukebox library resource.";

            leaf name {
              type string {
                length "1 .. max";
              }
              description "The name of the artist.";
            }

            list album {
              key name;

              description
                "Represents one album resource within one
                 artist resource, within the jukebox library.";

              leaf name {
                type string {
                  length "1 .. max";
                }
                description "The name of the album.";
              }

              leaf genre {
                type identityref { base genre; }
                description
                  "The genre identifying the type of music on
                   the album.";
              }

              leaf year {
                type uint16 {
                  range "1900 .. max";
                }
                description "The year the album was released";
              }

              container admin {
                description
                  "Administrative information for the album.";

                leaf label {
                  type string;
                  description "The label that released the album.";
                }
                leaf catalogue-number {
                  type string;
                  description "The album's catalogue number.";
                }
              }

              list song {
                key name;

                description
                  "Represents one song resource within one
                   album resource, within the jukebox library.";

                leaf name {
                  type string {
                     length "1 .. max";
                  }
                  description "The name of the song";
                }
                leaf location {
                  type string;
                  mandatory true;
                  description
                   "The file location string of the
                    media file for the song";
                }
                leaf format {
                  type string;
                  description
                    "An identifier string for the media type
                     for the file associated with the
                     'location' leaf for this entry.";
                }
                leaf length {
                  type uint32;
                  units "seconds";
                  description
                    "The duration of this song in seconds.";
                }
              }   // end list 'song'
            }   // end list 'album'
          }  // end list 'artist'

          leaf artist-count {
             type uint32;
             units "songs";
             config false;
             description "Number of artists in the library";
          }
          leaf album-count {
             type uint32;
             units "albums";
             config false;
             description "Number of albums in the library";
          }
          leaf song-count {
             type uint32;
             units "songs";
             config false;
             description "Number of songs in the library";
          }
        }  // end library

        list playlist {
          key name;

          description
            "Example configuration data resource";

          leaf name {
            type string;
            description
              "The name of the playlist.";
          }
          leaf description {
            type string;
            description
              "A comment describing the playlist.";
          }
          list song {
            key index;
            ordered-by user;

            description
              "Example nested configuration data resource";

            leaf index {    // not really needed
              type uint32;
              description
                "An arbitrary integer index for this playlist song.";
            }
            leaf id {
              type leafref {
                path "/jbox:jukebox/jbox:library/jbox:artist/" +
                     "jbox:album/jbox:song/jbox:name";
              }
              mandatory true;
              description
                "Song identifier. Must identify an instance of
                 /jukebox/library/artist/album/song/name.";
            }
          }
        }

        container player {
          description
            "Represents the jukebox player resource.";

          leaf gap {
            type decimal64 {
              fraction-digits 1;
              range "0.0 .. 2.0";
            }
            units "tenths of seconds";
            description "Time gap between each song";
          }
        }
      }

      rpc play {
        description "Control function for the jukebox player";
        input {
          leaf playlist {
            type string;
            mandatory true;
            description "playlist name";
          }
          leaf song-number {
            type uint32;
            mandatory true;
            description "Song number in playlist to play";
          }
        }
      }
   }

Appendix D.  RESTCONF Message Examples

   The examples within this document use the normative YANG module
   defined in Section 8 and the non-normative example YANG module
   defined in Appendix C.1.

   This section shows some typical RESTCONF message exchanges.

D.1.  Resource Retrieval Examples

D.1.1.  Retrieve the Top-level API Resource

   The client may start by retrieving the top-level API resource, using
   the entry point URI "{+restconf}".

   GET /restconf   HTTP/1.1
   Host: example.com
   Accept: application/yang.api+json

   The server might respond as follows:

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:01:00 GMT
      Server: example-server
      Content-Type: application/yang.api+json

      {
        "ietf-restconf:restconf": {
          "data" : [ null ], {},
          "operations" : [ null ] {}
        }
      }

   To request that the response content to be encoded in XML, the
   "Accept" header can be used, as in this example request:

   GET /restconf HTTP/1.1
   Host: example.com
   Accept: application/yang.api+xml

   The server will return the same response either way, which might be
   as follows :

   HTTP/1.1 200 OK
   Date: Mon, 23 Apr 2012 17:01:00 GMT
   Server: example-server
   Cache-Control: no-cache
   Pragma: no-cache
   Content-Type: application/yang.api+xml

   <restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
     <data/>
     <operations/>
     <yang-library-version>2016-02-01</yang-library-version>
   </restconf>

D.1.2.  Retrieve The Server Module Information

   In this example the client is retrieving the modules information from
   the server in JSON format:

   GET /restconf/data/ietf-yang-library:modules HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond as follows. follows (some strings wrapped for display
   purposes):

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:01:00 GMT
      Server: example-server
      Cache-Control: no-cache
      Pragma: no-cache
      Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT
      Content-Type: application/yang.data+json

      {
        "ietf-yang-library:modules": {
          "module": [
            {
              "name" : "foo",
              "revision" : "2012-01-02",
              "schema" : "https://example.com/modules/foo/2012-01-02",
              "namespace" : "http://example.com/ns/foo",
              "feature" : [ "feature1", "feature2" ],
              "conformance"
              "conformance-type" : "implement"
            },
            {
              "name" : "ietf-yang-library",
              "revision" : "2016-02-01",
              "schema" : "https://example.com/modules/ietf-yang-
                library/2016-02-01",
              "namespace" :
                "urn:ietf:params:xml:ns:yang:ietf-yang-library",
              "conformance-type" : "implement"
            },
            {
              "name" : "foo-types",
              "revision" : "2012-01-05",
              "schema" :
                "https://example.com/modules/foo-types/2012-01-05",
              "schema" : [null],
              "namespace" : "http://example.com/ns/foo-types",
              "conformance"
              "conformance-type" : "import"
            },
            {
              "name" : "bar",
              "revision" : "2012-11-05",
              "schema" : "https://example.com/modules/bar/2012-11-05",
              "namespace" : "http://example.com/ns/bar",
              "feature" : [ "bar-ext" ],
              "conformance"
              "conformance-type" : "implement",
              "submodule" : [
                {
                  "name" : "bar-submod1",
                  "revision" : "2012-11-05",
                  "schema" :
                   "https://example.com/modules/bar-submod1/2012-11-05"
                },
                {
                  "name" : "bar-submod2",
                  "revision" : "2012-11-05",
                  "schema" :
                   "https://example.com/modules/bar-submod2/2012-11-05"
                }
              ]
            }
          ]
        }
      }

D.1.3.  Retrieve The Server Capability Information

   In this example the client is retrieving the capability information
   from the server in JSON XML format, and the server supports all the
   RESTCONF query parameters, plus one vendor parameter:

   GET /restconf/data/ietf-restconf-monitoring:restconf-state/
       capabilities  HTTP/1.1
   Host: example.com
   Accept: application/yang.data+xml

   The server might respond as follows.  The extra whitespace in
   'capability' elements for display purposes only.

   HTTP/1.1 200 OK
   Date: Mon, 23 Apr 2012 17:02:00 GMT
   Server: example-server
   Cache-Control: no-cache
   Pragma: no-cache
   Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT
   Content-Type: application/yang.data+xml
   <capabilities xmlns="">
    <capability>
     urn:ietf:params:restconf:capability:depth:1.0
    </capability>
    <capability>
     urn:ietf:params:restconf:capability:fields:1.0
    </capability>
    <capability>
     urn:ietf:params:restconf:capability:filter:1.0
    </capability>
    <capability>
     urn:ietf:params:restconf:capability:start-time:1.0
    </capability>
    <capability>
     urn:ietf:params:restconf:capability:stop-time:1.0
    </capability>
    <capability>
     http://example.com/capabilities/myparam
    </capability>
   </capabilities>

D.2.  Edit Resource Examples

D.2.1.  Create New Data Resources

   To create a new "artist" resource within the "library" resource, the
   client might send the following request.

      POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1
      Host: example.com
      Content-Type: application/yang.data+json

      {
        "example-jukebox:artist" : {
          "name" : "Foo Fighters"
        }
      }

   If the resource is created, the server might respond as follows.
   Note that the "Location" header line is wrapped for display purposes
   only:

   HTTP/1.1 201 Created
   Date: Mon, 23 Apr 2012 17:02:00 GMT
   Server: example-server
   Location: https://example.com/restconf/data/
       example-jukebox:jukebox/library/artist=Foo%20Fighters
   Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT
   ETag: b3830f23a4c

   To create a new "album" resource for this artist within the "jukebox"
   resource, the client might send the following request.  Note that the
   request URI header line is wrapped for display purposes only:

   POST /restconf/data/example-jukebox:jukebox/
       library/artist=Foo%20Fighters  HTTP/1.1
   Host: example.com
   Content-Type: application/yang.data+json

      {
        "example-jukebox:album" : {
          "name" : "Wasting Light",
          "genre" : "example-jukebox:alternative",
          "year" : 2012    # note this is the wrong date
        }
      } application/yang.data+xml

   <album xmlns="http://example.com/ns/example-jukebox">
     <name>Wasting Light</name>
     <year>2011</year>
   </album>

   If the resource is created, the server might respond as follows.
   Note that the "Location" header line is wrapped for display purposes
   only:

   HTTP/1.1 201 Created
   Date: Mon, 23 Apr 2012 17:03:00 GMT
   Server: example-server
   Location: https://example.com/restconf/data/
       example-jukebox:jukebox/library/artist=Foo%20Fighters/
       album=Wasting%20Light
   Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT
   ETag: b8389233a4c

D.2.2.  Detect Resource Entity Tag Change

   In this example, the server just supports the mandatory datastore
   last-changed timestamp.  The client has previously retrieved the
   "Last-Modified" header and has some value cached to provide in the
   following request to patch an "album" list entry with key value
   "Wasting Light".  Only the "year" "genre" field is being updated.

      PATCH /restconf/data/example-jukebox:jukebox/
          library/artist=Foo%20Fighters/album=Wasting%20Light/year
          library/artist=Foo%20Fighters/album=Wasting%20Light/genre
          HTTP/1.1
      Host: example.com
      If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT
      Content-Type: application/yang.data+json

      { "example-jukebox:year" "example-jukebox:genre" : "2011" "example-jukebox:alternative" }

   In this example the datastore resource has changed since the time
   specified in the "If-Unmodified-Since" header.  The server might
   respond:

   HTTP/1.1 412 Precondition Failed
   Date: Mon, 23 Apr 2012 19:01:00 GMT
   Server: example-server
   Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT
   ETag: b34aed893a4c

D.2.3.  Edit a Datastore Resource

   In this example, the client modifies two different data nodes by
   sending a PATCH to the datastore resource:

   PATCH /restconf/data HTTP/1.1
   Host: example.com
   Content-Type: application/yang.datastore+xml

   <data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
     <jukebox xmlns="http://example.com/ns/example-jukebox">
       <library>
         <artist>
           <name>Foo Fighters</name>
           <album>
             <name>Wasting Light</name>
             <year>2011</year>
           </album>
         </artist>
         <artist>
           <name>Nick Cave</name>
           <album>
             <name>Tender Prey</name>
             <year>1988</year>
           </album>
         </artist>
       </library>
     </jukebox>
   </data>

D.3.  Query Parameter Examples

D.3.1.  "content" Parameter
   The "content" parameter is used to select the type of data child
   resources (configuration and/or not configuration) that are returned
   by the server for a GET method request.

   In this example, a simple YANG list that has configuration and non-
   configuration child resources.

   container events
     list event {
       key name;
       leaf name { type string; }
       leaf description { type string; }
       leaf event-count {
         type uint32;
         config false;
       }
     }
   }

   Example 1: content=all

   To retrieve all the child resources, the "content" parameter is set
   to "all".  The client might send:

   GET /restconf/data/example-events:events?content=all
       HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond:

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:11:30 GMT
      Server: example-server
      Cache-Control: no-cache
      Pragma: no-cache
      Content-Type: application/yang.data+json

      {
        "example-events:events" : {
          "event" : [
            {
              "name" : "interface-up",
              "description" : "Interface up notification count",
              "event-count" : 42
            },
            {
              "name" : "interface-down",
              "description" : "Interface down notification count",
              "event-count" : 4
            }
          ]
        }
      }

   Example 2: content=config

   To retrieve only the configuration child resources, the "content"
   parameter is set to "config" or omitted since this is the default
   value.  Note that the "ETag" and "Last-Modified" headers are only
   returned if the content parameter value is "config".

   GET /restconf/data/example-events:events?content=config
       HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond:

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:11:30 GMT
      Server: example-server
      Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
      ETag: eeeada438af
      Cache-Control: no-cache
      Pragma: no-cache
      Content-Type: application/yang.data+json

      {
        "example-events:events" : {
          "event" : [
            {
              "name" : "interface-up",
              "description" : "Interface up notification count"
            },
            {
              "name" : "interface-down",
              "description" : "Interface down notification count"
            }
          ]
        }
      }

   Example 3: content=nonconfig
   To retrieve only the non-configuration child resources, the "content"
   parameter is set to "nonconfig".  Note that configuration ancestors
   (if any) and list key leafs (if any) are also returned.  The client
   might send:

   GET /restconf/data/example-events:events?content=nonconfig
       HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond:

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:11:30 GMT
      Server: example-server
      Cache-Control: no-cache
      Pragma: no-cache
      Content-Type: application/yang.data+json

      {
        "example-events:events" : {
          "event" : [
            {
              "name" : "interface-up",
              "event-count" : 42
            },
            {
              "name" : "interface-down",
              "event-count" : 4
            }
          ]
        }
      }

D.3.2.  "depth" Parameter

   The "depth" parameter is used to limit the number of levels of child
   resources that are returned by the server for a GET method request.

   The depth parameter starts counting levels at the level of the target
   resource that is specified, so that a depth level of "1" includes
   just the target resource level itself.  A depth level of "2" includes
   the target resource level and its child nodes.

   This example shows how different values of the "depth" parameter
   would affect the reply content for retrieval of the top-level
   "jukebox" data resource.

   Example 1: depth=unbounded

   To retrieve all the child resources, the "depth" parameter is not
   present or set to the default value "unbounded".  Note that some
   strings are wrapped for display purposes only.

   GET /restconf/data/example-jukebox:jukebox?depth=unbounded
       HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond:

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:11:30 GMT
      Server: example-server
      Cache-Control: no-cache
      Pragma: no-cache
      Content-Type: application/yang.data+json

      {
        "example-jukebox:jukebox" : {
          "library" : {
            "artist" : [
              {
                "name" : "Foo Fighters",
                "album" : [
                  {
                    "name" : "Wasting Light",
                    "genre" : "example-jukebox:alternative",
                    "year" : 2011,
                    "song" : [
                      {
                        "name" : "Wasting Light",
                        "location" :
                          "/media/foo/a7/wasting-light.mp3",
                        "format" : "MP3",
                        "length" " 286
                      },
                      {
                        "name" : "Rope",
                        "location" : "/media/foo/a7/rope.mp3",
                        "format" : "MP3",
                        "length" " 259
                      }
                    ]
                  }
                ]

              }
            ]
          },
          "playlist" : [
            {
              "name" : "Foo-One",
              "description" : "example playlist 1",
              "song" : [
                {
                  "index" : 1,
                  "id" : "https://example.com/restconf/data/
                        example-jukebox:jukebox/library/artist=
                        Foo%20Fighters/album=Wasting%20Light/
                        song=Rope"
                },
                {
                  "index" : 2,
                  "id" : "https://example.com/restconf/data/
                        example-jukebox:jukebox/library/artist=
                        Foo%20Fighters/album=Wasting%20Light/song=
                        Bridge%20Burning"
                }
              ]
            }
          ],
          "player" : {
            "gap" : 0.5
          }
        }
      }

   Example 2: depth=1

   To determine if 1 or more resource instances exist for a given target
   resource, the value "1" is used.

   GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond:

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:11:30 GMT
      Server: example-server
      Cache-Control: no-cache
      Pragma: no-cache
      Content-Type: application/yang.data+json
      {
        "example-jukebox:jukebox" : [null] {}
      }

   Example 3: depth=3

   To limit the depth level to the target resource plus 2 child resource
   layers the value "3" is used.

   GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond:

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:11:30 GMT
      Server: example-server
      Cache-Control: no-cache
      Pragma: no-cache
      Content-Type: application/yang.data+json

      {
        "example-jukebox:jukebox" : {
          "library" : {
            "artist" : [ null ] {}
          },
          "playlist" : [
            {
              "name" : "Foo-One",
              "description" : "example playlist 1",
              "song" : [ null ] {}
            }
          ],
          "player" : {
            "gap" : 0.5
          }
        }
      }

D.3.3.  "fields" Parameter

   In this example the client is retrieving the API resource, but
   retrieving only the "name" and "revision" nodes from each module, in
   JSON format:

   GET /restconf/data?fields=ietf-yang-library:modules/
       module(name;revision) HTTP/1.1

   Host: example.com
   Accept: application/yang.data+json

   The server might respond as follows.

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:01:00 GMT
      Server: example-server
      Content-Type: application/yang.data+json

      {
        "ietf-yang-library:modules": {
          "module": [
            {
              "name" : "example-jukebox",
              "revision" : "2015-06-04"
            },
            {
              "name" : "ietf-inet-types",
              "revision" : "2013-07-15"
            },
            {
              "name" : "ietf-restconf-monitoring",
              "revision" : "2015-06-19"
            },
            {
              "name" : "ietf-yang-library",
              "revision" : "2015-07-03" "2016-02-01"
            },
            {
              "name" : "ietf-yang-types",
              "revision" : "2013-07-15"
            }

          ]
        }
      }

D.3.4.  "insert" Parameter

   In this example, a new first entry in the "Foo-One" playlist is being
   created.

   Request from client:

      POST /restconf/data/example-jukebox:jukebox/
          playlist=Foo-One?insert=first HTTP/1.1
      Host: example.com
      Content-Type: application/yang.data+json

      {
        "example-jukebox:song" : {
           "index" : 1,
           "id" : "/example-jukebox:jukebox/library/
               artist=Foo%20Fighters/album=Wasting%20Light/song=Rope"
         }
      }

   Response from server:

   HTTP/1.1 201 Created
   Date: Mon, 23 Apr 2012 13:01:20 GMT
   Server: example-server
   Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
   Location: https://example.com/restconf/data/
       example-jukebox:jukebox/playlist=Foo-One/song=1
   ETag: eeeada438af

D.3.5.  "point" Parameter

   In this example, the client is inserting a new "song" resource within
   an "album" resource after another song.  The request URI is split for
   display purposes only.

   Request from client:

      POST /restconf/data/example-jukebox:jukebox/
          library/artist=Foo%20Fighters/album=Wasting%20Light?
          insert=after&point=%2Fexample-jukebox%3Ajukebox%2F
          library%2Fartist%2FFoo%20Fighters%2Falbum%2F
          Wasting%20Light%2Fsong%2FBridge%20Burning
          library%2Fartist%3DFoo%20Fighters%2Falbum%3D
          Wasting%20Light%2Fsong%3DBridge%20Burning   HTTP/1.1
      Host: example.com
      Content-Type: application/yang.data+json

      {
        "example-jukebox:song" : {
          "name" : "Rope",
          "location" : "/media/foo/a7/rope.mp3",
          "format" : "MP3",
          "length" : 259
        }
      }

   Response from server:

   HTTP/1.1 204 No Content
   Date: Mon, 23 Apr 2012 13:01:20 GMT
   Server: example-server
   Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
   ETag: abcada438af

D.3.6.  "filter" Parameter

   The following URIs show some examples of notification filter
   specifications (lines wrapped for display purposes only):

      // filter = /event/event-class='fault'
      GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault'

      // filter = /event/severity<=4
      GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4

      // filter = /linkUp|/linkDown
      GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown

      // filter = /*/reporting-entity/card!='Ethernet0'
      GET /streams/NETCONF?
         filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0'

      // filter = /*/email-addr[contains(.,'company.com')]
      GET /streams/critical-syslog?
         filter=%2F*%2Femail-addr[contains(.%2C'company.com')]

      // Note: the module name is used as prefix.
      // filter = (/example-mod:event1/name='joe' and
      //           /example-mod:event1/status='online')
      GET /streams/NETCONF?
        filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and
                %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online')

      // To get notifications from just two modules (e.g., m1 + m2)
      // filter=(/m1:* or /m2:*)
      GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*)

D.3.7.  "start-time" Parameter

   // start-time = 2014-10-25T10:02:00Z
   GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z

D.3.8.  "stop-time" Parameter

   // stop-time = 2014-10-25T12:31:00Z
   GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z

D.3.9.  "with-defaults" Parameter

   The following YANG module is assumed for this example.

     module example-interface {
       prefix "exif";
       namespace "urn:example.com:params:xml:ns:yang:example-interface";

       container interfaces {
         list interface {
           key name;
           leaf name { type string; }
           leaf mtu { type uint32; }
           leaf status {
             config false;
             type enumeration {
               enum up;
               enum down;
               enum testing;
             }
           }
         }
       }
     }

   Assume the same data model as defined in Appendix A.1 of [RFC6243].
   Assume the same data set as defined in Appendix A.2 of [RFC6243].  If
   the server defaults-uri basic-mode is "trim", the the following
   request for interface "eth1" might be as follows:

   Without query parameter:

   GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond as follows.

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:01:00 GMT
      Server: example-server
      Content-Type: application/yang.data+json

      {
        "example:interface": [
          {
            "name" : "eth1",
            "status" : "up"

          }
        ]
      }

   Note that the "mtu" leaf is missing because it is set to the default
   "1500", and the server defaults handling basic-mode is "trim".

   With query parameter:

   GET /restconf/data/example:interfaces/interface=eth1
       ?with-defaults=report-all HTTP/1.1
   Host: example.com
   Accept: application/yang.data+json

   The server might respond as follows.

      HTTP/1.1 200 OK
      Date: Mon, 23 Apr 2012 17:01:00 GMT
      Server: example-server
      Content-Type: application/yang.data+json

      {
        "example:interface": [
          {
            "name" : "eth1",
            "mtu" : 1500,
            "status" : "up"
          }
        ]
      }

   Note that the server returns the "mtu" leaf because the "report-all"
   mode was requested with the "with-defaults" query parameter.

Authors' Addresses

   Andy Bierman
   YumaWorks

   Email: andy@yumaworks.com

   Martin Bjorklund
   Tail-f Systems

   Email: mbj@tail-f.com
   Kent Watsen
   Juniper Networks

   Email: kwatsen@juniper.net