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 |