idnits 2.17.1 draft-ietf-netconf-restconf-collection-00.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (January 30, 2015) is 3373 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: 'FIXME' is mentioned on line 695, but not defined == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-04 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track M. Bjorklund 5 Expires: August 3, 2015 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 January 30, 2015 10 RESTCONF Collection Resource 11 draft-ietf-netconf-restconf-collection-00 13 Abstract 15 This document describes a collection resource for the RESTCONF 16 protocol to provide enhanced filtering features for the retrieval of 17 data nodes with the GET method. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on August 3, 2015. 36 Copyright Notice 38 Copyright (c) 2015 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 5 58 1.1.4. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 5 59 1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 60 1.1.6. URI Template . . . . . . . . . . . . . . . . . . . . 6 61 1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 6 62 1.2. Collection Resource Type . . . . . . . . . . . . . . . . 6 63 1.3. Collection Resource . . . . . . . . . . . . . . . . . . . 6 64 1.4. Query Parameters . . . . . . . . . . . . . . . . . . . . 7 65 1.4.1. Query Parameter URIs . . . . . . . . . . . . . . . . 7 66 1.4.2. The "limit" Query Parameter . . . . . . . . . . . . . 8 67 1.4.3. The "offset" Query Parameter . . . . . . . . . . . . 8 68 1.4.4. The "sort" Query Parameter . . . . . . . . . . . . . 8 69 1.4.5. The "where" Query Parameter . . . . . . . . . . . . . 8 70 2. RESTCONF Collection module . . . . . . . . . . . . . . . . . 9 71 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 72 3.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 11 73 3.2. application/yang Media Sub Types . . . . . . . . . . . . 11 74 3.3. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 12 75 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 76 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 77 6. Normative References . . . . . . . . . . . . . . . . . . . . 13 78 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 14 79 A.1. restconf-03 to restconf-collection-00 . . . . . . . . . . 14 80 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 14 81 Appendix C. RESTCONF Collection Examples . . . . . . . . . . . . 14 82 C.1. "limit" Parameter . . . . . . . . . . . . . . . . . . . . 14 83 C.2. "offset" Parameter . . . . . . . . . . . . . . . . . . . 15 84 C.3. "sort" Parameter . . . . . . . . . . . . . . . . . . . . 16 85 C.4. "where" Parameter . . . . . . . . . . . . . . . . . . . . 16 86 C.5. "TopN" Use Case . . . . . . . . . . . . . . . . . . . . . 16 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 89 1. Introduction 91 There is a need for standard mechanisms to control the filtering, 92 sorting, and retrieval of data from RESTCONF devices. A server may 93 contain many instances of a particular YANG list. Retrieval of the 94 entire list at once can be extremely inefficient. 96 Pagination mechanisms are needed to allow a client to iterate through 97 a large list, in a manner that is most efficient for the application. 99 This document describes a "collection" resource that can be used to 100 control retrieval of data nodes from a RESTCONF server. 102 [FIXME: describe basic needs 103 - target resource picks the list 104 - 'fields' is a node-set XPath expression to pick 105 the subtrees within the target resource 106 to return 107 - 'where' is a boolean XPath expression to pick which list 108 instances are selected for return 109 - 'sort' is ??? parameter to sort the selected list instances 110 - 'limit' is the max number of list instances returned 111 - 'offset' is the XPath position() of the list instance 112 ??? pre or post access control ??? 113 ??? if post, then what if NACM changes while client 114 retrieving 115 ] 117 Collection resources represent search results through the server 118 data. Data that the client is not authorized to receive according to 119 the access control parameters configured in [RFC6536] MUST NOT be 120 returned in RESTCONF response messages. 122 1.1. Terminology 124 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 126 "OPTIONAL" in this document are to be interpreted as described in BCP 127 14, [RFC2119]. 129 [FIXME: remove terms that are not used] 131 1.1.1. NETCONF 133 The following terms are defined in [RFC6241]: 135 o candidate configuration datastore 137 o client 139 o configuration data 141 o datastore 143 o configuration datastore 144 o protocol operation 146 o running configuration datastore 148 o server 150 o startup configuration datastore 152 o state data 154 o user 156 1.1.2. HTTP 158 The following terms are defined in [RFC3986]: 160 o fragment 162 o path 164 o query 166 The following terms are defined in [RFC7230]: 168 o header 170 o message-body 172 o Request-Line 174 o request URI 176 The following terms are defined in [RFC7231]: 178 o method 180 o request 182 o resource 184 The following terms are defined in [RFC7232]: 186 o entity tag 188 1.1.3. YANG 190 The following terms are defined in [RFC6020]: 192 o container 194 o data node 196 o key leaf 198 o leaf 200 o leaf-list 202 o list 204 o presence container (or P-container) 206 o RPC operation (now called protocol operation) 208 o non-presence container (or NP-container) 210 o ordered-by system 212 o ordered-by user 214 1.1.4. RESTCONF 216 The following terms are defined in [I-D.ietf-netconf-restconf]: 218 o data resource 220 o target resource 222 o retrieval request 224 1.1.5. Terms 226 The following terms are used within this document: 228 o collection resource: a resource with the media type "application/ 229 yang.collection+xml" or "application/yang.collection+json". 230 Contains a set of data resources. 232 1.1.6. URI Template 234 Throughout this document, the URI template [RFC6570] syntax 235 "{+restconf}" is used to refer to the RESTCONF API entry point 236 outside of an example. See the root resource discovery serction 237 defined in [I-D.ietf-netconf-restconf] for details. 239 All of the examples in this document assume "/restconf" as the 240 discovered RESTCONF API root path. 242 1.1.7. Tree Diagrams 244 A simplified graphical representation of the data model is used in 245 this document. The meaning of the symbols in these diagrams is as 246 follows: 248 o Brackets "[" and "]" enclose list keys. 250 o Abbreviations before data node names: "rw" means configuration 251 data (read-write) and "ro" state data (read-only). 253 o Symbols after data node names: "?" means an optional node, "!" 254 means a presence container, and "*" denotes a list and leaf-list. 256 o Parentheses enclose choice and case nodes, and case nodes are also 257 marked with a colon (":"). 259 o Ellipsis ("...") stands for contents of subtrees that are not 260 shown. 262 1.2. Collection Resource Type 264 The following resource type are defined in this document: 266 +------------+-----------------------------+ 267 | Resource | Media Type | 268 +------------+-----------------------------+ 269 | Collection | application/yang.collection | 270 +------------+-----------------------------+ 272 RESTCONF Media Types 274 1.3. Collection Resource 276 A collection resource contains a set of data resources. It is used 277 to represent a all instances or a subset of all instances in a YANG 278 list or leaf-list. 280 A collection resource can be retrieved with the GET method, 281 optionally with the query parameters "limit" (Section 1.4.2) and 282 "offset" (Section 1.4.3). 284 The "ietf-restconf-collection" YANG module contains the "application/ 285 yang.collection" restconf-media-type extension which specifies the 286 syntax and semantics of a "collection" media type. 288 1.4. Query Parameters 290 Each RESTCONF operation allows zero or more query parameters to be 291 present in the request URI. The following query parameters are 292 defined for RESTCONF collection resources. 294 +--------+---------+------------------------------------------------+ 295 | Name | Methods | Description | 296 +--------+---------+------------------------------------------------+ 297 | limit | GET | Number of entries to return for collection | 298 | | | resources | 299 | offset | GET | Starting point for collection resources | 300 | sort | GET | Sorting criteria for collection resources | 301 | where | GET | Boolean filter to select data instances for a | 302 | | | collection resource | 303 +--------+---------+------------------------------------------------+ 305 RESTCONF Query Parameters 307 Query parameters can be given in any order. Each parameter can 308 appear at most once in a request URI. A default value may apply if 309 the parameter is missing. 311 Refer to Appendix C for examples of query parameter usage. 313 If vendors define additional query parameters, they SHOULD use a 314 prefix (such as the enterprise or organization name) for query 315 parameter names in order to avoid collisions with other parameters. 317 1.4.1. Query Parameter URIs 319 A new set of RESTCONF Capability URNs are defined to identify the 320 specific query parameters supported by the server. 322 +------+----------------------------------------------------+ 323 | Name | URI | 324 +------+----------------------------------------------------+ 325 | page | urn:ietf:params:restconf:capability:page:1.0 | 326 | page | urn:ietf:params:restconf:capability:page-xpath:1.0 | 327 +------+----------------------------------------------------+ 329 RESTCONF Query Parameter URIs 331 1.4.2. The "limit" Query Parameter 333 The "limit" parameter is used to restrict the number of data 334 resources to return in response to GET requests on collection 335 resources. 337 The value of the "limit" parameter is either an integer greater than 338 or equal to 1, or the string "unbounded". The string "unbounded" is 339 the default value. 341 If the server includes the "page" query parameter URI in the 342 "capability" leaf-list in the "ietf-restconf-monitoring" module 343 defined in [I-D.ietf-netconf-restconf], then the "limit" query 344 parameter MUST be supported. 346 1.4.3. The "offset" Query Parameter 348 The "offset" parameter is used to specify the first data resource to 349 return in response to GET requests on collection resources. 350 Resources instances are numbered with consecutive integers from 1 to 351 the number of resource instances. 353 The value of the "offset" parameter is an integer greater than or 354 equal to 1. The default value is 1. 356 If the server includes the "page" query parameter URI in the 357 "capability" leaf-list in "ietf-restconf-monitoring" module defined 358 in [I-D.ietf-netconf-restconf], then the "offset" query parameter 359 MUST be supported. 361 1.4.4. The "sort" Query Parameter 363 [FIXME] 365 1.4.5. The "where" Query Parameter 367 [FIXME] 369 2. RESTCONF Collection module 371 The "ietf-restconf-collection" module defines conceptual definitions 372 within groupings, which are not meant to be implemented as datastore 373 contents by a server. 375 The "ietf-restconf" module from [I-D.ietf-netconf-restconf] is used 376 by this module for the 'restconf-media-type' extension definition. 378 RFC Ed.: update the date below with the date of RFC publication and 379 remove this note. 381 file "ietf-restconf-collection@2015-01-30.yang" 383 module ietf-restconf-collection { 384 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-collection"; 385 prefix "rcoll"; 387 import ietf-restconf { 388 prefix rc; 389 revision-date 2015-01-30; 390 } 392 organization 393 "IETF NETCONF (Network Configuration) Working Group"; 395 contact 396 "WG Web: 397 WG List: 399 WG Chair: Mehmet Ersue 400 402 WG Chair: Mahesh Jethanandani 403 405 Editor: Andy Bierman 406 408 Editor: Martin Bjorklund 409 411 Editor: Kent Watsen 412 "; 414 description 415 "This module contains conceptual YANG specifications 416 for the RESTCONF Collection resource type. 418 Note that the YANG definitions within this module do not 419 represent configuration data of any kind. 420 The YANG grouping statements provide a normative syntax 421 for XML and JSON message encoding purposes. 423 Copyright (c) 2015 IETF Trust and the persons identified as 424 authors of the code. All rights reserved. 426 Redistribution and use in source and binary forms, with or 427 without modification, is permitted pursuant to, and subject 428 to the license terms contained in, the Simplified BSD License 429 set forth in Section 4.c of the IETF Trust's Legal Provisions 430 Relating to IETF Documents 431 (http://trustee.ietf.org/license-info). 433 This version of this YANG module is part of RFC XXXX; see 434 the RFC itself for full legal notices."; 436 // RFC Ed.: replace XXXX with actual RFC number and remove this 437 // note. 439 // RFC Ed.: remove this note 440 // Note: extracted from 441 // draft-ietf-netconf-restconf-collection-00.txt 443 // RFC Ed.: update the date below with the date of RFC publication 444 // and remove this note. 445 revision 2015-01-30 { 446 description 447 "Initial revision."; 448 reference 449 "RFC XXXX: RESTCONF Collection Resource."; 450 } 452 rc:restconf-media-type "application/yang.collection" { 453 uses collection; 454 } 456 grouping collection { 457 description 458 "Conceptual container representing the 459 application/yang.collection resource type."; 461 container collection { 462 description 463 "Container representing the application/yang.collection 464 resource type."; 465 } 467 } // grouping collection 469 } 471 473 3. IANA Considerations 475 3.1. YANG Module Registry 477 This document registers three URIs in the IETF XML registry 478 [RFC3688]. Following the format in RFC 3688, the following 479 registration is requested to be made. 481 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-collection 482 Registrant Contact: The NETMOD WG of the IETF. 483 XML: N/A, the requested URI is an XML namespace. 485 This document registers three YANG modules in the YANG Module Names 486 registry [RFC6020]. 488 name: ietf-restconf-collection 489 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-collection 490 prefix: rcoll 491 // RFC Ed.: replace XXXX with RFC number and remove this note 492 reference: RFC XXXX 494 3.2. application/yang Media Sub Types 496 The parent MIME media type for RESTCONF resources is application/ 497 yang, which is defined in [RFC6020]. This document defines the 498 following sub-types for this media type. 500 - collection 502 Type name: application 504 Subtype name: yang.xxx 506 Required parameters: TBD 508 Optional parameters: TBD 510 Encoding considerations: TBD 512 Security considerations: TBD 514 Interoperability considerations: TBD 516 // RFC Ed.: replace XXXX with RFC number and remove this note 517 Published specification: RFC XXXX 519 3.3. NETCONF Capability URNs 521 This document registers two capability identifiers in "RESTCONF 522 Protocol Capability URNs" registry 524 Index 525 Capability Identifier 526 ------------------------ 528 :page 529 urn:ietf:params:restconf:capability:page:1.0 531 :page-xpath 532 urn:ietf:params:restconf:capability:page-xpath:1.0 534 4. Security Considerations 536 This section provides security considerations for the resources 537 defined by the RESTCONF protocol. Security considerations for HTTPS 538 are defined in [RFC2818]. Security considerations for the content 539 manipulated by RESTCONF can be found in the documents defining data 540 models. 542 All security considerations that apply to resources defined in 543 [I-D.ietf-netconf-restconf] also apply to the collection resource. 545 5. Acknowledgements 547 The authors would like to thank for following for lively discussions 548 on list and in the halls (ordered by last name): Rex Fernando 550 6. Normative References 552 [I-D.ietf-netconf-restconf] 553 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 554 Protocol", draft-ietf-netconf-restconf-04 (work in 555 progress), January 2015. 557 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 558 Requirement Levels", BCP 14, RFC 2119, March 1997. 560 [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. 562 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 563 January 2004. 565 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 566 Resource Identifier (URI): Generic Syntax", STD 66, RFC 567 3986, January 2005. 569 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 570 Network Configuration Protocol (NETCONF)", RFC 6020, 571 October 2010. 573 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 574 and A. Bierman, Ed., "Network Configuration Protocol 575 (NETCONF)", RFC 6241, June 2011. 577 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 578 Protocol (NETCONF) Access Control Model", RFC 6536, March 579 2012. 581 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 582 and D. Orchard, "URI Template", RFC 6570, March 2012. 584 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 585 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 586 2014. 588 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 589 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 591 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 592 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 594 Appendix A. Change Log 596 -- RFC Ed.: remove this section before publication. 598 The RESTCONF issue tracker can be found here: https://github.com/ 599 netconf-wg/restconf/issues 601 A.1. restconf-03 to restconf-collection-00 603 o Moved collection resource from RESTCONF to a new document 605 Appendix B. Open Issues 607 -- RFC Ed.: remove this section before publication. 609 The RESTCONF Collection issues are tracked on github.com: 611 https://github.com/netconf-wg/restconf/issues 613 Appendix C. RESTCONF Collection Examples 615 The examples within this document use the "example-jukebox" YANG 616 module defined in [I-D.ietf-netconf-restconf]. 618 C.1. "limit" Parameter 620 In this example, the client requests the first two "album" resources 621 for a given artist: 623 Request from client: 625 GET /restconf/data/example-jukebox:jukebox/ 626 library/artist=Foo%20Fighters/album/?limit=2 HTTP/1.1 627 Host: example.com 628 Content-Type: application/yang.collection+xml 630 Response from server: 632 HTTP/1.1 200 OK 633 Date: Mon, 23 Apr 2012 17:01:00 GMT 634 Server: example-server 635 Cache-Control: no-cache 636 Pragma: no-cache 637 Content-Type: application/yang.collection+xml 638 640 Foo Fighters 641 1995 642 ... 643 644 645 The Color and the Shape 646 1997 647 ... 648 649 651 C.2. "offset" Parameter 653 In this example, the client requests the next two albums, i.e., two 654 albums starting from two. 656 Request from client: 658 GET /restconf/data/example-jukebox:jukebox/ 659 library/artist=Foo%20Fighters/album/?limit=2&offset=2 HTTP/1.1 660 Host: example.com 661 Content-Type: application/yang.collection+json 663 Response from server: 665 HTTP/1.1 200 OK 666 Date: Mon, 23 Apr 2012 17:02:00 GMT 667 Server: example-server 668 Cache-Control: no-cache 669 Pragma: no-cache 670 Content-Type: application/yang.collection+json 672 { 673 "collection": { 674 "example-jukebox:album" : [ 675 { 676 "year" : 1999, 677 "name" : "There is Nothing Left to Loose", 678 ... 679 }, 680 { 681 "year" : 2002, 682 "name" : "One by One", 683 ... 684 } 685 ] 686 } 687 } 689 C.3. "sort" Parameter 691 [FIXME] 693 C.4. "where" Parameter 695 [FIXME] 697 C.5. "TopN" Use Case 699 [FIXME: use-case using all parameters for topN for some list] 701 Authors' Addresses 703 Andy Bierman 704 YumaWorks 706 Email: andy@yumaworks.com 708 Martin Bjorklund 709 Tail-f Systems 711 Email: mbj@tail-f.com 712 Kent Watsen 713 Juniper Networks 715 Email: kwatsen@juniper.net