draft-ietf-netconf-restconf-15.txt   draft-ietf-netconf-restconf-16.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: January 8, 2017 Tail-f Systems Expires: February 16, 2017 Tail-f Systems
K. Watsen K. Watsen
Juniper Networks Juniper Networks
July 7, 2016 August 15, 2016
RESTCONF Protocol RESTCONF Protocol
draft-ietf-netconf-restconf-15 draft-ietf-netconf-restconf-16
Abstract Abstract
This document describes an HTTP-based protocol that provides a This document describes an HTTP-based protocol that provides a
programmatic interface for accessing data defined in YANG, using the programmatic interface for accessing data defined in YANG, using the
datastore concepts defined in NETCONF. datastore concepts defined in NETCONF.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 8, 2017. This Internet-Draft will expire on February 16, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 23 skipping to change at page 2, line 15
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 . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.4. NETCONF Notifications . . . . . . . . . . . . . . . . 7 1.1.4. NETCONF Notifications . . . . . . . . . . . . . . . . 7
1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 8
1.1.6. URI Template and Examples . . . . . . . . . . . . . . 10 1.1.6. URI Template and Examples . . . . . . . . . . . . . . 10
1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10 1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10
1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 10 1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 11
1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 11 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 12
1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 12 1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 13
1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 13 1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 14
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 14 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 15
2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 14 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 15
2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 14 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 15
2.3. Certificate Validation . . . . . . . . . . . . . . . . . 14 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 15
2.4. Authenticated Server Identity . . . . . . . . . . . . . . 15 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 16
2.5. Authenticated Client Identity . . . . . . . . . . . . . . 15 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 16
3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 16 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 17
3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 17 3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 19
3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 18 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 19
3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 19 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 20
3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 19 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 20
3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 20 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 21
3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 20 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 21
3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 21 3.4.1. Edit Collision Prevention . . . . . . . . . . . . . . 22
3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 22 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 23
3.5.1. Timestamp . . . . . . . . . . . . . . . . . . . . . . 22 3.5.1. Timestamp . . . . . . . . . . . . . . . . . . . . . . 24
3.5.2. Entity tag . . . . . . . . . . . . . . . . . . . . . 23 3.5.2. Entity-Tag . . . . . . . . . . . . . . . . . . . . . 24
3.5.3. Encoding Data Resource Identifiers in the Request URI 23 3.5.3. Encoding Data Resource Identifiers in the Request URI 24
3.5.4. Defaults Handling . . . . . . . . . . . . . . . . . . 26 3.5.4. Default Handling . . . . . . . . . . . . . . . . . . 28
3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 27 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 29
3.6.1. Encoding Operation Resource Input Parameters . . . . 29 3.6.1. Encoding Operation Resource Input Parameters . . . . 30
3.6.2. Encoding Operation Resource Output Parameters . . . . 32 3.6.2. Encoding Operation Resource Output Parameters . . . . 34
3.6.3. Encoding Operation Resource Errors . . . . . . . . . 34 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 36
3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 35 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 37
3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 36 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 38
3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 37 3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 39
4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 37 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 40 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 40 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 43
4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 41 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 44
4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 44 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 44 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 47
4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 45 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 46 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 49
4.8.1. The "content" Query Parameter . . . . . . . . . . . . 47 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 50
4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 47 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 51
4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 48 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 52
4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 49 4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 53
4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 50 4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 53
4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 50 4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 54
4.8.7. The "start-time" Query Parameter . . . . . . . . . . 51 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 55
4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 52 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 55
4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 52 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 56
5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 53 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 53 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 57
5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 55 5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 59
5.3. RESTCONF Metadata . . . . . . . . . . . . . . . . . . . . 55 5.3. RESTCONF Metadata . . . . . . . . . . . . . . . . . . . . 60
5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 56 5.3.1. XML Metadata Encoding Example . . . . . . . . . . . . 60
5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 56 5.3.2. JSON Metadata Encoding Example . . . . . . . . . . . 60
5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 57 5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 61
5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 57 5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 61
6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 57 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 62
6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 58 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 62
6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 58 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 62
6.3. Subscribing to Receive Notifications . . . . . . . . . . 59 6.3. Subscribing to Receive Notifications . . . . . . . . . . 64
6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 60 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 65
6.4. Receiving Event Notifications . . . . . . . . . . . . . . 61 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 65
7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 63 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 67
7.1. Error Response Message . . . . . . . . . . . . . . . . . 64 7.1. Error Response Message . . . . . . . . . . . . . . . . . 68
8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 66 8. RESTCONF Module . . . . . . . . . . . . . . . . . . . . . . . 70
9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 72 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 77
9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 73 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 77
9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 73 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 78
9.1.2. The "defaults" Protocol Capability URI . . . . . . . 74 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 78
9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 75 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 79
9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 75 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 79
10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 83
10.1. modules-state/module . . . . . . . . . . . . . . . . . . 83
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 83
11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 84
11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 84
11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 85
11.3.1. Media Type application/yang-data-xml . . . . . . . . 85
11.3.2. Media Type application/yang-data+json . . . . . . . 86
11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 88
12. Security Considerations . . . . . . . . . . . . . . . . . . . 89
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 90
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 91
14.1. Normative References . . . . . . . . . . . . . . . . . . 91
14.2. Informative References . . . . . . . . . . . . . . . . . 94
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 94
A.1. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . 94
A.2. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . 94
A.3. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 95
A.4. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 97
A.5. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 97
A.6. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 97
A.7. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 98
A.8. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 100
A.9. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 100
A.10. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 101
A.11. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 101
A.12. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 101
A.13. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 102
A.14. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 103
A.15. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 103
A.16. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 104
A.17. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 105
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 105
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 105
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 106
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 111
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 112
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 112
D.1.2. Retrieve The Server Module Information . . . . . . . 113
D.1.3. Retrieve The Server Capability Information . . . . . 115
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 116
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 116
D.2.2. Detect Resource Entity-Tag Change . . . . . . . . . . 118
D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 118
D.2.4. Edit a Data Resource . . . . . . . . . . . . . . . . 119
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 120
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 120
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 123
D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 126
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 127
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 128
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 129
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 130
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 130
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 131
10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 132
10.1. modules-state . . . . . . . . . . . . . . . . . . . . . 79
10.1.1. modules-state/module . . . . . . . . . . . . . . . . 79
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79
11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 79
11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 80
11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 80
11.3.1. Media Type application/yang-data . . . . . . . . . . 80
11.3.2. Media Type application/yang-data+json . . . . . . . 82
11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 84
12. Security Considerations . . . . . . . . . . . . . . . . . . . 84
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 85
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 86
14.1. Normative References . . . . . . . . . . . . . . . . . . 86
14.2. Informative References . . . . . . . . . . . . . . . . . 89
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 89
A.1. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . 89
A.2. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 89
A.3. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 91
A.4. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 91
A.5. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 92
A.6. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 93
A.7. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 95
A.8. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 95
A.9. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 95
A.10. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 96
A.11. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 96
A.12. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 97
A.13. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 97
A.14. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 98
A.15. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 99
A.16. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 99
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 100
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 100
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 101
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 106
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 106
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 106
D.1.2. Retrieve The Server Module Information . . . . . . . 108
D.1.3. Retrieve The Server Capability Information . . . . . 109
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 110
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 110
D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 112
D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 112
D.2.4. Edit a Data Resource . . . . . . . . . . . . . . . . 113
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 113
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 113
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 116
D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 119
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 120
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 121
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 122
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 122
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 122
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 123
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 124
1. Introduction 1. Introduction
There is a need for standard mechanisms to allow Web applications to There is a need for standard mechanisms to allow Web applications to
access the configuration data, state data, data-model specific RPC access the configuration data, state data, data-model-specific RPC
operations, and event notifications within a networking device, in a operations, and event notifications within a networking device, in a
modular and extensible manner. modular and extensible manner.
This document defines an HTTP [RFC7230] based protocol called This document defines an HTTP [RFC7230] based protocol called
RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or
YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using the datastore YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using the datastore
concepts 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. NETCONF also defines a protocol for invoking these
of datastore content, configuration, state data, RPC operations, and operations. The YANG language defines the syntax and semantics of
datastore content, configuration, state data, RPC operations, and
event notifications. event notifications.
RESTCONF uses HTTP methods to provide CRUD operations on a conceptual RESTCONF uses HTTP methods to provide CRUD operations on a conceptual
datastore containing YANG-defined data, which is compatible with a datastore containing YANG-defined data, which is compatible with a
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 with the NETCONF protocol, which are
Section 1.4. The RESTCONF server MAY provide access to specific described in Section 1.4. The RESTCONF server MAY provide access to
datastores using operation resources, as described in Section 3.6. specific datastores using operation resources, as described in
Section 3.6. The RESTCONF protocol does not specify any mandatory
operation resources. The semantics of each operation resource
determine if and how datastores are accessed.
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 RPC 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 key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
1.1.1. NETCONF 1.1.1. NETCONF
skipping to change at page 6, line 43 skipping to change at page 6, line 43
The following terms are defined in [RFC3986]: The following terms are defined in [RFC3986]:
o fragment o fragment
o path o path
o query o query
The following terms are defined in [RFC7230]: The following terms are defined in [RFC7230]:
o header o header field
o message-body o message-body
o request-line o request-line
o request URI o request URI
o status-line o status-line
The following terms are defined in [RFC7231]: The following terms are defined in [RFC7231]:
o method o method
o request o request
o resource o resource
The following terms are defined in [RFC7232]: The following terms are defined in [RFC7232]:
o entity tag o entity-tag
1.1.3. YANG 1.1.3. YANG
The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: The following terms are defined in [I-D.ietf-netmod-rfc6020bis]:
o action o action
o container o container
o data node o data node
skipping to change at page 8, line 4 skipping to change at page 8, line 6
o top-level data node o top-level data node
1.1.4. NETCONF Notifications 1.1.4. NETCONF Notifications
The following terms are defined in [RFC5277]: The following terms are defined in [RFC5277]:
o notification replay o notification replay
1.1.5. Terms 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 that models the RESTCONF entry point and o API resource: the resource that models the RESTCONF root resource
the sub-resources to access YANG-defined content. It is defined and the sub-resources to access YANG-defined content. It is
with the YANG data template named "yang-api" in the defined with the YANG data template named "yang-api" in the
"ietf-restconf" module. "ietf-restconf" module.
o client: a RESTCONF client
o data resource: a resource that models a YANG data node. It is o data resource: a resource that models a YANG data node. It is
defined with YANG data definition statements, and YANG containers, defined with YANG data definition statements.
leafs, leaf-list entries, list entries, anydata and anyxml nodes
can be data resources.
o datastore resource: a resource that models a programmatic o datastore resource: the resource that models a programmatic
interface to NETCONF datastores. By default, RESTCONF methods interface using NETCONF datastore concepts. By default, RESTCONF
access a unified view of the underlying datastore implementation methods access a unified view of the underlying datastore
on the server. It is defined as a sub-resource within the API implementation on the server. It is defined as a sub-resource
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. This is not the same 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 as the NETCONF edit operation (i.e., one of the values for the
"nc:operation" attribute: "create", "replace", "merge", "delete", "nc:operation" attribute: "create", "replace", "merge", "delete",
or "remove"). 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 SSE media type "text/event-stream", as defined by the SSE
[W3C.REC-eventsource-20150203] specification. Each event [W3C.REC-eventsource-20150203] specification. Event stream
represents one <notification> message generated by the server. It contents are described in Section 3.8.
contains a conceptual system or data-model specific event that is
delivered within an event notification stream. Also called a
"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. o NETCONF client: a client which implements the NETCONF protocol.
Called "client" in [RFC6241]. Called "client" in [RFC6241].
o NETCONF server: a server which implements the NETCONF protocol. o NETCONF server: a server which implements the NETCONF protocol.
Called "server" in [RFC6241]. 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, header fields, and
body. message-body.
o operation resource: a resource that models a data-model specific o operation resource: a resource that models a data-model-specific
operation, that is defined with a YANG "rpc" or "action" operation, that is defined with a YANG "rpc" or "action"
statement. It is invoked with the POST method. statement. It is invoked with the POST method.
o patch: a generic PATCH request on the target datastore or data o patch: a PATCH method on the target datastore or data resource.
resource. The media type of the message-body content will The media type of the message-body content will identify the patch
identify the patch type in use. type in use.
o plain patch: a specific PATCH request type, defined in o plain patch: a specific media type for use with the PATCH method,
Section 4.6.1, that can be used for simple merge operations. It defined in Section 4.6.1, that can be used for simple merge
has a representation with the media-type "application/yang-data" operations. It is specified by a request Content-Type of
or "application/yang-data+json". "application/yang-data-xml" or "application/yang-data+json".
o query parameter: a parameter (and its value if any), encoded o query parameter: a parameter (and its value if any), encoded
within the query component of the request URI. within the query component of the request URI.
o resource type: one of the RESTCONF resource classes defined in
this document. One of "api", "datastore", "data", "operation",
"schema", or "event stream".
o RESTCONF capability: An optional RESTCONF protocol feature o RESTCONF capability: An optional RESTCONF protocol feature
supported by the server, which is identified by an IANA registered supported by the server, which is identified by an IANA registered
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 defined in Section 9.3.
o RESTCONF client: a client which implements the RESTCONF protocol. o RESTCONF client: a client which implements the RESTCONF protocol.
Also called "client".
o RESTCONF server: a server which implements the RESTCONF protocol. 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 schema resource: a resource that used by the client to retrieve a
message, identified by the "path" component of the request URI. YANG schema with the GET method. It has a representation with the
media type "application/yang".
o schema resource: a resource that has a representation with the o server: a RESTCONF server
media type "application/yang". The schema resource is used by the
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.
o YANG data template: a schema for modeling a conceptual data o stream resource: An event stream resource.
structure in an encoding-independent manner. It is defined with
the "yang-data" extension, found in Section 8. It has a o target resource: the resource that is associated with a particular
representation with the media-type "application/yang-data" or message, identified by the "path" component of the request URI.
"application/yang-data+json".
o yang-data extension: A YANG external statement that conforms to
the "yang-data" extension statement found in Section 8. The yang-
data extension is used to define YANG data structures that are
meant to be used as YANG data templates. These data structures
are not intended to be implemented as part of a configuration
datastore or as operational state within the server, so normal
YANG data definition statements cannot be used.
o YANG data template: a schema for modeling protocol message
components as conceptual data structure using YANG. This allows
the messages to be defined in an encoding-independent manner.
Each YANG data template is defined with the "yang-data" extension,
found in Section 8. Representations of instances conforming to a
particular YANG data template can be defined for YANG. The XML
representation is defined in YANG version 1.1
[I-D.ietf-netmod-rfc6020bis], and supported with the "application/
yang-data-xml" media type. The JSON representation is defined in
JSON Encoding of Data Modeled with YANG
[I-D.ietf-netmod-yang-json], and supported with the "application/
yang-data+json" media type.
1.1.6. URI Template and Examples 1.1.6. URI Template and Examples
Throughout this document, the URI template [RFC6570] syntax Throughout this document, the URI template [RFC6570] syntax
"{+restconf}" is used to refer to the RESTCONF API entry point "{+restconf}" is used to refer to the RESTCONF root resource outside
outside of an example. See Section 3.1 for details. of an example. See Section 3.1 for details.
For simplicity, all of the examples in this document assume "/ For simplicity, all of the examples in this document use "/restconf"
restconf" as the discovered RESTCONF API root path. as the discovered RESTCONF API root path. Many of the examples
throughout the document are based on the "example-jukebox" YANG
module, defined in Appendix C.1.
Many of the examples throughout the document are based on the Many protocol header lines and message-body text within examples
"example-jukebox" YANG module, defined in Appendix C.1. throughout the document are split into multiple lines for display
purposes only. When a line ends with backslash ('\') as the last
character, the line is wrapped for display purposes. It is to be
considered to be joined to the next line by deleting the backslash,
the following line break, and the leading whitespace of the next
line.
1.1.7. Tree Diagrams 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), "ro" state data (read-only), and "x" operation
resource (executable)
o Symbols after data node names: "?" means an optional node, "!" o Symbols after data node names: "?" means an optional node, "!"
means a presence container, and "*" denotes a list and leaf-list. means a presence container, and "*" denotes a list and leaf-list.
o Parentheses enclose choice and case nodes, and case nodes are also o Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":"). marked with a colon (":").
o Ellipsis ("...") stands for contents of subtrees that are not o Ellipsis ("...") stands for contents of subtrees that are not
shown. shown.
skipping to change at page 11, line 11 skipping to change at page 11, line 34
RESTCONF achieves this by implementing a subset of the interaction RESTCONF achieves this by implementing a subset of the interaction
capabilities provided by the NETCONF protocol, for instance, by capabilities provided by the NETCONF protocol, for instance, by
eliminating datastores and explicit locking. eliminating datastores and explicit locking.
RESTCONF uses HTTP methods to implement the equivalent of NETCONF RESTCONF uses HTTP methods to implement the equivalent of NETCONF
operations, enabling basic CRUD operations on a hierarchy of operations, enabling basic CRUD operations on a hierarchy of
conceptual resources. conceptual resources.
The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data
resources represented by YANG data models. These basic edit resources represented by YANG data models. These basic edit
operations allow the running configuration to be altered in an all- operations allow the running configuration to be altered by a
or-none fashion. RESTCONF client.
RESTCONF is not intended to replace NETCONF, but rather provide an RESTCONF is not intended to replace NETCONF, but rather provide an
additional interface that follows Representational State Transfer HTTP interface that follows Representational State Transfer (REST)
(REST) principles [rest-dissertation], and is compatible with a principles [rest-dissertation], and is compatible with the NETCONF
resource-oriented device abstraction. datastore model.
The following figure shows the system components if a RESTCONF server The following figure shows the system components if a RESTCONF server
is co-located with a NETCONF server: is co-located with a NETCONF server:
+-----------+ +-----------------+ +-----------+ +-----------------+
| Web app | <-------> | | | Web app | <-------> | |
+-----------+ HTTP | network device | +-----------+ RESTCONF | network device |
| | | |
+-----------+ | +-----------+ | +-----------+ | +-----------+ |
| NMS app | <-------> | | datastore | | | NETCONF | <-------> | | datastore | |
+-----------+ NETCONF | +-----------+ | | Client | NETCONF | | | |
+-----------------+ +-----------+ | +-----------+ |
+-----------------+
The following figure shows the system components if a RESTCONF server The following figure shows the system components if a RESTCONF server
is implemented in a device that does not have a NETCONF server: is implemented in a device that does not have a NETCONF server:
+-----------+ +-----------------+ +-----------+ +-----------------+
| Web app | <-------> | | | Web app | <-------> | |
+-----------+ HTTP | network device | +-----------+ RESTCONF | network device |
| | | |
+-----------------+ +-----------------+
Note that there are no interactions at all between the NETCONF
protocol and RESTCONF protocol. It is possible that locks are in use
on a RESTCONF server, even though RESTCONF cannot manipulate locks.
In such a case, the RESTCONF protocol will not be granted write
access to data resources within a datastore.
1.3. Data Model Driven API 1.3. Data Model Driven API
RESTCONF combines the simplicity of the HTTP protocol with the RESTCONF combines the simplicity of the HTTP protocol with the
predictability and automation potential of a schema-driven API. predictability and automation potential of a schema-driven API.
Using YANG, a client can predict all management resources, much like Knowing the YANG modules used by the server, a client can derive all
using URI Templates [RFC6570], but in a more holistic manner. This management resource URLs and the proper structure of all RESTCONF
strategy obviates the need for responses provided by the server to requests and responses. This strategy obviates the need for
contain Hypermedia as the Engine of Application State (HATEOAS) responses provided by the server to contain Hypermedia as the Engine
links, originally described in Roy Fielding's doctoral dissertation of Application State (HATEOAS) links, originally described in Roy
[rest-dissertation], because the client can determine the links it Fielding's doctoral dissertation [rest-dissertation], because the
needs from the YANG modules. client can determine the links it needs from the YANG modules.
RESTCONF provides the YANG module capability information supported by RESTCONF utilizes the YANG Library [RFC7895] to allow a client to
the server, in case the client wants to use it. The URIs for data- discover the YANG module conformance information for the server, in
model specific RPC operations and datastore content are predictable, case the client wants to use it.
based on the YANG module definitions.
The server can optionally support retrieval of the YANG modules it
uses, as identified in its YANG library. See Section 3.7 for
details.
The URIs for data-model-specific RPC operations and datastore content
are predictable, 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 [RFC7895]. The server MUST implement the "ietf-yang-library" module,
"ietf-yang-library" module, which MUST identify all the YANG modules which MUST identify all the YANG modules used by the server, in the
used by the server. "modules-state/module" list. The conceptual datastore contents,
data-model-specific RPC operations and event notifications are
The conceptual datastore contents, data-model-specific operations and identified by this set of YANG modules.
event notifications are identified by this set of YANG modules.
The classification of data as configuration or non-configuration is The classification of data as configuration or non-configuration is
derived from the YANG "config" statement. Data ordering behavior is derived from the YANG "config" statement. Data ordering behavior is
derived from the YANG "ordered-by" statement. derived from the YANG "ordered-by" statement. Non-configuration data
is also called "state data".
The RESTCONF datastore editing model is simple and direct, similar to The RESTCONF datastore editing model is simple and direct, similar to
the behavior of the :writable-running capability in NETCONF. Each the behavior of the :writable-running capability in NETCONF. Each
RESTCONF edit of a datastore resource is activated upon successful RESTCONF edit of a data resource within the datastore resource is
completion of the transaction. activated upon successful completion of the edit.
1.4. Coexistence with NETCONF 1.4. Coexistence with NETCONF
RESTCONF can be implemented on a device that supports NETCONF. RESTCONF can be implemented on a device that supports the NETCONF
protocol.
If the device supports :writable-running, all edits to configuration If the NETCONF server supports :writable-running, all edits to
nodes in {+restconf}/data are performed in the running configuration configuration nodes in {+restconf}/data are performed in the running
datastore. The URI template "{+restconf}" is defined in configuration datastore. The URI template "{+restconf}" is defined
Section 1.1.6. in Section 1.1.6.
Otherwise, if the device supports :candidate, all edits to Otherwise, if the device supports :candidate, all edits to
configuration nodes in {+restconf}/data are performed in the configuration nodes in {+restconf}/data are performed in the
candidate configuration datastore. The candidate MUST be candidate configuration datastore. The candidate MUST be
automatically committed to running immediately after each successful automatically committed to running immediately after each successful
edit. Any edits from other sources that are in the candidate edit. Any edits from other sources that are in the candidate
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 by any NETCONF client, then this commit will act as the
the server is expecting a "persist-id" parameter to complete the confirming commit. If the NETCONF server is expecting a "persist-id"
confirmed commit procedure then the RESTCONF edit operation MUST fail parameter to complete the confirmed commit procedure then the
with a "409 Conflict" status-line. RESTCONF edit operation MUST fail with a "409 Conflict" status-line.
There error-tag "in-use" is returned in this case. The error-tag
value "resource-denied" is used in this case.
If the device supports :startup, the device MUST automatically update If the NETCONF server supports :startup, the RESTCONF server MUST
the non-volatile "startup datastore", after the running datastore has automatically update the non-volatile startup configuration
been updated as a consequence of a RESTCONF edit operation. datastore, after the running datastore has been altered 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 from a NETCONF client, the RESTCONF edit operation MUST active lock from a NETCONF client, the RESTCONF edit operation MUST
fail with a "409 Conflict" status-line. fail with a "409 Conflict" status-line. There error-tag "in-use" is
returned in this case.
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
future version of this protocol is defined, then that document will future version of this protocol is defined, then that document will
specify how the new version of RESTCONF is identified. It is specify how the new version of RESTCONF is identified. It is
expected that a different entry point {+restconf2} would be defined. expected that a different RESTCONF root resource will be used which
will be located using a different link relation (See Section 3.1).
The server will advertise all protocol versions that it supports in The server will advertise all protocol versions that it supports in
its host-meta data. its host-meta data.
In this example, the server supports both RESTCONF version 1 and a In this example, the server supports both RESTCONF version 1 and a
fictitious version 2. fictitious version 2.
Request The client might send:
-------
GET /.well-known/host-meta HTTP/1.1 GET /.well-known/host-meta HTTP/1.1
Host: example.com Host: example.com
Accept: application/xrd+xml Accept: application/xrd+xml
Response The server might respond:
--------
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/xrd+xml Content-Type: application/xrd+xml
Content-Length: nnn Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'> <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<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. This "ietf-restconf-monitoring" module defined in Section 9.3. This
document defines several query parameters in Section 4.8. Each document defines several query parameters in Section 4.8. Each
optional parameter has a corresponding capability URI defined in optional parameter has a corresponding capability URI defined in
Section 9.1.1 that is advertised by the server if supported. Section 9.1.1 that is advertised by the server if 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 Currently this extension mechanism is used to identify optional query
parameters but it is not limited to that purpose. For example, the parameters that are supported, but it is not limited to that purpose.
"defaults" URI defined in Section 9.1.2 specifies a mandatory URI For example, the "defaults" URI defined in Section 9.1.2 specifies a
identifying server defaults handling behavior. mandatory URI 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.
2. Transport Protocol Requirements 2. Transport Protocol Requirements
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
skipping to change at page 14, line 36 skipping to change at page 15, line 39
The server MAY respond using same HTTP/2 stream that was used for the The server MAY respond using same HTTP/2 stream that was used for the
corresponding request. corresponding request.
2.2. HTTPS with X.509v3 Certificates 2.2. HTTPS with X.509v3 Certificates
Given the nearly ubiquitous support for HTTP over TLS [RFC7230], Given the nearly ubiquitous support for HTTP over TLS [RFC7230],
RESTCONF implementations MUST support the "https" URI scheme, which RESTCONF implementations MUST support the "https" URI scheme, which
has the IANA assigned default port 443. has the IANA assigned default port 443.
RESTCONF servers MUST present an X.509v3 based certificate when RESTCONF servers MUST present an X.509v3 based certificate when
establishing a TLS connection with a RESTCONF client. The use the establishing a TLS connection with a RESTCONF client. The use of
X.509v3 based certificates is consistent with NETCONF over TLS X.509v3 based certificates is consistent with NETCONF over TLS
[RFC7589]. [RFC7589].
2.3. Certificate Validation 2.3. Certificate Validation
The RESTCONF client MUST either use X.509 certificate path validation The RESTCONF client MUST either use X.509 certificate path validation
[RFC5280] to verify the integrity of the RESTCONF server's TLS [RFC5280] to verify the integrity of the RESTCONF server's TLS
certificate, or match the presented X.509 certificate with locally certificate, or match the server's TLS certificate with a certificate
configured certificate fingerprints. obtained by a trusted mechanism (e.g. a pinned certificate). If
X.509 certificate path validation fails, and the presented X.509
The presented X.509 certificate MUST also be considered valid if it certificate does not match a certificate obtained by a trusted
matches a locally configured certificate fingerprint. If X.509 mechanism, the connection MUST be terminated, as described in
certificate path validation fails and the presented X.509 certificate Section 7.2.1 of [RFC5246].
does not match a locally configured certificate fingerprint, the
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 authenticated, the server resource. If the RESTCONF client is not authenticated, the server
SHOULD send an HTTP response with "401 Unauthorized" status-line, as SHOULD send an HTTP response with "401 Unauthorized" status-line, as
defined in Section 3.1 of [RFC7235]. defined in Section 3.1 of [RFC7235]. The error-tag value
"access-denied" is used in this case.
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 15, line 40 skipping to change at page 16, line 41
derived using the algorithm defined in Section 7 of [RFC7589]. For derived using the algorithm defined in Section 7 of [RFC7589]. For
all other cases, when HTTP authentication is used, the RESTCONF all other cases, when HTTP authentication is used, the RESTCONF
username MUST be provided by the HTTP authentication scheme used. username MUST be provided by the HTTP authentication scheme used.
3. Resources 3. Resources
The RESTCONF protocol operates on a hierarchy of resources, starting The RESTCONF protocol operates on a hierarchy of resources, starting
with the top-level API resource itself (Section 3.1). Each resource with the top-level API resource itself (Section 3.1). Each resource
represents a manageable component within the device. represents a manageable component within the device.
A resource can be considered a collection of data and the set of A resource can be considered as 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 representation associated with a media type A resource has a representation associated with a media type
identifier, as represented by the "Content-Type" header in the HTTP identifier, as represented by the "Content-Type" header field in the
response message. A resource can contain zero or more nested HTTP response message. A resource has one or more representations,
resources. A resource can be created and deleted independently of each associated with a different media type. When a representation
its parent resource, as long as the parent resource exists. of a resource is sent in an HTTP message, the associated media type
is given in the "Content-Type" header. A resource can contain zero
All RESTCONF resource types are defined in this document except or more nested resources. A resource can be created and deleted
specific datastore contents, RPC operations, and event notifications. independently of its parent resource, as long as the parent resource
exists.
The syntax and semantics for these resource types are defined in YANG
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 RPC operations, top-level data determine the data model specific RPC operations, top-level data
nodes, 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 an RPC operation or
operation or data resource identifier. 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.
When first connecting to a RESTCONF server, a RESTCONF client MUST When first connecting to a RESTCONF server, a RESTCONF client MUST
determine the root of the RESTCONF API. There MUST be exactly one determine the root of the RESTCONF API. There MUST be exactly one
"restconf" link relation returned by the device. "restconf" link relation returned by the device.
The client discovers this by getting the "/.well-known/host-meta" The client discovers this by getting the "/.well-known/host-meta"
resource ([RFC6415]) and using the <Link> element containing the resource ([RFC6415]) and using the <Link> element containing the
"restconf" attribute : "restconf" attribute :
Example returning /restconf: Example returning /restconf:
Request The client might send:
-------
GET /.well-known/host-meta HTTP/1.1 GET /.well-known/host-meta HTTP/1.1
Host: example.com Host: example.com
Accept: application/xrd+xml Accept: application/xrd+xml
Response The server might respond:
--------
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/xrd+xml Content-Type: application/xrd+xml
Content-Length: nnn Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'> <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/> <Link rel='restconf' href='/restconf'/>
</XRD> </XRD>
After discovering the RESTCONF API root, the client MUST prepend it After discovering the RESTCONF API root, the client MUST use this
to any subsequent request to a RESTCONF resource. In this example, value as the initial part of the path in the request URI, in any
the client would use the path "/restconf" as the RESTCONF entry subsequent request for a RESTCONF resource.
point.
In this example, the client would use the path "/restconf" as the
RESTCONF root resource.
Example returning /top/restconf: Example returning /top/restconf:
Request The client might send:
-------
GET /.well-known/host-meta HTTP/1.1 GET /.well-known/host-meta HTTP/1.1
Host: example.com Host: example.com
Accept: application/xrd+xml Accept: application/xrd+xml
Response The server might respond:
--------
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/xrd+xml Content-Type: application/xrd+xml
Content-Length: nnn Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'> <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/top/restconf'/> <Link rel='restconf' href='/top/restconf'/>
</XRD> </XRD>
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 root resource.
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 The client might send:
-------
GET /top/restconf/operations HTTP/1.1 GET /top/restconf/operations HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data+json Accept: application/yang-data+json
Response The server might respond:
--------
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2016 17:01:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT Last-Modified: Sun, 22 Apr 2016 01:00:14 GMT
Content-Type: application/yang-data+json Content-Type: application/yang-data+json
{ "operations" : { "example-jukebox:play" : [null] } } { "operations" : { "example-jukebox:play" : [null] } }
If the XRD contains more than one link relation, then only the If the Extensible Resource Descriptor (XRD) contains more than one
relation named "restconf" is relevant to this specification. link relation, then only the relation named "restconf" is relevant to
this specification.
Note that any given endpoint (host:port) can only support one
RESTCONF server, due to the root resource discovery mechanism. This
limits the number of RESTCONF servers that can run concurrently on a
host, since each server must use a different port.
3.2. RESTCONF Media Types 3.2. RESTCONF Media Types
The RESTCONF protocol defines two application specific media types to The RESTCONF protocol defines two application specific media types to
identify representations of data which conforms to the schema for a identify representations of data which conforms to the schema for a
particular YANG construct. particular YANG construct.
This document defines media types for XML and JSON serialization of This document defines media types for XML and JSON serialization of
YANG data. Other documents MAY define other media types for YANG data. Other documents MAY define other media types for
different serializations of YANG data. The "application/yang-data" different serializations of YANG data. The "application/
media-type is defined in Section 11.3.1. The "application/ yang-data-xml" media-type is defined in Section 11.3.1. The
yang-data+json" media-type is defined in Section 11.3.2. "application/yang-data+json" media-type is defined in Section 11.3.2.
3.3. API Resource 3.3. API Resource
The API resource contains the entry points for the RESTCONF datastore The API resource contains the RESTCONF root resource for the RESTCONF
and operation resources. It is the top-level resource located at datastore and operation resources. It is the top-level resource
{+restconf} and has the media type "application/yang-data" or located at {+restconf} and has the media type "application/
"application/yang-data+json". yang-data-xml" or "application/yang-data+json".
YANG Tree Diagram for an API Resource: YANG Tree Diagram for an API Resource:
+--rw restconf +---- {+restconf}
+--rw data +---- data
+--rw operations | ...
+--ro yang-library-version +---- operations?
| ...
+--ro yang-library-version string
The "yang-api" YANG data template is defined with the "yang-data" The "yang-api" YANG data template is defined using the "yang-data"
extension in the "ietf-restconf" module, found in Section 8. It is extension in the "ietf-restconf" module, found in Section 8. It
used to specify the structure and syntax of the conceptual child specifies the structure and syntax of the conceptual child resources
resources within the API resource. 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 The {+restconf} root resource name used in responses representing the
identify the "ietf-restconf" YANG module. For example, a request to root of the "ietf-restconf" module MUST identify the "ietf-restconf"
GET the entry point "/restconf" in JSON format will return a YANG module. For example, a request to GET the root resource
representation of the API resource named "ietf-restconf:restconf". "/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 |
+----------------------+--------------------------------+ +----------------------+--------------------------------+
RESTCONF API Resource RESTCONF API Resource
3.3.1. {+restconf}/data 3.3.1. {+restconf}/data
This mandatory resource represents the combined configuration and This mandatory resource represents the combined configuration and
state data resources that can be accessed by a client. It cannot be state data resources that can be accessed by a client. It cannot be
created or deleted by the client. The datastore resource type is created or deleted by the client. The datastore resource type is
defined in Section 3.4. defined in Section 3.4.
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 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 2016 17:01:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Content-Type: application/yang-data 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 RPC 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 RPC
are advertised. operations are advertised.
Any data-model specific RPC operations defined in the YANG modules Any data-model-specific RPC operations defined in the YANG modules
advertised by the server MUST be available as child nodes of this advertised by the server MUST be available as child nodes of this
resource. resource.
The entry point for each RPC operation is represented as an empty The access point for each RPC operation is represented as an empty
leaf. If an operation resource is retrieved, the empty leaf leaf. If an operation resource is retrieved, the empty leaf
representation is returned by the server. 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.
Note that the revision date for the module version found in [RFC7895]
[RFC Editor Note: Adjust the date for ietf-yang-library below to the is used.
date in the published ietf-yang-library YANG module, and remove this
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 Accept: application/yang-data-xml
The server might respond (response wrapped for display purposes): 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 2016 17:01:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Content-Type: application/yang-data 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-06-21\
</yang-library-version> </yang-library-version>
3.4. Datastore Resource 3.4. Datastore Resource
The "{+restconf}/data" subtree represents the datastore resource The "{+restconf}/data" subtree represents the datastore resource,
type, which is a collection of configuration data and state data which is a collection of configuration data and state data nodes.
nodes. The fragment field in the request URI has no defined purpose The fragment field in the request URI has no defined purpose if the
if the target resource is a datastore resource. 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. The client uses it to edit and retrieve
for the client. The RESTCONF datastore resource is a conceptual data resources, as the conceptual root of all configuration and state
collection of all configuration and state data that is present on the 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, as described in
Section 1.4.
If the datastore resource represented by the "{+restconf}/data" If the datastore resource represented by the "{+restconf}/data"
subtree is retrieved, then the datastore and its contents are subtree is retrieved, then the datastore and its contents are
returned by the server. The datastore is represented by a node named returned by the server. The datastore is represented by a node named
"data" in the "ietf-restconf" module namespace. "data" in the "ietf-restconf" module namespace.
3.4.1. Edit Collision Detection 3.4.1. Edit Collision Prevention
Two "edit collision detection" mechanisms are provided in RESTCONF, Two edit collision detection and prevention mechanisms are provided
for datastore and data resources. in RESTCONF for the datastore resource: a timestamp and an entity-
tag. Any change to configuration data resources updates the
timestamp and entity tag of the datastore resource. In addition, the
RESTCONF server will return an error if the datastore is locked by an
external source (e.g., NETCONF server).
3.4.1.1. Timestamp 3.4.1.1. Timestamp
The last change time is maintained and the "Last-Modified" The last change time is maintained and the "Last-Modified"
([RFC7232], Section 2.2) header is returned in the response for a ([RFC7232], Section 2.2) header field is returned in the response for
retrieval request. The "If-Unmodified-Since" header can be used in a retrieval request. The "If-Unmodified-Since" header field
edit operation requests to cause the server to reject the request if ([RFC7232], Section 3.4) can be used in edit operation requests to
the resource has been modified since the specified timestamp. cause the server to reject the request if the resource has been
modified since the specified timestamp.
The server SHOULD maintain a last-modified timestamp for the The server SHOULD maintain a last-modified timestamp for the
datastore resource, defined in Section 3.4. This timestamp is only datastore resource, defined in Section 3.4. This timestamp is only
affected by configuration child data resources, and MUST NOT be affected by configuration child data resources, and MUST NOT be
updated for changes to non-configuration child data resources. Last- updated for changes to non-configuration child data resources. Last-
modified timestamps for data resources are discussed in Section 3.5. modified timestamps for data resources are discussed in Section 3.5.
If the RESTCONF server is colocated with a NETCONF server, then the If the RESTCONF server is colocated with a NETCONF server, then the
last-modified timestamp MUST represent the "running" datastore. last-modified timestamp MUST be for the "running" datastore. Note
that it is possible other protocols can cause the last-modified
timestamp to be updated. Such mechanisms are out of scope for this
document.
3.4.1.2. Entity tag 3.4.1.2. Entity-Tag
A unique opaque string is maintained and the "ETag" ([RFC7232], The server MUST maintain a unique opaque entity-tag for the datastore
Section 2.3) header is returned in the response for a retrieval resource and MUST return it in the "ETag" ([RFC7232], Section 2.3)
request. The "If-Match" header can be used in edit operation header in the response for a retrieval request. The client MAY use
requests to cause the server to reject the request if the resource an "If-Match" header in edit operation requests to cause the server
entity tag does not match the specified value. to reject the request if the resource 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
data resource. This entity tag is only affected by configuration {+restconf}/data resource. This entity-tag is only affected by
data resources, and MUST NOT be updated for changes to non- configuration data resources, and MUST NOT be updated for changes to
configuration data. Entity tags for data resources are discussed in non-configuration data. Entity-tags for data resources are discussed
Section 3.5. in Section 3.5. Note that each representation (e.g. XML vs. JSON)
requires a different entity-tag.
If the RESTCONF server is colocated with a NETCONF server, then this If the RESTCONF server is colocated with a NETCONF server, then this
entity tag MUST represent the "running" datastore. entity-tag MUST be for the "running" datastore. Note that it is
possible other protocols can cause the entity-tag to be updated.
Such mechanisms are out of scope for this document.
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 for that resource, any ancestor data resources, and the
datastore resource. datastore resource.
For example, an edit to disable an interface might be done by setting For example, an edit to disable an interface might be done by setting
the leaf "/interfaces/interface/enabled" to "false". The "enabled" the leaf "/interfaces/interface/enabled" to "false". The "enabled"
data node and its ancestors (one "interface" list instance, and the data node and its ancestors (one "interface" list instance, and the
"interfaces" container) are considered to be changed. The datastore "interfaces" container) are considered to be changed. The datastore
is considered to be changed when any top-level configuration data is considered to be changed when any top-level configuration data
node is changed (e.g., "interfaces"). node is changed (e.g., "interfaces").
3.5. Data Resource 3.5. Data Resource
skipping to change at page 22, line 28 skipping to change at page 23, line 46
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 method. Containers, leafs, targeted by the request-line of an HTTP method. Containers, leafs,
leaf-list entries, list entries, anydata and anyxml nodes are data leaf-list entries, list entries, anydata and anyxml nodes are data
resources. resources.
The representation maintained for each data resource is the YANG The representation maintained for each data resource is the YANG
defined subtree for that node. HTTP methods on a data resource defined subtree for that node. HTTP methods on a data resource
affect both the targeted data node and all its descendants, if any. affect both the targeted data node and all its descendants, if any.
A data resource can be retrieved with the GET method. Data resources A data resource can be retrieved with the GET method. Data resources
are accessed via the "{+restconf}/data" entry point. This sub-tree are accessed via the "{+restconf}/data" URI. This sub-tree is used
is used to retrieve and edit data resources. The fragment field in to retrieve and edit data resources. The fragment field in the
the request URI has no defined purpose if the target resource is a request URI has no defined purpose if the target resource is a data
data resource. 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 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 field 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 field can be used by a RESTCONF client in
client in subsequent requests, within the "If-Modified-Since" and subsequent requests, within the "If-Modified-Since" and
"If-Unmodified-Since" headers. "If-Unmodified-Since" header fields.
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. If the RESTCONF server is for the datastore MUST be used instead. If the RESTCONF server is
colocated with a NETCONF server, then the last-modified timestamp for colocated with a NETCONF server, then the last-modified timestamp for
a configuration data resource MUST represent the instance within the a configuration data resource MUST represent the instance within the
"running" datastore. "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- 3.5.2. Entity-Tag
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 each 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 field when it is retrieved as the target resource with the GET or
methods. If maintained, the resource entity tag MUST be updated HEAD 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 field 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" header
headers. fields.
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. If the MUST NOT be updated for changes to non-configuration data. If the
RESTCONF server is colocated with a NETCONF server, then the entity RESTCONF server is colocated with a NETCONF server, then the entity-
tag for a configuration data resource MUST represent the instance tag for a configuration data resource MUST represent the instance
within the "running" datastore. within the "running" datastore.
For non-configuration data resources, the server MAY maintain an
entity tag for each resource, and return the "ETag" header when it is
retrieved with the GET or HEAD methods. The entity tags for non-
configuration data resources are updated in an implementation-
specific manner.
3.5.3. 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 can be identified with an absolute XPath
defined in [XPath], starting from the document root to the target expression, defined in [XPath], starting from the document root to
resource. In RESTCONF, URI-encoded path expressions are used the target resource. In RESTCONF, URI-encoded path expressions are
instead. used 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 encoded from left to right,
is encoded from left to right, starting with the top-level data node, starting with the top-level data node, according to the "api-path"
according to the "api-path" rule in Section 3.5.3.1. The node name rule in Section 3.5.3.1. The node name of each ancestor of the
of each ancestor of the target resource node is encoded in order, target resource node is encoded in order, ending with the node name
ending with the node name for the target resource. If a node in the for the target resource. If a node in the path is defined in another
path is defined in another module than its parent node, then module module than its parent node, or its parent is the datastore, then the
name followed by a colon character (":") is prepended to the node module name followed by a colon character (":") MUST be prepended to
name in the resource identifier. See Section 3.5.3.1 for details. the node 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 identifier for the leaf-list MUST be encoded using one path o The identifier for the leaf-list MUST be encoded using 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).
o The leaf-list value is specified as a string, using the canonical
representation for the YANG data type. Any reserved characters
MUST be percent-encoded, according to [RFC3986], section 2.1 and
2.5.
o YANG 1.1 allows duplicate leaf-list values for non-configuration
data. In this case there is no mechanism to specify the exact
matching leaf-list instance.
o The comma (',') character is percent-encoded, even though multiple
key values are not possible for a leaf-list. This is more
consistent and avoids special processing rules.
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
MUST be encoded using one path segment [RFC3986]. MUST be encoded using one path segment [RFC3986].
o If there is only one key leaf value, the path segment is o If there is only one key leaf value, the path segment is
constructed by having the list name, followed by an "=" character, constructed by having the list name, followed by an "=" character,
followed by the single key leaf value. followed by the single key leaf value.
o If there are multiple key leaf values, the path segment is o If there are multiple key leaf values, the path segment is
constructed by having the list name, followed by the value of each constructed by having the list name, followed by the value of each
leaf identified in the "key" statement, encoded in the order leaf identified in the "key" statement, encoded in the order
specified in the YANG "key" statement. Each key leaf value except specified in the YANG "key" statement. Each key leaf value except
the last one is followed by a comma character. the last one is followed by a comma character.
o The key value is specified as a string, using the canonical o The key value is specified as a string, using the canonical
representation for the YANG data type. Any reserved characters representation for the YANG data type. Any reserved characters
MUST be percent-encoded, according to [RFC3986], section 2.1. MUST be percent-encoded, according to [RFC3986], section 2.1 and
2.5. The comma (',') character MUST be percent-encoded if it is
present in the key value.
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 Missing key values are not allowed, so two consecutive commas are
are interpreted as a zero-length string. (example: interpreted as a comma, followed by a zero-length string, followed
list=foo,,baz). by a comma. For example, "list1=foo,,baz" would be interpreted as
a list named "list1" with 3 key values, and the second key value
is a zero-length string.
o Note that non-configuration lists are not required to define keys.
In this case, a single list instance cannot be accessed.
o The "list-instance" ABNF rule defined in Section 3.5.3.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.
Resource URI values returned in Location headers for data resources
MUST identify the module name as specified in
[I-D.ietf-netmod-yang-json], even if there are no conflicting local
names when the resource is created. This ensures the correct
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, the container "top" is defined in the For the above YANG definition, the container "top" is defined in the
"example-top" YANG module, and a target resource URI for leaf "X" "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:
/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
The following example shows how reserved characters are percent- The following example shows how reserved characters are percent-
encoded within a key value. The value of "key1" contains a comma, encoded within a key value. The value of "key1" contains a comma,
single-quote, double-quote, colon, double-quote, space, and forward single-quote, double-quote, colon, double-quote, space, and forward
slash. (,'":" /). Note that double-quote is not a reserved slash. (,'":" /). Note that double-quote is not a reserved
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.3.1. ABNF For Data Resource Identifiers 3.5.3.1. ABNF For Data Resource Identifiers
The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to
construct RESTCONF path identifiers: construct RESTCONF path identifiers. Note that this syntax is used
for all resources, and the API path starts with the RESTCONF root
resource. Data resources are required to be identified under the
subtree "+{restconf}/data".
api-path = "/" | An identifier is not allowed to start with the case-insensitive
("/" api-identifier string "XML", according to YANG identifier rules. The syntax for
0*("/" (api-identifier | list-instance ))) "api-identifier" and "key-value" MUST conform to the JSON identifier
encoding rules in Section 4 of [I-D.ietf-netmod-yang-json]: The
RESTCONF root resource path is required. Additional sub-resource
identifiers are optional. The characters in a key value string are
constrained, and some characters need to be percent-encoded, as
described in Section 3.5.3.
api-identifier = [module-name ":"] identifier ;; note 1 api-path = root ["/" (api-identifier | list-instance)]*
root = string ;; replacement string for {+restconf}
api-identifier = [module-name ":"] identifier
module-name = identifier module-name = identifier
list-instance = api-identifier "=" key-value ["," key-value]* list-instance = api-identifier "=" key-value ["," key-value]*
key-value = string ;; note 1 key-value = string ;; constrained chars are percent-encoded
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'))
identifier = (ALPHA / "_") identifier = (ALPHA / "_")
*(ALPHA / DIGIT / "_" / "-" / ".") *(ALPHA / DIGIT / "_" / "-" / ".")
Note 1: The syntax for "api-identifier" and "key-value" MUST conform 3.5.4. Default Handling
to the JSON identifier encoding rules in Section 4 of
[I-D.ietf-netmod-yang-json].
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.
skipping to change at page 27, line 19 skipping to change at page 29, line 8
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 an RPC operation defined with the
YANG "rpc" statement or a data-model specific action defined with a YANG "rpc" statement or a data-model-specific action defined with a
YANG "action" statement. It is invoked using a POST method on the YANG "action" statement. It is invoked using a POST method on the
operation resource. The fragment field in the request URI has no operation resource. The fragment field in the request URI has no
defined purpose if the target resource is an 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 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 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.
All operation resources representing RPC operations supported by the
server MUST be identified in the {+restconf}/operations subtree
defined in Section 3.3.2. Operation resources representing YANG
actions are not identified in this subtree since they are invoked
using a URI within the {+restconf}/data subtree.
3.6.1. Encoding Operation Resource Input Parameters
If the "rpc" or "action" statement has an "input" section then If the "rpc" or "action" statement has an "input" section then
instances of these input parameters are encoded in the module instances of these input parameters are encoded in the module
namespace where the "rpc" or "action" statement is defined, in an XML namespace where the "rpc" or "action" statement is defined, in an XML
element or JSON object named "input", which is in the module element or JSON object named "input", which is in the module
namespace where the "rpc" or "action" statement is defined. namespace where the "rpc" or "action" statement is defined.
If the "rpc" or "action" statement has an "input" section and the If the "rpc" or "action" statement has an "input" section and the
"input" object tree contains any child data nodes which are "input" object tree contains any child data nodes which are
considered mandatory nodes, then a message-body MUST be sent by the considered mandatory nodes, then a message-body MUST be sent by the
client in the request. client in the request.
If the "rpc" or "action" statement has an "input" section and the If the "rpc" or "action" statement has an "input" section and the
"input" object tree does not contain any child nodes which are "input" object tree does not contain any child nodes which are
considered mandatory nodes, then a message-body MAY be sent by the considered mandatory nodes, then a message-body MAY be sent by the
client in the request. client in the request.
If the "rpc" or "action" statement has no "input" section, the If the "rpc" or "action" statement has no "input" section, the
request message MUST NOT include a message-body. request message MUST NOT include a message-body.
If the "rpc" or "action" statement has an "output" section then
instances of these output parameters are encoded in the module
namespace where the "rpc" or "action" statement is defined, in an XML
element or JSON object named "output", which is in the module
namespace where the "rpc" or "action" statement is defined.
If the RPC operation is invoked without errors, and if the "rpc" or
"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
server MUST be identified in the {+restconf}/operations subtree
defined in Section 3.3.2. Operation resources representing YANG
actions are not identified in this subtree since they are invoked
using a URI within the {+restconf}/data subtree.
3.6.1. Encoding Operation Resource Input Parameters
If the "rpc" or "action" statement has an "input" section, then the
"input" node is provided in the message-body, corresponding to the
YANG data definition statements within the "input" section. The
"input" node is defined to be in the namespace of the module
containing the "rpc" or "action" statement.
Examples: Examples:
The following YANG module is used for the RPC operation examples in The following YANG module is used for the RPC operation examples in
this section. this section.
module example-ops { module example-ops {
namespace "https://example.com/ns/example-ops"; namespace "https://example.com/ns/example-ops";
prefix "ops"; prefix "ops";
organization "Example, Inc."; organization "Example, Inc.";
skipping to change at page 31, line 18 skipping to change at page 33, line 8
} }
} }
} }
RPC Input Example: RPC Input Example:
The client might send the following POST request message to invoke The client might send the following POST request message to invoke
the "reboot" RPC operation: the "reboot" RPC operation:
POST /restconf/operations/example-ops:reboot HTTP/1.1 POST /restconf/operations/example-ops:reboot HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data 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 2016 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-data+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:
POST /restconf/data/example-actions:interfaces/interface=eth0 POST /restconf/data/example-actions:interfaces/\
/reset HTTP/1.1 interface=eth0/reset HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data 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 2016 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):
POST /restconf/data/example-actions:interfaces/interface=eth0 POST /restconf/data/example-actions:interfaces/\
/reset HTTP/1.1 interface=eth0/reset HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data+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
"output" node is provided in the message-body, corresponding to the instances of these output parameters are encoded in the module
YANG data definition statements within the "output" section. The namespace where the "rpc" or "action" statement is defined, in an XML
"output" node is defined to be in the namespace of the module element or JSON object named "output", which is in the module
containing the "rpc" or "action" statement. namespace where the "rpc" or "action" statement is defined.
The request URI is not returned in the response. This URI might have If the RPC operation is invoked without errors, and if the "rpc" or
context information required to associate the output to the specific "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.
The request URI is not returned in the response. Knowledge of the
request URI may be needed to associate the output with the specific
"rpc" or "action" statement used in the request. "rpc" or "action" statement used in the request.
Examples: Examples:
RPC Output Example: RPC Output Example:
The "example-ops" YANG module defined in Section 3.6.1 is used for The "example-ops" YANG module defined in Section 3.6.1 is used for
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-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, 25 Apr 2012 11:10:30 GMT Date: Mon, 25 Apr 2016 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+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 2016 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data 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/\
/get-last-reset-time HTTP/1.1 interface=eth0/get-last-reset-time 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, 25 Apr 2012 11:10:30 GMT Date: Mon, 25 Apr 2016 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+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.
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.
Using the "reboot" RPC operation from the example in Section 3.6.1, Using the "reboot" RPC operation from the example in Section 3.6.1,
the client might send the following POST request message: the client might send the following POST request message:
POST /restconf/operations/example-ops:reboot HTTP/1.1 POST /restconf/operations/example-ops:reboot HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data 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 2016 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data Content-Type: application/yang-data-xml
<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error> <errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error-type>protocol</error-type> <error>
<error-tag>invalid-value</error-tag> <error-type>protocol</error-type>
<error-path xmlns:ops="https://example.com/ns/example-ops"> <error-tag>invalid-value</error-tag>
/ops:input/ops:delay <error-path xmlns:ops="https://example.com/ns/example-ops">
</error-path> /ops:input/ops:delay
<error-message>Invalid input parameter</error-message> </error-path>
</error> <error-message>Invalid input parameter</error-message>
</errors> </error>
</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 2016 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+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",
} }
] ]
} }
} }
3.7. Schema Resource 3.7. Schema Resource
The server can optionally support retrieval of the YANG modules it The server can optionally support retrieval of the YANG modules it
supports. If retrieval is supported, then the "schema" leaf MUST be supports. If retrieval is supported, then the "schema" leaf MUST be
present in the associated "module" list entry, defined in present in the associated "module" list entry, defined in [RFC7895].
[I-D.ietf-netconf-yang-library].
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/\
example-jukebox,2015-04-04/schema HTTP/1.1 module=example-jukebox,2016-08-15/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/2016-08-15"
} }
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:
GET https://example.com/mymodules/example-jukebox/2015-04-04 GET https://example.com/mymodules/example-jukebox/\
HTTP/1.1 2016-08-15 HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang Accept: application/yang
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:31 GMT Date: Thu, 11 Feb 2016 11:10:31 GMT
Server: example-server Server: example-server
Content-Type: application/yang Content-Type: application/yang
module example-jukebox { module example-jukebox {
skipping to change at page 36, line 46 skipping to change at page 39, line 5
} }
3.8. Event Stream Resource 3.8. Event Stream Resource
An "event stream" resource represents a source for system generated An "event stream" resource represents a source for system generated
event notifications. Each stream is created and modified by the event notifications. Each stream is created and modified by the
server only. A client can retrieve a stream resource or initiate a server only. A client can retrieve a stream resource or initiate a
long-poll server sent event stream, using the procedure specified in long-poll server sent event stream, using the procedure specified in
Section 6.3. Section 6.3.
A notification stream functions according to the NETCONF An event stream functions according to the NETCONF Notifications
Notifications specification [RFC5277]. The available streams can be specification [RFC5277]. The available streams can be retrieved from
retrieved from the stream list, which specifies the syntax and the stream list, which specifies the syntax and semantics of the
semantics of a stream resource. stream resources. The fragment field in the request URI has no
defined purpose if the target resource is an event stream resource.
The fragment field in the request URI has no defined purpose if the
target resource is an event stream resource.
3.9. Errors YANG Data Template 3.9. Errors YANG Data Template
An "errors" YANG data template models a collection of error The "errors" YANG data template models a collection of error
information that is sent as the message-body in a server response information that is sent as the message-body in a server response
message, if an error occurs while processing a request message. It message, if an error occurs while processing a request message. It
is not considered a resource type because no instances can be is not considered as a resource type because no instances can be
retrieved with a GET request. retrieved with a GET request.
The "ietf-restconf" YANG module contains the "yang-errors" YANG data The "ietf-restconf" YANG module contains the "yang-errors" YANG data
template, that specifies the syntax and semantics of an "errors" template, that specifies the syntax and semantics of an "errors"
container within a RESTCONF response. RESTCONF error handling container within a RESTCONF response. RESTCONF error handling
behavior is defined in Section 7. behavior is defined in Section 7.
4. Operations 4. 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. operations requested for a particular resource.
The following table shows how the RESTCONF operations relate to The following table shows how the RESTCONF operations relate to
NETCONF protocol operations and edit operations, which are identified NETCONF protocol operations and for the NETCONF <edit-config>
with the NETCONF "nc:operation" attribute. operation, the "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> (nc:operation="create") | | POST | <edit-config> (nc:operation="create") |
| POST | invoke an RPC operation | | POST | invoke an RPC operation |
| PUT | <edit-config> (nc:operation="create/replace") | | PUT | <edit-config> (nc:operation="create/replace") |
| PATCH | <edit-config> (nc:operation="merge") | | PATCH | <edit-config> (nc:operation="merge") |
| DELETE | <edit-config> (nc:operation="delete") | | DELETE | <edit-config> (nc:operation="delete") |
+----------+-----------------------------------------------+ +----------+-----------------------------------------------+
CRUD Methods in RESTCONF CRUD Methods in RESTCONF
The "remove" operation attribute for the NETCONF <edit-config> The "remove" edit operation attribute for the NETCONF <edit-config>
operation is not supported by the HTTP DELETE method. The resource RPC operation is not supported by the HTTP DELETE method. The
must exist or the DELETE method will fail. The PATCH method is resource must exist or the DELETE method will fail. The PATCH method
equivalent to a "merge" operation when using a plain patch (see is equivalent to a "merge" edit operation when using a plain patch
Section 4.6.1); other media-types may provide more granular control. (see 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 are used to limit what CRUD 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. The resource path needs to
resource path needs to be converted internally by the server to the be converted internally by the server to the corresponding YANG
corresponding YANG instance-identifier. Using this information, the instance-identifier. Using this information, the server can apply
server can apply the NACM access control rules to RESTCONF messages. 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 RESTCONF operation for any resources
client is not authorized to access. that the client is not authorized to access.
Implementation of all methods (except PATCH) are defined in Implementation of all methods (except PATCH [RFC5789]) 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.
If the PATCH method is supported, then the "Accept-Patch" header MUST If the PATCH method is supported, then the "Accept-Patch" header
be supported and returned in the response to the OPTIONS request, as field MUST be supported and returned in the response to the OPTIONS
defined in [RFC5789]. request, as defined in [RFC5789].
4.2. HEAD 4.2. HEAD
The HEAD method is sent by the client to retrieve just the headers The RESTCONF server MUST support the HEAD method. The HEAD method is
that would be returned for the comparable GET method, without the sent by the client to retrieve just the header fields (which contain
response message-body. It is supported for all resource types, the metadata for a resource) that would be returned for the
except operation resources. comparable GET method, without the response message-body. It is
supported for all resources that support the GET method.
The request MUST contain a request URI that contains at least the The request MUST contain a request URI that contains at least the
entry point. The same query parameters supported by the GET method root resource. 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 metadata The RESTCONF server MUST support the GET method. The GET method is
for a resource. It is supported for all resource types, except sent by the client to retrieve data and metadata for a resource. It
operation resources. The request MUST contain a request URI that is supported for all resource types, except operation resources. The
contains at least the entry point. request MUST contain a request URI that contains at least the root
resource.
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. The error-tag value "access-denied"
Found" status-line, as described in section 6.5.3 in [RFC7231]. is returned in this case. A server MAY return a "404 Not Found"
status-line, as described in section 6.5.3 in [RFC7231]. The error-
tag value "invalid-value" is returned in this case.
If the user is authorized to read some but not all of the target If the user is authorized to read some but not all of the target
resource, the unauthorized content is omitted from the response resource, the unauthorized content is omitted from the response
message-body, and the authorized content is returned to the client. message-body, and the authorized content is returned to the client.
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 multiple elements are sent in a JSON
message-body, then they MUST be sent as a JSON array. In this case
any timestamp or entity-tag returned in the response MUST be
associated with the first element returned.
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. The
error-tag value "invalid-value" is used in this case. Note that a
non-configuration list is not required to defined any keys. In this
case, retrieval of a single list instance is not possible.
If a retrieval request for a data resource represents an instance If a retrieval request for a data resource represents an instance
that does not exist, then an error response containing a "404 Not that does not exist, then an error response containing a "404 Not
Found" status-line MUST be returned by the server. Found" status-line MUST be returned by the server. The error-tag
value "invalid-value" is used in this case.
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. The error-tag value "operation-not-supported" is used
in this case.
Note that the way that access control is applied to data resources Note that the way that access control is applied to data resources
may not be completely compatible with HTTP caching. The Last- may not be completely compatible with HTTP caching. The Last-
Modified and ETag headers maintained for a data resource are not Modified and ETag header fields maintained for a data resource are
affected by changes to the access control rules for that data not affected by changes to the access control rules for that data
resource. It is possible for the representation of a data resource resource. It is possible for the representation of a data resource
that is visible to a particular client to be changed without that is visible to a particular client to be changed without
detection via the Last-Modified or ETag values. detection via the Last-Modified or ETag values.
Example: Example:
The client might request the response headers for an XML The client might request the response header fields for an XML
representation of the a specific "album" resource: representation of the a specific "album" resource:
GET /restconf/data/example-jukebox:jukebox/ GET /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data 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 2016 17:02:40 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data Content-Type: application/yang-data-xml
Cache-Control: no-cache Cache-Control: no-cache
ETag: "a74eefc993a2b" ETag: "a74eefc993a2b"
Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT Last-Modified: Mon, 23 Apr 2016 11:02:14 GMT
<album xmlns="http://example.com/ns/example-jukebox" <album xmlns="http://example.com/ns/example-jukebox"
xmlns:jbox="http://example.com/ns/example-jukebox"> xmlns:jbox="http://example.com/ns/example-jukebox">
<name>Wasting Light</name> <name>Wasting Light</name>
<genre>jbox:alternative</genre> <genre>jbox:alternative</genre>
<year>2011</year> <year>2011</year>
</album> </album>
4.4. POST 4.4. POST
The POST method is sent by the client to create a data resource or The RESTCONF server MUST support the POST method. The POST method is
invoke an operation resource. The server uses the target resource sent by the client to create a data resource or invoke an operation
media type to determine how to process the request. resource. The server uses the target resource 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 an RPC operation | | Operation | Invoke an RPC operation |
+-----------+------------------------------------------------+ +-----------+------------------------------------------------+
Resource Types that Support POST Resource Types that Support POST
skipping to change at page 40, line 48 skipping to change at page 43, line 21
resource). The message-body MUST contain exactly one instance of the resource). The message-body MUST contain exactly one instance of the
expected data resource. The data-model for the child tree is the expected data resource. The data-model for the child tree is the
subtree as defined by YANG for the child resource. subtree as defined by YANG for the child resource.
The "insert" Section 4.8.5 and "point" Section 4.8.6 query parameters The "insert" Section 4.8.5 and "point" Section 4.8.6 query parameters
MUST be supported by the POST method for datastore and data MUST be supported by the POST method for datastore and data
resources. These parameters are only allowed if the list or leaf- resources. These parameters are only allowed if the list or leaf-
list is ordered-by user. 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 field
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. The error-tag
value "resource-denied" is used in this case.
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
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 The error-tag value "access-denied" is used in this case. A server
section 6.5.3 in [RFC7231]. All other error responses are handled MAY return a "404 Not Found" status-line, as described in section
according to the procedures defined in Section 7. 6.5.3 in [RFC7231]. The error-tag value "invalid-value" is used in
this case. All other error responses are handled 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
only:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2016 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 2016 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
error response containing a "403 Forbidden" status-line is returned error response containing a "403 Forbidden" status-line is returned
to the client. All other error responses are handled according to to the client. The error-tag value "access-denied" is used in this
the procedures defined in Section 7. case. All other error responses are handled according to the
procedures defined in Section 7.
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-data+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:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:50:00 GMT Date: Mon, 23 Apr 2016 17:50:00 GMT
Server: example-server Server: example-server
4.5. PUT 4.5. PUT
The PUT method is sent by the client to create or replace the target The RESTCONF server MUST support the PUT method. The PUT method is
data resource. A request message-body MUST be present, representing sent by the client to create or replace the target data resource. A
the new data resource, or the server MUST return "400 Bad Request" request message-body MUST be present, representing the new data
status-line. resource, or the server MUST return "400 Bad Request" status-line.
The error-tag value "invalid-value" is used in this case.
The only target resource media type that supports PUT is the data Both the POST and PUT methods can be used to create data resources.
resource. The message-body is expected to contain the content used The difference is that for POST, the client does not provide the
to create or replace the target resource. resource identifier for the resource that will be created. The
target resource for the POST method for resource creation is the
parent of the new resource. The target resource for the PUT method
for resource creation is the new resource.
The PUT method MUST be supported for data and datastore resources. A
PUT on the datastore resource is used to replace the entire contents
of the datastore. A PUT on a data resource only replaces that data
resource within the datastore.
The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query
parameters MUST be supported by the PUT method for data resources. parameters MUST be supported by the PUT method for data resources.
These parameters are only allowed if the list or leaf-list is These parameters are only allowed if the list or leaf-list is
ordered-by user. ordered-by user.
Consistent with [RFC7231], if the PUT request creates a new resource, Consistent with [RFC7231], if the PUT request creates a new resource,
a "201 Created" status-line is returned. If an existing resource is a "201 Created" status-line is returned. If an existing resource is
modified, a "204 No Content" status-line is returned. modified, a "204 No Content" status-line is returned.
If the user is not authorized to create or replace the target If the user is not authorized to create or replace the target
resource an error response containing a "403 Forbidden" status-line resource an error response containing a "403 Forbidden" status-line
SHOULD be returned. A server MAY return a "404 Not Found" status- SHOULD be returned. The error-tag value "access-denied" is used in
line, as described in section 6.5.3 in [RFC7231]. All other error this case.
responses are handled according to the procedures defined in
Section 7. A server MAY return a "404 Not Found" status-line, as
described in section 6.5.3 in ^RFC7231^.
The error-tag value "invalid-value" is used in this case.
All other error responses are handled according to
the procedures defined in ^error-reporting^.
If the target resource represents a YANG leaf-list, then the PUT If the target resource represents a YANG leaf-list, then the PUT
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 PUT If the target resource represents a YANG list instance, then the key
method MUST NOT change any key leaf values in the message-body leaf values in message-body representation MUST be the same as the
representation. key leaf values in the request URI. The PUT method MUST NOT be used
to change the key leaf values for a data resource instance.
Example: Example:
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:
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", "name" : "Wasting Light",
"genre" : "example-jukebox:alternative", "genre" : "example-jukebox:alternative",
"year" : 2011 "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 2016 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 2016 17:04:00 GMT
ETag: "b27480aeda4c" ETag: "b27480aeda4c"
The same request is shown here using XML encoding: The same request is shown here using XML encoding:
PUT /restconf/data/example-jukebox:jukebox/ PUT /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data Content-Type: application/yang-data-xml
<album xmlns="http://example.com/ns/example-jukebox"
xmlns:jbox="http://example.com/ns/example-jukebox"> <album xmlns="http://example.com/ns/example-jukebox"
<name>Wasting Light</name> xmlns:jbox="http://example.com/ns/example-jukebox">
<genre>jbox:alternative</genre> <name>Wasting Light</name>
<year>2011</year> <genre>jbox:alternative</genre>
</album> <year>2011</year>
</album>
4.6. PATCH 4.6. PATCH
RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide The RESTCONF server MUST support the PATCH method. RESTCONF uses the
an extensible framework for resource patching mechanisms. It is HTTP PATCH method defined in [RFC5789] to provide an extensible
optional to implement by the server. Each patch mechanism needs a framework for resource patching mechanisms. It is optional to
unique media type. Zero or more patch media types MAY be supported implement by the server. Each patch mechanism needs a unique media
by the server. The media types supported by a server can be type. Zero or more patch media types MAY be supported by the server.
discovered by the client by sending an OPTIONS request, and examining The media types supported by a server can be discovered by the client
the Accept-Patch header field in the response. (see Section 4.1). by sending an OPTIONS request, and examining the Accept-Patch header
field in the response. (see Section 4.1).
This document defines one patch mechanism (Section 4.6.1). Another This document defines one patch mechanism (Section 4.6.1). Another
patch mechanism, the YANG PATCH mechanism, is defined in patch mechanism, the YANG PATCH mechanism, is defined in
[I-D.ietf-netconf-yang-patch]. Other patch mechanisms may be defined [I-D.ietf-netconf-yang-patch]. Other patch mechanisms may be defined
by future specifications. by future specifications.
If the target resource instance does not exist, the server MUST NOT If the target resource instance does not exist, the server MUST NOT
create it. create it.
If the PATCH request succeeds, a "200 OK" status-line is returned if If the PATCH request succeeds, a "200 OK" status-line is returned if
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]. The error-tag value "invalid-value" is
according to the procedures defined in Section 7. used in this case. All other error responses are handled according
to the procedures defined in Section 7.
4.6.1. Plain Patch 4.6.1. Plain Patch
The plain patch mechanism merges the contents of the message-body The plain patch mechanism merges the contents of the message-body
with the target resource. The message-body for a plain patch MUST be with the target resource. The message-body for a plain patch MUST be
present and MUST be represented by the media type "application/ present and MUST be represented by the media type "application/
yang-data" or "application/yang-data+json". yang-data-xml" or "application/yang-data+json".
Plain patch can be used to create or update, but not delete, a child Plain patch can be used to create or update, but not delete, a child
resource within the target resource. Please see resource within the target resource. Please see
[I-D.ietf-netconf-yang-patch] for an alternate media-type supporting [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting
the ability to delete child resources. The YANG Patch Media Type the ability to delete child resources. The YANG Patch Media Type
allows multiple sub-operations (e.g., merge, delete) within a single allows multiple sub-operations (e.g., merge, delete) within a single
PATCH operation. PATCH method.
If the target resource represents a YANG leaf-list, then the PATCH If the target resource represents a YANG leaf-list, then the PATCH
method MUST NOT change the value of the leaf-list instance. method MUST NOT change the value of the leaf-list instance.
If the target resource represents a YANG list instance, then the If the target resource represents a YANG list instance, then the key
PATCH method MUST NOT change any key leaf values in the message-body leaf values in message-body representation MUST be the same as the
representation. key leaf values in the request URI. The PATCH method MUST NOT be
used to change the key leaf values for a data resource instance.
After the plain patch is processed by the server. a response will be
returned to the client, as specified in Section 4.6.
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.
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 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 2016 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 2016 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 RESTCONF server MUST support the DELETE method. The DELETE
DELETE request succeeds, a "204 No Content" status-line is returned. method is used to delete the target resource. If the DELETE request
succeeds, a "204 No Content" status-line is returned.
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. The error-tag value "access-denied" is returned in this
described in section 6.5.3 in [RFC7231]. All other error responses case. A server MAY return a "404 Not Found" status-line, as
described in section 6.5.3 in [RFC7231]. The error-tag value
"invalid-value" is returned in this case. 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 configuration leaf-list or list
DELETE method SHOULD NOT delete more than one such instance. The data node, then it MUST represent a single YANG leaf-list or list
server MAY delete more than one instance if a query parameter is used instance. The server MUST NOT use the DELETE method to delete more
requesting this behavior. (Definition of this query parameter is than one such instance.
outside the scope of this document.)
Example: Example:
To delete a resource such as the "album" resource, the client might To delete the "album" resource with the key "Wasting Light", the
send: client might send:
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
If the resource is deleted, the server might respond: If the resource is deleted, the server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 17:49:40 GMT Date: Mon, 23 Apr 2016 17:49:40 GMT
Server: example-server Server: example-server
4.8. Query Parameters 4.8. Query Parameters
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 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. "400 Bad Request" status-line MUST be returned by the server. The
error-tag value "invalid-value" is returned in this case.
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. The error-tag value
"invalid-value" is returned in this case.
+-------------------+-------------+---------------------------------+ +---------------+---------+-----------------------------------------+
| Name | Methods | Description | | Name | Methods | Description |
+-------------------+-------------+---------------------------------+ +---------------+---------+-----------------------------------------+
| content | GET, HEAD | Select config and/or non-config | | content | GET, | Select config and/or non-config data |
| | | data resources | | | HEAD | resources |
| depth | GET, HEAD | Request limited sub-tree depth | | depth | GET, | Request limited sub-tree depth in the |
| | | in the reply content | | | HEAD | reply content |
| fields | GET, HEAD | Request a subset of the target | | fields | GET, | Request a subset of the target resource |
| | | resource contents | | | HEAD | contents |
| filter | GET, HEAD | Boolean notification filter for | | filter | GET, | Boolean notification filter for event |
| | | event stream resources | | | HEAD | stream resources |
| insert | POST, PUT | Insertion mode for ordered-by | | insert | POST, | Insertion mode for ordered-by user data |
| | | user data resources | | | PUT | resources |
| point | POST, PUT | Insertion point for ordered-by | | point | POST, | Insertion point for ordered-by user |
| | | user data resources | | | PUT | data resources |
| start-time | GET, HEAD | Replay buffer start time for | | start-time | GET, | Replay buffer start time for event |
| | | event stream resources | | | HEAD | stream resources |
| stop-time | GET, HEAD | Replay buffer stop time for | | stop-time | GET, | Replay buffer stop time for event |
| | | event stream resources | | | HEAD | stream resources |
| with-defaults | GET, HEAD | Control retrieval of default | | with-defaults | GET, | Control retrieval of default values |
| | | values | | | HEAD | |
+-------------------+-------------+---------------------------------+ +---------------+---------+-----------------------------------------+
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.
4.8.1. The "content" Query Parameter 4.8.1. The "content" Query Parameter
skipping to change at page 47, line 47 skipping to change at page 51, line 22
This parameter is only allowed for GET methods on datastore and data This parameter is only allowed for GET methods on datastore and data
resources. A "400 Bad Request" status-line is returned if used for resources. A "400 Bad Request" status-line is returned if used for
other methods or resource types. other methods or resource types.
If this query parameter is not present, the default value is "all". If this query parameter is not present, the default value is "all".
This query parameter MUST be supported by the server. This query parameter MUST be supported by the server.
4.8.2. The "depth" Query Parameter 4.8.2. The "depth" Query Parameter
The "depth" parameter is used to specify the number of nest levels The "depth" parameter is used to limit the depth of subtrees returned
returned in a response for a GET method. The first nest-level by the server. Data nodes with a depth value greater than the
consists of the requested data node itself. If the "fields" "depth" parameter are not returned in a response for a GET method.
The requested data node has a depth level of '1'. If the "fields"
parameter (Section 4.8.3) is used to select descendant data nodes, parameter (Section 4.8.3) is used to select descendant data nodes,
these nodes all have a depth value of 1. This has the effect of then these nodes and all their ancestor nodes have a depth value of
including the nodes specified by the fields, even if the "depth" 1. (This has the effect of including the nodes specified by the
value is less than the actual depth level of the specified fields. fields, even if the "depth" value is less than the actual depth level
Any child nodes which are contained within a parent node have a depth of the specified fields.) Any other child node has a depth value
value that is 1 greater than its parent. 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.
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
skipping to change at page 48, line 33 skipping to change at page 52, line 12
leaf-list in Section 9.3, then the server supports the "depth" query leaf-list in Section 9.3, then the server supports the "depth" query
parameter. parameter.
4.8.3. The "fields" Query Parameter 4.8.3. The "fields" Query Parameter
The "fields" query parameter is used to optionally identify data The "fields" query parameter is used to optionally identify data
nodes within the target resource to be retrieved in a GET method. nodes within the target resource to be retrieved in a GET method.
The client can use this parameter to retrieve a subset of all nodes The client can use this parameter to retrieve a subset of all nodes
in a resource. in a resource.
The server will return a message-body representing the target
resource, with descendant nodes pruned as specified in the
"fields-expr" value. The server does not return a set separate sub-
resources.
A value of the "fields" query parameter matches the following rule: A value of the "fields" query parameter matches the following rule:
fields-expr = path '(' fields-expr ')' / fields-expr = path '(' fields-expr ')' /
path ';' fields-expr / path ';' fields-expr /
path path
path = api-identifier [ '/' path ] path = api-identifier [ '/' path ]
"api-identifier" is defined in Section 3.5.3.1. "api-identifier" is defined in Section 3.5.3.1.
";" 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. Note that Parentheses are used to specify sub-selectors of a node. Note that
there is no path separator character '/' between a "path" field and there is no path separator character '/' between a "path" field and
left parenthesis character '('. 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:
/label". "fields=admin/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.
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.
This parameter is only allowed for GET methods on a text/event-stream This parameter is only allowed for GET methods on an event stream
data resource. A "400 Bad Request" status-line is returned if used resource. A "400 Bad Request" status-line is returned if used for
for other methods or resource types. other methods or resource types.
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
skipping to change at page 50, line 16 skipping to change at page 54, line 5
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
The "insert" parameter is used to specify how a resource should be The "insert" parameter is used to specify how a resource should be
inserted within a ordered-by user list. inserted within a ordered-by user list.
The allowed values are: The allowed values are:
+-----------+-------------------------------------------------------+ +--------+----------------------------------------------------------+
| Value | Description | | Value | Description |
+-----------+-------------------------------------------------------+ +--------+----------------------------------------------------------+
| first | Insert the new data as the new first entry. | | first | Insert the new data as the new first entry. |
| last | Insert the new data as the new last entry. | | last | Insert the new data as the new last entry. |
| before | Insert the new data before the insertion point, as | | before | Insert the new data before the insertion point, as |
| | specified by the value of the "point" parameter. | | | specified by the value of the "point" parameter. |
| after | Insert the new data after the insertion point, as | | after | Insert the new data after the insertion point, as |
| | 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.
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
skipping to change at page 51, line 45 skipping to change at page 55, line 31
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. A client can obtain a server's current time available notification. A client can obtain a server's current time
by examining the "Date" header field that the server returns in by examining the "Date" header field that the server returns in
response messages, according to [RFC7231]. 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, anf the "stop-time" query parameter MUST also be
by the server. supported 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.
4.8.8. The "stop-time" Query Parameter 4.8.8. The "stop-time" Query Parameter
The "stop-time" parameter is used with the replay feature to indicate The "stop-time" parameter is used with the replay feature to indicate
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.
skipping to change at page 52, line 24 skipping to change at page 56, line 11
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.
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, and the "start-time" query parameter MUST also be
by the server. supported 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
(defined in Section 9.3) then the server MUST support the (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.
4.8.9. The "with-defaults" Query Parameter 4.8.9. The "with-defaults" Query Parameter
The "with-defaults" parameter is used to specify how information The "with-defaults" parameter is used to specify how information
about default data nodes should be returned in response to GET about default data nodes should be returned in response to GET
requests on data resources. requests on data resources.
If the server supports this capability, then it MUST implement the If the server supports this capability, then it MUST implement the
behavior in Section 4.5.1 of [RFC6243], except applied to the behavior in Section 4.5.1 of [RFC6243], except applied to the
RESTCONF GET operation, instead of the NETCONF operations. RESTCONF GET operation, instead of the NETCONF operations.
+---------------------------+---------------------------------------+ +-------------------+-----------------------------------------------+
| Value | Description | | Value | Description |
+---------------------------+---------------------------------------+ +-------------------+-----------------------------------------------+
| report-all | All data nodes are reported | | report-all | All data nodes are reported |
| trim | Data nodes set to the YANG default | | trim | Data nodes set to the YANG default are not |
| | are not reported | | | reported |
| explicit | Data nodes set to the YANG default by | | explicit | Data nodes set to the YANG default by the |
| | the client are reported | | | client are reported |
| report-all-tagged | All data nodes are reported and | | report-all-tagged | All data nodes are reported and defaults are |
| | defaults are tagged | | | tagged |
+---------------------------+---------------------------------------+ +-------------------+-----------------------------------------------+
If the "with-defaults" parameter is set to "report-all" then the If the "with-defaults" parameter is set to "report-all" then the
server MUST adhere to the defaults reporting behavior defined in server MUST adhere to the defaults reporting behavior defined in
Section 3.1 of [RFC6243]. Section 3.1 of [RFC6243].
If the "with-defaults" parameter is set to "trim" then the server If the "with-defaults" parameter is set to "trim" then the server
MUST adhere to the defaults reporting behavior defined in Section 3.2 MUST adhere to the defaults reporting behavior defined in Section 3.2
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]. Metadata is reported by the server as
specified in Section 5.3. The XML encoding for the "default"
attribute sent by the server for default nodes is defined in section
6 of [RFC6243]. The JSON encoding for the "default" attribute MUST
use the same values as defined in [RFC6243], but encoded according to
the rules in [I-D.ietf-netmod-yang-metadata]. The module name
"ietf-netconf-with-defaults" MUST be used for the "default"
attribute.
If the "with-defaults" parameter is not present then the server MUST If the "with-defaults" parameter is not present then the server MUST
adhere to the defaults reporting behavior defined in its "basic-mode" adhere to the defaults reporting behavior defined in its "basic-mode"
parameter for the "defaults" protocol capability URI, defined in parameter for the "defaults" protocol capability URI, defined in
Section 9.1.2. Section 9.1.2.
If the server includes the "with-defaults" query parameter URI in the If the server includes the "with-defaults" query parameter URI in the
"capability" leaf-list in Section 9.3, then the "with-defaults" query "capability" leaf-list in Section 9.3, then the "with-defaults" query
parameter MUST be supported. parameter MUST be supported.
Since the server does not report the "also-supported" parameter as
described in section 4.3 of [RFC6243], it is possible that some
values for the "with-defaults" parameter will not be supported. If
the server does not support the requested value of the
"with-defaults" parameter, the server MUST return a response with a
"400 Bad Request" status-line. The error-tag value "invalid-value"
is used in this case.
5. Messages 5. Messages
The RESTCONF protocol uses HTTP entities for messages. A single HTTP The RESTCONF protocol uses HTTP entities for messages. A single HTTP
message corresponds to a single protocol method. Most messages can message corresponds to a single protocol method. Most messages can
perform a single task on a single resource, such as retrieving a perform a single task on a single resource, such as retrieving a
resource or editing a resource. The exception is the PATCH method, resource or editing a resource. The exception is the PATCH method,
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>
^ ^ ^ ^ ^ ^ ^ ^ ^
| | | | | | | | |
method entry resource query fragment method entry resource query
M M O O I M M O O
M=mandatory, O=optional, I=ignored M=mandatory, O=optional
where: where:
<OP> is the HTTP method <OP> is the HTTP method
<restconf> is the RESTCONF entry point <restconf> is the RESTCONF root resource
<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
o method: the HTTP method identifying the RESTCONF operation o method: the HTTP method identifying the RESTCONF operation
requested by the client, to act upon the target resource specified requested by the client, to act upon the target resource specified
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 RESTCONF operation. If this field is not
then the target resource is the API itself, represented by the present, then the target resource is the API itself, represented
YANG data template named "yang-api", found in Section 8. by the 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,
as defined in section 3.4 of [RFC3986]. RESTCONF parameters have as defined in section 3.4 of [RFC3986]. RESTCONF parameters have
the familiar form of "name=value" pairs. Most query parameters the familiar form of "name=value" pairs. Most query parameters
are optional to implement by the server and optional to use by the are optional to implement by the server and optional to use by the
client. Each optional query parameter is identified by a URI. client. Each optional query parameter is identified by a URI.
The server MUST list the optional query parameter URIs it supports The server MUST list the optional query parameter URIs it supports
in the "capabilities" list defined in Section 9.3. 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 and 2.5.
o fragment: This field is not used by the RESTCONF protocol. Note that the fragment component not used by the RESTCONF protocol.
The fragment is excluded from the target URI by a server, as
described in section 5.1 of [RFC7230].
When new resources are created by the client, a "Location" header is When new resources are created by the client, a "Location" header
returned, which identifies the path of the newly created resource. field is returned, which identifies the path of the newly created
The client uses this exact path identifier to access the resource resource. The client uses this exact path identifier to access the
once it has been created. resource once it has been created.
The "target" of an operation is a resource. The "path" field in the The "target" of a RESTCONF operation is a resource. The "path" field
request URI represents the target resource for the operation. in the request URI represents the target resource for the RESTCONF
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 one of either XML or JSON encoding. A server MAY support
both XML and JSON encoding. XML encoding rules for data nodes are
defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are defined in [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 metadata is defined in [I-D.ietf-netmod-yang-json]. Additional JSON encoding rules for
[I-D.ietf-netmod-yang-metadata]. This encoding is valid JSON, but metadata are defined in [I-D.ietf-netmod-yang-metadata]. This
also has special encoding rules to identify module namespaces and encoding is valid JSON, but also has special encoding rules to
provide consistent type processing of YANG data. identify module namespaces and 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 field. This field MUST be present if a message-body is
the client. sent by the client.
The server MUST support the "Accept" header and "406 Not Acceptable" The server MUST support the "Accept" header field and "406 Not
status-line, as defined in [RFC7231]. Response output content Acceptable" status-line, as defined in [RFC7231]. The response
encoding format is identified with the Accept header in the request. output content encoding formats that the client will accept are
If it is not specified, the request input encoding format SHOULD be identified with the Accept header field in the request. If it is not
used, or the server MAY choose any supported content encoding format. specified, the request input encoding format SHOULD be 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.
A client can determine if the RESTCONF server supports an encoding A client can determine if the RESTCONF server supports an encoding
format by sending a request using a specific format in the Content- format by sending a request using a specific format in the Content-
Type and/or Accept header. If the server does not support the Type and/or Accept header field. If the server does not support the
requested input encoding for a request, then it MUST return an error requested input encoding for a request, then it MUST return an error
response with a '415 Unsupported Media Type' status-line. If the response with a '415 Unsupported Media Type' status-line. If the
server does not support any of the requested output encodings for a server does not support any of the requested output encodings for a
request, then it MUST return an error response with a '406 Not request, then it MUST return an error response with a '406 Not
Acceptable' status-line. Acceptable' status-line.
5.3. RESTCONF Metadata 5.3. RESTCONF Metadata
The RESTCONF protocol needs to retrieve the same metadata that is The RESTCONF protocol needs support retrieval of the same metadata
used in the NETCONF protocol. Information about default leafs, last- that is used in the NETCONF protocol. Information about default
modified timestamps, etc. are commonly used to annotate leafs, last-modified timestamps, etc. are commonly used to annotate
representations of the datastore contents. representations of the datastore contents.
With the XML encoding, the metadata is encoded as attributes in XML. With the XML encoding, the metadata is encoded as attributes in XML,
With the JSON encoding, the metadata is encoded as specified in according to section 3.3 of [W3C.REC-xml-20081126]. With the JSON
encoding, the metadata is encoded as specified in
[I-D.ietf-netmod-yang-metadata]. [I-D.ietf-netmod-yang-metadata].
The following examples are based on the example in Appendix D.3.9. The following examples are based on the example in Appendix D.3.9.
The "report-all-tagged" mode for the "with-defaults" query parameter The "report-all-tagged" mode for the "with-defaults" query parameter
requires that a "default" attribute be returned for default nodes. requires that a "default" attribute be returned for default nodes.
This example shows that attribute for the "mtu" leaf . This example shows that attribute for the "mtu" leaf .
5.3.1. XML MetaData Encoding Example 5.3.1. XML Metadata Encoding Example
GET /restconf/data/interfaces/interface=eth1 GET /restconf/data/interfaces/interface=eth1
?with-defaults=report-all-tagged HTTP/1.1 ?with-defaults=report-all-tagged HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data 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 2016 17:01:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data 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 instead of derived YANG, so the YANG module name has to be assigned instead of derived
from the YANG module name. The value "ietf-netconf-with-defaults" is from the YANG module. The value "ietf-netconf-with-defaults" is
assigned for JSON metadata encoding. 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 2016 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" "status-line" header field is returned for each request. If a "4xx"
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 SHOULD be returned in the response, according to the information SHOULD be returned in the response, according to the
format defined in Section 7.1. If a "5xx" range status code is 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 status-line, then the error information MAY be
returned in the response, according to the format defined in 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 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 the status-line, then error information MUST NOT be returned in the
response, since these ranges do not represent error conditions. 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 field in every
that specifies whether the response should be cached. response that specifies whether the response should be cached.
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" header fields returned by the server
datastore resource (or data resource if the server supports it). A for the datastore resource (or data resource if the server supports
retrieval request for a resource can include the "If-None-Match" and/ it). A retrieval request for a resource can include the
or "If-Modified-Since" headers, which will cause the server to return "If-None-Match" and/or "If-Modified-Since" header fields, which will
a "304 Not Modified" status-line if the resource has not changed. cause the server to return a "304 Not Modified" status-line if the
The client MAY use the HEAD method to retrieve just the message resource has not changed. The client MAY use the HEAD method to
headers, which SHOULD include the "ETag" and "Last-Modified" headers, retrieve just the message header fields, which SHOULD include the
if this metadata is maintained for the target resource. "ETag" and "Last-Modified" header fields, if this metadata is
maintained for the target resource.
Note that the way that access control is applied to data resources
the values in the Last-Modified and ETag headers maintained for a
data resource may not be reliable, as described in Section 4.3.
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.REC-eventsource-20150203] 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 method 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).
6.2. Event Streams 6.2. Event Streams
A RESTCONF server that supports notifications will populate a stream A RESTCONF server that supports notifications will populate a stream
resource for each notification delivery service access point. A resource for each notification delivery service access point. A
RESTCONF client can retrieve the list of supported event streams from RESTCONF client can retrieve the list of supported event streams from
a RESTCONF server using the GET operation on the stream list. a RESTCONF server using the GET method on the stream list.
The "restconf-state/streams" container definition in the The "restconf-state/streams" container definition in the
"ietf-restconf-monitoring" module (defined in Section 9.3) is used to "ietf-restconf-monitoring" module (defined in Section 9.3) is used to
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 Accept: application/yang-data-xml
The server might send the following response: The server might send the following response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/yang-data Content-Type: application/yang-data-xml
<streams <streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<stream> <stream>
<name>NETCONF</name> <name>NETCONF</name>
<description>default NETCONF event stream <description>default NETCONF event stream
</description> </description>
<replay-support>true</replay-support> <replay-support>true</replay-support>
<replay-log-creation-time> <replay-log-creation-time>
2007-07-08T00:00:00Z 2007-07-08T00:00:00Z
</replay-log-creation-time>
<access>
<encoding>xml</encoding>
<location>https://example.com/streams/NETCONF
</location>
</access>
<access>
<encoding>json</encoding>
<location>https://example.com/streams/NETCONF-JSON
</location>
</access>
</stream>
<stream>
<name>SNMP</name>
<description>SNMP notifications</description>
<replay-support>false</replay-support>
<access>
<encoding>xml</encoding>
<location>https://example.com/streams/SNMP</location>
</access>
</stream>
<stream>
<name>syslog-critical</name>
<description>Critical and higher severity
</description>
<replay-support>true</replay-support>
<replay-log-creation-time>
2007-07-01T00:00:00Z
</replay-log-creation-time>
<access>
<encoding>xml</encoding>
<location>
https://example.com/streams/syslog-critical
</location>
</replay-log-creation-time> </access>
<access> </stream>
<encoding>xml</encoding> </streams>
<location>https://example.com/streams/NETCONF
</location>
</access>
<access>
<encoding>json</encoding>
<location>https://example.com/streams/NETCONF-JSON
</location>
</access>
</stream>
<stream>
<name>SNMP</name>
<description>SNMP notifications</description>
<replay-support>false</replay-support>
<access>
<encoding>xml</encoding>
<location>https://example.com/streams/SNMP</location>
</access>
</stream>
<stream>
<name>syslog-critical</name>
<description>Critical and higher severity
</description>
<replay-support>true</replay-support>
<replay-log-creation-time>
2007-07-01T00:00:00Z
</replay-log-creation-time>
<access>
<encoding>xml</encoding>
<location>
https://example.com/streams/syslog-critical
</location>
</access>
</stream>
</streams>
6.3. Subscribing to Receive Notifications 6.3. Subscribing to Receive Notifications
RESTCONF clients can determine the URL for the subscription resource RESTCONF clients can determine the URL for the subscription resource
(to receive notifications) by sending an HTTP GET request for the (to receive notifications) by sending an HTTP GET request for the
"location" leaf with the stream list entry. The value returned by "location" leaf with the stream list entry. The value returned by
the server can be used for the actual notification subscription. the server can be used for the actual notification subscription.
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.REC-eventsource-20150203] 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 event stream.
For example: For example:
The client might send the following request: The client might send the following request:
GET /restconf/data/ietf-restconf-monitoring:restconf-state/ GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
streams/stream=NETCONF/access=xml/location HTTP/1.1 streams/stream=NETCONF/access=xml/location HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data Accept: application/yang-data-xml
The server might send the following response: The server might send the following response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/yang-data 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 that the server compress the events
using the HTTP header field "Accept-Encoding". For instance: using 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
The server SHOULD support the "NETCONF" notification stream defined The server SHOULD support the "NETCONF" event stream defined in
in [RFC5277]. For this stream, RESTCONF notification subscription section 3.2.3 of [RFC5277]. For this stream, The server MAY support
requests MAY specify parameters indicating the events it wishes to the "start-time", "stop-time", and "filter" query parameters, defined
receive. These query parameters are optional to implement, and only in Section 4.8. Refer to Appendix D.3.6 for filter parameter
available if the server supports them. examples.
+------------+---------+-------------------------+
| Name | Section | Description |
+------------+---------+-------------------------+
| start-time | 4.8.7 | replay event start time |
| stop-time | 4.8.8 | replay event stop time |
| filter | 4.8.4 | boolean content filter |
+------------+---------+-------------------------+
NETCONF Stream Query Parameters
The semantics and syntax for these query parameters are defined in
the sections listed above. The YANG definition MUST be converted to
a URI-encoded string for use in the request URI.
Refer to Appendix D.3.6 for filter parameter examples.
6.4. Receiving Event Notifications 6.4. Receiving Event Notifications
RESTCONF notifications are encoded according to the definition of the RESTCONF notifications are encoded according to the definition of the
event stream. The NETCONF stream defined in [RFC5277] is encoded in event stream. The NETCONF stream defined in [RFC5277] is encoded in
XML format. XML format.
The structure of the event data is based on the "notification" The structure of the event data is based on the "notification"
element definition in Section 4 of [RFC5277]. It MUST conform to the element definition in Section 4 of [RFC5277]. It MUST conform to the
schema for the "notification" element in Section 4 of [RFC5277], schema for the "notification" element in Section 4 of [RFC5277],
except the XML namespace for this element is defined as: except the XML namespace for the event data element is defined as:
urn:ietf:params:xml:ns:yang:ietf-restconf urn:ietf:params:xml:ns:yang:ietf-restconf
For JSON encoding purposes, the module name for the "notification" For JSON encoding purposes, the module name for the "notification"
element is "ietf-restconf". element is "ietf-restconf".
Two child nodes within the "notification" container are expected, Two child nodes within the "notification" container are expected,
representing the event time and the event payload. The "event-time" representing the event time and the event payload. The "event-time"
node is defined within the "ietf-restconf" module namespace. The node is defined within the "ietf-restconf" module namespace. The
name and namespace of the payload element are determined by the YANG name and namespace of the payload element are determined by the YANG
module containing the notification-stmt. module containing the notification-stmt.
skipping to change at page 62, line 15 skipping to change at page 66, line 20
leaf event-class { type string; } leaf event-class { type string; }
container reporting-entity { container reporting-entity {
leaf card { type string; } leaf card { type string; }
} }
leaf severity { type string; } leaf severity { type string; }
} }
} }
An example SSE event notification encoded using XML: An example SSE event notification encoded using XML:
data: <notification data: <notification
data: xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> data: xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
data: <event-time>2013-12-21T00:01:00Z</event-time> data: <event-time>2013-12-21T00:01:00Z</event-time>
data: <event xmlns="http://example.com/event/1.0"> data: <event xmlns="http://example.com/event/1.0">
data: <event-class>fault</event-class> data: <event-class>fault</event-class>
data: <reporting-entity> data: <reporting-entity>
data: <card>Ethernet0</card> data: <card>Ethernet0</card>
data: </reporting-entity> data: </reporting-entity>
data: <severity>major</severity> data: <severity>major</severity>
data: </event> data: </event>
data: </notification> data: </notification>
An example SSE event notification encoded using JSON: An example SSE event notification encoded using JSON:
data: { data: {
data: "ietf-restconf:notification": { data: "ietf-restconf:notification" : {
data: "event-time": "2013-12-21T00:01:00Z", data: "event-time" : "2013-12-21T00:01:00Z",
data: "example-mod:event": { data: "example-mod:event" : {
data: "event-class": "fault", data: "event-class" : "fault",
data: "reporting-entity": { "card": "Ethernet0" }, data: "reporting-entity" : { "card" : "Ethernet0" },
data: "severity": "major" data: "severity" : "major"
data: } data: }
data: } data: }
data: } data: }
Alternatively, since neither XML nor JSON are whitespace sensitive, Alternatively, since neither XML nor JSON are whitespace sensitive,
the above messages can be encoded onto a single line. For example: the above messages can be encoded onto a single line. For example:
For example: ('\' line wrapping added for formatting only) For example:
XML: XML:
data: <notification xmlns="urn:ietf:params:xml:ns:yang:ietf-rest\ data: <notification xmlns="urn:ietf:params:xml:ns:yang:ietf-rest\
conf"><event-time>2013-12-21T00:01:00Z</event-time><event xmlns="\ conf"><event-time>2013-12-21T00:01:00Z</event-time><event xmlns="\
http://example.com/event/1.0"><event-class>fault</event-class><re\ http://example.com/event/1.0"><event-class>fault</event-class><re\
portingEntity><card>Ethernet0</card></reporting-entity><severity>\ portingEntity><card>Ethernet0</card></reporting-entity><severity>\
major</severity></event></notification> major</severity></event></notification>
JSON: JSON:
data: {"ietf-restconf:notification":{"event-time":"2013-12-21\ data: {"ietf-restconf:notification":{"event-time":"2013-12-21\
T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ T00:01:00Z","example-mod:event":{"event-class": "fault","repor\
tingEntity":{"card":"Ethernet0"},"severity":"major"}}} tingEntity":{"card":"Ethernet0"},"severity":"major"}}}
The SSE specifications supports the following additional fields: The SSE specifications supports the following additional fields:
event, id and retry. A RESTCONF server MAY send the "retry" field event, id and retry. A RESTCONF server MAY send the "retry" field
and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server
SHOULD NOT send the "event" or "id" fields, as there are no SHOULD NOT send the "event" or "id" fields, as there are no
skipping to change at page 63, line 17 skipping to change at page 67, line 26
T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ T00:01:00Z","example-mod:event":{"event-class": "fault","repor\
tingEntity":{"card":"Ethernet0"},"severity":"major"}}} tingEntity":{"card":"Ethernet0"},"severity":"major"}}}
The SSE specifications supports the following additional fields: The SSE specifications supports the following additional fields:
event, id and retry. A RESTCONF server MAY send the "retry" field event, id and retry. A RESTCONF server MAY send the "retry" field
and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server
SHOULD NOT send the "event" or "id" fields, as there are no SHOULD NOT send the "event" or "id" fields, as there are no
meaningful values that could be used for them that would not be meaningful values that could be used for them that would not be
redundant to the contents of the notification itself. RESTCONF redundant to the contents of the notification itself. RESTCONF
servers that do not send the "id" field also do not need to support servers that do not send the "id" field also do not need to support
the HTTP header "Last-Event-Id". RESTCONF servers that do send the the HTTP header field "Last-Event-Id". RESTCONF servers that do send
"id" field MUST still support the "startTime" query parameter as the the "id" field SHOULD support the "start-time" 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 codes 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 error information that NETCONF error responses
responses contains some useful information. This error information contain in the <rpc-error> element is adapted for use in RESTCONF,
is adapted for use in RESTCONF, and error information is returned for and an <errors> data tree information is returned for "4xx" and "5xx"
"4xx" and "5xx" class of status codes. class of status codes.
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 from the NETCONF <error-tag> value to the HTTP status code is needed.
needed. The specific error-tag and response code to use are data- The specific error-tag and response code to use are data-model-
model specific and might be contained in the YANG "description" specific and might be contained in the YANG "description" statement
statement for the "action" or "rpc" statement. for the "action" or "rpc" statement.
+-------------------------+-------------+ +-------------------------+-----------------+
| error-tag | status code | | error-tag | status code |
+-------------------------+-------------+ +-------------------------+-----------------+
| in-use | 409 | | in-use | 409 |
| invalid-value | 400 or 406 | | invalid-value | 400, 404 or 406 |
| (request) too-big | 413 | | (request) too-big | 413 |
| (response) too-big | 400 | | (response) too-big | 400 |
| missing-attribute | 400 | | missing-attribute | 400 |
| bad-attribute | 400 | | bad-attribute | 400 |
| unknown-attribute | 400 | | unknown-attribute | 400 |
| bad-element | 400 | | bad-element | 400 |
| unknown-element | 400 | | unknown-element | 400 |
| unknown-namespace | 400 | | unknown-namespace | 400 |
| access-denied | 403 | | access-denied | 401, 403 |
| lock-denied | 409 | | lock-denied | 409 |
| resource-denied | 409 | | resource-denied | 409 |
| rollback-failed | 500 | | rollback-failed | 500 |
| data-exists | 409 | | data-exists | 409 |
| data-missing | 409 | | data-missing | 409 |
| operation-not-supported | 501 | | operation-not-supported | 405 or 501 |
| operation-failed | 412 or 500 | | operation-failed | 412 or 500 |
| partial-operation | 500 | | partial-operation | 500 |
| malformed-message | 400 | | malformed-message | 400 |
+-------------------------+-------------+ +-------------------------+-----------------+
Mapping from error-tag to status code Mapping from error-tag to status code
7.1. Error Response Message 7.1. Error Response Message
When an error occurs for a request message on any resource type, and When an error occurs for a request message on any resource type, and
the status code that will be returned is in the "4xx" range (except the status code that will be returned is in the "4xx" range (except
for status code "403 Forbidden"), then the server SHOULD send a for status code "403 Forbidden"), then the server SHOULD send a
response message-body containing the information described by the response message-body containing the information described by the
"yang-errors" YANG template definition within the "ietf-restconf" "yang-errors" YANG data template within the "ietf-restconf" module,
module, found in Section 8. The Content-Type of this response found in Section 8. The Content-Type of this response message MUST
message MUST be a subtype of application/yang-data (see example be "application/yang-data", plus optionally a structured syntax name
below). suffix.
The client SHOULD specify the desired encoding for error messages by The client SHOULD specify the desired encoding(s) for response
specifying the appropriate media-type in the Accept header. If no messages by specifying the appropriate media-type(s) in the Accept
error media is specified, then the media subtype (e.g., XML or JSON) header. If the client did not specify an Accept header, then the
of the request message SHOULD be used, or the server MAY choose any same structured syntax name suffix used in the request message SHOULD
supported message encoding format. If there is no request message be used, or the server MAY choose any supported message encoding
the server MUST select "application/yang-data" or "application/ format. If there is no request message the server MUST select
yang-data+json", depending on server preference. All of the examples "application/yang-data-xml" or "application/yang-data+json",
in this document, except for the one below, assume that XML encoding depending on server preference. All of the examples in this
will be returned if there is an error. document, except for the one below, assume that XML encoding will be
returned if there is an error.
YANG Tree Diagram for <errors> data: YANG Tree Diagram for <errors> data:
+--ro errors +---- errors
+--ro error* +---- error*
+--ro error-type enumeration +---- error-type enumeration
+--ro error-tag string +---- error-tag string
+--ro error-app-tag? string +---- error-app-tag? string
+--ro error-path? instance-identifier +---- error-path? instance-identifier
+--ro error-message? string +---- error-message? string
+--ro error-info +---- error-info?
The semantics and syntax for RESTCONF error messages are defined with The semantics and syntax for RESTCONF error messages are defined with
the "yang-errors" YANG data template extension, found in Section 8. the "yang-errors" YANG data template extension, found in 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 field is used to specify the desired encoding for
error message. No response message-body content is expected by the the error message. There would be no response message-body content
client in this example. if this operation was successful.
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-data+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 2016 17:11:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+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:
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:
HTTP/1.1 409 Conflict HTTP/1.1 409 Conflict
Date: Mon, 23 Apr 2012 17:11:00 GMT Date: Mon, 23 Apr 2016 17:11:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data Content-Type: application/yang-data-xml
<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error>
<error-type>protocol</error-type>
<error-tag>data-exists</error-tag>
<error-path
xmlns:rc="urn:ietf:params:xml:ns:yang:ietf-restconf"
xmlns:jbox="https://example.com/ns/example-jukebox">
/rc:restconf/rc:data/jbox:jukebox
</error-path>
<error-message>
Data already exists, cannot create new resource
</error-message>
</error>
</errors>
8. RESTCONF module <errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error>
<error-type>protocol</error-type>
<error-tag>data-exists</error-tag>
<error-path
xmlns:rc="urn:ietf:params:xml:ns:yang:ietf-restconf"
xmlns:jbox="https://example.com/ns/example-jukebox">\
/rc:restconf/rc:data/jbox:jukebox
</error-path>
<error-message>
Data already exists, cannot create new resource
</error-message>
</error>
</errors>
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" URI).
Note that the "ietf-restconf" module does not have any protocol- Note that the "ietf-restconf" module does not have any protocol-
accessible objects, so no YANG tree diagram is shown. accessible objects, so no YANG tree diagram is shown.
RFC Ed.: update the date below with the date of RFC publication and RFC Ed.: update the date below with the date of RFC publication and
remove this note. remove this note.
<CODE BEGINS> file "ietf-restconf@2016-07-07.yang" <CODE BEGINS> file "ietf-restconf@2016-08-15.yang"
module ietf-restconf { module ietf-restconf {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; namespace "urn:ietf:params:xml:ns:yang:ietf-restconf";
prefix "rc"; prefix "rc";
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
contact contact
"WG Web: <http://tools.ietf.org/wg/netconf/> "WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org> WG List: <mailto:netconf@ietf.org>
Editor: Andy Bierman Author: Andy Bierman
<mailto:andy@yumaworks.com> <mailto:andy@yumaworks.com>
Editor: Martin Bjorklund Author: Martin Bjorklund
<mailto:mbj@tail-f.com> <mailto:mbj@tail-f.com>
Editor: Kent Watsen Author: Kent Watsen
<mailto:kwatsen@juniper.net>"; <mailto:kwatsen@juniper.net>";
description description
"This module contains conceptual YANG specifications "This module contains conceptual YANG specifications
for basic RESTCONF media type definitions used in for basic RESTCONF media type definitions used in
RESTCONF protocol messages. RESTCONF protocol messages.
Note that the YANG definitions within this module do not Note that the YANG definitions within this module do not
represent configuration data of any kind. represent configuration data of any kind.
The 'restconf-media-type' YANG extension statement The 'restconf-media-type' YANG extension statement
skipping to change at page 67, line 36 skipping to change at page 72, line 4
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from draft-ietf-netconf-restconf-15.txt // Note: extracted from draft-ietf-netconf-restconf-16.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-07-07 { revision 2016-08-15 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
extension yang-data { extension yang-data {
argument name { argument name {
yin-element true; yin-element true;
} }
description description
"This extension is used to specify a YANG data template which "This extension is used to specify a YANG data template which
represents conceptual data defined in YANG. It is represents conceptual data defined in YANG. It is
intended to describe hierarchical data independent of intended to describe hierarchical data independent of
protocol context or specific message encoding format. protocol context or specific message encoding format.
Data definition statements within this extension specify Data definition statements within a yang-data extension
the generic syntax for the specific YANG data template. specify the generic syntax for the specific YANG data
template, whose name is the argument of the yang-data
extension statement.
Note that this extension does not define a media-type. Note that this extension does not define a media-type.
A specification using this extension MUST specify the A specification using this extension MUST specify the
message encoding rules, including the content media type. message encoding rules, including the content media type.
The mandatory 'name' parameter value identifies the YANG The mandatory 'name' parameter value identifies the YANG
data template that is being defined. It contains the data template that is being defined. It contains the
template name. 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 MUST 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 An instance of a YANG data template can thus be translated
document for each YANG data template. into an XML instance document, whose top-level element
corresponds to the top-level container.
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,
such that the child nodes of the document root are such that the child nodes of the document root are
represented by the data-def-stmt sub-statements within represented by the data-def-stmt sub-statements within
this extension. This conceptual document is the context this extension. This conceptual document is the context
for the following YANG statements: for the following YANG statements:
- must-stmt - must-stmt
- 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 are constrained
meaning when used within a yang-data-resource extension 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:yang-data yang-errors { rc:yang-data yang-errors {
uses errors; uses errors;
} }
rc:yang-data yang-api { rc:yang-data yang-api {
uses restconf; uses restconf;
} }
skipping to change at page 70, line 50 skipping to change at page 75, line 21
"This anydata value MUST represent a container with "This anydata value MUST represent a container with
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 grouping representing the RESTCONF
application/yang-api resource type."; root resource.";
container restconf { container restconf {
description description
"Conceptual container representing the "Conceptual container representing the RESTCONF
application/yang-api resource type."; root resource.";
container data { container data {
description description
"Container representing the application/yang-datastore "Container representing the datastore resource.
resource type. Represents the conceptual root of all Represents the conceptual root of all state data
state data and configuration data supported by and configuration data supported by the server.
the server. The child nodes of this container can be The child nodes of this container can be any data
any data resource (application/yang-data), which are resource which are defined as top-level data nodes
defined as top-level data nodes from the YANG modules from the YANG modules advertised by the server in
advertised by the server in the ietf-restconf-monitoring the ietf-yang-library module.";
module.";
} }
container operations { container operations {
description description
"Container for all operation resources "Container for all operation resources.
(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.
For example, the 'system-restart' RPC operation defined For example, the 'system-restart' RPC operation defined
in the 'ietf-system' module would be represented as in the 'ietf-system' module would be represented as
an empty leaf in the 'ietf-system' namespace. This is an empty leaf in the 'ietf-system' namespace. This is
a conceptual leaf, and will not actually be found in a conceptual leaf, and will not actually be found in
the module: the module:
skipping to change at page 72, line 35 skipping to change at page 77, line 8
} }
} }
} }
<CODE ENDS> <CODE ENDS>
9. RESTCONF Monitoring 9. RESTCONF Monitoring
The "ietf-restconf-monitoring" module provides information about the The "ietf-restconf-monitoring" module provides information about the
RESTCONF protocol capabilities and event notification streams RESTCONF protocol capabilities and event streams available from the
available from the server. A RESTCONF server MUST implement the "/ server. A RESTCONF server MUST implement the
restconf-state/capabilities" container in this module. "ietf-restconf-monitoring" module.
YANG Tree Diagram for "ietf-restconf-monitoring" module: YANG tree diagram for "ietf-restconf-monitoring" module:
+--ro restconf-state +--ro restconf-state
+--ro capabilities +--ro capabilities
| +--ro capability* inet:uri | +--ro capability* inet:uri
+--ro streams +--ro streams
+--ro stream* [name] +--ro stream* [name]
+--ro name string +--ro name string
+--ro description? string +--ro description? string
+--ro replay-support? boolean +--ro replay-support? boolean
+--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 MAY maintain a last-modified timestamp for this container, The server MAY maintain a last-modified timestamp for this container,
and return the "Last-Modified" header when this data node is and return the "Last-Modified" header field when this data node is
retrieved with the GET or HEAD methods. Note that the last-modified retrieved with the GET or HEAD methods. Note that the last-modified
timestamp for the datastore resource is not affected by changes to timestamp for the datastore resource is not affected by changes to
this subtree. this subtree.
The server SHOULD maintain an entity-tag for this container, and The server SHOULD maintain an entity-tag for this container, and
return the "ETag" header when this data node is retrieved with the return the "ETag" header field when this data node is retrieved with
GET or HEAD methods. Note that the entity-tag for the datastore the GET or HEAD methods. Note that the entity-tag for the datastore
resource is not affected by changes to this subtree. resource is not affected by changes to this subtree.
The server MUST include a "capability" URI leaf-list entry for the The server MUST include a "capability" URI leaf-list entry for the
"defaults" mode used by the server, defined in Section 9.1.2. "defaults" mode used by the server, defined in Section 9.1.2.
The server MUST include a "capability" URI leaf-list entry The server MUST include a "capability" URI leaf-list entry
identifying each supported optional protocol feature. This includes identifying each supported optional protocol feature. This includes
optional query parameters and MAY include other capability URIs optional query parameters and MAY include other capability URIs
defined outside this document. defined outside this document.
9.1.1. Query Parameter URIs 9.1.1. Query Parameter URIs
A new set of RESTCONF Capability URIs are defined to identify the A new set of RESTCONF Capability URIs are defined to identify the
specific query parameters (defined in Section 4.8) supported by the specific query parameters (defined in Section 4.8) supported by the
server. server.
The server MUST include a "capability" leaf-list entry for each The server MUST include a "capability" leaf-list entry for each
optional query parameter that it supports. optional query parameter that it supports.
+-------------+-------+---------------------------------------------+ +------------+--------+---------------------------------------------+
| Name | Secti | URI | | Name | Sectio | URI |
| | on | | | | n | |
+-------------+-------+---------------------------------------------+ +------------+--------+---------------------------------------------+
| depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 | | depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 |
| | | .0 | | | | .0 |
| fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: | | fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: |
| | | 1.0 | | | | 1.0 |
| filter | 4.8.4 | urn:ietf:params:restconf:capability:filter: | | filter | 4.8.4 | urn:ietf:params:restconf:capability:filter: |
| | | 1.0 | | | | 1.0 |
| replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: | | replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: |
| | 4.8.8 | 1.0 | | | 4.8.8 | 1.0 |
| with- | 4.8.9 | urn:ietf:params:restconf:capability:with- | | with- | 4.8.9 | urn:ietf:params:restconf:capability:with- |
| defaults | | defaults:1.0 | | defaults | | defaults:1.0 |
+-------------+-------+---------------------------------------------+ +------------+--------+---------------------------------------------+
RESTCONF Query Parameter URIs RESTCONF Query Parameter URIs
9.1.2. The "defaults" Protocol Capability URI 9.1.2. The "defaults" Protocol Capability URI
This URI identifies the defaults handling mode that is used by the This URI identifies the "basic-mode" defaults handling mode that is
server for processing default leafs in requests for data resources. used by the server for processing default leafs in requests for data
A parameter named "basic-mode" is required for this capability URI. resources. This protocol capability URI MUST be supported by the
The "basic-mode" definitions are specified in the "With-Defaults server, and MUST be listed in the "capability" leaf-list in
Capability for NETCONF" [RFC6243]. Section 9.3.
+----------+--------------------------------------------------+ +----------+--------------------------------------------------+
| Name | URI | | Name | URI |
+----------+--------------------------------------------------+ +----------+--------------------------------------------------+
| defaults | urn:ietf:params:restconf:capability:defaults:1.0 | | defaults | urn:ietf:params:restconf:capability:defaults:1.0 |
+----------+--------------------------------------------------+ +----------+--------------------------------------------------+
RESTCONF defaults capability URI RESTCONF defaults capability URI
This protocol capability URI MUST be supported by the server, and The URI MUST contain a query parameter named "basic-mode" with one of
MUST be listed in the "capability" leaf-list in Section 9.3. the values listed below:
+------------------+------------------------------------------------+ +------------+------------------------------------------------------+
| Value | Description | | Value | Description |
+------------------+------------------------------------------------+ +------------+------------------------------------------------------+
| report-all | No data nodes are considered default | | report-all | No data nodes are considered default |
| trim | Values set to the YANG default-stmt value are | | trim | Values set to the YANG default-stmt value are |
| | default | | | default |
| explicit | Values set by the client are never considered | | explicit | Values set by the client are never considered |
| | default | | | default |
+------------------+------------------------------------------------+ +------------+------------------------------------------------------+
The "basic-mode" definitions are specified in the "With-Defaults
Capability for NETCONF" [RFC6243].
If the "basic-mode" is set to "report-all" then the server MUST If the "basic-mode" is set to "report-all" then the server MUST
adhere to the defaults handling behavior defined in Section 2.1 of adhere to the defaults handling behavior defined in Section 2.1 of
[RFC6243]. [RFC6243].
If the "basic-mode" is set to "trim" then the server MUST adhere to If the "basic-mode" is set to "trim" then the server MUST adhere to
the defaults handling behavior defined in Section 2.2 of [RFC6243]. the defaults handling behavior defined in Section 2.2 of [RFC6243].
If the "basic-mode" is set to "explicit" then the server MUST adhere If the "basic-mode" is set to "explicit" then the server MUST adhere
to the defaults handling behavior defined in Section 2.3 of to the defaults handling behavior defined in Section 2.3 of
[RFC6243]. [RFC6243].
Example: (split for display purposes only) Example: (split for display purposes only)
urn:ietf:params:restconf:capability:defaults:1.0? urn:ietf:params:restconf:capability:defaults:1.0?
basic-mode=explicit basic-mode=explicit
9.2. restconf-state/streams 9.2. restconf-state/streams
This optional container provides access to the event notification This optional container provides access to the event streams
streams supported by the server. The server MAY omit this container supported by the server. The server MAY omit this container if no
if no event notification streams are supported. event streams are supported.
The server will populate this container with a stream list entry for The server will populate this container with a stream list entry for
each stream type it supports. Each stream contains a leaf called each stream type it supports. Each stream contains a leaf called
"events" which contains a URI that represents an event stream "events" which contains a URI that represents an event stream
resource. resource.
Stream resources are defined in Section 3.8. Notifications are Stream resources are defined in Section 3.8. Notifications are
defined in Section 6. defined in Section 6.
9.3. RESTCONF Monitoring Module 9.3. RESTCONF Monitoring Module
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-07-07.yang" <CODE BEGINS> file "ietf-restconf-monitoring@2016-08-15.yang"
module ietf-restconf-monitoring { module ietf-restconf-monitoring {
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring";
prefix "rcmon"; prefix "rcmon";
import ietf-yang-types { prefix yang; } import ietf-yang-types { prefix yang; }
import ietf-inet-types { prefix inet; } import ietf-inet-types { prefix inet; }
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
contact contact
"WG Web: <http://tools.ietf.org/wg/netconf/> "WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org> WG List: <mailto:netconf@ietf.org>
Editor: Andy Bierman Author: Andy Bierman
<mailto:andy@yumaworks.com> <mailto:andy@yumaworks.com>
Editor: Martin Bjorklund Author: Martin Bjorklund
<mailto:mbj@tail-f.com> <mailto:mbj@tail-f.com>
Editor: Kent Watsen Author: Kent Watsen
<mailto:kwatsen@juniper.net>"; <mailto:kwatsen@juniper.net>";
description description
"This module contains monitoring information for the "This module contains monitoring information for the
RESTCONF protocol. RESTCONF protocol.
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
skipping to change at page 76, line 39 skipping to change at page 81, line 9
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from draft-ietf-netconf-restconf-15.txt // Note: extracted from draft-ietf-netconf-restconf-16.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-07-07 { revision 2016-08-15 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
container restconf-state { container restconf-state {
config false; config false;
description description
"Contains RESTCONF protocol monitoring information."; "Contains RESTCONF protocol monitoring information.";
skipping to change at page 77, line 34 skipping to change at page 82, line 4
key name; key name;
description description
"Each entry describes an event stream supported by "Each entry describes an event stream supported by
the server."; the server.";
leaf name { leaf name {
type string; type string;
description "The stream name"; description "The stream name";
reference "RFC 5277, Section 3.4, <name> element."; reference "RFC 5277, Section 3.4, <name> element.";
} }
leaf description { leaf description {
type string; type string;
description "Description of stream content"; description "Description of stream content";
reference reference
"RFC 5277, Section 3.4, <description> element."; "RFC 5277, Section 3.4, <description> element.";
} }
leaf replay-support { leaf replay-support {
type boolean; type boolean;
default false;
description description
"Indicates if replay buffer supported for this stream. "Indicates if replay buffer supported for this stream.
If 'true', then the server MUST support the 'start-time' If 'true', then the server MUST support the 'start-time'
and 'stop-time' query parameters for this stream."; and 'stop-time' query parameters for this stream.";
reference reference
"RFC 5277, Section 3.4, <replaySupport> element."; "RFC 5277, Section 3.4, <replaySupport> element.";
} }
leaf replay-log-creation-time { leaf replay-log-creation-time {
when "../replay-support" { when "../replay-support" {
description description
"Only present if notification replay is supported"; "Only present if notification replay is supported";
} }
type yang:date-and-time; type yang:date-and-time;
description description
"Indicates the time the replay log for this stream "Indicates the time the replay log for this stream
was created."; was created.";
reference reference
skipping to change at page 79, line 4 skipping to change at page 83, line 22
"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.";
} }
} }
} }
} }
} }
} }
<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 [RFC7895] provides
[I-D.ietf-netconf-yang-library] provides information about the YANG information about the YANG modules and submodules used by the
modules and submodules used by the RESTCONF server. Implementation RESTCONF server. Implementation is mandatory for RESTCONF servers.
is mandatory for RESTCONF servers. All YANG modules and submodules All YANG modules and submodules used by the server MUST be identified
used by the server MUST be identified in the YANG module library. in the YANG module library.
10.1. modules-state
This mandatory container holds the identifiers for the YANG data
model modules supported by the server.
10.1.1. modules-state/module 10.1. modules-state/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 [RFC7895].
11. IANA Considerations Note that there are no protocol accessible objects in the
"ietf-restconf" module to implement, but it is possible that a server
will list the "ietf-restconf" module in the YANG library if it is
imported (directly or indirectly) by an implemented module.
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.
skipping to change at page 80, line 36 skipping to change at page 85, line 7
reference: RFCXXXX reference: RFCXXXX
name: ietf-restconf-monitoring name: ietf-restconf-monitoring
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
prefix: rcmon prefix: rcmon
// RFC Ed.: replace XXXX with RFC number and remove this note // RFC Ed.: replace XXXX with RFC number and remove this note
reference: RFCXXXX reference: RFCXXXX
11.3. Media Types 11.3. Media Types
11.3.1. Media Type application/yang-data 11.3.1. Media Type application/yang-data-xml
Type name: application Type name: application
Subtype name: yang-data Subtype name: yang-data
Required parameters: None Required parameters: None
Optional parameters: None Optional parameters: None
// RFC Ed.: replace draft-ietf-netmod-rfc6020bis with // RFC Ed.: replace draft-ietf-netmod-rfc6020bis with
skipping to change at page 84, line 7 skipping to change at page 88, line 22
Author: See Authors' Addresses section of [RFCXXXX]. Author: See Authors' Addresses section of [RFCXXXX].
Change controller: Internet Engineering Task Force Change controller: Internet Engineering Task Force
(mailto:iesg&ietf.org). (mailto:iesg&ietf.org).
Provisional registration? (standards tree only): no Provisional registration? (standards tree only): no
11.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 o the name of the RESTCONF capability. By convention, this name
begins with the colon ':' character. begins with the colon ':' character.
o the URN for the RESTCONF capability. o the URN for the RESTCONF capability.
skipping to change at page 85, line 4 skipping to change at page 89, line 33
:with-defaults :with-defaults
urn:ietf:params:restconf:capability:with-defaults:1.0 urn:ietf:params:restconf:capability:with-defaults:1.0
12. Security Considerations 12. Security Considerations
The "ietf-restconf-monitoring" YANG module defined in this memo is The "ietf-restconf-monitoring" YANG module defined in this memo is
designed to be accessed via the NETCONF protocol [RFC6241]. The designed to be accessed via the NETCONF protocol [RFC6241]. The
lowest NETCONF layer is the secure transport layer, and the lowest NETCONF layer is the secure transport layer, and the
mandatory-to-implement secure transport is Secure Shell (SSH) mandatory-to-implement secure transport is Secure Shell (SSH)
[RFC6242]. The NETCONF access control model [RFC6536] provides the [RFC6242]. The NETCONF access control model [RFC6536] provides the
means to restrict access for particular NETCONF users to a pre- means to restrict access for particular NETCONF users to a pre-
configured subset of all available NETCONF protocol operations and configured subset of all available NETCONF protocol operations and
content. content.
The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement
secure transport is TLS [RFC5246]. The RESTCONF protocol uses the
NETCONF access control model [RFC6536], which provides the means to
restrict access for particular RESTCONF users to a preconfigured
subset of all available RESTCONF 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, except the
YANG-defined content manipulated by RESTCONF can be found in the "ietf-restconf-monitoring" module. Security considerations for the
documents defining those YANG modules. other modules manipulated by RESTCONF can be found in the 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
used whenever a client accesses a protected resource. Client used whenever a client accesses a protected resource. Client
authentication MUST be implemented using client certificates or MUST authentication MUST be implemented using client certificates or MUST
be implemented using an HTTP authentication scheme. Client be implemented using an HTTP authentication scheme. Client
authorization MAY be configured using the NETCONF Access Control authorization MAY be configured using the NETCONF Access Control
Model (NACM) [RFC6536]. Model (NACM) [RFC6536].
Configuration information is by its very nature sensitive. Its Configuration information is by its very nature sensitive. Its
transmission in the clear and without integrity checking leaves transmission in the clear and without integrity checking leaves
devices open to classic eavesdropping and false data injection devices open to classic eavesdropping and false data injection
attacks. Configuration information often contains passwords, user attacks. Configuration information often contains passwords, user
names, service descriptions, and topological information, all of names, service descriptions, and topological information, all of
which are sensitive. Because of this, this protocol SHOULD be which are sensitive. There are many patterns of attack that have
implemented carefully with adequate attention to all manner of attack been observed through operational practice with existing management
one might expect to experience with other management interfaces. interfaces. It would be wise for implementers to research them, and
take them into account when implementing this protocol.
Different environments may well allow different rights prior to and Different environments may well allow different rights prior to and
then after authentication. When an operation is not properly then after authentication. When a RESTCONF operation is not properly
authorized, the RESTCONF server MUST return a "401 Unauthorized" authorized, the RESTCONF server MUST return a "401 Unauthorized"
status-line. Note that authorization information can be exchanged in status-line. Note that authorization information can be exchanged in
the form of configuration information, which is all the more reason the form of configuration information, which is all the more reason
to ensure the security of the connection. Note that it is possible to ensure the security of the connection. Note that it is possible
for a client to detect configuration changes in data resources it is for a client to detect configuration changes in data resources it is
not authorized to access by monitoring changes in the ETag and Last- not authorized to access by monitoring changes in the ETag and Last-
Modified header fields returned by the server for the datastore Modified header fields returned by the server for the datastore
resource. resource.
A RESTCONF server implementation SHOULD attempt to prevent system
disruption due to excessive resource consumption required to fulfill
edit requests via the POST, PUT, and PATCH methods. It may be
possible to construct an attack on such a RESTCONF server, which
attempts to consume all available memory or other resource types.
13. Acknowledgements 13. Acknowledgements
The authors would like to thank the following people for their The authors would like to thank the following people for their
contributions to this document: Ladislav Lhotka, Juergen contributions to this document: Ladislav Lhotka, Juergen
Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford.
The authors would like to thank the following people for their The authors would like to thank the following people for their
excellent technical reviews of this document: Mehmet Ersue, Mahesh excellent technical reviews of this document: Mehmet Ersue, Mahesh
Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka, Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka,
Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint
Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise, and Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise,
Dale Worley. Dale Worley, and Lionel Morand.
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 United States Army, Space & Terrestrial supported by the United States Army, Space & Terrestrial
Communications Directorate (S&TCD) under Contract No. Communications Directorate (S&TCD) under Contract No. W15P7T-
W15P7T-13-C-A616. Any opinions, findings and conclusions or 13-C-A616. Any opinions, findings and conclusions or recommendations
recommendations expressed in this material are those of the author(s) expressed in this material are those of the author(s) and do not
and do not necessarily reflect the views of The Space & Terrestrial necessarily reflect the views of The Space & Terrestrial
Communications Directorate (S&TCD). Communications Directorate (S&TCD).
14. References 14. References
14.1. Normative References 14.1. Normative References
[I-D.ietf-netconf-yang-library]
Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
Library", draft-ietf-netconf-yang-library-06 (work in
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-14 (work in progress), June draft-ietf-netmod-rfc6020bis-14 (work in progress), June
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-10 (work in progress), March draft-ietf-netmod-yang-json-10 (work in progress), March
2016. 2016.
skipping to change at page 87, line 6 skipping to change at page 91, line 43
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.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66,
3986, January 2005. RFC 3986, January 2005.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
Notifications", RFC 5277, July 2008. Notifications", RFC 5277, July 2008.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and T. Polk, "Internet X.509 Public Key Housley, R., and T. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008. (CRL) Profile", RFC 5280, May 2008.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
5789, March 2010. RFC 5789, March 2010.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020, Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010. October 2010.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509 within Internet Public Key Infrastructure Using X.509
skipping to change at page 87, line 46 skipping to change at page 92, line 36
and A. Bierman, Ed., "Network Configuration Protocol and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, June 2011. (NETCONF)", RFC 6241, June 2011.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<http://www.rfc-editor.org/info/rfc6242>. <http://www.rfc-editor.org/info/rfc6242>.
[RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for
NETCONF", RFC 6243, June 2011. NETCONF", RFC 6243, June 2011.
[RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata",
6415, October 2011. RFC 6415, October 2011.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536, March Protocol (NETCONF) Access Control Model", RFC 6536, March
2012. 2012.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, March 2012. and D. Orchard, "URI Template", RFC 6570, March 2012.
[RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991,
July 2013. July 2013.
skipping to change at page 88, line 28 skipping to change at page 93, line 18
[RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", RFC 7231, June 2014. (HTTP/1.1): Semantics and Content", RFC 7231, June 2014.
[RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Conditional Requests", RFC 7232, June 2014. (HTTP/1.1): Conditional Requests", RFC 7232, June 2014.
[RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Authentication", RFC 7235, June 2014. (HTTP/1.1): Authentication", RFC 7235, June 2014.
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190,
7320, July 2014. RFC 7320, July 2014.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
10.17487/RFC7540, May 2015, DOI 10.17487/RFC7540, May 2015,
<http://www.rfc-editor.org/info/rfc7540>. <http://www.rfc-editor.org/info/rfc7540>.
[RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the
NETCONF Protocol over Transport Layer Security (TLS) with NETCONF Protocol over Transport Layer Security (TLS) with
Mutual X.509 Authentication", RFC 7589, DOI 10.17487/ Mutual X.509 Authentication", RFC 7589,
RFC7589, June 2015, DOI 10.17487/RFC7589, June 2015,
<http://www.rfc-editor.org/info/rfc7589>. <http://www.rfc-editor.org/info/rfc7589>.
[RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
Library", RFC 7895, June 2016.
[W3C.REC-eventsource-20150203] [W3C.REC-eventsource-20150203]
Hickson, I., "Server-Sent Events", World Wide Web Hickson, I., "Server-Sent Events", World Wide Web
Consortium Recommendation REC-eventsource-20150203, Consortium Recommendation REC-eventsource-20150203,
February 2015, February 2015,
<http://www.w3.org/TR/2015/REC-eventsource-20150203>. <http://www.w3.org/TR/2015/REC-eventsource-20150203>.
[W3C.REC-html5-20141028]
Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", World
Wide Web Consortium Recommendation REC-html5-20141028,
October 2014,
<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.,
and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC- Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008, xml-20081126, November 2008,
<http://www.w3.org/TR/2008/REC-xml-20081126>. <http://www.w3.org/TR/2008/REC-xml-20081126>.
[XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Recommendation Version 1.0", World Wide Web Consortium Recommendation
REC-xpath-19991116, November 1999, REC-xpath-19991116, November 1999,
skipping to change at page 89, line 35 skipping to change at page 94, line 18
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-08 (work in Media Type", draft-ietf-netconf-yang-patch-08 (work in
progress), March 2016. 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. v14 to v15 A.1. v15 to v16
o changed media type application/yang-data to application/yang-data-
xml
o changed header to header field
o added linewrap convention in terminology and applied in many
examples
o clarified DELETE for leaf-list and list
o clarified URI format for lists without keys or duplicate leaf-
lists
o added 'yang-data extension' term and clarified 'YANG data
template' term
o clarified that the fragment component is not part of the request
URI, per HTTP
o clarified request URI "api-path" syntax
o clarified many examples
A.2. v14 to v15
o added text for HTTP/2 usage o added text for HTTP/2 usage
o changed media type definitions per review comments o changed media type definitions per review comments
o added some clarifications and typos o added some clarifications and typos
o added error-tag mapping for 406 and 412 errors o added error-tag mapping for 406 and 412 errors
A.2. v13 - v14 o added clarifications based on ops-dir review by Lionel Morand
o clarified PUT and POST differences for creating a data resource
o clarify PUT for a datastore resource
o added clarifications from Gen-Art review by Robert Sparks
o clarified terminology in many places
A.3. v13 - v14
This release addresses github issues #61, #62, #63, #65, #66, and This release addresses github issues #61, #62, #63, #65, #66, and
#67. #67.
o change term 'server' to 'NETCONF server' o change term 'server' to 'NETCONF server'
o add term 'RESTCONF server' also called 'server' o add term 'RESTCONF server' also called 'server'
o change term 'client' to 'NETCONF client' o change term 'client' to 'NETCONF client'
o add term 'RESTCONF client' also called 'client' o add term 'RESTCONF client' also called 'client'
skipping to change at page 91, line 34 skipping to change at page 97, line 4
o remove suggestion MAY send Pragma: no-cache in response o remove suggestion MAY send Pragma: no-cache in response
o remove table of HTTP status codes used in RESTCONF o remove table of HTTP status codes used in RESTCONF
o changed media type names so they conform to RFC 6838 o changed media type names so they conform to RFC 6838
o clarified too-big error-tag conversion o clarified too-big error-tag conversion
o update SSE reference o update SSE reference
o clarify leaf-list identifier encoding o clarify leaf-list identifier encoding
o removed all media types except yang-data o removed all media types except yang-data
o changed restconf-media-type extension to be more generic yang-data o changed restconf-media-type extension to be more generic yang-data
extension extension
A.3. v12 - v13 A.4. v12 - v13
o fix YANG library module examples (now called module-state) o fix YANG library module examples (now called module-state)
o fix terminology idnit issue o fix terminology idnit issue
o removed RFC 2818 reference (changed citation to RFC 7230) o removed RFC 2818 reference (changed citation to RFC 7230)
A.4. v11 - v12 A.5. v11 - v12
o clarify query parameter requirements o clarify query parameter requirements
o move filter query section to match table order in sec. 4.8 o move filter query section to match table order in sec. 4.8
o clarify that depth default is entire subtree for datastore o clarify that depth default is entire subtree for datastore
resource resource
o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml
o made implementation of timestamps optional since ETags are o made implementation of timestamps optional since ETags are
skipping to change at page 92, line 28 skipping to change at page 97, line 45
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.5. v10 - v11 A.6. v10 - v11
o change term 'operational data' to 'state data' o change term 'operational data' to 'state data'
o clarify :startup behavior o clarify :startup behavior
o clarify X.509 security text o clarify X.509 security text
o change '403 Forbidden' to '401 Unauthorized' for GET error o change '403 Forbidden' to '401 Unauthorized' for GET error
o clarify MUST have one "restconf" link relation o clarify MUST have one "restconf" link relation
o clarify that NV-storage is not mandatory o clarify that NV-storage is not mandatory
o clarify how "Last-Modified" and "ETag" header info can be used by o clarify how "Last-Modified" and "ETag" header info can be used by
a client a client
o clarify meaning of mandatory parameter o clarify meaning of mandatory parameter
skipping to change at page 93, line 9 skipping to change at page 98, line 24
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.6. v09 - v10 A.7. 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 95, line 11 skipping to change at page 100, line 23
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.7. v08 - v09 A.8. 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.8. v07 - v08 A.9. v07 - v08
o add support for YANG 1.1 action statement o add support for YANG 1.1 action statement
o changed mandatory encoding from XML to XML or JSON o changed mandatory encoding from XML to XML or JSON
o fix syntax in fields parameter definition o fix syntax in fields parameter definition
o add meta-data encoding examples for XML and JSON o add meta-data encoding examples for XML and JSON
o remove RFC 2396 references and update with 3986 o remove RFC 2396 references and update with 3986
skipping to change at page 95, line 39 skipping to change at page 101, line 4
o add support for YANG 1.1 action statement o add support for YANG 1.1 action statement
o changed mandatory encoding from XML to XML or JSON o changed mandatory encoding from XML to XML or JSON
o fix syntax in fields parameter definition o fix syntax in fields parameter definition
o add meta-data encoding examples for XML and JSON o add meta-data encoding examples for XML and JSON
o remove RFC 2396 references and update with 3986 o remove RFC 2396 references and update with 3986
o change encoding of a key so quoted string are not used, since they o change encoding of a key so quoted string are not used, since they
are already percent-encoded. A zero-length string is not encoded are already percent-encoded. A zero-length string is not encoded
(/list=foo,,baz) (/list=foo,,baz)
o Add example of percent-encoded key value o Add example of percent-encoded key value
A.9. v06 - v07 A.10. 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.10. v05 - v06 A.11. v05 - v06
o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug)
A.11. v04 - v05 A.12. v04 - v05
o changed term 'notification event' to 'event notification' o changed term 'notification event' to 'event notification'
o removed intro text about framework and meta-model o removed intro text about framework and meta-model
o removed early mention of API resources o removed early mention of API resources
o removed term unified datastore and cleaned up text about NETCONF o removed term unified datastore and cleaned up text about NETCONF
datastores datastores
skipping to change at page 97, line 5 skipping to change at page 102, line 17
o renamed stream/encoding/events to stream/access/location o renamed stream/encoding/events to stream/access/location
o changed XPath from informative to normative reference o changed XPath from informative to normative reference
o changed rest-dissertation from normative to informative reference o changed rest-dissertation from normative to informative reference
o changed example-jukebox playlist 'id' from a data-resource- o changed example-jukebox playlist 'id' from a data-resource-
identifier to a leafref pointing at the song name identifier to a leafref pointing at the song name
A.12. v03 - v04 A.13. 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 97, line 40 skipping to change at page 103, line 5
o changed lock-denied error example o changed lock-denied error example
o added with-defaults query parameter example o added with-defaults query parameter example
o added term "RESTCONF Capability" o added term "RESTCONF Capability"
o changed NETCONF Capability URI registry usage to new RESTCONF o changed NETCONF Capability URI registry usage to new RESTCONF
Capability URI Registry usage Capability URI Registry usage
A.13. v02 - v03 A.14. 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 98, line 4 skipping to change at page 103, line 17
o added collection resource o added collection resource
o added "page" query parameter capability o added "page" query parameter capability
o added "limit" and "offset" query parameters, which are available o added "limit" and "offset" query parameters, which are available
if the "page" capability is supported if the "page" capability is supported
o added "stream list" term o added "stream list" term
o fixed bugs in some examples o fixed bugs in some examples
o added "encoding" list within the "stream" list to allow different o added "encoding" list within the "stream" list to allow different
<events> URLs for XML and JSON encoding. <events> URLs for XML and JSON encoding.
o made XML MUST implement and JSON MAY implement for servers o made XML MUST implement and JSON MAY implement for servers
o re-add JSON notification examples (previously removed) o re-add JSON notification examples (previously removed)
o updated JSON references o updated JSON references
A.14. v01 - v02 A.15. v01 - v02
o moved query parameter definitions from the YANG module back to the o moved query parameter definitions from the YANG module back to the
plain text sections plain text sections
o made all query parameters optional to implement o made all query parameters optional to implement
o defined query parameter capability URI o defined query parameter capability URI
o moved 'streams' to new YANG module (ietf-restconf-monitoring) o moved 'streams' to new YANG module (ietf-restconf-monitoring)
skipping to change at page 99, line 5 skipping to change at page 104, line 16
information is no longer in this resource information is no longer in this resource
o closed issue #1 'select parameter' since no objections to the o closed issue #1 'select parameter' since no objections to the
proposed syntax proposed syntax
o closed "encoding of list keys" issue since no objection to new o closed "encoding of list keys" issue since no objection to new
encoding of list keys in a target resource URI. encoding of list keys in a target resource URI.
o moved open issues list to the issue tracker on github o moved open issues list to the issue tracker on github
A.15. v00 - v01 A.16. 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 99, line 42 skipping to change at page 105, line 4
o closed open issue '_self links for HATEOAS support'. It was o closed open issue '_self links for HATEOAS support'. It was
decided that they are redundant because they can be derived from decided that they are redundant because they can be derived from
the YANG module for the specific data. the YANG module for the specific data.
o added explanatory text for the 'select' parameter. o added explanatory text for the 'select' parameter.
o added RESTCONF Path Resolution section for discovering the root of o added RESTCONF Path Resolution section for discovering the root of
the RESTCONF API using the /.well-known/host-meta. the RESTCONF API using the /.well-known/host-meta.
o added an "error" media type to for structured error messages o added an "error" media type to for structured error messages
o added Secure Transport section requiring TLS o added Secure Transport section requiring TLS
o added Security Considerations section o added Security Considerations section
o removed all references to "REST-like" o removed all references to "REST-like"
A.16. bierman:restconf-04 to ietf:restconf-00 A.17. bierman:restconf-04 to ietf:restconf-00
o updated open issues section o updated open issues section
Appendix B. Open Issues Appendix B. Open Issues
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
The RESTCONF issues are tracked on github.com: The RESTCONF issues are tracked on github.com:
https://github.com/netconf-wg/restconf/issues https://github.com/netconf-wg/restconf/issues
Appendix C. Example YANG Module Appendix C. Example YANG Module
The example YANG module used in this document represents a simple The example YANG module used in this document represents a simple
media jukebox interface. media jukebox interface.
YANG Tree Diagram for "example-jukebox" Module YANG Tree Diagram for "example-jukebox" Module
+--rw jukebox!
+--rw library
| +--rw artist* [name]
| | +--rw name string
| | +--rw album* [name]
| | +--rw name string
| | +--rw genre? identityref
| | +--rw year? uint16
| | +--rw admin
| | | +--rw label? string
| | | +--rw catalogue-number? string
| | +--rw song* [name]
| | +--rw name string
| | +--rw location string
| | +--rw format? string
| | +--rw length? uint32
| +--ro artist-count? uint32
| +--ro album-count? uint32
| +--ro song-count? uint32
+--rw playlist* [name]
| +--rw name string
| +--rw description? string
| +--rw song* [index]
| +--rw index uint32
| +--rw id leafref
+--rw player
+--rw gap? decimal64
+--rw jukebox! rpcs:
+--rw library
| +--rw artist* [name]
| | +--rw name string
| | +--rw album* [name]
| | +--rw name string
| | +--rw genre? identityref
| | +--rw year? uint16
| | +--rw admin
| | | +--rw label? string
| | | +--rw catalogue-number? string
| | +--rw song* [name]
| | +--rw name string
| | +--rw location string
| | +--rw format? string
| | +--rw length? uint32
| +--ro artist-count? uint32
| +--ro album-count? uint32
| +--ro song-count? uint32
+--rw playlist* [name]
| +--rw name string
| +--rw description? string
| +--rw song* [index]
| +--rw index uint32
| +--rw id leafref
+--rw player
+--rw gap? decimal64
rpcs:
+---x play +---x play
+--ro input +--ro input
+--ro playlist string +--ro playlist string
+--ro song-number uint32 +--ro song-number uint32
C.1. example-jukebox YANG Module C.1. example-jukebox YANG Module
module example-jukebox { module example-jukebox {
namespace "http://example.com/ns/example-jukebox"; namespace "http://example.com/ns/example-jukebox";
prefix "jbox"; prefix "jbox";
organization "Example, Inc."; organization "Example, Inc.";
contact "support at example.com"; contact "support at example.com";
description "Example Jukebox Data Model Module"; description "Example Jukebox Data Model Module";
revision "2015-04-04" { revision "2016-08-15" {
description "Initial version."; description "Initial version.";
reference "example.com document 1-4673"; reference "example.com document 1-4673";
} }
identity genre { identity genre {
description "Base for all genre types"; description "Base for all genre types";
} }
// abbreviated list of genre classifications // abbreviated list of genre classifications
identity alternative { identity alternative {
base genre; base genre;
description "Alternative music"; description "Alternative music";
skipping to change at page 106, line 16 skipping to change at page 111, line 46
mandatory true; mandatory true;
description "Song number in playlist to play"; description "Song number in playlist to play";
} }
} }
} }
} }
Appendix D. RESTCONF Message Examples Appendix D. RESTCONF Message Examples
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 "ietf-restconf" defined in Section 8 and the non-normative example
defined in Appendix C.1. YANG module "example-jukebox" 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 starts by retrieving the RESTCONF entry point: The client starts by retrieving the RESTCONF root resource:
GET /.well-known/host-meta HTTP/1.1 GET /.well-known/host-meta HTTP/1.1
Host: example.com Host: example.com
Accept: application/xrd+xml Accept: application/xrd+xml
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/xrd+xml Content-Type: application/xrd+xml
Content-Length: nnn Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'> <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/> <Link rel='restconf' href='/restconf'/>
</XRD> </XRD>
The client may then retrieve the top-level API resource, using the The client may then retrieve the top-level API resource, using the
entry point "/restconf". root resource "/restconf".
GET /restconf HTTP/1.1 GET /restconf 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 (2016-04-09) for ietf-yang-library [RFC Editor Note: Adjust the date (2016-04-09) for ietf-yang-library
below to the date in the published ietf-yang-library YANG module, and below to the date in the published ietf-yang-library YANG module, and
remove this 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 2016 17:01:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+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-06-21"
} }
} }
To request that the response content to be encoded in XML, the To request that the response content to be encoded in XML, the
"Accept" header can be used, as in this example request: "Accept" header can be used, as in this example request:
GET /restconf HTTP/1.1 GET /restconf HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data Accept: application/yang-data-xml
The server will return the same response either way, which might be The server will return the same conceptual data either way, which
as follows : might be as follows :
[RFC Editor Note: Adjust the date for ietf-yang-library below to the [RFC Editor Note: Adjust the date for ietf-yang-library below to the
date in the published ietf-yang-library YANG module, and remove this date in the published ietf-yang-library YANG module, and remove this
note.] note.]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2016 17:01:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Content-Type: application/yang-data Content-Type: application/yang-data-xml
<restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<data/> <data/>
<operations/> <operations/>
<yang-library-version>2016-04-09</yang-library-version> <yang-library-version>2016-06-21</yang-library-version>
</restconf> </restconf>
D.1.2. Retrieve The Server Module Information D.1.2. Retrieve The Server Module Information
It is possible the YANG library module will change over time. The It is possible the YANG library module will change over time. The
client can retrieve the revision date of the ietf-yang-library client can retrieve the revision date of the ietf-yang-library
supported by the server from the API resource, as described in the supported by the server from the API resource, as described in the
previous section. 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:
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 2016 17:01:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT Last-Modified: Sun, 22 Apr 2016 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" : [ "deviation" : [
{ {
"name" : "foo-dev", "name" : "foo-dev",
"revision" "2012-02-16" "revision" "2012-02-16"
} }
], ],
"conformance-type" : "implement" "conformance-type" : "implement"
}, },
{ {
"name" : "ietf-yang-library", "name" : "ietf-yang-library",
"revision" : "2016-04-09", "revision" : "2016-06-21",
"schema" : "https://example.com/modules/ietf-yang- "schema" : "https://example.com/modules/\
library/2016-04-09", ietf-yang-library/2016-06-21",
"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"
}, },
{ {
"name" : "foo-types", "name" : "foo-types",
"revision" : "2012-01-05", "revision" : "2012-01-05",
"schema" : "schema" :
"https://example.com/modules/foo-types/2012-01-05", "https://example.com/modules/foo-types/2012-01-05",
"namespace" : "http://example.com/ns/foo-types", "namespace" : "http://example.com/ns/foo-types",
skipping to change at page 110, line 5 skipping to change at page 115, 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 Accept: application/yang-data-xml
The server might respond as follows. The extra whitespace in The server might respond as follows:
'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 2016 17:02:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT Last-Modified: Sun, 22 Apr 2016 01:00:14 GMT
Content-Type: application/yang-data Content-Type: application/yang-data-xml
<capabilities <capabilities
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<capability> <capability>\
urn:ietf:params:restconf:capability:defaults:1.0? urn:ietf:params:restconf:capability:defaults:1.0?\
basic-mode=explicit basic-mode=explicit\
</capability> </capability>
<capability> <capability>\
urn:ietf:params:restconf:capability:with-defaults:1.0 urn:ietf:params:restconf:capability:with-defaults:1.0\
</capability> </capability>
<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>\
urn:ietf:params:restconf:capability:start-time:1.0 urn:ietf:params:restconf:capability:start-time:1.0\
</capability> </capability>
<capability> <capability>\
urn:ietf:params:restconf:capability:stop-time:1.0 urn:ietf:params:restconf:capability:stop-time:1.0\
</capability> </capability>
<capability> <capability>\
http://example.com/capabilities/myparam http://example.com/capabilities/myparam\
</capability> </capability>
</capabilities> </capabilities>
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
only:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2012 17:02:00 GMT Date: Mon, 23 Apr 2016 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 2016 17:02:00 GMT
ETag: "b3830f23a4c" ETag: "b3830f23a4c"
To create a new "album" resource for this artist within the "jukebox" To create a new "album" resource for this artist within the "jukebox"
resource, the client might send the following request. Note that the resource, the client might send the following request:
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 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
only:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2012 17:03:00 GMT Date: Mon, 23 Apr 2016 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 2016 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 datastore last-changed In this example, the server just supports the datastore last-changed
timestamp. The client has previously retrieved the "Last-Modified" timestamp. After the previous request, the client has cached the
header and has some value cached to provide in the following request "Last-Modified" header and the Location header from the response to
to patch an "album" list entry with key value "Wasting Light". Only provide in the following request to patch an "album" list entry with
the "genre" field is being updated. key value "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/\
HTTP/1.1 genre 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 2016 17:03: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 2016 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 2016 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, assume there is a top-level data resource named
sending a PATCH to the datastore resource: "system" from the example-system module, and this container has a
child leaf called "enable-jukebox-streaming":
PATCH /restconf/data HTTP/1.1 container system {
Host: example.com leaf enable-jukebox-streaming {
Content-Type: application/yang-data type boolean;
}
}
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> In this example PATCH is used by the client to modify 2 top-level
<jukebox xmlns="http://example.com/ns/example-jukebox"> resources at once, in order to enable jukebox streaming and add an
<library> "album" sub-resource to eachof 2 "artist" resources:
<artist>
<name>Foo Fighters</name>
<album>
<name>Wasting Light</name>
<year>2011</year>
</album> PATCH /restconf/data HTTP/1.1
</artist> Host: example.com
<artist> Content-Type: application/yang-data-xml
<name>Nick Cave and the Bad Seeds</name>
<album> <data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<name>Tender Prey</name> <system xmlns="http://example.com/ns/example-system">
<year>1988</year> <enable-jukebox-streaming>true</enable-jukebox-streaming>
</album> </system>
</artist> <jukebox xmlns="http://example.com/ns/example-jukebox">
</library> <library>
</jukebox> <artist>
</data> <name>Foo Fighters</name>
<album>
<name>One by One</name>
<year>2012</year>
</album>
</artist>
<artist>
<name>Nick Cave and the Bad Seeds</name>
<album>
<name>Tender Prey</name>
<year>1988</year>
</album>
</artist>
</library>
</jukebox>
</data>
D.2.4. Edit a Data Resource D.2.4. Edit a Data Resource
In this example, the client modifies one data nodes by sending a In this example, the client modifies one data node by adding an
PATCH to the data resource (URI wrapped for display purposes only): "album" sub-resource by sending a PATCH for the data resource:
PATCH /restconf/data/example-jukebox:jukebox/library/ PATCH /restconf/data/example-jukebox:jukebox/library/\
artist=Nick%20Cave%20and%20the%Bad%20Seeds HTTP/1.1 artist=Nick%20Cave%20and%20the%Bad%20Seeds HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data Content-Type: application/yang-data-xml
<artist xmlns="http://example.com/ns/example-jukebox"> <artist xmlns="http://example.com/ns/example-jukebox">
<name>Nick Cave and the Bad Seeds</name> <name>Nick Cave and the Bad Seeds</name>
<album> <album>
<name>The Good Son</name> <name>The Good Son</name>
<year>1990</year> <year>1990</year>
</album> </album>
</artist> </artist>
D.3. Query Parameter Examples D.3. Query Parameter Examples
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.
container events container events
list event { list event {
key name; key name;
leaf name { type string; } leaf name { type string; }
leaf description { type string; } leaf description { type string; }
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", or omitted, since this is the default value. The client to "all", or omitted, since this is the default value. The client
might send: might send:
GET /restconf/data/example-events:events?content=all GET /restconf/data/example-events:events?\
HTTP/1.1 content=all 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 2016 17:11:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: 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",
skipping to change at page 115, line 5 skipping to change at page 121, line 35
} }
} }
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". Note that the "ETag" and parameter is set to "config". Note that the "ETag" and
"Last-Modified" headers are only returned if the content parameter "Last-Modified" headers are only 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?\
HTTP/1.1 content=config 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 2016 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 2016 13:01:20 GMT
ETag: "eeeada438af" ETag: "eeeada438af"
Cache-Control: no-cache Cache-Control: 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"
skipping to change at page 115, line 42 skipping to change at page 122, line 35
} }
} }
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?\
HTTP/1.1 content=nonconfig 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 2016 17:11:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: 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
skipping to change at page 116, line 38 skipping to change at page 123, line 43
just the target resource level itself. A depth level of "2" includes just the target resource level itself. A depth level of "2" includes
the target resource level and its child nodes. the target resource level and its child nodes.
This example shows how different values of the "depth" parameter This example shows how different values of the "depth" parameter
would affect the reply content for retrieval of the top-level would affect the reply content for retrieval of the top-level
"jukebox" data resource. "jukebox" data resource.
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".
strings are wrapped for display purposes only.
GET /restconf/data/example-jukebox:jukebox?depth=unbounded GET /restconf/data/example-jukebox:jukebox?\
HTTP/1.1 depth=unbounded 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 2016 17:11:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: 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",
skipping to change at page 118, line 20 skipping to change at page 125, line 23
], ],
"player" : { "player" : {
"gap" : 0.5 "gap" : 0.5
} }
} }
} }
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