draft-ietf-netconf-restconf-13.txt   draft-ietf-netconf-restconf-14.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: October 29, 2016 Tail-f Systems Expires: December 30, 2016 Tail-f Systems
K. Watsen K. Watsen
Juniper Networks Juniper Networks
April 27, 2016 June 28, 2016
RESTCONF Protocol RESTCONF Protocol
draft-ietf-netconf-restconf-13 draft-ietf-netconf-restconf-14
Abstract Abstract
This document describes an HTTP-based protocol that provides a This document describes an HTTP-based protocol that provides a
programmatic interface for accessing data defined in YANG, using the programmatic interface for accessing data defined in YANG, using the
datastores defined in NETCONF. 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
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 October 29, 2016. This Internet-Draft will expire on December 30, 2016.
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 . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 5 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. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.4. NETCONF Notifications . . . . . . . . . . . . . . . . 7
1.1.5. URI Template . . . . . . . . . . . . . . . . . . . . 9 1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 9 1.1.6. URI Template and Examples . . . . . . . . . . . . . . 9
1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 9 1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10
1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 10 1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 10
1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 11 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 11
1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 12 1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 12
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 13 1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 13
2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 13 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 14
2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 13 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 14
2.3. Certificate Validation . . . . . . . . . . . . . . . . . 13 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 14
2.3. Certificate Validation . . . . . . . . . . . . . . . . . 14
2.4. Authenticated Server Identity . . . . . . . . . . . . . . 14 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 14
2.5. Authenticated Client Identity . . . . . . . . . . . . . . 14 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 14
3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 15 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 16
3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 17 3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 17
3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 17 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 18
3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18
3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 18 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 19
3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19
3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 19 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 20
3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20
3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21
3.5.1. Encoding Data Resource Identifiers in the Request URI 22 3.5.1. Timestamp . . . . . . . . . . . . . . . . . . . . . . 22
3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 25 3.5.2. Entity tag . . . . . . . . . . . . . . . . . . . . . 23
3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 25 3.5.3. Encoding Data Resource Identifiers in the Request URI 23
3.6.1. Encoding Operation Resource Input Parameters . . . . 27 3.5.4. Defaults Handling . . . . . . . . . . . . . . . . . . 26
3.6.2. Encoding Operation Resource Output Parameters . . . . 30 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 26
3.6.3. Encoding Operation Resource Errors . . . . . . . . . 31 3.6.1. Encoding Operation Resource Input Parameters . . . . 28
3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 33 3.6.2. Encoding Operation Resource Output Parameters . . . . 31
3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 34 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 33
3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 34 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 34
4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 34 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 35
4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 36
4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 37 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 38 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 39
4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 40
4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 42 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 43 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 43 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 43
4.8.1. The "content" Query Parameter . . . . . . . . . . . . 44 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 45 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 45
4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 45 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 46
4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 46 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 47
4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 47 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 47
4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 48 4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 48
4.8.7. The "start-time" Query Parameter . . . . . . . . . . 49 4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 49
4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 49 4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 50
4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 50 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 50
5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 51 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 51
5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 51 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 51
5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 52 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.3. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 53 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 52
5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 53 5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 54
5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 54 5.3. RESTCONF Metadata . . . . . . . . . . . . . . . . . . . . 55
5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 55 5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 55
5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 55 5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 56
6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 55 5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 56
6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 55 5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 56
6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 56 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 57
6.3. Subscribing to Receive Notifications . . . . . . . . . . 57 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 57
6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 58 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 57
6.4. Receiving Event Notifications . . . . . . . . . . . . . . 59 6.3. Subscribing to Receive Notifications . . . . . . . . . . 59
7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 61 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 60
7.1. Error Response Message . . . . . . . . . . . . . . . . . 62 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 60
8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 64 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 62
9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 70 7.1. Error Response Message . . . . . . . . . . . . . . . . . 63
9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 71 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 65
9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 71 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 72
9.1.2. The "defaults" Protocol Capability URI . . . . . . . 72 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 72
9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 73 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 73
9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 73 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 73
10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 77 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 74
10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 77 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 74
10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 77
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 78
11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 77 10.1. modules-state . . . . . . . . . . . . . . . . . . . . . 78
11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 78 10.1.1. modules-state/module . . . . . . . . . . . . . . . . 78
11.3. application/yang Media Sub Types . . . . . . . . . . . . 78 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78
11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 79 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 78
12. Security Considerations . . . . . . . . . . . . . . . . . . . 80 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 79
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 81 11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 79
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 81 11.3.1. Media Type application/yang-data+xml . . . . . . . . 79
14.1. Normative References . . . . . . . . . . . . . . . . . . 81 11.3.2. Media Type application/yang-data+json . . . . . . . 81
14.2. Informative References . . . . . . . . . . . . . . . . . 84 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 83
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 84 12. Security Considerations . . . . . . . . . . . . . . . . . . . 84
A.1. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 84 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 85
A.2. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 84 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 85
A.3. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 85 14.1. Normative References . . . . . . . . . . . . . . . . . . 85
A.4. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 86 14.2. Informative References . . . . . . . . . . . . . . . . . 88
A.5. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 88 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 88
A.6. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.1. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 88
A.7. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.2. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 90
A.8. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 89 A.3. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 90
A.9. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 89 A.4. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 91
A.10. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 90 A.5. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 91
A.11. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 90 A.6. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 93
A.12. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 91 A.7. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 94
A.13. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 92 A.8. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 94
A.14. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 92 A.9. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 94
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 93 A.10. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 94
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 93 A.11. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 95
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 94 A.12. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 96
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 99 A.13. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 96
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 99 A.14. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 97
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 99 A.15. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 98
D.1.2. Retrieve The Server Module Information . . . . . . . 100 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 98
D.1.3. Retrieve The Server Capability Information . . . . . 102 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 98
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 103 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 99
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 103 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 104
D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 104 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 104
D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 104 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 104
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 105 D.1.2. Retrieve The Server Module Information . . . . . . . 106
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 105 D.1.3. Retrieve The Server Capability Information . . . . . 108
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 108 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 109
D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 111 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 109
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 112 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 110
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 113 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 111
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 113 D.2.4. Edit a Data Resource . . . . . . . . . . . . . . . . 111
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 114 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 112
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 114 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 112
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 114 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 114
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 116 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 117
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 119
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 119
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 120
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 121
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 121
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 121
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 123
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 access the configuration data, state data, data-model specific RPC
protocol operations, and event notifications within a networking operations, and event notifications within a networking device, in a
device, in a modular and extensible manner. modular and extensible manner.
This document defines an HTTP [RFC7230] based protocol called This document defines an HTTP [RFC7230] based protocol called
RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or
YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using datastores YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using the datastore
defined in NETCONF [RFC6241]. concepts defined in NETCONF [RFC6241].
NETCONF defines configuration datastores and a set of Create, NETCONF defines configuration datastores and a set of Create,
Retrieve, Update, Delete (CRUD) operations that can be used to access Retrieve, Update, Delete (CRUD) operations that can be used to access
these datastores. The YANG language defines the syntax and semantics these datastores. The YANG language defines the syntax and semantics
of datastore content, state data, protocol operations, and event of datastore content, configuration, state data, RPC operations, and
notifications. event notifications.
RESTCONF uses HTTP operations to provide CRUD operations on a RESTCONF uses HTTP methods to provide CRUD operations on a conceptual
conceptual datastore containing YANG-defined data, which is datastore containing YANG-defined data, which is compatible with a
compatible with a server which implements NETCONF datastores. server which implements NETCONF datastores.
If a RESTCONF server is co-located with a NETCONF server, then there If a RESTCONF server is co-located with a NETCONF server, then there
are protocol interactions to be considered, as described in are protocol interactions to be considered, as described in
Section 1.4. The server MAY provide access to specific datastores Section 1.4. The RESTCONF server MAY provide access to specific
using operation resources, as described in Section 3.6. datastores using operation resources, as described in Section 3.6.
Configuration data and state data are exposed as resources that can Configuration data and state data are exposed as resources that can
be retrieved with the GET method. Resources representing be retrieved with the GET method. Resources representing
configuration data can be modified with the DELETE, PATCH, POST, and configuration data can be modified with the DELETE, PATCH, POST, and
PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126]
or JSON [RFC7159]. or JSON [RFC7159].
Data-model specific operations defined with the YANG "rpc" or Data-model specific RPC operations defined with the YANG "rpc" or
"action" statements can be invoked with the POST method. Data-model "action" statements can be invoked with the POST method. Data-model
specific event notifications defined with the YANG "notification" specific event notifications defined with the YANG "notification"
statement can be accessed. statement can be accessed.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and document are to be interpreted as described in [RFC2119].
"OPTIONAL" in this document are to be interpreted as described in BCP
14, [RFC2119].
1.1.1. NETCONF 1.1.1. NETCONF
The following terms are defined in [RFC6241]: The following terms are defined in [RFC6241]:
o candidate configuration datastore o candidate configuration datastore
o client
o configuration data o configuration data
o datastore o datastore
o configuration datastore o configuration datastore
o protocol operation
o running configuration datastore o running configuration datastore
o server
o startup configuration datastore o startup configuration datastore
o state data o state data
o user o user
1.1.2. HTTP 1.1.2. HTTP
The following terms are defined in [RFC3986]: The following terms are defined in [RFC3986]:
skipping to change at page 7, line 30 skipping to change at page 7, line 33
o data node o data node
o key leaf o key leaf
o leaf o leaf
o leaf-list o leaf-list
o list o list
o non-presence container (or NP-container) o mandatory node
o ordered-by user o ordered-by user
o presence container (or P-container) o presence container
o RPC operation o RPC operation
o top-level data node o top-level data node
1.1.4. Terms 1.1.4. NETCONF Notifications
The following terms are defined in [RFC5277]:
o notification replay
1.1.5. Terms
The following terms are used within this document: The following terms are used within this document:
o API resource: a resource with the media type "application/ o API resource: a resource that models the RESTCONF entry point and
yang.api+xml" or "application/yang.api+json". the sub-resources to access YANG-defined content. It is defined
with the YANG data template named "yang-api" in the
"ietf-restconf" module.
o data resource: a resource with the media type "application/ o data resource: a resource that models a YANG data node. It is
yang.data+xml" or "application/yang.data+json". Containers, defined with YANG data definition statements, and YANG containers,
leafs, list entries, anydata and anyxml nodes can be data leafs, leaf-list entries, list entries, anydata and anyxml nodes
resources. can be data resources.
o datastore resource: a resource with the media type "application/ o datastore resource: a resource that models a programmatic
yang.datastore+xml" or "application/yang.datastore+json". interface to NETCONF datastores. By default, RESTCONF methods
Represents a datastore. access a unified view of the underlying datastore implementation
on the server. It is defined as a sub-resource within the API
resource.
o edit operation: a RESTCONF operation on a data resource using o edit operation: a RESTCONF operation on a data resource using
either a POST, PUT, PATCH, or DELETE method. either a POST, PUT, PATCH, or DELETE method. This is not the same
as the NETCONF edit operation (i.e., one of the values for the
"nc:operation" attribute: "create", "replace", "merge", "delete",
or "remove").
o event stream resource: This resource represents an SSE (Server- o event stream resource: This resource represents an SSE (Server-
Sent Events) event stream. The content consists of text using the Sent Events) event stream. The content consists of text using the
media type "text/event-stream", as defined by the HTML5 media type "text/event-stream", as defined by the SSE
[W3C.REC-html5-20141028] specification. Each event represents one [W3C.REC-eventsource-20150203] specification. Each event
<notification> message generated by the server. It contains a represents one <notification> message generated by the server. It
conceptual system or data-model specific event that is delivered contains a conceptual system or data-model specific event that is
within an event notification stream. Also called a "stream delivered within an event notification stream. Also called a
resource". "stream resource".
o media-type: HTTP uses Internet media types [RFC2046] in the o media-type: HTTP uses Internet media types [RFC2046] in the
Content-Type and Accept header fields in order to provide open and Content-Type and Accept header fields in order to provide open and
extensible data typing and type negotiation. extensible data typing and type negotiation.
o NETCONF client: a client which implements the NETCONF protocol.
Called "client" in [RFC6241].
o NETCONF server: a server which implements the NETCONF protocol.
Called "server" in [RFC6241].
o operation: the conceptual RESTCONF operation for a message, o operation: the conceptual RESTCONF operation for a message,
derived from the HTTP method, request URI, headers, and message- derived from the HTTP method, request URI, headers, and message-
body. body.
o operation resource: a resource with the media type "application/ o operation resource: a resource that models a data-model specific
yang.operation+xml" or "application/yang.operation+json". operation, that is defined with a YANG "rpc" or "action"
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 that can be used for o plain patch: a specific PATCH request type, defined in
simple merge operations. Section 4.6.1, that can be used for simple merge operations. It
has a representation with the media-type "application/
yang-data+xml" or "application/yang-data+json".
o query parameter: a parameter (and its value if any), encoded o query parameter: a parameter (and its value if any), encoded
within the query component of the request URI. within the query component of the request URI.
o 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.
Also called "client".
o RESTCONF server: a server which implements the RESTCONF protocol.
Also called "server".
o retrieval request: a request using the GET or HEAD methods. o retrieval request: a request using the GET or HEAD methods.
o target resource: the resource that is associated with a particular o target resource: the resource that is associated with a particular
message, identified by the "path" component of the request URI. message, identified by the "path" component of the request URI.
o schema resource: a resource with the media type "application/ o schema resource: a resource that has a representation with the
yang". The YANG representation of the schema can be retrieved by media type "application/yang". The schema resource is used by the
the client with the GET method. client to retrieve the YANG schema with the GET method.
o stream list: the set of data resource instances that describe the o stream list: the set of data resource instances that describe the
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.
1.1.5. URI Template o YANG data template: a schema for modeling a conceptual data
structure in an encoding-independent manner. It is defined with
the "yang-data" extension, found in Section 8. It has a
representation with the media-type "application/yang-data+xml" or
"application/yang-data+json".
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.
1.1.6. Tree Diagrams Many of the examples throughout the document are based on the
"example-jukebox" YANG module, defined in Appendix C.1.
1.1.7. Tree Diagrams
A simplified graphical representation of the data model is used in A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these diagrams is as this document. The meaning of the symbols in these diagrams is as
follows: follows:
o Brackets "[" and "]" enclose list keys. o Brackets "[" and "]" enclose list keys.
o Abbreviations before data node names: "rw" means configuration o Abbreviations before data node names: "rw" means configuration
data (read-write) and "ro" state data (read-only). data (read-write) and "ro" state data (read-only).
skipping to change at page 10, line 49 skipping to change at page 11, line 40
1.3. Data Model Driven API 1.3. Data Model Driven API
RESTCONF combines the simplicity of the HTTP protocol with the RESTCONF combines the simplicity of the HTTP protocol with the
predictability and automation potential of a schema-driven API. predictability and automation potential of a schema-driven API.
Using YANG, a client can predict all management resources, much like Using YANG, a client can predict all management resources, much like
using URI Templates [RFC6570], but in a more holistic manner. This using URI Templates [RFC6570], but in a more holistic manner. This
strategy obviates the need for responses provided by the server to strategy obviates the need for responses provided by the server to
contain Hypermedia as the Engine of Application State (HATEOAS) contain Hypermedia as the Engine of Application State (HATEOAS)
links, originally described in Roy Fielding's doctoral dissertation links, originally described in Roy Fielding's doctoral dissertation
[rest-dissertation]. [rest-dissertation], because the client can determine the links it
needs from the YANG modules.
RESTCONF provides the YANG module capability information supported by RESTCONF provides the YANG module capability information supported by
the server, in case the client wants to use it. The URIs for custom the server, in case the client wants to use it. The URIs for data-
protocol operations and datastore content are predictable, based on model specific RPC operations and datastore content are predictable,
the YANG module definitions. based on the YANG module definitions.
The RESTCONF protocol operates on a conceptual datastore defined with The RESTCONF protocol operates on a conceptual datastore defined with
the YANG data modeling language. The server lists each YANG module the YANG data modeling language. The server lists each YANG module
it supports using the "ietf-yang-library" YANG module, defined in it supports using the "ietf-yang-library" YANG module, defined in
[I-D.ietf-netconf-yang-library]. The server MUST implement the [I-D.ietf-netconf-yang-library]. The server MUST implement the
"ietf-yang-library" module, which MUST identify all the YANG modules "ietf-yang-library" module, which MUST identify all the YANG modules
used by the server. used by the server.
The conceptual datastore contents, data-model-specific operations and The conceptual datastore contents, data-model-specific operations and
event notifications are identified by this set of YANG modules. event notifications are identified by this set of YANG modules.
skipping to change at page 11, line 33 skipping to change at page 12, line 31
RESTCONF edit of a datastore resource is activated upon successful RESTCONF edit of a datastore resource is activated upon successful
completion of the transaction. completion of the transaction.
1.4. Coexistence with NETCONF 1.4. Coexistence with NETCONF
RESTCONF can be implemented on a device that supports NETCONF. RESTCONF can be implemented on a device that supports NETCONF.
If the device supports :writable-running, all edits to configuration If the device supports :writable-running, all edits to configuration
nodes in {+restconf}/data are performed in the running configuration nodes in {+restconf}/data are performed in the running configuration
datastore. The URI template "{+restconf}" is defined in datastore. The URI template "{+restconf}" is defined in
Section 1.1.5. Section 1.1.6.
Otherwise, if the device supports :candidate, all edits to Otherwise, if the device supports :candidate, all edits to
configuration nodes in {+restconf}/data are performed in the configuration nodes in {+restconf}/data are performed in the
candidate configuration datastore. The candidate MUST be candidate configuration datastore. The candidate MUST be
automatically committed to running immediately after each successful automatically committed to running immediately after each successful
edit. Any edits from other sources that are in the candidate edit. Any edits from other sources that are in the candidate
datastore will also be committed. If a confirmed-commit procedure is datastore will also be committed. If a confirmed-commit procedure is
in progress, then this commit will act as the confirming commit. If in progress, then this commit will act as the confirming commit. If
the server is expecting a "persist-id" parameter to complete the the server is expecting a "persist-id" parameter to complete the
confirmed commit procedure then the RESTCONF edit operation MUST fail confirmed commit procedure then the RESTCONF edit operation MUST fail
with a "409 Conflict" status-line. with a "409 Conflict" status-line.
If the device supports :startup, the device MUST automatically update If the device supports :startup, the device MUST automatically update
the non-volatile "startup datastore", after the running datastore has the non-volatile "startup datastore", after the running datastore has
been updated as a consequence of a RESTCONF edit operation. been updated as a consequence of a RESTCONF edit operation.
If a datastore that would be modified by a RESTCONF operation has an If a datastore that would be modified by a RESTCONF operation has an
active lock, the RESTCONF edit operation MUST fail with a "409 active lock from a NETCONF client, the RESTCONF edit operation MUST
Conflict" status-line. fail with a "409 Conflict" status-line.
1.5. RESTCONF Extensibility 1.5. RESTCONF Extensibility
There are two extensibility mechanisms built into RESTCONF: There are two extensibility mechanisms built into RESTCONF:
o protocol version o protocol version
o optional capabilities o optional capabilities
This document defines version 1 of the RESTCONF protocol. If a This document defines version 1 of the RESTCONF protocol. If a
skipping to change at page 12, line 46 skipping to change at page 13, line 42
Content-Type: application/xrd+xml Content-Type: application/xrd+xml
Content-Length: nnn Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'> <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/> <Link rel='restconf' href='/restconf'/>
<Link rel='restconf2' href='/restconf2'/> <Link rel='restconf2' href='/restconf2'/>
</XRD> </XRD>
RESTCONF also supports a server-defined list of optional RESTCONF also supports a server-defined list of optional
capabilities, which are listed by a server using the capabilities, which are listed by a server using the
"ietf-restconf-monitoring" module defined in Section 9.3. For "ietf-restconf-monitoring" module defined in Section 9.3. This
example, this document defines several query parameters in document defines several query parameters in Section 4.8. Each
Section 4.8. Each optional parameter has a corresponding capability optional parameter has a corresponding capability URI defined in
URI defined in Section 9.1.1 that is advertised by the server if Section 9.1.1 that is advertised by the server if supported.
supported.
The "capabilities" list can identify any sort of server extension. The "capabilities" list can identify any sort of server extension.
Typically this extension mechanism is used to identify optional query Typically this extension mechanism is used to identify optional query
parameters but it is not limited to that purpose. For example, the parameters but it is not limited to that purpose. For example, the
"defaults" URI defined in Section 9.1.2 specifies a mandatory URI "defaults" URI defined in Section 9.1.2 specifies a mandatory URI
identifying server defaults handling behavior. identifying server defaults handling behavior.
A new sub-resource type could be identified with a capability if it A new sub-resource type could be identified with a capability if it
is optional to implement. Mandatory protocol features and new is optional to implement. Mandatory protocol features and new
resource types require a new revision of the RESTCONF protocol. resource types require a new revision of the RESTCONF protocol.
skipping to change at page 13, line 27 skipping to change at page 14, line 21
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/1.1 pipelining MUST be supported by the server. Responses MUST
be sent in the same order that requests are received. No other
versions of HTTP are supported for use with RESTCONF.
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 14, line 18 skipping to change at page 15, line 4
does not match a locally configured certificate fingerprint, the does not match a locally configured certificate fingerprint, the
connection MUST be terminated as defined in [RFC5246]. connection MUST be terminated as defined in [RFC5246].
2.4. Authenticated Server Identity 2.4. Authenticated Server Identity
The RESTCONF client MUST check the identity of the server according The RESTCONF client MUST check the identity of the server according
to Section 6 of [RFC6125], including processing the outcome as to Section 6 of [RFC6125], including processing the outcome as
described in Section 6.6 of [RFC6125]. described in Section 6.6 of [RFC6125].
2.5. Authenticated Client Identity 2.5. Authenticated Client Identity
The RESTCONF server MUST authenticate client access to any protected The RESTCONF server MUST authenticate client access to any protected
resource. If the RESTCONF client is not authorized to access a resource. If the RESTCONF client is not authenticated, the server
resource, the server MUST send an HTTP response with "401 SHOULD send an HTTP response with "401 Unauthorized" status-line, as
Unauthorized" status-line, as defined in Section 3.1 of [RFC7235]. defined in Section 3.1 of [RFC7235].
To authenticate a client, a RESTCONF server MUST use TLS based client To authenticate a client, a RESTCONF server MUST use TLS based client
certificates (Section 7.4.6 of [RFC5246]), or MUST use any HTTP certificates (Section 7.4.6 of [RFC5246]), or MUST use any HTTP
authentication scheme defined in the HTTP Authentication Scheme authentication scheme defined in the HTTP Authentication Scheme
Registry (Section 5.1 in [RFC7235]). A server MAY also support the Registry (Section 5.1 in [RFC7235]). A server MAY also support the
combination of both client certificates and an HTTP client combination of both client certificates and an HTTP client
authentication scheme, with the determination of how to process this authentication scheme, with the determination of how to process this
combination left as an implementation decision. combination left as an implementation decision.
The RESTCONF client identity derived from the authentication The RESTCONF client identity derived from the authentication
skipping to change at page 14, line 51 skipping to change at page 15, line 36
The RESTCONF protocol operates on a hierarchy of resources, starting The RESTCONF protocol operates on a hierarchy of resources, starting
with the top-level API resource itself (Section 3.1). Each resource with the top-level API resource itself (Section 3.1). Each resource
represents a manageable component within the device. represents a manageable component within the device.
A resource can be considered a collection of data and the set of A resource can be considered a collection of data and the set of
allowed methods on that data. It can contain nested child resources. allowed methods on that data. It can contain nested child resources.
The child resource types and methods allowed on them are data-model The child resource types and methods allowed on them are data-model
specific. specific.
A resource has a media type identifier, represented by the A resource has a representation associated with a media type
"Content-Type" header in the HTTP response message. A resource can identifier, as represented by the "Content-Type" header in the HTTP
contain zero or more nested resources. A resource can be created and response message. A resource can contain zero or more nested
deleted independently of its parent resource, as long as the parent resources. A resource can be created and deleted independently of
resource exists. its parent resource, as long as the parent resource exists.
All RESTCONF resource types are defined in this document except All RESTCONF resource types are defined in this document except
specific datastore contents, protocol operations, and event specific datastore contents, RPC operations, and event notifications.
notifications. The syntax and semantics for these resource types are The syntax and semantics for these resource types are defined in YANG
defined in YANG modules. modules.
The RESTCONF resources are accessed via a set of URIs defined in this The RESTCONF resources are accessed via a set of URIs defined in this
document. The set of YANG modules supported by the server will document. The set of YANG modules supported by the server will
determine the data model specific operations, top-level data nodes, determine the data model specific RPC operations, top-level data
and event notification messages supported by the server. nodes, and event notification messages supported by the server.
The RESTCONF protocol does not include a data resource discovery The RESTCONF protocol does not include a data resource discovery
mechanism. Instead, the definitions within the YANG modules mechanism. Instead, the definitions within the YANG modules
advertised by the server are used to construct a predictable advertised by the server are used to construct a predictable
operation or data resource identifier. operation or data resource identifier.
3.1. Root Resource Discovery 3.1. Root Resource Discovery
In line with the best practices defined by [RFC7320], RESTCONF In line with the best practices defined by [RFC7320], RESTCONF
enables deployments to specify where the RESTCONF API is located. enables deployments to specify where the RESTCONF API is located.
skipping to change at page 16, line 37 skipping to change at page 17, line 24
In this example, the client would use the path "/top/restconf" as the In this example, the client would use the path "/top/restconf" as the
RESTCONF entry point. RESTCONF entry point.
The client can now determine the operation resources supported by the The client can now determine the operation resources supported by the
the server. In this example a custom "play" operation is supported: the server. In this example a custom "play" operation is supported:
Request Request
------- -------
GET /top/restconf/operations HTTP/1.1 GET /top/restconf/operations HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.api+json Accept: application/yang-data+json
Response Response
-------- --------
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
Pragma: 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.api+json Content-Type: application/yang-data+json
{ "operations" : { "example-jukebox:play" : {} } } { "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 a set of application specific media The RESTCONF protocol defines two application specific media types to
types to identify each of the available resource types. The identify representations of data which conforms to the schema for a
following resource types are defined in RESTCONF: particular YANG construct.
+-----------+---------------------------------+
| Resource | Media Type |
+-----------+---------------------------------+
| API | application/yang.api+xml |
| | application/yang.api+json |
| Datastore | application/yang.datastore+xml |
| | application/yang.datastore+json |
| Data | application/yang.data+xml |
| | application/yang.data+json |
| [none] | application/yang.errors+xml |
| | application/yang.errors+json |
| Operation | application/yang.operation+xml |
| | application/yang.operation+json |
| Schema | application/yang |
+-----------+---------------------------------+
RESTCONF Media Types This document defines media types for XML and JSON serialization of
YANG data. Other documents MAY define other media types for
different serializations of YANG data. The "application/
yang-data+xml" media-type is defined in Section 11.3.1. The
"application/yang-data+json" media-type is defined in Section 11.3.2.
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.api+xml" or {+restconf} and has the media type "application/yang-data+xml" or
"application/yang.api+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 "application/yang.api" restconf-media-type extension in the The "yang-api" YANG data template is defined with the "yang-data"
"ietf-restconf" module defined in Section 8 is used to specify the extension in the "ietf-restconf" module, found in Section 8. It is
structure and syntax of the conceptual child resources within the API used to specify the structure and syntax of the conceptual child
resource. resources within the API resource.
The API resource can be retrieved with the GET method. The API resource can be retrieved with the GET method.
The {+restconf} entry point resource name used in responses MUST
identify the "ietf-restconf" YANG module. For example, a request to
GET the entry point "/restconf" in JSON format will return a
representation of the API resource named "ietf-restconf:restconf".
This resource has the following child resources: This resource has the following child resources:
+----------------------+--------------------------------+ +----------------------+--------------------------------+
| Child Resource | Description | | Child Resource | Description |
+----------------------+--------------------------------+ +----------------------+--------------------------------+
| data | Contains all data resources | | data | Contains all data resources |
| operations | Data-model specific operations | | operations | Data-model specific operations |
| yang-library-version | ietf-yang-library module date | | yang-library-version | ietf-yang-library module date |
+----------------------+--------------------------------+ +----------------------+--------------------------------+
skipping to change at page 18, line 33 skipping to change at page 19, line 12
Example: Example:
This example request by the client would retrieve only the non- This example request by the client would retrieve only the non-
configuration data nodes that exist within the "library" resource, configuration data nodes that exist within the "library" resource,
using the "content" query parameter (see Section 4.8.1). using the "content" query parameter (see Section 4.8.1).
GET /restconf/data/example-jukebox:jukebox/library GET /restconf/data/example-jukebox:jukebox/library
?content=nonconfig HTTP/1.1 ?content=nonconfig HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+xml Accept: application/yang-data+xml
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 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
Pragma: no-cache Content-Type: application/yang-data+xml
Content-Type: application/yang.data+xml
<library xmlns="https://example.com/ns/example-jukebox"> <library xmlns="https://example.com/ns/example-jukebox">
<artist-count>42</artist-count> <artist-count>42</artist-count>
<album-count>59</album-count> <album-count>59</album-count>
<song-count>374</song-count> <song-count>374</song-count>
</library> </library>
3.3.2. {+restconf}/operations 3.3.2. {+restconf}/operations
This optional resource is a container that provides access to the This optional resource is a container that provides access to the
data-model specific protocol operations supported by the server. The data-model specific RPC operations supported by the server. The
server MAY omit this resource if no data-model specific operations server MAY omit this resource if no data-model specific operations
are advertised. are advertised.
Any data-model specific protocol operations defined in the YANG Any data-model specific RPC operations defined in the YANG modules
modules advertised by the server MUST be available as child nodes of advertised by the server MUST be available as child nodes of this
this resource. resource.
The entry point for each RPC operation is represented as an empty
leaf. If an operation resource is retrieved, the empty leaf
representation is returned by the server.
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
skipping to change at page 19, line 23 skipping to change at page 20, line 4
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+xml
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
Pragma: no-cache Content-Type: application/yang-data+xml
Content-Type: application/yang.data+xml
<yang-library-version <yang-library-version
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
2016-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
nodes. nodes. The fragment field in the request URI has no defined purpose
if the target resource is a datastore resource.
This resource type is an abstraction of the system's underlying This resource type is an abstraction of the system's underlying
datastore implementation. It is used to simplify resource editing datastore implementation. It is used to simplify resource editing
for the client. The RESTCONF datastore resource is a conceptual for the client. The RESTCONF datastore resource is a conceptual
collection of all configuration and state data that is present on the collection of all configuration and state data that is present on the
device. device.
Configuration edit transaction management and configuration Configuration edit transaction management and configuration
persistence are handled by the server and not controlled by the persistence are handled by the server and not controlled by the
client. A datastore resource can be written directly with the POST client. A datastore resource can be written directly with the POST
and PATCH methods. Each RESTCONF edit of a datastore resource is and PATCH methods. Each RESTCONF edit of a datastore resource is
saved to non-volatile storage by the server, if the server supports saved to non-volatile storage by the server, if the server supports
non-volatile storage of configuration data. non-volatile storage of configuration data.
If the datastore resource represented by the "{+restconf}/data"
subtree is retrieved, then the datastore and its contents are
returned by the server. The datastore is represented by a node named
"data" in the "ietf-restconf" module namespace.
3.4.1. Edit Collision Detection 3.4.1. Edit Collision Detection
Two "edit collision detection" mechanisms are provided in RESTCONF, Two "edit collision detection" mechanisms are provided in RESTCONF,
for datastore and data resources. for datastore and data resources.
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 top- The server SHOULD maintain a last-modified timestamp for the
level {+restconf}/data resource. This timestamp is only affected by datastore resource. This timestamp is only affected by configuration
configuration data resources, and MUST NOT be updated for changes to child data resources, and MUST NOT be updated for changes to non-
non-configuration data. configuration child data resources.
If the RESTCONF server is colocated with a NETCONF server, then the
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.
If the RESTCONF server is colocated with a NETCONF server, then this
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
skipping to change at page 21, line 13 skipping to change at page 22, line 4
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").
3.5. Data Resource 3.5. Data Resource
A data resource represents a YANG data node that is a descendant node A data resource represents a YANG data node that is a descendant node
of a datastore resource. Each YANG-defined data node can be uniquely of a datastore resource. Each YANG-defined data node can be uniquely
targeted by the request-line of an HTTP operation. Containers, targeted by the request-line of an HTTP method. Containers, leafs,
leafs, leaf-list entries, list entries, anydata and anyxml nodes are leaf-list entries, list entries, anydata and anyxml nodes are data
data resources. resources.
The representation maintained for each data resource is the YANG The representation maintained for each data resource is the YANG
defined subtree for that node. HTTP operations on a data resource defined subtree for that node. HTTP methods on a data resource
affect both the targeted data node and all its descendants, if any. affect both the targeted data node and all its descendants, if any.
A data resource can be retrieved with the GET method. Data resources
are accessed via the "{+restconf}/data" entry point. This sub-tree
is used to retrieve and edit data resources. The fragment field in
the request URI has no defined purpose if the target resource is a
data resource.
A configuration data resource can be altered by the client with some
or all of the edit operations, depending on the target resource and
the specific operation. Refer to Section 4 for more details on edit
operations.
3.5.1. Timestamp
For configuration data resources, the server MAY maintain a last- For configuration data resources, the server MAY maintain a last-
modified timestamp for the resource, and return the "Last-Modified" modified timestamp for the resource, and return the "Last-Modified"
header when it is retrieved with the GET or HEAD methods. header when it is retrieved with the GET or HEAD methods.
The "Last-Modified" header information can be used by a RESTCONF The "Last-Modified" header information can be used by a RESTCONF
client in subsequent requests, within the "If-Modified-Since" and client in subsequent requests, within the "If-Modified-Since" and
"If-Unmodified-Since" headers. "If-Unmodified-Since" headers.
If maintained, the resource timestamp MUST be set to the current time If maintained, the resource timestamp MUST be set to the current time
whenever the resource or any configuration resource within the whenever the resource or any configuration resource within the
resource is altered. If not maintained, then the resource timestamp resource is altered. If not maintained, then the resource timestamp
for the datastore MUST be used instead. for the datastore MUST be used instead. If the RESTCONF server is
colocated with a NETCONF server, then the last-modified timestamp for
a configuration data resource MUST represent the instance within the
"running" datastore.
This timestamp is only affected by configuration data resources, and This timestamp is only affected by configuration data resources, and
MUST NOT be updated for changes to non-configuration data. MUST NOT be updated for changes to non-configuration data.
For non-configuration data resources, the server MAY maintain a last-
modified timestamp for the resource, and return the "Last-Modified"
header when it is retrieved with the GET or HEAD methods. The
timestamps for non-configuration data resources are updated in an
implementation-specific manner.
3.5.2. Entity tag
For configuration data resources, the server SHOULD maintain a For configuration data resources, the server SHOULD maintain a
resource entity tag for the resource, and return the "ETag" header resource entity tag for each resource, and return the "ETag" header
when it is retrieved as the target resource with the GET or HEAD when it is retrieved as the target resource with the GET or HEAD
methods. If maintained, the resource entity tag MUST be updated methods. If maintained, the resource entity tag MUST be updated
whenever the resource or any configuration resource within the whenever the resource or any configuration resource within the
resource is altered. If not maintained, then the resource entity tag resource is altered. If not maintained, then the resource entity tag
for the datastore MUST be used instead. for the datastore MUST be used instead.
The "ETag" header information can be used by a RESTCONF client in The "ETag" header information can be used by a RESTCONF client in
subsequent requests, within the "If-Match" and "If-None-Match" subsequent requests, within the "If-Match" and "If-None-Match"
headers. headers.
This entity tag is only affected by configuration data resources, and This entity tag is only affected by configuration data resources, and
MUST NOT be updated for changes to non-configuration data. MUST NOT be updated for changes to non-configuration data. If the
RESTCONF server is colocated with a NETCONF server, then the entity
A data resource can be retrieved with the GET method. Data resources tag for a configuration data resource MUST represent the instance
are accessed via the "{+restconf}/data" entry point. This sub-tree within the "running" datastore.
is used to retrieve and edit data resources.
A configuration data resource can be altered by the client with some For non-configuration data resources, the server MAY maintain an
or all of the edit operations, depending on the target resource and entity tag for each resource, and return the "ETag" header when it is
the specific operation. Refer to Section 4 for more details on edit retrieved with the GET or HEAD methods. The entity tags for non-
operations. configuration data resources are updated in an implementation-
specific manner.
3.5.1. Encoding Data Resource Identifiers in the Request URI 3.5.3. Encoding Data Resource Identifiers in the Request URI
In YANG, data nodes are identified with an absolute XPath expression, In YANG, data nodes are identified with an absolute XPath expression,
defined in [XPath], starting from the document root to the target defined in [XPath], starting from the document root to the target
resource. In RESTCONF, URI-encoded path expressions are used resource. In RESTCONF, URI-encoded path expressions are used
instead. instead.
A predictable location for a data resource is important, since A predictable location for a data resource is important, since
applications will code to the YANG data model module, which uses applications will code to the YANG data model module, which uses
static naming and defines an absolute path location for all data static naming and defines an absolute path location for all data
nodes. nodes.
A RESTCONF data resource identifier is not an XPath expression. It A RESTCONF data resource identifier is not an XPath expression. It
is encoded from left to right, starting with the top-level data node, is encoded from left to right, starting with the top-level data node,
according to the "api-path" rule in Section 3.5.1.1. The node name according to the "api-path" rule in Section 3.5.3.1. The node name
of each ancestor of the target resource node is encoded in order, of each ancestor of the target resource node is encoded in order,
ending with the node name for the target resource. If a node in the ending with the node name for the target resource. If a node in the
path is defined in another module than its parent node, then module path is defined in another module than its parent node, then module
name followed by a colon character (":") is prepended to the node name followed by a colon character (":") is prepended to the node
name in the resource identifier. See Section 3.5.1.1 for details. name in the resource identifier. See Section 3.5.3.1 for details.
If a data node in the path expression is a YANG leaf-list node, then If a data node in the path expression is a YANG leaf-list node, then
the leaf-list value MUST be encoded according to the following rules: the leaf-list value MUST be encoded according to the following rules:
o The instance-identifier for the leaf-list MUST be encoded using o The identifier for the leaf-list MUST be encoded using one path
one path segment [RFC3986]. segment [RFC3986].
o The path segment is constructed by having the leaf-list name, o The path segment is constructed by having the leaf-list name,
followed by an "=" character, followed by the leaf-list value. followed by an "=" character, followed by the leaf-list value.
(e.g., /restconf/data/top-leaflist=fred). (e.g., /restconf/data/top-leaflist=fred).
If a data node in the path expression is a YANG list node, then the If a data node in the path expression is a YANG list node, then the
key values for the list (if any) MUST be encoded according to the key values for the list (if any) MUST be encoded according to the
following rules: following rules:
o The key leaf values for a data resource representing a YANG list o The key leaf values for a data resource representing a YANG list
skipping to change at page 23, line 29 skipping to change at page 24, line 43
representation for the YANG data type. Any reserved characters representation for the YANG data type. Any reserved characters
MUST be percent-encoded, according to [RFC3986], section 2.1. MUST be percent-encoded, according to [RFC3986], section 2.1.
o All the components in the "key" statement MUST be encoded. o All the components in the "key" statement MUST be encoded.
Partial instance identifiers are not supported. Partial instance identifiers are not supported.
o Since missing key values are not allowed, two consecutive commas o Since missing key values are not allowed, two consecutive commas
are interpreted as a zero-length string. (example: are interpreted as a zero-length string. (example:
list=foo,,baz). list=foo,,baz).
o The "list-instance" ABNF rule defined in Section 3.5.1.1 o The "list-instance" ABNF rule defined in Section 3.5.3.1
represents the syntax of a list instance identifier. represents the syntax of a list instance identifier.
o Resource URI values returned in Location headers for data Resource URI values returned in Location headers for data resources
resources MUST identify the module name, even if there are no MUST identify the module name as specified in
conflicting local names when the resource is created. This [I-D.ietf-netmod-yang-json], even if there are no conflicting local
ensures the correct resource will be identified even if the server names when the resource is created. This ensures the correct
loads a new module that the old client does not know about. resource will be identified even if the server loads a new module
that the old client does not know about.
Examples: Examples:
container top { container top {
list list1 { list list1 {
key "key1 key2 key3"; key "key1 key2 key3";
... ...
list list2 { list list2 {
key "key4 key5"; key "key4 key5";
... ...
leaf X { type string; } leaf X { type string; }
} }
} }
leaf-list Y { leaf-list Y {
type uint32; type uint32;
} }
} }
For the above YANG definition, a target resource URI for leaf "X" For the above YANG definition, the container "top" is defined in the
"example-top" YANG module, and a target resource URI for leaf "X"
would be encoded as follows (line wrapped for display purposes only): would be encoded as follows (line wrapped for display purposes only):
/restconf/data/example-top:top/list1=key1,key2,key3/ /restconf/data/example-top:top/list1=key1,key2,key3/
list2=key4,key5/X list2=key4,key5/X
For the above YANG definition, a target resource URI for leaf-list For the above YANG definition, a target resource URI for leaf-list
"Y" would be encoded as follows: "Y" would be encoded as follows:
/restconf/data/example-top:top/Y=instance-value /restconf/data/example-top:top/Y=instance-value
skipping to change at page 24, line 43 skipping to change at page 25, line 46
single-quote, double-quote, colon, double-quote, space, and forward single-quote, double-quote, colon, double-quote, space, and forward
slash. (,'":" /). Note that double-quote is not a reserved slash. (,'":" /). Note that double-quote is not a reserved
characters and does not need to be percent-encoded. The value of characters and does not need to be percent-encoded. The value of
"key2" is the empty string, and the value of "key3" is the string "key2" is the empty string, and the value of "key3" is the string
"foo". "foo".
Example URL: Example URL:
/restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo
3.5.1.1. ABNF For Data Resource Identifiers 3.5.3.1. ABNF For Data Resource Identifiers
The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to
construct RESTCONF path identifiers: construct RESTCONF path identifiers:
api-path = "/" | api-path = "/" |
("/" api-identifier ("/" api-identifier
0*("/" (api-identifier | list-instance ))) 0*("/" (api-identifier | list-instance )))
api-identifier = [module-name ":"] identifier ;; note 1 api-identifier = [module-name ":"] identifier ;; note 1
module-name = identifier module-name = identifier
list-instance = api-identifier "=" key-value ["," key-value]* list-instance = api-identifier "=" key-value ["," key-value]*
key-value = string ;; note 1 key-value = string ;; note 1
string = <a quoted or unquoted string> string = <a quoted or unquoted string>
;; An identifier MUST NOT start with ;; An identifier MUST NOT start with
;; (('X'|'x') ('M'|'m') ('L'|'l')) ;; (('X'|'x') ('M'|'m') ('L'|'l'))
skipping to change at page 25, line 21 skipping to change at page 26, line 25
;; An identifier MUST NOT start with ;; An identifier MUST NOT start with
;; (('X'|'x') ('M'|'m') ('L'|'l')) ;; (('X'|'x') ('M'|'m') ('L'|'l'))
identifier = (ALPHA / "_") identifier = (ALPHA / "_")
*(ALPHA / DIGIT / "_" / "-" / ".") *(ALPHA / DIGIT / "_" / "-" / ".")
Note 1: The syntax for "api-identifier" and "key-value" MUST conform Note 1: The syntax for "api-identifier" and "key-value" MUST conform
to the JSON identifier encoding rules in Section 4 of to the JSON identifier encoding rules in Section 4 of
[I-D.ietf-netmod-yang-json]. [I-D.ietf-netmod-yang-json].
3.5.2. Defaults Handling 3.5.4. Defaults Handling
RESTCONF requires that a server report its default handling mode (see RESTCONF requires that a server report its default handling mode (see
Section 9.1.2 for details). If the optional "with-defaults" query Section 9.1.2 for details). If the optional "with-defaults" query
parameter is supported by the server, a client may use it to control parameter is supported by the server, a client may use it to control
retrieval of default values (see Section 4.8.9 for details). retrieval of default values (see Section 4.8.9 for details).
If a leaf or leaf-list is missing from the configuration and there is If a leaf or leaf-list is missing from the configuration and there is
a YANG-defined default for that data resource, then the server MUST a YANG-defined default for that data resource, then the server MUST
use the YANG-defined default as the configured value. use the YANG-defined default as the configured value.
If the target of a GET method is a data node that represents a leaf If the target of a GET method is a data node that represents a leaf
that has a default value, and the leaf has not been configured yet, or leaf-list that has a default value, and the leaf or leaf-list has
the server MUST return the default value that is in use by the not been instantiated yet, the server MUST return the default
server. value(s) that are in use by the server. In this case, the server
MUST ignore its basic-mode, described in Section 4.8.9, and return
the default value.
If the target of a GET method is a data node that represents a If the target of a GET method is a data node that represents a
container or list that has any child resources with default values, container or list that has any child resources with default values,
for the child resources that have not been given value yet, the for the child resources that have not been given value yet, the
server MAY return the default values that are in use by the server, server MAY return the default values that are in use by the server,
in accordance with its reported default handing mode and query in accordance with its reported default handing mode and query
parameters passed by the client. parameters passed by the client.
3.6. Operation Resource 3.6. Operation Resource
An operation resource represents an RPC operation defined with the
An operation resource represents a protocol operation defined with YANG "rpc" statement or a data-model specific action defined with a
the YANG "rpc" statement or a data-model specific action defined with YANG "action" statement. It is invoked using a POST method on the
a YANG "action" statement. It is invoked using a POST method on the operation resource. The fragment field in the request URI has no
operation resource. defined purpose if the target resource is an operation resource.
An RPC operation is invoked as: An RPC operation is invoked as:
POST {+restconf}/operations/<operation> POST {+restconf}/operations/<operation>
The <operation> field identifies the module name and rpc identifier The <operation> field identifies the module name and rpc identifier
string for the desired operation. string for the desired operation.
For example, if "module-A" defined a "reset" rpc operation, then For example, if "module-A" defined a "reset" rpc operation, then
invoking the operation from "module-A" would be requested as follows: invoking the operation from "module-A" would be requested as follows:
POST /restconf/operations/module-A:reset HTTP/1.1 POST /restconf/operations/module-A:reset HTTP/1.1
Server example.com Server: example.com
An action is invoked as: An action is invoked as:
POST {+restconf}/data/<data-resource-identifier>/<action> POST {+restconf}/data/<data-resource-identifier>/<action>
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 a If the "rpc" or "action" statement has an "input" section then
message-body MAY be sent by the client in the request, otherwise the instances of these input parameters are encoded in the module
request message MUST NOT include a message-body. If the "input" namespace where the "rpc" or "action" statement is defined, in an XML
objcet tree contains mandatory parameters, then a message-body MUST element or JSON object named "input".
be sent by the client. A mandatory parameter is a leaf or choice
with a "mandatory" statement set to "true", or a list or leaf-list
than have a "min-elements" statement value greater than zero.
If the operation is invoked without errors, and if the "rpc" or If the "rpc" or "action" statement has an "input" section and the
"action" statement has an "output" section, then a message-body MAY "input" object tree contains any child data nodes which are
be sent by the server in the response, otherwise the response message considered mandatory nodes, then a message-body MUST be sent by the
MUST NOT include a message-body in the response message, and MUST client in the request.
send a "204 No Content" status-line instead.
If the operation input is not valid, or the operation is invoked but If the "rpc" or "action" statement has an "input" section and the
errors occur, then a message-body MUST be sent by the server, "input" object tree does not contain any child nodes which are
containing an "errors" resource, as defined in Section 3.9. A considered mandatory nodes, then a message-body MAY be sent by the
detailed example of an operation resource error response can be found client in the request.
in Section 3.6.3.
If the "rpc" or "action" statement has no "input" section, the
request message MUST NOT include a message-body.
If the "rpc" or "action" statement has an "output" section then
instances of these input parameters are encoded in the module
namespace where the "rpc" or "action" statement is defined, in an XML
element or JSON object named "output".
If the RPC operation is invoked without errors, and if the "rpc" or
"action" statement has an "output" section and the "output" object
tree contains any child data nodes which are considered mandatory
nodes, then a response message-body MUST be sent by the server in the
response.
If the RPC operation is invoked without errors, and if the "rpc" or
"action" statement has an "output" section and the "output" object
tree does not contain any child nodes which are considered mandatory
nodes, then a response message-body MAY be sent by the server in the
response.
If the RPC operation is invoked without errors, and if the "rpc" or
"action" statement has no "output" section, the response message MUST
NOT include a message-body, and MUST send a "204 No Content" status-
line instead.
If the RPC operation input is not valid, or the RPC operation is
invoked but errors occur, then a message-body MUST be sent by the
server, containing an "errors" resource, as defined in Section 3.9.
A detailed example of an operation resource error response can be
found in Section 3.6.3.
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
skipping to change at page 28, line 47 skipping to change at page 30, line 31
} }
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.operation+xml Content-Type: application/yang-data+xml
<input xmlns="https://example.com/ns/example-ops"> <input xmlns="https://example.com/ns/example-ops">
<delay>600</delay> <delay>600</delay>
<message>Going down for system maintenance</message> <message>Going down for system maintenance</message>
<language>en-US</language> <language>en-US</language>
</input> </input>
The server might respond: The server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 25 Apr 2012 11:01:00 GMT Date: Mon, 25 Apr 2012 11:01:00 GMT
Server: example-server Server: example-server
The same example request message is shown here using JSON encoding: The same example request message is shown here using JSON encoding:
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.operation+json Content-Type: application/yang-data+json
{ {
"example-ops:input" : { "example-ops:input" : {
"delay" : 600, "delay" : 600,
"message" : "Going down for system maintenance", "message" : "Going down for system maintenance",
"language" : "en-US" "language" : "en-US"
} }
} }
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.operation+xml Content-Type: application/yang-data+xml
<input xmlns="https://example.com/ns/example-actions"> <input xmlns="https://example.com/ns/example-actions">
<delay>600</delay> <delay>600</delay>
</input> </input>
The server might respond: The server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 25 Apr 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 30, line 4 skipping to change at page 31, line 37
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
The same example request message is shown here using JSON encoding The same example request message is shown here using JSON encoding
(text wrap for display purposes): (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.operation+json Content-Type: application/yang-data+json
{ "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
skipping to change at page 30, line 35 skipping to change at page 32, line 21
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
this example. this example.
The client might send the following POST request message to invoke The client might send the following POST request message to invoke
the "get-reboot-info" operation: the "get-reboot-info" operation:
POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.operation+json Accept: application/yang-data+json
The server might respond: The server might respond:
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.operation+json Content-Type: application/yang-data+json
{ {
"example-ops:output" : { "example-ops:output" : {
"reboot-time" : 30, "reboot-time" : 30,
"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.operation+xml Content-Type: application/yang-data+xml
<output xmlns="https://example.com/ns/example-ops"> <output xmlns="https://example.com/ns/example-ops">
<reboot-time>30</reboot-time> <reboot-time>30</reboot-time>
<message>Going down for system maintenance</message> <message>Going down for system maintenance</message>
<language>en-US</language> <language>en-US</language>
</output> </output>
Action Output Example: Action Output Example:
The "example-actions" YANG module defined in Section 3.6.1 is used The "example-actions" YANG module defined in Section 3.6.1 is used
for this example. for this example.
The client might send the following POST request message to invoke The client might send the following POST request message to invoke
the "get-last-reset-time" action: the "get-last-reset-time" action:
POST /restconf/data/example-actions:interfaces/interface=eth0 POST /restconf/data/example-actions:interfaces/interface=eth0
/get-last-reset-time HTTP/1.1 /get-last-reset-time HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.operation+json Accept: application/yang-data+json
The server might respond: The server might respond:
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.operation+json Content-Type: application/yang-data+json
{ {
"example-actions:output" : { "example-actions:output" : {
"last-reset" : "2015-10-10T02:14:11Z" "last-reset" : "2015-10-10T02:14:11Z"
} }
} }
3.6.3. Encoding Operation Resource Errors 3.6.3. Encoding Operation Resource Errors
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" operation from the example in Section 3.6.1, the Using the "reboot" RPC operation from the example in Section 3.6.1,
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.operation+xml Content-Type: application/yang-data+xml
<input xmlns="https://example.com/ns/example-ops"> <input xmlns="https://example.com/ns/example-ops">
<delay>-33</delay> <delay>-33</delay>
<message>Going down for system maintenance</message> <message>Going down for system maintenance</message>
<language>en-US</language> <language>en-US</language>
</input> </input>
The server might respond with an "invalid-value" error: The server might respond with an "invalid-value" error:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Date: Mon, 25 Apr 2012 11:10:30 GMT Date: Mon, 25 Apr 2012 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang.errors+xml Content-Type: application/yang-data+xml
<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error> <error>
<error-type>protocol</error-type> <error-type>protocol</error-type>
<error-tag>invalid-value</error-tag> <error-tag>invalid-value</error-tag>
<error-path xmlns:ops="https://example.com/ns/example-ops"> <error-path xmlns:ops="https://example.com/ns/example-ops">
/ops:input/ops:delay /ops:input/ops:delay
</error-path> </error-path>
<error-message>Invalid input parameter</error-message> <error-message>Invalid input parameter</error-message>
</error> </error>
</errors> </errors>
The same response is shown here in JSON encoding: The same response is shown here in JSON encoding:
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.errors+json Content-Type: application/yang-data+json
{ "ietf-restconf:errors" : { { "ietf-restconf:errors" : {
"error" : [ "error" : [
{ {
"error-type" : "protocol", "error-type" : "protocol",
"error-tag" : "invalid-value", "error-tag" : "invalid-value",
"error-path" : "/example-ops:input/delay", "error-path" : "/example-ops:input/delay",
"error-message" : "Invalid input parameter", "error-message" : "Invalid input parameter",
} }
] ]
skipping to change at page 33, line 22 skipping to change at page 35, line 8
To retrieve a YANG module, a client first needs to get the URL for To retrieve a YANG module, a client first needs to get the URL for
retrieving the schema, which is stored in the "schema" leaf. Note retrieving the schema, which is stored in the "schema" leaf. Note
that there is no required structure for this URL. The URL value that there is no required structure for this URL. The URL value
shown below is just an example. shown below is just an example.
The client might send the following GET request message: The client might send the following GET request message:
GET /restconf/data/ietf-yang-library:modules-state/module= GET /restconf/data/ietf-yang-library:modules-state/module=
example-jukebox,2015-04-04/schema HTTP/1.1 example-jukebox,2015-04-04/schema HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json Accept: application/yang-data+json
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Thu, 11 Feb 2016 11:10:30 GMT Date: Thu, 11 Feb 2016 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang.data+json Content-Type: application/yang-data+json
{ {
"ietf-yang-library:schema": "ietf-yang-library:schema":
"https://example.com/mymodules/example-jukebox/2015-04-04" "https://example.com/mymodules/example-jukebox/2015-04-04"
} }
Next the client needs to retrieve the actual YANG schema. Next the client needs to retrieve the actual YANG schema.
The client might send the following GET request message: The client might send the following GET request message:
skipping to change at page 34, line 21 skipping to change at page 36, line 10
event notifications. Each stream is created and modified by the event notifications. Each stream is created and modified by the
server only. A client can retrieve a stream resource or initiate a server only. A client can retrieve a stream resource or initiate a
long-poll server sent event stream, using the procedure specified in long-poll server sent event stream, using the procedure specified in
Section 6.3. Section 6.3.
A notification stream functions according to the NETCONF A notification stream functions according to the NETCONF
Notifications specification [RFC5277]. The available streams can be Notifications specification [RFC5277]. The available streams can be
retrieved from the stream list, which specifies the syntax and retrieved from the stream list, which specifies the syntax and
semantics of a stream resource. semantics of a stream resource.
3.9. Errors Media Type The fragment field in the request URI has no defined purpose if the
target resource is an event stream resource.
An "errors" media type is a collection of error information that is 3.9. Errors YANG Data Template
sent as the message-body in a server response message, if an error
occurs while processing a request message. It is not considered a
resource type because no instances can be retrieved with a GET
request.
The "ietf-restconf" YANG module contains the "application/ An "errors" YANG data template models a collection of error
yang.errors" restconf-media-type extension which specifies the syntax information that is sent as the message-body in a server response
and semantics of an "errors" media type. RESTCONF error handling message, if an error occurs while processing a request message. It
is not considered a resource type because no instances can be
retrieved with a GET request.
The "ietf-restconf" YANG module contains the "yang-errors" YANG data
template, that specifies the syntax and semantics of an "errors"
container within a RESTCONF response. RESTCONF error handling
behavior is defined in Section 7. behavior is defined in Section 7.
4. Operations 4. Operations
The RESTCONF protocol uses HTTP methods to identify the CRUD The RESTCONF protocol uses HTTP methods to identify the CRUD
operation requested for a particular resource. operation requested for a particular resource.
The following table shows how the RESTCONF operations relate to The following table shows how the RESTCONF operations relate to
NETCONF protocol operations: NETCONF protocol operations and edit operations, which are identified
with the NETCONF "nc:operation" attribute.
+----------+--------------------------------------------+ +----------+-----------------------------------------------+
| RESTCONF | NETCONF | | RESTCONF | NETCONF |
+----------+--------------------------------------------+ +----------+-----------------------------------------------+
| OPTIONS | none | | OPTIONS | none |
| HEAD | none | | HEAD | none |
| GET | <get-config>, <get> | | GET | <get-config>, <get> |
| POST | <edit-config> (operation="create") | | POST | <edit-config> (nc:operation="create") |
| POST | invoke any operation | | POST | invoke an RPC operation |
| PUT | <edit-config> (operation="create/replace") | | PUT | <edit-config> (nc:operation="create/replace") |
| PATCH | <edit-config> (operation="merge") | | PATCH | <edit-config> (nc:operation="merge") |
| DELETE | <edit-config> (operation="delete") | | DELETE | <edit-config> (nc:operation="delete") |
+----------+--------------------------------------------+ +----------+-----------------------------------------------+
CRUD Methods in RESTCONF CRUD Methods in RESTCONF
The NETCONF "remove" operation attribute is not supported by the HTTP The "remove" operation attribute for the NETCONF <edit-config>
DELETE method. The resource must exist or the DELETE method will operation is not supported by the HTTP DELETE method. The resource
fail. The PATCH method is equivalent to a "merge" operation when must exist or the DELETE method will fail. The PATCH method is
using a plain patch (see Section 4.6.1); other media-types may equivalent to a "merge" operation when using a plain patch (see
provide more granular control. Section 4.6.1); other media-types may provide more granular control.
Access control mechanisms MUST be used to limit what operations can Access control mechanisms MUST be used to limit what operations can
be used. In particular, RESTCONF is compatible with the NETCONF be used. In particular, RESTCONF is compatible with the NETCONF
Access Control Model (NACM) [RFC6536], as there is a specific mapping Access Control Model (NACM) [RFC6536], as there is a specific mapping
between RESTCONF and NETCONF operations, defined in Section 4. The between RESTCONF and NETCONF operations, defined in Section 4. The
resource path needs to be converted internally by the server to the resource path needs to be converted internally by the server to the
corresponding YANG instance-identifier. Using this information, the corresponding YANG instance-identifier. Using this information, the
server can apply the NACM access control rules to RESTCONF messages. server can apply the NACM access control rules to RESTCONF messages.
The server MUST NOT allow any operation to any resources that the The server MUST NOT allow any operation to any resources that the
client is not authorized to access. client is not authorized to access.
Operations are applied to a single data resource instance at once.
The server MUST NOT allow any operation to be applied to multiple
instances of a YANG list or leaf-list.
Implementation of all methods (except PATCH) are defined in Implementation of all methods (except PATCH) are defined in
[RFC7231]. This section defines the RESTCONF protocol usage for each [RFC7231]. This section defines the RESTCONF protocol usage for each
HTTP method. HTTP method.
4.1. OPTIONS 4.1. OPTIONS
The OPTIONS method is sent by the client to discover which methods The OPTIONS method is sent by the client to discover which methods
are supported by the server for a specific resource (e.g., GET, POST, are supported by the server for a specific resource (e.g., GET, POST,
DELETE, etc.). The server MUST implement this method. DELETE, etc.). The server MUST implement this method.
skipping to change at page 36, line 16 skipping to change at page 37, line 50
entry point. The same query parameters supported by the GET method entry point. The same query parameters supported by the GET method
are supported by the HEAD method. are supported by the HEAD method.
The access control behavior is enforced as if the method was GET The access control behavior is enforced as if the method was GET
instead of HEAD. The server MUST respond the same as if the method instead of HEAD. The server MUST respond the same as if the method
was GET instead of HEAD, except that no response message-body is was GET instead of HEAD, except that no response message-body is
included. included.
4.3. GET 4.3. GET
The GET method is sent by the client to retrieve data and meta-data The GET method is sent by the client to retrieve data and metadata
for a resource. It is supported for all resource types, except for a resource. It is supported for all resource types, except
operation resources. The request MUST contain a request URI that operation resources. The request MUST contain a request URI that
contains at least the entry point. contains at least the entry point.
The server MUST NOT return any data resources for which the user does The server MUST NOT return any data resources for which the user does
not have read privileges. If the user is not authorized to read the not have read privileges. If the user is not authorized to read the
target resource, an error response containing a "401 Unauthorized" target resource, an error response containing a "401 Unauthorized"
status-line SHOULD be returned. A server MAY return a "404 Not status-line SHOULD be returned. A server MAY return a "404 Not
Found" status-line, as described in section 6.5.3 in [RFC7231]. Found" status-line, as described in section 6.5.3 in [RFC7231].
skipping to change at page 36, line 40 skipping to change at page 38, line 26
If any content is returned to the client, then the server MUST send a If any content is returned to the client, then the server MUST send a
valid response message-body. More than one element MUST NOT be valid response message-body. More than one element MUST NOT be
returned for XML encoding. returned for XML encoding.
If a retrieval request for a data resource representing a YANG leaf- If a retrieval request for a data resource representing a YANG leaf-
list or list object identifies more than one instance, and XML list or list object identifies more than one instance, and XML
encoding is used in the response, then an error response containing a encoding is used in the response, then an error response containing a
"400 Bad Request" status-line MUST be returned by the server. "400 Bad Request" status-line MUST be returned by the server.
If a retrieval request for a data resource represents an instance
that does not exist, then an error response containing a "404 Not
Found" status-line MUST be returned by the server.
If the target resource of a retrieval request is for an operation If the target resource of a retrieval request is for an operation
resource then a "405 Method Not Allowed" status-line MUST be returned resource then a "405 Method Not Allowed" status-line MUST be returned
by the server. by the server.
Note that the way that access control is applied to data resources is Note that the way that access control is applied to data resources
completely incompatible with HTTP caching. The Last-Modified and may not be completely compatible with HTTP caching. The Last-
ETag headers maintained for a data resource are not affected by Modified and ETag headers maintained for a data resource are not
changes to the access control rules for that data resource. It is affected by changes to the access control rules for that data
possible for the representation of a data resource that is visible to resource. It is possible for the representation of a data resource
a particular client to be changed without detection via the Last- that is visible to a particular client to be changed without
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+xml
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:02:40 GMT Date: Mon, 23 Apr 2012 17:02:40 GMT
Server: example-server Server: example-server
Content-Type: application/yang.data+xml Content-Type: application/yang-data+xml
Cache-Control: no-cache Cache-Control: no-cache
Pragma: 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>
4.4. POST 4.4. POST
The POST method is sent by the client to create a data resource or The POST method is sent by the client to create a data resource or
invoke an operation resource. The server uses the target resource invoke an operation resource. The server uses the target resource
media type to determine how to process the request. media type to determine how to process the request.
+-----------+------------------------------------------------+ +-----------+------------------------------------------------+
| Type | Description | | Type | Description |
+-----------+------------------------------------------------+ +-----------+------------------------------------------------+
| Datastore | Create a top-level configuration data resource | | Datastore | Create a top-level configuration data resource |
| Data | Create a configuration data child resource | | Data | Create a configuration data child resource |
| Operation | Invoke a protocol operation | | Operation | Invoke an RPC operation |
+-----------+------------------------------------------------+ +-----------+------------------------------------------------+
Resource Types that Support POST Resource Types that Support POST
4.4.1. Create Resource Mode 4.4.1. Create Resource Mode
If the target resource type is a datastore or data resource, then the If the target resource type is a datastore or data resource, then the
POST is treated as a request to create a top-level resource or child POST is treated as a request to create a top-level resource or child
resource, respectively. The message-body is expected to contain the resource, respectively. The message-body is expected to contain the
content of a child resource to create within the parent (target content of a child resource to create within the parent (target
resource). The message-body MUST NOT contain more than one instance resource). The message-body MUST contain exactly one instance of the
of the expected data resource. The data-model for the child tree is expected data resource. The data-model for the child tree is the
the subtree as defined by YANG for the child resource. subtree as defined by YANG for the child resource.
The "insert" and "point" query parameters MUST be supported by the The "insert" Section 4.8.5 and "point" Section 4.8.6 query parameters
POST method for datastore and data resources. These parameters are MUST be supported by the POST method for datastore and data
only allowed if the list or leaf-list is ordered-by user. resources. These parameters are only allowed if the list or leaf-
list is ordered-by user.
If the POST method succeeds, a "201 Created" status-line is returned If the POST method succeeds, a "201 Created" status-line is returned
and there is no response message-body. A "Location" header and there is no response message-body. A "Location" header
identifying the child resource that was created MUST be present in identifying the child resource that was created MUST be present in
the response in this case. the response in this case.
If the data resource already exists, then the POST request MUST fail If the data resource already exists, then the POST request MUST fail
and a "409 Conflict" status-line MUST be returned. and a "409 Conflict" status-line MUST be returned.
If the user is not authorized to create the target resource, an error If the user is not authorized to create the target resource, an error
skipping to change at page 38, line 32 skipping to change at page 40, line 25
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.
Example: Example:
To create a new "jukebox" resource, the client might send: To create a new "jukebox" resource, the client might send:
POST /restconf/data HTTP/1.1 POST /restconf/data HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang.data+json Content-Type: application/yang-data+json
{ "example-jukebox:jukebox" : {} } { "example-jukebox:jukebox" : {} }
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:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server Server: example-server
Location: https://example.com/restconf/data/ Location: https://example.com/restconf/data/
example-jukebox:jukebox example-jukebox:jukebox
Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT
ETag: b3a3e673be2 ETag: "b3a3e673be2"
Refer to Appendix D.2.1 for more resource creation examples. Refer to Appendix D.2.1 for more resource creation examples.
4.4.2. Invoke Operation Mode 4.4.2. Invoke Operation Mode
If the target resource type is an operation resource, then the POST If the target resource type is an operation resource, then the POST
method is treated as a request to invoke that operation. The method is treated as a request to invoke that operation. The
message-body (if any) is processed as the operation input parameters. message-body (if any) is processed as the operation input parameters.
Refer to Section 3.6 for details on operation resources. Refer to Section 3.6 for details on operation resources.
If the POST request succeeds, a "200 OK" status-line is returned if If the POST request succeeds, a "200 OK" status-line is returned if
there is a response message-body, and a "204 No Content" status-line there is a response message-body, and a "204 No Content" status-line
is returned if there is no response message-body. is returned if there is no response message-body.
If the user is not authorized to invoke the target operation, an If the user is not authorized to invoke the target operation, an
skipping to change at page 39, line 27 skipping to change at page 41, line 19
Example: Example:
In this example, the client is invoking the "play" operation defined In this example, the client is invoking the "play" operation defined
in the "example-jukebox" YANG module. in the "example-jukebox" YANG module.
A client might send a "play" request as follows: A client might send a "play" request as follows:
POST /restconf/operations/example-jukebox:play HTTP/1.1 POST /restconf/operations/example-jukebox:play HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang.operation+json Content-Type: application/yang-data+json
{ {
"example-jukebox:input" : { "example-jukebox:input" : {
"playlist" : "Foo-One", "playlist" : "Foo-One",
"song-number" : 2 "song-number" : 2
} }
} }
The server might respond: The server might respond:
skipping to change at page 40, line 40 skipping to change at page 42, line 31
An "album" child resource defined in the "example-jukebox" YANG An "album" child resource defined in the "example-jukebox" YANG
module is replaced or created if it does not already exist. module is replaced or created if it does not already exist.
To replace the "album" resource contents, the client might send as To replace the "album" resource contents, the client might send as
follows. Note that the request-line is wrapped for display purposes follows. Note that the request-line is wrapped for display purposes
only: only:
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+json Content-Type: application/yang-data+json
{ {
"example-jukebox:album" : { "example-jukebox:album" : [
"name" : "Wasting Light", {
"genre" : "example-jukebox:alternative", "name" : "Wasting Light",
"year" : 2011 "genre" : "example-jukebox:alternative",
} "year" : 2011
}
]
} }
If the resource is updated, the server might respond: If the resource is updated, the server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
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+xml
<album xmlns="http://example.com/ns/example-jukebox" <album xmlns="http://example.com/ns/example-jukebox"
xmlns:jbox="http://example.com/ns/example-jukebox"> xmlns:jbox="http://example.com/ns/example-jukebox">
<name>Wasting Light</name> <name>Wasting Light</name>
<genre>jbox:alternative</genre> <genre>jbox:alternative</genre>
<year>2011</year> <year>2011</year>
</album> </album>
4.6. PATCH 4.6. PATCH
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 (see
Section 4.1). Section 4.1).
This document defines one patch mechanism (Section 4.6.1). The YANG This document defines one patch mechanism (Section 4.6.1). Another
PATCH mechanism is defined in [I-D.ietf-netconf-yang-patch]. Other patch mechanism, the YANG PATCH mechanism, is defined in
patch mechanisms may be defined by future specifications. [I-D.ietf-netconf-yang-patch]. Other patch mechanisms may be defined
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
there is a message-body, and "204 No Content" is returned if no there is a message-body, and "204 No Content" is returned if no
response message-body is sent. response message-body is sent.
If the user is not authorized to alter the target resource an error If the user is not authorized to alter the target resource an error
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. If the target resource is a datastore with the target resource. The message-body for a plain patch MUST be
resource (see Section 3.4), the message body MUST be either present and MUST be represented by the media type "application/
application/yang.datastore+xml or application/yang.datastore+json. yang-data+xml" or "application/yang-data+json".
If then the target resource is a data resource (see Section 3.5),
then the message body MUST be either application/yang.data+xml or
application/yang.data+json.
Plain patch can be used to create or update, but not delete, a child Plain patch can be used to create or update, but not delete, a child
resource within the target resource. Please see resource within the target resource. Please see
[I-D.ietf-netconf-yang-patch] for an alternate media-type supporting [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting
more granular control. The YANG Patch Media Type allows multiple the ability to delete child resources. The YANG Patch Media Type
sub-operations (e.g., merge, delete) within a single PATCH operation. allows multiple sub-operations (e.g., merge, delete) within a single
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.
If the target resource represents a YANG list instance, then the If the target resource represents a YANG list instance, then the
PATCH method MUST NOT change any key leaf values in the message-body PATCH method MUST NOT change any key leaf values in the message-body
representation. representation.
Example: Example:
To replace just the "year" field in the "album" resource (instead of To replace just the "year" field in the "album" resource (instead of
replacing the entire resource with the PUT method), the client might replacing the entire resource with the PUT method), the client might
send a plain patch as follows. 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+xml
<album xmlns="http://example.com/ns/example-jukebox"> <album xmlns="http://example.com/ns/example-jukebox">
<year>2011</year> <year>2011</year>
</album> </album>
If the field is updated, the server might respond: If the field is updated, the server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:49:30 GMT Date: Mon, 23 Apr 2012 17:49:30 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT
ETag: b2788923da4c ETag: "b2788923da4c"
4.7. DELETE 4.7. DELETE
The DELETE method is used to delete the target resource. If the The DELETE method is used to delete the target resource. If the
DELETE request succeeds, a "204 No Content" status-line is returned, DELETE request succeeds, a "204 No Content" status-line is returned.
and there is no response message-body.
If the user is not authorized to delete the target resource then an If the user is not authorized to delete the target resource then an
error response containing a "403 Forbidden" status-line SHOULD be error response containing a "403 Forbidden" status-line SHOULD be
returned. A server MAY return a "404 Not Found" status-line, as returned. A server MAY return a "404 Not Found" status-line, as
described in section 6.5.3 in [RFC7231]. All other error responses described in section 6.5.3 in [RFC7231]. All other error responses
are handled according to the procedures defined in Section 7. are handled according to the procedures defined in Section 7.
If the target resource represents a YANG leaf-list or list, then the If the target resource represents a YANG leaf-list or list, then the
PATCH method SHOULD NOT delete more than one such instance. The DELETE method SHOULD NOT delete more than one such instance. The
server MAY delete more than one instance if a query parameter is used server MAY delete more than one instance if a query parameter is used
requesting this behavior. (Definition of this query parameter is requesting this behavior. (Definition of this query parameter is
outside the scope of this document.) outside the scope of this document.)
Example: Example:
To delete a resource such as the "album" resource, the client might To delete a resource such as the "album" resource, the client might
send: send:
DELETE /restconf/data/example-jukebox:jukebox/ DELETE /restconf/data/example-jukebox:jukebox/
skipping to change at page 43, line 49 skipping to change at page 45, line 43
Each RESTCONF operation allows zero or more query parameters to be Each RESTCONF operation allows zero or more query parameters to be
present in the request URI. The specific parameters that are allowed present in the request URI. The specific parameters that are allowed
depends on the resource type, and sometimes the specific target depends on the resource type, and sometimes the specific target
resource used, in the request. resource used, in the request.
o Query parameters can be given in any order. o Query parameters can be given in any order.
o Each parameter can appear at most once in a request URI. o Each parameter can appear at most once in a request URI.
o If more than one instance of a query parameter is present, then a
"400 Bad Request" status-line MUST be returned by the server.
o A default value may apply if the parameter is missing. o A default value may apply if the parameter is missing.
o Query parameter names and values are case-sensitive o Query parameter names and values are case-sensitive
o A server MUST return an error with a '400 Bad Request' status-line o A server MUST return an error with a '400 Bad Request' status-line
if a query parameter is unexpected. if a query parameter is unexpected.
+-------------------+-------------+---------------------------------+ +-------------------+-------------+---------------------------------+
| Name | Methods | Description | | Name | Methods | Description |
+-------------------+-------------+---------------------------------+ +-------------------+-------------+---------------------------------+
| content | GET | Select config and/or non-config | | content | GET, HEAD | Select config and/or non-config |
| | | data resources | | | | data resources |
| depth | GET | Request limited sub-tree depth | | depth | GET, HEAD | Request limited sub-tree depth |
| | | in the reply content | | | | in the reply content |
| fields | GET | Request a subset of the target | | fields | GET, HEAD | Request a subset of the target |
| | | resource contents | | | | resource contents |
| filter | GET | Boolean notification filter for | | filter | GET, HEAD | Boolean notification filter for |
| | | event stream resources | | | | event stream resources |
| insert | POST, PUT | Insertion mode for ordered-by | | insert | POST, PUT | Insertion mode for ordered-by |
| | | user data resources | | | | user data resources |
| point | POST, PUT | Insertion point for ordered-yb | | point | POST, PUT | Insertion point for ordered-by |
| | | user data resources | | | | user data resources |
| start-time | GET | Replay buffer start time for | | start-time | GET, HEAD | Replay buffer start time for |
| | | event stream resources | | | | event stream resources |
| stop-time | GET | Replay buffer stop time for | | stop-time | GET, HEAD | Replay buffer stop time for |
| | | event stream resources | | | | event stream resources |
| with-defaults | GET | Control retrieval of default | | with-defaults | GET, HEAD | Control retrieval of default |
| | | values | | | | values |
+-------------------+-------------+---------------------------------+ +-------------------+-------------+---------------------------------+
RESTCONF Query Parameters RESTCONF Query Parameters
Refer to Appendix D.3 for examples of query parameter usage. Refer to Appendix D.3 for examples of query parameter usage.
If vendors define additional query parameters, they SHOULD use a If vendors define additional query parameters, they SHOULD use a
prefix (such as the enterprise or organization name) for query prefix (such as the enterprise or organization name) for query
parameter names in order to avoid collisions with other parameters. parameter names in order to avoid collisions with other parameters.
skipping to change at page 45, line 31 skipping to change at page 47, line 31
Any child nodes which are contained within a parent node have a depth Any child nodes which are contained within a parent node have a depth
value that is 1 greater than its parent. value that is 1 greater than its parent.
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.
More than one "depth" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server.
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. Only one level of sub-resources with a different
media type than the target resource will be returned. The exception media type than the target resource will be returned. The exception
is the datastore resource. If this resource type is retrieved then is the datastore resource. If this resource type is retrieved then
by default the datastore and all 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.
skipping to change at page 46, line 12 skipping to change at page 48, line 7
The client can use this parameter to retrieve a subset of all nodes The client can use this parameter to retrieve a subset of all nodes
in a resource. in a resource.
A value of the "fields" query parameter matches the following rule: A value of the "fields" query parameter matches the following rule:
fields-expr = path '(' fields-expr ')' / fields-expr = path '(' fields-expr ')' /
path ';' fields-expr / path ';' fields-expr /
path path
path = api-identifier [ '/' path ] path = api-identifier [ '/' path ]
"api-identifier" is defined in Section 3.5.1.1. "api-identifier" is defined in Section 3.5.3.1.
";" is used to select multiple nodes. For example, to retrieve only ";" is used to select multiple nodes. For example, to retrieve only
the "genre" and "year" of an album, use: "fields=genre;year". the "genre" and "year" of an album, use: "fields=genre;year".
Parentheses are used to specify sub-selectors of a node. Parentheses are used to specify sub-selectors of a node. Note that
there is no path separator character '/' between a "path" field and
left parenthesis character '('.
For example, assume the target resource is the "album" list. To For example, assume the target resource is the "album" list. To
retrieve only the "label" and "catalogue-number" of the "admin" retrieve only the "label" and "catalogue-number" of the "admin"
container within an album, use: container within an album, use:
"fields=admin(label;catalogue-number)". "fields=admin(label;catalogue-number)".
"/" is used in a path to retrieve a child node of a node. For "/" is used in a path to retrieve a child node of a node. For
example, to retrieve only the "label" of an album, use: "fields=admin example, to retrieve only the "label" of an album, use: "fields=admin
/label". /label".
This parameter is only allowed for GET methods on api, datastore, and This parameter is only allowed for GET methods on api, datastore, and
data resources. A "400 Bad Request" status-line is returned if used data resources. A "400 Bad Request" status-line is returned if used
for other methods or resource types. for other methods or resource types.
More than one "fields" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server.
If the "fields" query parameter URI is listed in the "capability" If the "fields" query parameter URI is listed in the "capability"
leaf-list in Section 9.3, then the server supports the "fields" leaf-list in Section 9.3, then the server supports the "fields"
parameter. parameter.
4.8.4. The "filter" Query Parameter 4.8.4. The "filter" Query Parameter
The "filter" parameter is used to indicate which subset of all The "filter" parameter is used to indicate which subset of all
possible events are of interest. If not present, all events not possible events are of interest. If not present, all events not
precluded by other parameters will be sent. precluded by other parameters will be sent.
skipping to change at page 47, line 11 skipping to change at page 49, line 6
The format of this parameter is an XPath 1.0 expression, and is The format of this parameter is an XPath 1.0 expression, and is
evaluated in the following context: evaluated in the following context:
o The set of namespace declarations is the set of prefix and o The set of namespace declarations is the set of prefix and
namespace pairs for all supported YANG modules, where the prefix namespace pairs for all supported YANG modules, where the prefix
is the YANG module name, and the namespace is as defined by the is the YANG module name, and the namespace is as defined by the
"namespace" statement in the YANG module. "namespace" statement in the YANG module.
o The function library is the core function library defined in XPath o The function library is the core function library defined in XPath
1.0. 1.0, plus any functions defined by the data model.
o The set of variable bindings is empty. o The set of variable bindings is empty.
o The context node is the root node. o The context node is the root node.
More than one "filter" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server.
The filter is used as defined in [RFC5277], Section 3.6. If the The filter is used as defined in [RFC5277], Section 3.6. If the
boolean result of the expression is true when applied to the boolean result of the expression is true when applied to the
conceptual "notification" document root, then the event notification conceptual "notification" document root, then the event notification
is delivered to the client. is delivered to the client.
If the "filter" query parameter URI is listed in the "capability" If the "filter" query parameter URI is listed in the "capability"
leaf-list in Section 9.3, then the server supports the "filter" query leaf-list in Section 9.3, then the server supports the "filter" query
parameter. parameter.
4.8.5. The "insert" Query Parameter 4.8.5. The "insert" Query Parameter
skipping to change at page 48, line 10 skipping to change at page 49, line 46
| | specified by the value of the "point" parameter. | | | specified by the value of the "point" parameter. |
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
The default value is "last". The default value is "last".
This parameter is only supported for the POST and PUT methods. It is This parameter is only supported for the POST and PUT methods. It is
also only supported if the target resource is a data resource, and also only supported if the target resource is a data resource, and
that data represents a YANG list or leaf-list that is ordered-by that data represents a YANG list or leaf-list that is ordered-by
user. user.
More than one "insert" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server.
If the values "before" or "after" are used, then a "point" query If the values "before" or "after" are used, then a "point" query
parameter for the insertion parameter MUST also be present, or a "400 parameter for the insertion parameter MUST also be present, or a "400
Bad Request" status-line is returned. Bad Request" status-line is returned.
The "insert" query parameter MUST be supported by the server. The "insert" query parameter MUST be supported by the server.
4.8.6. The "point" Query Parameter 4.8.6. The "point" Query Parameter
The "point" parameter is used to specify the insertion point for a The "point" parameter is used to specify the insertion point for a
data resource that is being created or moved within an ordered-by data resource that is being created or moved within an ordered-by
skipping to change at page 48, line 39 skipping to change at page 50, line 24
This parameter is only supported for the POST and PUT methods. It is This parameter is only supported for the POST and PUT methods. It is
also only supported if the target resource is a data resource, and also only supported if the target resource is a data resource, and
that data represents a YANG list or leaf-list that is ordered-by that data represents a YANG list or leaf-list that is ordered-by
user. user.
If the "insert" query parameter is not present, or has a value other If the "insert" query parameter is not present, or has a value other
than "before" or "after", then a "400 Bad Request" status-line is than "before" or "after", then a "400 Bad Request" status-line is
returned. returned.
More than one "point" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server.
This parameter contains the instance identifier of the resource to be This parameter contains the instance identifier of the resource to be
used as the insertion point for a POST or PUT method. used as the insertion point for a POST or PUT method.
The "point" query parameter MUST be supported by the server. The "point" query parameter MUST be supported by the server.
4.8.7. The "start-time" Query Parameter 4.8.7. The "start-time" Query Parameter
The "start-time" parameter is used to trigger the notification replay The "start-time" parameter is used to trigger the notification replay
feature and indicate that the replay should start at the time feature defined in [RFC5277] and indicate that the replay should
specified. If the stream does not support replay, per the start at the time specified. If the stream does not support replay,
"replay-support" attribute returned by stream list entry for the per the "replay-support" attribute returned by stream list entry for
stream resource, then the server MUST return a "400 Bad Request" the stream resource, then the server MUST return a "400 Bad Request"
status-line. status-line.
The value of the "start-time" parameter is of type "date-and-time", The value of the "start-time" parameter is of type "date-and-time",
defined in the "ietf-yang" YANG module [RFC6991]. defined in the "ietf-yang" YANG module [RFC6991].
This parameter is only allowed for GET methods on a text/event-stream This parameter is only allowed for GET methods on a text/event-stream
data resource. A "400 Bad Request" status-line is returned if used data resource. A "400 Bad Request" status-line is returned if used
for other methods or resource types. for other methods or resource types.
More than one "start-time" query parameter MUST NOT appear in a
request. If more than one instance is present, then a "400 Bad
Request" status-line MUST be returned by the server.
If this parameter is not present, then a replay subscription is not If this parameter is not present, then a replay subscription is not
being requested. It is not valid to specify start times that are being requested. It is not valid to specify start times that are
later than the current time. If the value specified is earlier than later than the current time. If the value specified is earlier than
the log can support, the replay will begin with the earliest the log can support, the replay will begin with the earliest
available notification. available notification. A client can obtain a server's current time
by examining the "Date" header field that the server returns in
response messages, according to [RFC7231].
If this query parameter is supported by the server, then the "replay" If this query parameter is supported by the server, then the "replay"
query parameter URI MUST be listed in the "capability" leaf-list in query parameter URI MUST be listed in the "capability" leaf-list in
Section 9.3. The "stop-time" query parameter MUST also be supported Section 9.3. The "stop-time" query parameter MUST also be supported
by the server. by the server.
If the "replay-support" leaf has the value 'true' in the "stream" If the "replay-support" leaf has the value 'true' in the "stream"
entry (defined in Section 9.3) then the server MUST support the entry (defined in Section 9.3) then the server MUST support the
"start-time" and "stop-time" query parameters for that stream. "start-time" and "stop-time" query parameters for that stream.
skipping to change at page 50, line 5 skipping to change at page 51, line 27
the newest notifications of interest. This parameter MUST be used the newest notifications of interest. This parameter MUST be used
with and have a value later than the "start-time" parameter. with and have a value later than the "start-time" parameter.
The value of the "stop-time" parameter is of type "date-and-time", The value of the "stop-time" parameter is of type "date-and-time",
defined in the "ietf-yang" YANG module [RFC6991]. defined in the "ietf-yang" YANG module [RFC6991].
This parameter is only allowed for GET methods on a text/event-stream This parameter is only allowed for GET methods on a text/event-stream
data resource. A "400 Bad Request" status-line is returned if used data resource. A "400 Bad Request" status-line is returned if used
for other methods or resource types. for other methods or resource types.
More than one "stop-time" query parameter MUST NOT appear in a
request. If more than one instance is present, then a "400 Bad
Request" status-line MUST be returned by the server.
If this parameter is not present, the notifications will continue If this parameter is not present, the notifications will continue
until the subscription is terminated. Values in the future are until the subscription is terminated. Values in the future are
valid. valid.
If this query parameter is supported by the server, then the "replay" If this query parameter is supported by the server, then the "replay"
query parameter URI MUST be listed in the "capability" leaf-list in query parameter URI MUST be listed in the "capability" leaf-list in
Section 9.3. The "start-time" query parameter MUST also be supported Section 9.3. The "start-time" query parameter MUST also be supported
by the server. by the server.
If the "replay-support" leaf is present in the "stream" entry If the "replay-support" leaf is present in the "stream" entry
skipping to change at page 51, line 13 skipping to change at page 52, line 29
of [RFC6243]. of [RFC6243].
If the "with-defaults" parameter is set to "explicit" then the server If the "with-defaults" parameter is set to "explicit" then the server
MUST adhere to the defaults reporting behavior defined in Section 3.3 MUST adhere to the defaults reporting behavior defined in Section 3.3
of [RFC6243]. of [RFC6243].
If the "with-defaults" parameter is set to "report-all-tagged" then If the "with-defaults" parameter is set to "report-all-tagged" then
the server MUST adhere to the defaults reporting behavior defined in the server MUST adhere to the defaults reporting behavior defined in
Section 3.4 of [RFC6243]. Section 3.4 of [RFC6243].
More than one "with-defaults" query parameter MUST NOT appear in a
request. If more than one instance is present, then a "400 Bad
Request" status-line MUST be returned by the server.
If the "with-defaults" parameter is not present then the server MUST If the "with-defaults" parameter is not present then the server MUST
adhere to the defaults reporting behavior defined in its "basic-mode" adhere to the defaults reporting behavior defined in its "basic-mode"
parameter for the "defaults" protocol capability URI, defined in parameter for the "defaults" protocol capability URI, defined in
Section 9.1.2. Section 9.1.2.
If the server includes the "with-defaults" query parameter URI in the If the server includes the "with-defaults" query parameter URI in the
"capability" leaf-list in Section 9.3, then the "with-defaults" query "capability" leaf-list in Section 9.3, then the "with-defaults" query
parameter MUST be supported. parameter MUST be supported.
5. Messages 5. Messages
skipping to change at page 51, line 42 skipping to change at page 53, line 8
which allows multiple datastore edits within a single message. which allows multiple datastore edits within a single message.
5.1. Request URI Structure 5.1. Request URI Structure
Resources are represented with URIs following the structure for Resources are represented with URIs following the structure for
generic URIs in [RFC3986]. generic URIs in [RFC3986].
A RESTCONF operation is derived from the HTTP method and the request A RESTCONF operation is derived from the HTTP method and the request
URI, using the following conceptual fields: URI, using the following conceptual fields:
<OP> /<restconf>/<path>?<query>#<fragment> <OP> /<restconf>/<path>?<query>#<fragment>
^ ^ ^ ^ ^ ^ ^ ^ ^ ^
| | | | | | | | | |
method entry resource query fragment method entry resource query fragment
M M O O I M M O O I
M=mandatory, O=optional, I=ignored M=mandatory, O=optional, I=ignored
where: where:
<OP> is the HTTP method <OP> is the HTTP method
<restconf> is the RESTCONF entry point <restconf> is the RESTCONF entry point
<path> is the Target Resource URI <path> is the Target Resource URI
<query> is the query parameter list <query> is the query parameter list
<fragment> is not used in RESTCONF <fragment> is not used in RESTCONF
skipping to change at page 52, line 23 skipping to change at page 53, line 38
in the request URI. RESTCONF operation details are described in in the request URI. RESTCONF operation details are described in
Section 4. Section 4.
o entry: the root of the RESTCONF API configured on this HTTP o entry: the root of the RESTCONF API configured on this HTTP
server, discovered by getting the "/.well-known/host-meta" server, discovered by getting the "/.well-known/host-meta"
resource, as described in Section 3.1. resource, as described in Section 3.1.
o resource: the path expression identifying the resource that is o resource: the path expression identifying the resource that is
being accessed by the operation. If this field is not present, being accessed by the operation. If this field is not present,
then the target resource is the API itself, represented by the then the target resource is the API itself, represented by the
media type "application/yang.api". YANG data template named "yang-api", found in Section 8.
o query: the set of parameters associated with the RESTCONF message. o query: the set of parameters associated with the RESTCONF message,
These have the familiar form of "name=value" pairs. Most query as defined in section 3.4 of [RFC3986]. RESTCONF parameters have
parameters are optional to implement by the server and optional to the familiar form of "name=value" pairs. Most query parameters
use by the client. Each optional query parameter is identified by are optional to implement by the server and optional to use by the
a URI. The server MUST list the optional query parameter URIs it client. Each optional query parameter is identified by a URI.
supports in the "capabilities" list defined in Section 9.3. The server MUST list the optional query parameter URIs it supports
in the "capabilities" list defined in Section 9.3.
There is a specific set of parameters defined, although the server There is a specific set of parameters defined, although the server
MAY choose to support query parameters not defined in this document. MAY choose to support query parameters not defined in this document.
The contents of the any query parameter value MUST be encoded The contents of the any query parameter value MUST be encoded
according to [RFC3986], Section 3.4. Any reserved characters MUST be according to [RFC3986], Section 3.4. Any reserved characters MUST be
percent-encoded, according to [RFC3986], section 2.1. percent-encoded, according to [RFC3986], section 2.1.
o fragment: This field is not used by the RESTCONF protocol. o fragment: This field is not used by the RESTCONF protocol.
When new resources are created by the client, a "Location" header is When new resources are created by the client, a "Location" header is
skipping to change at page 53, line 4 skipping to change at page 54, line 18
returned, which identifies the path of the newly created resource. returned, which identifies the path of the newly created resource.
The client uses this exact path identifier to access the resource The client uses this exact path identifier to access the resource
once it has been created. once it has been created.
The "target" of an operation is a resource. The "path" field in the The "target" of an operation is a resource. The "path" field in the
request URI represents the target resource for the operation. request URI represents the target resource for the operation.
Refer to Appendix D for examples of RESTCONF Request URIs. Refer to Appendix D for examples of RESTCONF Request URIs.
5.2. Message Encoding 5.2. Message Encoding
RESTCONF messages are encoded in HTTP according to [RFC7230]. The RESTCONF messages are encoded in HTTP according to [RFC7230]. The
"utf-8" character set is used for all messages. RESTCONF message "utf-8" character set is used for all messages. RESTCONF message
content is sent in the HTTP message-body. content is sent in the HTTP message-body.
Content is encoded in either JSON or XML format. A server MUST Content is encoded in either JSON or XML format. A server MUST
support XML or JSON encoding. XML encoding rules for data nodes are support XML or JSON encoding. XML encoding rules for data nodes are
defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are
used for all XML content. JSON encoding rules are defined in used for all XML content. JSON encoding rules are defined in
[I-D.ietf-netmod-yang-json]. JSON encoding of meta-data is defined [I-D.ietf-netmod-yang-json]. JSON encoding of metadata is defined in
in [I-D.ietf-netmod-yang-metadata]. This encoding is valid JSON, but [I-D.ietf-netmod-yang-metadata]. This encoding is valid JSON, but
also has special encoding rules to identify module namespaces and also has special encoding rules to identify module namespaces and
provide consistent type processing of YANG data. provide consistent type processing of YANG data.
Request input content encoding format is identified with the Content- Request input content encoding format is identified with the Content-
Type header. This field MUST be present if a message-body is sent by Type header. This field MUST be present if a message-body is sent by
the client. the client.
The server MUST support the "Accept" header and "406 Not Acceptable" The server MUST support the "Accept" header and "406 Not Acceptable"
status-line, as defined in [RFC7231]. Response output content status-line, as defined in [RFC7231]. Response output content
encoding format is identified with the Accept header in the request. encoding format is identified with the Accept header in the request.
If it is not specified, the request input encoding format SHOULD be If it is not specified, the request input encoding format SHOULD be
used, or the server MAY choose any supported content encoding format. used, or the server MAY choose any supported content encoding format.
If there was no request input, then the default output encoding is If there was no request input, then the default output encoding is
XML or JSON, depending on server preference. File extensions encoded XML or JSON, depending on server preference. File extensions encoded
in the request are not used to identify format encoding. in the request are not used to identify format encoding.
5.3. RESTCONF Meta-Data A client can determine if the RESTCONF server supports an encoding
format by sending a request using a specific format in the Content-
Type and/or Accept header. If the server does not support the
requested input encoding for a request, then it MUST return an error
response with a '415 Unsupported Media Type' status-line. If the
server does not support any of the requested output encodings for a
request, then it MUST return an error response with a '406 Not
Acceptable' status-line.
The RESTCONF protocol needs to retrieve the same meta-data that is 5.3. RESTCONF Metadata
The RESTCONF protocol needs to retrieve the same metadata that is
used in the NETCONF protocol. Information about default leafs, last- used in the NETCONF protocol. Information about default leafs, last-
modified timestamps, etc. are commonly used to annotate modified timestamps, etc. are commonly used to annotate
representations of the datastore contents. This meta-data is not representations of the datastore contents.
defined in the YANG schema because it applies to the datastore, and
is common across all data nodes.
This information is encoded as attributes in XML. JSON encoding of With the XML encoding, the metadata is encoded as attributes in XML.
meta-data is defined in [I-D.ietf-netmod-yang-metadata]. With the JSON encoding, the metadata is encoded as specified in
[I-D.ietf-netmod-yang-metadata].
The following examples are based on the example in Appendix D.3.9. The following examples are based on the example in Appendix D.3.9.
The "report-all-tagged" mode for the "with-defaults" query parameter The "report-all-tagged" mode for the "with-defaults" query parameter
requires that a "default" attribute be returned for default nodes. requires that a "default" attribute be returned for default nodes.
This example shows that attribute for the "mtu" leaf . This example shows that attribute for the "mtu" leaf .
5.3.1. XML MetaData Encoding Example 5.3.1. XML MetaData Encoding Example
GET /restconf/data/interfaces/interface=eth1 GET /restconf/data/interfaces/interface=eth1
?with-defaults=report-all-tagged HTTP/1.1 ?with-defaults=report-all-tagged HTTP/1.1
skipping to change at page 54, line 4 skipping to change at page 55, line 34
The following examples are based on the example in Appendix D.3.9. The following examples are based on the example in Appendix D.3.9.
The "report-all-tagged" mode for the "with-defaults" query parameter The "report-all-tagged" mode for the "with-defaults" query parameter
requires that a "default" attribute be returned for default nodes. requires that a "default" attribute be returned for default nodes.
This example shows that attribute for the "mtu" leaf . This example shows that attribute for the "mtu" leaf .
5.3.1. XML MetaData Encoding Example 5.3.1. XML MetaData Encoding Example
GET /restconf/data/interfaces/interface=eth1 GET /restconf/data/interfaces/interface=eth1
?with-defaults=report-all-tagged HTTP/1.1 ?with-defaults=report-all-tagged HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+xml Accept: application/yang-data+xml
The server might respond as follows. The server might respond as follows.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 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+xml
<interface <interface
xmlns="urn:example.com:params:xml:ns:yang:example-interface"> xmlns="urn:example.com:params:xml:ns:yang:example-interface">
<name>eth1</name> <name>eth1</name>
<mtu xmlns:wd="urn:ietf:params:xml:ns:netconf:default:1.0" <mtu xmlns:wd="urn:ietf:params:xml:ns:netconf:default:1.0"
wd:default="true">1500</mtu> wd:default="true">1500</mtu>
<status>up</status> <status>up</status>
</interface> </interface>
5.3.2. JSON MetaData Encoding Example 5.3.2. JSON MetaData Encoding Example
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 manually. The value
"ietf-netconf-with-defaults" is assigned for JSON meta-data encoding. "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
Server: example-server Server: example-server
Content-Type: application/yang.data+json Content-Type: application/yang-data+json
{ {
"example:interface": [ "example:interface": [
{ {
"name" : "eth1", "name" : "eth1",
"mtu" : 1500, "mtu" : 1500,
"@mtu": { "@mtu": {
"ietf-netconf-with-defaults:default" : true "ietf-netconf-with-defaults:default" : true
}, },
"status" : "up" "status" : "up"
} }
] ]
} }
5.4. Return Status 5.4. Return Status
Each message represents some sort of resource access. An HTTP Each message represents some sort of resource access. An HTTP
"status-line" header line is returned for each request. If a 4xx or "status-line" header line is returned for each request. If a "4xx"
5xx range status code is returned in the status-line, then the error range status code is returned in the status-line, then the error
information will be returned in the response, according to the format information SHOULD be returned in the response, according to the
defined in Section 7.1. format defined in Section 7.1. If a "5xx" range status code is
returned in the status-line, then the error information MAY be
returned in the response, according to the format defined in
Section 7.1. If a 1xx, 2xx, or 3xx range status code is returned in
the status-line, then error information MUST NOT be returned in the
response, since these ranges do not represent error conditions.
5.5. Message Caching 5.5. Message Caching
Since the datastore contents change at unpredictable times, responses Since the datastore contents change at unpredictable times, responses
from a RESTCONF server generally SHOULD NOT be cached. from a RESTCONF server generally SHOULD NOT be cached.
The server SHOULD include a "Cache-Control" header in every response The server SHOULD include a "Cache-Control" header in every response
that specifies whether the response should be cached. A "Pragma" that specifies whether the response should be cached.
header specifying "no-cache" MAY also be sent in case the
"Cache-Control" header is not supported.
Instead of relying on HTTP caching, the client SHOULD track the Instead of relying on HTTP caching, the client SHOULD track the
"ETag" and/or "Last-Modified" headers returned by the server for the "ETag" and/or "Last-Modified" headers returned by the server for the
datastore resource (or data resource if the server supports it). A datastore resource (or data resource if the server supports it). A
retrieval request for a resource can include the "If-None-Match" and/ retrieval request for a resource can include the "If-None-Match" and/
or "If-Modified-Since" headers, which will cause the server to return or "If-Modified-Since" headers, which will cause the server to return
a "304 Not Modified" status-line if the resource has not changed. a "304 Not Modified" status-line if the resource has not changed.
The client MAY use the HEAD method to retrieve just the message The client MAY use the HEAD method to retrieve just the message
headers, which SHOULD include the "ETag" and "Last-Modified" headers, headers, which SHOULD include the "ETag" and "Last-Modified" headers,
if this meta-data is maintained for the target resource. if this metadata is maintained for the target resource.
6. Notifications 6. Notifications
The RESTCONF protocol supports YANG-defined event notifications. The The RESTCONF protocol supports YANG-defined event notifications. The
solution preserves aspects of NETCONF Event Notifications [RFC5277] solution preserves aspects of NETCONF Event Notifications [RFC5277]
while utilizing the Server-Sent Events [W3C.CR-eventsource-20121211] while utilizing the Server-Sent Events [W3C.REC-eventsource-20150203]
transport strategy. transport strategy.
6.1. Server Support 6.1. Server Support
A RESTCONF server MAY support RESTCONF notifications. Clients may A RESTCONF server MAY support RESTCONF notifications. Clients may
determine if a server supports RESTCONF notifications by using the determine if a server supports RESTCONF notifications by using the
HTTP operation OPTIONS, HEAD, or GET on the stream list. The server HTTP operation OPTIONS, HEAD, or GET on the stream list. The server
does not support RESTCONF notifications if an HTTP error code is does not support RESTCONF notifications if an HTTP error code is
returned (e.g., "404 Not Found" status-line). returned (e.g., "404 Not Found" status-line).
skipping to change at page 56, line 24 skipping to change at page 57, line 52
specify the structure and syntax of the conceptual child resources specify the structure and syntax of the conceptual child resources
within the "streams" resource. within the "streams" resource.
For example: For example:
The client might send the following request: The client might send the following request:
GET /restconf/data/ietf-restconf-monitoring:restconf-state/ GET /restconf/data/ietf-restconf-monitoring:restconf-state/
streams HTTP/1.1 streams HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+xml Accept: application/yang-data+xml
The server might send the following response: The server might send the following response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/yang.api+xml Content-Type: application/yang-data+xml
<streams <streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<stream> <stream>
<name>NETCONF</name> <name>NETCONF</name>
<description>default NETCONF event stream <description>default NETCONF event stream
</description> </description>
<replay-support>true</replay-support> <replay-support>true</replay-support>
<replay-log-creation-time> <replay-log-creation-time>
2007-07-08T00:00:00Z 2007-07-08T00:00:00Z
skipping to change at page 57, line 40 skipping to change at page 59, line 20
RESTCONF clients can determine the URL for the subscription resource RESTCONF clients can determine the URL for the subscription resource
(to receive notifications) by sending an HTTP GET request for the (to receive notifications) by sending an HTTP GET request for the
"location" leaf with the stream list entry. The value returned by "location" leaf with the stream list entry. The value returned by
the server can be used for the actual notification subscription. the server can be used for the actual notification subscription.
The client will send an HTTP GET request for the URL returned by the The client will send an HTTP GET request for the URL returned by the
server with the "Accept" type "text/event-stream". server with the "Accept" type "text/event-stream".
The server will treat the connection as an event stream, using the The server will treat the connection as an event stream, using the
Server Sent Events [W3C.CR-eventsource-20121211] transport strategy. Server Sent Events [W3C.REC-eventsource-20150203] transport strategy.
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+xml
The server might send the following response: The server might send the following response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/yang.api+xml Content-Type: application/yang-data+xml
<location <location
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
https://example.com/streams/NETCONF https://example.com/streams/NETCONF
</location> </location>
The RESTCONF client can then use this URL value to start monitoring The RESTCONF client can then use this URL value to start monitoring
the event stream: the event stream:
GET /streams/NETCONF HTTP/1.1 GET /streams/NETCONF HTTP/1.1
Host: example.com Host: example.com
Accept: text/event-stream Accept: text/event-stream
Cache-Control: no-cache Cache-Control: no-cache
Connection: keep-alive Connection: keep-alive
A RESTCONF client MAY request that the server compress the events
A RESTCONF client MAY request the server compress the events using using the HTTP header field "Accept-Encoding". For instance:
the HTTP header field "Accept-Encoding". For instance:
GET /streams/NETCONF HTTP/1.1 GET /streams/NETCONF HTTP/1.1
Host: example.com Host: example.com
Accept: text/event-stream Accept: text/event-stream
Cache-Control: no-cache Cache-Control: no-cache
Connection: keep-alive Connection: keep-alive
Accept-Encoding: gzip, deflate Accept-Encoding: gzip, deflate
6.3.1. NETCONF Event Stream 6.3.1. NETCONF Event Stream
skipping to change at page 61, line 14 skipping to change at page 62, line 40
meaningful values that could be used for them that would not be meaningful values that could be used for them that would not be
redundant to the contents of the notification itself. RESTCONF redundant to the contents of the notification itself. RESTCONF
servers that do not send the "id" field also do not need to support servers that do not send the "id" field also do not need to support
the HTTP header "Last-Event-Id". RESTCONF servers that do send the the HTTP header "Last-Event-Id". RESTCONF servers that do send the
"id" field MUST still support the "startTime" query parameter as the "id" field MUST still support the "startTime" query parameter as the
preferred means for a client to specify where to restart the event preferred means for a client to specify where to restart the event
stream. stream.
7. Error Reporting 7. Error Reporting
HTTP status-lines are used to report success or failure for RESTCONF HTTP status codes are used to report success or failure for RESTCONF
operations. The <rpc-error> element returned in NETCONF error operations. The <rpc-error> element returned in NETCONF error
responses contains some useful information. This error information responses contains some useful information. This error information
is adapted for use in RESTCONF, and error information is returned for is adapted for use in RESTCONF, and error information is returned for
"4xx" class of status codes. "4xx" and "5xx" class of status codes.
The following table summarizes the return status codes used
specifically by RESTCONF operations:
+----------------------------+--------------------------------------+
| Status-Line | Description |
+----------------------------+--------------------------------------+
| 100 Continue | POST accepted, 201 should follow |
| 200 OK | Success with response message-body |
| 201 Created | POST to create a resource success |
| 204 No Content | Success without response message- |
| | body |
| 304 Not Modified | Conditional operation not done |
| 400 Bad Request | Invalid request message |
| 401 Unauthorized | Client cannot be authenticated |
| 403 Forbidden | Access to resource denied |
| 404 Not Found | Resource target or resource node not |
| | found |
| 405 Method Not Allowed | Method not allowed for target |
| | resource |
| 409 Conflict | Resource or lock in use |
| 412 Precondition Failed | Conditional method is false |
| 413 Request Entity Too | too-big error |
| Large | |
| 414 Request-URI Too Large | too-big error |
| 415 Unsupported Media Type | non RESTCONF media type |
| 500 Internal Server Error | operation-failed |
| 501 Not Implemented | unknown-operation |
| 503 Service Unavailable | Recoverable server error |
+----------------------------+--------------------------------------+
HTTP Status Codes used in RESTCONF
Since an operation resource is defined with a YANG "rpc" statement, Since an operation resource is defined with a YANG "rpc" statement,
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 condition and response code to use are needed. The specific error-tag and response code to use are data-
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&#8209;tag> | status code | | error-tag | status code |
+-------------------------+-------------+ +-------------------------+-------------+
| in-use | 409 | | in-use | 409 |
| invalid-value | 400 | | invalid-value | 400 |
| too-big | 413 | | (request) too-big | 413 |
| (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 |
skipping to change at page 62, line 41 skipping to change at page 63, line 35
| operation-failed | 500 | | operation-failed | 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
a "4xx" class of status codes will be returned (except for status the status code that will be returned is in the "4xx" range (except
code "403 Forbidden"), then the server SHOULD send a response for status code "403 Forbidden"), then the server SHOULD send a
message-body containing the information described by the "errors" response message-body containing the information described by the
container definition within the YANG module Section 8. The Content- "yang-errors" YANG template definition within the "ietf-restconf"
Type of this response message MUST be a subtype of application/ module, found in Section 8. The Content-Type of this response
yang.errors (see example below). message MUST be a subtype of application/yang-data (see example
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.errors+xml" or "application/ the server MUST select "application/yang-data+xml" or "application/
yang.errors+json", depending on server preference. All of the yang-data+json", depending on server preference. All of the examples
examples in this document, except for the one below, assume that XML in this document, except for the one below, assume that XML encoding
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
+--ro error-app-tag? string +--ro error-app-tag? string
+--ro error-path? instance-identifier +--ro error-path? instance-identifier
+--ro error-message? string +--ro error-message? string
+--ro error-info +--ro error-info
The semantics and syntax for RESTCONF error messages are defined in The semantics and syntax for RESTCONF error messages are defined with
the "application/yang.errors" restconf-media-type extension in the "yang-errors" YANG data template extension, found in Section 8.
Section 8.
Examples: Examples:
The following example shows an error returned for an "lock-denied" The following example shows an error returned for an "lock-denied"
error that can occur if a NETCONF client has locked a datastore. The error that can occur if a NETCONF client has locked a datastore. The
RESTCONF client is attempting to delete a data resource. Note that RESTCONF client is attempting to delete a data resource. Note that
an Accept header is used to specify the desired encoding for the an Accept header is used to specify the desired encoding for the
error message. No response message-body content is expected by the error message. No response message-body content is expected by the
client in this example. client in this example.
DELETE /restconf/data/example-jukebox:jukebox/ DELETE /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.errors+json Accept: application/yang-data+json
The server might respond: The server might respond:
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.errors+json Content-Type: application/yang-data+json
{ {
"ietf-restconf:errors": { "ietf-restconf:errors": {
"error": [ "error": [
{ {
"error-type": "protocol", "error-type": "protocol",
"error-tag": "lock-denied", "error-tag": "lock-denied",
"error-message": "Lock failed, lock already held" "error-message": "Lock failed, lock already held"
} }
] ]
} }
} }
The following example shows an error returned for a "data-exists" The following example shows an error returned for a "data-exists"
error on a data resource. The "jukebox" resource already exists so error on a data resource. The "jukebox" resource already exists so
it cannot be created. it cannot be created.
The client might send: The client might send:
skipping to change at page 64, line 24 skipping to change at page 65, line 19
The client might send: The client might send:
POST /restconf/data/example-jukebox:jukebox HTTP/1.1 POST /restconf/data/example-jukebox:jukebox HTTP/1.1
Host: example.com Host: example.com
The server might respond (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.errors+xml Content-Type: application/yang-data+xml
<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error> <error>
<error-type>protocol</error-type> <error-type>protocol</error-type>
<error-tag>data-exists</error-tag> <error-tag>data-exists</error-tag>
<error-path <error-path
xmlns:rc="urn:ietf:params:xml:ns:yang:ietf-restconf" xmlns:rc="urn:ietf:params:xml:ns:yang:ietf-restconf"
xmlns:jbox="https://example.com/ns/example-jukebox"> xmlns:jbox="https://example.com/ns/example-jukebox">
/rc:restconf/rc:data/jbox:jukebox /rc:restconf/rc:data/jbox:jukebox
</error-path> </error-path>
skipping to change at page 64, line 49 skipping to change at page 65, line 44
</errors> </errors>
8. RESTCONF module 8. RESTCONF module
The "ietf-restconf" module defines conceptual definitions within an The "ietf-restconf" module defines conceptual definitions within an
extension and two groupings, which are not meant to be implemented as extension and two groupings, which are not meant to be implemented as
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-
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-03-16.yang" <CODE BEGINS> file "ietf-restconf@2016-06-28.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/>
skipping to change at page 66, line 4 skipping to change at page 66, line 50
Copyright (c) 2016 IETF Trust and the persons identified as Copyright (c) 2016 IETF Trust and the persons identified as
authors of the code. All rights reserved. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
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-13.txt // Note: extracted from draft-ietf-netconf-restconf-14.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-03-16 { revision 2016-06-28 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
extension restconf-media-type { extension yang-data {
argument media-type-id { argument name {
yin-element true; yin-element true;
} }
// RFC Ed.: replace draft-ietf-netmod-yang-json with RFC number
// in the description below, and remove this note.
description description
"This extension is used to specify a YANG data structure which "This extension is used to specify a YANG data template which
represents a conceptual RESTCONF media type. represents conceptual data defined in YANG. It is
intended to describe hierarchical data independent of
protocol context or specific message encoding format.
Data definition statements within this extension specify Data definition statements within this extension specify
the generic syntax for the specific media type. the generic syntax for the specific YANG data template.
YANG is mapped to specific encoding formats outside the Note that this extension does not define a media-type.
scope of this extension statement. RFC 6020 defines XML A specification using this extension MUST specify the
encoding rules for all RESTCONF media types that use message encoding rules, including the content media type.
the '+xml' suffix. draft-ietf-netmod-yang-json defines
JSON encoding rules for all RESTCONF media types that
use the '+json' suffix.
The 'media-type-id' parameter value identifies the media type The mandatory 'name' parameter value identifies the YANG
that is being defined. It contains the string associated data template that is being defined. It contains the
with the generic media type, i.e., no suffix is specified. template name.
This extension is ignored unless it appears as a top-level This extension is ignored unless it appears as a top-level
statement. It SHOULD contain data definition statements statement. It SHOULD contain data definition statements
that result in exactly one container data node definition. that result in exactly one container data node definition.
This allows compliant translation to an XML instance This allows compliant translation to an XML instance
document for each media type. document for each YANG data template.
The module name and namespace value for the YANG module using The module name and namespace value for the YANG module using
the extension statement is assigned to instance document data the extension statement is assigned to instance document data
conforming to the data definition statements within conforming to the data definition statements within
this extension. this extension.
The sub-statements of this extension MUST follow the The sub-statements of this extension MUST follow the
'data-def-stmt' rule in the YANG ABNF. 'data-def-stmt' rule in the YANG ABNF.
The XPath document root is the extension statement itself, The XPath document root is the extension statement itself,
skipping to change at page 67, line 28 skipping to change at page 68, line 25
- when-stmt - when-stmt
- path-stmt - path-stmt
- min-elements-stmt - min-elements-stmt
- max-elements-stmt - max-elements-stmt
- mandatory-stmt - mandatory-stmt
- unique-stmt - unique-stmt
- ordered-by - ordered-by
- instance-identifier data type - instance-identifier data type
The following data-def-stmt sub-statements have special The following data-def-stmt sub-statements have special
meaning when used within a restconf-resource extension meaning when used within a yang-data-resource extension
statement. statement.
- The list-stmt is not required to have a key-stmt defined. - The list-stmt is not required to have a key-stmt defined.
- The if-feature-stmt is ignored if present. - The if-feature-stmt is ignored if present.
- The config-stmt is ignored if present. - The config-stmt is ignored if present.
- The available identity values for any 'identityref' - The available identity values for any 'identityref'
leaf or leaf-list nodes is limited to the module leaf or leaf-list nodes is limited to the module
containing this extension statement, and the modules containing this extension statement, and the modules
imported into that module. imported into that module.
"; ";
} }
rc:restconf-media-type "application/yang.errors" { rc:yang-data yang-errors {
uses errors; uses errors;
} }
rc:restconf-media-type "application/yang.api" { rc:yang-data yang-api {
uses restconf; uses restconf;
} }
grouping errors { grouping errors {
description description
"A grouping that contains a YANG container "A grouping that contains a YANG container
representing the syntax and semantics of a representing the syntax and semantics of a
YANG Patch errors report within a response message."; YANG Patch errors report within a response message.";
container errors { container errors {
skipping to change at page 69, line 30 skipping to change at page 70, line 26
zero or more data nodes representing additional zero or more data nodes representing additional
error information."; error information.";
} }
} }
} }
} }
grouping restconf { grouping restconf {
description description
"Conceptual container representing the "Conceptual container representing the
application/yang.api resource type."; application/yang-api resource type.";
container restconf { container restconf {
description description
"Conceptual container representing the "Conceptual container representing the
application/yang.api resource type."; application/yang-api resource type.";
container data { container data {
description description
"Container representing the application/yang.datastore "Container representing the application/yang-datastore
resource type. Represents the conceptual root of all resource type. Represents the conceptual root of all
state data and configuration data supported by state data and configuration data supported by
the server. The child nodes of this container can be the server. The child nodes of this container can be
any data resource (application/yang.data), which are any data resource (application/yang-data), which are
defined as top-level data nodes from the YANG modules defined as top-level data nodes from the YANG modules
advertised by the server in the ietf-restconf-monitoring advertised by the server in the ietf-restconf-monitoring
module."; module.";
} }
container operations { container operations {
description description
"Container for all operation resources "Container for all operation resources
(application/yang.operation), (application/yang-operation),
Each resource is represented as an empty leaf with the Each resource is represented as an empty leaf with the
name of the RPC operation from the YANG rpc statement. name of the RPC operation from the YANG rpc statement.
E.g.; For example, the 'system-restart' RPC operation defined
in the 'ietf-system' module would be represented as
POST /restconf/operations/show-log-errors an empty leaf in the 'ietf-system' namespace. This is
a conceptual leaf, and will not actually be found in
the module:
leaf show-log-errors { module ietf-system {
type empty; leaf system-reset {
type empty;
}
} }
To invoke the 'system-restart' RPC operation:
POST /restconf/operations/ietf-system:system-restart
To discover the RPC operations supported by the server:
GET /restconf/operations
In XML the YANG module namespace identifies the module:
<system-restart
xmlns='urn:ietf:params:xml:ns:yang:ietf-system' />
In JSON the YANG module name identifies the module:
{ 'ietf-system:system-restart' : [null] }
"; ";
} }
leaf yang-library-version { leaf yang-library-version {
type string { type string {
pattern '\d{4}-\d{2}-\d{2}'; pattern '\d{4}-\d{2}-\d{2}';
} }
config false; config false;
mandatory true; mandatory true;
description description
skipping to change at page 71, line 17 skipping to change at page 72, line 33
+--ro replay-log-creation-time? yang:date-and-time +--ro replay-log-creation-time? yang:date-and-time
+--ro access* [encoding] +--ro access* [encoding]
+--ro encoding string +--ro encoding string
+--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 MUST maintain a last-modified timestamp for this The server MAY maintain a last-modified timestamp for this container,
container, and return the "Last-Modified" header when this data node and return the "Last-Modified" header when this data node is
is retrieved with the GET or HEAD methods. retrieved with the GET or HEAD methods. Note that the last-modified
timestamp for the datastore resource is not affected by changes 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. GET or HEAD methods. Note that the entity-tag for the datastore
resource is not affected by changes 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 73, line 35 skipping to change at page 75, line 5
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-03-16.yang" <CODE BEGINS> file "ietf-restconf-monitoring@2016-06-28.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";
skipping to change at page 74, line 38 skipping to change at page 76, line 9
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from draft-ietf-netconf-restconf-13.txt // Note: extracted from draft-ietf-netconf-restconf-14.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-03-16 { revision 2016-06-28 {
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 76, line 22 skipping to change at page 77, line 41
"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 'application/yang-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 the media type
'application/yang.stream+xml'. The type 'json' 'application/yang-stream+xml'. The type 'json'
is supported for the media type is supported for the media type
'application/yang.stream+json'."; '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 77, line 14 skipping to change at page 78, line 34
<CODE ENDS> <CODE ENDS>
10. YANG Module Library 10. YANG Module Library
The "ietf-yang-library" module defined in The "ietf-yang-library" module defined in
[I-D.ietf-netconf-yang-library] provides information about the YANG [I-D.ietf-netconf-yang-library] provides information about the YANG
modules and submodules used by the RESTCONF server. Implementation modules and submodules used by the RESTCONF server. Implementation
is mandatory for RESTCONF servers. All YANG modules and submodules is mandatory for RESTCONF servers. All YANG modules and submodules
used by the server MUST be identified in the YANG module library. used by the server MUST be identified in the YANG module library.
10.1. modules 10.1. modules-state
This mandatory container holds the identifiers for the YANG data This mandatory container holds the identifiers for the YANG data
model modules supported by the server. model modules supported by the server.
The server MUST maintain a last-modified timestamp for this 10.1.1. modules-state/module
container, and return the "Last-Modified" header when this data node
is retrieved with the GET or HEAD methods.
The server SHOULD maintain an entity-tag for this container, and
return the "ETag" header when this data node is retrieved with the
GET or HEAD methods.
10.1.1. modules/module
This mandatory list contains one entry for each YANG data model This mandatory list contains one entry for each YANG data model
module supported by the server. There MUST be an instance of this module supported by the server. There MUST be an instance of this
list for every YANG module that is used by the server. list for every YANG module that is used by the server.
The contents of this list are defined in the "module" YANG list The contents of this list are defined in the "module" YANG list
statement in [I-D.ietf-netconf-yang-library]. statement in [I-D.ietf-netconf-yang-library].
The server SHOULD maintain a last-modified timestamp for each
instance of this list entry, and return the "Last-Modified" header
when this data node is retrieved with the GET or HEAD methods.
The server SHOULD maintain an entity-tag for each instance of this
list entry, and return the "ETag" header when this data node is
retrieved with the GET or HEAD methods.
11. IANA Considerations 11. IANA Considerations
11.1. The "restconf" Relation Type 11.1. The "restconf" Relation Type
This specification registers the "restconf" relation type in the Link This specification registers the "restconf" relation type in the Link
Relation Type Registry defined by [RFC5988]: Relation Type Registry defined by [RFC5988]:
Relation Name: restconf Relation Name: restconf
Description: Identifies the root of RESTCONF API as configured Description: Identifies the root of RESTCONF API as configured
on this HTTP server. The "restconf" relation on this HTTP server. The "restconf" relation
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.
skipping to change at page 78, line 19 skipping to change at page 79, line 21
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 in the IETF XML registry [RFC3688]. This document registers two URIs as namesapces in the IETF XML
Following the format in RFC 3688, the following registration is registry [RFC3688]. Following the format in RFC 3688, the following
requested to be made. 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.
This document registers two YANG modules in the YANG Module Names This document registers two YANG modules in the YANG Module Names
registry [RFC6020]. registry [RFC6020]:
name: ietf-restconf name: ietf-restconf
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf namespace: urn:ietf:params:xml:ns:yang:ietf-restconf
prefix: rc prefix: rc
// 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
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. application/yang Media Sub Types 11.3. Media Types
The parent MIME media type for RESTCONF resources is application/ 11.3.1. Media Type application/yang-data+xml
yang, which is defined in [RFC6020]. This document defines the Type name: application
following sub-types for this media type.
- api Subtype name: yang-data+xml
- data
- datastore Required parameters: none
- errors
- operation Optional parameters: none
- stream
// RFC Ed.: replace draft-ietf-netmod-rfc6020bis with
// the actual RFC reference for YANG 1.1, and remove this note.
Encoding considerations: 8-bit
Each conceptual YANG data node is encoded according to
XML Encoding Rules and Canonical Format for the specific
YANG data node type defined in [draft-ietf-netmod-rfc6020bis].
// RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the
// section number for Security Considerations
// Replace 'XXXX' in Section NN of [RFCXXXX] with the actual
// RFC number, and remove this note.
Security considerations: Security considerations related
to the generation and consumption of RESTCONF messages
are discussed in Section NN of [RFCXXXX].
Additional security considerations are specific to the
semantics of particular YANG data models. Each YANG module
is expected to specify security considerations for the
YANG data defined in that module.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
Interoperability considerations: [RFCXXXX] specifies format of
conforming messages and the interpretation thereof.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
Published specification: RFC XXXX
Applications that use this media type: Instance document
data parsers used within a protocol or automation tool
that utilizes YANG defined data structures.
Fragment identifier considerations: The fragment field in the
request URI has no defined purpose.
Additional information:
Deprecated alias names for this type: n/a
Magic number(s): n/a
File extension(s): .xml
Macintosh file type code(s): "TEXT"
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
Person & email address to contact for further information: See
Authors' Addresses section of [RFCXXXX].
Intended usage: COMMON
(One of COMMON, LIMITED USE, or OBSOLETE.)
Restrictions on usage: n/a
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
Author: See Authors' Addresses section of [RFCXXXX].
Change controller: Internet Engineering Task Force
(mailto:iesg&ietf.org).
Provisional registration? (standards tree only): no
11.3.2. Media Type application/yang-data+json
Type name: application Type name: application
Subtype name: yang.xxx, where "xxx" is 1 of "api", Subtype name: yang-data+json
"data", "datastore", "errors", "operation", or "stream"
Required parameters: none Required parameters: none
Optional parameters: See section 4.8 in RFC XXXX Optional parameters: none
// RFC Ed.: replace draft-ietf-netmod-yang-json with
// the actual RFC reference for JSON Encoding of YANG Data,
// and remove this note.
// RFC Ed.: replace draft-ietf-netmod-yang-metadata with
// the actual RFC reference for JSON Encoding of YANG Data,
// and remove this note.
Encoding considerations: 8-bit Encoding considerations: 8-bit
Each conceptual YANG data node is encoded according to
[draft-ietf-netmod-yang-json]. A data annotation is
encoded according to [draft-ietf-netmod-yang-metadata]
Security considerations: See Section 12 in RFC XXXX // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the
// section number for Security Considerations
// Replace 'XXXX' in Section NN of [RFCXXXX] with the actual
// RFC number, and remove this note.
Interoperability considerations: none Security considerations: Security considerations related
to the generation and consumption of RESTCONF messages
are discussed in Section NN of [RFCXXXX].
Additional security considerations are specific to the
semantics of particular YANG data models. Each YANG module
is expected to specify security considerations for the
YANG data defined in that module.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
Interoperability considerations: [RFCXXXX] specifies format of
conforming messages and the interpretation thereof.
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
// RFC Ed.: replace XXXX with RFC number and remove this note
Published specification: RFC XXXX Published specification: RFC XXXX
Applications that use this media type: Instance document
data parsers used within a protocol or automation tool
that utilizes YANG defined data structures.
Fragment identifier considerations: The fragment field in the
request URI has no defined purpose.
Additional information:
Deprecated alias names for this type: n/a
Magic number(s): n/a
File extension(s): .json
Macintosh file type code(s): "TEXT"
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
Person & email address to contact for further information: See
Authors' Addresses section of [RFCXXXX].
Intended usage: COMMON
(One of COMMON, LIMITED USE, or OBSOLETE.)
Restrictions on usage: n/a
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
Author: See Authors' Addresses section of [RFCXXXX].
Change controller: Internet Engineering Task Force
(mailto:iesg&ietf.org).
Provisional registration? (standards tree only): no
11.4. RESTCONF Capability URNs 11.4. RESTCONF Capability URNs
[Note to RFC Editor: [Note to RFC Editor:
The RESTCONF Protocol Capability Registry does not yet exist; The RESTCONF Protocol Capability Registry does not yet exist;
Need to ask IANA to create it; remove this note for publication Need to ask IANA to create it; remove this note for publication
] ]
This document defines a registry for RESTCONF capability identifiers. This document defines a registry for RESTCONF capability identifiers.
The name of the registry is "RESTCONF Capability URNs". The review The name of the registry is "RESTCONF Capability URNs". The review
policy for this registry is "IETF Review". The registry shall record policy for this registry is "IETF Review". The registry shall record
for each entry: for each entry:
o the name of the RESTCONF capability. By convention, this name is o the name of the RESTCONF capability. By convention, this name
prefixed with the colon ':' character. begins with the colon ':' character.
o the URN for the RESTCONF capability. o the URN for the RESTCONF capability.
This document registers several capability identifiers in "RESTCONF This document registers several capability identifiers in "RESTCONF
Capability URNs" registry: Capability URNs" registry:
Index Index
Capability Identifier Capability Identifier
------------------------ ------------------------
:defaults :defaults
urn:ietf:params:restconf:capability:defaults:1.0 urn:ietf:params:restconf:capability:defaults:1.0
:depth :depth
urn:ietf:params:restconf:capability:depth:1.0 urn:ietf:params:restconf:capability:depth:1.0
:fields :fields
urn:ietf:params:restconf:capability:fields:1.0 urn:ietf:params:restconf:capability:fields:1.0
:filter :filter
skipping to change at page 80, line 24 skipping to change at page 84, line 14
urn:ietf:params:restconf:capability:filter:1.0 urn:ietf:params:restconf:capability:filter:1.0
: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
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) ^RFC6242^. The NETCONF access control model ^RFC6536^
provides the means to restrict access for particular NETCONF users
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
that a client authentication mechanism and authorization model is that a client authentication mechanism and authorization model is
skipping to change at page 81, line 15 skipping to change at page 85, line 15
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.
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 review comments and contributions to this document: Mehmet excellent technical reviews of this document: Mehmet Ersue, Mahesh
Ersue, Mahesh Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka,
Lhotka, Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint
Balint Uveges, Randy Presuhn, and Sue Hares. Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise, and
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 The Space & Terrestrial Communications Directorate
(S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings
and conclusions or recommendations expressed in this material are and conclusions or recommendations expressed in this material are
those of the author(s) and do not necessarily reflect the views of those of the author(s) and do not necessarily reflect the views of
The Space & Terrestrial Communications Directorate (S&TCD). 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.
[I-D.ietf-netmod-rfc6020bis] [I-D.ietf-netmod-rfc6020bis]
Bjorklund, M., "The YANG 1.1 Data Modeling Language", Bjorklund, M., "The YANG 1.1 Data Modeling Language",
draft-ietf-netmod-rfc6020bis-11 (work in progress), draft-ietf-netmod-rfc6020bis-14 (work in progress), June
February 2016. 2016.
[I-D.ietf-netmod-yang-json] [I-D.ietf-netmod-yang-json]
Lhotka, L., "JSON Encoding of Data Modeled with YANG", Lhotka, L., "JSON Encoding of Data Modeled with YANG",
draft-ietf-netmod-yang-json-06 (work in progress), October draft-ietf-netmod-yang-json-10 (work in progress), March
2015. 2016.
[I-D.ietf-netmod-yang-metadata] [I-D.ietf-netmod-yang-metadata]
Lhotka, L., "Defining and Using Metadata with YANG", Lhotka, L., "Defining and Using Metadata with YANG",
draft-ietf-netmod-yang-metadata-02 (work in progress), draft-ietf-netmod-yang-metadata-07 (work in progress),
September 2015. March 2016.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996. November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
skipping to change at page 83, line 44 skipping to change at page 87, line 44
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC
7320, July 2014. 7320, July 2014.
[RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the [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.CR-eventsource-20121211] [W3C.REC-eventsource-20150203]
Hickson, I., "Server-Sent Events", World Wide Web Hickson, I., "Server-Sent Events", World Wide Web
Consortium CR CR-eventsource-20121211, December 2012, Consortium Recommendation REC-eventsource-20150203,
<http://www.w3.org/TR/2012/CR-eventsource-20121211>. February 2015,
<http://www.w3.org/TR/2015/REC-eventsource-20150203>.
[W3C.REC-html5-20141028] [W3C.REC-html5-20141028]
Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", World Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", World
Wide Web Consortium Recommendation REC-html5-20141028, Wide Web Consortium Recommendation REC-html5-20141028,
October 2014, October 2014,
<http://www.w3.org/TR/2014/REC-html5-20141028>. <http://www.w3.org/TR/2014/REC-html5-20141028>.
[W3C.REC-xml-20081126] [W3C.REC-xml-20081126]
Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C.,
skipping to change at page 84, line 23 skipping to change at page 88, line 24
[XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Recommendation Version 1.0", World Wide Web Consortium Recommendation
REC-xpath-19991116, November 1999, REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
14.2. Informative References 14.2. Informative References
[I-D.ietf-netconf-yang-patch] [I-D.ietf-netconf-yang-patch]
Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
Media Type", draft-ietf-netconf-yang-patch-06 (work in Media Type", draft-ietf-netconf-yang-patch-08 (work in
progress), October 2015. progress), March 2016.
[rest-dissertation] [rest-dissertation]
Fielding, R., "Architectural Styles and the Design of Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000. Network-based Software Architectures", 2000.
Appendix A. Change Log Appendix A. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
The RESTCONF issue tracker can be found here: https://github.com/ The RESTCONF issue tracker can be found here: https://github.com/
netconf-wg/restconf/issues netconf-wg/restconf/issues
A.1. v12 - v13 A.1. v13 - v14
This release addresses github issues #61, #62, #63, #65, #66, and
#67.
o change term 'server' to 'NETCONF server'
o add term 'RESTCONF server' also called 'server'
o change term 'client' to 'NETCONF client'
o add term 'RESTCONF client' also called 'client'
o remove unused YANG terms
o clarified operation resource and schema resource terms
o clarified abstract and intro: RESTCONF uses NETCONF datastore
concepts
o removed term 'protocol operation'; use 'RPC operation' instead
o clarified edit operation from NETCONF as nc:operation
o clarified retrieval of an operation resource
o remove ETag and Last-Modified requirements for /modules-state and
/modules-state/module objects, since these are not configuration
data nodes
o clarified Last-Modified and ETag requirements for datastore and
data resources
o clarified defaults retrieval for leaf and leaf-list target
resources
o clarified request message-body for operation resources
o clarified query parameters for GET also allowed for HEAD
o clarified error handling for query parameters
o clarified XPath function library for "filter" parameter
o added example for 'edit a data resource'
o added term 'notification replay' from RFC 5277
o clarified unsupported encoding format error handling
o change term 'meta-data' to 'metadata'
o clarified RESTCONF metadata definition
o clarified error info not returned for 1xx, 2xx, and 3xx ranges
o clarified operations description in ietf-restconf module
o clarified Acknowledgements section
o clarified some examples
o update some references
o update RFC 2119 boilerplace
o remove requirements that simply restate HTTP requirements
o remove Pragma: no-cache from examples since RFC 7234 says this
pragma is not defined for responses
o remove suggestion MAY send Pragma: no-cache in response
o remove table of HTTP status codes used in RESTCONF
o changed media type names so they conform to RFC 6838
o clarified too-big error-tag conversion
o update SSE reference
o clarify leaf-list identifier encoding
o removed all media types except yang-data
o changed restconf-media-type extension to be more generic yang-data
extension
A.2. v12 - v13
o fix YANG library module examples (now called module-state) o fix YANG library module examples (now called module-state)
o fix MUST not term (should be MUST NOT) 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.2. v11 - v12 A.3. 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
mandatory mandatory
o removed confusing text about data resource definition revision o removed confusing text about data resource definition revision
date date
skipping to change at page 85, line 24 skipping to change at page 91, line 14
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.3. v10 - v11 A.4. 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 86, line 5 skipping to change at page 91, line 42
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.4. v09 - v10 A.5. 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 88, line 5 skipping to change at page 93, line 40
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.5. v08 - v09 A.6. 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.6. v07 - v08 A.7. 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.7. v06 - v07 A.8. 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.8. v05 - v06 A.9. v05 - v06
o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug)
A.9. v04 - v05 A.10. 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 90, line 5 skipping to change at page 95, line 33
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.10. v03 - v04 A.11. 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 90, line 40 skipping to change at page 96, line 21
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.11. v02 - v03 A.12. 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 91, line 4 skipping to change at page 96, line 33
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.12. v01 - v02 A.13. 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 92, line 5 skipping to change at page 97, line 31
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.13. v00 - v01 A.14. 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 92, line 49 skipping to change at page 98, line 27
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.14. bierman:restconf-04 to ietf:restconf-00 A.15. 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 99, line 25 skipping to change at page 104, line 47
The examples within this document use the normative YANG module The examples within this document use the normative YANG module
defined in Section 8 and the non-normative example YANG module defined in Section 8 and the non-normative example YANG module
defined in Appendix C.1. defined in Appendix C.1.
This section shows some typical RESTCONF message exchanges. This section shows some typical RESTCONF message exchanges.
D.1. Resource Retrieval Examples D.1. Resource Retrieval Examples
D.1.1. Retrieve the Top-level API Resource D.1.1. Retrieve the Top-level API Resource
The client may start by retrieving the top-level API resource, using The client starts by retrieving the RESTCONF entry point:
the entry point URI "{+restconf}".
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
The server might respond:
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
</XRD>
The client may then retrieve the top-level API resource, using the
entry point "/restconf".
GET /restconf HTTP/1.1 GET /restconf HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.api+json Accept: application/yang-data+json
The server might respond as follows: The server might respond as follows:
[RFC Editor Note: Adjust the date for ietf-yang-library below to the [RFC Editor Note: Adjust the date (2016-04-09) for ietf-yang-library
date in the published ietf-yang-library YANG module, and remove this below to the date in the published ietf-yang-library YANG module, and
note.] remove this 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
Content-Type: application/yang.api+json Content-Type: application/yang-data+json
{ {
"ietf-restconf:restconf": { "ietf-restconf:restconf": {
"data" : {}, "data" : {},
"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.api+xml Accept: application/yang-data+xml
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
Pragma: no-cache Content-Type: application/yang-data+xml
Content-Type: application/yang.api+xml
<restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<data/> <data/>
<operations/> <operations/>
<yang-library-version>2016-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
client can retrieve the revision date of the ietf-yang-library
supported by the server from the API resource, as described in the
previous section.
In this example the client is retrieving the modules information from In this example the client is retrieving the modules information from
the server in JSON format: the server in JSON format:
GET /restconf/data/ietf-yang-library:modules-state HTTP/1.1 GET /restconf/data/ietf-yang-library:modules-state 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 (some strings wrapped for display The server might respond as follows (some strings wrapped for display
purposes): purposes):
[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
Pragma: 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
{ {
"ietf-yang-library:modules-state": { "ietf-yang-library:modules-state": {
"module-set-id": "5479120c17a619545ea6aff7aa19838b036ebbd7", "module-set-id": "5479120c17a619545ea6aff7aa19838b036ebbd7",
"module": [ "module": [
{ {
"name" : "foo", "name" : "foo",
"revision" : "2012-01-02", "revision" : "2012-01-02",
"schema" : "https://example.com/modules/foo/2012-01-02", "schema" : "https://example.com/modules/foo/2012-01-02",
"namespace" : "http://example.com/ns/foo", "namespace" : "http://example.com/ns/foo",
"feature" : [ "feature1", "feature2" ], "feature" : [ "feature1", "feature2" ],
"deviation" : [
{
"name" : "foo-dev",
"revision" "2012-02-16"
}
],
"conformance-type" : "implement" "conformance-type" : "implement"
}, },
{ {
"name" : "ietf-yang-library", "name" : "ietf-yang-library",
"revision" : "2016-04-09", "revision" : "2016-04-09",
"schema" : "https://example.com/modules/ietf-yang- "schema" : "https://example.com/modules/ietf-yang-
library/2016-04-09", library/2016-04-09",
"namespace" : "namespace" :
"urn:ietf:params:xml:ns:yang:ietf-yang-library", "urn:ietf:params:xml:ns:yang:ietf-yang-library",
"conformance-type" : "implement" "conformance-type" : "implement"
skipping to change at page 102, line 23 skipping to change at page 108, line 25
D.1.3. Retrieve The Server Capability Information D.1.3. Retrieve The Server Capability Information
In this example the client is retrieving the capability information In this example the client is retrieving the capability information
from the server in XML format, and the server supports all the from the server in XML format, and the server supports all the
RESTCONF query parameters, plus one vendor parameter: RESTCONF query parameters, plus one vendor parameter:
GET /restconf/data/ietf-restconf-monitoring:restconf-state/ GET /restconf/data/ietf-restconf-monitoring:restconf-state/
capabilities HTTP/1.1 capabilities HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+xml Accept: application/yang-data+xml
The server might respond as follows. The extra whitespace in The server might respond as follows. The extra whitespace in
'capability' elements 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
Pragma: 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+xml
<capabilities xmlns=""> <capabilities
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<capability>
urn:ietf:params:restconf:capability:defaults:1.0?
basic-mode=explicit
</capability>
<capability>
urn:ietf:params:restconf:capability:with-defaults:1.0
</capability>
<capability> <capability>
urn:ietf:params:restconf:capability:depth:1.0 urn:ietf:params:restconf:capability:depth:1.0
</capability> </capability>
<capability> <capability>
urn:ietf:params:restconf:capability:fields:1.0 urn:ietf:params:restconf:capability:fields:1.0
</capability> </capability>
<capability> <capability>
urn:ietf:params:restconf:capability:filter:1.0 urn:ietf:params:restconf:capability:filter:1.0
</capability> </capability>
<capability> <capability>
skipping to change at page 103, line 18 skipping to change at page 109, line 27
D.2. Edit Resource Examples D.2. Edit Resource Examples
D.2.1. Create New Data Resources D.2.1. Create New Data Resources
To create a new "artist" resource within the "library" resource, the To create a new "artist" resource within the "library" resource, the
client might send the following request. client might send the following request.
POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang.data+json Content-Type: application/yang-data+json
{ {
"example-jukebox:artist" : { "example-jukebox:artist" : {
"name" : "Foo Fighters" "name" : "Foo Fighters"
} }
} }
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:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2012 17:02:00 GMT Date: Mon, 23 Apr 2012 17:02: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
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+xml
<album xmlns="http://example.com/ns/example-jukebox"> <album xmlns="http://example.com/ns/example-jukebox">
<name>Wasting Light</name> <name>Wasting Light</name>
<year>2011</year> <year>2011</year>
</album> </album>
If the resource is created, the server might respond as follows. If the resource is created, the server might respond as follows.
Note that the "Location" header line is wrapped for display purposes Note that the "Location" header line is wrapped for display purposes
only: only:
HTTP/1.1 201 Created HTTP/1.1 201 Created
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
skipping to change at page 104, line 15 skipping to change at page 110, line 26
Note that the "Location" header line is wrapped for display purposes Note that the "Location" header line is wrapped for display purposes
only: only:
HTTP/1.1 201 Created HTTP/1.1 201 Created
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 mandatory datastore
last-changed timestamp. The client has previously retrieved the last-changed timestamp. The client has previously retrieved the
"Last-Modified" header and has some value cached to provide in the "Last-Modified" header and has some value cached to provide in the
following request to patch an "album" list entry with key value following request to patch an "album" list entry with key value
"Wasting Light". Only the "genre" field is being updated. "Wasting Light". Only 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" }
In this example the datastore resource has changed since the time In this example the datastore resource has changed since the time
specified in the "If-Unmodified-Since" header. The server might specified in the "If-Unmodified-Since" header. The server might
respond: respond:
HTTP/1.1 412 Precondition Failed HTTP/1.1 412 Precondition Failed
Date: Mon, 23 Apr 2012 19:01:00 GMT Date: Mon, 23 Apr 2012 19:01:00 GMT
Server: example-server Server: example-server
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.datastore+xml Content-Type: application/yang-data+xml
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<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</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>
</jukebox> </jukebox>
</data> </data>
D.2.4. Edit a Data Resource
In this example, the client modifies one data nodes by sending a
PATCH to the data resource (URI wrapped for display purposes only):
PATCH /restconf/data/example-jukebox:jukebox/library/
artist=Nick%20Cave%20and%20the%Bad%20Seeds HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
<artist xmlns="http://example.com/ns/example-jukebox">
<name>Nick Cave and the Bad Seeds</name>
<album>
<name>The Good Son</name>
<year>1990</year>
</album>
</artist>
D.3. Query Parameter Examples D.3. Query Parameter Examples
D.3.1. "content" Parameter D.3.1. "content" Parameter
The "content" parameter is used to select the type of data child The "content" parameter is used to select the type of data child
resources (configuration and/or not configuration) that are returned resources (configuration and/or not configuration) that are returned
by the server for a GET method request. by the server for a GET method request.
In this example, a simple YANG list that has configuration and non- In this example, a simple YANG list that has configuration and non-
configuration child resources. configuration child resources.
skipping to change at page 105, line 51 skipping to change at page 112, line 36
leaf event-count { leaf event-count {
type uint32; type uint32;
config false; config false;
} }
} }
} }
Example 1: content=all Example 1: content=all
To retrieve all the child resources, the "content" parameter is set To retrieve all the child resources, the "content" parameter is set
to "all". The client might send: to "all", or omitted, since this is the default value. The client
might send:
GET /restconf/data/example-events:events?content=all GET /restconf/data/example-events:events?content=all
HTTP/1.1 HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json Accept: application/yang-data+json
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:11:30 GMT Date: Mon, 23 Apr 2012 17:11:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Content-Type: application/yang-data+json
Content-Type: application/yang.data+json
{ {
"example-events:events" : { "example-events:events" : {
"event" : [ "event" : [
{ {
"name" : "interface-up", "name" : "interface-up",
"description" : "Interface up notification count", "description" : "Interface up notification count",
"event-count" : 42 "event-count" : 42
}, },
{ {
"name" : "interface-down", "name" : "interface-down",
"description" : "Interface down notification count", "description" : "Interface down notification count",
"event-count" : 4 "event-count" : 4
} }
] ]
} }
} }
Example 2: content=config Example 2: content=config
To retrieve only the configuration child resources, the "content" To retrieve only the configuration child resources, the "content"
parameter is set to "config" or omitted since this is the default parameter is set to "config". Note that the "ETag" and
value. Note that the "ETag" and "Last-Modified" headers are only "Last-Modified" headers are only returned if the content parameter
returned if the content parameter value is "config". value is "config".
GET /restconf/data/example-events:events?content=config GET /restconf/data/example-events:events?content=config
HTTP/1.1 HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json Accept: application/yang-data+json
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:11:30 GMT Date: Mon, 23 Apr 2012 17:11:30 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
ETag: eeeada438af ETag: "eeeada438af"
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Content-Type: application/yang-data+json
Content-Type: application/yang.data+json
{ {
"example-events:events" : { "example-events:events" : {
"event" : [ "event" : [
{ {
"name" : "interface-up", "name" : "interface-up",
"description" : "Interface up notification count" "description" : "Interface up notification count"
}, },
{ {
"name" : "interface-down", "name" : "interface-down",
skipping to change at page 107, line 35 skipping to change at page 114, line 20
Example 3: content=nonconfig Example 3: content=nonconfig
To retrieve only the non-configuration child resources, the "content" To retrieve only the non-configuration child resources, the "content"
parameter is set to "nonconfig". Note that configuration ancestors parameter is set to "nonconfig". Note that configuration ancestors
(if any) and list key leafs (if any) are also returned. The client (if any) and list key leafs (if any) are also returned. The client
might send: might send:
GET /restconf/data/example-events:events?content=nonconfig GET /restconf/data/example-events:events?content=nonconfig
HTTP/1.1 HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json Accept: application/yang-data+json
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:11:30 GMT Date: Mon, 23 Apr 2012 17:11:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Content-Type: application/yang-data+json
Content-Type: application/yang.data+json
{ {
"example-events:events" : { "example-events:events" : {
"event" : [ "event" : [
{ {
"name" : "interface-up", "name" : "interface-up",
"event-count" : 42 "event-count" : 42
}, },
{ {
"name" : "interface-down", "name" : "interface-down",
"event-count" : 4 "event-count" : 4
} }
] ]
} }
} }
D.3.2. "depth" Parameter D.3.2. "depth" Parameter
skipping to change at page 108, line 37 skipping to change at page 115, line 20
Example 1: depth=unbounded Example 1: depth=unbounded
To retrieve all the child resources, the "depth" parameter is not To retrieve all the child resources, the "depth" parameter is not
present or set to the default value "unbounded". Note that some present or set to the default value "unbounded". Note that some
strings are wrapped for display purposes only. strings are wrapped for display purposes only.
GET /restconf/data/example-jukebox:jukebox?depth=unbounded GET /restconf/data/example-jukebox:jukebox?depth=unbounded
HTTP/1.1 HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json Accept: application/yang-data+json
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:11:30 GMT Date: Mon, 23 Apr 2012 17:11:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Content-Type: application/yang-data+json
Content-Type: application/yang.data+json
{ {
"example-jukebox:jukebox" : { "example-jukebox:jukebox" : {
"library" : { "library" : {
"artist" : [ "artist" : [
{ {
"name" : "Foo Fighters", "name" : "Foo Fighters",
"album" : [ "album" : [
{ {
"name" : "Wasting Light", "name" : "Wasting Light",
skipping to change at page 110, line 17 skipping to change at page 116, line 48
} }
} }
Example 2: depth=1 Example 2: depth=1
To determine if 1 or more resource instances exist for a given target To determine if 1 or more resource instances exist for a given target
resource, the value "1" is used. resource, the value "1" is used.
GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json Accept: application/yang-data+json
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:11:30 GMT Date: Mon, 23 Apr 2012 17:11:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Content-Type: application/yang-data+json
Content-Type: application/yang.data+json
{ {
"example-jukebox:jukebox" : {} "example-jukebox:jukebox" : {}
} }
Example 3: depth=3 Example 3: depth=3
To limit the depth level to the target resource plus 2 child resource To limit the depth level to the target resource plus 2 child resource
layers the value "3" is used. layers the value "3" is used.
GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json Accept: application/yang-data+json
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:11:30 GMT Date: Mon, 23 Apr 2012 17:11:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Content-Type: application/yang-data+json
Content-Type: application/yang.data+json
{ {
"example-jukebox:jukebox" : { "example-jukebox:jukebox" : {
"library" : { "library" : {
"artist" : {} "artist" : {}
}, },
"playlist" : [ "playlist" : [
{ {
"name" : "Foo-One", "name" : "Foo-One",
"description" : "example playlist 1", "description" : "example playlist 1",
"song" : {} "song" : {}
} }
], ],
"player" : { "player" : {
"gap" : 0.5 "gap" : 0.5
} }
} }
} }
D.3.3. "fields" Parameter D.3.3. "fields" Parameter
In this example the client is retrieving the datastore resource in
In this example the client is retrieving the API resource, but JSON format, but retrieving only the "modules-state/module" list, and
retrieving only the "name" and "revision" nodes from each module, in only the "name" and "revision" nodes from each list entry. Note that
JSON format: top node returned by the server matches the target resource node
(which is "data" in this example). The "module-set-id" leaf is not
returned because it is not selected in the fields expression.
GET /restconf/data?fields=ietf-yang-library:modules-state/ GET /restconf/data?fields=ietf-yang-library:modules-state/
module(name;revision) HTTP/1.1 module(name;revision) 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.
[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.]
[RFC Editor Note: Adjust the date for ietf-restconf-monitoring below [RFC Editor Note: Adjust the date for ietf-restconf-monitoring below
to the date in the published ietf-restconf-monitoring YANG module, to the date in the published ietf-restconf-monitoring YANG module,
and remove this note.] and remove this 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
Content-Type: application/yang.data+json Content-Type: application/yang-data+json
{ {
"ietf-yang-library:modules-state": { "ietf-restconf:data" : {
"module-set-id": "cb4c422111a779e1eed55bffc8d6b46a3a0999e2", "ietf-yang-library:modules-state": {
"module": [ "module": [
{ {
"name" : "example-jukebox", "name" : "example-jukebox",
"revision" : "2015-06-04" "revision" : "2015-06-04"
}, },
{ {
"name" : "ietf-inet-types", "name" : "ietf-inet-types",
"revision" : "2013-07-15" "revision" : "2013-07-15"
}, },
{ {
"name" : "ietf-restconf-monitoring", "name" : "ietf-restconf-monitoring",
"revision" : "2016-03-16" "revision" : "2016-03-16"
}, },
{ {
"name" : "ietf-yang-library", "name" : "ietf-yang-library",
"revision" : "2016-04-09" "revision" : "2016-04-09"
}, },
{ {
"name" : "ietf-yang-types", "name" : "ietf-yang-types",
"revision" : "2013-07-15" "revision" : "2013-07-15"
} }
]
] }
} }
} }
D.3.4. "insert" Parameter D.3.4. "insert" Parameter
In this example, a new first song entry in the "Foo-One" playlist is In this example, a new first song entry in the "Foo-One" playlist is
being created. being created.
Request from client: Request from client:
POST /restconf/data/example-jukebox:jukebox/ POST /restconf/data/example-jukebox:jukebox/
playlist=Foo-One?insert=first HTTP/1.1 playlist=Foo-One?insert=first HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang.data+json Content-Type: application/yang-data+json
{ {
"example-jukebox:song" : { "example-jukebox:song" : {
"index" : 1, "index" : 1,
"id" : "/example-jukebox:jukebox/library/ "id" : "/example-jukebox:jukebox/library/
artist=Foo%20Fighters/album=Wasting%20Light/song=Rope" artist=Foo%20Fighters/album=Wasting%20Light/song=Rope"
} }
} }
Response from server: Response from server. Note that the "Location" header line is
wrapped for display purposes only:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2012 13:01:20 GMT Date: Mon, 23 Apr 2012 13:01:20 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
Location: https://example.com/restconf/data/ Location: https://example.com/restconf/data/
example-jukebox:jukebox/playlist=Foo-One/song=1 example-jukebox:jukebox/playlist=Foo-One/song=1
ETag: eeeada438af ETag: "eeeada438af"
D.3.5. "point" Parameter D.3.5. "point" Parameter
In this example, the client is inserting a new "song" resource within In this example, the client is inserting a new "song" resource within
an "album" resource after another song. The request URI is split for an "album" resource after another song. The request URI is split for
display purposes only. display purposes only.
Request from client: Request from client:
POST /restconf/data/example-jukebox:jukebox/ POST /restconf/data/example-jukebox:jukebox/
library/artist=Foo%20Fighters/album=Wasting%20Light? library/artist=Foo%20Fighters/album=Wasting%20Light?
insert=after&point=%2Fexample-jukebox%3Ajukebox%2F insert=after&point=%2Fexample-jukebox%3Ajukebox%2F
library%2Fartist%3DFoo%20Fighters%2Falbum%3D library%2Fartist%3DFoo%20Fighters%2Falbum%3D
Wasting%20Light%2Fsong%3DBridge%20Burning HTTP/1.1 Wasting%20Light%2Fsong%3DBridge%20Burning HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang.data+json Content-Type: application/yang-data+json
{ {
"example-jukebox:song" : { "example-jukebox:song" : {
"name" : "Rope", "name" : "Rope",
"location" : "/media/foo/a7/rope.mp3", "location" : "/media/foo/a7/rope.mp3",
"format" : "MP3", "format" : "MP3",
"length" : 259 "length" : 259
} }
} }
Response from server: Response from server:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 13:01:20 GMT Date: Mon, 23 Apr 2012 13:01:20 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
ETag: abcada438af ETag: "abcada438af"
D.3.6. "filter" Parameter D.3.6. "filter" Parameter
The following URIs show some examples of notification filter The following URIs show some examples of notification filter
specifications (lines wrapped for display purposes only): specifications (lines wrapped for display purposes only):
// filter = /event/event-class='fault' // filter = /event/event-class='fault'
GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault'
// filter = /event/severity<=4 // filter = /event/severity<=4
skipping to change at page 115, line 22 skipping to change at page 122, line 14
Assume the same data model as defined in Appendix A.1 of [RFC6243]. Assume the same data model as defined in Appendix A.1 of [RFC6243].
Assume the same data set as defined in Appendix A.2 of [RFC6243]. If Assume the same data set as defined in Appendix A.2 of [RFC6243]. If
the server defaults-uri basic-mode is "trim", the the following the server defaults-uri basic-mode is "trim", the the following
request for interface "eth1" might be as follows: request for interface "eth1" might be as follows:
Without query parameter: Without query parameter:
GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1 GET /restconf/data/example:interfaces/interface=eth1 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
Server: example-server Server: example-server
Content-Type: application/yang.data+json Content-Type: application/yang-data+json
{ {
"example:interface": [ "example:interface": [
{ {
"name" : "eth1", "name" : "eth1",
"status" : "up" "status" : "up"
} }
] ]
} }
Note that the "mtu" leaf is missing because it is set to the default Note that the "mtu" leaf is missing because it is set to the default
"1500", and the server defaults handling basic-mode is "trim". "1500", and the server defaults handling basic-mode is "trim".
With query parameter: With query parameter:
GET /restconf/data/example:interfaces/interface=eth1 GET /restconf/data/example:interfaces/interface=eth1
?with-defaults=report-all HTTP/1.1 ?with-defaults=report-all 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
Server: example-server Server: example-server
Content-Type: application/yang.data+json Content-Type: application/yang-data+json
{ {
"example:interface": [ "example:interface": [
{ {
"name" : "eth1", "name" : "eth1",
"mtu" : 1500, "mtu" : 1500,
"status" : "up" "status" : "up"
} }
] ]
} }
 End of changes. 337 change blocks. 
765 lines changed or deleted 1097 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/