]> Watsen Networks

kent+ietf@watsen.net

Huawei Technologies

101 Software Avenue, Yuhua District Nanjing Jiangsu 210012 China bill.wu@huawei.com

Netgate

olof@hagsand.se

Hewlett Packard Enterprise

flycoolman@gmail.com

Cisco Systems

perander@cisco.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 and DELETE operations, 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. Declaring these nodes as valid resource targets for the DELETE operation merely completes the solution for RESTCONF.

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 used in this document use a placeholder value for binary data that has been base64 encoded (e.g., "BASE64VALUE=“). This placeholder value is used as 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" and "DELETE" operations.

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", "where", and "sublist-list". These six query parameters correspond to those defined in Sections 3.1 and 3.2 in . 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 lists and leaf-lists, but servers 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, 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 error-app-tag value.

The "cursor" Query Parameter The "cursor" querey parameter corresponds to the "cursor" parameter defined in . 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 error-app-tag value.

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 "where" Query Parameter The "where" query parameter corresponds to the "where" parameter defined in . 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 sumlist-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 the 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 In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF). RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References This document specifies the procedure to register RTP payload formats as audio, video, or other media subtype names. This is useful in a text-based format description or control protocol to identify the type of an RTP transmission. [STANDARDS-TRACK] This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice.

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 . Response from the RESTCONF server: eric eric@example.com $0$1543 BASE64VALUE= Go to bed with dreams; wake up with a purpose. alice 2020-09-17T18:02:04Z 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 2020-08-14T03:30:00Z standard 2020-08-14T03:34:30Z ]]>

Deletion of a leaf-list This example illustrates using a "leaf-list" as the DELETE target. Response from the RESTCONF server:

Acknowledgements This work has benefited from the discussions of restconf resource collection over the years, in particular, . The authors additionally thank the following for lively discussions on list (ordered by first name): Andy Bierman, Martin Björklund, and Robert Varga