draft-ietf-netconf-restconf-14.txt   draft-ietf-netconf-restconf-15.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: December 30, 2016 Tail-f Systems Expires: January 8, 2017 Tail-f Systems
K. Watsen K. Watsen
Juniper Networks Juniper Networks
June 28, 2016 July 7, 2016
RESTCONF Protocol RESTCONF Protocol
draft-ietf-netconf-restconf-14 draft-ietf-netconf-restconf-15
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 December 30, 2016. This Internet-Draft will expire on January 8, 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 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 . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.6. URI Template and Examples . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . 10 1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 10
1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 11 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 11
1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 12 1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 12
1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 13 1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 13
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 14 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 14
2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 14 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 14
2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 14 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 14
2.3. Certificate Validation . . . . . . . . . . . . . . . . . 14 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 14
2.4. Authenticated Server Identity . . . . . . . . . . . . . . 14 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 15
2.5. Authenticated Client Identity . . . . . . . . . . . . . . 14 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 15
3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 16 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 16
3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 17 3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 17
3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 18 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 18
3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 19
3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 19 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 19
3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 20
3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 20 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 20
3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 21
3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 22
3.5.1. Timestamp . . . . . . . . . . . . . . . . . . . . . . 22 3.5.1. Timestamp . . . . . . . . . . . . . . . . . . . . . . 22
3.5.2. Entity tag . . . . . . . . . . . . . . . . . . . . . 23 3.5.2. Entity tag . . . . . . . . . . . . . . . . . . . . . 23
3.5.3. Encoding Data Resource Identifiers in the Request URI 23 3.5.3. Encoding Data Resource Identifiers in the Request URI 23
3.5.4. Defaults Handling . . . . . . . . . . . . . . . . . . 26 3.5.4. Defaults Handling . . . . . . . . . . . . . . . . . . 26
3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 26 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 27
3.6.1. Encoding Operation Resource Input Parameters . . . . 28 3.6.1. Encoding Operation Resource Input Parameters . . . . 29
3.6.2. Encoding Operation Resource Output Parameters . . . . 31 3.6.2. Encoding Operation Resource Output Parameters . . . . 32
3.6.3. Encoding Operation Resource Errors . . . . . . . . . 33 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 34
3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 34 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 35
3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 35 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 36
3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 36 3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 37
4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 36 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 39 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 40
4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 40 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 41
4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 43 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 43 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 44
4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 44 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 45 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 46
4.8.1. The "content" Query Parameter . . . . . . . . . . . . 46 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 47
4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 47 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 47
4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 47 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 48
4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 48 4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 49
4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 49 4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 50
4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 50 4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 50
4.8.7. The "start-time" Query Parameter . . . . . . . . . . 50 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 51
4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 51 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 52
4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 51 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 52
5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 52 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 53
5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 54 5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 55
5.3. RESTCONF Metadata . . . . . . . . . . . . . . . . . . . . 55 5.3. RESTCONF Metadata . . . . . . . . . . . . . . . . . . . . 55
5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 55 5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 56
5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 56 5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 56
5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 56 5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 57
5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 56 5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 57
6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 57 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 57
6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 57 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 58
6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 57 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 58
6.3. Subscribing to Receive Notifications . . . . . . . . . . 59 6.3. Subscribing to Receive Notifications . . . . . . . . . . 59
6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 60 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 60
6.4. Receiving Event Notifications . . . . . . . . . . . . . . 60 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 61
7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 62 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 63
7.1. Error Response Message . . . . . . . . . . . . . . . . . 63 7.1. Error Response Message . . . . . . . . . . . . . . . . . 64
8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 65 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 66
9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 72 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 72
9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 72 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 73
9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 73 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 73
9.1.2. The "defaults" Protocol Capability URI . . . . . . . 73 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 74
9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 74 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 75
9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 74 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 75
10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 78 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 79
10.1. modules-state . . . . . . . . . . . . . . . . . . . . . 78 10.1. modules-state . . . . . . . . . . . . . . . . . . . . . 79
10.1.1. modules-state/module . . . . . . . . . . . . . . . . 78 10.1.1. modules-state/module . . . . . . . . . . . . . . . . 79
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79
11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 78 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 79
11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 79 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 80
11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 79 11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 80
11.3.1. Media Type application/yang-data+xml . . . . . . . . 79 11.3.1. Media Type application/yang-data . . . . . . . . . . 80
11.3.2. Media Type application/yang-data+json . . . . . . . 81 11.3.2. Media Type application/yang-data+json . . . . . . . 82
11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 83 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 84
12. Security Considerations . . . . . . . . . . . . . . . . . . . 84 12. Security Considerations . . . . . . . . . . . . . . . . . . . 84
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 85 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 85
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 85 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 86
14.1. Normative References . . . . . . . . . . . . . . . . . . 85 14.1. Normative References . . . . . . . . . . . . . . . . . . 86
14.2. Informative References . . . . . . . . . . . . . . . . . 88 14.2. Informative References . . . . . . . . . . . . . . . . . 89
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 88 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 89
A.1. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.1. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . 89
A.2. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 90 A.2. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 89
A.3. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 90 A.3. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 91
A.4. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 91 A.4. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 91
A.5. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 91 A.5. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 92
A.6. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 93 A.6. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 93
A.7. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 94 A.7. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 95
A.8. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 94 A.8. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 95
A.9. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 94 A.9. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 95
A.10. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 94 A.10. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 96
A.11. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 95 A.11. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 96
A.12. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 96 A.12. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 97
A.13. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 96 A.13. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 97
A.14. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 97 A.14. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 98
A.15. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 98 A.15. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 99
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 98 A.16. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 99
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 98 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 100
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 99 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 100
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 104 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 101
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 104 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 106
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 104 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 106
D.1.2. Retrieve The Server Module Information . . . . . . . 106 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 106
D.1.3. Retrieve The Server Capability Information . . . . . 108 D.1.2. Retrieve The Server Module Information . . . . . . . 108
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 109 D.1.3. Retrieve The Server Capability Information . . . . . 109
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 109 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 110
D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 110 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 110
D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 111 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 112
D.2.4. Edit a Data Resource . . . . . . . . . . . . . . . . 111 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 112
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 112 D.2.4. Edit a Data Resource . . . . . . . . . . . . . . . . 113
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 112 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 113
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 114 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 113
D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 117 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 116
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 119 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 119
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 119 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 120
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 120 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 121
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 121 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 122
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 121 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 122
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 121 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 122
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 123 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 123
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 124
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
skipping to change at page 9, line 11 skipping to change at page 9, line 15
o operation resource: a resource that models a data-model specific o operation resource: a resource that models a data-model specific
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 generic PATCH request on the target datastore or data o patch: a generic PATCH request on the target datastore or data
resource. The media type of the message-body content will resource. The media type of the message-body content will
identify the patch type in use. identify the patch type in use.
o plain patch: a specific PATCH request type, defined in o plain patch: a specific PATCH request type, defined in
Section 4.6.1, that can be used for simple merge operations. It Section 4.6.1, that can be used for simple merge operations. It
has a representation with the media-type "application/ has a representation with the media-type "application/yang-data"
yang-data+xml" or "application/yang-data+json". 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 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
NETCONF Capability URI, and advertised with an entry in the NETCONF Capability URI, and advertised with an entry in the
"capability" leaf-list in Section 9.3. "capability" leaf-list in Section 9.3.
o RESTCONF client: a client which implements the RESTCONF protocol. o RESTCONF client: a client which implements the RESTCONF protocol.
skipping to change at page 9, line 48 skipping to change at page 10, line 8
event stream resources available from the server. This event stream resources available from the server. This
information is defined in the "ietf-restconf-monitoring" module as information is defined in the "ietf-restconf-monitoring" module as
the "stream" list. It can be retrieved using the target resource the "stream" list. It can be retrieved using the target resource
"{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/ "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/
stream". The stream list contains information about each stream, stream". The stream list contains information about each stream,
such as the URL to retrieve the event stream data. such as the URL to retrieve the event stream data.
o YANG data template: a schema for modeling a conceptual data o YANG data template: a schema for modeling a conceptual data
structure in an encoding-independent manner. It is defined with structure in an encoding-independent manner. It is defined with
the "yang-data" extension, found in Section 8. It has a the "yang-data" extension, found in Section 8. It has a
representation with the media-type "application/yang-data+xml" or representation with the media-type "application/yang-data" or
"application/yang-data+json". "application/yang-data+json".
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 API entry point "{+restconf}" is used to refer to the RESTCONF API entry point
outside of an example. See Section 3.1 for details. outside of an example. See Section 3.1 for details.
For simplicity, all of the examples in this document assume "/ For simplicity, all of the examples in this document assume "/
restconf" as the discovered RESTCONF API root path. restconf" as the discovered RESTCONF API root path.
Many of the examples throughout the document are based on the Many of the examples throughout the document are based on the
"example-jukebox" YANG module, defined in Appendix C.1. "example-jukebox" YANG module, defined in Appendix C.1.
skipping to change at page 14, line 21 skipping to change at page 14, line 24
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
using a single HTTP/2 stream for all client requests from a stream.
The server MAY respond using same HTTP/2 stream that was used for the
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 the establishing a TLS connection with a RESTCONF client. The use the
X.509v3 based certificates is consistent with NETCONF over TLS X.509v3 based certificates is consistent with NETCONF over TLS
[RFC7589]. [RFC7589].
skipping to change at page 17, line 41 skipping to change at page 18, line 4
Cache-Control: no-cache Cache-Control: no-cache
Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT
Content-Type: application/yang-data+json Content-Type: application/yang-data+json
{ "operations" : { "example-jukebox:play" : [null] } } { "operations" : { "example-jukebox:play" : [null] } }
If the XRD contains more than one link relation, then only the If the XRD contains more than one link relation, then only the
relation named "restconf" is relevant to this specification. relation named "restconf" is relevant to this specification.
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"
yang-data+xml" media-type is defined in Section 11.3.1. The media-type is defined in Section 11.3.1. The "application/
"application/yang-data+json" media-type is defined in Section 11.3.2. 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 entry points for the RESTCONF datastore The API resource contains the entry points for the RESTCONF datastore
and operation resources. It is the top-level resource located at and operation resources. It is the top-level resource located at
{+restconf} and has the media type "application/yang-data+xml" or {+restconf} and has the media type "application/yang-data" or
"application/yang-data+json". "application/yang-data+json".
YANG Tree Diagram for an API Resource: YANG Tree Diagram for an API Resource:
+--rw restconf +--rw restconf
+--rw data +--rw data
+--rw operations +--rw operations
+--ro yang-library-version +--ro yang-library-version
The "yang-api" YANG data template is defined with the "yang-data" The "yang-api" YANG data template is defined with the "yang-data"
skipping to change at page 19, line 12 skipping to change at page 19, line 21
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
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:30 GMT Date: Mon, 23 Apr 2012 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
<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 20, line 4 skipping to change at page 20, line 13
Operation resources are defined in Section 3.6. Operation resources are defined in Section 3.6.
3.3.3. {+restconf}/yang-library-version 3.3.3. {+restconf}/yang-library-version
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.
[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.]
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
The server might respond (response wrapped for display purposes): The server might respond (response wrapped for display purposes):
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:30 GMT Date: Mon, 23 Apr 2012 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
<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-04-09 2016-04-09
</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
type, which is a collection of configuration data and state data type, which is a collection of configuration data and state data
skipping to change at page 21, line 14 skipping to change at page 21, line 24
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 is returned in the response for a ([RFC7232], Section 2.2) header is returned in the response for a
retrieval request. The "If-Unmodified-Since" header can be used in retrieval request. The "If-Unmodified-Since" header can be used in
edit operation requests to cause the server to reject the request if edit operation requests to cause the server to reject the request if
the resource has been modified since the specified timestamp. the resource has been modified since the specified timestamp.
The server SHOULD maintain a last-modified timestamp for the The server SHOULD maintain a last-modified timestamp for the
datastore resource. This timestamp is only affected by configuration datastore resource, defined in Section 3.4. This timestamp is only
child data resources, and MUST NOT be updated for changes to non- affected by configuration child data resources, and MUST NOT be
configuration child data resources. updated for changes to non-configuration child data resources. Last-
modified timestamps for data resources are discussed in Section 3.5.
If the RESTCONF server is colocated with a NETCONF server, then the If the RESTCONF server is colocated with a NETCONF server, then the
last-modified timestamp MUST represent the "running" datastore. last-modified timestamp MUST represent the "running" datastore.
3.4.1.2. Entity tag 3.4.1.2. Entity tag
A unique opaque string is maintained and the "ETag" ([RFC7232], A unique opaque string is maintained and the "ETag" ([RFC7232],
Section 2.3) header is returned in the response for a retrieval Section 2.3) header is returned in the response for a retrieval
request. The "If-Match" header can be used in edit operation request. The "If-Match" header can be used in edit operation
requests to cause the server to reject the request if the resource requests to cause the server to reject the request if the resource
entity tag does not match the specified value. entity tag does not match the specified value.
The server MUST maintain an entity tag for the top-level {+restconf}/ The server MUST maintain an entity tag for the top-level {+restconf}/
data resource. This entity tag is only affected by configuration data resource. This entity tag is only affected by configuration
data resources, and MUST NOT be updated for changes to non- data resources, and MUST NOT be updated for changes to non-
configuration data. configuration data. Entity tags for data resources are discussed in
Section 3.5.
If the RESTCONF server is colocated with a NETCONF server, then this If the RESTCONF server is colocated with a NETCONF server, then this
entity tag MUST represent the "running" datastore. entity tag MUST represent the "running" datastore.
3.4.1.3. Update Procedure 3.4.1.3. Update Procedure
Changes to configuration data resources affect the timestamp and Changes to configuration data resources affect the timestamp and
entity tag to that resource, any ancestor data resources, and the entity tag to that resource, any ancestor data resources, and the
datastore resource. datastore resource.
For example, an edit to disable an interface might be done by setting For example, an edit to disable an interface might be done by setting
the leaf "/interfaces/interface/enabled" to "false". The "enabled" the leaf "/interfaces/interface/enabled" to "false". The "enabled"
data node and its ancestors (one "interface" list instance, and the data node and its ancestors (one "interface" list instance, and the
"interfaces" container) are considered to be changed. The datastore "interfaces" container) are considered to be changed. The datastore
is considered to be changed when any top-level configuration data is considered to be changed when any top-level configuration data
node is changed (e.g., "interfaces"). node is changed (e.g., "interfaces").
skipping to change at page 27, line 36 skipping to change at page 28, line 4
where <data-resource-identifier> contains the path to the data node where <data-resource-identifier> contains the path to the data node
where the action is defined, and <action> is the name of the action. where the action is defined, and <action> is the name of the action.
For example, if "module-A" defined a "reset-all" action in the For example, if "module-A" defined a "reset-all" action in the
container "interfaces", then invoking this action would be requested container "interfaces", then invoking this action would be requested
as follows: as follows:
POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1
Server: example.com Server: example.com
If the "rpc" or "action" statement has an "input" section then If the "rpc" or "action" statement has an "input" section then
instances of these input parameters are encoded in the module instances of these input parameters are encoded in the module
namespace where the "rpc" or "action" statement is defined, in an XML namespace where the "rpc" or "action" statement is defined, in an XML
element or JSON object named "input". element or JSON object named "input", which is in the module
namespace where the "rpc" or "action" statement is defined.
If the "rpc" or "action" statement has an "input" section and the If the "rpc" or "action" statement has an "input" section and the
"input" object tree contains any child data nodes which are "input" object tree contains any child data nodes which are
considered mandatory nodes, then a message-body MUST be sent by the considered mandatory nodes, then a message-body MUST be sent by the
client in the request. client in the request.
If the "rpc" or "action" statement has an "input" section and the If the "rpc" or "action" statement has an "input" section and the
"input" object tree does not contain any child nodes which are "input" object tree does not contain any child nodes which are
considered mandatory nodes, then a message-body MAY be sent by the considered mandatory nodes, then a message-body MAY be sent by the
client in the request. client in the request.
If the "rpc" or "action" statement has no "input" section, the If the "rpc" or "action" statement has no "input" section, the
request message MUST NOT include a message-body. request message MUST NOT include a message-body.
If the "rpc" or "action" statement has an "output" section then If the "rpc" or "action" statement has an "output" section then
instances of these input parameters are encoded in the module instances of these output parameters are encoded in the module
namespace where the "rpc" or "action" statement is defined, in an XML namespace where the "rpc" or "action" statement is defined, in an XML
element or JSON object named "output". element or JSON object named "output", which is in the module
namespace where the "rpc" or "action" statement is defined.
If the RPC operation is invoked without errors, and if the "rpc" or If the RPC operation is invoked without errors, and if the "rpc" or
"action" statement has an "output" section and the "output" object "action" statement has an "output" section and the "output" object
tree contains any child data nodes which are considered mandatory tree contains any child data nodes which are considered mandatory
nodes, then a response message-body MUST be sent by the server in the nodes, then a response message-body MUST be sent by the server in the
response. response.
If the RPC operation is invoked without errors, and if the "rpc" or If the RPC operation is invoked without errors, and if the "rpc" or
"action" statement has an "output" section and the "output" object "action" statement has an "output" section and the "output" object
tree does not contain any child nodes which are considered mandatory tree does not contain any child nodes which are considered mandatory
skipping to change at page 28, line 46 skipping to change at page 29, line 15
All operation resources representing RPC operations supported by the All operation resources representing RPC operations supported by the
server MUST be identified in the {+restconf}/operations subtree server MUST be identified in the {+restconf}/operations subtree
defined in Section 3.3.2. Operation resources representing YANG defined in Section 3.3.2. Operation resources representing YANG
actions are not identified in this subtree since they are invoked actions are not identified in this subtree since they are invoked
using a URI within the {+restconf}/data subtree. using a URI within the {+restconf}/data subtree.
3.6.1. Encoding Operation Resource Input Parameters 3.6.1. Encoding Operation Resource Input Parameters
If the "rpc" or "action" statement has an "input" section, then the If the "rpc" or "action" statement has an "input" section, then the
"input" node is provided in the message-body, corresponding to the "input" node is provided in the message-body, corresponding to the
YANG data definition statements within the "input" section. YANG data definition statements within the "input" section. The
"input" node is defined to be in the namespace of the module
containing the "rpc" or "action" statement.
Examples: Examples:
The following YANG module is used for the RPC operation examples in The following YANG module is used for the RPC operation examples in
this section. this section.
module example-ops { module example-ops {
namespace "https://example.com/ns/example-ops"; namespace "https://example.com/ns/example-ops";
prefix "ops"; prefix "ops";
revision "2016-03-10";
organization "Example, Inc.";
contact "support at example.com";
description "Example Operations Data Model Module";
revision "2016-07-07" {
description "Initial version.";
reference "example.com document 3-3373";
}
rpc reboot { rpc reboot {
input { input {
leaf delay { leaf delay {
units seconds; units seconds;
type uint32; type uint32;
default 0; default 0;
} }
leaf message { type string; } leaf message { type string; }
leaf language { type string; } leaf language { type string; }
skipping to change at page 29, line 42 skipping to change at page 30, line 20
} }
The following YANG module is used for the YANG action examples in The following YANG module is used for the YANG action examples in
this section. this section.
module example-actions { module example-actions {
yang-version 1.1; yang-version 1.1;
namespace "https://example.com/ns/example-actions"; namespace "https://example.com/ns/example-actions";
prefix "act"; prefix "act";
import ietf-yang-types { prefix yang; } import ietf-yang-types { prefix yang; }
organization "Example, Inc.";
contact "support at example.com";
description "Example Actions Data Model Module";
revision "2016-07-07" {
description "Initial version.";
reference "example.com document 2-9973";
}
revision "2016-03-10"; revision "2016-03-10";
container interfaces { container interfaces {
list interface { list interface {
key name; key name;
leaf name { type string; } leaf name { type string; }
action reset { action reset {
input { input {
leaf delay { leaf delay {
skipping to change at page 30, line 31 skipping to change at page 31, line 20
} }
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
<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 31, line 20 skipping to change at page 32, line 8
} }
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 (text wrap for display purposes): the "reset" action (text wrap for display purposes):
POST /restconf/data/example-actions:interfaces/interface=eth0 POST /restconf/data/example-actions:interfaces/interface=eth0
/reset HTTP/1.1 /reset HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data+xml Content-Type: application/yang-data
<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 2012 11:01:00 GMT Date: Mon, 25 Apr 2012 11:01:00 GMT
Server: example-server Server: example-server
skipping to change at page 31, line 49 skipping to change at page 32, line 37
{ "example-actions:input" : { { "example-actions:input" : {
"delay" : 600 "delay" : 600
} }
} }
3.6.2. Encoding Operation Resource Output Parameters 3.6.2. Encoding Operation Resource Output Parameters
If the "rpc" or "action" statement has an "output" section, then the If the "rpc" or "action" statement has an "output" section, then the
"output" node is provided in the message-body, corresponding to the "output" node is provided in the message-body, corresponding to the
YANG data definition statements within the "output" section. YANG data definition statements within the "output" section. The
"output" node is defined to be in the namespace of the module
containing the "rpc" or "action" statement.
The request URI is not returned in the response. This URI might have The request URI is not returned in the response. This URI might have
context information required to associate the output to the specific context information required to associate the output to the specific
"rpc" or "action" statement used in the request. "rpc" or "action" statement used in the request.
Examples: Examples:
RPC Output Example: RPC Output Example:
The "example-ops" YANG module defined in Section 3.6.1 is used for The "example-ops" YANG module defined in Section 3.6.1 is used for
skipping to change at page 32, line 43 skipping to change at page 33, 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 2012 11:10:30 GMT Date: Mon, 25 Apr 2012 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+xml Content-Type: application/yang-data
<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 33, line 40 skipping to change at page 34, line 28
If any errors occur while attempting to invoke the operation or If any errors occur while attempting to invoke the operation or
action, then an "errors" media type is returned with the appropriate action, then an "errors" media type is returned with the appropriate
error status. error status.
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
<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 2012 11:10:30 GMT Date: Mon, 25 Apr 2012 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+xml Content-Type: application/yang-data
<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 38, line 50 skipping to change at page 39, line 45
detection via the Last-Modified or ETag values. detection via the Last-Modified or ETag values.
Example: Example:
The client might request the response headers for an XML The client might request the response headers for an XML
representation of the 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
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:02:40 GMT Date: Mon, 23 Apr 2012 17:02:40 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+xml Content-Type: application/yang-data
Cache-Control: no-cache Cache-Control: no-cache
ETag: "a74eefc993a2b" ETag: "a74eefc993a2b"
Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT Last-Modified: Mon, 23 Apr 2012 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>
skipping to change at page 43, line 8 skipping to change at page 43, line 51
Date: Mon, 23 Apr 2012 17:04:00 GMT Date: Mon, 23 Apr 2012 17:04:00 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT Last-Modified: Mon, 23 Apr 2012 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
<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
RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide
an extensible framework for resource patching mechanisms. It is an extensible framework for resource patching mechanisms. It is
optional to implement by the server. Each patch mechanism needs a optional to implement by the server. Each patch mechanism needs a
unique media type. Zero or more patch media types MAY be supported unique media type. Zero or more patch media types MAY be supported
by the server. The media types supported by a server can be by the server. The media types supported by a server can be
discovered by the client by sending an OPTIONS request (see discovered by the client by sending an OPTIONS request, and examining
Section 4.1). the Accept-Patch header field in the response. (see Section 4.1).
This document defines one patch mechanism (Section 4.6.1). Another This document defines one patch mechanism (Section 4.6.1). Another
patch mechanism, the YANG PATCH mechanism, is defined in patch mechanism, the YANG PATCH mechanism, is defined in
[I-D.ietf-netconf-yang-patch]. Other patch mechanisms may be defined [I-D.ietf-netconf-yang-patch]. Other patch mechanisms may be defined
by future specifications. by future specifications.
If the target resource instance does not exist, the server MUST NOT If the target resource instance does not exist, the server MUST NOT
create it. create it.
If the PATCH request succeeds, a "200 OK" status-line is returned if If the PATCH request succeeds, a "200 OK" status-line is returned if
skipping to change at page 43, line 50 skipping to change at page 44, line 44
response containing a "403 Forbidden" status-line SHOULD be returned. response containing a "403 Forbidden" status-line SHOULD be returned.
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]. All other error responses are handled section 6.5.3 in [RFC7231]. All other error responses are handled
according to the procedures defined in Section 7. according 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" 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 operation. PATCH operation.
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 44, line 30 skipping to change at page 45, line 23
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. Note that the request-line is wrapped send a plain patch as follows. Note that the request-line is wrapped
for display purposes only: for display purposes only:
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
<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 2012 17:49:30 GMT Date: Mon, 23 Apr 2012 17:49:30 GMT
Server: example-server Server: example-server
skipping to change at page 47, line 33 skipping to change at page 48, line 18
The value of the "depth" parameter is either an integer between 1 and The value of the "depth" parameter is either an integer between 1 and
65535, or the string "unbounded". "unbounded" is the default. 65535, or the string "unbounded". "unbounded" is the default.
This parameter is only allowed for GET methods on API, datastore, and This parameter is only allowed for GET methods on API, datastore, and
data resources. A "400 Bad Request" status-line is returned if it data resources. A "400 Bad Request" status-line is returned if it
used for other methods or resource types. used for other methods or resource types.
By default, the server will include all sub-resources within a By default, the server will include all sub-resources within a
retrieved resource, which have the same resource type as the retrieved resource, which have the same resource type as the
requested resource. Only one level of sub-resources with a different requested resource. The exception is the datastore resource. If
media type than the target resource will be returned. The exception this resource type is retrieved then by default the datastore and all
is the datastore resource. If this resource type is retrieved then child data resources are returned.
by default the datastore and all child data resources are returned.
If the "depth" query parameter URI is listed in the "capability" If the "depth" query parameter URI is listed in the "capability"
leaf-list in Section 9.3, then the server supports the "depth" query leaf-list in Section 9.3, then the server supports the "depth" query
parameter. parameter.
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
skipping to change at page 55, line 35 skipping to change at page 56, line 19
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
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 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+xml Content-Type: application/yang-data
<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
Note that RFC 6243 defines the "default" attribute with XSD, not Note that RFC 6243 defines the "default" attribute with XSD, not
YANG, so the YANG module name has to be assigned manually. The value YANG, so the YANG module name has to be assigned instead of derived
"ietf-netconf-with-defaults" is assigned for JSON metadata encoding. from the YANG module name. The value "ietf-netconf-with-defaults" is
assigned for JSON metadata encoding.
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+json Accept: application/yang-data+json
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 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
skipping to change at page 57, line 52 skipping to change at page 58, line 36
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
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
<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
skipping to change at page 59, line 32 skipping to change at page 60, line 18
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 notification stream. resource. These parameters are specific to each notification 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
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
<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
skipping to change at page 63, line 9 skipping to change at page 63, line 41
and an action is defined with a YANG "action" statement, a mapping and an action is defined with a YANG "action" statement, a mapping
between the NETCONF <error-tag> value and the HTTP status code is between the NETCONF <error-tag> value and the HTTP status code is
needed. The specific error-tag and response code to use are data- needed. The specific error-tag and response code to use are data-
model specific and might be contained in the YANG "description" model specific and might be contained in the YANG "description"
statement for the "action" or "rpc" statement. statement for the "action" or "rpc" statement.
+-------------------------+-------------+ +-------------------------+-------------+
| error-tag | status code | | error-tag | status code |
+-------------------------+-------------+ +-------------------------+-------------+
| in-use | 409 | | in-use | 409 |
| invalid-value | 400 | | invalid-value | 400 or 406 |
| (request) too-big | 413 | | (request) too-big | 413 |
| (response) too-big | 400 | | (response) too-big | 400 |
| missing-attribute | 400 | | missing-attribute | 400 |
| bad-attribute | 400 | | bad-attribute | 400 |
| unknown-attribute | 400 | | unknown-attribute | 400 |
| bad-element | 400 | | bad-element | 400 |
| unknown-element | 400 | | unknown-element | 400 |
| unknown-namespace | 400 | | unknown-namespace | 400 |
| access-denied | 403 | | access-denied | 403 |
| lock-denied | 409 | | lock-denied | 409 |
| resource-denied | 409 | | resource-denied | 409 |
| rollback-failed | 500 | | rollback-failed | 500 |
| data-exists | 409 | | data-exists | 409 |
| data-missing | 409 | | data-missing | 409 |
| operation-not-supported | 501 | | operation-not-supported | 501 |
| operation-failed | 500 | | operation-failed | 412 or 500 |
| partial-operation | 500 | | partial-operation | 500 |
| malformed-message | 400 | | malformed-message | 400 |
+-------------------------+-------------+ +-------------------------+-------------+
Mapping from error-tag to status code Mapping from error-tag to status code
7.1. Error Response Message 7.1. Error Response Message
When an error occurs for a request message on any resource type, and When an error occurs for a request message on any resource type, and
the status code that will be returned is in the "4xx" range (except the status code that will be returned is in the "4xx" range (except
skipping to change at page 63, line 48 skipping to change at page 64, line 32
"yang-errors" YANG template definition within the "ietf-restconf" "yang-errors" YANG template definition within the "ietf-restconf"
module, found in Section 8. The Content-Type of this response module, found in Section 8. The Content-Type of this response
message MUST be a subtype of application/yang-data (see example message MUST be a subtype of application/yang-data (see example
below). below).
The client SHOULD specify the desired encoding for error messages by The client SHOULD specify the desired encoding for error messages by
specifying the appropriate media-type in the Accept header. If no specifying the appropriate media-type in the Accept header. If no
error media is specified, then the media subtype (e.g., XML or JSON) error media is specified, then the media subtype (e.g., XML or JSON)
of the request message SHOULD be used, or the server MAY choose any of the request message SHOULD be used, or the server MAY choose any
supported message encoding format. If there is no request message supported message encoding format. If there is no request message
the server MUST select "application/yang-data+xml" or "application/ the server MUST select "application/yang-data" or "application/
yang-data+json", depending on server preference. All of the examples yang-data+json", depending on server preference. All of the examples
in this document, except for the one below, assume that XML encoding in this document, except for the one below, assume that XML encoding
will be returned if there is an error. will be returned if there is an error.
YANG Tree Diagram for <errors> data: YANG Tree Diagram for <errors> data:
+--ro errors +--ro errors
+--ro error* +--ro error*
+--ro error-type enumeration +--ro error-type enumeration
+--ro error-tag string +--ro error-tag string
skipping to change at page 65, line 19 skipping to change at page 65, line 50
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 (some lines wrapped for display purposes): The server might respond (some lines wrapped for display purposes):
HTTP/1.1 409 Conflict HTTP/1.1 409 Conflict
Date: Mon, 23 Apr 2012 17:11:00 GMT Date: Mon, 23 Apr 2012 17:11:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+xml Content-Type: application/yang-data
<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>
<error-message> <error-message>
skipping to change at page 65, line 50 skipping to change at page 66, line 33
datastore contents by a server. E.g., the "restconf" container is datastore contents by a server. E.g., the "restconf" container is
not intended to be implemented as a top-level data node (under the "/ not intended to be implemented as a top-level data node (under the "/
restconf/data" entry point). restconf/data" entry point).
Note that the "ietf-restconf" module does not have any protocol- Note that the "ietf-restconf" module does not have any protocol-
accessible objects, so no YANG tree diagram is shown. accessible objects, so no YANG tree diagram is shown.
RFC Ed.: update the date below with the date of RFC publication and RFC Ed.: update the date below with the date of RFC publication and
remove this note. remove this note.
<CODE BEGINS> file "ietf-restconf@2016-06-28.yang" <CODE BEGINS> file "ietf-restconf@2016-07-07.yang"
module ietf-restconf { module ietf-restconf {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; namespace "urn:ietf:params:xml:ns:yang:ietf-restconf";
prefix "rc"; prefix "rc";
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
contact contact
"WG Web: <http://tools.ietf.org/wg/netconf/> "WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org> WG List: <mailto:netconf@ietf.org>
WG Chair: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com>
WG Chair: Mahesh Jethanandani
<mailto:mjethanandani@gmail.com>
Editor: Andy Bierman Editor: Andy Bierman
<mailto:andy@yumaworks.com> <mailto:andy@yumaworks.com>
Editor: Martin Bjorklund Editor: Martin Bjorklund
<mailto:mbj@tail-f.com> <mailto:mbj@tail-f.com>
Editor: Kent Watsen Editor: Kent Watsen
<mailto:kwatsen@juniper.net>"; <mailto:kwatsen@juniper.net>";
description description
skipping to change at page 67, line 10 skipping to change at page 67, line 36
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-14.txt // Note: extracted from draft-ietf-netconf-restconf-15.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-06-28 { revision 2016-07-07 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
extension yang-data { extension yang-data {
argument name { argument name {
yin-element true; yin-element true;
} }
skipping to change at page 72, line 36 skipping to change at page 73, line 26
+--ro location inet:uri +--ro location inet:uri
9.1. restconf-state/capabilities 9.1. restconf-state/capabilities
This mandatory container holds the RESTCONF protocol capability URIs This mandatory container holds the RESTCONF protocol capability URIs
supported by the server. supported by the server.
The server MAY maintain a last-modified timestamp for this container, The server MAY maintain a last-modified timestamp for this container,
and return the "Last-Modified" header when this data node is and return the "Last-Modified" header when this data node is
retrieved with the GET or HEAD methods. Note that the last-modified retrieved with the GET or HEAD methods. Note that the last-modified
timestamp for the datastore resource is not affected by changes this timestamp for the datastore resource is not affected by changes to
subtree. this subtree.
The server SHOULD maintain an entity-tag for this container, and The server SHOULD maintain an entity-tag for this container, and
return the "ETag" header when this data node is retrieved with the return the "ETag" header when this data node is retrieved with the
GET or HEAD methods. Note that the entity-tag for the datastore GET or HEAD methods. Note that the entity-tag for the datastore
resource is not affected by changes this subtree. resource is not affected by changes to this subtree.
The server MUST include a "capability" URI leaf-list entry for the The server MUST include a "capability" URI leaf-list entry for the
"defaults" mode used by the server, defined in Section 9.1.2. "defaults" mode used by the server, defined in Section 9.1.2.
The server MUST include a "capability" URI leaf-list entry The server MUST include a "capability" URI leaf-list entry
identifying each supported optional protocol feature. This includes identifying each supported optional protocol feature. This includes
optional query parameters and MAY include other capability URIs optional query parameters and MAY include other capability URIs
defined outside this document. defined outside this document.
9.1.1. Query Parameter URIs 9.1.1. Query Parameter URIs
skipping to change at page 75, line 5 skipping to change at page 75, line 42
The "ietf-restconf-monitoring" module defines monitoring information The "ietf-restconf-monitoring" module defines monitoring information
for the RESTCONF protocol. for the RESTCONF protocol.
The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991]
are used by this module for some type definitions. are used by this module for some type definitions.
RFC Ed.: update the date below with the date of RFC publication and RFC Ed.: update the date below with the date of RFC publication and
remove this note. remove this note.
<CODE BEGINS> file "ietf-restconf-monitoring@2016-06-28.yang" <CODE BEGINS> file "ietf-restconf-monitoring@2016-07-07.yang"
module ietf-restconf-monitoring { module 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";
import ietf-yang-types { prefix yang; } import ietf-yang-types { prefix yang; }
import ietf-inet-types { prefix inet; } import ietf-inet-types { prefix inet; }
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
contact contact
"WG Web: <http://tools.ietf.org/wg/netconf/> "WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org> WG List: <mailto:netconf@ietf.org>
WG Chair: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com>
WG Chair: Mahesh Jethanandani
<mailto:mjethanandani@gmail.com>
Editor: Andy Bierman Editor: Andy Bierman
<mailto:andy@yumaworks.com> <mailto:andy@yumaworks.com>
Editor: Martin Bjorklund Editor: Martin Bjorklund
<mailto:mbj@tail-f.com> <mailto:mbj@tail-f.com>
Editor: Kent Watsen Editor: Kent Watsen
<mailto:kwatsen@juniper.net>"; <mailto:kwatsen@juniper.net>";
description description
skipping to change at page 76, line 9 skipping to change at page 76, line 39
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-14.txt // Note: extracted from draft-ietf-netconf-restconf-15.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-06-28 { revision 2016-07-07 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
container restconf-state { container restconf-state {
config false; config false;
description description
"Contains RESTCONF protocol monitoring information."; "Contains RESTCONF protocol monitoring information.";
skipping to change at page 77, line 41 skipping to change at page 78, line 24
"RFC 5277, Section 3.4, <replayLogCreationTime> "RFC 5277, Section 3.4, <replayLogCreationTime>
element."; element.";
} }
list access { list access {
key encoding; key encoding;
min-elements 1; min-elements 1;
description description
"The server will create an entry in this list for each "The server will create an entry in this list for each
encoding format that is supported for this stream. encoding format that is supported for this stream.
The media type 'application/yang-stream' is expected The media type 'text/event-stream' is expected
for all event streams. This list identifies the for all event streams. This list identifies the
sub-types supported for this stream."; sub-types supported for this stream.";
leaf encoding { leaf encoding {
type string; type string;
description description
"This is the secondary encoding format within the "This is the secondary encoding format within the
'text/event-stream' encoding used by all streams. 'text/event-stream' encoding used by all streams.
The type 'xml' is supported for the media type The type 'xml' is supported for XML encoding.
'application/yang-stream+xml'. The type 'json' The type 'json' is supported for JSON encoding.";
is supported for the media type
'application/yang-stream+json'.";
} }
leaf location { leaf location {
type inet:uri; type inet:uri;
mandatory true; mandatory true;
description description
"Contains a URL that represents the entry point "Contains a URL that represents the entry point
for establishing notification delivery via server for establishing notification delivery via server
sent events."; sent events.";
} }
skipping to change at page 79, line 21 skipping to change at page 80, line 7
defines the root of the API defined in RFCXXXX. defines the root of the API defined in RFCXXXX.
Subsequent revisions of RESTCONF will use alternate Subsequent revisions of RESTCONF will use alternate
relation values to support protocol versioning. relation values to support protocol versioning.
Reference: RFCXXXX Reference: RFCXXXX
` `
11.2. YANG Module Registry 11.2. YANG Module Registry
This document registers two URIs as namesapces in the IETF XML This document registers two URIs as namespaces in the IETF XML
registry [RFC3688]. Following the format in RFC 3688, the following registry [RFC3688]. Following the format in RFC 3688, the following
registration is requested: registration is requested:
URI: urn:ietf:params:xml:ns:yang:ietf-restconf URI: urn:ietf:params:xml:ns:yang:ietf-restconf
Registrant Contact: The NETMOD WG of the IETF. Registrant Contact: The NETMOD WG of the IETF.
XML: N/A, the requested URI is an XML namespace. XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
Registrant Contact: The NETMOD WG of the IETF. Registrant Contact: The NETMOD WG of the IETF.
XML: N/A, the requested URI is an XML namespace. XML: N/A, the requested URI is an XML namespace.
skipping to change at page 79, line 50 skipping to change at page 80, line 36
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
Type name: application Type name: application
Subtype name: yang-data+xml Subtype name: yang-data
Required parameters: none Required parameters: None
Optional parameters: none Optional parameters: None
// RFC Ed.: replace draft-ietf-netmod-rfc6020bis with // RFC Ed.: replace draft-ietf-netmod-rfc6020bis with
// the actual RFC reference for YANG 1.1, and remove this note. // 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 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 [draft-ietf-netmod-rfc6020bis].
// 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
semantics of particular YANG data models. Each YANG module semantics of particular YANG data models. Each YANG module
is expected to specify security considerations for the is expected to specify security considerations for the
YANG data defined in that module. YANG data defined in that module.
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
Interoperability considerations: [RFCXXXX] specifies format of Interoperability considerations: [RFCXXXX] specifies the
conforming messages and the interpretation thereof. format of conforming messages and the interpretation
thereof.
// 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 utilizes YANG defined data structures. that utilize YANG defined data structures.
Fragment identifier considerations: The fragment field in the Fragment identifier considerations: The fragment field in the
request URI has no defined purpose. request URI has no defined purpose.
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.
Person & email address to contact for further information: See Person & email address to contact for further information: See
Authors' Addresses section of [RFCXXXX]. Authors' Addresses section of [RFCXXXX].
Intended usage: COMMON Intended usage: COMMON
(One of COMMON, LIMITED USE, or OBSOLETE.) Restrictions on usage: N/A
Restrictions on usage: n/a
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
Author: See Authors' Addresses section of [RFCXXXX]. Author: See Authors' Addresses section of [RFCXXXX].
Change controller: Internet Engineering Task Force Change controller: Internet Engineering Task Force
(mailto:iesg&ietf.org). (mailto:iesg&ietf.org).
Provisional registration? (standards tree only): no Provisional registration? (standards tree only): no
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 // RFC Ed.: replace draft-ietf-netmod-yang-json with
// the actual RFC reference for JSON Encoding of YANG Data, // the actual RFC reference for JSON Encoding of YANG Data,
// and remove this note. // and remove this note.
// RFC Ed.: replace draft-ietf-netmod-yang-metadata with // RFC Ed.: replace draft-ietf-netmod-yang-metadata with
// the actual RFC reference for JSON Encoding of YANG Data, // the actual RFC reference for JSON Encoding of YANG Data,
// and remove this note. // and remove this note.
Encoding considerations: 8-bit Encoding considerations: 8-bit
skipping to change at page 82, line 22 skipping to change at page 83, line 5
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
semantics of particular YANG data models. Each YANG module semantics of particular YANG data models. Each YANG module
is expected to specify security considerations for the is expected to specify security considerations for the
YANG data defined in that module. YANG data defined in that module.
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
Interoperability considerations: [RFCXXXX] specifies format of Interoperability considerations: [RFCXXXX] specifies the format
conforming messages and the interpretation thereof. of conforming messages and the interpretation thereof.
// 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 utilizes YANG defined data structures. that utilize YANG defined data structures.
Fragment identifier considerations: The fragment field in the Fragment identifier considerations: The syntax and semantics
request URI has no defined purpose. of fragment identifiers are the same as specified for the
"application/json" media type.
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): .json File extension(s): .json
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.
Person & email address to contact for further information: See Person & email address to contact for further information: See
Authors' Addresses section of [RFCXXXX]. Authors' Addresses section of [RFCXXXX].
Intended usage: COMMON Intended usage: COMMON
(One of COMMON, LIMITED USE, or OBSOLETE.)
Restrictions on usage: n/a Restrictions on usage: N/A
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
Author: See Authors' Addresses section of [RFCXXXX]. Author: See Authors' Addresses section of [RFCXXXX].
Change controller: Internet Engineering Task Force Change controller: Internet Engineering Task Force
(mailto:iesg&ietf.org). (mailto:iesg&ietf.org).
Provisional registration? (standards tree only): no Provisional registration? (standards tree only): no
skipping to change at page 84, line 15 skipping to change at page 84, line 50
:replay :replay
urn:ietf:params:restconf:capability:replay:1.0 urn:ietf:params:restconf:capability:replay:1.0
:with-defaults :with-defaults
urn:ietf:params:restconf:capability:with-defaults:1.0 urn:ietf:params:restconf:capability:with-defaults:1.0
12. Security Considerations 12. Security Considerations
The "ietf-restconf-monitoring" YANG module defined in this memo is The "ietf-restconf-monitoring" YANG module defined in this memo is
designed to be accessed via the NETCONF protocol [RFC6241]. designed to be accessed via the NETCONF protocol [RFC6241]. The
lowest NETCONF layer is the secure transport layer, and the
mandatory-to-implement secure transport is Secure Shell (SSH)
The lowest NETCONF layer is the secure transport layer, [RFC6242]. The NETCONF access control model [RFC6536] provides the
and the mandatory-to-implement secure transport is Secure Shell means to restrict access for particular NETCONF users to a pre-
(SSH) ^RFC6242^. The NETCONF access control model ^RFC6536^ configured subset of all available NETCONF protocol operations and
provides the means to restrict access for particular NETCONF users content.
to a pre-configured subset of all available NETCONF protocol
operations and content.
This section provides security considerations for the resources This section provides security considerations for the resources
defined by the RESTCONF protocol. Security considerations for HTTPS defined by the RESTCONF protocol. Security considerations for HTTPS
are defined in [RFC7230]. RESTCONF does not specify which YANG are defined in [RFC7230]. RESTCONF does not specify which YANG
modules a server needs to support. Security considerations for the modules a server needs to support. Security considerations for the
YANG-defined content manipulated by RESTCONF can be found in the YANG-defined content manipulated by RESTCONF can be found in the
documents defining those YANG modules. documents defining those YANG modules.
This document does not require use of a specific client This document does not require use of a specific client
authentication mechanism or authorization model, but it does require authentication mechanism or authorization model, but it does require
skipping to change at page 85, line 6 skipping to change at page 85, line 40
names, service descriptions, and topological information, all of names, service descriptions, and topological information, all of
which are sensitive. Because of this, this protocol SHOULD be which are sensitive. Because of this, this protocol SHOULD be
implemented carefully with adequate attention to all manner of attack implemented carefully with adequate attention to all manner of attack
one might expect to experience with other management interfaces. one might expect to experience with other management interfaces.
Different environments may well allow different rights prior to and Different environments may well allow different rights prior to and
then after authentication. When an operation is not properly then after authentication. When an operation is not properly
authorized, the RESTCONF server MUST return a "401 Unauthorized" authorized, the RESTCONF server MUST return a "401 Unauthorized"
status-line. Note that authorization information can be exchanged in status-line. Note that authorization information can be exchanged in
the form of configuration information, which is all the more reason the form of configuration information, which is all the more reason
to ensure the security of the connection. to ensure the security of the connection. Note that it is possible
for a client to detect configuration changes in data resources it is
not authorized to access by monitoring changes in the ETag and Last-
Modified header fields returned by the server for the datastore
resource.
13. Acknowledgements 13. Acknowledgements
The authors would like to thank the following people for their The authors would like to thank the following people for their
contributions to this document: Ladislav Lhotka, Juergen contributions to this document: Ladislav Lhotka, Juergen
Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford.
The authors would like to thank the following people for their The authors would like to thank the following people for their
excellent technical reviews of this document: Mehmet Ersue, Mahesh excellent technical reviews of this document: Mehmet Ersue, Mahesh
Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka, Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka,
Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint
Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise, and Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise, and
Dale Worley. Dale Worley.
Contributions to this material by Andy Bierman are based upon work Contributions to this material by Andy Bierman are based upon work
supported by the The Space & Terrestrial Communications Directorate supported by the United States Army, Space & Terrestrial
(S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings Communications Directorate (S&TCD) under Contract No.
and conclusions or recommendations expressed in this material are W15P7T-13-C-A616. Any opinions, findings and conclusions or
those of the author(s) and do not necessarily reflect the views of recommendations expressed in this material are those of the author(s)
The Space & Terrestrial Communications Directorate (S&TCD). and do not necessarily reflect the views of The Space & Terrestrial
Communications Directorate (S&TCD).
14. References 14. References
14.1. Normative References 14.1. Normative References
[I-D.ietf-netconf-yang-library] [I-D.ietf-netconf-yang-library]
Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
Library", draft-ietf-netconf-yang-library-06 (work in Library", draft-ietf-netconf-yang-library-06 (work in
progress), April 2016. progress), April 2016.
skipping to change at page 86, line 49 skipping to change at page 87, line 39
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509 within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer (PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, March 2011. Security (TLS)", RFC 6125, March 2011.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, June 2011. (NETCONF)", RFC 6241, June 2011.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<http://www.rfc-editor.org/info/rfc6242>.
[RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for
NETCONF", RFC 6243, June 2011. NETCONF", RFC 6243, June 2011.
[RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC
6415, October 2011. 6415, October 2011.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536, March Protocol (NETCONF) Access Control Model", RFC 6536, March
2012. 2012.
skipping to change at page 87, line 38 skipping to change at page 88, 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, RFC [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC
7320, July 2014. 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, DOI 10.17487/ Mutual X.509 Authentication", RFC 7589, DOI 10.17487/
RFC7589, June 2015, RFC7589, June 2015,
<http://www.rfc-editor.org/info/rfc7589>. <http://www.rfc-editor.org/info/rfc7589>.
[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,
skipping to change at page 88, line 38 skipping to change at page 89, line 40
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. v13 - v14 A.1. v14 to v15
o added text for HTTP/2 usage
o changed media type definitions per review comments
o added some clarifications and typos
o added error-tag mapping for 406 and 412 errors
A.2. 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'
o add term 'RESTCONF client' also called 'client' o add term 'RESTCONF client' also called 'client'
skipping to change at page 90, line 4 skipping to change at page 91, line 17
o clarified error info not returned for 1xx, 2xx, and 3xx ranges o clarified error info not returned for 1xx, 2xx, and 3xx ranges
o clarified operations description in ietf-restconf module o clarified operations description in ietf-restconf module
o clarified Acknowledgements section o clarified Acknowledgements section
o clarified some examples o clarified some examples
o update some references o update some references
o update RFC 2119 boilerplace
o update RFC 2119 boilerplate
o remove requirements that simply restate HTTP requirements o remove requirements that simply restate HTTP requirements
o remove Pragma: no-cache from examples since RFC 7234 says this o remove Pragma: no-cache from examples since RFC 7234 says this
pragma is not defined for responses pragma is not defined for responses
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
skipping to change at page 90, line 28 skipping to change at page 91, line 42
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.2. v12 - v13 A.3. 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.3. v11 - v12 A.4. 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
o made implementation of timestamps optional since ETags are o made implementation of timestamps optional since ETags are
skipping to change at page 91, line 14 skipping to change at page 92, line 28
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.4. v10 - v11 A.5. 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
skipping to change at page 91, line 42 skipping to change at page 93, line 9
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.5. v09 - v10 A.6. 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 93, line 40 skipping to change at page 95, 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.6. v08 - v09 A.7. 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.7. v07 - v08 A.8. 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
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.8. v06 - v07 A.9. 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.9. v05 - v06 A.10. v05 - v06
o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug)
A.10. v04 - v05 A.11. 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
o removed text about not immediate persistence of edits o removed text about not immediate persistence of edits
o removed RESTCONF-specific data-resource-identifier typedef and its o removed RESTCONF-specific data-resource-identifier typedef and its
usage usage
o clarified encoding of key leafs o clarified encoding of key leafs
skipping to change at page 95, line 33 skipping to change at page 97, 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.11. v03 - v04 A.12. 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 96, line 21 skipping to change at page 97, 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.12. v02 - v03 A.13. 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 96, line 33 skipping to change at page 98, 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.13. v01 - v02 A.14. 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)
o added 'capabilities' container to new YANG module (ietf-restconf- o added 'capabilities' container to new YANG module (ietf-restconf-
monitoring) monitoring)
o moved 'modules' container to new YANG module (ietf-yang-library) o moved 'modules' container to new YANG module (ietf-yang-library)
o added new leaf 'module-set-id' (ietf-yang-library) o added new leaf 'module-set-id' (ietf-yang-library)
o added new leaf 'conformance' (ietf-yang-library) o added new leaf 'conformance' (ietf-yang-library)
o changed 'schema' leaf to type inet:uri that returns the location o changed 'schema' leaf to type inet:uri that returns the location
skipping to change at page 97, line 31 skipping to change at page 99, 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.14. v00 - v01 A.15. 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 98, line 27 skipping to change at page 99, line 49
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.15. bierman:restconf-04 to ietf:restconf-00 A.16. 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
skipping to change at page 105, line 50 skipping to change at page 107, line 27
"operations" : {}, "operations" : {},
"yang-library-version" : "2016-04-09" "yang-library-version" : "2016-04-09"
} }
} }
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
The server will return the same response either way, which might be The server will return the same response either way, which might be
as follows : 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 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 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
<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-04-09</yang-library-version> <yang-library-version>2016-04-09</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 108, line 25 skipping to change at page 110, line 8
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
The server might respond as follows. The extra whitespace in The server might respond as follows. The extra whitespace in
'capability' elements is for display purposes only. 'capability' elements is for display purposes only.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:02:00 GMT Date: Mon, 23 Apr 2012 17:02:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT
Content-Type: application/yang-data+xml Content-Type: application/yang-data
<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 110, line 8 skipping to change at page 111, line 36
Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT Last-Modified: Mon, 23 Apr 2012 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. Note that the resource, the client might send the following request. Note that the
request URI header line is wrapped for display purposes only: request URI header line is wrapped for display purposes only:
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
<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.
Note that the "Location" header line is wrapped for display purposes Note that the "Location" header line is wrapped for display purposes
only: only:
skipping to change at page 110, line 30 skipping to change at page 112, line 10
Date: Mon, 23 Apr 2012 17:03:00 GMT Date: Mon, 23 Apr 2012 17:03:00 GMT
Server: example-server Server: example-server
Location: https://example.com/restconf/data/ Location: https://example.com/restconf/data/
example-jukebox:jukebox/library/artist=Foo%20Fighters/ example-jukebox:jukebox/library/artist=Foo%20Fighters/
album=Wasting%20Light album=Wasting%20Light
Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT
ETag: "b8389233a4c" ETag: "b8389233a4c"
D.2.2. Detect Resource Entity Tag Change D.2.2. Detect Resource Entity Tag Change
In this example, the server just supports the mandatory datastore In this example, the server just supports the datastore last-changed
last-changed timestamp. The client has previously retrieved the timestamp. The client has previously retrieved the "Last-Modified"
"Last-Modified" header and has some value cached to provide in the header and has some value cached to provide in the following request
following request to patch an "album" list entry with key value to patch an "album" list entry with key value "Wasting Light". Only
"Wasting Light". Only the "genre" field is being updated. the "genre" field is being updated.
PATCH /restconf/data/example-jukebox:jukebox/ PATCH /restconf/data/example-jukebox:jukebox/
library/artist=Foo%20Fighters/album=Wasting%20Light/genre library/artist=Foo%20Fighters/album=Wasting%20Light/genre
HTTP/1.1 HTTP/1.1
Host: example.com Host: example.com
If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT
Content-Type: application/yang-data+json Content-Type: application/yang-data+json
{ "example-jukebox:genre" : "example-jukebox:alternative" } { "example-jukebox:genre" : "example-jukebox:alternative" }
skipping to change at page 111, line 18 skipping to change at page 112, line 42
Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT
ETag: "b34aed893a4c" ETag: "b34aed893a4c"
D.2.3. Edit a Datastore Resource D.2.3. Edit a Datastore Resource
In this example, the client modifies two different data nodes by In this example, the client modifies two different data nodes by
sending a PATCH to the datastore resource: sending a PATCH to the datastore resource:
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
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<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>Wasting Light</name> <name>Wasting Light</name>
<year>2011</year> <year>2011</year>
</album> </album>
</artist> </artist>
<artist> <artist>
<name>Nick Cave and the Bad Seeds</name> <name>Nick Cave and the Bad Seeds</name>
<album> <album>
<name>Tender Prey</name> <name>Tender Prey</name>
<year>1988</year> <year>1988</year>
</album> </album>
</artist> </artist>
</library> </library>
skipping to change at page 111, line 49 skipping to change at page 113, line 26
</data> </data>
D.2.4. Edit a Data Resource D.2.4. Edit a Data Resource
In this example, the client modifies one data nodes by sending a In this example, the client modifies one data nodes by sending a
PATCH to the data resource (URI wrapped for display purposes only): PATCH to the data resource (URI wrapped for display purposes only):
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%Bad%20Seeds HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data+xml Content-Type: application/yang-data
<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
 End of changes. 132 change blocks. 
257 lines changed or deleted 296 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/