Tech-invite3GPPspaceIETF RFCsSIP
93929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8040

RESTCONF Protocol

Pages: 137
Proposed Standard
Errata
Part 3 of 6 – Pages 42 to 60
First   Prev   Next

Top   ToC   RFC8040 - Page 42   prevText

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.
Top   ToC   RFC8040 - Page 43
   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.
Top   ToC   RFC8040 - Page 44
   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
Top   ToC   RFC8040 - Page 45
   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.
Top   ToC   RFC8040 - Page 46
   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.
Top   ToC   RFC8040 - Page 47

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
Top   ToC   RFC8040 - Page 48

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.
Top   ToC   RFC8040 - Page 49
   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.
Top   ToC   RFC8040 - Page 50

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.
Top   ToC   RFC8040 - Page 51
   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.
Top   ToC   RFC8040 - Page 52
   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.
Top   ToC   RFC8040 - Page 53
   +---------------+---------+-----------------------------------------+
   | 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.
Top   ToC   RFC8040 - Page 54

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.
Top   ToC   RFC8040 - Page 55
   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.
Top   ToC   RFC8040 - Page 56
   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.
Top   ToC   RFC8040 - Page 57

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".
Top   ToC   RFC8040 - Page 58
   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.
Top   ToC   RFC8040 - Page 59
   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].
Top   ToC   RFC8040 - Page 60
   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.



(page 60 continued on part 4)

Next Section