4.  RESTCONF Methods

   The RESTCONF protocol uses HTTP methods to identify the CRUD
   operations requested for a particular resource.

   The following table shows how the RESTCONF operations relate to
   NETCONF protocol operations.

   +----------+-------------------------------------------------------+
   | RESTCONF | NETCONF                                               |
   +----------+-------------------------------------------------------+
   | OPTIONS  | none                                                  |
   |          |                                                       |
   | HEAD     | <get-config>, <get>                                   |
   |          |                                                       |
   | GET      | <get-config>, <get>                                   |
   |          |                                                       |
   | POST     | <edit-config> (nc:operation="create")                 |
   |          |                                                       |
   | POST     | invoke an RPC operation                               |
   |          |                                                       |
   | PUT      | <copy-config> (PUT on datastore)                      |
   |          |                                                       |
   | PUT      | <edit-config> (nc:operation="create/replace")         |
   |          |                                                       |
   | PATCH    | <edit-config> (nc:operation depends on PATCH content) |
   |          |                                                       |
   | DELETE   | <edit-config> (nc:operation="delete")                 |
   +----------+-------------------------------------------------------+

                         CRUD Methods in RESTCONF

   The "remove" edit operation attribute for the NETCONF <edit-config>
   RPC operation 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" edit operation when using a plain patch
   (see Section 4.6.1); other media types may provide more granular
   control.

   Access control mechanisms are used to limit what CRUD operations can
   be used.  In particular, RESTCONF is compatible with the NETCONF
   Access Control Model (NACM) [RFC6536], as there is a specific mapping
   between RESTCONF and NETCONF operations.  The resource path needs to
   be converted internally by the server to the corresponding YANG
   instance identifier.  Using this information, the server can apply
   the NACM access control rules to RESTCONF messages.

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

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

4.1.  OPTIONS

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

   The "Accept-Patch" header field MUST be supported and returned in the
   response to the OPTIONS request, as defined in [RFC5789].

4.2.  HEAD

   The RESTCONF server MUST support the HEAD method.  The HEAD method is
   sent by the client to retrieve just the header fields (which contain
   the metadata for a resource) that would be returned for the
   comparable GET method, without the response message-body.  It is
   supported for all resources that support the GET method.

   The request MUST contain a request URI that contains at least the
   root resource.  The same query parameters supported by the GET method
   are supported by 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 is
   included.

4.3.  GET

   The RESTCONF server MUST support the GET method.  The GET method is
   sent by the client to retrieve data and metadata for a resource.  It
   is supported for all resource types, except operation resources.  The
   request MUST contain a request URI that contains at least the root
   resource.

   The server MUST NOT return any data resources for which the user does
   not have read privileges.  If the user is not authorized to read the
   target resource, an error response containing a "401 Unauthorized"
   status-line SHOULD be returned.  The error-tag value "access-denied"
   is returned in this case.  A server MAY return a "404 Not Found"
   status-line, as described in Section 6.5.4 in [RFC7231].  The
   error-tag value "invalid-value" is returned in this case.

   If the user is authorized to read some but not all of the target
   resource, the unauthorized content is omitted from the response
   message-body, and the authorized content is returned to the 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 multiple elements are sent in a JSON
   message-body, then they MUST be sent as a JSON array.  In this case,
   any timestamp or entity-tag returned in the response MUST be
   associated with the first element returned.

   If a retrieval request for a data resource representing a YANG
   leaf-list or list object identifies more than one instance and XML
   encoding is used in the response, then an error response containing a
   "400 Bad Request" status-line MUST be returned by the server.  The
   error-tag value "invalid-value" is used in this case.  Note that a
   non-configuration list is not required to define any keys.  In this
   case, the retrieval of a single list instance is not possible.

   If a retrieval request for a data resource represents an instance
   that does not exist, then an error response containing a "404 Not
   Found" status-line MUST be returned by the server.  The error-tag
   value "invalid-value" is used in this case.

   If the target resource of a retrieval request is for an operation
   resource, then a "405 Method Not Allowed" status-line MUST be
   returned by the server.  The error-tag value
   "operation-not-supported" is used in this case.

   Note that the way that access control is applied to data resources
   may not be completely compatible with HTTP caching.  The
   "Last-Modified" and "ETag" header fields maintained for a data
   resource are not affected by changes to the access control rules for
   that data resource.  It is possible for the representation of a data
   resource that is visible to a particular client to be changed without
   detection via the "Last-Modified" or "ETag" values.

   Example:

   The client might request the response header fields for an XML
   representation of 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 as follows:

      HTTP/1.1 200 OK
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Content-Type: application/yang-data+xml
      Cache-Control: no-cache
      ETag: "a74eefc993a2b"
      Last-Modified: Thu, 26 Jan 2017 14: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>

   Refer to Appendix B.1 for more resource retrieval examples.

4.4.  POST

   The RESTCONF server MUST support the POST method.  The POST method is
   sent by the client to create a data resource or invoke an operation
   resource.  The server uses the target resource 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 an RPC 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
   POST is treated as a request to create a top-level resource or child
   resource, respectively.  The message-body is expected to contain the
   content of a child resource to create within the parent (target
   resource).  The message-body MUST contain exactly one instance of the
   expected data resource.  The data model for the child tree is the
   subtree, as defined by YANG for the child resource.

   The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query
   parameters MUST be supported by the POST method for datastore and
   data resources.  These parameters are only allowed if the list or
   leaf-list is "ordered-by user".

   If the POST method succeeds, a "201 Created" status-line is returned
   and there is no response message-body.  A "Location" header field
   identifying the child resource that was created MUST be present in
   the response in this case.

   If the data resource already exists, then the POST request MUST fail
   and a "409 Conflict" status-line MUST be returned.  The error-tag
   value "resource-denied" is used in this case.

   If the user is not authorized to create the target resource, an error
   response containing a "403 Forbidden" status-line SHOULD be returned.
   The error-tag value "access-denied" is used in this case.  A server
   MAY return a "404 Not Found" status-line, as described in
   Section 6.5.4 in [RFC7231].  The error-tag value "invalid-value" is
   used in this case.  All other error responses are handled according
   to the procedures defined in Section 7.

   Example:

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

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

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

   If the resource is created, the server might respond as follows:

      HTTP/1.1 201 Created
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Location: https://example.com/restconf/data/\
          example-jukebox:jukebox
      Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
      ETag: "b3a3e673be2"

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

4.4.2.  Invoke Operation Mode

   If the target resource type is an operation resource, then the POST
   method is treated as a request 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" status-line SHOULD be
   returned.  The error-tag value "access-denied" is used in this case.
   A server MAY return a "404 Not Found" status-line, as described in
   Section 6.5.4 in [RFC7231].  All other error responses are handled
   according to the procedures defined in Section 7.

   Example:

   In this example, the client is invoking the "play" operation defined
   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-data+json

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

   The server might respond as follows:

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

4.5.  PUT

   The RESTCONF server MUST support the PUT method.  The PUT method is
   sent by the client to create or replace the target data resource.  A
   request message-body MUST be present, representing the new data
   resource, or the server MUST return a "400 Bad Request" status-line.
   The error-tag value "invalid-value" is used in this case.

   Both the POST and PUT methods can be used to create data resources.
   The difference is that for POST, the client does not provide the
   resource identifier for the resource that will be created.  The
   target resource for the POST method for resource creation is the
   parent of the new resource.  The target resource for the PUT method
   for resource creation is the new resource.

   The PUT method MUST be supported for data and datastore resources.  A
   PUT on the datastore resource is used to replace the entire contents
   of the datastore.  A PUT on a data resource only replaces that data
   resource within the datastore.

   The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query
   parameters MUST be supported by the PUT method for data resources.
   These parameters are only allowed if the list or leaf-list is
   "ordered-by user".

   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.  The error-tag value "access-denied" is used in
   this case.

   A server MAY return a "404 Not Found" status-line, as described in
   Section 6.5.4 in [RFC7231].  The error-tag value "invalid-value" is
   used in this case.  All other error responses are handled according
   to the procedures defined in Section 7.

   If the target resource represents a YANG leaf-list, then the PUT
   method MUST NOT change the value of the leaf-list instance.

   If the target resource represents a YANG list instance, then the key
   leaf values, in message-body representation, MUST be the same as the
   key leaf values in the request URI.  The PUT method MUST NOT be used
   to change the key leaf values for a data resource instance.

   Example:

   An "album" child resource defined in the "example-jukebox" YANG
   module is replaced, or it is created if it does not already exist.

   To replace the "album" resource contents, the client might send the
   following:

      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 resource is updated, the server might respond as follows:

      HTTP/1.1 204 No Content
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Last-Modified: Thu, 26 Jan 2017 20:56:30 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>

   Refer to Appendix B.2.4 for an example using the PUT method to
   replace the contents of the datastore resource.

4.6.  PATCH

   The RESTCONF server MUST support the PATCH method for a plain patch
   and MAY support additional media types.  The media types for the
   PATCH method supported by the server can be discovered by the client
   by sending an OPTIONS request and examining the "Accept-Patch" header
   field in the response (see Section 4.1).

   RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide
   an extensible framework for resource patching mechanisms.  Each patch
   mechanism needs a unique media type.

   This document defines one patch mechanism (Section 4.6.1).  Another
   patch mechanism, the YANG Patch mechanism, is defined in
   [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 request succeeds, a "200 OK" status-line is returned if
   there is a message-body, and "204 No Content" is returned if no
   response message-body is sent.

   If the user is not authorized to alter the target resource, 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.4 in [RFC7231].  The error-tag value "invalid-value" is
   used in this case.  All other error responses are handled according
   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.  The message-body for a plain patch MUST be
   present and MUST be represented by the media type
   "application/yang-data+xml" or "application/yang-data+json".

   Plain patch can be used to create or update, but not delete, a child
   resource within the target resource.  Please see [YANG-Patch] for an
   alternate media type supporting the ability to delete child
   resources.  The YANG Patch media type allows multiple suboperations
   (e.g., "merge", "delete") within a single PATCH method.

   If the target resource represents a YANG leaf-list, then the PATCH
   method MUST NOT change the value of the leaf-list instance.

   If the target resource represents a YANG list instance, then the key
   leaf values, in message-body representation, MUST be the same as the
   key leaf values in the request URI.  The PATCH method MUST NOT be
   used to change the key leaf values for a data resource instance.

   After the plain patch is processed by the server, a response will be
   returned to the client, as specified in Section 4.6.

   Example:

   To replace just the "year" field in the "album" resource (instead of
   replacing the entire resource with the PUT method), the client might
   send a plain patch as follows:

      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 as follows:

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

4.7.  DELETE

   The RESTCONF server MUST support the DELETE method.  The DELETE
   method is used to delete the target resource.  If the DELETE request
   succeeds, a "204 No Content" status-line is returned.

   If the user is not authorized to delete the target resource, then an
   error response containing a "403 Forbidden" status-line SHOULD be
   returned.  The error-tag value "access-denied" is returned in this
   case.  A server MAY return a "404 Not Found" status-line, as
   described in Section 6.5.4 in [RFC7231].  The error-tag value
   "invalid-value" is returned in this case.  All other error responses
   are handled according to the procedures defined in Section 7.

   If the target resource represents a configuration leaf-list or list
   data node, then it MUST represent a single YANG leaf-list or list
   instance.  The server MUST NOT use the DELETE method to delete more
   than one such instance.

   Example:

   To delete the "album" resource with the key "Wasting Light", the
   client might send the following:

      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 as follows:

      HTTP/1.1 204 No Content
      Date: Thu, 26 Jan 2017 20:56: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.  Which specific parameters are allowed
   will depend on the resource type, and sometimes the specific target
   resource used, in the request.

   o  Query parameters can be given in any order.

   o  Each parameter can appear at most once in a request URI.

   o  If more than one instance of a query parameter is present, then a
      "400 Bad Request" status-line MUST be returned by the server.  The
      error-tag value "invalid-value" is returned in this case.

   o  A default value may apply if the parameter is missing.

   o  Query parameter names and values are case sensitive.

   o  A server MUST return an error with a "400 Bad Request" status-line
      if a query parameter is unexpected.  The error-tag value
      "invalid-value" is returned in this case.

   +---------------+---------+-----------------------------------------+
   | Name          | Methods | Description                             |
   +---------------+---------+-----------------------------------------+
   | content       | GET,    | Select config and/or non-config data    |
   |               | HEAD    | resources                               |
   |               |         |                                         |
   | depth         | GET,    | Request limited subtree depth in the    |
   |               | HEAD    | reply content                           |
   |               |         |                                         |
   | fields        | GET,    | Request a subset of the target resource |
   |               | HEAD    | contents                                |
   |               |         |                                         |
   | filter        | GET,    | Boolean notification filter for event   |
   |               | HEAD    | stream resources                        |
   |               |         |                                         |
   | insert        | POST,   | Insertion mode for "ordered-by user"    |
   |               | PUT     | data resources                          |
   |               |         |                                         |
   | point         | POST,   | Insertion point for "ordered-by user"   |
   |               | PUT     | data resources                          |
   |               |         |                                         |
   | start-time    | GET,    | Replay buffer start time for event      |
   |               | HEAD    | stream resources                        |
   |               |         |                                         |
   | stop-time     | GET,    | Replay buffer stop time for event       |
   |               | HEAD    | stream resources                        |
   |               |         |                                         |
   | with-defaults | GET,    | Control the retrieval of default values |
   |               | HEAD    |                                         |
   +---------------+---------+-----------------------------------------+

                         RESTCONF Query Parameters

   Refer to Appendix B.3 for examples of query parameter usage.

   If vendors define additional query parameters, they SHOULD use a
   prefix (such as 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" query parameter controls how descendant nodes of the
   requested data nodes will be processed 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" status-line is returned if used for
   other methods or resource types.

   If this query parameter is not present, the default value is "all".
   This query parameter MUST be supported by the server.

4.8.2.  The "depth" Query Parameter

   The "depth" query parameter is used to limit the depth of subtrees
   returned by the server.  Data nodes with a "depth" value greater than
   the "depth" parameter are not returned in a response for a GET
   method.

   The requested data node has a depth level of "1".  If the "fields"
   parameter (Section 4.8.3) is used to select descendant data nodes,
   then these nodes and all of their ancestor nodes have a "depth" value
   of "1".  (This has the effect of including the nodes specified by the
   fields, even if the "depth" value is less than the actual depth level
   of the specified fields.)  Any other child node has a "depth" value
   that is 1 greater than its parent.

   The value of the "depth" parameter is either an integer between 1 and
   65535 or the string "unbounded".  "unbounded" is the default.

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

   By default, the server will include all sub-resources within a
   retrieved resource that have the same resource type as the requested
   resource.  The exception is the datastore resource.  If this resource
   type is retrieved, then by default the datastore and all child data
   resources are returned.

   If the "depth" query parameter URI is listed in the "capability"
   leaf-list defined in Section 9.3, then the 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 resource to be retrieved in a GET method.
   The client can use this parameter to retrieve a subset of all nodes
   in a resource.

   The server will return a message-body representing the target
   resource, with descendant nodes pruned as specified in the
   "fields-expr" value.  The server does not return a set of separate
   sub-resources.

   A value of the "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.3.1.

   ";" is used to 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 node.  Note that
   there is no path separator character "/" between a "path" field and a
   left parenthesis character "(".

   For example, assume that the target resource is the "album" list.  To
   retrieve only the "label" and "catalogue-number" of the "admin"
   container within an album, use
   "fields=admin(label;catalogue-number)".

   "/" is used in a path to retrieve a child node of a node.  For
   example, to retrieve only the "label" of an album, use
   "fields=admin/label".

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

   If the "fields" query parameter URI is listed in the "capability"
   leaf-list defined in Section 9.3, then the server supports the
   "fields" parameter.

4.8.4.  The "filter" Query Parameter

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

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

   The format of this parameter is an XPath 1.0 expression [XPath] and
   is evaluated in the following context:

   o  The set of namespace declarations is the set of prefix and
      namespace pairs for all supported YANG modules, where the prefix
      is the YANG module name and the namespace is as defined by the
      "namespace" statement in the YANG module.

   o  The function library is the core function library defined in
      XPath 1.0, plus any functions defined by the data model.

   o  The set of variable bindings is empty.

   o  The context node is the root node.

   The "filter" query parameter is used as defined in Section 3.6 of
   [RFC5277].  If the boolean result of the expression is "true" when
   applied to the conceptual "notification" document root, then the
   event notification is delivered to the client.

   If the "filter" query parameter URI is listed in the "capability"
   leaf-list defined in Section 9.3, then the server supports the
   "filter" query parameter.

4.8.5.  The "insert" Query Parameter

   The "insert" query parameter is used to specify how a resource should
   be inserted within an "ordered-by user" list.

   The allowed values are:

   +--------+----------------------------------------------------------+
   | Value  | Description                                              |
   +--------+----------------------------------------------------------+
   | first  | Insert the new data as the new first entry.              |
   |        |                                                          |
   | last   | Insert the new data as the new last entry.               |
   |        |                                                          |
   | before | Insert the new data before the insertion point, as       |
   |        | specified by the value of the "point" parameter.         |
   |        |                                                          |
   | after  | Insert the new data after the insertion point, as        |
   |        | specified by the value of the "point" parameter.         |
   +--------+----------------------------------------------------------+

   The 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 data resource, and
   that data represents a YANG list or leaf-list that is
   "ordered-by user".

   If the values "before" or "after" are used, then a "point" query
   parameter for the "insert" query parameter MUST also be present, or a
   "400 Bad Request" status-line is returned.

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

4.8.6.  The "point" Query Parameter

   The "point" query parameter is used to specify the insertion point
   for a data resource that is being created or moved within an
   "ordered-by user" list or leaf-list.

   The value of the "point" parameter is a string that identifies the
   path to the insertion point object.  The format is the same as a
   target resource URI string.

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

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

   This parameter contains the instance identifier of the resource to be
   used as the insertion point for a POST or PUT method.

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

4.8.7.  The "start-time" Query Parameter

   The "start-time" query parameter is used to trigger the notification
   replay feature defined in [RFC5277] and indicate that the replay
   should start at the time specified.  If the stream does not support
   replay per the "replay-support" attribute returned by the
   "stream" list entry for the stream resource, then the server MUST
   return a "400 Bad Request" status-line.

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

   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.

   If this parameter is not present, then a replay subscription is not
   being requested.  It is not valid to specify start times that are
   later than the current time.  If the value specified is earlier than
   the log can support, the replay will begin with the earliest
   available notification.  A client can obtain a server's current time
   by examining the "Date" header field that the server returns in
   response messages, according to [RFC7231].

   If this query parameter is supported by the server, then the "replay"
   query parameter URI MUST be listed in the "capability" leaf-list
   defined in Section 9.3, and the "stop-time" query parameter MUST also
   be supported by the server.

   If the "replay-support" leaf has the value "true" in the "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" query parameter is used with the replay feature to
   indicate the newest notifications of interest.  This parameter MUST
   be used with, and have a value later than, the "start-time"
   parameter.

   The value of the "stop-time" parameter is of type "date-and-time",
   defined in the "ietf-yang-types" YANG module [RFC6991].

   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.

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

   If this query parameter is supported by the server, then the "replay"
   query parameter URI MUST be listed in the "capability" leaf-list
   defined in Section 9.3, and the "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 that stream.

4.8.9.  The "with-defaults" Query Parameter

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

   If the server supports this capability, then it MUST implement the
   behavior described 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 to the YANG default by the     |
   |                   | client are reported                           |
   |                   |                                               |
   | report-all-tagged | All data nodes are reported, and defaults are |
   |                   | tagged                                        |
   +-------------------+-----------------------------------------------+

   If the "with-defaults" parameter is set to "report-all", then the
   server MUST adhere to the default-reporting behavior defined in
   Section 3.1 of [RFC6243].

   If the "with-defaults" parameter is set to "trim", then the server
   MUST adhere to the default-reporting behavior defined in Section 3.2
   of [RFC6243].

   If the "with-defaults" parameter is set to "explicit", then the
   server MUST adhere to the default-reporting behavior defined in
   Section 3.3 of [RFC6243].

   If the "with-defaults" parameter is set to "report-all-tagged", then
   the server MUST adhere to the default-reporting behavior defined in
   Section 3.4 of [RFC6243].  Metadata is reported by the server as
   specified in Section 5.3.  The XML encoding for the "default"
   attribute sent by the server for default nodes is defined in
   Section 6 of [RFC6243].  The JSON encoding for the "default"
   attribute MUST use the same values, as defined in [RFC6243], but
   encoded according to the rules in [RFC7952].  The module name
   "ietf-netconf-with-defaults" MUST be used for the "default"
   attribute.

   If the "with-defaults" parameter is not present, then the server MUST
   adhere to the default-reporting behavior defined in its "basic-mode"
   parameter for the "defaults" protocol capability URI, defined in
   Section 9.1.2.

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

   Since the server does not report the "also-supported" parameter as
   described in Section 4.3 of [RFC6243], it is possible that some
   values for the "with-defaults" parameter will not be supported.  If
   the server does not support the requested value of the
   "with-defaults" parameter, the server MUST return a response with a
   "400 Bad Request" status-line.  The error-tag value "invalid-value"
   is used in this case.