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/