--- 1/draft-ietf-netconf-restconf-05.txt 2015-06-20 09:16:14.158264611 -0700 +++ 2/draft-ietf-netconf-restconf-06.txt 2015-06-20 09:16:14.338268966 -0700 @@ -1,21 +1,21 @@ Network Working Group A. Bierman Internet-Draft YumaWorks Intended status: Standards Track M. Bjorklund -Expires: December 6, 2015 Tail-f Systems +Expires: December 22, 2015 Tail-f Systems K. Watsen Juniper Networks - June 4, 2015 + June 20, 2015 RESTCONF Protocol - draft-ietf-netconf-restconf-05 + draft-ietf-netconf-restconf-06 Abstract This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastores defined in NETCONF. Status of This Memo This Internet-Draft is submitted in full conformance with the @@ -24,21 +24,21 @@ 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 December 6, 2015. + This Internet-Draft will expire on December 22, 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 @@ -136,26 +136,27 @@ 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 68 11.3. application/yang Media Sub Types . . . . . . . . . . . . 69 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 70 12. Security Considerations . . . . . . . . . . . . . . . . . . . 71 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 72 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 72 14.1. Normative References . . . . . . . . . . . . . . . . . . 72 14.2. Informative References . . . . . . . . . . . . . . . . . 75 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 75 - A.1. 04 - 05 . . . . . . . . . . . . . . . . . . . . . . . . . 75 - A.2. 03 - 04 . . . . . . . . . . . . . . . . . . . . . . . . . 76 - A.3. 02 - 03 . . . . . . . . . . . . . . . . . . . . . . . . . 77 - A.4. 01 - 02 . . . . . . . . . . . . . . . . . . . . . . . . . 77 - A.5. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 78 - A.6. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 79 + A.1. 05 - 06 . . . . . . . . . . . . . . . . . . . . . . . . . 75 + A.2. 04 - 05 . . . . . . . . . . . . . . . . . . . . . . . . . 75 + A.3. 03 - 04 . . . . . . . . . . . . . . . . . . . . . . . . . 76 + A.4. 02 - 03 . . . . . . . . . . . . . . . . . . . . . . . . . 77 + A.5. 01 - 02 . . . . . . . . . . . . . . . . . . . . . . . . . 77 + A.6. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 78 + A.7. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 79 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 79 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 79 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 80 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 85 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 86 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 86 D.1.2. Retrieve The Server Module Information . . . . . . . 87 D.1.3. Retrieve The Server Capability Information . . . . . 88 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 89 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 89 @@ -2036,21 +2037,21 @@ 5.4. RESTCONF Meta-Data The RESTCONF protocol needs to retrieve the same meta-data that is used in the NETCONF protocol. Information about default leafs, last- modified timestamps, etc. are commonly used to annotate representations of the datastore contents. This meta-data is not defined in the YANG schema because it applies to the datastore, and is common across all data nodes. This information is encoded as attributes in XML. JSON encoding of - meta-data is defined in [I-D.lhotka-netmod-yang-metadata]. + meta-data is defined in [I-D.ietf-netmod-yang-metadata]. 5.5. Return Status Each message represents some sort of resource access. An HTTP "status-line" header line is returned for each request. If a 4xx or 5xx range status code is returned in the status-line, then the error information will be returned in the response, according to the format defined in Section 7.1. 5.6. Message Caching @@ -2174,21 +2175,21 @@ Server Sent Events [W3C.CR-eventsource-20121211] transport strategy. The server MAY support query parameters for a GET method on this resource. These parameters are specific to each notification stream. For example: The client might send the following request: GET /restconf/data/ietf-restconf-monitoring:restconf-state/ - streams/stream=NETCONF/encoding=xml/location HTTP/1.1 + streams/stream=NETCONF/access=xml/location HTTP/1.1 Host: example.com Accept: application/yang.data+xml The server might send the following response: HTTP/1.1 200 OK Content-Type: application/yang.api+xml @@ -2556,21 +2557,21 @@ 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-05.txt + // Note: extracted from draft-ietf-netconf-restconf-06.txt // RFC Ed.: update the date below with the date of RFC publication // and remove this note. revision 2015-06-04 { description "Initial revision."; reference "RFC XXXX: RESTCONF Protocol."; } @@ -2903,21 +2904,21 @@ The "ietf-restconf-monitoring" module defines monitoring information for the RESTCONF protocol. The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] are used by this module for some type definitions. RFC Ed.: update the date below with the date of RFC publication and remove this note. - file "ietf-restconf-monitoring@2015-06-04.yang" + file "ietf-restconf-monitoring@2015-06-19.yang" module ietf-restconf-monitoring { namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; prefix "rcmon"; import ietf-yang-types { prefix yang; } import ietf-inet-types { prefix inet; } organization "IETF NETCONF (Network Configuration) Working Group"; @@ -2954,25 +2955,25 @@ 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-05.txt + // Note: extracted from draft-ietf-netconf-restconf-06.txt // RFC Ed.: update the date below with the date of RFC publication // and remove this note. - revision 2015-06-04 { + revision 2015-06-19 { description "Initial revision."; reference "RFC XXXX: RESTCONF Protocol."; } container restconf-state { config false; description "Contains RESTCONF protocol monitoring information."; @@ -3031,21 +3032,21 @@ type yang:date-and-time; description "Indicates the time the replay log for this stream was created."; reference "RFC 5277, Section 3.4, element."; } list access { - key type; + key encoding; min-elements 1; description "The server will create an entry in this list for each encoding format that is supported for this stream. The media type 'application/yang.stream' is expected for all event streams. This list identifies the sub-types supported for this stream."; leaf encoding { type string; @@ -3284,27 +3285,27 @@ 14.1. Normative References [I-D.ietf-netconf-yang-library] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module Library", draft-ietf-netconf-yang-library-00 (work in progress), January 2015. [I-D.ietf-netmod-yang-json] Lhotka, L., "JSON Encoding of Data Modeled with YANG", - draft-ietf-netmod-yang-json-02 (work in progress), - November 2014. + draft-ietf-netmod-yang-json-03 (work in progress), + February 2015. - [I-D.lhotka-netmod-yang-metadata] + [I-D.ietf-netmod-yang-metadata] Lhotka, L., "Defining and Using Metadata with YANG", - draft-lhotka-netmod-yang-metadata-01 (work in progress), - February 2015. + draft-ietf-netmod-yang-metadata-00 (work in progress), + April 2015. [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, November 1996. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, @@ -3422,41 +3423,45 @@ [draft-thomson-httpbis-cant-01] Thomson, M., "Client Authentication over New TLS Connection", draft-thomson-httpbis-cant-01 (work in progress), Jul 2014. 14.2. Informative References [I-D.ietf-netconf-yang-patch] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch - Media Type", draft-ietf-netconf-yang-patch-03 (work in - progress), January 2015. + Media Type", draft-ietf-netconf-yang-patch-04 (work in + progress), June 2015. [rest-dissertation] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", 2000. 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. 04 - 05 +A.1. 05 - 06 + + o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) + +A.2. 04 - 05 o changed term 'notification event' to 'event notification' o removed intro text about framework and meta-model - o removed early mention of API resources + o removed term unified datastore and cleaned up text about NETCONF datastores o removed text about not immediate persistence of edits o removed RESTCONF-specific data-resource-identifier typedef and its usage o clarified encoding of key leafs @@ -3472,21 +3477,21 @@ o renamed stream/encoding/events to stream/access/location o changed XPath from informative to normative reference o changed rest-dissertation from normative to informative reference o changed example-jukebox playlist 'id' from a data-resource- identifier to a leafref pointing at the song name -A.2. 03 - 04 +A.3. 03 - 04 o renamed 'select' to 'fields' (#1) o moved collection resource and page capability to draft-ietf- netconf-restconf-collection-00 (#3) o added mandatory "defaults" protocol capability URI (#4) o added optional "with-defaults" query parameter URI (#4) @@ -3507,21 +3512,21 @@ o changed lock-denied error example o added with-defaults query parameter example o added term "RESTCONF Capability" o changed NETCONF Capability URI registry usage to new RESTCONF Capability URI Registry usage -A.3. 02 - 03 +A.4. 02 - 03 o added collection resource o added "page" query parameter capability o added "limit" and "offset" query parameters, which are available if the "page" capability is supported o added "stream list" term @@ -3529,30 +3534,30 @@ o added "encoding" list within the "stream" list to allow different URLs for XML and JSON encoding. o made XML MUST implement and JSON MAY implement for servers o re-add JSON notification examples (previously removed) o updated JSON references -A.4. 01 - 02 +A.5. 01 - 02 o moved query parameter definitions from the YANG module back to the plain text sections o made all query parameters optional to implement - o defined query parameter capability URI o moved 'streams' to new YANG module (ietf-restconf-monitoring) + o added 'capabilities' container to new YANG module (ietf-restconf- monitoring) o moved 'modules' container to new YANG module (ietf-yang-library) o added new leaf 'module-set-id' (ietf-yang-library) o added new leaf 'conformance' (ietf-yang-library) o changed 'schema' leaf to type inet:uri that returns the location @@ -3566,21 +3571,21 @@ information is no longer in this resource o closed issue #1 'select parameter' since no objections to the proposed syntax o closed "encoding of list keys" issue since no objection to new encoding of list keys in a target resource URI. o moved open issues list to the issue tracker on github -A.5. 00 - 01 +A.6. 00 - 01 o fixed content=nonconfig example (non-config was incorrect) o closed open issue 'message-id'. There is no need for a message-id field, and RFC 2392 does not apply. o closed open issue 'server support verification'. The headers used by RESTCONF are widely supported. o removed encoding rules from section on RESTCONF Meta-Data. This @@ -3610,21 +3615,21 @@ the RESTCONF API using the /.well-known/host-meta. o added an "error" media type to for structured error messages o added Secure Transport section requiring TLS o added Security Considerations section o removed all references to "REST-like" -A.6. bierman:restconf-04 to ietf:restconf-00 +A.7. bierman:restconf-04 to ietf:restconf-00 o updated open issues section Appendix B. Open Issues -- RFC Ed.: remove this section before publication. The RESTCONF issues are tracked on github.com: https://github.com/netconf-wg/restconf/issues @@ -4401,28 +4406,28 @@ }, "playlist" : [ { "name" : "Foo-One", "description" : "example playlist 1", "song" : [ { "index" : 1, "id" : "https://example.com/restconf/data/ example-jukebox:jukebox/library/artist= - Foo%20Fighters/album/Wasting%20Light/ - song/Rope" + Foo%20Fighters/album=Wasting%20Light/ + song=Rope" }, { "index" : 2, "id" : "https://example.com/restconf/data/ example-jukebox:jukebox/library/artist= - Foo%20Fighters/album/Wasting%20Light/song/ + Foo%20Fighters/album=Wasting%20Light/song= Bridge%20Burning" } ] } ], "player" : { "gap" : 0.5 } } } @@ -4508,21 +4513,21 @@ { "name" : "example-jukebox", "revision" : "2015-06-04" }, { "name" : "ietf-inet-types", "revision" : "2013-07-15" }, { "name" : "ietf-restconf-monitoring", - "revision" : "2015-06-04" + "revision" : "2015-06-19" }, { "name" : "ietf-yang-library", "revision" : "2015-01-30" }, { "name" : "ietf-yang-types", "revision" : "2013-07-15" } @@ -4539,21 +4544,21 @@ POST /restconf/data/example-jukebox:jukebox/ playlist=Foo-One?insert=first HTTP/1.1 Host: example.com Content-Type: application/yang.data+json { "example-jukebox:song" : { "index" : 1, "id" : "/example-jukebox:jukebox/library/ - artist=Foo%20Fighters/album/Wasting%20Light/song/Rope" + artist=Foo%20Fighters/album=Wasting%20Light/song=Rope" } } Response from server: HTTP/1.1 201 Created Date: Mon, 23 Apr 2012 13:01:20 GMT Server: example-server Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT Location: https://example.com/restconf/data/ @@ -4562,21 +4567,21 @@ D.3.5. "point" Parameter In this example, the client is inserting a new "song" resource within an "album" resource after another song. The request URI is split for display purposes only. Request from client: POST /restconf/data/example-jukebox:jukebox/ - library/artist=Foo%20Fighters/album/Wasting%20Light? + library/artist=Foo%20Fighters/album=Wasting%20Light? insert=after&point=%2Fexample-jukebox%3Ajukebox%2F library%2Fartist%2FFoo%20Fighters%2Falbum%2F Wasting%20Light%2Fsong%2FBridge%20Burning HTTP/1.1 Host: example.com Content-Type: application/yang.data+json { "example-jukebox:song" : { "name" : "Rope", "location" : "/media/foo/a7/rope.mp3",