draft-ietf-netconf-restconf-16.txt   draft-ietf-netconf-restconf-17.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: February 16, 2017 Tail-f Systems Expires: April 1, 2017 Tail-f Systems
K. Watsen K. Watsen
Juniper Networks Juniper Networks
August 15, 2016 September 28, 2016
RESTCONF Protocol RESTCONF Protocol
draft-ietf-netconf-restconf-16 draft-ietf-netconf-restconf-17
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
datastore concepts defined in NETCONF. datastore concepts 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 February 16, 2017. This Internet-Draft will expire on April 1, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 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
skipping to change at page 2, line 19 skipping to change at page 2, line 19
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.4. NETCONF Notifications . . . . . . . . . . . . . . . . 7 1.1.4. NETCONF Notifications . . . . . . . . . . . . . . . . 7
1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 8 1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 8
1.1.6. URI Template and Examples . . . . . . . . . . . . . . 10 1.1.6. URI Template and Examples . . . . . . . . . . . . . . 10
1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10 1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10
1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 11 1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 11
1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 12 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 11
1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 13 1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 12
1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 14 1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 13
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 15 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 15
2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 15 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 15
2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 15 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 15
2.3. Certificate Validation . . . . . . . . . . . . . . . . . 15 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 15
2.4. Authenticated Server Identity . . . . . . . . . . . . . . 16 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 15
2.5. Authenticated Client Identity . . . . . . . . . . . . . . 16 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 16
3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 17 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 17
3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 19 3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 19
3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 19 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 19
3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 20 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 20
3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 20 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 20
3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 21 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 21
3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 21 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 21
3.4.1. Edit Collision Prevention . . . . . . . . . . . . . . 22 3.4.1. Edit Collision Prevention . . . . . . . . . . . . . . 22
skipping to change at page 2, line 49 skipping to change at page 2, line 49
3.5.2. Entity-Tag . . . . . . . . . . . . . . . . . . . . . 24 3.5.2. Entity-Tag . . . . . . . . . . . . . . . . . . . . . 24
3.5.3. Encoding Data Resource Identifiers in the Request URI 24 3.5.3. Encoding Data Resource Identifiers in the Request URI 24
3.5.4. Default Handling . . . . . . . . . . . . . . . . . . 28 3.5.4. Default Handling . . . . . . . . . . . . . . . . . . 28
3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 29 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 29
3.6.1. Encoding Operation Resource Input Parameters . . . . 30 3.6.1. Encoding Operation Resource Input Parameters . . . . 30
3.6.2. Encoding Operation Resource Output Parameters . . . . 34 3.6.2. Encoding Operation Resource Output Parameters . . . . 34
3.6.3. Encoding Operation Resource Errors . . . . . . . . . 36 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 36
3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 37 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 37
3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 38 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 38
3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 39 3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 39
4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 39 4. RESTCONF Methods . . . . . . . . . . . . . . . . . . . . . . 39
4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 40 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 40 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 42 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 43 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 42
4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 44 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 44
4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 47 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 47 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 47
4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 48 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 49 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 49
4.8.1. The "content" Query Parameter . . . . . . . . . . . . 50 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 50
4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 51 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 51
4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 52 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 51
4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 53 4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 52
4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 53 4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 53
4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 54 4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 54
4.8.7. The "start-time" Query Parameter . . . . . . . . . . 55 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 54
4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 55 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 55
4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 56 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 55
5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 57 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 57 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 57
5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 59 5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 58
5.3. RESTCONF Metadata . . . . . . . . . . . . . . . . . . . . 60 5.3. RESTCONF Metadata . . . . . . . . . . . . . . . . . . . . 59
5.3.1. XML Metadata Encoding Example . . . . . . . . . . . . 60 5.3.1. XML Metadata Encoding Example . . . . . . . . . . . . 60
5.3.2. JSON Metadata Encoding Example . . . . . . . . . . . 60 5.3.2. JSON Metadata Encoding Example . . . . . . . . . . . 60
5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 61 5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 61
5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 61 5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 61
6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 62 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 62
6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 62 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 62
6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 62 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 62
6.3. Subscribing to Receive Notifications . . . . . . . . . . 64 6.3. Subscribing to Receive Notifications . . . . . . . . . . 64
6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 65 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 65
6.4. Receiving Event Notifications . . . . . . . . . . . . . . 65 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 65
skipping to change at page 3, line 51 skipping to change at page 3, line 51
9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 78 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 78
9.1.2. The "defaults" Protocol Capability URI . . . . . . . 78 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 78
9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 79 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 79
9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 79 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 79
10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 83 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 83
10.1. modules-state/module . . . . . . . . . . . . . . . . . . 83 10.1. modules-state/module . . . . . . . . . . . . . . . . . . 83
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 83 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 83
11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 84 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 84
11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 84 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 84
11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 85 11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 85
11.3.1. Media Type application/yang-data-xml . . . . . . . . 85 11.3.1. Media Type application/yang-data+xml . . . . . . . . 85
11.3.2. Media Type application/yang-data+json . . . . . . . 86 11.3.2. Media Type application/yang-data+json . . . . . . . 86
11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 88 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 88
12. Security Considerations . . . . . . . . . . . . . . . . . . . 89 12. Security Considerations . . . . . . . . . . . . . . . . . . . 89
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 90 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 90
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 91 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 90
14.1. Normative References . . . . . . . . . . . . . . . . . . 91 14.1. Normative References . . . . . . . . . . . . . . . . . . 90
14.2. Informative References . . . . . . . . . . . . . . . . . 94 14.2. Informative References . . . . . . . . . . . . . . . . . 93
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 94 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 93
A.1. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . 94 A.1. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . 93
A.2. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . 94 A.2. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . 94
A.3. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 95 A.3. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . 94
A.4. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 97 A.4. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 95
A.5. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 97 A.5. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 96
A.6. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 97 A.6. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 97
A.7. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 98 A.7. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 97
A.8. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 100 A.8. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 98
A.9. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 100 A.9. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 100
A.10. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 101 A.10. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 100
A.11. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 101 A.11. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 100
A.12. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 101 A.12. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 101
A.13. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 102 A.13. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 101
A.14. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 103 A.14. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 102
A.15. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 103 A.15. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 102
A.16. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 104 A.16. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 103
A.17. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 105 A.17. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 104
A.18. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 105
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 105 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 105
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 105 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 105
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 106 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 106
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 111 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 111
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 112 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 111
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 112 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 111
D.1.2. Retrieve The Server Module Information . . . . . . . 113 D.1.2. Retrieve The Server Module Information . . . . . . . 112
D.1.3. Retrieve The Server Capability Information . . . . . 115 D.1.3. Retrieve The Server Capability Information . . . . . 114
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 116 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 115
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 116 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 115
D.2.2. Detect Resource Entity-Tag Change . . . . . . . . . . 118 D.2.2. Detect Resource Entity-Tag Change . . . . . . . . . . 117
D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 118 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 117
D.2.4. Edit a Data Resource . . . . . . . . . . . . . . . . 119 D.2.4. Edit a Data Resource . . . . . . . . . . . . . . . . 118
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 120 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 118
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 120 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 119
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 123 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 122
D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 126 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 125
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 127 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 126
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 128 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 127
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 129 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 128
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 130 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 129
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 130 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 129
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 131 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 130
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 131
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 132
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, state data, data-model-specific RPC access the configuration data, state data, data-model-specific RPC
operations, and event notifications within a networking device, in a operations, and event notifications within a networking device, in a
modular and extensible manner. modular and extensible manner.
This document defines an HTTP [RFC7230] based protocol called This document defines an HTTP [RFC7230] based protocol called
RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or
YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using the datastore YANG version 1.1 [RFC7950], using the datastore concepts defined in
concepts defined in NETCONF [RFC6241]. NETCONF [RFC6241].
NETCONF defines configuration datastores and a set of Create, NETCONF defines configuration datastores and a set of Create,
Retrieve, Update, Delete (CRUD) operations that can be used to access Retrieve, Update, Delete (CRUD) operations that can be used to access
these datastores. NETCONF also defines a protocol for invoking these these datastores. NETCONF also defines a protocol for invoking these
operations. The YANG language defines the syntax and semantics of operations. The YANG language defines the syntax and semantics of
datastore content, configuration, state data, RPC operations, and datastore content, configuration, state data, RPC operations, and
event notifications. event notifications.
RESTCONF uses HTTP methods to provide CRUD operations on a conceptual RESTCONF uses HTTP methods to provide CRUD operations on a conceptual
datastore containing YANG-defined data, which is compatible with a datastore containing YANG-defined data, which is compatible with a
skipping to change at page 7, line 18 skipping to change at page 7, line 18
o request o request
o resource o resource
The following terms are defined in [RFC7232]: The following terms are defined in [RFC7232]:
o entity-tag o entity-tag
1.1.3. YANG 1.1.3. YANG
The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: The following terms are defined in [RFC7950]:
o action o action
o container o container
o data node o data node
o key leaf o key leaf
o leaf o leaf
skipping to change at page 9, line 16 skipping to change at page 9, line 16
operation, that is defined with a YANG "rpc" or "action" operation, that is defined with a YANG "rpc" or "action"
statement. It is invoked with the POST method. statement. It is invoked with the POST method.
o patch: a PATCH method on the target datastore or data resource. o patch: a PATCH method on the target datastore or data resource.
The media type of the message-body content will identify the patch The media type of the message-body content will identify the patch
type in use. type in use.
o plain patch: a specific media type for use with the PATCH method, o plain patch: a specific media type for use with the PATCH method,
defined in Section 4.6.1, that can be used for simple merge defined in Section 4.6.1, that can be used for simple merge
operations. It is specified by a request Content-Type of operations. It is specified by a request Content-Type of
"application/yang-data-xml" or "application/yang-data+json". "application/yang-data+xml" or "application/yang-data+json".
o query parameter: a parameter (and its value if any), encoded o query parameter: a parameter (and its value if any), encoded
within the query component of the request URI. within the query component of the request URI.
o resource type: one of the RESTCONF resource classes defined in o resource type: one of the RESTCONF resource classes defined in
this document. One of "api", "datastore", "data", "operation", this document. One of "api", "datastore", "data", "operation",
"schema", or "event stream". "schema", or "event stream".
o RESTCONF capability: An optional RESTCONF protocol feature o RESTCONF capability: An optional RESTCONF protocol feature
supported by the server, which is identified by an IANA registered supported by the server, which is identified by an IANA registered
skipping to change at page 10, line 22 skipping to change at page 10, line 22
are not intended to be implemented as part of a configuration are not intended to be implemented as part of a configuration
datastore or as operational state within the server, so normal datastore or as operational state within the server, so normal
YANG data definition statements cannot be used. YANG data definition statements cannot be used.
o YANG data template: a schema for modeling protocol message o YANG data template: a schema for modeling protocol message
components as conceptual data structure using YANG. This allows components as conceptual data structure using YANG. This allows
the messages to be defined in an encoding-independent manner. the messages to be defined in an encoding-independent manner.
Each YANG data template is defined with the "yang-data" extension, Each YANG data template is defined with the "yang-data" extension,
found in Section 8. Representations of instances conforming to a found in Section 8. Representations of instances conforming to a
particular YANG data template can be defined for YANG. The XML particular YANG data template can be defined for YANG. The XML
representation is defined in YANG version 1.1 representation is defined in YANG version 1.1 [RFC7950], and
[I-D.ietf-netmod-rfc6020bis], and supported with the "application/ supported with the "application/yang-data+xml" media type. The
yang-data-xml" media type. The JSON representation is defined in JSON representation is defined in JSON Encoding of Data Modeled
JSON Encoding of Data Modeled with YANG with YANG [RFC7951], and supported with the "application/
[I-D.ietf-netmod-yang-json], and supported with the "application/
yang-data+json" media type. yang-data+json" media type.
1.1.6. URI Template and Examples 1.1.6. URI Template and Examples
Throughout this document, the URI template [RFC6570] syntax Throughout this document, the URI template [RFC6570] syntax
"{+restconf}" is used to refer to the RESTCONF root resource outside "{+restconf}" is used to refer to the RESTCONF root resource outside
of an example. See Section 3.1 for details. of an example. See Section 3.1 for details.
For simplicity, all of the examples in this document use "/restconf" For simplicity, all of the examples in this document use "/restconf"
as the discovered RESTCONF API root path. Many of the examples as the discovered RESTCONF API root path. Many of the examples
skipping to change at page 11, line 42 skipping to change at page 11, line 42
The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data
resources represented by YANG data models. These basic edit resources represented by YANG data models. These basic edit
operations allow the running configuration to be altered by a operations allow the running configuration to be altered by a
RESTCONF client. RESTCONF client.
RESTCONF is not intended to replace NETCONF, but rather provide an RESTCONF is not intended to replace NETCONF, but rather provide an
HTTP interface that follows Representational State Transfer (REST) HTTP interface that follows Representational State Transfer (REST)
principles [rest-dissertation], and is compatible with the NETCONF principles [rest-dissertation], and is compatible with the NETCONF
datastore model. datastore model.
The following figure shows the system components if a RESTCONF server
is co-located with a NETCONF server:
+-----------+ +-----------------+
| Web app | <-------> | |
+-----------+ RESTCONF | network device |
| |
+-----------+ | +-----------+ |
| NETCONF | <-------> | | datastore | |
| Client | NETCONF | | | |
+-----------+ | +-----------+ |
+-----------------+
The following figure shows the system components if a RESTCONF server
is implemented in a device that does not have a NETCONF server:
+-----------+ +-----------------+
| Web app | <-------> | |
+-----------+ RESTCONF | network device |
| |
+-----------------+
Note that there are no interactions at all between the NETCONF
protocol and RESTCONF protocol. It is possible that locks are in use
on a RESTCONF server, even though RESTCONF cannot manipulate locks.
In such a case, the RESTCONF protocol will not be granted write
access to data resources within a datastore.
1.3. Data Model Driven API 1.3. Data Model Driven API
RESTCONF combines the simplicity of the HTTP protocol with the RESTCONF combines the simplicity of the HTTP protocol with the
predictability and automation potential of a schema-driven API. predictability and automation potential of a schema-driven API.
Knowing the YANG modules used by the server, a client can derive all Knowing the YANG modules used by the server, a client can derive all
management resource URLs and the proper structure of all RESTCONF management resource URLs and the proper structure of all RESTCONF
requests and responses. This strategy obviates the need for requests and responses. This strategy obviates the need for
responses provided by the server to contain Hypermedia as the Engine responses provided by the server to contain Hypermedia as the Engine
of Application State (HATEOAS) links, originally described in Roy of Application State (HATEOAS) links, originally described in Roy
Fielding's doctoral dissertation [rest-dissertation], because the Fielding's doctoral dissertation [rest-dissertation], because the
skipping to change at page 13, line 29 skipping to change at page 12, line 40
The RESTCONF datastore editing model is simple and direct, similar to The RESTCONF datastore editing model is simple and direct, similar to
the behavior of the :writable-running capability in NETCONF. Each the behavior of the :writable-running capability in NETCONF. Each
RESTCONF edit of a data resource within the datastore resource is RESTCONF edit of a data resource within the datastore resource is
activated upon successful completion of the edit. activated upon successful completion of the edit.
1.4. Coexistence with NETCONF 1.4. Coexistence with NETCONF
RESTCONF can be implemented on a device that supports the NETCONF RESTCONF can be implemented on a device that supports the NETCONF
protocol. protocol.
The following figure shows the system components if a RESTCONF server
is co-located with a NETCONF server:
+-----------+ +-----------------+
| Web app | <-------> | |
+-----------+ RESTCONF | network device |
| |
+-----------+ | +-----------+ |
| NETCONF | <-------> | | datastore | |
| Client | NETCONF | | | |
+-----------+ | +-----------+ |
+-----------------+
The following figure shows the system components if a RESTCONF server
is implemented in a device that does not have a NETCONF server:
+-----------+ +-----------------+
| Web app | <-------> | |
+-----------+ RESTCONF | network device |
| |
+-----------------+
Note that there are no interactions at all between the NETCONF
protocol and RESTCONF protocol. It is possible that locks are in use
on a RESTCONF server, even though RESTCONF cannot manipulate locks.
In such a case, the RESTCONF protocol will not be granted write
access to data resources within a datastore.
If the NETCONF server supports :writable-running, all edits to If the NETCONF server supports :writable-running, all edits to
configuration nodes in {+restconf}/data are performed in the running configuration nodes in {+restconf}/data are performed in the running
configuration datastore. The URI template "{+restconf}" is defined configuration datastore. The URI template "{+restconf}" is defined
in Section 1.1.6. in Section 1.1.6.
Otherwise, if the device supports :candidate, all edits to Otherwise, if the device supports :candidate, all edits to
configuration nodes in {+restconf}/data are performed in the configuration nodes in {+restconf}/data are performed in the
candidate configuration datastore. The candidate MUST be candidate configuration datastore. The candidate MUST be
automatically committed to running immediately after each successful automatically committed to running immediately after each successful
edit. Any edits from other sources that are in the candidate edit. Any edits from other sources that are in the candidate
skipping to change at page 15, line 27 skipping to change at page 15, line 17
2.1. Integrity and Confidentiality 2.1. Integrity and Confidentiality
HTTP [RFC7230] is an application layer protocol that may be layered HTTP [RFC7230] is an application layer protocol that may be layered
on any reliable transport-layer protocol. RESTCONF is defined on top on any reliable transport-layer protocol. RESTCONF is defined on top
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. A RESTCONF server MUST support data integrity and confidentiality. A RESTCONF server MUST support
the TLS protocol [RFC5246]. The RESTCONF protocol MUST NOT be used the TLS protocol [RFC5246]. The RESTCONF protocol MUST NOT be used
over HTTP without using the TLS protocol. over HTTP without using the TLS protocol.
HTTP/2 [RFC7540] MAY be used for RESTCONF. The server MUST respond RESTCONF does not require a specific version of HTTP. However, it is
using a single HTTP/2 stream for all client requests from a stream. RECOMMENDED that at least HTTP/1.1 [RFC7230] be supported by all
The server MAY respond using same HTTP/2 stream that was used for the implementations.
corresponding request.
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. has the IANA assigned default port 443.
RESTCONF servers MUST present an X.509v3 based certificate when RESTCONF servers MUST present an X.509v3 based certificate when
establishing a TLS connection with a RESTCONF client. The use of establishing a TLS connection with a RESTCONF client. The use of
X.509v3 based certificates is consistent with NETCONF over TLS X.509v3 based certificates is consistent with NETCONF over TLS
skipping to change at page 19, line 19 skipping to change at page 19, line 14
3.2. RESTCONF Media Types 3.2. RESTCONF Media Types
The RESTCONF protocol defines two application specific media types to The RESTCONF protocol defines two application specific media types to
identify representations of data which conforms to the schema for a identify representations of data which conforms to the schema for a
particular YANG construct. particular YANG construct.
This document defines media types for XML and JSON serialization of This document defines media types for XML and JSON serialization of
YANG data. Other documents MAY define other media types for YANG data. Other documents MAY define other media types for
different serializations of YANG data. The "application/ different serializations of YANG data. The "application/
yang-data-xml" media-type is defined in Section 11.3.1. The yang-data+xml" media-type is defined in Section 11.3.1. The
"application/yang-data+json" media-type is defined in Section 11.3.2. "application/yang-data+json" media-type is defined in Section 11.3.2.
3.3. API Resource 3.3. API Resource
The API resource contains the RESTCONF root resource for the RESTCONF The API resource contains the RESTCONF root resource for the RESTCONF
datastore and operation resources. It is the top-level resource datastore and operation resources. It is the top-level resource
located at {+restconf} and has the media type "application/ located at {+restconf} and has the media type "application/
yang-data-xml" or "application/yang-data+json". yang-data+xml" or "application/yang-data+json".
YANG Tree Diagram for an API Resource: YANG Tree Diagram for an API Resource:
+---- {+restconf} +---- {+restconf}
+---- data +---- data
| ... | ...
+---- operations? +---- operations?
| ... | ...
+--ro yang-library-version string +--ro yang-library-version string
skipping to change at page 20, line 31 skipping to change at page 20, line 31
Example: Example:
This example request by the client would retrieve only the non- This example request by the client would retrieve only the non-
configuration data nodes that exist within the "library" resource, configuration data nodes that exist within the "library" resource,
using the "content" query parameter (see Section 4.8.1). using the "content" query parameter (see Section 4.8.1).
GET /restconf/data/example-jukebox:jukebox/library\ GET /restconf/data/example-jukebox:jukebox/library\
?content=nonconfig HTTP/1.1 ?content=nonconfig 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 2016 17:01:30 GMT Date: Mon, 23 Apr 2016 17:01:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<library xmlns="https://example.com/ns/example-jukebox"> <library xmlns="https://example.com/ns/example-jukebox">
<artist-count>42</artist-count> <artist-count>42</artist-count>
<album-count>59</album-count> <album-count>59</album-count>
<song-count>374</song-count> <song-count>374</song-count>
</library> </library>
3.3.2. {+restconf}/operations 3.3.2. {+restconf}/operations
This optional resource is a container that provides access to the This optional resource is a container that provides access to the
skipping to change at page 21, line 26 skipping to change at page 21, line 26
This mandatory leaf identifies the revision date of the This mandatory leaf identifies the revision date of the
"ietf-yang-library" YANG module that is implemented by this server. "ietf-yang-library" YANG module that is implemented by this server.
Note that the revision date for the module version found in [RFC7895] Note that the revision date for the module version found in [RFC7895]
is used. is used.
Example: Example:
GET /restconf/yang-library-version HTTP/1.1 GET /restconf/yang-library-version 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 2016 17:01:30 GMT Date: Mon, 23 Apr 2016 17:01:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<yang-library-version <yang-library-version
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">\ xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">\
2016-06-21\ 2016-06-21\
</yang-library-version> </yang-library-version>
3.4. Datastore Resource 3.4. Datastore Resource
The "{+restconf}/data" subtree represents the datastore resource, The "{+restconf}/data" subtree represents the datastore resource,
which is a collection of configuration data and state data nodes. which is a collection of configuration data and state data nodes.
The fragment field in the request URI has no defined purpose if the
target resource is a datastore resource.
This resource type is an abstraction of the system's underlying This resource type is an abstraction of the system's underlying
datastore implementation. The client uses it to edit and retrieve datastore implementation. The client uses it to edit and retrieve
data resources, as the conceptual root of all configuration and state data resources, as the conceptual root of all configuration and state
data that is present on the device. data that is present on the device.
Configuration edit transaction management and configuration Configuration edit transaction management and configuration
persistence are handled by the server and not controlled by the persistence are handled by the server and not controlled by the
client. A datastore resource can be written directly with the POST client. A datastore resource can be written directly with the POST
and PATCH methods. Each RESTCONF edit of a datastore resource is and PATCH methods. Each RESTCONF edit of a datastore resource is
skipping to change at page 22, line 24 skipping to change at page 22, line 21
subtree is retrieved, then the datastore and its contents are subtree is retrieved, then the datastore and its contents are
returned by the server. The datastore is represented by a node named returned by the server. The datastore is represented by a node named
"data" in the "ietf-restconf" module namespace. "data" in the "ietf-restconf" module namespace.
3.4.1. Edit Collision Prevention 3.4.1. Edit Collision Prevention
Two edit collision detection and prevention mechanisms are provided Two edit collision detection and prevention mechanisms are provided
in RESTCONF for the datastore resource: a timestamp and an entity- in RESTCONF for the datastore resource: a timestamp and an entity-
tag. Any change to configuration data resources updates the tag. Any change to configuration data resources updates the
timestamp and entity tag of the datastore resource. In addition, the timestamp and entity tag of the datastore resource. In addition, the
RESTCONF server will return an error if the datastore is locked by an RESTCONF server MUST return an error if the datastore is locked by an
external source (e.g., NETCONF server). external source (e.g., NETCONF server).
3.4.1.1. Timestamp 3.4.1.1. Timestamp
The last change time is maintained and the "Last-Modified" The last change time is maintained and the "Last-Modified"
([RFC7232], Section 2.2) header field is returned in the response for ([RFC7232], Section 2.2) header field is returned in the response for
a retrieval request. The "If-Unmodified-Since" header field a retrieval request. The "If-Unmodified-Since" header field
([RFC7232], Section 3.4) can be used in edit operation requests to ([RFC7232], Section 3.4) can be used in edit operation requests to
cause the server to reject the request if the resource has been cause the server to reject the request if the resource has been
modified since the specified timestamp. modified since the specified timestamp.
skipping to change at page 23, line 47 skipping to change at page 23, line 46
targeted by the request-line of an HTTP method. Containers, leafs, targeted by the request-line of an HTTP method. Containers, leafs,
leaf-list entries, list entries, anydata and anyxml nodes are data leaf-list entries, list entries, anydata and anyxml nodes are data
resources. resources.
The representation maintained for each data resource is the YANG The representation maintained for each data resource is the YANG
defined subtree for that node. HTTP methods on a data resource defined subtree for that node. HTTP methods on a data resource
affect both the targeted data node and all its descendants, if any. affect both the targeted data node and all its descendants, if any.
A data resource can be retrieved with the GET method. Data resources A data resource can be retrieved with the GET method. Data resources
are accessed via the "{+restconf}/data" URI. This sub-tree is used are accessed via the "{+restconf}/data" URI. This sub-tree is used
to retrieve and edit data resources. The fragment field in the to retrieve and edit data resources.
request URI has no defined purpose if the target resource is a data
resource.
3.5.1. Timestamp 3.5.1. Timestamp
For configuration data resources, the server MAY maintain a last- For configuration data resources, the server MAY maintain a last-
modified timestamp for the resource, and return the "Last-Modified" modified timestamp for the resource, and return the "Last-Modified"
header field when it is retrieved with the GET or HEAD methods. header field when it is retrieved with the GET or HEAD methods.
The "Last-Modified" header field can be used by a RESTCONF client in The "Last-Modified" header field can be used by a RESTCONF client in
subsequent requests, within the "If-Modified-Since" and subsequent requests, within the "If-Modified-Since" and
"If-Unmodified-Since" header fields. "If-Unmodified-Since" header fields.
skipping to change at page 27, line 16 skipping to change at page 27, line 16
list2=key4,key5/X list2=key4,key5/X
For the above YANG definition, a target resource URI for leaf-list For the above YANG definition, a target resource URI for leaf-list
"Y" would be encoded as follows: "Y" would be encoded as follows:
/restconf/data/example-top:top/Y=instance-value /restconf/data/example-top:top/Y=instance-value
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, double-quote, space, and forward single-quote, double-quote, colon, double-quote, space, and forward
slash. (,'":" /). Note that double-quote is not a reserved slash. (,'":" /). Note that double-quote is not a reserved character
characters and does not need to be percent-encoded. The value of and does not need to be percent-encoded. The value of "key2" is the
"key2" is the empty string, and the value of "key3" is the string empty string, and the value of "key3" is the string "foo".
"foo".
Example URL: Example URL:
/restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo
3.5.3.1. ABNF For Data Resource Identifiers 3.5.3.1. ABNF For Data Resource Identifiers
The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to
construct RESTCONF path identifiers. Note that this syntax is used construct RESTCONF path identifiers. Note that this syntax is used
for all resources, and the API path starts with the RESTCONF root for all resources, and the API path starts with the RESTCONF root
resource. Data resources are required to be identified under the resource. Data resources are required to be identified under the
subtree "+{restconf}/data". subtree "+{restconf}/data".
An identifier is not allowed to start with the case-insensitive An identifier is not allowed to start with the case-insensitive
string "XML", according to YANG identifier rules. The syntax for string "XML", according to YANG identifier rules. The syntax for
"api-identifier" and "key-value" MUST conform to the JSON identifier "api-identifier" and "key-value" MUST conform to the JSON identifier
encoding rules in Section 4 of [I-D.ietf-netmod-yang-json]: The encoding rules in Section 4 of [RFC7951]: The RESTCONF root resource
RESTCONF root resource path is required. Additional sub-resource path is required. Additional sub-resource identifiers are optional.
identifiers are optional. The characters in a key value string are The characters in a key value string are constrained, and some
constrained, and some characters need to be percent-encoded, as characters need to be percent-encoded, as described in Section 3.5.3.
described in Section 3.5.3.
api-path = root ["/" (api-identifier | list-instance)]* api-path = root ["/" (api-identifier | list-instance)]*
root = string ;; replacement string for {+restconf} root = string ;; replacement string for {+restconf}
api-identifier = [module-name ":"] identifier api-identifier = [module-name ":"] identifier
module-name = identifier module-name = identifier
list-instance = api-identifier "=" key-value ["," key-value]* list-instance = api-identifier "=" key-value ["," key-value]*
key-value = string ;; constrained chars are percent-encoded key-value = string ;; constrained chars are percent-encoded
string = <a quoted or unquoted string> string = <an unquoted string>
;; An identifier MUST NOT start with ;; An identifier MUST NOT start with
;; (('X'|'x') ('M'|'m') ('L'|'l')) ;; (('X'|'x') ('M'|'m') ('L'|'l'))
identifier = (ALPHA / "_") identifier = (ALPHA / "_")
*(ALPHA / DIGIT / "_" / "-" / ".") *(ALPHA / DIGIT / "_" / "-" / ".")
3.5.4. Default Handling 3.5.4. Default Handling
RESTCONF requires that a server report its default handling mode (see RESTCONF requires that a server report its default handling mode (see
Section 9.1.2 for details). If the optional "with-defaults" query Section 9.1.2 for details). If the optional "with-defaults" query
skipping to change at page 29, line 10 skipping to change at page 29, line 10
for the child resources that have not been given value yet, the for the child resources that have not been given value yet, the
server MAY return the default values that are in use by the server, server MAY return the default values that are in use by the server,
in accordance with its reported default handing mode and query in accordance with its reported default handing mode and query
parameters passed by the client. parameters passed by the client.
3.6. Operation Resource 3.6. Operation Resource
An operation resource represents an RPC operation defined with the An operation resource represents an RPC operation defined with the
YANG "rpc" statement or a data-model-specific action defined with a YANG "rpc" statement or a data-model-specific action defined with a
YANG "action" statement. It is invoked using a POST method on the YANG "action" statement. It is invoked using a POST method on the
operation resource. The fragment field in the request URI has no operation resource.
defined purpose if the target resource is an operation resource.
An RPC operation is invoked as: An RPC operation is invoked as:
POST {+restconf}/operations/<operation> POST {+restconf}/operations/<operation>
The <operation> field identifies the module name and rpc identifier The <operation> field identifies the module name and rpc identifier
string for the desired operation. string for the desired operation.
For example, if "module-A" defined a "reset" rpc operation, then For example, if "module-A" defined a "reset" rpc operation, then
invoking the operation would be requested as follows: invoking the operation would be requested as follows:
skipping to change at page 33, line 10 skipping to change at page 33, line 10
} }
RPC Input Example: RPC Input Example:
The client might send the following POST request message to invoke The client might send the following POST request message to invoke
the "reboot" RPC operation: the "reboot" RPC operation:
POST /restconf/operations/example-ops:reboot HTTP/1.1 POST /restconf/operations/example-ops:reboot HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<input xmlns="https://example.com/ns/example-ops"> <input xmlns="https://example.com/ns/example-ops">
<delay>600</delay> <delay>600</delay>
<message>Going down for system maintenance</message> <message>Going down for system maintenance</message>
<language>en-US</language> <language>en-US</language>
</input> </input>
The server might respond: The server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
skipping to change at page 33, line 46 skipping to change at page 33, line 46
} }
Action Input Example: Action Input Example:
The client might send the following POST request message to invoke The client might send the following POST request message to invoke
the "reset" action: the "reset" action:
POST /restconf/data/example-actions:interfaces/\ POST /restconf/data/example-actions:interfaces/\
interface=eth0/reset HTTP/1.1 interface=eth0/reset HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<input xmlns="https://example.com/ns/example-actions"> <input xmlns="https://example.com/ns/example-actions">
<delay>600</delay> <delay>600</delay>
</input> </input>
The server might respond: The server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 25 Apr 2016 11:01:00 GMT Date: Mon, 25 Apr 2016 11:01:00 GMT
Server: example-server Server: example-server
skipping to change at page 35, line 32 skipping to change at page 35, line 32
"message" : "Going down for system maintenance", "message" : "Going down for system maintenance",
"language" : "en-US" "language" : "en-US"
} }
} }
The same response is shown here using XML encoding: The same response is shown here using XML encoding:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 25 Apr 2016 11:10:30 GMT Date: Mon, 25 Apr 2016 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<output xmlns="https://example.com/ns/example-ops"> <output xmlns="https://example.com/ns/example-ops">
<reboot-time>30</reboot-time> <reboot-time>30</reboot-time>
<message>Going down for system maintenance</message> <message>Going down for system maintenance</message>
<language>en-US</language> <language>en-US</language>
</output> </output>
Action Output Example: Action Output Example:
The "example-actions" YANG module defined in Section 3.6.1 is used The "example-actions" YANG module defined in Section 3.6.1 is used
skipping to change at page 36, line 35 skipping to change at page 36, line 35
invoked but errors occur, then a message-body MUST be sent by the invoked but errors occur, then a message-body MUST be sent by the
server, containing an "errors" resource, as defined in Section 3.9. server, containing an "errors" resource, as defined in Section 3.9.
A detailed example of an operation resource error response can be A detailed example of an operation resource error response can be
found in Section 3.6.3. found in Section 3.6.3.
Using the "reboot" RPC operation from the example in Section 3.6.1, Using the "reboot" RPC operation from the example in Section 3.6.1,
the client might send the following POST request message: the client might send the following POST request message:
POST /restconf/operations/example-ops:reboot HTTP/1.1 POST /restconf/operations/example-ops:reboot HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<input xmlns="https://example.com/ns/example-ops"> <input xmlns="https://example.com/ns/example-ops">
<delay>-33</delay> <delay>-33</delay>
<message>Going down for system maintenance</message> <message>Going down for system maintenance</message>
<language>en-US</language> <language>en-US</language>
</input> </input>
The server might respond with an "invalid-value" error: The server might respond with an "invalid-value" error:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Date: Mon, 25 Apr 2016 11:10:30 GMT Date: Mon, 25 Apr 2016 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error> <error>
<error-type>protocol</error-type> <error-type>protocol</error-type>
<error-tag>invalid-value</error-tag> <error-tag>invalid-value</error-tag>
<error-path xmlns:ops="https://example.com/ns/example-ops"> <error-path xmlns:ops="https://example.com/ns/example-ops">
/ops:input/ops:delay /ops:input/ops:delay
</error-path> </error-path>
<error-message>Invalid input parameter</error-message> <error-message>Invalid input parameter</error-message>
</error> </error>
</errors> </errors>
skipping to change at page 39, line 8 skipping to change at page 38, line 50
An "event stream" resource represents a source for system generated An "event stream" resource represents a source for system generated
event notifications. Each stream is created and modified by the event notifications. Each stream is created and modified by the
server only. A client can retrieve a stream resource or initiate a server only. A client can retrieve a stream resource or initiate a
long-poll server sent event stream, using the procedure specified in long-poll server sent event stream, using the procedure specified in
Section 6.3. Section 6.3.
An event stream functions according to the NETCONF Notifications An event stream functions according to the NETCONF Notifications
specification [RFC5277]. The available streams can be retrieved from specification [RFC5277]. The available streams can be retrieved from
the stream list, which specifies the syntax and semantics of the the stream list, which specifies the syntax and semantics of the
stream resources. The fragment field in the request URI has no stream resources.
defined purpose if the target resource is an event stream resource.
3.9. Errors YANG Data Template 3.9. Errors YANG Data Template
The "errors" YANG data template models a collection of error The "errors" YANG data template models a collection of error
information that is sent as the message-body in a server response information that is sent as the message-body in a server response
message, if an error occurs while processing a request message. It message, if an error occurs while processing a request message. It
is not considered as a resource type because no instances can be is not considered as a resource type because no instances can be
retrieved with a GET request. retrieved with a GET request.
The "ietf-restconf" YANG module contains the "yang-errors" YANG data The "ietf-restconf" YANG module contains the "yang-errors" YANG data
template, that specifies the syntax and semantics of an "errors" template, that specifies the syntax and semantics of an "errors"
container within a RESTCONF response. RESTCONF error handling container within a RESTCONF response. RESTCONF error handling
behavior is defined in Section 7. behavior is defined in Section 7.
4. Operations 4. RESTCONF Methods
The RESTCONF protocol uses HTTP methods to identify the CRUD The RESTCONF protocol uses HTTP methods to identify the CRUD
operations requested for a particular resource. operations requested for a particular resource.
The following table shows how the RESTCONF operations relate to The following table shows how the RESTCONF operations relate to
NETCONF protocol operations and for the NETCONF <edit-config> NETCONF protocol operations and for the NETCONF <edit-config>
operation, the "nc:operation" attribute. operation, the "nc:operation" attribute.
+----------+-----------------------------------------------+ +----------+-----------------------------------------------+
| RESTCONF | NETCONF | | RESTCONF | NETCONF |
skipping to change at page 42, line 17 skipping to change at page 42, line 8
detection via the Last-Modified or ETag values. detection via the Last-Modified or ETag values.
Example: Example:
The client might request the response header fields for an XML The client might request the response header fields for an XML
representation of the a specific "album" 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=Wasting%20Light 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 2016 17:02:40 GMT Date: Mon, 23 Apr 2016 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
ETag: "a74eefc993a2b" ETag: "a74eefc993a2b"
Last-Modified: Mon, 23 Apr 2016 11:02:14 GMT Last-Modified: Mon, 23 Apr 2016 11:02:14 GMT
<album xmlns="http://example.com/ns/example-jukebox" <album xmlns="http://example.com/ns/example-jukebox"
xmlns:jbox="http://example.com/ns/example-jukebox"> xmlns:jbox="http://example.com/ns/example-jukebox">
<name>Wasting Light</name> <name>Wasting Light</name>
<genre>jbox:alternative</genre> <genre>jbox:alternative</genre>
<year>2011</year> <year>2011</year>
</album> </album>
Refer to Appendix D.1 for more resource retrieval examples.
4.4. POST 4.4. POST
The RESTCONF server MUST support the POST method. The POST method is The RESTCONF server MUST support the POST method. The POST method is
sent by the client to create a data resource or invoke an operation sent by the client to create a data resource or invoke an operation
resource. The server uses the target resource type to determine how resource. The server uses the target resource type to determine how
to process the request. to process the request.
+-----------+------------------------------------------------+ +-----------+------------------------------------------------+
| Type | Description | | Type | Description |
+-----------+------------------------------------------------+ +-----------+------------------------------------------------+
skipping to change at page 47, line 8 skipping to change at page 46, line 33
Date: Mon, 23 Apr 2016 17:04:00 GMT Date: Mon, 23 Apr 2016 17:04:00 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2016 17:04:00 GMT Last-Modified: Mon, 23 Apr 2016 17:04:00 GMT
ETag: "b27480aeda4c" ETag: "b27480aeda4c"
The same request is shown here using XML encoding: The same request is shown here using XML encoding:
PUT /restconf/data/example-jukebox:jukebox/\ PUT /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<album xmlns="http://example.com/ns/example-jukebox" <album xmlns="http://example.com/ns/example-jukebox"
xmlns:jbox="http://example.com/ns/example-jukebox"> xmlns:jbox="http://example.com/ns/example-jukebox">
<name>Wasting Light</name> <name>Wasting Light</name>
<genre>jbox:alternative</genre> <genre>jbox:alternative</genre>
<year>2011</year> <year>2011</year>
</album> </album>
4.6. PATCH 4.6. PATCH
skipping to change at page 47, line 52 skipping to change at page 47, line 29
A server MAY return a "404 Not Found" status-line, as described in A server MAY return a "404 Not Found" status-line, as described in
section 6.5.3 in [RFC7231]. The error-tag value "invalid-value" is section 6.5.3 in [RFC7231]. The error-tag value "invalid-value" is
used in this case. All other error responses are handled according used in this case. All other error responses are handled according
to the procedures defined in Section 7. to the procedures defined in Section 7.
4.6.1. Plain Patch 4.6.1. Plain Patch
The plain patch mechanism merges the contents of the message-body The plain patch mechanism merges the contents of the message-body
with the target resource. The message-body for a plain patch MUST be with the target resource. The message-body for a plain patch MUST be
present and MUST be represented by the media type "application/ present and MUST be represented by the media type "application/
yang-data-xml" or "application/yang-data+json". yang-data+xml" or "application/yang-data+json".
Plain patch can be used to create or update, but not delete, a child Plain patch can be used to create or update, but not delete, a child
resource within the target resource. Please see resource within the target resource. Please see
[I-D.ietf-netconf-yang-patch] for an alternate media-type supporting [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting
the ability to delete child resources. The YANG Patch Media Type the ability to delete child resources. The YANG Patch Media Type
allows multiple sub-operations (e.g., merge, delete) within a single allows multiple sub-operations (e.g., merge, delete) within a single
PATCH method. PATCH method.
If the target resource represents a YANG leaf-list, then the PATCH If the target resource represents a YANG leaf-list, then the PATCH
method MUST NOT change the value of the leaf-list instance. method MUST NOT change the value of the leaf-list instance.
skipping to change at page 48, line 33 skipping to change at page 48, line 13
Example: Example:
To replace just the "year" field in the "album" resource (instead of To replace just the "year" field in the "album" resource (instead of
replacing the entire resource with the PUT method), the client might replacing the entire resource with the PUT method), the client might
send a plain patch as follows. send a plain patch as follows.
PATCH /restconf/data/example-jukebox:jukebox/\ PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com Host: example.com
If-Match: "b8389233a4c" If-Match: "b8389233a4c"
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<album xmlns="http://example.com/ns/example-jukebox"> <album xmlns="http://example.com/ns/example-jukebox">
<year>2011</year> <year>2011</year>
</album> </album>
If the field is updated, the server might respond: If the field is updated, the server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2016 17:49:30 GMT Date: Mon, 23 Apr 2016 17:49:30 GMT
Server: example-server Server: example-server
skipping to change at page 52, line 14 skipping to change at page 52, line 4
4.8.3. The "fields" Query Parameter 4.8.3. The "fields" Query Parameter
The "fields" query parameter is used to optionally identify data The "fields" query parameter is used to optionally identify data
nodes within the target resource to be retrieved in a GET method. nodes within the target resource to be retrieved in a GET method.
The client can use this parameter to retrieve a subset of all nodes The client can use this parameter to retrieve a subset of all nodes
in a resource. in a resource.
The server will return a message-body representing the target The server will return a message-body representing the target
resource, with descendant nodes pruned as specified in the resource, with descendant nodes pruned as specified in the
"fields-expr" value. The server does not return a set separate sub- "fields-expr" value. The server does not return a set of separate
resources. sub-resources.
A value of the "fields" query parameter matches the following rule: A value of the "fields" query parameter matches the following rule:
fields-expr = path '(' fields-expr ')' / fields-expr = path '(' fields-expr ')' /
path ';' fields-expr / path ';' fields-expr /
path path
path = api-identifier [ '/' path ] path = api-identifier [ '/' path ]
"api-identifier" is defined in Section 3.5.3.1. "api-identifier" is defined in Section 3.5.3.1.
skipping to change at page 57, line 12 skipping to change at page 56, line 40
MUST adhere to the defaults reporting behavior defined in Section 3.3 MUST adhere to the defaults reporting behavior defined in Section 3.3
of [RFC6243]. of [RFC6243].
If the "with-defaults" parameter is set to "report-all-tagged" then If the "with-defaults" parameter is set to "report-all-tagged" then
the server MUST adhere to the defaults reporting behavior defined in the server MUST adhere to the defaults reporting behavior defined in
Section 3.4 of [RFC6243]. Metadata is reported by the server as Section 3.4 of [RFC6243]. Metadata is reported by the server as
specified in Section 5.3. The XML encoding for the "default" specified in Section 5.3. The XML encoding for the "default"
attribute sent by the server for default nodes is defined in section attribute sent by the server for default nodes is defined in section
6 of [RFC6243]. The JSON encoding for the "default" attribute MUST 6 of [RFC6243]. The JSON encoding for the "default" attribute MUST
use the same values as defined in [RFC6243], but encoded according to use the same values as defined in [RFC6243], but encoded according to
the rules in [I-D.ietf-netmod-yang-metadata]. The module name the rules in [RFC7952]. The module name "ietf-netconf-with-defaults"
"ietf-netconf-with-defaults" MUST be used for the "default" MUST be used for the "default" attribute.
attribute.
If the "with-defaults" parameter is not present then the server MUST If the "with-defaults" parameter is not present then the server MUST
adhere to the defaults reporting behavior defined in its "basic-mode" adhere to the defaults reporting behavior defined in its "basic-mode"
parameter for the "defaults" protocol capability URI, defined in parameter for the "defaults" protocol capability URI, defined in
Section 9.1.2. Section 9.1.2.
If the server includes the "with-defaults" query parameter URI in the If the server includes the "with-defaults" query parameter URI in the
"capability" leaf-list in Section 9.3, then the "with-defaults" query "capability" leaf-list in Section 9.3, then the "with-defaults" query
parameter MUST be supported. parameter MUST be supported.
Since the server does not report the "also-supported" parameter as Since the server does not report the "also-supported" parameter as
described in section 4.3 of [RFC6243], it is possible that some described in section 4.3 of [RFC6243], it is possible that some
values for the "with-defaults" parameter will not be supported. If values for the "with-defaults" parameter will not be supported. If
the server does not support the requested value of the the server does not support the requested value of the
"with-defaults" parameter, the server MUST return a response with a "with-defaults" parameter, the server MUST return a response with a
"400 Bad Request" status-line. The error-tag value "invalid-value" "400 Bad Request" status-line. The error-tag value "invalid-value"
is used in this case. is used in this case.
5. Messages 5. Messages
The RESTCONF protocol uses HTTP entities for messages. A single HTTP The RESTCONF protocol uses HTTP messages. A single HTTP message
message corresponds to a single protocol method. Most messages can corresponds to a single protocol method. Most messages can perform a
perform a single task on a single resource, such as retrieving a single task on a single resource, such as retrieving a resource or
resource or editing a resource. The exception is the PATCH method, editing a resource. The exception is the PATCH method, which allows
which allows multiple datastore edits within a single message. multiple datastore edits within a single message.
5.1. Request URI Structure 5.1. Request URI Structure
Resources are represented with URIs following the structure for Resources are represented with URIs following the structure for
generic URIs in [RFC3986]. generic URIs in [RFC3986].
A RESTCONF operation is derived from the HTTP method and the request A RESTCONF operation is derived from the HTTP method and the request
URI, using the following conceptual fields: URI, using the following conceptual fields:
<OP> /<restconf>/<path>?<query> <OP> /<restconf>/<path>?<query>
skipping to change at page 59, line 22 skipping to change at page 58, line 52
5.2. Message Encoding 5.2. Message Encoding
RESTCONF messages are encoded in HTTP according to [RFC7230]. The RESTCONF messages are encoded in HTTP according to [RFC7230]. The
"utf-8" character set is used for all messages. RESTCONF message "utf-8" character set is used for all messages. RESTCONF message
content is sent in the HTTP message-body. content is sent in the HTTP message-body.
Content is encoded in either JSON or XML format. A server MUST Content is encoded in either JSON or XML format. A server MUST
support one of either XML or JSON encoding. A server MAY support support one of either XML or JSON encoding. A server MAY support
both XML and JSON encoding. XML encoding rules for data nodes are both XML and JSON encoding. XML encoding rules for data nodes are
defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are defined in [RFC7950]. The same encoding rules are used for all XML
used for all XML content. JSON encoding rules are defined in content. JSON encoding rules are defined in [RFC7951]. Additional
[I-D.ietf-netmod-yang-json]. Additional JSON encoding rules for JSON encoding rules for metadata are defined in [RFC7952]. This
metadata are defined in [I-D.ietf-netmod-yang-metadata]. This
encoding is valid JSON, but also has special encoding rules to encoding is valid JSON, but also has special encoding rules to
identify module namespaces and provide consistent type processing of identify module namespaces and provide consistent type processing of
YANG data. YANG data.
Request input content encoding format is identified with the Content- Request input content encoding format is identified with the Content-
Type header field. This field MUST be present if a message-body is Type header field. This field MUST be present if a message-body is
sent by the client. sent by the client.
The server MUST support the "Accept" header field and "406 Not The server MUST support the "Accept" header field and "406 Not
Acceptable" status-line, as defined in [RFC7231]. The response Acceptable" status-line, as defined in [RFC7231]. The response
skipping to change at page 60, line 16 skipping to change at page 59, line 43
5.3. RESTCONF Metadata 5.3. RESTCONF Metadata
The RESTCONF protocol needs support retrieval of the same metadata The RESTCONF protocol needs support retrieval of the same metadata
that is used in the NETCONF protocol. Information about default that is used in the NETCONF protocol. Information about default
leafs, last-modified timestamps, etc. are commonly used to annotate leafs, last-modified timestamps, etc. are commonly used to annotate
representations of the datastore contents. representations of the datastore contents.
With the XML encoding, the metadata is encoded as attributes in XML, With the XML encoding, the metadata is encoded as attributes in XML,
according to section 3.3 of [W3C.REC-xml-20081126]. With the JSON according to section 3.3 of [W3C.REC-xml-20081126]. With the JSON
encoding, the metadata is encoded as specified in encoding, the metadata is encoded as specified in [RFC7952].
[I-D.ietf-netmod-yang-metadata].
The following examples are based on the example in Appendix D.3.9. The following examples are based on the example in Appendix D.3.9.
The "report-all-tagged" mode for the "with-defaults" query parameter The "report-all-tagged" mode for the "with-defaults" query parameter
requires that a "default" attribute be returned for default nodes. requires that a "default" attribute be returned for default nodes.
This example shows that attribute for the "mtu" leaf . This example shows that attribute for the "mtu" leaf .
5.3.1. XML Metadata Encoding Example 5.3.1. XML Metadata Encoding Example
GET /restconf/data/interfaces/interface=eth1 GET /restconf/data/interfaces/interface=eth1
?with-defaults=report-all-tagged HTTP/1.1 ?with-defaults=report-all-tagged HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data-xml Accept: application/yang-data+xml
The server might respond as follows. The server might respond as follows.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2016 17:01:00 GMT Date: Mon, 23 Apr 2016 17:01:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<interface <interface
xmlns="urn:example.com:params:xml:ns:yang:example-interface"> xmlns="urn:example.com:params:xml:ns:yang:example-interface">
<name>eth1</name> <name>eth1</name>
<mtu xmlns:wd="urn:ietf:params:xml:ns:netconf:default:1.0" <mtu xmlns:wd="urn:ietf:params:xml:ns:netconf:default:1.0"
wd:default="true">1500</mtu> wd:default="true">1500</mtu>
<status>up</status> <status>up</status>
</interface> </interface>
5.3.2. JSON Metadata Encoding Example 5.3.2. JSON Metadata Encoding Example
skipping to change at page 62, line 51 skipping to change at page 62, line 45
specify the structure and syntax of the conceptual child resources specify the structure and syntax of the conceptual child resources
within the "streams" resource. within the "streams" resource.
For example: For example:
The client might send the following request: The client might send the following request:
GET /restconf/data/ietf-restconf-monitoring:restconf-state/\ GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
streams HTTP/1.1 streams HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data-xml Accept: application/yang-data+xml
The server might send the following response: The server might send the following response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<streams <streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<stream> <stream>
<name>NETCONF</name> <name>NETCONF</name>
<description>default NETCONF event stream <description>default NETCONF event stream</description>
</description>
<replay-support>true</replay-support> <replay-support>true</replay-support>
<replay-log-creation-time> <replay-log-creation-time>\
2007-07-08T00:00:00Z 2007-07-08T00:00:00Z\
</replay-log-creation-time> </replay-log-creation-time>
<access> <access>
<encoding>xml</encoding> <encoding>xml</encoding>
<location>https://example.com/streams/NETCONF <location>https://example.com/streams/NETCONF\
</location> </location>
</access> </access>
<access> <access>
<encoding>json</encoding> <encoding>json</encoding>
<location>https://example.com/streams/NETCONF-JSON <location>https://example.com/streams/NETCONF-JSON\
</location> </location>
</access> </access>
</stream> </stream>
<stream> <stream>
<name>SNMP</name> <name>SNMP</name>
<description>SNMP notifications</description> <description>SNMP notifications</description>
<replay-support>false</replay-support> <replay-support>false</replay-support>
<access> <access>
<encoding>xml</encoding> <encoding>xml</encoding>
<location>https://example.com/streams/SNMP</location> <location>https://example.com/streams/SNMP</location>
</access> </access>
</stream> </stream>
<stream> <stream>
<name>syslog-critical</name> <name>syslog-critical</name>
<description>Critical and higher severity <description>Critical and higher severity</description>
</description>
<replay-support>true</replay-support> <replay-support>true</replay-support>
<replay-log-creation-time> <replay-log-creation-time>
2007-07-01T00:00:00Z 2007-07-01T00:00:00Z
</replay-log-creation-time> </replay-log-creation-time>
<access> <access>
<encoding>xml</encoding> <encoding>xml</encoding>
<location> <location>\
https://example.com/streams/syslog-critical https://example.com/streams/syslog-critical\
</location> </location>
</access> </access>
</stream> </stream>
</streams> </streams>
6.3. Subscribing to Receive Notifications 6.3. Subscribing to Receive Notifications
RESTCONF clients can determine the URL for the subscription resource RESTCONF clients can determine the URL for the subscription resource
(to receive notifications) by sending an HTTP GET request for the (to receive notifications) by sending an HTTP GET request for the
"location" leaf with the stream list entry. The value returned by "location" leaf with the stream list entry. The value returned by
the server can be used for the actual notification subscription. the server can be used for the actual notification subscription.
skipping to change at page 64, line 32 skipping to change at page 64, line 28
The server MAY support query parameters for a GET method on this The server MAY support query parameters for a GET method on this
resource. These parameters are specific to each event stream. resource. These parameters are specific to each event stream.
For example: For example:
The client might send the following request: The client might send the following request:
GET /restconf/data/ietf-restconf-monitoring:restconf-state/\ GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
streams/stream=NETCONF/access=xml/location HTTP/1.1 streams/stream=NETCONF/access=xml/location HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data-xml Accept: application/yang-data+xml
The server might send the following response: The server might send the following response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<location <location
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">\
https://example.com/streams/NETCONF https://example.com/streams/NETCONF\
</location> </location>
The RESTCONF client can then use this URL value to start monitoring The RESTCONF client can then use this URL value to start monitoring
the event stream: the event stream:
GET /streams/NETCONF HTTP/1.1 GET /streams/NETCONF HTTP/1.1
Host: example.com Host: example.com
Accept: text/event-stream Accept: text/event-stream
Cache-Control: no-cache Cache-Control: no-cache
Connection: keep-alive Connection: keep-alive
skipping to change at page 65, line 18 skipping to change at page 65, line 15
GET /streams/NETCONF HTTP/1.1 GET /streams/NETCONF HTTP/1.1
Host: example.com Host: example.com
Accept: text/event-stream Accept: text/event-stream
Cache-Control: no-cache Cache-Control: no-cache
Connection: keep-alive Connection: keep-alive
Accept-Encoding: gzip, deflate Accept-Encoding: gzip, deflate
6.3.1. NETCONF Event Stream 6.3.1. NETCONF Event Stream
The server SHOULD support the "NETCONF" event stream defined in The server SHOULD support the "NETCONF" event stream defined in
section 3.2.3 of [RFC5277]. For this stream, The server MAY support section 3.2.3 of [RFC5277]. The notification messages for this
the "start-time", "stop-time", and "filter" query parameters, defined stream are encoded in XML.
in Section 4.8. Refer to Appendix D.3.6 for filter parameter
examples. The server MAY support additional streams which represent the
semantic content of the NETCONF event stream, but using a
representation with a different media type.
The server MAY support the "start-time", "stop-time", and "filter"
query parameters, defined in Section 4.8. Refer to Appendix D.3.6
for filter parameter examples.
6.4. Receiving Event Notifications 6.4. Receiving Event Notifications
RESTCONF notifications are encoded according to the definition of the RESTCONF notifications are encoded according to the definition of the
event stream. The NETCONF stream defined in [RFC5277] is encoded in event stream.
XML format.
The structure of the event data is based on the "notification" The structure of the event data is based on the "notification"
element definition in Section 4 of [RFC5277]. It MUST conform to the element definition in Section 4 of [RFC5277]. It MUST conform to the
schema for the "notification" element in Section 4 of [RFC5277], schema for the "notification" element in Section 4 of [RFC5277] using
except the XML namespace for the event data element is defined as: the XML namespace as defined in the XSD as follows:
urn:ietf:params:xml:ns:yang:ietf-restconf urn:ietf:params:xml:ns:netconf:notification:1.0
For JSON encoding purposes, the module name for the "notification" For JSON encoding purposes, the module name for the "notification"
element is "ietf-restconf". element is "ietf-restconf".
Two child nodes within the "notification" container are expected, Two child nodes within the "notification" container are expected,
representing the event time and the event payload. The "event-time" representing the event time and the event payload. The "eventTime"
node is defined within the "ietf-restconf" module namespace. The node is defined within the same XML namespace as the "notification"
name and namespace of the payload element are determined by the YANG element. It is defined to be within the "ietf-restconf" module
module containing the notification-stmt. namespace for JSON encoding purposes.
The name and namespace of the payload element are determined by the
YANG module containing the notification-stmt representing the
notification message.
In the following example, the YANG module "example-mod" is used: In the following example, the YANG module "example-mod" is used:
module example-mod { module example-mod {
namespace "http://example.com/event/1.0"; namespace "http://example.com/event/1.0";
prefix ex; prefix ex;
notification event { notification event {
leaf event-class { type string; } leaf event-class { type string; }
container reporting-entity { container reporting-entity {
leaf card { type string; } leaf card { type string; }
} }
leaf severity { type string; } leaf severity { type string; }
} }
} }
An example SSE event notification encoded using XML: An example SSE event notification encoded using XML:
data: <notification data: <notification
data: xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> data: xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
data: <event-time>2013-12-21T00:01:00Z</event-time> data: <eventTime>2013-12-21T00:01:00Z</eventTime>
data: <event xmlns="http://example.com/event/1.0"> data: <event xmlns="http://example.com/event/1.0">
data: <event-class>fault</event-class> data: <event-class>fault</event-class>
data: <reporting-entity> data: <reporting-entity>
data: <card>Ethernet0</card> data: <card>Ethernet0</card>
data: </reporting-entity> data: </reporting-entity>
data: <severity>major</severity> data: <severity>major</severity>
data: </event> data: </event>
data: </notification> data: </notification>
An example SSE event notification encoded using JSON: An example SSE event notification encoded using JSON:
data: { data: {
data: "ietf-restconf:notification" : { data: "ietf-restconf:notification" : {
data: "event-time" : "2013-12-21T00:01:00Z", data: "eventTime" : "2013-12-21T00:01:00Z",
data: "example-mod:event" : { data: "example-mod:event" : {
data: "event-class" : "fault", data: "event-class" : "fault",
data: "reporting-entity" : { "card" : "Ethernet0" }, data: "reporting-entity" : { "card" : "Ethernet0" },
data: "severity" : "major" data: "severity" : "major"
data: } data: }
data: } data: }
data: } data: }
Alternatively, since neither XML nor JSON are whitespace sensitive, Alternatively, since neither XML nor JSON are whitespace sensitive,
the above messages can be encoded onto a single line. For example: the above messages can be encoded onto a single line. For example:
For example: For example:
XML: XML:
data: <notification xmlns="urn:ietf:params:xml:ns:yang:ietf-rest\ data: <notification xmlns="urn:ietf:params:xml:ns:netconf:notif\
conf"><event-time>2013-12-21T00:01:00Z</event-time><event xmlns="\ ication:1.0"><eventTime>2013-12-21T00:01:00Z</eventTime><event \
http://example.com/event/1.0"><event-class>fault</event-class><re\ xmlns="http://example.com/event/1.0"><event-class>fault</event-\
portingEntity><card>Ethernet0</card></reporting-entity><severity>\ class><reportingEntity><card>Ethernet0</card></reporting-entity>\
major</severity></event></notification> <severity>major</severity></event></notification>
JSON: JSON:
data: {"ietf-restconf:notification":{"event-time":"2013-12-21\ data: {"ietf-restconf:notification":{"eventTime":"2013-12-21\
T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ T00:01:00Z","example-mod:event":{"event-class": "fault","repor\
tingEntity":{"card":"Ethernet0"},"severity":"major"}}} tingEntity":{"card":"Ethernet0"},"severity":"major"}}}
The SSE specifications supports the following additional fields: The SSE specifications supports the following additional fields:
event, id and retry. A RESTCONF server MAY send the "retry" field event, id and retry. A RESTCONF server MAY send the "retry" field
and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server
SHOULD NOT send the "event" or "id" fields, as there are no SHOULD NOT send the "event" or "id" fields, as there are no
meaningful values that could be used for them that would not be meaningful values that could be used for them that would not be
redundant to the contents of the notification itself. RESTCONF redundant to the contents of the notification itself. RESTCONF
servers that do not send the "id" field also do not need to support servers that do not send the "id" field also do not need to support
skipping to change at page 68, line 49 skipping to change at page 68, line 49
found in Section 8. The Content-Type of this response message MUST found in Section 8. The Content-Type of this response message MUST
be "application/yang-data", plus optionally a structured syntax name be "application/yang-data", plus optionally a structured syntax name
suffix. suffix.
The client SHOULD specify the desired encoding(s) for response The client SHOULD specify the desired encoding(s) for response
messages by specifying the appropriate media-type(s) in the Accept messages by specifying the appropriate media-type(s) in the Accept
header. If the client did not specify an Accept header, then the header. If the client did not specify an Accept header, then the
same structured syntax name suffix used in the request message SHOULD same structured syntax name suffix used in the request message SHOULD
be used, or the server MAY choose any supported message encoding be used, or the server MAY choose any supported message encoding
format. If there is no request message the server MUST select format. If there is no request message the server MUST select
"application/yang-data-xml" or "application/yang-data+json", "application/yang-data+xml" or "application/yang-data+json",
depending on server preference. All of the examples in this depending on server preference. All of the examples in this
document, except for the one below, assume that XML encoding will be document, except for the one below, assume that XML encoding will be
returned if there is an error. returned if there is an error.
YANG Tree Diagram for <errors> data: YANG Tree Diagram for <errors> data:
+---- errors +---- errors
+---- error* +---- error*
+---- error-type enumeration +---- error-type enumeration
+---- error-tag string +---- error-tag string
skipping to change at page 70, line 19 skipping to change at page 70, line 19
The client might send: The client might send:
POST /restconf/data/example-jukebox:jukebox HTTP/1.1 POST /restconf/data/example-jukebox:jukebox HTTP/1.1
Host: example.com Host: example.com
The server might respond: The server might respond:
HTTP/1.1 409 Conflict HTTP/1.1 409 Conflict
Date: Mon, 23 Apr 2016 17:11:00 GMT Date: Mon, 23 Apr 2016 17:11:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error> <error>
<error-type>protocol</error-type> <error-type>protocol</error-type>
<error-tag>data-exists</error-tag> <error-tag>data-exists</error-tag>
<error-path <error-path
xmlns:rc="urn:ietf:params:xml:ns:yang:ietf-restconf" xmlns:rc="urn:ietf:params:xml:ns:yang:ietf-restconf"
xmlns:jbox="https://example.com/ns/example-jukebox">\ xmlns:jbox="https://example.com/ns/example-jukebox">\
/rc:restconf/rc:data/jbox:jukebox /rc:restconf/rc:data/jbox:jukebox
</error-path> </error-path>
skipping to change at page 72, line 4 skipping to change at page 72, line 4
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from draft-ietf-netconf-restconf-16.txt // Note: extracted from draft-ietf-netconf-restconf-17.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2016-08-15 { revision 2016-08-15 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
skipping to change at page 81, line 9 skipping to change at page 81, line 9
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from draft-ietf-netconf-restconf-16.txt // Note: extracted from draft-ietf-netconf-restconf-17.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2016-08-15 { revision 2016-08-15 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
skipping to change at page 85, line 7 skipping to change at page 85, line 7
reference: RFCXXXX reference: RFCXXXX
name: ietf-restconf-monitoring name: ietf-restconf-monitoring
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
prefix: rcmon prefix: rcmon
// RFC Ed.: replace XXXX with RFC number and remove this note // RFC Ed.: replace XXXX with RFC number and remove this note
reference: RFCXXXX reference: RFCXXXX
11.3. Media Types 11.3. Media Types
11.3.1. Media Type application/yang-data-xml 11.3.1. Media Type application/yang-data+xml
Type name: application Type name: application
Subtype name: yang-data Subtype name: yang-data
Required parameters: None Required parameters: None
Optional parameters: None Optional parameters: None
// RFC Ed.: replace draft-ietf-netmod-rfc6020bis with
// the actual RFC reference for YANG 1.1, and remove this note.
Encoding considerations: 8-bit Encoding considerations: 8-bit
Each conceptual YANG data node is encoded according to the Each conceptual YANG data node is encoded according to the
XML Encoding Rules and Canonical Format for the specific XML Encoding Rules and Canonical Format for the specific
YANG data node type defined in [draft-ietf-netmod-rfc6020bis]. YANG data node type defined in [RFC7950].
// RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the
// section number for Security Considerations // section number for Security Considerations
// Replace 'XXXX' in Section NN of [RFCXXXX] with the actual // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual
// RFC number, and remove this note. // RFC number, and remove this note.
Security considerations: Security considerations related Security considerations: Security considerations related
to the generation and consumption of RESTCONF messages to the generation and consumption of RESTCONF messages
are discussed in Section NN of [RFCXXXX]. are discussed in Section NN of [RFCXXXX].
Additional security considerations are specific to the Additional security considerations are specific to the
skipping to change at page 86, line 5 skipping to change at page 85, line 51
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
Published specification: RFC XXXX Published specification: RFC XXXX
Applications that use this media type: Instance document Applications that use this media type: Instance document
data parsers used within a protocol or automation tool data parsers used within a protocol or automation tool
that utilize YANG defined data structures. that utilize YANG defined data structures.
Fragment identifier considerations: The fragment field in the Fragment identifier considerations: Fragment identifiers for
request URI has no defined purpose. this type are not defined. All YANG data nodes are
accessible as resources using the path in the request URI.
Additional information: Additional information:
Deprecated alias names for this type: N/A Deprecated alias names for this type: N/A
Magic number(s): N/A Magic number(s): N/A
File extension(s): .xml File extension(s): .xml
Macintosh file type code(s): "TEXT" Macintosh file type code(s): "TEXT"
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
skipping to change at page 86, line 45 skipping to change at page 86, line 43
11.3.2. Media Type application/yang-data+json 11.3.2. Media Type application/yang-data+json
Type name: application Type name: application
Subtype name: yang-data+json Subtype name: yang-data+json
Required parameters: None Required parameters: None
Optional parameters: None Optional parameters: None
// RFC Ed.: replace draft-ietf-netmod-yang-json with
// the actual RFC reference for JSON Encoding of YANG Data,
// and remove this note.
// RFC Ed.: replace draft-ietf-netmod-yang-metadata with
// the actual RFC reference for JSON Encoding of YANG Data,
// and remove this note.
Encoding considerations: 8-bit Encoding considerations: 8-bit
Each conceptual YANG data node is encoded according to Each conceptual YANG data node is encoded according to
[draft-ietf-netmod-yang-json]. A data annotation is [RFC7951]. A data annotation is encoded according to
encoded according to [draft-ietf-netmod-yang-metadata] [RFC7952].
// RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the
// section number for Security Considerations // section number for Security Considerations
// Replace 'XXXX' in Section NN of [RFCXXXX] with the actual // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual
// RFC number, and remove this note. // RFC number, and remove this note.
Security considerations: Security considerations related Security considerations: Security considerations related
to the generation and consumption of RESTCONF messages to the generation and consumption of RESTCONF messages
are discussed in Section NN of [RFCXXXX]. are discussed in Section NN of [RFCXXXX].
Additional security considerations are specific to the Additional security considerations are specific to the
skipping to change at page 91, line 17 skipping to change at page 90, line 42
Communications Directorate (S&TCD) under Contract No. W15P7T- Communications Directorate (S&TCD) under Contract No. W15P7T-
13-C-A616. Any opinions, findings and conclusions or recommendations 13-C-A616. Any opinions, findings and conclusions or recommendations
expressed in this material are those of the author(s) and do not expressed in this material are those of the author(s) and do not
necessarily reflect the views of The Space & Terrestrial necessarily reflect the views of The Space & Terrestrial
Communications Directorate (S&TCD). Communications Directorate (S&TCD).
14. References 14. References
14.1. Normative References 14.1. Normative References
[I-D.ietf-netmod-rfc6020bis]
Bjorklund, M., "The YANG 1.1 Data Modeling Language",
draft-ietf-netmod-rfc6020bis-14 (work in progress), June
2016.
[I-D.ietf-netmod-yang-json]
Lhotka, L., "JSON Encoding of Data Modeled with YANG",
draft-ietf-netmod-yang-json-10 (work in progress), March
2016.
[I-D.ietf-netmod-yang-metadata]
Lhotka, L., "Defining and Using Metadata with YANG",
draft-ietf-netmod-yang-metadata-07 (work in progress),
March 2016.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996. November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[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.
skipping to change at page 93, line 21 skipping to change at page 92, line 31
[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, [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190,
RFC 7320, July 2014. RFC 7320, July 2014.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015,
<http://www.rfc-editor.org/info/rfc7540>.
[RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the
NETCONF Protocol over Transport Layer Security (TLS) with NETCONF Protocol over Transport Layer Security (TLS) with
Mutual X.509 Authentication", RFC 7589, Mutual X.509 Authentication", RFC 7589,
DOI 10.17487/RFC7589, June 2015, DOI 10.17487/RFC7589, June 2015,
<http://www.rfc-editor.org/info/rfc7589>. <http://www.rfc-editor.org/info/rfc7589>.
[RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
Library", RFC 7895, June 2016. Library", RFC 7895, June 2016.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<http://www.rfc-editor.org/info/rfc7950>.
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
RFC 7951, DOI 10.17487/RFC7951, August 2016,
<http://www.rfc-editor.org/info/rfc7951>.
[RFC7952] Lhotka, L., "Defining and Using Metadata with YANG",
RFC 7952, DOI 10.17487/RFC7952, August 2016,
<http://www.rfc-editor.org/info/rfc7952>.
[W3C.REC-eventsource-20150203] [W3C.REC-eventsource-20150203]
Hickson, I., "Server-Sent Events", World Wide Web Hickson, I., "Server-Sent Events", World Wide Web
Consortium Recommendation REC-eventsource-20150203, Consortium Recommendation REC-eventsource-20150203,
February 2015, February 2015,
<http://www.w3.org/TR/2015/REC-eventsource-20150203>. <http://www.w3.org/TR/2015/REC-eventsource-20150203>.
[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-
skipping to change at page 94, line 23 skipping to change at page 93, line 41
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. v15 to v16 A.1. v16 to v17
o various clarifications from NETCONF WG mailing list
o updated YANG 1.1 and YANG/JSON references to RFC numbers
o fixed notification namespace and eventTime name bug
o changed media type application/yang-data-xml to application/yang-
data+xml
o update fragment identifier considerations section for application/
yang-data+xml
o clarify HTTP version requirements
A.2. v15 to v16
o changed media type application/yang-data to application/yang-data- o changed media type application/yang-data to application/yang-data-
xml xml
o changed header to header field o changed header to header field
o added linewrap convention in terminology and applied in many o added linewrap convention in terminology and applied in many
examples examples
o clarified DELETE for leaf-list and list o clarified DELETE for leaf-list and list
skipping to change at page 94, line 48 skipping to change at page 94, line 35
o added 'yang-data extension' term and clarified 'YANG data o added 'yang-data extension' term and clarified 'YANG data
template' term template' term
o clarified that the fragment component is not part of the request o clarified that the fragment component is not part of the request
URI, per HTTP URI, per HTTP
o clarified request URI "api-path" syntax o clarified request URI "api-path" syntax
o clarified many examples o clarified many examples
A.2. v14 to v15 A.3. v14 to v15
o added text for HTTP/2 usage o added text for HTTP/2 usage
o changed media type definitions per review comments o changed media type definitions per review comments
o added some clarifications and typos o added some clarifications and typos
o added error-tag mapping for 406 and 412 errors o added error-tag mapping for 406 and 412 errors
o added clarifications based on ops-dir review by Lionel Morand o added clarifications based on ops-dir review by Lionel Morand
o clarified PUT and POST differences for creating a data resource o clarified PUT and POST differences for creating a data resource
o clarify PUT for a datastore resource o clarify PUT for a datastore resource
skipping to change at page 95, line 15 skipping to change at page 95, line 4
o added error-tag mapping for 406 and 412 errors o added error-tag mapping for 406 and 412 errors
o added clarifications based on ops-dir review by Lionel Morand o added clarifications based on ops-dir review by Lionel Morand
o clarified PUT and POST differences for creating a data resource o clarified PUT and POST differences for creating a data resource
o clarify PUT for a datastore resource o clarify PUT for a datastore resource
o added clarifications from Gen-Art review by Robert Sparks o added clarifications from Gen-Art review by Robert Sparks
o clarified terminology in many places o clarified terminology in many places
A.3. v13 - v14 A.4. v13 - v14
This release addresses github issues #61, #62, #63, #65, #66, and This release addresses github issues #61, #62, #63, #65, #66, and
#67. #67.
o change term 'server' to 'NETCONF server' o change term 'server' to 'NETCONF server'
o add term 'RESTCONF server' also called 'server' o add term 'RESTCONF server' also called 'server'
o change term 'client' to 'NETCONF client' o change term 'client' to 'NETCONF client'
skipping to change at page 97, line 4 skipping to change at page 96, line 38
o remove suggestion MAY send Pragma: no-cache in response o remove suggestion MAY send Pragma: no-cache in response
o remove table of HTTP status codes used in RESTCONF o remove table of HTTP status codes used in RESTCONF
o changed media type names so they conform to RFC 6838 o changed media type names so they conform to RFC 6838
o clarified too-big error-tag conversion o clarified too-big error-tag conversion
o update SSE reference o update SSE reference
o clarify leaf-list identifier encoding o clarify leaf-list identifier encoding
o removed all media types except yang-data o removed all media types except yang-data
o changed restconf-media-type extension to be more generic yang-data o changed restconf-media-type extension to be more generic yang-data
extension extension
A.4. v12 - v13 A.5. v12 - v13
o fix YANG library module examples (now called module-state) o fix YANG library module examples (now called module-state)
o fix terminology idnit issue o fix terminology idnit issue
o removed RFC 2818 reference (changed citation to RFC 7230) o removed RFC 2818 reference (changed citation to RFC 7230)
A.5. v11 - v12 A.6. v11 - v12
o clarify query parameter requirements o clarify query parameter requirements
o move filter query section to match table order in sec. 4.8 o move filter query section to match table order in sec. 4.8
o clarify that depth default is entire subtree for datastore o clarify that depth default is entire subtree for datastore
resource resource
o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml
skipping to change at page 97, line 45 skipping to change at page 97, line 32
o clarify that errors should be returned for any resource type o clarify that errors should be returned for any resource type
o clarified media subtype (not type) for error response o clarified media subtype (not type) for error response
o clarified client SHOULD (not MAY) specify errors format in Accept o clarified client SHOULD (not MAY) specify errors format in Accept
header header
o clarified terminology in many sections o clarified terminology in many sections
A.6. v10 - v11 A.7. v10 - v11
o change term 'operational data' to 'state data' o change term 'operational data' to 'state data'
o clarify :startup behavior o clarify :startup behavior
o clarify X.509 security text o clarify X.509 security text
o change '403 Forbidden' to '401 Unauthorized' for GET error o change '403 Forbidden' to '401 Unauthorized' for GET error
o clarify MUST have one "restconf" link relation o clarify MUST have one "restconf" link relation
o clarify that NV-storage is not mandatory o clarify that NV-storage is not mandatory
o clarify how "Last-Modified" and "ETag" header info can be used by o clarify how "Last-Modified" and "ETag" header info can be used by
a client a client
o clarify meaning of mandatory parameter o clarify meaning of mandatory parameter
skipping to change at page 98, line 16 skipping to change at page 98, line 4
o clarify MUST have one "restconf" link relation o clarify MUST have one "restconf" link relation
o clarify that NV-storage is not mandatory o clarify that NV-storage is not mandatory
o clarify how "Last-Modified" and "ETag" header info can be used by o clarify how "Last-Modified" and "ETag" header info can be used by
a client a client
o clarify meaning of mandatory parameter o clarify meaning of mandatory parameter
o fix module name in action examples o fix module name in action examples
o clarify operation resource request needs to be known to parse the o clarify operation resource request needs to be known to parse the
output output
o clarify ordered-by user terminology o clarify ordered-by user terminology
o fixed JSON example in D.1.1 o fixed JSON example in D.1.1
A.7. v09 - v10 A.8. v09 - v10
o address review comments: github issue #36 o address review comments: github issue #36
o removed intro text about no knowledge of NETCONF needed o removed intro text about no knowledge of NETCONF needed
o clarified candidate and confirmed-commit behavior in sec. 1.3 o clarified candidate and confirmed-commit behavior in sec. 1.3
o clarified that a RESTCONF server MUST support TLS o clarified that a RESTCONF server MUST support TLS
o clarified choice of 403 or 404 error o clarified choice of 403 or 404 error
skipping to change at page 100, line 23 skipping to change at page 100, line 11
o added mandatory /restconf/yang-library-version leaf to advertise o added mandatory /restconf/yang-library-version leaf to advertise
revision-date of the YANG library implemented by the server revision-date of the YANG library implemented by the server
o clarified URI encoding rules for leaf-list o clarified URI encoding rules for leaf-list
o clarified sec. 2.2 wrt/ certificates and TLS o clarified sec. 2.2 wrt/ certificates and TLS
o added update procedure for entity tag and timestamp o added update procedure for entity tag and timestamp
A.8. v08 - v09 A.9. v08 - v09
o fix introduction text regarding implementation requirements for o fix introduction text regarding implementation requirements for
the ietf-yang-library the ietf-yang-library
o clarified HTTP authentication requirements o clarified HTTP authentication requirements
o fix host-meta example o fix host-meta example
o changed list key encoding to clarify that quoted strings are not o changed list key encoding to clarify that quoted strings are not
allowed. Percent-encoded values are used if quotes would be allowed. Percent-encoded values are used if quotes would be
required. A missing key is treated as a zero-length string required. A missing key is treated as a zero-length string
o Fixed example of percent-encoded string to match YANG model o Fixed example of percent-encoded string to match YANG model
o Changed streams examples to align with naming already used o Changed streams examples to align with naming already used
A.9. v07 - v08 A.10. 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 101, line 4 skipping to change at page 100, line 39
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.10. v06 - v07 A.11. 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.11. v05 - v06 A.12. v05 - v06
o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug)
A.12. v04 - v05 A.13. 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 102, line 17 skipping to change at page 102, line 5
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.13. v03 - v04 A.14. 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 103, line 5 skipping to change at page 102, line 40
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.14. v02 - v03 A.15. 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 103, line 17 skipping to change at page 103, line 4
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.15. v01 - v02 A.16. 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 104, line 16 skipping to change at page 104, line 5
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.16. v00 - v01 A.17. 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 105, line 4 skipping to change at page 104, line 42
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.17. bierman:restconf-04 to ietf:restconf-00 A.18. 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
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
| +--rw artist* [name] | +--rw artist* [name]
| | +--rw name string | | +--rw name string
| | +--rw album* [name] | | +--rw album* [name]
| | +--rw name string | | +--rw name string
| | +--rw genre? identityref | | +--rw genre? identityref
| | +--rw year? uint16 | | +--rw year? uint16
| | +--rw admin | | +--rw admin
| | | +--rw label? string | | | +--rw label? string
skipping to change at page 106, line 28 skipping to change at page 105, line 48
| | +--rw format? string | | +--rw format? string
| | +--rw length? uint32 | | +--rw length? uint32
| +--ro artist-count? uint32 | +--ro artist-count? uint32
| +--ro album-count? uint32 | +--ro album-count? uint32
| +--ro song-count? uint32 | +--ro song-count? uint32
+--rw playlist* [name] +--rw playlist* [name]
| +--rw name string | +--rw name string
| +--rw description? string | +--rw description? string
| +--rw song* [index] | +--rw song* [index]
| +--rw index uint32 | +--rw index uint32
| +--rw id leafref | +--rw id instance-identifier
+--rw player +--rw player
+--rw gap? decimal64 +--rw gap? decimal64
rpcs: rpcs:
+---x play +---x play
+--ro input +--ro input
+--ro playlist string +--ro playlist string
+--ro song-number uint32 +--ro song-number uint32
skipping to change at page 110, line 47 skipping to change at page 110, line 17
description description
"Example nested configuration data resource"; "Example nested configuration data resource";
leaf index { // not really needed leaf index { // not really needed
type uint32; type uint32;
description description
"An arbitrary integer index for this playlist song."; "An arbitrary integer index for this playlist song.";
} }
leaf id { leaf id {
type leafref { type instance-identifier;
path "/jbox:jukebox/jbox:library/jbox:artist/" +
"jbox:album/jbox:song/jbox:name";
}
mandatory true; mandatory true;
description description
"Song identifier. Must identify an instance of "Song identifier. Must identify an instance of
/jukebox/library/artist/album/song/name."; /jukebox/library/artist/album/song/name.";
} }
} }
} }
container player { container player {
description description
skipping to change at page 113, line 7 skipping to change at page 112, line 22
"operations" : {}, "operations" : {},
"yang-library-version" : "2016-06-21" "yang-library-version" : "2016-06-21"
} }
} }
To request that the response content to be encoded in XML, the To request that the response content to be encoded in XML, the
"Accept" header can be used, as in this example request: "Accept" header can be used, as in this example request:
GET /restconf HTTP/1.1 GET /restconf HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data-xml Accept: application/yang-data+xml
The server will return the same conceptual data either way, which The server will return the same conceptual data either way, which
might be as follows : might be as follows :
[RFC Editor Note: Adjust the date for ietf-yang-library below to the [RFC Editor Note: Adjust the date for ietf-yang-library below to the
date in the published ietf-yang-library YANG module, and remove this date in the published ietf-yang-library YANG module, and remove this
note.] note.]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2016 17:01:00 GMT Date: Mon, 23 Apr 2016 17:01:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<data/> <data/>
<operations/> <operations/>
<yang-library-version>2016-06-21</yang-library-version> <yang-library-version>2016-06-21</yang-library-version>
</restconf> </restconf>
D.1.2. Retrieve The Server Module Information D.1.2. Retrieve The Server Module Information
It is possible the YANG library module will change over time. The It is possible the YANG library module will change over time. The
skipping to change at page 115, line 28 skipping to change at page 114, line 44
D.1.3. Retrieve The Server Capability Information D.1.3. Retrieve The Server Capability Information
In this example the client is retrieving the capability information In this example the client is retrieving the capability information
from the server in XML format, and the server supports all the from the server in XML format, and the server supports all the
RESTCONF query parameters, plus one vendor parameter: RESTCONF query parameters, plus one vendor parameter:
GET /restconf/data/ietf-restconf-monitoring:restconf-state/\ GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
capabilities HTTP/1.1 capabilities HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data-xml Accept: application/yang-data+xml
The server might respond as follows: The server might respond as follows:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2016 17:02:00 GMT Date: Mon, 23 Apr 2016 17:02:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Last-Modified: Sun, 22 Apr 2016 01:00:14 GMT Last-Modified: Sun, 22 Apr 2016 01:00:14 GMT
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<capabilities <capabilities
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<capability>\ <capability>\
urn:ietf:params:restconf:capability:defaults:1.0?\ urn:ietf:params:restconf:capability:defaults:1.0?\
basic-mode=explicit\ basic-mode=explicit\
</capability> </capability>
<capability>\ <capability>\
urn:ietf:params:restconf:capability:with-defaults:1.0\ urn:ietf:params:restconf:capability:with-defaults:1.0\
</capability> </capability>
skipping to change at page 117, line 33 skipping to change at page 116, line 33
example-jukebox:jukebox/library/artist=Foo%20Fighters example-jukebox:jukebox/library/artist=Foo%20Fighters
Last-Modified: Mon, 23 Apr 2016 17:02:00 GMT Last-Modified: Mon, 23 Apr 2016 17:02:00 GMT
ETag: "b3830f23a4c" ETag: "b3830f23a4c"
To create a new "album" resource for this artist within the "jukebox" To create a new "album" resource for this artist within the "jukebox"
resource, the client might send the following request: resource, the client might send the following request:
POST /restconf/data/example-jukebox:jukebox/\ POST /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters HTTP/1.1 library/artist=Foo%20Fighters HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<album xmlns="http://example.com/ns/example-jukebox"> <album xmlns="http://example.com/ns/example-jukebox">
<name>Wasting Light</name> <name>Wasting Light</name>
<year>2011</year> <year>2011</year>
</album> </album>
If the resource is created, the server might respond as follows: If the resource is created, the server might respond as follows:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2016 17:03:00 GMT Date: Mon, 23 Apr 2016 17:03:00 GMT
skipping to change at page 118, line 46 skipping to change at page 117, line 46
child leaf called "enable-jukebox-streaming": child leaf called "enable-jukebox-streaming":
container system { container system {
leaf enable-jukebox-streaming { leaf enable-jukebox-streaming {
type boolean; type boolean;
} }
} }
In this example PATCH is used by the client to modify 2 top-level In this example PATCH is used by the client to modify 2 top-level
resources at once, in order to enable jukebox streaming and add an resources at once, in order to enable jukebox streaming and add an
"album" sub-resource to eachof 2 "artist" resources: "album" sub-resource to each of 2 "artist" resources:
PATCH /restconf/data HTTP/1.1 PATCH /restconf/data HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<system xmlns="http://example.com/ns/example-system"> <system xmlns="http://example.com/ns/example-system">
<enable-jukebox-streaming>true</enable-jukebox-streaming> <enable-jukebox-streaming>true</enable-jukebox-streaming>
</system> </system>
<jukebox xmlns="http://example.com/ns/example-jukebox"> <jukebox xmlns="http://example.com/ns/example-jukebox">
<library> <library>
<artist> <artist>
<name>Foo Fighters</name> <name>Foo Fighters</name>
<album> <album>
<name>One by One</name> <name>One by One</name>
skipping to change at page 119, line 39 skipping to change at page 118, line 34
</library> </library>
</jukebox> </jukebox>
</data> </data>
D.2.4. Edit a Data Resource D.2.4. Edit a Data Resource
In this example, the client modifies one data node by adding an In this example, the client modifies one data node by adding an
"album" sub-resource by sending a PATCH for the data resource: "album" sub-resource by sending a PATCH for the data resource:
PATCH /restconf/data/example-jukebox:jukebox/library/\ PATCH /restconf/data/example-jukebox:jukebox/library/\
artist=Nick%20Cave%20and%20the%Bad%20Seeds HTTP/1.1 artist=Nick%20Cave%20and%20the%20Bad%20Seeds HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data-xml Content-Type: application/yang-data+xml
<artist xmlns="http://example.com/ns/example-jukebox"> <artist xmlns="http://example.com/ns/example-jukebox">
<name>Nick Cave and the Bad Seeds</name> <name>Nick Cave and the Bad Seeds</name>
<album> <album>
<name>The Good Son</name> <name>The Good Son</name>
<year>1990</year> <year>1990</year>
</album> </album>
</artist> </artist>
D.3. Query Parameter Examples D.3. Query Parameter Examples
skipping to change at page 124, line 47 skipping to change at page 123, line 47
} }
] ]
}, },
"playlist" : [ "playlist" : [
{ {
"name" : "Foo-One", "name" : "Foo-One",
"description" : "example playlist 1", "description" : "example playlist 1",
"song" : [ "song" : [
{ {
"index" : 1, "index" : 1,
"id" : "https://example.com/restconf/data/ "id" : "/example-jukebox:jukebox/library\
example-jukebox:jukebox/library/artist= /artist[name='Foo Figthers']\
Foo%20Fighters/album=Wasting%20Light/ /album[name='Wasting Light']\
song=Rope" /song[name=Rope']"
}, },
{ {
"index" : 2, "index" : 2,
"id" : "https://example.com/restconf/data/ "id" : "/example-jukebox:jukebox/library\
example-jukebox:jukebox/library/artist= /artist[name='Foo Figthers']\
Foo%20Fighters/album=Wasting%20Light/song= /album[name='Wasting Light']\
Bridge%20Burning" /song[name=Bridge Burning']"
} }
] ]
} }
], ],
"player" : { "player" : {
"gap" : 0.5 "gap" : 0.5
} }
} }
} }
skipping to change at page 128, line 14 skipping to change at page 127, line 14
POST /restconf/data/example-jukebox:jukebox/\ POST /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One?insert=first HTTP/1.1 playlist=Foo-One?insert=first HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data+json Content-Type: application/yang-data+json
{ {
"example-jukebox:song" : [ "example-jukebox:song" : [
{ {
"index" : 1, "index" : 1,
"id" : "/example-jukebox:jukebox/library/\ "id" : "/example-jukebox:jukebox/library\
artist=Foo%20Fighters/album=Wasting%20Light/song=Rope" /artist[name='Foo Figthers']\
/album[name='Wasting Light']\
/song[name=Rope']"
} }
] ]
} }
Response from server. Response from server:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2016 13:01:20 GMT Date: Mon, 23 Apr 2016 13:01:20 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2016 13:01:20 GMT Last-Modified: Mon, 23 Apr 2016 13:01:20 GMT
Location: https://example.com/restconf/data/\ Location: https://example.com/restconf/data/\
example-jukebox:jukebox/playlist=Foo-One/song=1 example-jukebox:jukebox/playlist=Foo-One/song=1
ETag: "eeeada438af" ETag: "eeeada438af"
D.3.5. "point" Parameter D.3.5. "point" Parameter
In this example, the client is inserting a new "song" resource within In this example, the client is inserting a new song entry in the
an "album" resource after another song. "Foo-One" playlist after the first song.
Request from client: Request from client:
POST /restconf/data/example-jukebox:jukebox/\ POST /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light?\ playlist=Foo-One?insert=after&point=\
insert=after&point=%2Fexample-jukebox%3Ajukebox%2F\ %2Fexample-jukebox%3Ajukebox\
library%2Fartist%3DFoo%20Fighters%2Falbum%3D\ %2Fplaylist%3DFoo-One%2Fsong%3D1 HTTP/1.1
Wasting%20Light%2Fsong%3DBridge%20Burning HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data+json Content-Type: application/yang-data+json
{ {
"example-jukebox:song" : [ "example-jukebox:song" : [
{ {
"name" : "Rope", "index" : 2,
"location" : "/media/foo/a7/rope.mp3", "id" : "/example-jukebox:jukebox/library\
"format" : "MP3", /artist[name='Foo Figthers']\
"length" : 259 /album[name='Wasting Light']\
} /song[name=Bridge Burning']"
] }
]
} }
Response from server: Response from server:
HTTP/1.1 204 No Content HTTP/1.1 201 Created
Date: Mon, 23 Apr 2016 13:01:20 GMT Date: Mon, 23 Apr 2016 13:01:20 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2016 13:01:20 GMT Last-Modified: Mon, 23 Apr 2016 13:01:20 GMT
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/playlist=Foo-One/song=2
ETag: "abcada438af" 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: specifications:
// filter = /event/event-class='fault' // filter = /event/event-class='fault'
GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault'
 End of changes. 139 change blocks. 
302 lines changed or deleted 295 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/