Network Working Group A. Bierman Internet-Draft YumaWorks Intended status: Standards Track M. Bjorklund Expires: August 3, 2015 Tail-f Systems K. Watsen Juniper Networks January 30, 2015 RESTCONF Collection Resource draft-ietf-netconf-restconf-collection-00 Abstract This document describes a collection resource for the RESTCONF protocol to provide enhanced filtering features for the retrieval of data nodes with the GET method. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on August 3, 2015. Copyright Notice Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of Bierman, et al. Expires August 3, 2015 [Page 1] Internet-Draft RESTCONF Collection January 2015 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1.4. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 5 1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1.6. URI Template . . . . . . . . . . . . . . . . . . . . 6 1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 6 1.2. Collection Resource Type . . . . . . . . . . . . . . . . 6 1.3. Collection Resource . . . . . . . . . . . . . . . . . . . 6 1.4. Query Parameters . . . . . . . . . . . . . . . . . . . . 7 1.4.1. Query Parameter URIs . . . . . . . . . . . . . . . . 7 1.4.2. The "limit" Query Parameter . . . . . . . . . . . . . 8 1.4.3. The "offset" Query Parameter . . . . . . . . . . . . 8 1.4.4. The "sort" Query Parameter . . . . . . . . . . . . . 8 1.4.5. The "where" Query Parameter . . . . . . . . . . . . . 8 2. RESTCONF Collection module . . . . . . . . . . . . . . . . . 9 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 3.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 11 3.2. application/yang Media Sub Types . . . . . . . . . . . . 11 3.3. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 12 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 6. Normative References . . . . . . . . . . . . . . . . . . . . 13 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 14 A.1. restconf-03 to restconf-collection-00 . . . . . . . . . . 14 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 14 Appendix C. RESTCONF Collection Examples . . . . . . . . . . . . 14 C.1. "limit" Parameter . . . . . . . . . . . . . . . . . . . . 14 C.2. "offset" Parameter . . . . . . . . . . . . . . . . . . . 15 C.3. "sort" Parameter . . . . . . . . . . . . . . . . . . . . 16 C.4. "where" Parameter . . . . . . . . . . . . . . . . . . . . 16 C.5. "TopN" Use Case . . . . . . . . . . . . . . . . . . . . . 16 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 1. Introduction There is a need for standard mechanisms to control the filtering, sorting, and retrieval of data from RESTCONF devices. A server may contain many instances of a particular YANG list. Retrieval of the entire list at once can be extremely inefficient. Bierman, et al. Expires August 3, 2015 [Page 2] Internet-Draft RESTCONF Collection January 2015 Pagination mechanisms are needed to allow a client to iterate through a large list, in a manner that is most efficient for the application. This document describes a "collection" resource that can be used to control retrieval of data nodes from a RESTCONF server. [FIXME: describe basic needs - target resource picks the list - 'fields' is a node-set XPath expression to pick the subtrees within the target resource to return - 'where' is a boolean XPath expression to pick which list instances are selected for return - 'sort' is ??? parameter to sort the selected list instances - 'limit' is the max number of list instances returned - 'offset' is the XPath position() of the list instance ??? pre or post access control ??? ??? if post, then what if NACM changes while client retrieving ] Collection resources represent search results through the server data. Data that the client is not authorized to receive according to the access control parameters configured in [RFC6536] MUST NOT be returned in RESTCONF response messages. 1.1. Terminology The keywords "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, [RFC2119]. [FIXME: remove terms that are not used] 1.1.1. NETCONF The following terms are defined in [RFC6241]: o candidate configuration datastore o client o configuration data o datastore o configuration datastore Bierman, et al. Expires August 3, 2015 [Page 3] Internet-Draft RESTCONF Collection January 2015 o protocol operation o running configuration datastore o server o startup configuration datastore o state data o user 1.1.2. HTTP The following terms are defined in [RFC3986]: o fragment o path o query The following terms are defined in [RFC7230]: o header o message-body o Request-Line o request URI The following terms are defined in [RFC7231]: o method o request o resource The following terms are defined in [RFC7232]: o entity tag Bierman, et al. Expires August 3, 2015 [Page 4] Internet-Draft RESTCONF Collection January 2015 1.1.3. YANG The following terms are defined in [RFC6020]: o container o data node o key leaf o leaf o leaf-list o list o presence container (or P-container) o RPC operation (now called protocol operation) o non-presence container (or NP-container) o ordered-by system o ordered-by user 1.1.4. RESTCONF The following terms are defined in [I-D.ietf-netconf-restconf]: o data resource o target resource o retrieval request 1.1.5. Terms The following terms are used within this document: o collection resource: a resource with the media type "application/ yang.collection+xml" or "application/yang.collection+json". Contains a set of data resources. Bierman, et al. Expires August 3, 2015 [Page 5] Internet-Draft RESTCONF Collection January 2015 1.1.6. URI Template Throughout this document, the URI template [RFC6570] syntax "{+restconf}" is used to refer to the RESTCONF API entry point outside of an example. See the root resource discovery serction defined in [I-D.ietf-netconf-restconf] for details. All of the examples in this document assume "/restconf" as the discovered RESTCONF API root path. 1.1.7. Tree Diagrams A simplified graphical representation of the data model is used in this document. The meaning of the symbols in these diagrams is as follows: o Brackets "[" and "]" enclose list keys. o Abbreviations before data node names: "rw" means configuration data (read-write) and "ro" state data (read-only). o Symbols after data node names: "?" means an optional node, "!" means a presence container, and "*" denotes a list and leaf-list. o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":"). o Ellipsis ("...") stands for contents of subtrees that are not shown. 1.2. Collection Resource Type The following resource type are defined in this document: +------------+-----------------------------+ | Resource | Media Type | +------------+-----------------------------+ | Collection | application/yang.collection | +------------+-----------------------------+ RESTCONF Media Types 1.3. Collection Resource A collection resource contains a set of data resources. It is used to represent a all instances or a subset of all instances in a YANG list or leaf-list. Bierman, et al. Expires August 3, 2015 [Page 6] Internet-Draft RESTCONF Collection January 2015 A collection resource can be retrieved with the GET method, optionally with the query parameters "limit" (Section 1.4.2) and "offset" (Section 1.4.3). The "ietf-restconf-collection" YANG module contains the "application/ yang.collection" restconf-media-type extension which specifies the syntax and semantics of a "collection" media type. 1.4. Query Parameters Each RESTCONF operation allows zero or more query parameters to be present in the request URI. The following query parameters are defined for RESTCONF collection resources. +--------+---------+------------------------------------------------+ | Name | Methods | Description | +--------+---------+------------------------------------------------+ | limit | GET | Number of entries to return for collection | | | | resources | | offset | GET | Starting point for collection resources | | sort | GET | Sorting criteria for collection resources | | where | GET | Boolean filter to select data instances for a | | | | collection resource | +--------+---------+------------------------------------------------+ RESTCONF Query Parameters Query parameters can be given in any order. Each parameter can appear at most once in a request URI. A default value may apply if the parameter is missing. Refer to Appendix C 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. 1.4.1. Query Parameter URIs A new set of RESTCONF Capability URNs are defined to identify the specific query parameters supported by the server. Bierman, et al. Expires August 3, 2015 [Page 7] Internet-Draft RESTCONF Collection January 2015 +------+----------------------------------------------------+ | Name | URI | +------+----------------------------------------------------+ | page | urn:ietf:params:restconf:capability:page:1.0 | | page | urn:ietf:params:restconf:capability:page-xpath:1.0 | +------+----------------------------------------------------+ RESTCONF Query Parameter URIs 1.4.2. The "limit" Query Parameter The "limit" parameter is used to restrict the number of data resources to return in response to GET requests on collection resources. The value of the "limit" parameter is either an integer greater than or equal to 1, or the string "unbounded". The string "unbounded" is the default value. If the server includes the "page" query parameter URI in the "capability" leaf-list in the "ietf-restconf-monitoring" module defined in [I-D.ietf-netconf-restconf], then the "limit" query parameter MUST be supported. 1.4.3. The "offset" Query Parameter The "offset" parameter is used to specify the first data resource to return in response to GET requests on collection resources. Resources instances are numbered with consecutive integers from 1 to the number of resource instances. The value of the "offset" parameter is an integer greater than or equal to 1. The default value is 1. If the server includes the "page" query parameter URI in the "capability" leaf-list in "ietf-restconf-monitoring" module defined in [I-D.ietf-netconf-restconf], then the "offset" query parameter MUST be supported. 1.4.4. The "sort" Query Parameter [FIXME] 1.4.5. The "where" Query Parameter [FIXME] Bierman, et al. Expires August 3, 2015 [Page 8] Internet-Draft RESTCONF Collection January 2015 2. RESTCONF Collection module The "ietf-restconf-collection" module defines conceptual definitions within groupings, which are not meant to be implemented as datastore contents by a server. The "ietf-restconf" module from [I-D.ietf-netconf-restconf] is used by this module for the 'restconf-media-type' extension definition. RFC Ed.: update the date below with the date of RFC publication and remove this note. file "ietf-restconf-collection@2015-01-30.yang" module ietf-restconf-collection { namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-collection"; prefix "rcoll"; import ietf-restconf { prefix rc; revision-date 2015-01-30; } organization "IETF NETCONF (Network Configuration) Working Group"; contact "WG Web: WG List: WG Chair: Mehmet Ersue WG Chair: Mahesh Jethanandani Editor: Andy Bierman Editor: Martin Bjorklund Editor: Kent Watsen "; description "This module contains conceptual YANG specifications for the RESTCONF Collection resource type. Bierman, et al. Expires August 3, 2015 [Page 9] Internet-Draft RESTCONF Collection January 2015 Note that the YANG definitions within this module do not represent configuration data of any kind. The YANG grouping statements provide a normative syntax for XML and JSON message encoding purposes. Copyright (c) 2015 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices."; // RFC Ed.: replace XXXX with actual RFC number and remove this // note. // RFC Ed.: remove this note // Note: extracted from // draft-ietf-netconf-restconf-collection-00.txt // RFC Ed.: update the date below with the date of RFC publication // and remove this note. revision 2015-01-30 { description "Initial revision."; reference "RFC XXXX: RESTCONF Collection Resource."; } rc:restconf-media-type "application/yang.collection" { uses collection; } grouping collection { description "Conceptual container representing the application/yang.collection resource type."; container collection { description "Container representing the application/yang.collection resource type."; } Bierman, et al. Expires August 3, 2015 [Page 10] Internet-Draft RESTCONF Collection January 2015 } // grouping collection } 3. IANA Considerations 3.1. YANG Module Registry This document registers three URIs in the IETF XML registry [RFC3688]. Following the format in RFC 3688, the following registration is requested to be made. URI: urn:ietf:params:xml:ns:yang:ietf-restconf-collection Registrant Contact: The NETMOD WG of the IETF. XML: N/A, the requested URI is an XML namespace. This document registers three YANG modules in the YANG Module Names registry [RFC6020]. name: ietf-restconf-collection namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-collection prefix: rcoll // RFC Ed.: replace XXXX with RFC number and remove this note reference: RFC XXXX 3.2. application/yang Media Sub Types The parent MIME media type for RESTCONF resources is application/ yang, which is defined in [RFC6020]. This document defines the following sub-types for this media type. Bierman, et al. Expires August 3, 2015 [Page 11] Internet-Draft RESTCONF Collection January 2015 - collection Type name: application Subtype name: yang.xxx Required parameters: TBD Optional parameters: TBD Encoding considerations: TBD Security considerations: TBD Interoperability considerations: TBD // RFC Ed.: replace XXXX with RFC number and remove this note Published specification: RFC XXXX 3.3. NETCONF Capability URNs This document registers two capability identifiers in "RESTCONF Protocol Capability URNs" registry Index Capability Identifier ------------------------ :page urn:ietf:params:restconf:capability:page:1.0 :page-xpath urn:ietf:params:restconf:capability:page-xpath:1.0 4. Security Considerations This section provides security considerations for the resources defined by the RESTCONF protocol. Security considerations for HTTPS are defined in [RFC2818]. Security considerations for the content manipulated by RESTCONF can be found in the documents defining data models. All security considerations that apply to resources defined in [I-D.ietf-netconf-restconf] also apply to the collection resource. Bierman, et al. Expires August 3, 2015 [Page 12] Internet-Draft RESTCONF Collection January 2015 5. Acknowledgements The authors would like to thank for following for lively discussions on list and in the halls (ordered by last name): Rex Fernando 6. Normative References [I-D.ietf-netconf-restconf] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", draft-ietf-netconf-restconf-04 (work in progress), January 2015. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, October 2010. [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, June 2011. [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration Protocol (NETCONF) Access Control Model", RFC 6536, March 2012. [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012. [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2014. [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. Bierman, et al. Expires August 3, 2015 [Page 13] Internet-Draft RESTCONF Collection January 2015 Appendix A. Change Log -- RFC Ed.: remove this section before publication. The RESTCONF issue tracker can be found here: https://github.com/ netconf-wg/restconf/issues A.1. restconf-03 to restconf-collection-00 o Moved collection resource from RESTCONF to a new document Appendix B. Open Issues -- RFC Ed.: remove this section before publication. The RESTCONF Collection issues are tracked on github.com: https://github.com/netconf-wg/restconf/issues Appendix C. RESTCONF Collection Examples The examples within this document use the "example-jukebox" YANG module defined in [I-D.ietf-netconf-restconf]. C.1. "limit" Parameter In this example, the client requests the first two "album" resources for a given artist: Request from client: GET /restconf/data/example-jukebox:jukebox/ library/artist=Foo%20Fighters/album/?limit=2 HTTP/1.1 Host: example.com Content-Type: application/yang.collection+xml Response from server: HTTP/1.1 200 OK Date: Mon, 23 Apr 2012 17:01:00 GMT Server: example-server Cache-Control: no-cache Pragma: no-cache Content-Type: application/yang.collection+xml Bierman, et al. Expires August 3, 2015 [Page 14] Internet-Draft RESTCONF Collection January 2015 Foo Fighters 1995 ... The Color and the Shape 1997 ... C.2. "offset" Parameter In this example, the client requests the next two albums, i.e., two albums starting from two. Request from client: GET /restconf/data/example-jukebox:jukebox/ library/artist=Foo%20Fighters/album/?limit=2&offset=2 HTTP/1.1 Host: example.com Content-Type: application/yang.collection+json Response from server: Bierman, et al. Expires August 3, 2015 [Page 15] Internet-Draft RESTCONF Collection January 2015 HTTP/1.1 200 OK Date: Mon, 23 Apr 2012 17:02:00 GMT Server: example-server Cache-Control: no-cache Pragma: no-cache Content-Type: application/yang.collection+json { "collection": { "example-jukebox:album" : [ { "year" : 1999, "name" : "There is Nothing Left to Loose", ... }, { "year" : 2002, "name" : "One by One", ... } ] } } C.3. "sort" Parameter [FIXME] C.4. "where" Parameter [FIXME] C.5. "TopN" Use Case [FIXME: use-case using all parameters for topN for some list] Authors' Addresses Andy Bierman YumaWorks Email: andy@yumaworks.com Martin Bjorklund Tail-f Systems Email: mbj@tail-f.com Bierman, et al. Expires August 3, 2015 [Page 16] Internet-Draft RESTCONF Collection January 2015 Kent Watsen Juniper Networks Email: kwatsen@juniper.net Bierman, et al. Expires August 3, 2015 [Page 17]