draft-ietf-netconf-restconf-08.txt | draft-ietf-netconf-restconf-09.txt | |||
---|---|---|---|---|
Network Working Group A. Bierman | Network Working Group A. Bierman | |||
Internet-Draft YumaWorks | Internet-Draft YumaWorks | |||
Intended status: Standards Track M. Bjorklund | Intended status: Standards Track M. Bjorklund | |||
Expires: April 20, 2016 Tail-f Systems | Expires: June 17, 2016 Tail-f Systems | |||
K. Watsen | K. Watsen | |||
Juniper Networks | Juniper Networks | |||
October 18, 2015 | December 15, 2015 | |||
RESTCONF Protocol | RESTCONF Protocol | |||
draft-ietf-netconf-restconf-08 | draft-ietf-netconf-restconf-09 | |||
Abstract | Abstract | |||
This document describes an HTTP-based protocol that provides a | This document describes an HTTP-based protocol that provides a | |||
programmatic interface for accessing data defined in YANG, using the | programmatic interface for accessing data defined in YANG, using the | |||
datastores defined in NETCONF. | datastores defined in NETCONF. | |||
Status of This Memo | Status of This Memo | |||
This Internet-Draft is submitted in full conformance with the | This Internet-Draft is submitted in full conformance with the | |||
skipping to change at page 1, line 35 | skipping to change at page 1, line 35 | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
Drafts is at http://datatracker.ietf.org/drafts/current/. | Drafts is at http://datatracker.ietf.org/drafts/current/. | |||
Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
This Internet-Draft will expire on April 20, 2016. | This Internet-Draft will expire on June 17, 2016. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2015 IETF Trust and the persons identified as the | Copyright (c) 2015 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
(http://trustee.ietf.org/license-info) in effect on the date of | (http://trustee.ietf.org/license-info) in effect on the date of | |||
publication of this document. Please review these documents | publication of this document. Please review these documents | |||
carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
described in the Simplified BSD License. | described in the Simplified BSD License. | |||
Table of Contents | Table of Contents | |||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
1.1. Simple Subset of NETCONF Functionality . . . . . . . . . 5 | 1.1. Simple Subset of NETCONF Functionality . . . . . . . . . 5 | |||
1.2. Data Model Driven API . . . . . . . . . . . . . . . . . . 6 | 1.2. Data Model Driven API . . . . . . . . . . . . . . . . . . 6 | |||
1.3. Coexistence with NETCONF . . . . . . . . . . . . . . . . 7 | 1.3. Coexistence with NETCONF . . . . . . . . . . . . . . . . 7 | |||
1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 | 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
1.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 8 | 1.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
1.4.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 8 | 1.4.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
1.4.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 9 | 1.4.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 9 | |||
1.4.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 10 | 1.4.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
1.4.5. URI Template . . . . . . . . . . . . . . . . . . . . 11 | 1.4.5. URI Template . . . . . . . . . . . . . . . . . . . . 11 | |||
1.4.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 11 | 1.4.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 11 | |||
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 12 | 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 12 | |||
2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 12 | 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 12 | |||
2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 12 | 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 12 | |||
2.3. Certificate Validation . . . . . . . . . . . . . . . . . 12 | 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 12 | |||
2.4. Authenticated Server Identity . . . . . . . . . . . . . . 13 | 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 13 | |||
2.5. Authenticated Client Identity . . . . . . . . . . . . . . 13 | 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 13 | |||
3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 13 | 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 13 | |||
3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 14 | 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 14 | |||
3.2. RESTCONF Resource Types . . . . . . . . . . . . . . . . . 15 | 3.2. RESTCONF Resource Types . . . . . . . . . . . . . . . . . 15 | |||
3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 16 | 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 15 | |||
3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 16 | 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 16 | |||
3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 17 | 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 17 | |||
3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 17 | 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 17 | |||
3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 18 | 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 17 | |||
3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 18 | 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 18 | |||
3.5.1. Encoding Data Resource Identifiers in the Request URI 19 | 3.5.1. Encoding Data Resource Identifiers in the Request URI 19 | |||
3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 22 | 3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 22 | |||
3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 22 | 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 22 | |||
3.6.1. Encoding Operation Input Parameters . . . . . . . . . 23 | 3.6.1. Encoding Operation Input Parameters . . . . . . . . . 23 | |||
3.6.2. Encoding Operation Output Parameters . . . . . . . . 24 | 3.6.2. Encoding Operation Output Parameters . . . . . . . . 24 | |||
3.6.3. Encoding Operation Errors . . . . . . . . . . . . . . 25 | 3.6.3. Encoding Operation Errors . . . . . . . . . . . . . . 25 | |||
3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 26 | 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 26 | |||
3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 27 | 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 27 | |||
3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 27 | 3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 27 | |||
4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 27 | 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 27 | |||
4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 28 | 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 28 | 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 29 | |||
4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 | 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 | |||
4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 30 | 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 30 | 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 30 | |||
4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 31 | 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 31 | |||
4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 | 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 | |||
4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 33 | 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 33 | |||
4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 33 | 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 33 | |||
4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 34 | 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 34 | |||
4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 35 | 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 35 | |||
4.8.1. The "content" Query Parameter . . . . . . . . . . . . 36 | 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 36 | |||
4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 36 | 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 36 | |||
4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 37 | 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 37 | |||
4.8.4. The "insert" Query Parameter . . . . . . . . . . . . 38 | 4.8.4. The "insert" Query Parameter . . . . . . . . . . . . 38 | |||
4.8.5. The "point" Query Parameter . . . . . . . . . . . . . 38 | 4.8.5. The "point" Query Parameter . . . . . . . . . . . . . 39 | |||
4.8.6. The "filter" Query Parameter . . . . . . . . . . . . 39 | 4.8.6. The "filter" Query Parameter . . . . . . . . . . . . 39 | |||
4.8.7. The "start-time" Query Parameter . . . . . . . . . . 39 | 4.8.7. The "start‑time" Query Parameter . . . . . . . 40 | |||
4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 40 | 4.8.8. The "stop‑time" Query Parameter . . . . . . . . 40 | |||
4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 41 | 4.8.9. The "with‑defaults" Query Parameter . . . . . . 41 | |||
5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 42 | 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 42 | |||
5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 42 | 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 42 | |||
5.2. Message Headers . . . . . . . . . . . . . . . . . . . . . 43 | 5.2. Message Headers . . . . . . . . . . . . . . . . . . . . . 43 | |||
5.3. Message Encoding . . . . . . . . . . . . . . . . . . . . 44 | 5.3. Message Encoding . . . . . . . . . . . . . . . . . . . . 45 | |||
5.4. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 44 | 5.4. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 45 | |||
5.4.1. XML MetaData Encoding Example . . . . . . . . . . . . 45 | 5.4.1. XML MetaData Encoding Example . . . . . . . . . . . . 45 | |||
5.4.2. JSON MetaData Encoding Example . . . . . . . . . . . 45 | 5.4.2. JSON MetaData Encoding Example . . . . . . . . . . . 46 | |||
5.5. Return Status . . . . . . . . . . . . . . . . . . . . . . 46 | 5.5. Return Status . . . . . . . . . . . . . . . . . . . . . . 47 | |||
5.6. Message Caching . . . . . . . . . . . . . . . . . . . . . 46 | 5.6. Message Caching . . . . . . . . . . . . . . . . . . . . . 47 | |||
6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 47 | 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 47 | |||
6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 47 | 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 47 | |||
6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 47 | 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 48 | |||
6.3. Subscribing to Receive Notifications . . . . . . . . . . 48 | 6.3. Subscribing to Receive Notifications . . . . . . . . . . 49 | |||
6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 50 | 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 50 | |||
6.4. Receiving Event Notifications . . . . . . . . . . . . . . 50 | 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 51 | |||
7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 52 | 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 53 | |||
7.1. Error Response Message . . . . . . . . . . . . . . . . . 54 | 7.1. Error Response Message . . . . . . . . . . . . . . . . . 54 | |||
8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 56 | 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 56 | |||
9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 62 | 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 62 | |||
9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 62 | 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 62 | |||
9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 63 | 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 63 | |||
9.1.2. The "defaults" Protocol Capability URI . . . . . . . 63 | 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 64 | |||
9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 64 | 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 64 | |||
9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 64 | 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 65 | |||
10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 68 | 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 68 | |||
10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 68 | 10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 69 | |||
10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 69 | 10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 69 | |||
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 | 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 | |||
11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 69 | 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 69 | |||
11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 69 | 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 70 | |||
11.3. application/yang Media Sub Types . . . . . . . . . . . . 70 | 11.3. application/yang Media Sub Types . . . . . . . . . . . . 70 | |||
11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 71 | 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 71 | |||
12. Security Considerations . . . . . . . . . . . . . . . . . . . 71 | 12. Security Considerations . . . . . . . . . . . . . . . . . . . 72 | |||
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 72 | 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 73 | |||
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 | 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 | |||
14.1. Normative References . . . . . . . . . . . . . . . . . . 73 | 14.1. Normative References . . . . . . . . . . . . . . . . . . 73 | |||
14.2. Informative References . . . . . . . . . . . . . . . . . 76 | 14.2. Informative References . . . . . . . . . . . . . . . . . 76 | |||
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 76 | Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 76 | |||
A.1. 07 - 08 . . . . . . . . . . . . . . . . . . . . . . . . . 76 | A.1. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 76 | |||
A.2. 06 - 07 . . . . . . . . . . . . . . . . . . . . . . . . . 76 | A.2. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 76 | |||
A.3. 05 - 06 . . . . . . . . . . . . . . . . . . . . . . . . . 77 | A.3. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 77 | |||
A.4. 04 - 05 . . . . . . . . . . . . . . . . . . . . . . . . . 77 | A.4. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 77 | |||
A.5. 03 - 04 . . . . . . . . . . . . . . . . . . . . . . . . . 78 | A.5. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 77 | |||
A.6. 02 - 03 . . . . . . . . . . . . . . . . . . . . . . . . . 78 | A.6. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 78 | |||
A.7. 01 - 02 . . . . . . . . . . . . . . . . . . . . . . . . . 79 | A.7. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 79 | |||
A.8. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 80 | A.8. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 79 | |||
A.9. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 80 | A.9. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 80 | |||
A.10. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 81 | ||||
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 81 | Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 81 | |||
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 81 | Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 81 | |||
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 82 | C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 82 | |||
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 87 | Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 87 | |||
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 87 | D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 87 | |||
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 87 | D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 87 | |||
D.1.2. Retrieve The Server Module Information . . . . . . . 88 | D.1.2. Retrieve The Server Module Information . . . . . . . 88 | |||
D.1.3. Retrieve The Server Capability Information . . . . . 89 | D.1.3. Retrieve The Server Capability Information . . . . . 90 | |||
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 90 | D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 90 | |||
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 90 | D.2.1. Create New Data Resources . . . . . . . . . . . . . . 91 | |||
D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 91 | D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 92 | |||
D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 92 | D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 92 | |||
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 93 | D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 93 | |||
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 93 | D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 93 | |||
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 96 | D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 96 | |||
D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 99 | D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 99 | |||
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 100 | D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 100 | |||
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 100 | D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 100 | |||
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 101 | D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 101 | |||
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 102 | D.3.7. "start‑time" Parameter . . . . . . . . . . . . 102 | |||
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 102 | D.3.8. "stop‑time" Parameter . . . . . . . . . . . . . 102 | |||
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 102 | D.3.9. "with‑defaults" Parameter . . . . . . . . . . . 102 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 103 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 104 | |||
1. Introduction | 1. Introduction | |||
There is a need for standard mechanisms to allow Web applications to | There is a need for standard mechanisms to allow Web applications to | |||
access the configuration data, operational data, data-model specific | access the configuration data, operational data, data-model specific | |||
protocol operations, and event notifications within a networking | protocol operations, and event notifications within a networking | |||
device, in a modular and extensible manner. | device, in a modular and extensible manner. | |||
This document describes an HTTP [RFC7230] based protocol called | This document describes an HTTP [RFC7230] based protocol called | |||
RESTCONF, for accessing data defined in YANG version 1 [RFC6020] or | RESTCONF, for accessing data defined in YANG version 1 [RFC6020] or | |||
skipping to change at page 5, line 33 | skipping to change at page 5, line 28 | |||
defined data. Since NETCONF protocol operations are not relevant, | defined data. Since NETCONF protocol operations are not relevant, | |||
the user should not need any prior knowledge of NETCONF in order to | the user should not need any prior knowledge of NETCONF in order to | |||
use RESTCONF. | use RESTCONF. | |||
Configuration data and state data are exposed as resources that can | Configuration data and state data are exposed as resources that can | |||
be retrieved with the GET method. Resources representing | be retrieved with the GET method. Resources representing | |||
configuration data can be modified with the DELETE, PATCH, POST, and | configuration data can be modified with the DELETE, PATCH, POST, and | |||
PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] | PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] | |||
or JSON [RFC7158]. | or JSON [RFC7158]. | |||
Data-model specific protocol operations defined with the YANG "rpc" | Data-model specific operations defined with the YANG "rpc" or | |||
or "action" statements can be invoked with the POST method. Data- | "action" statements can be invoked with the POST method. Data-model | |||
model specific event notifications defined with the YANG | specific event notifications defined with the YANG "notification" | |||
"notification" statement can be accessed. | statement can be accessed. | |||
1.1. Simple Subset of NETCONF Functionality | 1.1. Simple Subset of NETCONF Functionality | |||
An HTTP-based management protocol does not need to mirror the | An HTTP-based management protocol does not need to mirror the | |||
functionality of the NETCONF protocol, but it needs to be compatible | functionality of the NETCONF protocol, but it needs to be compatible | |||
with NETCONF. A simplified transaction model is needed that allows | with NETCONF. A simplified transaction model is needed that allows | |||
basic CRUD operations on a hierarchy of conceptual resources. This | basic CRUD operations on a hierarchy of conceptual resources. This | |||
represents a limited subset of the transaction capabilities of the | represents a limited subset of the transaction capabilities of the | |||
NETCONF protocol. | NETCONF protocol. | |||
skipping to change at page 7, line 21 | skipping to change at page 7, line 21 | |||
data model, knowing in advance important details about the exact | data model, knowing in advance important details about the exact | |||
protocol operations and datastore content a conforming server | protocol operations and datastore content a conforming server | |||
implementation will support. | implementation will support. | |||
RESTCONF provides the YANG module capability information supported by | RESTCONF provides the YANG module capability information supported by | |||
the server, in case the client wants to use it. The URIs for custom | the server, in case the client wants to use it. The URIs for custom | |||
protocol operations and datastore content are predictable, based on | protocol operations and datastore content are predictable, based on | |||
the YANG module definitions. | the YANG module definitions. | |||
Operational experience with CLI and SNMP indicates that operators | Operational experience with CLI and SNMP indicates that operators | |||
learn the 'location' of specific service or device related data and | learn the location of specific service or device related data and do | |||
do not expect such information to be arbitrary and discovered each | not expect such information to be arbitrary and discovered each time | |||
time the client opens a management session to a server. | the client opens a management session to a server. | |||
The RESTCONF protocol operates on a conceptual datastore defined with | The RESTCONF protocol operates on a conceptual datastore defined with | |||
the YANG data modeling language. The server lists each YANG module | the YANG data modeling language. The server lists each YANG module | |||
it supports using the "ietf-yang-library" YANG module, defined in | it supports using the "ietf-yang-library" YANG module, defined in | |||
[I-D.ietf-netconf-yang-library]. The server MUST implement the | [I-D.ietf-netconf-yang-library]. The server MUST implement the | |||
"ietf-yang-library" module, which SHOULD identify all the YANG | "ietf-yang-library" module, which MUST identify all the YANG modules | |||
modules used by the server. | used by the server. | |||
The conceptual datastore contents, data-model-specific operations and | The conceptual datastore contents, data-model-specific operations and | |||
event notifications are identified by this set of YANG modules. All | event notifications are identified by this set of YANG modules. All | |||
RESTCONF content identified as either a data resource, operation | RESTCONF content identified as either a data resource, operation | |||
resource, or event stream resource is defined with the YANG language. | resource, or event stream resource is defined with the YANG language. | |||
The classification of data as configuration or non-configuration is | The classification of data as configuration or non-configuration is | |||
derived from the YANG "config" statement. Data ordering behavior is | derived from the YANG "config" statement. Data ordering behavior is | |||
derived from the YANG "ordered-by" statement. | derived from the YANG "ordered-by" statement. | |||
skipping to change at page 12, line 38 | skipping to change at page 12, line 38 | |||
of HTTP, but due to the sensitive nature of the information conveyed, | of HTTP, but due to the sensitive nature of the information conveyed, | |||
RESTCONF requires that the transport-layer protocol provides both | RESTCONF requires that the transport-layer protocol provides both | |||
data integrity and confidentiality, such as are provided by the TLS | data integrity and confidentiality, such as are provided by the TLS | |||
protocol [RFC5246]. | protocol [RFC5246]. | |||
2.2. HTTPS with X.509v3 Certificates | 2.2. HTTPS with X.509v3 Certificates | |||
Given the nearly ubiquitous support for HTTP over TLS [RFC7230], | Given the nearly ubiquitous support for HTTP over TLS [RFC7230], | |||
RESTCONF implementations MUST support the "https" URI scheme, which | RESTCONF implementations MUST support the "https" URI scheme, which | |||
has the IANA assigned default port 443. Consistent with the | has the IANA assigned default port 443. Consistent with the | |||
exclusive use of X.509v3 certificates for NETCONF over TLS | exclusive use of X.509v3 certificates for NETCONF over TLS [RFC7589], | |||
[draft-ietf-netconf-rfc5539bis-10], use of certificates in RESTCONF | use of certificates in RESTCONF is also limited to X.509v3 | |||
is also limited to X.509v3 certificates. | certificates. | |||
2.3. Certificate Validation | 2.3. Certificate Validation | |||
When presented an X.509 certificate, the RESTCONF peer MUST use X.509 | When presented an X.509 certificate, the RESTCONF peer MUST use X.509 | |||
certificate path validation [RFC5280] to verify the integrity of the | certificate path validation [RFC5280] to verify the integrity of the | |||
certificate. The presented X.509 certificate MAY also be considered | certificate. The presented X.509 certificate MAY also be considered | |||
valid if it matches a locally configured certificate fingerprint. If | valid if it matches a locally configured certificate fingerprint. If | |||
X.509 certificate path validation fails and the presented X.509 | X.509 certificate path validation fails and the presented X.509 | |||
certificate does not match a locally configured certificate | certificate does not match a locally configured certificate | |||
fingerprint, the connection MUST be terminated as defined in | fingerprint, the connection MUST be terminated as defined in | |||
skipping to change at page 13, line 16 | skipping to change at page 13, line 16 | |||
The RESTCONF client MUST carefully examine the certificate presented | The RESTCONF client MUST carefully examine the certificate presented | |||
by the RESTCONF server to determine if it meets the client's | by the RESTCONF server to determine if it meets the client's | |||
expectations. The RESTCONF client MUST check the identity of the | expectations. The RESTCONF client MUST check the identity of the | |||
server according to Section 6 of [RFC6125], including processing the | server according to Section 6 of [RFC6125], including processing the | |||
outcome as described in Section 6.6 of [RFC6125]. | outcome as described in Section 6.6 of [RFC6125]. | |||
2.5. Authenticated Client Identity | 2.5. Authenticated Client Identity | |||
The RESTCONF server MUST authenticate client access to any protected | The RESTCONF server MUST authenticate client access to any protected | |||
resource using HTTP Authentication [RFC7235]. If the RESTCONF client | resource. If the RESTCONF client is not authenticated to access a | |||
is not authenticated to access a resource, the server MUST send a | resource, the server MUST send an HTTP response with status code 401 | |||
response with status code 401 (Unauthorized) and a WWW-Authenticate | (Unauthorized), as defined in Section 3.1 of [RFC7235]. | |||
header field containing at least one challenge applicable to the | ||||
target resource. The RESTCONF server MAY advertise support for any | ||||
number of authentication schemes but, in order to ensure | ||||
interoperability, the RESTCONF server MUST advertise at least one of | ||||
the following authentication schemes: | ||||
o Basic [draft-ietf-httpauth-basicauth-update-03] | ||||
o Digest [draft-ietf-httpauth-digest-09] | ||||
o ClientCertificate [draft-thomson-httpbis-cant-01] | ||||
These authentication schemes are selected for their similarity to the | RESTCONF client authentication MUST either use TLS client | |||
authentication schemes supported by NETCONF. In particular, the | certificates, like NETCONF over TLS [RFC7589], or use a standard HTTP | |||
Basic and Digest authentication schemes both directly provide an | Authentication scheme, see Section 5.1 in [RFC7235]. A combination | |||
identity and verification of a shared secret, much like NETCONF over | of both client certificates and an HTTP Authentication scheme is also | |||
SSH, when using the SSH "password" authentication method [RFC4252]. | allowed, with the determination of how to process this combination | |||
Similarly, the ClientCertificate authentication scheme is much like | left as an implementation decision. | |||
NETCONF over TLS's use of X.509 client-certificates. When using the | ||||
ClientCertificate authentication scheme, the RESTCONF server MUST | ||||
derive the identity of the RESTCONF client using the algorithm | ||||
defined in Section 7 of [draft-ietf-netconf-rfc5539bis-10]. | ||||
The RESTCONF client identity determined from any HTTP authentication | The RESTCONF client identity derived from the authentication | |||
scheme is hereafter known as the "RESTCONF username" and subject to | mechanism used is hereafter known as the "RESTCONF username" and | |||
the NETCONF Access Control Module (NACM) [RFC6536]. | subject to the NETCONF Access Control Module (NACM) [RFC6536]. For | |||
when a client certificate is presented, this identity MUST be derived | ||||
using the algorithm defined in Section 7 of [RFC7589]. For all other | ||||
cases, when HTTP Authentication is used, the identity is provided by | ||||
the HTTP Authentication scheme used. | ||||
3. Resources | 3. Resources | |||
The RESTCONF protocol operates on a hierarchy of resources, starting | The RESTCONF protocol operates on a hierarchy of resources, starting | |||
with the top-level API resource itself (Section 3.1). Each resource | with the top-level API resource itself (Section 3.1). Each resource | |||
represents a manageable component within the device. | represents a manageable component within the device. | |||
A resource can be considered a collection of conceptual data and the | A resource can be considered a collection of conceptual data and the | |||
set of allowed methods on that data. It can contain nested child | set of allowed methods on that data. It can contain nested child | |||
resources. The child resource types and methods allowed on them are | resources. The child resource types and methods allowed on them are | |||
skipping to change at page 14, line 42 | skipping to change at page 14, line 31 | |||
In line with the best practices defined by [RFC7320], RESTCONF | In line with the best practices defined by [RFC7320], RESTCONF | |||
enables deployments to specify where the RESTCONF API is located. | enables deployments to specify where the RESTCONF API is located. | |||
When first connecting to a RESTCONF server, a RESTCONF client MUST | When first connecting to a RESTCONF server, a RESTCONF client MUST | |||
determine the root of the RESTCONF API. The client discovers this by | determine the root of the RESTCONF API. The client discovers this by | |||
getting the "/.well-known/host-meta" resource ([RFC6415]) and using | getting the "/.well-known/host-meta" resource ([RFC6415]) and using | |||
the <Link> element containing the "restconf" attribute : | the <Link> element containing the "restconf" attribute : | |||
Request | Request | |||
------- | ------- | |||
GET /.well-known/host-meta users HTTP/1.1 | GET /.well-known/host-meta HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Accept: application/xrd+xml | Accept: application/xrd+xml | |||
Response | Response | |||
-------- | -------- | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Content-Type: application/xrd+xml | Content-Type: application/xrd+xml | |||
Content-Length: nnn | Content-Length: nnn | |||
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'> | <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'> | |||
skipping to change at page 20, line 34 | skipping to change at page 20, line 24 | |||
specified in the YANG "key" statement, with a comma separating | specified in the YANG "key" statement, with a comma separating | |||
them. | them. | |||
o The key value is specified as a string, using the canonical | o The key value is specified as a string, using the canonical | |||
representation for the YANG data type. Any reserved characters | representation for the YANG data type. Any reserved characters | |||
MUST be percent-encoded, according to [RFC3986], section 2.1. | MUST be percent-encoded, according to [RFC3986], section 2.1. | |||
o All the components in the "key" statement MUST be encoded. | o All the components in the "key" statement MUST be encoded. | |||
Partial instance identifiers are not supported. | Partial instance identifiers are not supported. | |||
o Quoted strings are not allowed in the key leaf values. A missing | o A missing key value is interpreted a zero-length string. | |||
key value is interpreted a zero-length string. (example: | (example: list=foo,,baz). | |||
list=foo,,baz). | ||||
o The "list-instance" ABNF rule defined in Section 3.5.1.1 | o The "list-instance" ABNF rule defined in Section 3.5.1.1 | |||
represents the syntax of a list instance identifier. | represents the syntax of a list instance identifier. | |||
o Resource URI values returned in Location headers for data | o Resource URI values returned in Location headers for data | |||
resources MUST identify the module name, even if there are no | resources MUST identify the module name, even if there are no | |||
conflicting local names when the resource is created. This | conflicting local names when the resource is created. This | |||
ensures the correct resource will be identified even if the server | ensures the correct resource will be identified even if the server | |||
loads a new module that the old client does not know about. | loads a new module that the old client does not know about. | |||
skipping to change at page 21, line 16 | skipping to change at page 21, line 5 | |||
key "key4 key5"; | key "key4 key5"; | |||
... | ... | |||
leaf X { type string; } | leaf X { type string; } | |||
} | } | |||
} | } | |||
} | } | |||
For the above YANG definition, URI with key leaf values will be | For the above YANG definition, URI with key leaf values will be | |||
encoded as follows (line wrapped for display purposes only): | encoded as follows (line wrapped for display purposes only): | |||
/restconf/data/example-top:top/list1=key1val,key2val,key3val3/ | /restconf/data/example-top:top/list1=key1val,key2val,key3val/ | |||
list2=key4val,key5val/X | list2=key4val,key5val/X | |||
The following example shows how reserved characters are percent- | The following example shows how reserved characters are percent- | |||
encoded within a key value. The value of 'key1' contains a comma, | encoded within a key value. The value of "key1" contains a comma, | |||
single-quote, double-quote, colon, space, and forward slash. (,'": / | single-quote, double-quote, colon, double-quote, space, and forward | |||
). Note that the angle brackets ('<', '>'), and double-quote ('"') | slash. (,'":" /). Note that double-quote is not a reserved | |||
are not reserved characters and do not need to be percent-encoded. | characters and does not need to be percent-encoded. The value of | |||
"key2" is the empty string, and the value of "key3" is the string | ||||
"foo". | ||||
Example URL: | Example URL: | |||
/restconf/data/example-top:top/list2=key1/X | /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo | |||
/restconf/data/example-top:top/list2=%2C%27"%3A%20%2F/X | ||||
3.5.1.1. ABNF For Data Resource Identifiers | 3.5.1.1. ABNF For Data Resource Identifiers | |||
The "api-path" ABNF syntax is used to construct RESTCONF path | The "api-path" ABNF syntax is used to construct RESTCONF path | |||
identifiers: | identifiers: | |||
api-path = "/" | | api-path = "/" | | |||
("/" api-identifier | ("/" api-identifier | |||
0*("/" (api-identifier | list-instance ))) | 0*("/" (api-identifier | list-instance ))) | |||
skipping to change at page 29, line 33 | skipping to change at page 29, line 40 | |||
target resource, an error response containing a "403 Forbidden" or | target resource, an error response containing a "403 Forbidden" or | |||
"404 Not Found" status-line is returned to the client. | "404 Not Found" status-line is returned to the client. | |||
If the user is authorized to read some but not all of the target | If the user is authorized to read some but not all of the target | |||
resource, the unauthorized content is omitted from the response | resource, the unauthorized content is omitted from the response | |||
message-body, and the authorized content is returned to the client. | message-body, and the authorized content is returned to the client. | |||
Example: | Example: | |||
The client might request the response headers for an XML | The client might request the response headers for an XML | |||
representation of the "library" resource: | representation of the a specific "album" resource: | |||
GET /restconf/data/example-jukebox:jukebox/ | GET /restconf/data/example-jukebox:jukebox/ | |||
library/artist=Foo%20Fighters/album HTTP/1.1 | library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Accept: application/yang.data+xml | Accept: application/yang.data+xml | |||
The server might respond: | The server might respond: | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Date: Mon, 23 Apr 2012 17:02:40 GMT | Date: Mon, 23 Apr 2012 17:02:40 GMT | |||
Server: example-server | Server: example-server | |||
Content-Type: application/yang.data+xml | Content-Type: application/yang.data+xml | |||
Cache-Control: no-cache | Cache-Control: no-cache | |||
skipping to change at page 37, line 35 | skipping to change at page 38, line 5 | |||
path | path | |||
path = api-identifier [ '/' path ] | path = api-identifier [ '/' path ] | |||
"api-identifier" is defined in Section 3.5.1.1. | "api-identifier" is defined in Section 3.5.1.1. | |||
";" is used to select multiple nodes. For example, to retrieve only | ";" is used to select multiple nodes. For example, to retrieve only | |||
the "genre" and "year" of an album, use: "fields=genre;year". | the "genre" and "year" of an album, use: "fields=genre;year". | |||
Parentheses are used to specify sub-selectors of a node. | Parentheses are used to specify sub-selectors of a node. | |||
For example, assume the target resource is the 'album' list. To | For example, assume the target resource is the "album" list. To | |||
retrieve only the "label" and "catalogue-number" of the "admin" | retrieve only the "label" and "catalogue-number" of the "admin" | |||
container within an album, use: | container within an album, use: | |||
"fields=admin(label;catalogue-number)". | "fields=admin(label;catalogue-number)". | |||
"/" is used in a path to retrieve a child node of a node. For | "/" is used in a path to retrieve a child node of a node. For | |||
example, to retrieve only the "label" of an album, use: "fields=admin | example, to retrieve only the "label" of an album, use: "fields=admin | |||
/label". | /label". | |||
This parameter is only allowed for GET methods on api, datastore, and | This parameter is only allowed for GET methods on api, datastore, and | |||
data resources. A 400 Bad Request error is returned if used for | data resources. A 400 Bad Request error is returned if used for | |||
skipping to change at page 73, line 45 | skipping to change at page 74, line 14 | |||
[RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. | [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. | |||
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, | [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, | |||
January 2004. | January 2004. | |||
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | |||
Resource Identifier (URI): Generic Syntax", STD 66, RFC | Resource Identifier (URI): Generic Syntax", STD 66, RFC | |||
3986, January 2005. | 3986, January 2005. | |||
[RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) | ||||
Authentication Protocol", RFC 4252, January 2006. | ||||
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security | [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security | |||
(TLS) Protocol Version 1.2", RFC 5246, August 2008. | (TLS) Protocol Version 1.2", RFC 5246, August 2008. | |||
[RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event | [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event | |||
Notifications", RFC 5277, July 2008. | Notifications", RFC 5277, July 2008. | |||
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., | [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., | |||
Housley, R., and T. Polk, "Internet X.509 Public Key | Housley, R., and T. Polk, "Internet X.509 Public Key | |||
Infrastructure Certificate and Certificate Revocation List | Infrastructure Certificate and Certificate Revocation List | |||
(CRL) Profile", RFC 5280, May 2008. | (CRL) Profile", RFC 5280, May 2008. | |||
skipping to change at page 75, line 17 | skipping to change at page 75, line 30 | |||
[RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol | [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol | |||
(HTTP/1.1): Conditional Requests", RFC 7232, June 2014. | (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. | |||
[RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol | [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol | |||
(HTTP/1.1): Authentication", RFC 7235, June 2014. | (HTTP/1.1): Authentication", RFC 7235, June 2014. | |||
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC | [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC | |||
7320, July 2014. | 7320, July 2014. | |||
[RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the | ||||
NETCONF Protocol over Transport Layer Security (TLS) with | ||||
Mutual X.509 Authentication", RFC 7589, DOI 10.17487/ | ||||
RFC7589, June 2015, | ||||
<http://www.rfc-editor.org/info/rfc7589>. | ||||
[W3C.CR-eventsource-20121211] | [W3C.CR-eventsource-20121211] | |||
Hickson, I., "Server-Sent Events", World Wide Web | Hickson, I., "Server-Sent Events", World Wide Web | |||
Consortium CR CR-eventsource-20121211, December 2012, | Consortium CR CR-eventsource-20121211, December 2012, | |||
<http://www.w3.org/TR/2012/CR-eventsource-20121211>. | <http://www.w3.org/TR/2012/CR-eventsource-20121211>. | |||
[W3C.REC-xml-20081126] | [W3C.REC-xml-20081126] | |||
Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., | Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., | |||
and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth | and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth | |||
Edition)", World Wide Web Consortium Recommendation REC- | Edition)", World Wide Web Consortium Recommendation REC- | |||
xml-20081126, November 2008, | xml-20081126, November 2008, | |||
<http://www.w3.org/TR/2008/REC-xml-20081126>. | <http://www.w3.org/TR/2008/REC-xml-20081126>. | |||
[XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) | [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) | |||
Version 1.0", World Wide Web Consortium Recommendation | Version 1.0", World Wide Web Consortium Recommendation | |||
REC-xpath-19991116, November 1999, | REC-xpath-19991116, November 1999, | |||
<http://www.w3.org/TR/1999/REC-xpath-19991116>. | <http://www.w3.org/TR/1999/REC-xpath-19991116>. | |||
[draft-ietf-httpauth-basicauth-update-03] | ||||
Reschke, J., "The 'Basic' HTTP Authentication Scheme", | ||||
draft-ietf-httpauth-basicauth-update-03 (work in | ||||
progress), Dec 2014. | ||||
[draft-ietf-httpauth-digest-09] | ||||
Shekh-Yusef, R., Reschke, D., and S. Bremer, "HTTP Digest | ||||
Access Authentication", draft-ietf-httpauth-digest-09 | ||||
(work in progress), Dec 2014. | ||||
[draft-ietf-netconf-rfc5539bis-10] | ||||
Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the | ||||
NETCONF Protocol over Transport Layer Security (TLS) with | ||||
Mutual X.509 Authentication", draft-ietf-netconf- | ||||
rfc5539bis-10 (work in progress), Dec 2014. | ||||
[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 | 14.2. Informative References | |||
[I-D.ietf-netconf-yang-patch] | [I-D.ietf-netconf-yang-patch] | |||
Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch | Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch | |||
Media Type", draft-ietf-netconf-yang-patch-06 (work in | Media Type", draft-ietf-netconf-yang-patch-06 (work in | |||
progress), October 2015. | progress), October 2015. | |||
[rest-dissertation] | [rest-dissertation] | |||
Fielding, R., "Architectural Styles and the Design of | Fielding, R., "Architectural Styles and the Design of | |||
Network-based Software Architectures", 2000. | Network-based Software Architectures", 2000. | |||
Appendix A. Change Log | Appendix A. Change Log | |||
-- RFC Ed.: remove this section before publication. | -- RFC Ed.: remove this section before publication. | |||
The RESTCONF issue tracker can be found here: https://github.com/ | The RESTCONF issue tracker can be found here: https://github.com/ | |||
netconf-wg/restconf/issues | netconf-wg/restconf/issues | |||
A.1. 07 - 08 | A.1. v08 - v09 | |||
o fix introduction text regarding implementation requirements for | ||||
the ietf-yang-library | ||||
o clarified HTTP authentication requirements | ||||
o fix host-meta example | ||||
o changed list key encoding to clarify that quoted strings are not | ||||
allowed. Percent-encoded values are used if quotes would be | ||||
required. A missing key is treated as a zero-length string | ||||
o Fixed example of percent-encoded string to match YANG model | ||||
o Changed streams examples to align with naming already used | ||||
A.2. v07 - v08 | ||||
o add support for YANG 1.1 action statement | o add support for YANG 1.1 action statement | |||
o changed mandatory encoding from XML to XML or JSON | o changed mandatory encoding from XML to XML or JSON | |||
o fix syntax in fields parameter definition | o fix syntax in fields parameter definition | |||
o add meta-data encoding examples for XML and JSON | o add meta-data encoding examples for XML and JSON | |||
o remove RFC 2396 references and update with 3986 | o remove RFC 2396 references and update with 3986 | |||
skipping to change at page 76, line 37 | skipping to change at page 77, line 4 | |||
o add support for YANG 1.1 action statement | o add support for YANG 1.1 action statement | |||
o changed mandatory encoding from XML to XML or JSON | o changed mandatory encoding from XML to XML or JSON | |||
o fix syntax in fields parameter definition | o fix syntax in fields parameter definition | |||
o add meta-data encoding examples for XML and JSON | o add meta-data encoding examples for XML and JSON | |||
o remove RFC 2396 references and update with 3986 | o remove RFC 2396 references and update with 3986 | |||
o change encoding of a key so quoted string are not used, since they | o change encoding of a key so quoted string are not used, since they | |||
are already percent-encoded. A zero-length string is not encoded | are already percent-encoded. A zero-length string is not encoded | |||
(/list=foo,,baz) | (/list=foo,,baz) | |||
o Add example of percent-encoded key value | o Add example of percent-encoded key value | |||
A.2. 06 - 07 | A.3. v06 - v07 | |||
o fixed all issues identified in email from Jernej Tuljak in netconf | o fixed all issues identified in email from Jernej Tuljak in netconf | |||
email 2015-06-22 | email 2015-06-22 | |||
o fixed error example bug where error-urlpath was still used. | o fixed error example bug where error-urlpath was still used. | |||
Changed to error-path. | Changed to error-path. | |||
o added mention of YANG Patch and informative reference | o added mention of YANG Patch and informative reference | |||
o added support for YANG 1.1, specifically support for anydata and | o added support for YANG 1.1, specifically support for anydata and | |||
actions | actions | |||
o removed the special field value "*", since it is no longer needed | o removed the special field value "*", since it is no longer needed | |||
A.3. 05 - 06 | A.4. v05 - v06 | |||
o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) | o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) | |||
A.4. 04 - 05 | A.5. v04 - v05 | |||
o changed term 'notification event' to 'event notification' | o changed term 'notification event' to 'event notification' | |||
o removed intro text about framework and meta-model | o removed intro text about framework and meta-model | |||
o removed early mention of API resources | o removed early mention of API resources | |||
o removed term unified datastore and cleaned up text about NETCONF | o removed term unified datastore and cleaned up text about NETCONF | |||
datastores | datastores | |||
skipping to change at page 78, line 5 | skipping to change at page 78, line 17 | |||
o renamed stream/encoding/events to stream/access/location | o renamed stream/encoding/events to stream/access/location | |||
o changed XPath from informative to normative reference | o changed XPath from informative to normative reference | |||
o changed rest-dissertation from normative to informative reference | o changed rest-dissertation from normative to informative reference | |||
o changed example-jukebox playlist 'id' from a data-resource- | o changed example-jukebox playlist 'id' from a data-resource- | |||
identifier to a leafref pointing at the song name | identifier to a leafref pointing at the song name | |||
A.5. 03 - 04 | A.6. v03 - v04 | |||
o renamed 'select' to 'fields' (#1) | o renamed 'select' to 'fields' (#1) | |||
o moved collection resource and page capability to draft-ietf- | o moved collection resource and page capability to draft-ietf- | |||
netconf-restconf-collection-00 (#3) | netconf-restconf-collection-00 (#3) | |||
o added mandatory "defaults" protocol capability URI (#4) | o added mandatory "defaults" protocol capability URI (#4) | |||
o added optional "with-defaults" query parameter URI (#4) | o added optional "with-defaults" query parameter URI (#4) | |||
skipping to change at page 78, line 40 | skipping to change at page 79, line 5 | |||
o changed lock-denied error example | o changed lock-denied error example | |||
o added with-defaults query parameter example | o added with-defaults query parameter example | |||
o added term "RESTCONF Capability" | o added term "RESTCONF Capability" | |||
o changed NETCONF Capability URI registry usage to new RESTCONF | o changed NETCONF Capability URI registry usage to new RESTCONF | |||
Capability URI Registry usage | Capability URI Registry usage | |||
A.6. 02 - 03 | A.7. v02 - v03 | |||
o added collection resource | o added collection resource | |||
o added "page" query parameter capability | o added "page" query parameter capability | |||
o added "limit" and "offset" query parameters, which are available | o added "limit" and "offset" query parameters, which are available | |||
if the "page" capability is supported | if the "page" capability is supported | |||
o added "stream list" term | o added "stream list" term | |||
skipping to change at page 79, line 4 | skipping to change at page 79, line 17 | |||
o added collection resource | o added collection resource | |||
o added "page" query parameter capability | o added "page" query parameter capability | |||
o added "limit" and "offset" query parameters, which are available | o added "limit" and "offset" query parameters, which are available | |||
if the "page" capability is supported | if the "page" capability is supported | |||
o added "stream list" term | o added "stream list" term | |||
o fixed bugs in some examples | o fixed bugs in some examples | |||
o added "encoding" list within the "stream" list to allow different | o added "encoding" list within the "stream" list to allow different | |||
<events> URLs for XML and JSON encoding. | <events> URLs for XML and JSON encoding. | |||
o made XML MUST implement and JSON MAY implement for servers | o made XML MUST implement and JSON MAY implement for servers | |||
o re-add JSON notification examples (previously removed) | o re-add JSON notification examples (previously removed) | |||
o updated JSON references | o updated JSON references | |||
A.7. 01 - 02 | A.8. v01 - v02 | |||
o moved query parameter definitions from the YANG module back to the | o moved query parameter definitions from the YANG module back to the | |||
plain text sections | plain text sections | |||
o made all query parameters optional to implement | o made all query parameters optional to implement | |||
o defined query parameter capability URI | o defined query parameter capability URI | |||
o moved 'streams' to new YANG module (ietf-restconf-monitoring) | o moved 'streams' to new YANG module (ietf-restconf-monitoring) | |||
skipping to change at page 80, line 5 | skipping to change at page 80, line 16 | |||
information is no longer in this resource | information is no longer in this resource | |||
o closed issue #1 'select parameter' since no objections to the | o closed issue #1 'select parameter' since no objections to the | |||
proposed syntax | proposed syntax | |||
o closed "encoding of list keys" issue since no objection to new | o closed "encoding of list keys" issue since no objection to new | |||
encoding of list keys in a target resource URI. | encoding of list keys in a target resource URI. | |||
o moved open issues list to the issue tracker on github | o moved open issues list to the issue tracker on github | |||
A.8. 00 - 01 | A.9. v00 - v01 | |||
o fixed content=nonconfig example (non-config was incorrect) | o fixed content=nonconfig example (non-config was incorrect) | |||
o closed open issue 'message-id'. There is no need for a message-id | o closed open issue 'message-id'. There is no need for a message-id | |||
field, and RFC 2392 does not apply. | field, and RFC 2392 does not apply. | |||
o closed open issue 'server support verification'. The headers used | o closed open issue 'server support verification'. The headers used | |||
by RESTCONF are widely supported. | by RESTCONF are widely supported. | |||
o removed encoding rules from section on RESTCONF Meta-Data. This | o removed encoding rules from section on RESTCONF Meta-Data. This | |||
skipping to change at page 80, line 42 | skipping to change at page 81, line 4 | |||
o closed open issue '_self links for HATEOAS support'. It was | o closed open issue '_self links for HATEOAS support'. It was | |||
decided that they are redundant because they can be derived from | decided that they are redundant because they can be derived from | |||
the YANG module for the specific data. | the YANG module for the specific data. | |||
o added explanatory text for the 'select' parameter. | o added explanatory text for the 'select' parameter. | |||
o added RESTCONF Path Resolution section for discovering the root of | o added RESTCONF Path Resolution section for discovering the root of | |||
the RESTCONF API using the /.well-known/host-meta. | the RESTCONF API using the /.well-known/host-meta. | |||
o added an "error" media type to for structured error messages | o added an "error" media type to for structured error messages | |||
o added Secure Transport section requiring TLS | o added Secure Transport section requiring TLS | |||
o added Security Considerations section | o added Security Considerations section | |||
o removed all references to "REST-like" | o removed all references to "REST-like" | |||
A.9. bierman:restconf-04 to ietf:restconf-00 | A.10. bierman:restconf-04 to ietf:restconf-00 | |||
o updated open issues section | o updated open issues section | |||
Appendix B. Open Issues | Appendix B. Open Issues | |||
-- RFC Ed.: remove this section before publication. | -- RFC Ed.: remove this section before publication. | |||
The RESTCONF issues are tracked on github.com: | The RESTCONF issues are tracked on github.com: | |||
https://github.com/netconf-wg/restconf/issues | https://github.com/netconf-wg/restconf/issues [1] | |||
Appendix C. Example YANG Module | Appendix C. Example YANG Module | |||
The example YANG module used in this document represents a simple | The example YANG module used in this document represents a simple | |||
media jukebox interface. | media jukebox interface. | |||
YANG Tree Diagram for "example-jukebox" Module | YANG Tree Diagram for "example-jukebox" Module | |||
+--rw jukebox! | +--rw jukebox! | |||
+--rw library | +--rw library | |||
skipping to change at page 101, line 20 | skipping to change at page 101, line 27 | |||
"name" : "Rope", | "name" : "Rope", | |||
"location" : "/media/foo/a7/rope.mp3", | "location" : "/media/foo/a7/rope.mp3", | |||
"format" : "MP3", | "format" : "MP3", | |||
"length" : 259 | "length" : 259 | |||
} | } | |||
} | } | |||
Response from server: | Response from server: | |||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | |||
Date: Mon, 23 Apr 2012 13:01:20 GMT | ||||
1. Date: Mon, 23 Apr 2012 13:01:20 GMT Server: example-server Last- | Server: example-server | |||
Modified: Mon, 23 Apr 2012 13:01:20 GMT ETag: abcada438af | Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT | |||
ETag: abcada438af | ||||
D.3.6. "filter" Parameter | D.3.6. "filter" Parameter | |||
The following URIs show some examples of notification filter | The following URIs show some examples of notification filter | |||
specifications (lines wrapped for display purposes only): | specifications (lines wrapped for display purposes only): | |||
// filter = /event/event-class='fault' | // filter = /event/event-class='fault' | |||
GET /mystreams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' | GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' | |||
// filter = /event/severity<=4 | // filter = /event/severity<=4 | |||
GET /mystreams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 | GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 | |||
// filter = /linkUp|/linkDown | // filter = /linkUp|/linkDown | |||
GET /mystreams/SNMP?filter=%2FlinkUp%7C%2FlinkDown | GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown | |||
// filter = /*/reporting-entity/card!='Ethernet0' | // filter = /*/reporting-entity/card!='Ethernet0' | |||
GET /mystreams/NETCONF? | GET /streams/NETCONF? | |||
filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' | filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' | |||
// filter = /*/email-addr[contains(.,'company.com')] | // filter = /*/email-addr[contains(.,'company.com')] | |||
GET /mystreams/critical-syslog? | GET /streams/critical-syslog? | |||
filter=%2F*%2Femail-addr[contains(.%2C'company.com')] | filter=%2F*%2Femail-addr[contains(.%2C'company.com')] | |||
// Note: the module name is used as prefix. | // Note: the module name is used as prefix. | |||
// filter = (/example-mod:event1/name='joe' and | // filter = (/example-mod:event1/name='joe' and | |||
// /example-mod:event1/status='online') | // /example-mod:event1/status='online') | |||
GET /mystreams/NETCONF? | GET /streams/NETCONF? | |||
filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and | filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and | |||
%20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') | %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') | |||
// To get notifications from just two modules (e.g., m1 + m2) | ||||
// filter=(/m1:* or /m2:*) | ||||
GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*) | ||||
D.3.7. "start-time" Parameter | D.3.7. "start-time" Parameter | |||
// start-time = 2014-10-25T10:02:00Z | // start-time = 2014-10-25T10:02:00Z | |||
GET /mystreams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z | GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z | |||
D.3.8. "stop-time" Parameter | D.3.8. "stop-time" Parameter | |||
// stop-time = 2014-10-25T12:31:00Z | // stop-time = 2014-10-25T12:31:00Z | |||
GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z | GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z | |||
D.3.9. "with-defaults" Parameter | D.3.9. "with-defaults" Parameter | |||
The following YANG module is assumed for this example. | The following YANG module is assumed for this example. | |||
End of changes. 63 change blocks. | ||||
143 lines changed or deleted | 135 lines changed or added | |||
This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |