]> RESTCONF Extensions to Support List Pagination Watsen Networks
kent+ietf@watsen.net
Huawei Technologies
bill.wu@huawei.com
Ionio Systems
per.ietf@ionio.se
SUNET
olof@hagsand.se
Hewlett Packard Enterprise
flycoolman@gmail.com
OPS Area NETCONF Working Group This document defines a mapping of the list pagination mechanism defined in to RESTCONF . This document updates RFC 8040, to declare "list" and "leaf-list" as valid resource targets for the RESTCONF GET operation, to define GET query parameters necessary for list pagination, and to define a media-type for XML-based lists.
Introduction This document defines a mapping of the list pagination mechanism defined in to RESTCONF . This document updates RFC 8040, as described in . Declaring "list" and "leaf-list" as valid resource targets for the GET operation is necessary for list pagination.
Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.
Conventions Various examples in this document use "BASE64VALUE=" as a placeholder value for binary data that has been base64 encoded (per ). This placeholder value is used because real base64 encoded structures are often many lines long and hence distracting to the example being presented.
Updates to RFC 8040
Resource Targets This document extends to add "list" and "leaf-list" nodes (not just their entries) as valid data resources for the "GET" operation.
Media Type This document extends to add a new media type, "application/yang-data+xml-list", to encode "list" and "leaf-list" nodes in XML. The "application/yang-data+xml-list" media-type defines a pseudo top-level element called "xml-list" that is used to wrap the response set, thus ensuring that a single top-level element is returned for the XML encoding, as required by . For JSON, the existing "application/yang-data+json" media type is sufficient, as the JSON format has built-in support for encoding arrays. The "application/yang-data+xml-list" media type is registered in .
Query Parameters This document extends to add new query parameters "limit", "offset", "cursor", "direction", "sort-by", "locale", "where", and "sublist-limit". These eight query parameters correspond to those defined in Sections 3.1 and 3.2 in . Note that complex pagination with combination of query parameters may cause performance strain on constrained devices due to intensive processing on both the server and the client. For all of the query parameters, the query parameter is only allowed for the GET and HEAD methods on "list" and "leaf-list" data resources. A "400 Bad Request" status-line MUST be returned if used with any other method or resource type. The error-tag value "operation-not-supported" is used in this case. Per the conformance defined in , all of these parameters MUST be supported for all "config true" lists and leaf-lists, and SHOULD be supported for "config false" lists and leaf-lists. A server MAY disable the support for some or all "config false" lists, as described in .
The "limit" Query Parameter The "limit" query parameter corresponds to the "limit" parameter defined in . If the limit value is invalid, i.e. not an unsigned 32-bit integer greater than or equal to 1 or the string "unbounded", then a "400 Bad Request" status-line MUST be returned with the error-type value "application" and error-tag value "invalid-value".
The "offset" Query Parameter The "offset" query parameter corresponds to the "offset" parameter defined in . If the offset value is invalid, a "400 Bad Request" status-line MUST be returned with the error-type value "application" and error-tag value "invalid-value". If the offset value exceeds the number of entries in the working result set, then a "416 Range Not Satisfiable" status-line MUST be returned with the error-type value "application", error-tag value "invalid-value", and SHOULD also include the "offset-out-of-range" identity as the error-app-tag value.
The "cursor" Query Parameter The "cursor" query parameter corresponds to the "cursor" parameter defined in . As described in the server does not keep any stateful information about the "next" and "previous" cursor or the current page. Due to their ephemeral nature, cursor values are never cached. If the cursor value is unknown, i.e. the key does not exist, a "404 Not Found" status-line MUST be returned with the error-type value "application" and error-tag value "invalid-value", and SHOULD also include the "cursor-not-found" identity as the error-app-tag value. If the "cursor" query parameter is not supported on the target node, then a "501 Not Implemented" status-line MUST be returned with error-type value "application" and error-tag value "operation-not-supported".
The "direction" Query Parameter The "direction" query parameter corresponds to the "direction" parameter defined in . If the direction value is invalid, then a "400 Bad Request" status-line MUST be returned with the error-type value "application" and error-tag value "invalid-value".
The "sort-by" Query Parameter The "sort-by" query parameter corresponds to the "sort-by" parameter defined in . If the specified node identifier is invalid, then a "400 Bad Request" status-line MUST be returned with the error-type value "application" and error-tag value "invalid-value".
The "locale" Query Parameter The "locale" query parameter corresponds to the "locale" parameter defined in . If the specified node identifier is invalid, i.e. the locale is unknown to the server, then a "501 Not Implemented" status-line MUST be returned with the error-type value "application" and error-tag value "invalid-value", and SHOULD also include the "locale-unavailable" identity as the error-app-tag value. If "locale" is supplied but not "sort-by", a "400 Bad Request" status-line MUST be returned with the error-type "application" and error-tag value "invalid-value".
The "where" Query Parameter The "where" query parameter corresponds to the "where" parameter defined in . Prefixes in the XPath expression MUST be YANG module names. If the specified XPath expression is invalid, then a "400 Bad Request" status-line MUST be returned with the error-type value "application" and error-tag value "invalid-value".
The "sublist-limit" Query Parameter The "sublist-limit" query parameter corresponds to the "sublist-limit" parameter defined in . If the sublist-limit value is invalid, then a "400 Bad Request" status-line MUST be returned with the error-type value "application" and error-tag value "invalid-value".
IANA Considerations
The "RESTCONF Capability URNs" Registry This document registers six capabilities in the RESTCONF Capability URNs maintained at . Following the instructions defined in , the below registrations are requested: All registrations are to use this document (RFC XXXX) for the "Reference" value.
The "Media Types" Registry This document registers one media type in the "application" subregistry of the Media Types registry maintained at . Following the format defined in , the below registration is requested:
Media Type "application/yang-data+xml-list"
Security Considerations This document introduces protocol operations for paging through data already provided by the RESTCONF protocol, and hence does not introduce any new security considerations. This document does not define a YANG module and hence there are no data modeling considerations beyond those discussed in .
References Normative References Informative References
Example YANG Module The examples within this document use the "example-social" YANG module defined in .
Example Data Set The Example Data Set used by the examples is defined in .
Example Queries
List pagination with all query parameters This example mimics that . This example is presented twice, once using XML and again using JSON. XML: Response from the RESTCONF server: eric eric@example.com $0$1543 BASE64VALUE= Go to bed with dreams; wake up with purpose. alice 2020-09-17T18:02:04Z Son, brother, husband, father What's your story? two 2020-09-17T19:38:32Z pro 2020-09-17T18:02:04Z bob bob@example.com $0$1543 BASE64VALUE= Here and now, like never before. 2020-08-14T03:32:25Z Just got in. 3.14159<\ /decimal64-numbers> 2020-08-14T03:30:00Z standard 2020-08-14T03:34:30Z ]]> JSON: Response from the RESTCONF server:
Acknowledgements This work has benefited from the discussions of RESTCONF resource collection over the years, in particular, which provides enhanced filtering features for the retrieval of data nodes with the GET method and which document large size data handling challenge. The authors would like to thank the following for lively discussions on list (ordered by first name): Andy Bierman, Martin Björklund, Robert Varga, and Rob Wilton.