idnits 2.17.1 draft-wwlh-netconf-list-pagination-rc-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.wwlh-netconf-list-pagination], [RFC8040]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 281 has weird spacing: '...t-limit urn:i...' -- The document date (25 October 2021) is 912 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC7950' is mentioned on line 304, but not defined -- No information found for draft-wwlh-netconf-list-pagination - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'I-D.wwlh-netconf-list-pagination' Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Watsen Networks 4 Updates: 8040 (if approved) Q. Wu 5 Intended status: Standards Track Huawei Technologies 6 Expires: 28 April 2022 O. Hagsand 7 Netgate 8 H. Li 9 Hewlett Packard Enterprise 10 P. Andersson 11 Cisco Systems 12 25 October 2021 14 RESTCONF Extensions to Support List Pagination 15 draft-wwlh-netconf-list-pagination-rc-02 17 Abstract 19 This document defines a mapping of the list pagination mechanism 20 defined in [I-D.wwlh-netconf-list-pagination] to RESTCONF [RFC8040]. 22 This document updates RFC 8040, to declare "list" and "leaf-list" as 23 valid resource targets for the RESTCONF GET and DELETE operations, to 24 define GET query parameters necessary for list pagination, and to 25 define a media-type for XML-based lists. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 28 April 2022. 44 Copyright Notice 46 Copyright (c) 2021 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Simplified BSD License text 55 as described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Updates to RFC 8040 . . . . . . . . . . . . . . . . . . . . . 3 64 2.1. Resource Targets . . . . . . . . . . . . . . . . . . . . 3 65 2.2. Media Type . . . . . . . . . . . . . . . . . . . . . . . 3 66 2.3. Query Parameters . . . . . . . . . . . . . . . . . . . . 4 67 2.3.1. The "limit" Query Parameter . . . . . . . . . . . . . 5 68 2.3.2. The "offset" Query Parameter . . . . . . . . . . . . 5 69 2.3.3. The "direction" Query Parameter . . . . . . . . . . . 5 70 2.3.4. The "sort-by" Query Parameter . . . . . . . . . . . . 6 71 2.3.5. The "where" Query Parameter . . . . . . . . . . . . . 6 72 2.3.6. The "sublist-limit" Query Parameter . . . . . . . . . 6 73 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 74 3.1. The "RESTCONF Capability URNs" Registry . . . . . . . . . 6 75 3.2. The "Media Types" Registry . . . . . . . . . . . . . . . 7 76 3.2.1. Media Type "application/yang-data+xml-list" . . . . . 7 77 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 78 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 79 5.1. Normative References . . . . . . . . . . . . . . . . . . 8 80 5.2. Informative References . . . . . . . . . . . . . . . . . 9 81 Appendix A. Example YANG Module . . . . . . . . . . . . . . . . 9 82 Appendix B. Example Data Set . . . . . . . . . . . . . . . . . . 9 83 Appendix C. Example Queries . . . . . . . . . . . . . . . . . . 9 84 C.1. List pagination with all query parameters . . . . . . . . 9 85 C.2. Deletion of a list . . . . . . . . . . . . . . . . . . . 11 86 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 11 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 89 1. Introduction 91 This document defines a mapping of the list pagination mechanism 92 defined in [I-D.wwlh-netconf-list-pagination] to RESTCONF [RFC8040]. 94 This document updates RFC 8040, as described in Section 2. 96 Declaring "list" and "leaf-list" as valid resource targets for the 97 GET operation is necessary for list pagination. Declaring these 98 nodes as valid resource targets for the DELETE operation merely 99 completes the solution for RESTCONF. 101 1.1. Terminology 103 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 104 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 105 "OPTIONAL" in this document are to be interpreted as described in BCP 106 14 [RFC2119] [RFC8174] when, and only when, they appear in all 107 capitals, as shown here. 109 1.2. Conventions 111 Various examples used in this document use a placeholder value for 112 binary data that has been base64 encoded (e.g., "BASE64VALUE="). 113 This placeholder value is used as real base64 encoded structures are 114 often many lines long and hence distracting to the example being 115 presented. 117 2. Updates to RFC 8040 119 2.1. Resource Targets 121 This document extends Section 3.5 of [RFC8040] to add "list" and 122 "leaf-list" nodes (not just their entries) as valid data resources 123 for the "GET" and "DELETE" operations. 125 2.2. Media Type 127 This document extends Section 3.2 of [RFC8040] to add a new media 128 type, "application/yang-data+xml-list", to encode "list" and "leaf- 129 list" nodes in XML. 131 The "application/yang-data+xml-list" media-type defines a pseudo top- 132 level element called "xml-list" that is used to wrap the response 133 set, thus ensuring that a single top-level element is returned for 134 the XML encoding", as required by Section 4.3 of [RFC8040]. 136 For JSON, the existing "application/yang-data+json" media type is 137 sufficient, as the JSON format has built-in support for encoding 138 arrays. 140 The "application/yang-data+xml-list" media type is registered in 141 Section 3.2.1. 143 2.3. Query Parameters 145 This document extends Section 4.8 of [RFC8040] to add new query 146 parameters "limit", "offset", "direction", "sort-by", "where", and 147 "sublist-list". 149 These six query parameters correspond to those defined in Sections 150 3.1 and 3.2 in [I-D.wwlh-netconf-list-pagination]. 152 +-----------+---------+-----------------------------------------+ 153 | Name | Methods | Description | 154 +-----------+---------+-----------------------------------------+ 155 | limit | GET, | Limits the number of entries returned. | 156 | | HEAD | If not specified, the number of entries | 157 | | | that may be returned is unbounded. | 158 | | | | 159 | offset | GET, | Indicates the number of entries in the | 160 | | HEAD | result set that should the skipped over | 161 | | | when preparing the response. If not | 162 | | | specified, then no entries in the | 163 | | | result set are skipped. | 164 | | | | 165 | direction | GET, | Indicates the direction that the result | 166 | | HEAD | set is to be traversed. If not | 167 | | | specified, then the result set is | 168 | | | traversed in the "forwards" direction. | 169 | | | | 170 | sort-by | GET, | Indicates the node name that the result | 171 | | HEAD | set should be sorted by. If not | 172 | | | specified, then the result set's | 173 | | | default order is used, per YANG's | 174 | | | "ordered-by" statement. | 175 | | | | 176 | where | GET, | Specifies a filter expression that | 177 | | HEAD | result set entries must match. If | 178 | | | not specified, then no entries are | 179 | | | filtered from the result set. | 180 | | | | 181 | sublist- | GET, | Limits the number of entries returned | 182 | limit | HEAD | returned for descendent lists and | 183 | | | leaf-lists. If not specified, the | 184 | | | number of entries that may be returned | 185 | | | is unbounded. | 186 +-----------+---------+-----------------------------------------+ 187 For all of the query parameters, the query parameter is only allowed 188 for the GET and HEAD methods on "list" and "leaf-list" data 189 resources. A "400 Bad Request" status-line MUST be returned if used 190 with any other method or resource type. The error-tag value 191 "operation-not-supported" is used in this case. 193 Per the conformance defined in Section 3.1 of 194 [I-D.wwlh-netconf-list-pagination], all of these parameters MUST be 195 supported for all lists and leaf-lists, but servers MAY disable the 196 support for some or all "config false" lists, as described in 197 Section 3.3 of [I-D.wwlh-netconf-list-pagination]. 199 2.3.1. The "limit" Query Parameter 201 The "limit" query parameter corresponds to the "limit" parameter 202 defined in Section 3.1.5 of [I-D.wwlh-netconf-list-pagination]. 204 If the limit value is invalid, then a "400 Bad Request" status-line 205 MUST be returned with the error-type value "application" and error- 206 tag value "invalid-value". 208 2.3.2. The "offset" Query Parameter 210 The "offset" query parameter corresponds to the "offset" parameter 211 defined in Section 3.1.4 of [I-D.wwlh-netconf-list-pagination]. 213 If the offset value is invalid, a "400 Bad Request" status-line MUST 214 be returned with the error-type value "application" and error-tag 215 value "invalid-value". 217 If the offset value exceeds the number of entries in the working 218 result set, then a "416 Range Not Satisfiable" status-line MUST be 219 returned with the error-type value "application", error-tag value 220 "invalid-value", and SHOULD also include the "offset-out-of-range" 221 identity as error-app-tag value. 223 2.3.3. The "direction" Query Parameter 225 The "direction" query parameter corresponds to the "direction" 226 parameter defined in Section 3.1.3 of 227 [I-D.wwlh-netconf-list-pagination]. 229 If the direction value is invalid, then a "400 Bad Request" status- 230 line MUST be returned with the error-type value "application" and 231 error-tag value "invalid-value". 233 2.3.4. The "sort-by" Query Parameter 235 The "sort-by" query parameter corresponds to the "sort-by" parameter 236 defined in Section 3.1.2 of [I-D.wwlh-netconf-list-pagination]. 238 If the specified node identifier is invalid, then a "400 Bad Request" 239 status-line MUST be returned with the error-type value "application" 240 and error-tag value "invalid-value". 242 2.3.5. The "where" Query Parameter 244 The "where" query parameter corresponds to the "where" parameter 245 defined in Section 3.1.1 of [I-D.wwlh-netconf-list-pagination]. 247 If the specified XPath expression is invalid, then a "400 Bad 248 Request" status-line MUST be returned with the error-type value 249 "application" and error-tag value "invalid-value". 251 2.3.6. The "sublist-limit" Query Parameter 253 The "sublist-limit" query parameter corresponds to the "sublist- 254 limit" parameter defined in Section 3.2.1 of 255 [I-D.wwlh-netconf-list-pagination]. 257 If the sumlist-limit value is invalid, then a "400 Bad Request" 258 status-line MUST be returned with the error-type value "application" 259 and error-tag value "invalid-value". 261 3. IANA Considerations 263 3.1. The "RESTCONF Capability URNs" Registry 265 This document registers six capabilities in the RESTCONF Capability 266 URNs [RFC8040] maintained at https://www.iana.org/assignments/ 267 restconf-capability-urns/restconf-capability-urns.xhtml. Following 268 the instructions defined in Section 11.4 of [RFC8040], the below 269 registrations are requested: 271 All the registrations are to use this document (RFC XXXX) for the 272 "Reference" value. 274 Index Capability Identifier 275 --------------------------------------------------------------------- 276 :limit urn:ietf:params:restconf:capability:limit:1.0 277 :offset urn:ietf:params:restconf:capability:offset:1.0 278 :direction urn:ietf:params:restconf:capability:direction:1.0 279 :sort-by urn:ietf:params:restconf:capability:sort-by:1.0 280 :where urn:ietf:params:restconf:capability:where:1.0 281 :sublist-limit urn:ietf:params:restconf:capability:sublist-limit:1.0 283 3.2. The "Media Types" Registry 285 This document registers one media type in the "application" 286 subregistry of the Media Types registry [RFC6838] [RFC4855] 287 maintained at https://www.iana.org/assignments/media-types/media- 288 types.xhtml#application. Following the format defined in [RFC4855], 289 the below registration is requested: 291 3.2.1. Media Type "application/yang-data+xml-list" 293 Type name: application 295 Subtype name: yang-data+xml-list 297 Required parameters: None 299 Optional parameters: None 301 Encoding considerations: 8-bit 302 Each conceptual YANG data node is encoded according to the 303 XML Encoding Rules and Canonical Format for the specific 304 YANG data node type defined in [RFC7950]. 306 Security considerations: Security considerations related 307 to the generation and consumption of RESTCONF messages 308 are discussed in Section 12 of RFC 8040. Additional 309 security considerations are specific to the semantics 310 of particular YANG data models. Each YANG module is 311 expected to specify security considerations for the 312 YANG data defined in that module. 314 Interoperability considerations: RFC XXXX specifies the 315 format of conforming messages and the interpretation 316 thereof. 318 Published specification: RFC XXXX 320 Applications that use this media type: Instance document data 321 parsers used within a protocol or automation tool that 322 utilize the YANG Patch data structure. 324 Fragment identifier considerations: Fragment identifiers for 325 this type are not defined. All YANG data nodes are 326 accessible as resources using the path in the request URI. 328 Additional information: 330 Deprecated alias names for this type: N/A 331 Magic number(s): N/A 332 File extension(s): None 333 Macintosh file type code(s): "TEXT" 335 Person & email address to contact for further information: 336 See the Authors' Addresses section of RFC XXXX. 338 Intended usage: COMMON 340 Restrictions on usage: N/A 342 Author: See the Authors' Addresses section of RFC XXXX. 344 Change controller: Internet Engineering Task Force 345 (mailto:iesg@ietf.org). 347 Provisional registration? (standards tree only): no 349 4. Security Considerations 351 This document introduces protocol operations for paging through data 352 already provided by the RESTCONF protocol, and hence does not 353 introduce any new security considerations. 355 This document does not define a YANG module and hence there are no 356 data modeling considerations beyond those discussed in 357 [I-D.wwlh-netconf-list-pagination]. 359 5. References 361 5.1. Normative References 363 [I-D.wwlh-netconf-list-pagination] 364 "List Pagination...", . 366 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 367 Requirement Levels", BCP 14, RFC 2119, 368 DOI 10.17487/RFC2119, March 1997, 369 . 371 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 372 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 373 . 375 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 376 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 377 May 2017, . 379 5.2. Informative References 381 [I-D.ietf-netconf-restconf-collection] 382 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 383 Collection Resource", Work in Progress, Internet-Draft, 384 draft-ietf-netconf-restconf-collection-00, 30 January 385 2015, . 388 [RFC4855] Casner, S., "Media Type Registration of RTP Payload 389 Formats", RFC 4855, DOI 10.17487/RFC4855, February 2007, 390 . 392 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 393 Specifications and Registration Procedures", BCP 13, 394 RFC 6838, DOI 10.17487/RFC6838, January 2013, 395 . 397 Appendix A. Example YANG Module 399 The examples within this document use the "example-social" YANG 400 module defined in Appendix A.1 of [I-D.wwlh-netconf-list-pagination]. 402 Appendix B. Example Data Set 404 The Example Data Set used by the examples is defined in Appendix A.2 405 of [I-D.wwlh-netconf-list-pagination]. 407 Appendix C. Example Queries 409 C.1. List pagination with all query parameters 411 This example mimics that Appendix A.3.7 of 412 [I-D.wwlh-netconf-list-pagination]. 414 =============== NOTE: '\' line wrapping per RFC 8792 ================ 416 GET /restconf/ds/ietf-datastores:running/example-social:members/memb\ 417 er?where=//stats//joined[starts-with(@timestamp,'2020')]&sort-by=tim\ 418 estamp&direction=backwards&offset=2&limit=2&sublist-limit=1 HTTP/1.1 419 Host: example.com 420 Accept: application/yang-data+xml-list 422 Response from the RESTCONF server: 424 =============== NOTE: '\' line wrapping per RFC 8792 ================ 426 HTTP/1.1 200 OK 427 Date: Thu, 26 Jan 2017 20:56:30 GMT 428 Server: example-server 429 Last-Modified: Thu, 26 Jan 2017 20:55:30 GMT 430 Content-Type: application/yang-data+xml-list 432 435 436 eric 437 eric@example.com 438 $0$1543 439 BASE64VALUE= 440 Go to bed with dreams; wake up with a purpose. 441 alice 442 443 444 2020-09-17T18:02:04Z 445 Son, brother, husband, father 446 What's your story? 447 448 449 450 two 451 452 453 2020-09-17T19:38:32Z 454 pro 455 2020-09-17T18:02:04Z 456 457 458 459 bob 460 bob@example.com 461 $0$1543 462 BASE64VALUE= 463 Here and now, like never before. 464 465 466 2020-08-14T03:32:25Z 467 Just got in. 468 469 470 471 3.14159 472 473 474 2020-08-14T03:30:00Z 475 standard 476 2020-08-14T03:34:30Z 477 478 479 481 C.2. Deletion of a list 483 This example illustrates using a "list" as the DELETE target. 485 =============== NOTE: '\' line wrapping per RFC 8792 ================ 487 DELETE /restconf/ds/ietf-datastores:running/example-social:members/m\ 488 ember=bob/favorites/decimal64-numbers HTTP/1.1 489 Host: example.com 490 Accept: application/yang-data+xml 492 Response from the RESTCONF server: 494 HTTP/1.1 204 No Content 495 Date: Thu, 26 Jan 2017 20:56:30 GMT 496 Server: example-server 498 Acknowledgements 500 This work has benefited from the discussions of restconf resource 501 collection over the years, in particular, 502 [I-D.ietf-netconf-restconf-collection]. The authors additionally 503 thank the following for lively discussions on list (ordered by first 504 name): Andy Bierman, Martin Bjoerklund, and Robert Varga 506 Authors' Addresses 507 Kent Watsen 508 Watsen Networks 510 Email: kent+ietf@watsen.net 512 Qin Wu 513 Huawei Technologies 514 101 Software Avenue, Yuhua District 515 Nanjing 516 Jiangsu, 210012 517 China 519 Email: bill.wu@huawei.com 521 Olof Hagsand 522 Netgate 524 Email: olof@hagsand.se 526 Hongwei Li 527 Hewlett Packard Enterprise 529 Email: flycoolman@gmail.com 531 Per Andersson 532 Cisco Systems 534 Email: perander@cisco.com