[Docs] [txt|pdf|xml] [Tracker] [WG] [Email] [Nits]

Versions: 00

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.

   <CODE BEGINS> 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:   <http://tools.ietf.org/wg/netconf/>
        WG List:  <mailto:netconf@ietf.org>

        WG Chair: Mehmet Ersue
                  <mailto:mehmet.ersue@nsn.com>

        WG Chair: Mahesh Jethanandani
                  <mailto:mjethanandani@gmail.com>

        Editor:   Andy Bierman
                  <mailto:andy@yumaworks.com>

        Editor:   Martin Bjorklund
                  <mailto:mbj@tail-f.com>

        Editor:   Kent Watsen
                  <mailto:kwatsen@juniper.net>";

     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

   }

   <CODE ENDS>

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


      <collection xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"
        <album xmlns="http://example.com/ns/example-jukebox">
          <name>Foo Fighters</name>
          <year>1995</year>
          ...
        </album>
        <album xmlns="http://example.com/ns/example-jukebox">
          <name>The Color and the Shape</name>
          <year>1997</year>
          ...
        </album>
      </collection>

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]


Html markup produced by rfcmarkup 1.127, available from https://tools.ietf.org/tools/rfcmarkup/