draft-ietf-netconf-restconf-01.txt | draft-ietf-netconf-restconf-02.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 4, 2015 Tail-f Systems | Expires: April 11, 2015 Tail-f Systems | |||
K. Watsen | K. Watsen | |||
Juniper Networks | Juniper Networks | |||
R. Fernando | October 8, 2014 | |||
Cisco | ||||
July 3, 2014 | ||||
RESTCONF Protocol | RESTCONF Protocol | |||
draft-ietf-netconf-restconf-01 | draft-ietf-netconf-restconf-02 | |||
Abstract | Abstract | |||
This document describes an HTTP-based protocol that provides a | This document describes an HTTP-based protocol that provides a | |||
programmatic interface for accessing data defined in YANG, using the | programmatic interface for accessing data defined in YANG, using the | |||
datastores defined in NETCONF. | datastores defined in NETCONF. | |||
Status of this Memo | Status of This Memo | |||
This Internet-Draft is submitted in full conformance with the | This Internet-Draft is submitted in full conformance with the | |||
provisions of BCP 78 and BCP 79. | provisions of BCP 78 and BCP 79. | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
Drafts is at http://datatracker.ietf.org/drafts/current/. | Drafts is at http://datatracker.ietf.org/drafts/current/. | |||
Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
This Internet-Draft will expire on January 4, 2015. | This Internet-Draft will expire on April 11, 2015. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2014 IETF Trust and the persons identified as the | Copyright (c) 2014 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
(http://trustee.ietf.org/license-info) in effect on the date of | (http://trustee.ietf.org/license-info) in effect on the date of | |||
publication of this document. Please review these documents | publication of this document. Please review these documents | |||
carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
described in the Simplified BSD License. | described in the Simplified BSD License. | |||
Table of Contents | Table of Contents | |||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
1.1. Secure Transport . . . . . . . . . . . . . . . . . . . . . 5 | 1.1. Secure Transport . . . . . . . . . . . . . . . . . . . . 5 | |||
1.2. Simple Subset of NETCONF Functionality . . . . . . . . . . 5 | 1.2. Simple Subset of NETCONF Functionality . . . . . . . . . 5 | |||
1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 6 | 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 6 | |||
1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 | 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
1.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 8 | 1.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
1.4.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . 8 | 1.4.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
1.4.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 9 | 1.4.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
1.4.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 10 | 1.4.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 9 | |||
1.4.5. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 11 | 1.4.5. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10 | |||
2. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 12 | 2. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 11 | |||
2.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 12 | 2.1. RESTCONF Resource Types . . . . . . . . . . . . . . . . . 11 | |||
2.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 | 2.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 12 | |||
2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 | 2.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 12 | |||
2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 | 2.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 13 | |||
2.4.1. Create Resource Mode . . . . . . . . . . . . . . . . . 14 | 2.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 14 | |||
2.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 15 | 2.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 14 | |||
2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 | 2.4.1. Edit Collision Detection . . . . . . . . . . . . . . 14 | |||
2.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 17 | 2.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 15 | |||
2.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 18 | 2.5.1. Encoding YANG Instance Identifiers in the Request URI 16 | |||
2.8. Query Parameters . . . . . . . . . . . . . . . . . . . . . 19 | 2.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 18 | |||
3. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 | 2.6. Operation Resource . . . . . . . . . . . . . . . . . . . 19 | |||
3.1. Request URI Structure . . . . . . . . . . . . . . . . . . 21 | 2.6.1. Encoding Operation Input Parameters . . . . . . . . . 19 | |||
3.2. RESTCONF Path Resolution . . . . . . . . . . . . . . . . . 22 | 2.6.2. Encoding Operation Output Parameters . . . . . . . . 20 | |||
3.3. Message Headers . . . . . . . . . . . . . . . . . . . . . 23 | 2.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 21 | |||
3.4. Message Encoding . . . . . . . . . . . . . . . . . . . . . 24 | 2.8. Stream Resource . . . . . . . . . . . . . . . . . . . . . 22 | |||
3.5. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . . 25 | 2.9. Errors Resource . . . . . . . . . . . . . . . . . . . . . 23 | |||
3.6. Return Status . . . . . . . . . . . . . . . . . . . . . . 25 | 3. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 23 | |||
3.7. Message Caching . . . . . . . . . . . . . . . . . . . . . 25 | 3.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
4. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 26 | 3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
4.1. RESTCONF Resource Types . . . . . . . . . . . . . . . . . 26 | 3.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
4.2. Resource Discovery . . . . . . . . . . . . . . . . . . . . 27 | 3.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 25 | |||
4.3. API Resource . . . . . . . . . . . . . . . . . . . . . . . 27 | 3.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 26 | |||
4.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . . 28 | 3.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 26 | |||
4.3.2. {+restconf}/modules . . . . . . . . . . . . . . . . . 29 | 3.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 | |||
4.3.3. {+restconf}/operations . . . . . . . . . . . . . . . . 30 | 3.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
4.3.4. {+restconf}/streams . . . . . . . . . . . . . . . . . 30 | 3.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
4.4. Datastore Resource . . . . . . . . . . . . . . . . . . . . 30 | 3.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 30 | |||
4.4.1. Edit Collision Detection . . . . . . . . . . . . . . . 31 | 3.8.1. Query Parameter URIs . . . . . . . . . . . . . . . . 31 | |||
4.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 31 | 3.8.2. The "content" Query Parameter . . . . . . . . . . . . 32 | |||
4.5.1. Encoding YANG Instance Identifiers in the Request | 3.8.3. The "depth" Query Parameter . . . . . . . . . . . . . 32 | |||
URI . . . . . . . . . . . . . . . . . . . . . . . . . 32 | 3.8.4. The "select" Query Parameter . . . . . . . . . . . . 33 | |||
4.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 34 | 3.8.5. The "insert" Query Parameter . . . . . . . . . . . . 34 | |||
4.6. Operation Resource . . . . . . . . . . . . . . . . . . . . 35 | 3.8.6. The "point" Query Parameter . . . . . . . . . . . . . 34 | |||
4.6.1. Encoding Operation Input Parameters . . . . . . . . . 35 | 3.8.7. The "filter" Query Parameter . . . . . . . . . . . . 35 | |||
4.6.2. Encoding Operation Output Parameters . . . . . . . . . 36 | 3.8.8. The "start-time" Query Parameter . . . . . . . . . . 36 | |||
4.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 37 | 3.8.9. The "stop-time" Query Parameter . . . . . . . . . . . 36 | |||
4.8. Stream Resource . . . . . . . . . . . . . . . . . . . . . 38 | 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 37 | |||
4.9. Errors Resource . . . . . . . . . . . . . . . . . . . . . 38 | 4.1. Request URI Structure . . . . . . . . . . . . . . . . . . 37 | |||
5. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 39 | 4.2. RESTCONF Path Resolution . . . . . . . . . . . . . . . . 38 | |||
5.1. Server Support . . . . . . . . . . . . . . . . . . . . . . 39 | 4.3. Message Headers . . . . . . . . . . . . . . . . . . . . . 39 | |||
5.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 39 | 4.4. Message Encoding . . . . . . . . . . . . . . . . . . . . 40 | |||
5.3. Subscribing to Receive Notifications . . . . . . . . . . . 40 | 4.5. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 41 | |||
5.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . . 41 | 4.6. Return Status . . . . . . . . . . . . . . . . . . . . . . 41 | |||
5.4. Receiving Event Notifications . . . . . . . . . . . . . . 41 | 4.7. Message Caching . . . . . . . . . . . . . . . . . . . . . 41 | |||
6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 43 | 5. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 42 | |||
6.1. Error Response Message . . . . . . . . . . . . . . . . . . 44 | 5.1. Server Support . . . . . . . . . . . . . . . . . . . . . 42 | |||
7. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 47 | 5.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 42 | |||
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 61 | 5.3. Subscribing to Receive Notifications . . . . . . . . . . 43 | |||
8.1. The "restconf" Relation Type . . . . . . . . . . . . . . . 61 | 5.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 44 | |||
8.2. YANG Module Registry . . . . . . . . . . . . . . . . . . . 61 | 5.4. Receiving Event Notifications . . . . . . . . . . . . . . 45 | |||
8.3. application/yang Media Sub Types . . . . . . . . . . . . . 61 | 6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 46 | |||
9. Security Considerations . . . . . . . . . . . . . . . . . . . 63 | 6.1. Error Response Message . . . . . . . . . . . . . . . . . 48 | |||
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 64 | 7. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 50 | |||
10.1. Normative References . . . . . . . . . . . . . . . . . . . 64 | 8. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 56 | |||
10.2. Informative References . . . . . . . . . . . . . . . . . . 65 | 8.1. restconf-state/capabilities . . . . . . . . . . . . . . . 56 | |||
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 66 | 8.2. restconf-state/streams . . . . . . . . . . . . . . . . . 57 | |||
A.1. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 66 | 8.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 57 | |||
A.2. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 67 | 9. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 60 | |||
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 68 | 9.1. modules . . . . . . . . . . . . . . . . . . . . . . . . . 61 | |||
B.1. select parameter . . . . . . . . . . . . . . . . . . . . . 68 | 9.1.1. modules/module . . . . . . . . . . . . . . . . . . . 61 | |||
B.2. netconf-state monitoring support . . . . . . . . . . . . . 68 | 9.2. YANG Library Module . . . . . . . . . . . . . . . . . . . 62 | |||
B.3. secure transport . . . . . . . . . . . . . . . . . . . . . 68 | 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 66 | |||
B.4. Encoding of key leafs in resource URIs . . . . . . . . . . 68 | 10.1. The "restconf" Relation Type . . . . . . . . . . . . . . 66 | |||
B.5. get-bulk query parameters . . . . . . . . . . . . . . . . 69 | 10.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 66 | |||
B.6. defaults handling . . . . . . . . . . . . . . . . . . . . 69 | 10.3. application/yang Media Sub Types . . . . . . . . . . . . 67 | |||
B.7. protocol capability URIs . . . . . . . . . . . . . . . . . 69 | 10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . 68 | |||
B.8. target resource list keys required for GET . . . . . . . . 70 | 11. Security Considerations . . . . . . . . . . . . . . . . . . . 68 | |||
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . . 71 | 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 69 | |||
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 71 | 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 69 | |||
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . . 77 | 13.1. Normative References . . . . . . . . . . . . . . . . . . 69 | |||
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 77 | 13.2. Informative References . . . . . . . . . . . . . . . . . 71 | |||
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 77 | Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 71 | |||
D.1.2. Retrieve The Server Module Information . . . . . . . . 79 | A.1. 01 - 02 . . . . . . . . . . . . . . . . . . . . . . . . . 71 | |||
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . . 81 | A.2. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 72 | |||
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 81 | A.3. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 73 | |||
D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 82 | Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 73 | |||
D.3. Query String Parameter Examples . . . . . . . . . . . . . 82 | Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 73 | |||
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 82 | C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 74 | |||
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 85 | Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 79 | |||
D.3.3. "filter" Parameter . . . . . . . . . . . . . . . . . . 88 | D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 80 | |||
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . . 89 | D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 80 | |||
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 90 | D.1.2. Retrieve The Server Module Information . . . . . . . 81 | |||
D.3.6. "select" Parameter . . . . . . . . . . . . . . . . . . 90 | D.1.3. Retrieve The Server Capability Information . . . . . 82 | |||
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . . 91 | D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 83 | |||
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 91 | D.2.1. Create New Data Resources . . . . . . . . . . . . . . 83 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 92 | D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 84 | |||
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 85 | ||||
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 85 | ||||
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 88 | ||||
D.3.3. "select" Parameter . . . . . . . . . . . . . . . . . 91 | ||||
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 92 | ||||
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 93 | ||||
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 93 | ||||
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 94 | ||||
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 94 | ||||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 94 | ||||
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, operational data, data-model specific | access the configuration data, operational data, data-model specific | |||
protocol operations, and notification events within a networking | protocol operations, and notification events within a networking | |||
device, in a modular and extensible manner. | device, in a modular and extensible manner. | |||
This document describes an HTTP [RFC2616] based protocol called | This document describes an HTTP [RFC2616] based protocol called | |||
RESTCONF, for accessing data defined in YANG [RFC6020], using | RESTCONF, for accessing data defined in YANG [RFC6020], using | |||
skipping to change at page 10, line 26 | skipping to change at page 9, line 43 | |||
can be data resources. YANG terminal nodes cannot contain child | can be data resources. YANG terminal nodes cannot contain child | |||
resources. | resources. | |||
o datastore resource: a resource with the media type "application/ | o datastore resource: a resource with the media type "application/ | |||
yang.datastore+xml" or "application/yang.datastore+json". | yang.datastore+xml" or "application/yang.datastore+json". | |||
Represents a configuration datastore. | Represents a configuration datastore. | |||
o edit operation: a RESTCONF operation on a data resource using the | o edit operation: a RESTCONF operation on a data resource using the | |||
POST, PUT, PATCH, or DELETE method. | POST, PUT, PATCH, or DELETE method. | |||
o event stream resource: a resource with the media type | o event stream resource: This resource represents an SSE (Server- | |||
"application/yang.stream+xml" or "application/yang.stream+json". | Sent Events) event stream. The content consists of text using the | |||
This resource represents an SSE (Server-Sent Events) event stream. | media type "text/event-stream", as defined by the HTML5 | |||
The content consists of text using the media type "text/ | specification. Each event represents one <notification> message | |||
event-stream", as defined by the HTML5 specification. Each event | generated by the server. It contains a conceptual system or data- | |||
represents one <notification> message generated by the server. It | model specific event that is delivered within a notification event | |||
contains a conceptual system or data-model specific event that is | stream. | |||
delivered within a notification event stream. | ||||
o operation: the conceptual RESTCONF operation for a message, | o operation: the conceptual RESTCONF operation for a message, | |||
derived from the HTTP method, request URI, headers, and message | derived from the HTTP method, request URI, headers, and message | |||
body. | body. | |||
o operation resource: a resource with the media type "application/ | o operation resource: a resource with the media type "application/ | |||
yang.operation+xml" or "application/yang.operation+json". | yang.operation+xml" or "application/yang.operation+json". | |||
o patch: a generic PATCH request on the target datastore or data | o patch: a generic PATCH request on the target datastore or data | |||
resource. The media type of the message body content will | resource. The media type of the message body content will | |||
skipping to change at page 12, line 5 | skipping to change at page 11, line 11 | |||
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. | |||
2. Operations | 2. Resources | |||
The RESTCONF protocol operates on a hierarchy of resources, starting | ||||
with the top-level API resource itself. Each resource represents a | ||||
manageable component within the device. | ||||
A resource can be considered a collection of conceptual data and the | ||||
set of allowed methods on that data. It can contain nested child | ||||
resources. The child resource types and methods allowed on them are | ||||
data-model specific. | ||||
A resource has its own media type identifier, represented by the | ||||
"Content-Type" header in the HTTP response message. A resource can | ||||
contain zero or more nested resources. A resource can be created and | ||||
deleted independently of its parent resource, as long as the parent | ||||
resource exists. | ||||
All RESTCONF resources are defined in this document except datastore | ||||
contents, protocol operations, and notification events. 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 | ||||
document. The set of YANG modules supported by the server will | ||||
determine the data model specific operations, top-level data node | ||||
resources, and notification event messages supported by the server. | ||||
The resources used in the RESTCONF protocol are identified by the | ||||
"path" component in the request URI. Each operation is performed on | ||||
a target resource. | ||||
2.1. RESTCONF Resource Types | ||||
The RESTCONF protocol defines a set of application specific media | ||||
types to identify each of the available resource types. The | ||||
following resource types are defined in RESTCONF: | ||||
+-----------+----------------------------+ | ||||
| Resource | Media Type | | ||||
+-----------+----------------------------+ | ||||
| API | application/yang.api | | ||||
| Datastore | application/yang.datastore | | ||||
| Data | application/yang.data | | ||||
| Errors | application/yang.errors | | ||||
| Operation | application/yang.operation | | ||||
| Schema | application/yang | | ||||
+-----------+----------------------------+ | ||||
RESTCONF Media Types | ||||
2.2. Resource Discovery | ||||
A client SHOULD start by retrieving the top-level API resource, using | ||||
the entry point URI defined in Section 4.2. | ||||
The RESTCONF protocol does not include a resource discovery | ||||
mechanism. Instead, the definitions within the YANG modules | ||||
advertised by the server are used to construct a predictable | ||||
operation or data resource identifier. | ||||
The "depth" query parameter (see Section 3.8.3) can be used to | ||||
control how many descendant levels should be included when retrieving | ||||
child resources. This parameter can be used with the GET method to | ||||
discover child resources within a particular resource. | ||||
2.3. API Resource | ||||
The API resource contains the state and access points for the | ||||
RESTCONF features. It is the top-level resource and has the media | ||||
type "application/yang.api+xml" or "application/yang.api+json". | ||||
YANG Tree Diagram for "application/yang.api" Resource Type: | ||||
+--rw restconf | ||||
+--rw data | ||||
+--rw operations | ||||
The "restconf" grouping definition in the "ietf-restconf" module | ||||
defined in Section 7 is used to specify the structure and syntax of | ||||
the conceptual child resources within the API resource. | ||||
This resource has the following child resources: | ||||
+----------------+--------------------------------+ | ||||
| Child Resource | Description | | ||||
+----------------+--------------------------------+ | ||||
| data | Contains all data resources | | ||||
| operations | Data-model specific operations | | ||||
+----------------+--------------------------------+ | ||||
RESTCONF API Resource | ||||
2.3.1. {+restconf}/data | ||||
This mandatory resource represents the combined configuration and | ||||
operational data resources that can be accessed by a client. It | ||||
cannot be created or deleted by the client. The datastore resource | ||||
type is defined in Section 2.4. | ||||
Example: | ||||
This example request by the client would retrieve only the non- | ||||
configuration data nodes that exist within the "library" resource, | ||||
using the "content" query parameter (see Section 3.8.2). | ||||
GET /restconf/data/example-jukebox:jukebox/library | ||||
?content=nonconfig HTTP/1.1 | ||||
Host: example.com | ||||
Accept: application/yang.data+json, | ||||
application/yang.errors+json | ||||
The server might respond: | ||||
HTTP/1.1 200 OK | ||||
Date: Mon, 23 Apr 2012 17:01:30 GMT | ||||
Server: example-server | ||||
Cache-Control: no-cache | ||||
Pragma: no-cache | ||||
Content-Type: application/yang.data+json | ||||
{ | ||||
"example-jukebox:library" : { | ||||
"artist-count" : 42, | ||||
"album-count" : 59, | ||||
"song-count" : 374 | ||||
} | ||||
} | ||||
2.3.2. {+restconf}/operations | ||||
This optional resource is a container that provides access to the | ||||
data-model specific protocol operations supported by the server. The | ||||
server MAY omit this resource if no data-model specific operations | ||||
are advertised. | ||||
Any data-model specific operations defined in the YANG modules | ||||
advertised by the server MAY be available as child nodes of this | ||||
resource. | ||||
Operation resources are defined in Section 2.6. | ||||
2.4. Datastore Resource | ||||
The "{+restconf}/data" subtree represents the datastore resource | ||||
type, which is a collection of configuration and operational data | ||||
nodes. | ||||
A "unified datastore" interface is used to simplify resource editing | ||||
for the client. The RESTCONF unified datastore is a conceptual | ||||
interface to the native configuration datastores that are present on | ||||
the device. | ||||
The underlying NETCONF datastores (i.e., candidate, running, startup) | ||||
can be used to implement the unified datastore, but the server design | ||||
is not limited to the exact datastore procedures defined in NETCONF. | ||||
The "candidate" and "startup" datastores are not visible in the | ||||
RESTCONF protocol. Transaction management and configuration | ||||
persistence are handled by the server and not controlled by the | ||||
client. | ||||
A datastore resource can only be written directly with the PATCH | ||||
method. Only the configuration data resources within the datastore | ||||
resource can be edited directly with all methods. | ||||
Each RESTCONF edit of a datastore resource is saved to non-volatile | ||||
storage in an implementation-specific matter by the server. There is | ||||
no guarantee that configuration changes are saved immediately, or | ||||
that the saved configuration is always a mirror of the running | ||||
configuration. | ||||
2.4.1. Edit Collision Detection | ||||
Two "edit collision detection" mechanisms are provided in RESTCONF, | ||||
for datastore and data resources. | ||||
2.4.1.1. Timestamp | ||||
The last change time is maintained and the "Last-Modified" and "Date" | ||||
headers are returned in the response for a retrieval request. The | ||||
"If-Unmodified-Since" header can be used in edit operation requests | ||||
to cause the server to reject the request if the resource has been | ||||
modified since the specified timestamp. | ||||
The server MUST maintain a last-modified timestamp for this resource, | ||||
and return the "Last-Modified" header when this resource is retrieved | ||||
with the GET or HEAD methods. Only changes to configuration data | ||||
resources within the datastore affect this timestamp. | ||||
2.4.1.2. Entity tag | ||||
A unique opaque string is maintained and the "ETag" header is | ||||
returned in the response for a retrieval request. The "If-Match" | ||||
header can be used in edit operation requests to cause the server to | ||||
reject the request if the resource entity tag does not match the | ||||
specified value. | ||||
The server MUST maintain a resource entity tag for this resource, and | ||||
return the "ETag" header when this resource is retrieved with the GET | ||||
or HEAD methods. The resource entity tag MUST be changed to a new | ||||
previously unused value if changes to any configuration data | ||||
resources within the datastore are made. | ||||
2.5. Data Resource | ||||
A data resource represents a YANG data node that is a descendant node | ||||
of a datastore resource. | ||||
For configuration data resources, the server MAY maintain a last- | ||||
modified timestamp for the resource, and return the "Last-Modified" | ||||
header when it is retrieved with the GET or HEAD methods. If | ||||
maintained, the resource timestamp MUST be set to the current time | ||||
whenever the resource or any configuration resource within the | ||||
resource is altered. | ||||
For configuration data resources, the server MAY maintain a resource | ||||
entity tag for the resource, and return the "ETag" header when it is | ||||
retrieved as the target resource with the GET or HEAD methods. If | ||||
maintained, the resource entity tag MUST be updated whenever the | ||||
resource or any configuration resource within the resource is | ||||
altered. | ||||
A data resource can be retrieved with the GET method. Data resources | ||||
are accessed via the "{+restconf}/data" entry point. This sub-tree | ||||
is used to retrieve and edit data resources. | ||||
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 3 for more details on edit | ||||
operations. | ||||
The resource definition version for a data resource is identified by | ||||
the revision date of the YANG module containing the YANG definition | ||||
for the data resource, specified in the "{+restconf}/modules" sub- | ||||
tree. | ||||
2.5.1. Encoding YANG Instance Identifiers in the Request URI | ||||
In YANG, data nodes are named with an absolute XPath expression, | ||||
defined in [XPath] , starting from the document root to the target | ||||
resource. In RESTCONF, URL encoded Location header expressions are | ||||
used instead. | ||||
The YANG "instance-identifier" (i-i) data type is represented in | ||||
RESTCONF with the path expression format defined in this section. | ||||
+-------+-------------------------------------------+ | ||||
| Name | Comments | | ||||
+-------+-------------------------------------------+ | ||||
| point | Insertion point is always a full i-i | | ||||
| path | Request URI path is a full or partial i-i | | ||||
+-------+-------------------------------------------+ | ||||
RESTCONF instance-identifier Type Conversion | ||||
The "path" component of the request URI contains the absolute path | ||||
expression that identifies the target resource. | ||||
A predictable location for a data resource is important, since | ||||
applications will code to the YANG data model module, which uses | ||||
static naming and defines an absolute path location for all data | ||||
nodes. | ||||
A RESTCONF data resource identifier is not an XPath expression. It | ||||
is encoded from left to right, starting with the top-level data node, | ||||
according to the "api-path" rule in Section 2.5.1.1. The node name | ||||
of each ancestor of the target resource node is encoded in order, | ||||
ending with the node name for the target resource. | ||||
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 | ||||
following rules. | ||||
o The key leaf values for a data resource representing a YANG list | ||||
MUST be encoded using one path segment [RFC3986]. | ||||
o If there is only one key leaf value, the path segment is | ||||
constructed by having the list name followed by an "=" followed by | ||||
the single key leaf value. | ||||
o If there are multiple key leaf values, the value of each leaf | ||||
identified in the "key" statement is encoded in the order | ||||
specified in the YANG "key" statement, with a comma separating | ||||
them. | ||||
o All the components in the "key" statement MUST be encoded. | ||||
Partial instance identifiers are not supported. | ||||
o Quoted strings are supported in the key leaf values. Quoted | ||||
strings MUST be used to express empty strings. (example: | ||||
list=foo,'',baz). | ||||
o The "list-instance" ABNF rule defined in Section 2.5.1.1 | ||||
represents the syntax of a list instance identifier. | ||||
o Resource URI values returned in Location headers for data | ||||
resources MUST identify the module name, 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: | ||||
container top { | ||||
list list1 { | ||||
key "key1 key2 key3"; | ||||
... | ||||
list list2 { | ||||
key "key4 key5"; | ||||
... | ||||
leaf X { type string; } | ||||
} | ||||
} | ||||
For the above YANG definition, URI with key leaf values will be | ||||
encoded as follows (line wrapped for display purposes only): | ||||
/restconf/data/top/list1=key1val,key2val,key3val3/ | ||||
list2=key4val,key5val/X | ||||
2.5.1.1. ABNF For Data Resource Identifiers | ||||
The "api-path" ABNF syntax is used to construct RESTCONF path | ||||
identifiers: | ||||
api-path = "/" | | ||||
("/" api-identifier | ||||
0*("/" (api-identifier | list-instance ))) | ||||
api-identifier = [module-name ":"] identifier | ||||
module-name = identifier | ||||
list-instance = api-identifier "=" key-value ["," key-value]* | ||||
key-value = string | ||||
string = <a quoted or unquoted or empty string> | ||||
;; An identifier MUST NOT start with | ||||
;; (('X'|'x') ('M'|'m') ('L'|'l')) | ||||
identifier = (ALPHA / "_") | ||||
*(ALPHA / DIGIT / "_" / "-" / ".") | ||||
2.5.2. Defaults Handling | ||||
NETCONF has a rather complex model for handling default values for | ||||
leafs. RESTCONF attempts to avoid this complexity by restricting the | ||||
operations that can be applied to a resource. Applications that | ||||
require full control of defaults might consider NETCONF instead of | ||||
RESTCONF. | ||||
If the target of a GET method is a data node that represents a leaf | ||||
that has a default value, and the leaf has not been given a value | ||||
yet, the server MUST return the default value that is in use by the | ||||
server. | ||||
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, | ||||
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. | ||||
2.6. Operation Resource | ||||
An operation resource represents an protocol operation defined with | ||||
the YANG "rpc" statement. | ||||
All operation resources share the same module namespace as any top- | ||||
level data resources, so the name of an operation resource cannot | ||||
conflict with the name of a top-level data resource defined within | ||||
the same module. | ||||
If 2 different YANG modules define the same "rpc" identifier, then | ||||
the module name MUST be used in the request URI. For example, if | ||||
"module-A" and "module-B" both defined a "reset" operation, then | ||||
invoking the operation from "module-A" would be requested as follows: | ||||
POST /restconf/operations/module-A:reset HTTP/1.1 | ||||
Server example.com | ||||
Any usage of an operation resource from the same module, with the | ||||
same name, refers to the same "rpc" statement definition. This | ||||
behavior can be used to design protocol operations that perform the | ||||
same general function on different resource types. | ||||
If the "rpc" statement has an "input" section, then a message body | ||||
MAY be sent by the client in the request, otherwise the request | ||||
message MUST NOT include a message body. If the "rpc" statement has | ||||
an "output" section, then a message body MAY be sent by the server in | ||||
the response. Otherwise the server MUST NOT include a message body | ||||
in the response message, and MUST send a "204 No Content" Status-Line | ||||
instead. | ||||
2.6.1. Encoding Operation Input Parameters | ||||
If the "rpc" 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. | ||||
Example: | ||||
The following YANG definition is used for the examples in this | ||||
section. | ||||
rpc reboot { | ||||
input { | ||||
leaf delay { | ||||
units seconds; | ||||
type uint32; | ||||
default 0; | ||||
} | ||||
leaf message { type string; } | ||||
leaf language { type string; } | ||||
} | ||||
} | ||||
The client might send the following POST request message: | ||||
POST /restconf/operations/example-ops:reboot HTTP/1.1 | ||||
Host: example.com | ||||
Content-Type: application/yang.operation+json | ||||
{ | ||||
"example-ops:input" : { | ||||
"delay" : 600, | ||||
"message" : "Going down for system maintenance", | ||||
"language" : "en-US" | ||||
} | ||||
} | ||||
The server might respond: | ||||
HTTP/1.1 204 No Content | ||||
Date: Mon, 25 Apr 2012 11:01:00 GMT | ||||
Server: example-server | ||||
2.6.2. Encoding Operation Output Parameters | ||||
If the "rpc" statement has an "output" section, then the "output" | ||||
node is provided in the message body, corresponding to the YANG data | ||||
definition statements within the "output" section. | ||||
Example: | ||||
The following YANG definition is used for the examples in this | ||||
section. | ||||
rpc get-reboot-info { | ||||
output { | ||||
leaf reboot-time { | ||||
units seconds; | ||||
type uint32; | ||||
} | ||||
leaf message { type string; } | ||||
leaf language { type string; } | ||||
} | ||||
} | ||||
The client might send the following POST request message: | ||||
POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 | ||||
Host: example.com | ||||
Accept: application/yang.operation+json, | ||||
application/yang.errors+json | ||||
The server might respond: | ||||
HTTP/1.1 200 OK | ||||
Date: Mon, 25 Apr 2012 11:10:30 GMT | ||||
Server: example-server | ||||
Content-Type: application/yang.operation+json | ||||
{ | ||||
"example-ops:output" : { | ||||
"reboot-time" : 30, | ||||
"message" : "Going down for system maintenance", | ||||
"language" : "en-US" | ||||
} | ||||
} | ||||
2.7. Schema Resource | ||||
If the server supports the "schema" leaf within the API then the | ||||
client can retrieve the YANG schema text for the associated YANG | ||||
module or submodule, using the GET method. First the client needs to | ||||
retrieve the URL for retrieving the schema. | ||||
The client might send the following GET request message: | ||||
GET /restconf/data/modules/module= | ||||
example-jukebox,2014-07-03/schema HTTP/1.1 | ||||
Host: example.com | ||||
Accept: application/yang.data+json, | ||||
application/yang.errors+json | ||||
The server might respond: | ||||
HTTP/1.1 200 OK | ||||
Date: Mon, 25 Apr 2012 11:10:30 GMT | ||||
Server: example-server | ||||
Content-Type: application/yang.data+json | ||||
{ | ||||
"schema": | ||||
"http://example.com/mymodules/example-jukebox/2014-07-03" | ||||
} | ||||
Next the client needs to retrieve the actual YANG schema. | ||||
The client might send the following GET request message: | ||||
GET http://example.com/mymodules/example-jukebox/2014-07-03 | ||||
HTTP/1.1 | ||||
Host: example.com | ||||
Accept: application/yang.data+json, | ||||
application/yang.errors+json | ||||
The server might respond: | ||||
module example-jukebox { | ||||
namespace "http://example.com/ns/example-jukebox"; | ||||
prefix "jbox"; | ||||
// rest of YANG module content deleted... | ||||
} | ||||
2.8. Stream Resource | ||||
A "stream" resource represents a source for system generated event | ||||
notifications. Each stream is created and modified by the server | ||||
only. A client can retrieve a stream resource or initiate a long- | ||||
poll server sent event stream, using the procedure specified in | ||||
Section 5.3. | ||||
A notification stream functions according to the NETCONF | ||||
Notifications specification [RFC5277]. The "ietf-restconf" YANG | ||||
module contains the "stream" list ("{+restconf}/streams/stream") | ||||
which specifies the syntax and semantics of a stream resource. | ||||
2.9. Errors Resource | ||||
An "errors" resource is a collection of error information that is | ||||
sent as the message body in a server response message, if an error | ||||
occurs while processing a request message. | ||||
The "ietf-restconf" YANG module contains the "errors" grouping which | ||||
specifies the syntax and semantics of an errors resource. RESTCONF | ||||
error handling behavior is defined in Section 6. | ||||
3. Operations | ||||
The RESTCONF protocol uses HTTP methods to identify the CRUD | The RESTCONF protocol uses HTTP methods to identify the CRUD | |||
operation requested for a particular resource. | operation requested for a particular resource. | |||
The following table shows how the RESTCONF operations relate to | The following table shows how the RESTCONF operations relate to | |||
NETCONF protocol operations: | NETCONF protocol operations: | |||
+----------+-------------------------------------+ | +----------+-------------------------------------+ | |||
| RESTCONF | NETCONF | | | RESTCONF | NETCONF | | |||
+----------+-------------------------------------+ | +----------+-------------------------------------+ | |||
skipping to change at page 12, line 47 | skipping to change at page 24, line 9 | |||
corresponding YANG instance-identifier. Using this information, the | corresponding YANG instance-identifier. Using this information, the | |||
server can apply the NACM access control rules to RESTCONF messages. | server can apply the NACM access control rules to RESTCONF messages. | |||
The server MUST NOT allow any operation to any resources that the | The server MUST NOT allow any operation to any resources that the | |||
client is not authorized to access. | client is not authorized to access. | |||
Implementation of all methods (except PATCH) are defined in | Implementation of all methods (except PATCH) are defined in | |||
[RFC2616]. This section defines the RESTCONF protocol usage for each | [RFC2616]. This section defines the RESTCONF protocol usage for each | |||
HTTP method. | HTTP method. | |||
2.1. OPTIONS | 3.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. If supported, | are supported by the server for a specific resource. If supported, | |||
it SHOULD be implemented for all media types. | it SHOULD be implemented for all media types. | |||
The server SHOULD implement this method, however the same information | The server SHOULD implement this method, however the same information | |||
could be extracted from the YANG modules and the RESTCONF protocol | could be extracted from the YANG modules and the RESTCONF protocol | |||
specification. | specification. | |||
If the PATCH method is supported, then the "Accept-Patch" header MUST | If the PATCH method is supported, then the "Accept-Patch" header MUST | |||
be supported, as defined in [RFC5789]. | be supported, as defined in [RFC5789]. | |||
2.2. HEAD | 3.2. HEAD | |||
The HEAD method is sent by the client to retrieve just the headers | The HEAD method is sent by the client to retrieve just the headers | |||
that would be returned for the comparable GET method, without the | that would be returned for the comparable GET method, without the | |||
response body. It is supported for all resource types, except | response body. It is supported for all resource types, except | |||
operation resources. | operation resources. | |||
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 component. The same query parameters supported by the | entry point component. The same query parameters supported by the | |||
GET method are supported by the HEAD method. | GET 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 body is included. | was GET instead of HEAD, except that no response body is included. | |||
2.3. GET | 3.3. GET | |||
The GET method is sent by the client to retrieve data and meta-data | The GET method is sent by the client to retrieve data and meta-data | |||
for a resource. It is supported for all resource types, except | for a resource. It is supported for all resource types, except | |||
operation resources. The request MUST contain a request URI that | operation resources. The request MUST contain a request URI that | |||
contains at least the entry point component. | contains at least the entry point component. | |||
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 "403 Forbidden" or | target resource, an error response containing a "403 Forbidden" or | |||
"404 Not Found" Status-Line is returned to the client. | "404 Not Found" Status-Line is returned to the client. | |||
skipping to change at page 14, line 26 | skipping to change at page 25, line 37 | |||
{ | { | |||
"album" : [ | "album" : [ | |||
{ | { | |||
"name" : "Wasting Light", | "name" : "Wasting Light", | |||
"genre" : "example-jukebox:alternative", | "genre" : "example-jukebox:alternative", | |||
"year" : 2011 | "year" : 2011 | |||
} | } | |||
] | ] | |||
} | } | |||
2.4. POST | 3.4. POST | |||
The POST method is sent by the client to create a data resource or | The POST method is sent by the client to create a data resource or | |||
invoke an operation resource. The server uses the target resource | invoke an operation resource. The server uses the target resource | |||
media type to determine how to process the request. | media type to determine how to process the request. | |||
+-----------+------------------------------------------------+ | +-----------+------------------------------------------------+ | |||
| Type | Description | | | Type | Description | | |||
+-----------+------------------------------------------------+ | +-----------+------------------------------------------------+ | |||
| Datastore | Create a top-level configuration data resource | | | Datastore | Create a top-level configuration data resource | | |||
| Data | Create a configuration data child resource | | | Data | Create a configuration data child resource | | |||
| Operation | Invoke a protocol operation | | | Operation | Invoke a protocol operation | | |||
+-----------+------------------------------------------------+ | +-----------+------------------------------------------------+ | |||
Resource Types that Support POST | Resource Types that Support POST | |||
2.4.1. Create Resource Mode | 3.4.1. Create Resource Mode | |||
If the target resource type is a datastore or data resource, then the | If the target resource type is a datastore or data resource, then the | |||
POST is treated as a request to create a resource or child resource. | POST is treated as a request to create a resource or child resource. | |||
The message body is expected to contain the content of a child | The message body is expected to contain the content of a child | |||
resource to create within the parent (target resource). | resource to create within the parent (target resource). | |||
The "insert" and "point" query parameters are supported by the POST | The "insert" and "point" query parameters are supported by the POST | |||
method for datastore and data resource types, as specified in the | method for datastore and data resource types, as specified in the | |||
YANG definition in Section 7. | YANG definition in Section 7. | |||
skipping to change at page 15, line 36 | skipping to change at page 26, line 47 | |||
HTTP/1.1 201 Created | HTTP/1.1 201 Created | |||
Date: Mon, 23 Apr 2012 17:01:00 GMT | Date: Mon, 23 Apr 2012 17:01:00 GMT | |||
Server: example-server | Server: example-server | |||
Location: http://example.com/restconf/data/example-jukebox:jukebox | Location: http://example.com/restconf/data/example-jukebox:jukebox | |||
Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT | Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT | |||
ETag: b3a3e673be2 | ETag: b3a3e673be2 | |||
Refer to Appendix D.2.1 for more resource creation examples. | Refer to Appendix D.2.1 for more resource creation examples. | |||
2.4.2. Invoke Operation Mode | 3.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 message | method is treated as a request to invoke that operation. The message | |||
body (if any) is processed as the operation input parameters. Refer | body (if any) is processed as the operation input parameters. Refer | |||
to Section 4.6 for details on operation resources. | to Section 2.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" or "404 Not Found" | error response containing a "403 Forbidden" or "404 Not Found" | |||
Status-Line is returned to the client. All other error responses are | Status-Line is returned to the client. All other error responses are | |||
handled according to the procedures defined in Section 6. | handled according to the procedures defined in Section 6. | |||
skipping to change at page 16, line 27 | skipping to change at page 27, line 38 | |||
"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 2012 17:50:00 GMT | |||
Server: example-server | Server: example-server | |||
2.5. PUT | 3.5. PUT | |||
The PUT method is sent by the client to create or replace the target | The PUT method is sent by the client to create or replace the target | |||
resource. | resource. | |||
The only target resource media type that supports PUT is the data | The only target resource media type that supports PUT is the data | |||
resource. The message body is expected to contain the content used | resource. The message body is expected to contain the content used | |||
to create or replace the target resource. | to create or replace the target resource. | |||
The "insert" and "point" query parameters are supported by the PUT | The "insert" (Section 3.8.5) and "point" (Section 3.8.6) query | |||
method for data resources, as specified in the YANG definition in | parameters are supported by the PUT method for data resources. | |||
Section 7. | ||||
Consistent with [RFC2616], if the PUT request creates a new resource, | Consistent with [RFC2616], 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, either "200 OK" or "204 No Content" are returned. | modified, either "200 OK" or "204 No Content" are 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" or "404 Not | resource an error response containing a "403 Forbidden" or "404 Not | |||
Found" Status-Line is returned to the client. All other error | Found" Status-Line is returned to the client. All other error | |||
responses are handled according to the procedures defined in | responses are handled according to the procedures defined in | |||
Section 6. | Section 6. | |||
skipping to change at page 17, line 31 | skipping to change at page 28, line 41 | |||
} | } | |||
If the resource is updated, the server might respond: | If the resource is updated, the server might respond: | |||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | |||
Date: Mon, 23 Apr 2012 17:04:00 GMT | Date: Mon, 23 Apr 2012 17:04:00 GMT | |||
Server: example-server | Server: example-server | |||
Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT | Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT | |||
ETag: b27480aeda4c | ETag: b27480aeda4c | |||
2.6. PATCH | 3.6. PATCH | |||
RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide | RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide | |||
an extensible framework for resource patching mechanisms. It is | an extensible framework for resource patching mechanisms. It is | |||
optional to implement by the server. Each patch type needs a unique | optional to implement by the server. Each patch type needs a unique | |||
media type. Zero or more PATCH media types MAY be supported by the | media type. Zero or more PATCH media types MAY be supported by the | |||
server. | server. | |||
A plain patch is used to create or update a child resource within the | A plain patch is used to create or update a child resource within the | |||
target resource. If the target resource instance does not exist, the | target resource. If the target resource instance does not exist, the | |||
server MUST NOT create it. | server MUST NOT create it. | |||
skipping to change at page 18, line 45 | skipping to change at page 30, line 5 | |||
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 | library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
If-Match: b8389233a4c | If-Match: b8389233a4c | |||
Content-Type: application/yang.data+xml | Content-Type: application/yang.data+xml | |||
<album xmlns="http://example.com/ns/example-jukebox"> | <album xmlns="http://example.com/ns/example-jukebox"> | |||
<genre>example-jukebox:rock</genre> | <genre>example-jukebox:rock</genre> | |||
<year>2011</year> | <year>2011</year> | |||
</album> | </album> | |||
2.7. DELETE | 3.7. DELETE | |||
The DELETE method is used to delete the target resource. If the | The DELETE method is used to delete the target resource. If the | |||
DELETE request succeeds, a "204 No Content" Status-Line is returned, | DELETE request succeeds, a "204 No Content" Status-Line is returned, | |||
and there is no response message body. | and there is no response message body. | |||
If the user is not authorized to delete the target resource then an | If the user is not authorized to delete the target resource then an | |||
error response containing a "403 Forbidden" or "404 Not Found" | error response containing a "403 Forbidden" or "404 Not Found" | |||
Status-Line is returned to the client. All other error responses are | Status-Line is returned to the client. All other error responses are | |||
handled according to the procedures defined in Section 6. | handled according to the procedures defined in Section 6. | |||
skipping to change at page 19, line 23 | skipping to change at page 30, line 31 | |||
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 2012 17:49:40 GMT | |||
Server: example-server | Server: example-server | |||
2.8. Query Parameters | 3.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. | |||
+------------+----------+-------------------------------------------+ | +------------+----------+-------------------------------------------+ | |||
| Name | Methods | Description | | | Name | Methods | Description | | |||
+------------+----------+-------------------------------------------+ | +------------+----------+-------------------------------------------+ | |||
| content | GET | Select config and/or non-config data | | | content | GET | Select config and/or non-config data | | |||
| | | resources | | | | | resources | | |||
| depth | GET | Request limited sub-tree depth in the | | | depth | GET | Request limited sub-tree depth in the | | |||
| | | reply content | | | | | reply content | | |||
| filter | GET | Boolean notification filter for | | | filter | GET | Boolean notification filter for event- | | |||
| | | event-stream resources | | | | | stream resources | | |||
| insert | POST, | Insertion mode for user-ordered data | | | insert | POST, | Insertion mode for user-ordered data | | |||
| | PUT | resources | | | | PUT | resources | | |||
| point | POST, | Insertion point for user-ordered data | | | point | POST, | Insertion point for user-ordered data | | |||
| | PUT | resources | | | | PUT | resources | | |||
| select | GET | Request a subset of the target resource | | | select | GET | Request a subset of the target resource | | |||
| | | contents | | | | | contents | | |||
| start-time | GET | Replay buffer start time for event-stream | | | start-time | GET | Replay buffer start time for event-stream | | |||
| | | resources | | | | | resources | | |||
| stop-time | GET | Replay buffer stop time for event-stream | | | stop-time | GET | Replay buffer stop time for event-stream | | |||
| | | resources | | | | | resources | | |||
+------------+----------+-------------------------------------------+ | +------------+----------+-------------------------------------------+ | |||
RESTCONF Query Parameters | RESTCONF Query Parameters | |||
Query parameters can be given in any order. Each parameter can | Query parameters can be given in any order. Each parameter can | |||
appear at most once in a request URI. A default value may apply if | appear at most once in a request URI. A default value may apply if | |||
the parameter is missing. | the parameter is missing. | |||
The semantics and syntax for all query parameters are defined in the | ||||
"query-parameters" YANG grouping in Section 7. The YANG encoding | ||||
MUST be converted to URL-encoded string for use in the request URI. | ||||
Refer to Appendix D.3 for examples of query parameter usage. | Refer to Appendix D.3 for examples of query parameter usage. | |||
3. Messages | If vendors define additional query parameters, they SHOULD use a | |||
prefix (such as the enterprise or organization name) for query | ||||
parameter names in order to avoid collisions with other parameters. | ||||
3.8.1. Query Parameter URIs | ||||
A new set of NETCONF Capability URNs are defined to identify the | ||||
specific query parameters supported by the server. | ||||
+---------+-------------------------------------------------+ | ||||
| Name | URI | | ||||
+---------+-------------------------------------------------+ | ||||
| content | urn:ietf:params:restconf:capability:content:1.0 | | ||||
| depth | urn:ietf:params:restconf:capability:depth:1.0 | | ||||
| filter | urn:ietf:params:restconf:capability:filter:1.0 | | ||||
| insert | urn:ietf:params:restconf:capability:insert:1.0 | | ||||
| select | urn:ietf:params:restconf:capability:select:1.0 | | ||||
| replay | urn:ietf:params:restconf:capability:replay:1.0 | | ||||
+---------+-------------------------------------------------+ | ||||
RESTCONF Query Parameter URIs | ||||
3.8.2. The "content" Query Parameter | ||||
The "content" parameter controls how descendant nodes of the | ||||
requested data nodes will be processed in the reply. | ||||
The allowed values are: | ||||
+-----------+-----------------------------------------------------+ | ||||
| Value | Description | | ||||
+-----------+-----------------------------------------------------+ | ||||
| config | Return only configuration descendant data nodes | | ||||
| nonconfig | Return only non-configuration descendant data nodes | | ||||
| all | Return all descendant data nodes | | ||||
+-----------+-----------------------------------------------------+ | ||||
This parameter is only allowed for GET methods on datastore and data | ||||
resources. A 400 Bad Request error is returned if used for other | ||||
methods or resource types. | ||||
The default value is determined by the "config" statement value of | ||||
the requested data nodes. If the "config" value is "false", then the | ||||
default for the "content" parameter is "nonconfig". If "config" is | ||||
"true" then the default for the "content" parameter is "config". | ||||
If this query parameter is supported by the server, then the | ||||
"content" query parameter URI MUST be listed in the "capability" | ||||
leaf-list in Section 8.3. | ||||
3.8.3. The "depth" Query Parameter | ||||
The "depth" parameter is used to specify the number of nest levels | ||||
returned in a response for a GET method. The first nest-level | ||||
consists of the requested data node itself. Any child nodes which | ||||
are contained within a parent node have a depth value that is 1 | ||||
greater than its parent. | ||||
The value of the "depth" parameter is either an integer between 1 and | ||||
65535, or the string "unbounded". "unbounded" is the default. | ||||
This parameter is only allowed for GET methods on API, datastore, and | ||||
data resources. A 400 Bad Request error is returned if it used for | ||||
other methods or resource types. | ||||
By default, the server will include all sub-resources within a | ||||
retrieved resource, which have the same resource type as the | ||||
requested resource. Only one level of sub-resources with a different | ||||
media type than the target resource will be returned. | ||||
If this query parameter is supported by the server, then the "depth" | ||||
query parameter URI MUST be listed in the "capability" leaf-list in | ||||
Section 8.3. | ||||
3.8.4. The "select" Query Parameter | ||||
The "select" query parameter is used to optionally identify data | ||||
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 | ||||
in a resource. | ||||
A value of the "select" query parameter matches the following rule: | ||||
select-expr = path '(' select-expr / '*' ')' / | ||||
path ';' select-expr / | ||||
path | ||||
path = api-identifier [ '/' path ] | ||||
"api-identifier" is defined in Section 2.5.1.1. | ||||
";" is used to select multiple nodes. For example, to retrieve only | ||||
the "genre" and "year" of an album, use: "select=genre;year". | ||||
Parentheses are used to specify sub-selectors of a node. For | ||||
example, to retrieve only the "label" and "catalogue-number" of an | ||||
album, use: "select=admin(label;catalogue-number)". | ||||
"/" is used in a path to retrieve a child node of a node. For | ||||
example, to retrieve only the "label" of an album, use: | ||||
"select=admin/label". | ||||
This parameter is only allowed for GET methods on api, datastore, and | ||||
data resources. A 400 Bad Request error is returned if used for | ||||
other methods or resource types. | ||||
If this query parameter is supported by the server, then the "select" | ||||
query parameter URI MUST be listed in the "capability" leaf-list in | ||||
Section 8.3. | ||||
3.8.5. The "insert" Query Parameter | ||||
The "insert" parameter is used to specify how a resource should be | ||||
inserted within a user-ordered list. | ||||
The allowed values are: | ||||
+--------+----------------------------------------------------------+ | ||||
| Value | Description | | ||||
+--------+----------------------------------------------------------+ | ||||
| first | Insert the new data as the new first entry. | | ||||
| last | Insert the new data as the new last entry. | | ||||
| before | Insert the new data before the insertion point, as | | ||||
| | specified by the value of the "point" parameter. | | ||||
| after | Insert the new data after the insertion point, as | | ||||
| | specified by the value of the "point" parameter. | | ||||
+--------+----------------------------------------------------------+ | ||||
The default value is "last". | ||||
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 | ||||
that data represents a YANG list or leaf-list that is ordered by the | ||||
user. | ||||
If the values "before" or "after" are used, then a "point" query | ||||
parameter for the insertion parameter MUST also be present, or a 400 | ||||
Bad Request error is returned. | ||||
If this query parameter is supported by the server, then the "insert" | ||||
query parameter URI MUST be listed in the "capability" leaf-list in | ||||
Section 8.3. The "point" query parameter MUST also be supported by | ||||
the server. | ||||
3.8.6. The "point" Query Parameter | ||||
The "point" parameter is used to specify the insertion point for a | ||||
data resource that is being created or moved within a user ordered | ||||
list or leaf-list. | ||||
The value of the "point" parameter is of type | ||||
"data-resource-identifier", defined in the "ietf-restconf" YANG | ||||
module Section 7. | ||||
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 | ||||
that data represents a YANG list or leaf-list that is ordered by the | ||||
user. | ||||
If the "insert" query parameter is not present, or has a value other | ||||
than "before" or "after", then a 400 Bad Request error is returned. | ||||
This parameter contains the instance identifier of the resource to be | ||||
used as the insertion point for a POST or PUT method. | ||||
If the server includes the "insert" query parameter URI in the | ||||
"capability" leaf-list in Section 8.3, then the "point" query | ||||
parameter MUST be supported. | ||||
3.8.7. The "filter" Query Parameter | ||||
The "filter" parameter is used to indicate which subset of all | ||||
possible events are of interest. If not present, all events not | ||||
precluded by other parameters will be sent. | ||||
This parameter is only allowed for GET methods on a text/event-stream | ||||
data resource. A 400 Bad Request error is returned if used for other | ||||
methods or resource types. | ||||
The format of this parameter is an XPath 1.0 expression, and is | ||||
evaluated in the following context: | ||||
o The set of namespace declarations is the set of prefix and | ||||
namespace pairs for all supported YANG modules, where the prefix | ||||
is the YANG module name, and the namespace is as defined by the | ||||
"namespace" statement in the YANG module. | ||||
o The function library is the core function library defined in XPath | ||||
1.0. | ||||
o The set of variable bindings is empty. | ||||
o The context node is the root node. | ||||
The filter is used as defined in [RFC5277], section 3.6. If the | ||||
boolean result of the expression is true when applied to the | ||||
conceptual "notification" document root, then the notification event | ||||
is delivered to the client. | ||||
If this query parameter is supported by the server, then the "filter" | ||||
query parameter URI MUST be listed in the "capability" leaf-list in | ||||
Section 8.3. | ||||
3.8.8. The "start-time" Query Parameter | ||||
The "start-time" parameter is used to trigger the notification replay | ||||
feature and indicate that the replay should start at the time | ||||
specified. If the stream does not support replay, per the | ||||
"replay-support" attribute returned by the /restconf/streams | ||||
resource, then the server MUST return the HTTP error code 400 Bad | ||||
Request. | ||||
The value of the "start-time" parameter is of type "date-and-time", | ||||
defined in the "ietf-yang" YANG module [RFC6991]. | ||||
This parameter is only allowed for GET methods on a text/event-stream | ||||
data resource. A 400 Bad Request error is returned if used for other | ||||
methods or resource types. | ||||
If this parameter is not present, then a replay subscription is not | ||||
being requested. It is not valid to specify start times that are | ||||
later than the current time. If the value specified is earlier than | ||||
the log can support, the replay will begin with the earliest | ||||
available notification. | ||||
If this query parameter is supported by the server, then the "replay" | ||||
query parameter URI MUST be listed in the "capability" leaf-list in | ||||
Section 8.3. The "stop-time" query parameter MUST also be supported | ||||
by the server. | ||||
If the "replay-support" leaf is present in the "stream" entry | ||||
(defined in Section 8.3) then the server MUST support the | ||||
"start-time" and "stop-time" query parameters for that stream. | ||||
3.8.9. The "stop-time" Query Parameter | ||||
The "stop-time" parameter is used with the replay feature to indicate | ||||
the newest notifications of interest. This parameter MUST be used | ||||
with and have a value later than the "start-time" parameter. | ||||
The value of the "stop-time" parameter is of type "date-and-time", | ||||
defined in the "ietf-yang" YANG module [RFC6991]. | ||||
This parameter is only allowed for GET methods on a text/event-stream | ||||
data resource. A 400 Bad Request error is returned if used for other | ||||
methods or resource types. | ||||
If this parameter is not present, the notifications will continue | ||||
until the subscription is terminated. Values in the future are | ||||
valid. | ||||
If this query parameter is supported by the server, then the "replay" | ||||
query parameter URI MUST be listed in the "capability" leaf-list in | ||||
Section 8.3. The "start-time" query parameter MUST also be supported | ||||
by the server. | ||||
If the "replay-support" leaf is present in the "stream" entry | ||||
(defined in Section 8.3) then the server MUST support the | ||||
"start-time" and "stop-time" query parameters for that stream. | ||||
4. 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. | |||
3.1. Request URI Structure | 4.1. Request URI Structure | |||
Resources are represented with URIs following the structure for | Resources are represented with URIs following the structure for | |||
generic URIs in [RFC3986]. | generic URIs in [RFC3986]. | |||
A RESTCONF operation is derived from the HTTP method and the request | A RESTCONF operation is derived from the HTTP method and the request | |||
URI, using the following conceptual fields: | URI, using the following conceptual fields: | |||
<OP> /<restconf>/<path>?<query>#<fragment> | <OP> /<restconf>/<path>?<query>#<fragment> | |||
^ ^ ^ ^ ^ | ^ ^ ^ ^ ^ | |||
skipping to change at page 21, line 36 | skipping to change at page 37, line 45 | |||
M M O O I | M M O O I | |||
M=mandatory, O=optional, I=ignored | M=mandatory, O=optional, I=ignored | |||
<text> replaced by client with real values | <text> replaced by client with real values | |||
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 2. | Section 3. | |||
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.2. All of the examples in | resource, as described in Section 4.2. All of the examples in | |||
this document assume "/restconf" as the discovered RESTCONF API | this document assume "/restconf" as the discovered RESTCONF API | |||
root path. The URI template [RFC6570] syntax "{+restconf}" is | root path. The URI template [RFC6570] syntax "{+restconf}" is | |||
used to refer to the entry point outside of an example. | used to refer to the entry point outside of an example. | |||
o resource: the path expression identifying the resource that is | o resource: the path expression identifying the resource that is | |||
being accessed by the operation. If this field is not present, | being accessed by the operation. If this field is not present, | |||
then the target resource is the API itself, represented by the | then the target resource is the API itself, represented by the | |||
media type "application/yang.api". | media type "application/yang.api". | |||
o query: the set of parameters associated with the RESTCONF message. | o query: the set of parameters associated with the RESTCONF message. | |||
These have the familiar form of "name=value" pairs. There is a | These have the familiar form of "name=value" pairs. All query | |||
specific set of parameters defined, although the server MAY choose | parameters are optional to implement by the server and optional to | |||
to support additional parameters not defined in this document. | use by the client. Each query parameter is identified by a URI. | |||
The contents of the any query parameter value MUST be encoded | The server MUST list the query parameter URIs it supports in the | |||
according to [RFC2396], section 3.4. Any reserved characters MUST | "capabilities" list defined in Section 8.3. | |||
be encoded with escape sequences, according to [RFC2396], section | ||||
2.4. | There is a specific set of parameters defined, although the server | |||
MAY choose to support query parameters not defined in this document. | ||||
The contents of the any query parameter value MUST be encoded | ||||
according to [RFC2396], section 3.4. Any reserved characters MUST be | ||||
encoded with escape sequences, according to [RFC2396], section 2.4. | ||||
o fragment: This field is not used by the RESTCONF protocol. | o fragment: This field is not used by the RESTCONF protocol. | |||
When new resources are created by the client, a "Location" header is | When new resources are created by the client, a "Location" header is | |||
returned, which identifies the path of the newly created resource. | returned, which identifies the path of the newly created resource. | |||
The client MUST use this exact path identifier to access the resource | The client MUST use this exact path identifier to access the resource | |||
once it has been created. | once it has been created. | |||
The "target" of an operation is a resource. The "path" field in the | The "target" of an operation is a resource. The "path" field in the | |||
request URI represents the target resource for the operation. | request URI represents the target resource for the operation. | |||
3.2. RESTCONF Path Resolution | 4.2. RESTCONF Path Resolution | |||
In line the best practices defined by [get-off-my-lawn], RESTCONF | In line the best practices defined by [get-off-my-lawn], 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. The client discovers this by | determine the root of the RESTCONF API. The client discovers this by | |||
getting the "/.well-known/host-meta" resource ([RFC6415]) and using | getting the "/.well-known/host-meta" resource ([RFC6415]) and using | |||
the <Link> element containing the "restconf" attribute : | the <Link> element containing the "restconf" attribute : | |||
Request | Request | |||
------- | ------- | |||
skipping to change at page 23, line 25 | skipping to change at page 39, line 32 | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Date: Mon, 23 Apr 2012 17:01:00 GMT | Date: Mon, 23 Apr 2012 17:01:00 GMT | |||
Server: example-server | Server: example-server | |||
Cache-Control: no-cache | Cache-Control: no-cache | |||
Pragma: no-cache | Pragma: no-cache | |||
Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT | Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT | |||
Content-Type: application/yang.api+json | Content-Type: application/yang.api+json | |||
{ "operations" : { "play" : [ null ] } } | { "operations" : { "play" : [ null ] } } | |||
3.3. Message Headers | 4.3. Message Headers | |||
There are several HTTP header lines utilized in RESTCONF messages. | There are several HTTP header lines utilized in RESTCONF messages. | |||
Messages are not limited to the HTTP headers listed in this section. | Messages are not limited to the HTTP headers listed in this section. | |||
HTTP defines which header lines are required for particular | HTTP defines which header lines are required for particular | |||
circumstances. Refer to each operation definition section in | circumstances. Refer to each operation definition section in | |||
Section 2 for examples on how particular headers are used. | Section 3 for examples on how particular headers are used. | |||
There are some request headers that are used within RESTCONF, usually | There are some request headers that are used within RESTCONF, usually | |||
applied to data resources. The following tables summarize the | applied to data resources. The following tables summarize the | |||
headers most relevant in RESTCONF message requests: | headers most relevant in RESTCONF message requests: | |||
+---------------------+---------------------------------------------+ | +---------------------+---------------------------------------------+ | |||
| Name | Description | | | Name | Description | | |||
+---------------------+---------------------------------------------+ | +---------------------+---------------------------------------------+ | |||
| Accept | Response Content-Types that are acceptable | | | Accept | Response Content-Types that are acceptable | | |||
| Content-Type | The media type of the request body | | | Content-Type | The media type of the request body | | |||
skipping to change at page 24, line 25 | skipping to change at page 40, line 40 | |||
| Date | The date and time the message was sent | | | Date | The date and time the message was sent | | |||
| ETag | An identifier for a specific version of a | | | ETag | An identifier for a specific version of a | | |||
| | resource | | | | resource | | |||
| Last-Modified | The last modified date and time of a resource | | | Last-Modified | The last modified date and time of a resource | | |||
| Location | The resource identifier for a newly created | | | Location | The resource identifier for a newly created | | |||
| | resource | | | | resource | | |||
+---------------+---------------------------------------------------+ | +---------------+---------------------------------------------------+ | |||
RESTCONF Response Headers | RESTCONF Response Headers | |||
3.4. Message Encoding | 4.4. Message Encoding | |||
RESTCONF messages are encoded in HTTP according to RFC 2616. The | RESTCONF messages are encoded in HTTP according to RFC 2616. 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. | Content is encoded in either JSON or XML format. | |||
XML encoding rules for data nodes are defined in [RFC6020]. The same | XML encoding rules for data nodes are defined in [RFC6020]. The same | |||
encoding rules are used for all XML content. | encoding rules are used for all XML content. | |||
skipping to change at page 25, line 5 | skipping to change at page 41, line 17 | |||
Request input content encoding format is identified with the Content- | Request input content encoding format is identified with the Content- | |||
Type header. This field MUST be present if a message body is sent by | Type header. This field MUST be present if a message body is sent by | |||
the client. | the client. | |||
Response output content encoding format is identified with the Accept | Response output content encoding format is identified with the Accept | |||
header in the request, or if is not specified, the request input | header in the request, or if is not specified, the request input | |||
encoding format is used. If there was no request input, then the | encoding format is used. If there was no request input, then the | |||
default output encoding is XML. File extensions encoded in the | default output encoding is XML. File extensions encoded in the | |||
request are not used to identify format encoding. | request are not used to identify format encoding. | |||
3.5. RESTCONF Meta-Data | 4.5. RESTCONF Meta-Data | |||
The RESTCONF protocol needs to retrieve the same meta-data that is | The RESTCONF protocol needs to retrieve the same meta-data that is | |||
used in the NETCONF protocol. Information about default leafs, last- | used in the NETCONF protocol. Information about default leafs, last- | |||
modified timestamps, etc. are commonly used to annotate | modified timestamps, etc. are commonly used to annotate | |||
representations of the datastore contents. This meta-data is not | representations of the datastore contents. This meta-data is not | |||
defined in the YANG schema because it applies to the datastore, and | defined in the YANG schema because it applies to the datastore, and | |||
is common across all data nodes. | is common across all data nodes. | |||
This information is encoded as attributes in XML. JSON encoding of | This information is encoded as attributes in XML. JSON encoding of | |||
meta-data is defined in [I-D.lhotka-netmod-json]. | meta-data is defined in [I-D.lhotka-netmod-json]. | |||
3.6. Return Status | 4.6. Return Status | |||
Each message represents some sort of resource access. An HTTP | Each message represents some sort of resource access. An HTTP | |||
"Status-Line" header line is returned for each request. If a 4xx or | "Status-Line" header line is returned for each request. If a 4xx or | |||
5xx range status code is returned in the Status-Line, then the error | 5xx range status code is returned in the Status-Line, then the error | |||
information will be returned in the response, according to the format | information will be returned in the response, according to the format | |||
defined in Section 6.1. | defined in Section 6.1. | |||
3.7. Message Caching | 4.7. Message Caching | |||
Since the datastore contents change at unpredictable times, responses | Since the datastore contents change at unpredictable times, responses | |||
from a RESTCONF server generally SHOULD NOT be cached. | from a RESTCONF server generally SHOULD NOT be cached. | |||
The server SHOULD include a "Cache-Control" header in every response | The server SHOULD include a "Cache-Control" header in every response | |||
that specifies whether the response should be cached. A "Pragma" | that specifies whether the response should be cached. A "Pragma" | |||
header specifying "no-cache" MAY also be sent in case the | header specifying "no-cache" MAY also be sent in case the | |||
"Cache-Control" header is not supported. | "Cache-Control" header is not supported. | |||
Instead of using HTTP caching, the client SHOULD track the "ETag" | Instead of using HTTP caching, the client SHOULD track the "ETag" | |||
and/or "Last-Modified" headers returned by the server for the | and/or "Last-Modified" headers returned by the server for the | |||
datastore resource (or data resource if the server supports it). A | datastore resource (or data resource if the server supports it). A | |||
retrieval request for a resource can include the "If-None-Match" | retrieval request for a resource can include the "If-None-Match" and/ | |||
and/or "If-Modified-Since" headers, which will cause the server to | or "If-Modified-Since" headers, which will cause the server to return | |||
return a "304 Not Modified" Status-Line if the resource has not | a "304 Not Modified" Status-Line if the resource has not changed. | |||
changed. The client MAY use the HEAD method to retrieve just the | The client MAY use the HEAD method to retrieve just the message | |||
message headers, which SHOULD include the "ETag" and "Last-Modified" | headers, which SHOULD include the "ETag" and "Last-Modified" headers, | |||
headers, if this meta-data is maintained for the target resource. | if this meta-data is maintained for the target resource. | |||
4. Resources | ||||
The RESTCONF protocol operates on a hierarchy of resources, starting | ||||
with the top-level API resource itself. Each resource represents a | ||||
manageable component within the device. | ||||
A resource can be considered a collection of conceptual data and the | ||||
set of allowed methods on that data. It can contain nested child | ||||
resources. The child resource types and methods allowed on them are | ||||
data-model specific. | ||||
A resource has its own media type identifier, represented by the | ||||
"Content-Type" header in the HTTP response message. A resource can | ||||
contain zero or more nested resources. A resource can be created and | ||||
deleted independently of its parent resource, as long as the parent | ||||
resource exists. | ||||
All RESTCONF resources are defined in this document except datastore | ||||
contents, protocol operations, and notification events. 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 | ||||
document. The set of YANG modules supported by the server will | ||||
determine the data model specific operations, top-level data node | ||||
resources, and notification event messages supported by the server. | ||||
The resources used in the RESTCONF protocol are identified by the | ||||
"path" component in the request URI. Each operation is performed on | ||||
a target resource. | ||||
4.1. RESTCONF Resource Types | ||||
The RESTCONF protocol defines a set of application specific media | ||||
types to identify each of the available resource types. The | ||||
following resource types are defined in RESTCONF: | ||||
+-----------+----------------------------+ | ||||
| Resource | Media Type | | ||||
+-----------+----------------------------+ | ||||
| API | application/yang.api | | ||||
| Datastore | application/yang.datastore | | ||||
| Data | application/yang.data | | ||||
| Errors | application/yang.errors | | ||||
| Operation | application/yang.operation | | ||||
| Schema | application/yang | | ||||
| Stream | application/yang.stream | | ||||
+-----------+----------------------------+ | ||||
RESTCONF Media Types | ||||
4.2. Resource Discovery | ||||
A client SHOULD start by retrieving the top-level API resource, using | ||||
the entry point URI defined in Section 3.2. | ||||
The RESTCONF protocol does not include a resource discovery | ||||
mechanism. Instead, the definitions within the YANG modules | ||||
advertised by the server are used to construct a predictable | ||||
operation or data resource identifier. | ||||
The "depth" query parameter can be used to control how many | ||||
descendant levels should be included when retrieving child resources. | ||||
This parameter can be used with the GET method to discover child | ||||
resources within a particular resource. | ||||
4.3. API Resource | ||||
The API resource contains the state and access points for the | ||||
RESTCONF features. It is the top-level resource and has the media | ||||
type "application/yang.api+xml" or "application/yang.api+json". | ||||
YANG Tree Diagram for "application/yang.api" Resource Type: | ||||
+--rw restconf | ||||
+--rw data | ||||
+--rw modules | ||||
| +--rw module* [name revision] | ||||
| +--rw name yang:yang-identifier | ||||
| +--rw revision union | ||||
| +--rw schema? empty | ||||
| +--rw namespace inet:uri | ||||
| +--rw feature* yang:yang-identifier | ||||
| +--rw deviation* yang:yang-identifier | ||||
| +--rw submodule* [name revision] | ||||
| +--rw name yang:yang-identifier | ||||
| +--rw revision union | ||||
| +--rw schema? empty | ||||
+--rw operations | ||||
+--rw streams | ||||
+--rw stream* [name] | ||||
+--rw name string | ||||
+--rw description? string | ||||
+--rw replay-support? boolean | ||||
+--rw replay-log-creation-time? yang:date-and-time | ||||
+--rw events? empty | ||||
The "restconf" container definition in the "ietf-restconf" module | ||||
defined in Section 7 is used to specify the structure and syntax of | ||||
the conceptual child resources within the API resource. | ||||
This resource has the following child resources: | ||||
+----------------+--------------------------------+ | ||||
| Child Resource | Description | | ||||
+----------------+--------------------------------+ | ||||
| data | Contains all data resources | | ||||
| modules | YANG module information | | ||||
| operations | Data-model specific operations | | ||||
| streams | Notification event streams | | ||||
+----------------+--------------------------------+ | ||||
RESTCONF Resources | ||||
4.3.1. {+restconf}/data | ||||
This mandatory resource represents the combined configuration and | ||||
operational data resources that can be accessed by a client. It | ||||
cannot be created or deleted by the client. The datastore resource | ||||
type is defined in Section 4.4. | ||||
Example: | ||||
This example request by the client would retrieve only the non- | ||||
configuration data nodes that exist within the "library" resource, | ||||
using the "content" query parameter. | ||||
GET /restconf/data/example-jukebox:jukebox/library | ||||
?content=nonconfig HTTP/1.1 | ||||
Host: example.com | ||||
Accept: application/yang.data+json, | ||||
application/yang.errors+json | ||||
The server might respond: | ||||
HTTP/1.1 200 OK | ||||
Date: Mon, 23 Apr 2012 17:01:30 GMT | ||||
Server: example-server | ||||
Cache-Control: no-cache | ||||
Pragma: no-cache | ||||
Content-Type: application/yang.data+json | ||||
{ | ||||
"example-jukebox:library" : { | ||||
"artist-count" : 42, | ||||
"album-count" : 59, | ||||
"song-count" : 374 | ||||
} | ||||
} | ||||
4.3.2. {+restconf}/modules | ||||
This mandatory resource contains the identifiers for the YANG data | ||||
model modules supported by the server. | ||||
The server MUST maintain a last-modified timestamp for this resource, | ||||
and return the "Last-Modified" header when this resource is retrieved | ||||
with the GET or HEAD methods. | ||||
The server SHOULD maintain an entity-tag for this resource, and | ||||
return the "ETag" header when this resource is retrieved with the GET | ||||
or HEAD methods. | ||||
4.3.2.1. {+restconf}/modules/module | ||||
This mandatory resource contains one list entry for each YANG data | ||||
model module supported by the server. There MUST be an instance of | ||||
this resource for every YANG module that is accessible via an | ||||
operation resource or a data resource. | ||||
The contents of the "module" resource are defined in the "module" | ||||
YANG list statement in Section 7. | ||||
The server MAY maintain a last-modified timestamp for each instance | ||||
of this resource, and return the "Last-Modified" header when this | ||||
resource is retrieved with the GET or HEAD methods. If not supported | ||||
then the timestamp for the parent "modules" resource MAY be used | ||||
instead. | ||||
The server MAY maintain an entity-tag for each instance of this | ||||
resource, and return the "ETag" header when this resource is | ||||
retrieved with the GET or HEAD methods. If not supported then the | ||||
timestamp for the parent "modules" resource MAY be used instead. | ||||
4.3.3. {+restconf}/operations | ||||
This optional resource is a container that provides access to the | ||||
data-model specific protocol operations supported by the server. The | ||||
server MAY omit this resource if no data-model specific operations | ||||
are advertised. | ||||
Any data-model specific operations defined in the YANG modules | ||||
advertised by the server MAY be available as child nodes of this | ||||
resource. | ||||
Operation resources are defined in Section 4.6. | ||||
4.3.4. {+restconf}/streams | ||||
This optional resource is a container that provides access to the | ||||
notification event streams supported by the server. The server MAY | ||||
omit this resource if no notification event streams are supported. | ||||
The media type for this resource is "application/yang.api". | ||||
The server will populate this container with a stream list entry for | ||||
each stream type it supports. Each stream contains a leaf called | ||||
"events" which represents an event stream resource. The media type | ||||
for this resource is "application/yang.stream". | ||||
Stream resources are defined in Section 4.8. Notifications are | ||||
defined in Section 5. | ||||
4.4. Datastore Resource | ||||
The "{+restconf}/data" subtree represents the datastore resource | ||||
type, which is a collection of configuration and operational data | ||||
nodes. | ||||
A "unified datastore" interface is used to simplify resource editing | ||||
for the client. The RESTCONF unified datastore is a conceptual | ||||
interface to the native configuration datastores that are present on | ||||
the device. | ||||
The underlying NETCONF datastores (i.e., candidate, running, startup) | ||||
can be used to implement the unified datastore, but the server design | ||||
is not limited to the exact datastore procedures defined in NETCONF. | ||||
The "candidate" and "startup" datastores are not visible in the | ||||
RESTCONF protocol. Transaction management and configuration | ||||
persistence are handled by the server and not controlled by the | ||||
client. | ||||
A datastore resource can only be written directly with the PATCH | ||||
method. Only the configuration data resources within the datastore | ||||
resource can be edited directly with all methods. | ||||
Each RESTCONF edit of a datastore resource is saved to non-volatile | ||||
storage in an implementation-specific matter by the server. There is | ||||
no guarantee that configuration changes are saved immediately, or | ||||
that the saved configuration is always a mirror of the running | ||||
configuration. | ||||
4.4.1. Edit Collision Detection | ||||
Two "edit collision detection" mechanisms are provided in RESTCONF, | ||||
for datastore and data resources. | ||||
4.4.1.1. Timestamp | ||||
The last change time is maintained and the "Last-Modified" and "Date" | ||||
headers are returned in the response for a retrieval request. The | ||||
"If-Unmodified-Since" header can be used in edit operation requests | ||||
to cause the server to reject the request if the resource has been | ||||
modified since the specified timestamp. | ||||
The server MUST maintain a last-modified timestamp for this resource, | ||||
and return the "Last-Modified" header when this resource is retrieved | ||||
with the GET or HEAD methods. Only changes to configuration data | ||||
resources within the datastore affect this timestamp. | ||||
4.4.1.2. Entity tag | ||||
A unique opaque string is maintained and the "ETag" header is | ||||
returned in the response for a retrieval request. The "If-Match" | ||||
header can be used in edit operation requests to cause the server to | ||||
reject the request if the resource entity tag does not match the | ||||
specified value. | ||||
The server MUST maintain a resource entity tag for this resource, and | ||||
return the "ETag" header when this resource is retrieved with the GET | ||||
or HEAD methods. The resource entity tag MUST be changed to a new | ||||
previously unused value if changes to any configuration data | ||||
resources within the datastore are made. | ||||
4.5. Data Resource | ||||
A data resource represents a YANG data node that is a descendant node | ||||
of a datastore resource. | ||||
For configuration data resources, the server MAY maintain a last- | ||||
modified timestamp for the resource, and return the "Last-Modified" | ||||
header when it is retrieved with the GET or HEAD methods. If | ||||
maintained, the resource timestamp MUST be set to the current time | ||||
whenever the resource or any configuration resource within the | ||||
resource is altered. | ||||
For configuration data resources, the server MAY maintain a resource | ||||
entity tag for the resource, and return the "ETag" header when it is | ||||
retrieved as the target resource with the GET or HEAD methods. If | ||||
maintained, the resource entity tag MUST be updated whenever the | ||||
resource or any configuration resource within the resource is | ||||
altered. | ||||
A data resource can be retrieved with the GET method. Data resources | ||||
are accessed via the "{+restconf}/data" entry point. This sub-tree | ||||
is used to retrieve and edit data resources. | ||||
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 2 for more details on edit | ||||
operations. | ||||
The resource definition version for a data resource is identified by | ||||
the revision date of the YANG module containing the YANG definition | ||||
for the data resource, specified in the "{+restconf}/modules" sub- | ||||
tree. | ||||
4.5.1. Encoding YANG Instance Identifiers in the Request URI | ||||
In YANG, data nodes are named with an absolute XPath expression, | ||||
defined in [XPath] , starting from the document root to the target | ||||
resource. In RESTCONF, URL encoded Location header expressions are | ||||
used instead. | ||||
The YANG "instance-identifier" (i-i) data type is represented in | ||||
RESTCONF with the path expression format defined in this section. | ||||
+-------+-------------------------------------------+ | ||||
| Name | Comments | | ||||
+-------+-------------------------------------------+ | ||||
| point | Insertion point is always a full i-i | | ||||
| path | Request URI path is a full or partial i-i | | ||||
+-------+-------------------------------------------+ | ||||
RESTCONF instance-identifier Type Conversion | ||||
The "path" component of the request URI contains the absolute path | ||||
expression that identifies the target resource. | ||||
A predictable location for a data resource is important, since | ||||
applications will code to the YANG data model module, which uses | ||||
static naming and defines an absolute path location for all data | ||||
nodes. | ||||
A RESTCONF data resource identifier is not an XPath expression. It | ||||
is encoded from left to right, starting with the top-level data node, | ||||
according to the "api-path" rule in Section 4.5.1.1. The node name | ||||
of each ancestor of the target resource node is encoded in order, | ||||
ending with the node name for the target resource. | ||||
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 | ||||
following rules. | ||||
o The key leaf values for a data resource representing a YANG list | ||||
MUST be encoded using one path segment [RFC3986]. | ||||
o If there is only one key leaf value, the path segment is | ||||
constructed by having the list name followed by an "=" followed by | ||||
the single key leaf value. | ||||
o If there are multiple key leaf values, the value of each leaf | ||||
identified in the "key" statement is encoded in the order | ||||
specified in the YANG "key" statement, with a comma separating | ||||
them. | ||||
o All the components in the "key" statement MUST be encoded. | ||||
Partial instance identifiers are not supported. | ||||
o Quoted strings are supported in the key leaf values. Quoted | ||||
strings MUST be used to express empty strings. (example: | ||||
list=foo,'',baz). | ||||
o The "list-instance" ABNF rule defined in Section 4.5.1.1 | ||||
represents the syntax of a list instance identifier. | ||||
o Resource URI values returned in Location headers for data | ||||
resources MUST identify the module name, 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: | ||||
container top { | ||||
list list1 { | ||||
key "key1 key2 key3"; | ||||
... | ||||
list list2 { | ||||
key "key4 key5"; | ||||
... | ||||
leaf X { type string; } | ||||
} | ||||
} | ||||
For the above YANG definition, URI with key leaf values will be | ||||
encoded as follows (line wrapped for display purposes only): | ||||
/restconf/data/top/list1=key1val,key2val,key3val3/ | ||||
list2=key4val,key5val/X | ||||
4.5.1.1. ABNF For Data Resource Identifiers | ||||
The "api-path" ABNF syntax is used to construct RESTCONF path | ||||
identifiers: | ||||
api-path = "/" | | ||||
("/" api-identifier | ||||
0*("/" (api-identifier | list-instance ))) | ||||
api-identifier = [module-name ":"] identifier | ||||
module-name = identifier | ||||
list-instance = api-identifier "=" key-value ["," key-value]* | ||||
key-value = string | ||||
string = <a quoted or unquoted or empty string> | ||||
;; An identifier MUST NOT start with | ||||
;; (('X'|'x') ('M'|'m') ('L'|'l')) | ||||
identifier = (ALPHA / "_") | ||||
*(ALPHA / DIGIT / "_" / "-" / ".") | ||||
4.5.2. Defaults Handling | ||||
NETCONF has a rather complex model for handling default values for | ||||
leafs. RESTCONF attempts to avoid this complexity by restricting the | ||||
operations that can be applied to a resource. Applications that | ||||
require full control of defaults might consider NETCONF instead of | ||||
RESTCONF. | ||||
If the target of a GET method is a data node that represents a leaf | ||||
that has a default value, and the leaf has not been given a value | ||||
yet, the server MUST return the default value that is in use by the | ||||
server. | ||||
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, | ||||
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. | ||||
4.6. Operation Resource | ||||
An operation resource represents an protocol operation defined with | ||||
the YANG "rpc" statement. | ||||
All operation resources share the same module namespace as any top- | ||||
level data resources, so the name of an operation resource cannot | ||||
conflict with the name of a top-level data resource defined within | ||||
the same module. | ||||
If 2 different YANG modules define the same "rpc" identifier, then | ||||
the module name MUST be used in the request URI. For example, if | ||||
"module-A" and "module-B" both defined a "reset" operation, then | ||||
invoking the operation from "module-A" would be requested as follows: | ||||
POST /restconf/operations/module-A:reset HTTP/1.1 | ||||
Server example.com | ||||
Any usage of an operation resource from the same module, with the | ||||
same name, refers to the same "rpc" statement definition. This | ||||
behavior can be used to design protocol operations that perform the | ||||
same general function on different resource types. | ||||
If the "rpc" statement has an "input" section, then a message body | ||||
MAY be sent by the client in the request, otherwise the request | ||||
message MUST NOT include a message body. If the "rpc" statement has | ||||
an "output" section, then a message body MAY be sent by the server in | ||||
the response. Otherwise the server MUST NOT include a message body | ||||
in the response message, and MUST send a "204 No Content" Status-Line | ||||
instead. | ||||
4.6.1. Encoding Operation Input Parameters | ||||
If the "rpc" 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. | ||||
Example: | ||||
The following YANG definition is used for the examples in this | ||||
section. | ||||
rpc reboot { | ||||
input { | ||||
leaf delay { | ||||
units seconds; | ||||
type uint32; | ||||
default 0; | ||||
} | ||||
leaf message { type string; } | ||||
leaf language { type string; } | ||||
} | ||||
} | ||||
The client might send the following POST request message: | ||||
POST /restconf/operations/example-ops:reboot HTTP/1.1 | ||||
Host: example.com | ||||
Content-Type: application/yang.operation+json | ||||
{ | ||||
"example-ops:input" : { | ||||
"delay" : 600, | ||||
"message" : "Going down for system maintenance", | ||||
"language" : "en-US" | ||||
} | ||||
} | ||||
The server might respond: | ||||
HTTP/1.1 204 No Content | ||||
Date: Mon, 25 Apr 2012 11:01:00 GMT | ||||
Server: example-server | ||||
4.6.2. Encoding Operation Output Parameters | ||||
If the "rpc" statement has an "output" section, then the "output" | ||||
node is provided in the message body, corresponding to the YANG data | ||||
definition statements within the "output" section. | ||||
Example: | ||||
The following YANG definition is used for the examples in this | ||||
section. | ||||
rpc get-reboot-info { | ||||
output { | ||||
leaf reboot-time { | ||||
units seconds; | ||||
type uint32; | ||||
} | ||||
leaf message { type string; } | ||||
leaf language { type string; } | ||||
} | ||||
} | ||||
The client might send the following POST request message: | ||||
POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 | ||||
Host: example.com | ||||
Accept: application/yang.operation+json, | ||||
application/yang.errors+json | ||||
The server might respond: | ||||
HTTP/1.1 200 OK | ||||
Date: Mon, 25 Apr 2012 11:10:30 GMT | ||||
Server: example-server | ||||
Content-Type: application/yang.operation+json | ||||
{ | ||||
"example-ops:output" : { | ||||
"reboot-time" : 30, | ||||
"message" : "Going down for system maintenance", | ||||
"language" : "en-US" | ||||
} | ||||
} | ||||
4.7. Schema Resource | ||||
If the server supports the "schema" leaf within the API then the | ||||
client can retrieve the YANG schema text for the associated YANG | ||||
module or submodule, using the GET method. | ||||
The client might send the following GET request message: | ||||
GET /restconf/modules/module=example-jukebox,2014-07-03/schema | ||||
HTTP/1.1 | ||||
Host: example.com | ||||
Accept: application/yang, | ||||
application/yang.errors+json | ||||
The server might respond: | ||||
HTTP/1.1 200 OK | ||||
Date: Mon, 25 Apr 2012 11:10:30 GMT | ||||
Server: example-server | ||||
Content-Type: application/yang | ||||
module example-jukebox { | ||||
namespace "http://example.com/ns/example-jukebox"; | ||||
prefix "jbox"; | ||||
// rest of YANG module content deleted... | ||||
} | ||||
4.8. Stream Resource | ||||
A "stream" resource represents a source for system generated event | ||||
notifications. Each stream is created and modified by the server | ||||
only. A client can retrieve a stream resource or initiate a long- | ||||
poll server sent event stream, using the procedure specified in | ||||
Section 5.3. | ||||
A notification stream functions according to the NETCONF | ||||
Notifications specification [RFC5277]. The "ietf-restconf" YANG | ||||
module contains the "stream" list ("{+restconf}/streams/stream") | ||||
which specifies the syntax and semantics of a stream resource. | ||||
4.9. Errors Resource | ||||
An "errors" resource is a collection of error information that is | ||||
sent as the message body in a server response message, if an error | ||||
occurs while processing a request message. | ||||
The "ietf-restconf" YANG module contains the "errors" grouping which | ||||
specifies the syntax and semantics of an errors resource. RESTCONF | ||||
error handling behavior is defined in Section 6. | ||||
5. Notifications | 5. 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 [wd-eventsource] transport | while utilizing the Server-Sent Events [wd-eventsource] transport | |||
strategy. | strategy. | |||
5.1. Server Support | 5.1. Server Support | |||
A RESTCONF server is not required to support RESTCONF notifications. | A RESTCONF server is not required to support RESTCONF notifications. | |||
Clients may determine if a server supports RESTCONF notifications by | Clients may determine if a server supports RESTCONF notifications by | |||
using the HTTP operation OPTIONS, HEAD, or GET on the "{+restconf}/ | using the HTTP operation OPTIONS, HEAD, or GET on the | |||
streams" resource described below. The server does not support | "{+restconf}/streams" resource described below. The server does not | |||
RESTCONF notifications if an HTTP error code is returned (e.g., 404 | support RESTCONF notifications if an HTTP error code is returned | |||
Not Found). | (e.g., 404 Not Found). | |||
5.2. Event Streams | 5.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 "{+restconf}/ | a RESTCONF server using the GET operation on the "restconf-state/ | |||
streams" resource. | streams" data resource defined in Section 8.3. | |||
The "{+restconf}/streams" container definition in the "ietf-restconf" | The "restconf-state/streams" container definition in the | |||
module defined in Section 7 is used to specify the structure and | "ietf-restconf-monitoring" module (defined in Section 8.3) is used to | |||
syntax of the conceptual child resources within the "streams" | specify the structure and syntax of the conceptual child resources | |||
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/streams HTTP/1.1 | GET /restconf/data/restconf-state/streams HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Accept: application/yang.api+xml, | Accept: application/yang.data+xml, | |||
application/yang.errors+xml | application/yang.errors+xml | |||
The server might send the following response: | The server might send the following response: | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Content-Type: application/yang.api+xml | Content-Type: application/yang.api+xml | |||
<streams xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> | <streams | |||
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> | ||||
<stream> | <stream> | |||
<name>NETCONF</name> | <name>NETCONF</name> | |||
<description>default NETCONF event stream | <description>default NETCONF event stream | |||
</description> | </description> | |||
<replay-support>true</replay-support> | <replay-support>true</replay-support> | |||
<replay-log-creation-time> | <replay-log-creation-time> | |||
2007-07-08T00:00:00Z | 2007-07-08T00:00:00Z | |||
</replay-log-creation-time> | </replay-log-creation-time> | |||
<events/> | <events>http://example.com/streams/NETCONF</events> | |||
</stream> | </stream> | |||
<stream> | <stream> | |||
<name>SNMP</name> | <name>SNMP</name> | |||
<description>SNMP notifications</description> | <description>SNMP notifications</description> | |||
<replay-support>false</replay-support> | <replay-support>false</replay-support> | |||
<events/> | <events>http://example.com/streams/SNMP</events> | |||
</stream> | </stream> | |||
<stream> | <stream> | |||
<name>syslog-critical</name> | <name>syslog-critical</name> | |||
<description>Critical and higher severity | <description>Critical and higher severity | |||
</description> | </description> | |||
<replay-support>true</replay-support> | <replay-support>true</replay-support> | |||
<replay-log-creation-time> | <replay-log-creation-time> | |||
2007-07-01T00:00:00Z | 2007-07-01T00:00:00Z | |||
</replay-log-creation-time> | </replay-log-creation-time> | |||
<events/> | <events>http://example.com/streams/syslog-critical</events> | |||
</stream> | </stream> | |||
</streams> | </streams> | |||
5.3. Subscribing to Receive Notifications | 5.3. Subscribing to Receive Notifications | |||
RESTCONF clients can subscribe to receive notifications by sending an | RESTCONF clients can determine the URL for the subscription resource | |||
HTTP GET request for the "{+restconf}/streams/stream/<stream-name>" | (to receive notifications) by sending an HTTP GET request for the | |||
resource, with the "Accept" type "text/event-stream". The server | "{+restconf}/streams/stream/<stream-name>/events" data resource. | |||
will treat the connection as an event stream, using the Server Sent | ||||
Events [wd-eventsource] transport strategy. | The value returned by the server can be used for the actual | |||
notification subscription. | ||||
The client will send an HTTP GET request for the URL returned by the | ||||
server with the "Accept" type "text/event-stream". | ||||
The server will treat the connection as an event stream, using the | ||||
Server Sent Events [wd-eventsource] transport strategy. | ||||
The server MAY support query parameters for a GET method on this | The server MAY support query parameters for a GET method on this | |||
resource. These parameters are specific to each notification stream. | resource. These parameters are specific to each notification stream. | |||
For example: | For example: | |||
GET /restconf/streams/stream=NETCONF/events HTTP/1.1 | The client might send the following request: | |||
GET /restconf/data/restconf-state/streams/stream=NETCONF/events | ||||
HTTP/1.1 | ||||
Host: example.com | ||||
Accept: application/yang.data+xml, | ||||
application/yang.errors+xml | ||||
The server might send the following response: | ||||
HTTP/1.1 200 OK | ||||
Content-Type: application/yang.api+xml | ||||
<ietf-restconf-monitoring:events | ||||
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> | ||||
http://example.com/streams/NETCONF | ||||
</events> | ||||
The RESTCONF client can then use this URL value to start monitoring | ||||
the event stream: | ||||
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 the server compress the events using | A RESTCONF client MAY request the server compress the events using | |||
the HTTP header field "Accept-Encoding". For instance: | the HTTP header field "Accept-Encoding". For instance: | |||
GET /restconf/streams/stream=NETCONF/events 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 | |||
5.3.1. NETCONF Event Stream | 5.3.1. NETCONF Event Stream | |||
The server SHOULD support the "NETCONF" notification stream defined | The server SHOULD support the "NETCONF" notification stream defined | |||
in [RFC5277]. For this stream, RESTCONF notification subscription | in [RFC5277]. For this stream, RESTCONF notification subscription | |||
requests MAY specify parameters indicating the events it wishes to | requests MAY specify parameters indicating the events it wishes to | |||
receive. | receive. These query parameters are optional to implement, and only | |||
available if the server supports them. | ||||
+------------+-------------------------+ | +------------+-------------------------+ | |||
| Name | Description | | | Name | Description | | |||
+------------+-------------------------+ | +------------+-------------------------+ | |||
| start-time | replay event start time | | | start-time | replay event start time | | |||
| stop-time | replay event stop time | | | stop-time | replay event stop time | | |||
| filter | boolean content filter | | | filter | boolean content filter | | |||
+------------+-------------------------+ | +------------+-------------------------+ | |||
NETCONF Stream Query Parameters | NETCONF Stream Query Parameters | |||
The semantics and syntax for these query parameters are defined in | The semantics and syntax for these query parameters are defined in | |||
the "query-parameters" YANG grouping in Section 7. The YANG encoding | the "query-parameters" YANG grouping in Section 7. The YANG encoding | |||
MUST be converted to URL-encoded string for use in the request URI. | MUST be converted to URL-encoded string for use in the request URI. | |||
Refer to Appendix D.3.3 for filter parameter examples. | Refer to Appendix D.3.6 for filter parameter examples. | |||
5.4. Receiving Event Notifications | 5.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 | |||
"notification" YANG container definition in Section 7. | "notification" YANG container definition in Section 7. | |||
skipping to change at page 47, line 9 | skipping to change at page 50, line 32 | |||
"error-message": | "error-message": | |||
"Data already exists, cannot create new resource" | "Data already exists, cannot create new resource" | |||
} | } | |||
} | } | |||
} | } | |||
7. RESTCONF module | 7. RESTCONF module | |||
The "ietf-restconf" module defines conceptual definitions within | The "ietf-restconf" module defines conceptual definitions within | |||
groupings, which are not meant to be implemented as datastore | groupings, which are not meant to be implemented as datastore | |||
contents by a server. | contents by a server. The "restconf" container is not intended to be | |||
implemented as a top-level data node (under the "/restconf/data" | ||||
entry point). | ||||
The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] | The "ietf-yang-types" module from [RFC6991] is used by this module | |||
are used by this module for some type definitions. | 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@2014-07-03.yang" | <CODE BEGINS> file "ietf-restconf@2014-10-07.yang" | |||
module ietf-restconf { | module ietf-restconf { | |||
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; | namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; | |||
prefix "rc"; | prefix "rc"; | |||
import ietf-yang-types { prefix yang; } | import ietf-yang-types { prefix yang; } | |||
import ietf-inet-types { prefix inet; } | ||||
organization | organization | |||
"IETF NETCONF (Network Configuration) Working Group"; | "IETF NETCONF (Network Configuration) Working Group"; | |||
contact | contact | |||
"WG Web: <http://tools.ietf.org/wg/netconf/> | "WG Web: <http://tools.ietf.org/wg/netconf/> | |||
WG List: <mailto:netconf@ietf.org> | WG List: <mailto:netconf@ietf.org> | |||
WG Chair: Bert Wijnen | WG Chair: Bert Wijnen | |||
<mailto:bertietf@bwijnen.net> | <mailto:bertietf@bwijnen.net> | |||
skipping to change at page 47, line 46 | skipping to change at page 51, line 22 | |||
WG Chair: Mehmet Ersue | WG Chair: Mehmet Ersue | |||
<mailto:mehmet.ersue@nsn.com> | <mailto:mehmet.ersue@nsn.com> | |||
Editor: Andy Bierman | Editor: Andy Bierman | |||
<mailto:andy@yumaworks.com> | <mailto:andy@yumaworks.com> | |||
Editor: Martin Bjorklund | Editor: Martin Bjorklund | |||
<mailto:mbj@tail-f.com> | <mailto:mbj@tail-f.com> | |||
Editor: Kent Watsen | Editor: Kent Watsen | |||
<mailto:kwatsen@juniper.net> | <mailto:kwatsen@juniper.net>"; | |||
Editor: Rex Fernando | ||||
<mailto:rex@cisco.com>"; | ||||
description | description | |||
"This module contains conceptual YANG specifications | "This module contains conceptual YANG specifications | |||
for the message and error content that is used in | for the message and error content that is used in | |||
RESTCONF protocol messages. A conceptual container | RESTCONF protocol messages. A conceptual container | |||
representing the RESTCONF API nodes is also defined | representing the RESTCONF API nodes is also defined | |||
for the media type application/yang.api. | for the media type application/yang.api. | |||
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. | |||
skipping to change at page 48, line 31 | skipping to change at page 52, 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-01.txt | // Note: extracted from draft-ietf-netconf-restconf-02.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 2014-07-03 { | revision 2014-10-07 { | |||
description | description | |||
"Initial revision."; | "Initial revision."; | |||
reference | reference | |||
"RFC XXXX: RESTCONF Protocol."; | "RFC XXXX: RESTCONF Protocol."; | |||
} | } | |||
typedef data-resource-identifier { | typedef data-resource-identifier { | |||
type string { | type string { | |||
length "1 .. max"; | length "1 .. max"; | |||
} | } | |||
skipping to change at page 49, line 22 | skipping to change at page 52, line 43 | |||
location identification. Instead the identifier will start | location identification. Instead the identifier will start | |||
with the '/' character to represent the datastore document | with the '/' character to represent the datastore document | |||
root for the data resource instance. | root for the data resource instance. | |||
The server MUST accept either representation and SHOULD | The server MUST accept either representation and SHOULD | |||
return the canonical representation in any response message."; | return the canonical representation in any response message."; | |||
reference | reference | |||
"RFC XXXX: [sec. 5.3.1.1 ABNF For Data Resource Identifiers]"; | "RFC XXXX: [sec. 5.3.1.1 ABNF For Data Resource Identifiers]"; | |||
} | } | |||
typedef revision-identifier { | ||||
type string { | ||||
pattern '\d{4}-\d{2}-\d{2}'; | ||||
} | ||||
description | ||||
"Represents a specific date in YYYY-MM-DD format. | ||||
TBD: make pattern more precise to exclude leading zeros."; | ||||
} | ||||
grouping errors { | grouping errors { | |||
description | description | |||
"A grouping that contains a YANG container | "A grouping that contains a YANG container | |||
representing the syntax and semantics of a | representing the syntax and semantics of a | |||
YANG Patch errors report within a response message."; | YANG Patch errors report within a response message."; | |||
container errors { | container errors { | |||
description | description | |||
"Represents an error report returned by the server if | "Represents an error report returned by the server if | |||
a request results in an error."; | a request results in an error."; | |||
skipping to change at page 51, line 30 | skipping to change at page 54, line 44 | |||
anyxml error-info { | anyxml error-info { | |||
description | description | |||
"Arbitrary XML that represents a container | "Arbitrary XML that represents a container | |||
of additional information for the error report."; | of additional information for the error report."; | |||
} | } | |||
} | } | |||
} | } | |||
} // grouping errors | } // grouping errors | |||
grouping restconf { | grouping restconf { | |||
description | ||||
"A grouping that contains a YANG container | ||||
representing the syntax and semantics of | ||||
the RESTCONF API resource."; | ||||
container restconf { | container restconf { | |||
description | description | |||
"Conceptual container representing the | "Conceptual container representing the | |||
application/yang.api resource type."; | application/yang.api resource type."; | |||
container data { | container data { | |||
description | description | |||
"Container representing the application/yang.datastore | "Container representing the application/yang.datastore | |||
resource type. Represents the conceptual root of all | resource type. Represents the conceptual root of all | |||
operational data and configuration data supported by | operational data and configuration data supported by | |||
the server. The child nodes of this container can be | the server. The child nodes of this container can be | |||
any data resource (application/yang.data), which are | any data resource (application/yang.data), which are | |||
defined as top-level data nodes from the YANG modules | defined as top-level data nodes from the YANG modules | |||
advertised by the server in /restconf/modules."; | advertised by the server in the ietf-restconf-monitoring | |||
} | module."; | |||
container modules { | ||||
description | ||||
"Contains a list of module description entries. | ||||
These modules are currently loaded into the server."; | ||||
grouping common-leafs { | ||||
description | ||||
"Common parameters for YANG modules and submodules."; | ||||
leaf name { | ||||
type yang:yang-identifier; | ||||
description "The YANG module or submodule name."; | ||||
} | ||||
leaf revision { | ||||
type union { | ||||
type revision-identifier; | ||||
type string { length 0; } | ||||
} | ||||
description | ||||
"The YANG module or submodule revision date. | ||||
An empty string is used if no revision statement | ||||
is present in the YANG module or submodule."; | ||||
} | ||||
leaf schema { | ||||
type empty; | ||||
description | ||||
"Represents the YANG schema resource for this module | ||||
or submodule if it is available on the server. | ||||
This leaf will only be present if the server has | ||||
the schema available for retrieval. A GET | ||||
request with a target resource URI that identifies | ||||
this leaf will cause the server to return the YANG | ||||
schema text for the associated module or submodule."; | ||||
} | ||||
} | ||||
list module { | ||||
key "name revision"; | ||||
description | ||||
"Each entry represents one module currently | ||||
supported by the server."; | ||||
uses common-leafs; | ||||
leaf namespace { | ||||
type inet:uri; | ||||
mandatory true; | ||||
description | ||||
"The XML namespace identifier for this module."; | ||||
} | ||||
leaf-list feature { | ||||
type yang:yang-identifier; | ||||
description | ||||
"List of YANG feature names from this module that are | ||||
supported by the server."; | ||||
} | ||||
leaf-list deviation { | ||||
type yang:yang-identifier; | ||||
description | ||||
"List of YANG deviation module names used by this | ||||
server to modify the conformance of the module | ||||
associated with this entry."; | ||||
} | ||||
list submodule { | ||||
key "name revision"; | ||||
description | ||||
"Each entry represents one submodule within the | ||||
parent module."; | ||||
uses common-leafs; | ||||
} | ||||
} | ||||
} | } | |||
container operations { | container operations { | |||
description | description | |||
"Container for all operation resources | "Container for all operation resources | |||
(application/yang.operation), | (application/yang.operation), | |||
Each resource is represented as an empty leaf with the | Each resource is represented as an empty leaf with the | |||
name of the RPC operation from the YANG rpc statement. | name of the RPC operation from the YANG rpc statement. | |||
E.g.; | E.g.; | |||
POST /restconf/operations/show-log-errors | POST /restconf/operations/show-log-errors | |||
leaf show-log-errors { | leaf show-log-errors { | |||
type empty; | type empty; | |||
} | } | |||
"; | "; | |||
} | } | |||
} // container restconf | ||||
} // grouping restconf | ||||
container streams { | grouping notification { | |||
description | ||||
"Contains the notification message wrapper definition."; | ||||
container notification { | ||||
description | ||||
"RESTCONF notification message wrapper."; | ||||
leaf event-time { | ||||
type yang:date-and-time; | ||||
mandatory true; | ||||
description | description | |||
"Container representing the notification event streams | "The time the event was generated by the | |||
supported by the server."; | event source."; | |||
reference | reference | |||
"RFC 5277, Section 3.4, <streams> element."; | "RFC 5277, section 4, <eventTime> element."; | |||
} | ||||
/* The YANG-specific notification container is encoded | ||||
* after the 'event-time' element. The format | ||||
* corresponds to the notificationContent element | ||||
* in RFC 5277, section 4. For example: | ||||
* | ||||
* module example-one { | ||||
* ... | ||||
* notification event1 { ... } | ||||
* | ||||
* } | ||||
* | ||||
* Encoded as element 'event1' in the namespace | ||||
* for module 'example-one'. | ||||
*/ | ||||
} | ||||
} // grouping notification | ||||
list stream { | } | |||
key name; | ||||
description | ||||
"Each entry describes an event stream supported by | ||||
the server."; | ||||
leaf name { | <CODE ENDS> | |||
type string; | ||||
description "The stream name"; | ||||
reference "RFC 5277, Section 3.4, <name> element."; | ||||
} | ||||
leaf description { | 8. RESTCONF Monitoring | |||
type string; | ||||
description "Description of stream content"; | ||||
reference | ||||
"RFC 5277, Section 3.4, <description> element."; | ||||
} | ||||
leaf replay-support { | The "ietf-restconf-monitoring" module provides information about the | |||
type boolean; | RESTCONF protocol capabilities and notification event streams | |||
description | available from the server. Implementation is mandatory for RESTCONF | |||
"Indicates if replay buffer supported for this stream"; | servers, if any protocol capabilities or notification event streams | |||
reference | are supported. | |||
"RFC 5277, Section 3.4, <replaySupport> element."; | ||||
} | ||||
leaf replay-log-creation-time { | YANG Tree Diagram for "ietf-restconf-monitoring" module: | |||
type yang:date-and-time; | ||||
description | ||||
"Indicates the time the replay log for this stream | ||||
was created."; | ||||
reference | ||||
"RFC 5277, Section 3.4, <replayLogCreationTime> | ||||
element."; | ||||
} | ||||
leaf events { | +--ro restconf-state | |||
type empty; | +--ro capabilities | |||
description | | +--ro capability* inet:uri | |||
"Represents the entry point for establishing | +--ro streams | |||
notification delivery via server sent events."; | +--ro stream* [name] | |||
+--ro name string | ||||
+--ro description? string | ||||
+--ro replay-support? boolean | ||||
+--ro replay-log-creation-time? yang:date-and-time | ||||
+--ro events inet:uri | ||||
} | 8.1. restconf-state/capabilities | |||
} | ||||
} | ||||
} | This mandatory container holds the RESTCONF protocol capability URIs | |||
} // grouping restconf | supported by the server. | |||
grouping query-parameters { | The server MUST maintain a last-modified timestamp for this | |||
description | container, and return the "Last-Modified" header when this data node | |||
"Contains conceptual definitions for the query string | is retrieved with the GET or HEAD methods. | |||
parameters used in the RESTCONF protocol."; | ||||
leaf content { | The server SHOULD maintain an entity-tag for this container, and | |||
type enumeration { | return the "ETag" header when this data node is retrieved with the | |||
enum config { | GET or HEAD methods. | |||
description | ||||
"Return only configuration descendant data nodes"; | ||||
} | ||||
enum nonconfig { | ||||
description | ||||
"Return only non-configuration descendant data nodes"; | ||||
} | ||||
enum all { | ||||
description | ||||
"Return all descendant data nodes"; | ||||
} | ||||
} | ||||
description | ||||
"The content parameter controls how descendant nodes of | ||||
the requested data nodes will be processed in the reply. | ||||
This parameter is only allowed for GET methods on | 8.2. restconf-state/streams | |||
datastore and data resources. A 400 Bad Request error | ||||
is returned if used for other methods or resource types. | ||||
The default value is determined by the config-stmt | This optional container provides access to the notification event | |||
value of the requested data nodes. If 'false', then | streams supported by the server. The server MAY omit this container | |||
the default is 'nonconfig'. If 'true' then the | if no notification event streams are supported. | |||
default is 'config'."; | ||||
} | ||||
leaf depth { | The server will populate this container with a stream list entry for | |||
type union { | each stream type it supports. Each stream contains a leaf called | |||
type enumeration { | "events" which contains a URI that represents an event stream | |||
enum unbounded { | resource. | |||
description "All sub-resources will be returned."; | ||||
} | ||||
} | Stream resources are defined in Section 2.8. Notifications are | |||
type uint32 { | defined in Section 5. | |||
range "1..max"; | ||||
} | ||||
} | ||||
default unbounded; | ||||
description | ||||
"The 'depth' parameter is used to specify the number | ||||
of nest levels returned in a response for a GET method. | ||||
The first nest-level consists of the requested data node | ||||
itself. Any child nodes which are contained within | ||||
a parent node have a depth value that is 1 greater than | ||||
its parent. | ||||
This parameter is only allowed for GET methods on api, | 8.3. RESTCONF Monitoring Module | |||
datastore, and data resources. A 400 Bad Request error | ||||
is returned if used for other methods or resource types. | ||||
By default, the server will include all sub-resources | The "ietf-restconf-monitoring" module defines monitoring information | |||
within a retrieved resource, which have the same resource | for the RESTCONF protocol. | |||
type as the requested resource. Only one level of | ||||
sub-resources with a different media type than the target | ||||
resource will be returned."; | ||||
} | ||||
leaf filter { | The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] | |||
type yang:xpath1.0; | are used by this module for some type definitions. | |||
description | ||||
"The 'filter' parameter is used to indicate which subset of | ||||
all possible events are of interest. If not present, all | ||||
events not precluded by other parameters will be sent. | ||||
This parameter is only allowed for GET methods on a | RFC Ed.: update the date below with the date of RFC publication and | |||
text/event-stream data resource. A 400 Bad Request error | remove this note. | |||
is returned if used for other methods or resource types. | ||||
The format of this parameter is an XPath expression, and | <CODE BEGINS> file "ietf-restconf-monitoring@2014-10-07.yang" | |||
is evaluated in the following context: | ||||
o The set of namespace declarations is the set of | module ietf-restconf-monitoring { | |||
prefix and namespace pairs for all supported YANG | namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; | |||
modules, where the prefix is the YANG module name, and | prefix "rcmon"; | |||
the namespace is as defined by the 'namespace' statement | ||||
in the YANG module. | ||||
o The function library is the core function library defined | ||||
in XPATH. | ||||
o The set of variable bindings is empty. | import ietf-yang-types { prefix yang; } | |||
import ietf-inet-types { prefix inet; } | ||||
o The context node is the root node | organization | |||
"IETF NETCONF (Network Configuration) Working Group"; | ||||
The filter is used as defined in [RFC5277], section 3.6. | contact | |||
If the boolean result of the expression is true when applied | "WG Web: <http://tools.ietf.org/wg/netconf/> | |||
to the conceptual 'notification' document root, then the | WG List: <mailto:netconf@ietf.org> | |||
notification event is delivered to the client."; | WG Chair: Bert Wijnen | |||
<mailto:bertietf@bwijnen.net> | ||||
WG Chair: Mehmet Ersue | ||||
<mailto:mehmet.ersue@nsn.com> | ||||
Editor: Andy Bierman | ||||
<mailto:andy@yumaworks.com> | ||||
Editor: Martin Bjorklund | ||||
<mailto:mbj@tail-f.com> | ||||
Editor: Kent Watsen | ||||
<mailto:kwatsen@juniper.net>"; | ||||
description | ||||
"This module contains monitoring information for the | ||||
RESTCONF protocol. | ||||
Copyright (c) 2014 IETF Trust and the persons identified as | ||||
authors of the code. All rights reserved. | ||||
Redistribution and use in source and binary forms, with or | ||||
without modification, is permitted pursuant to, and subject | ||||
to the license terms contained in, the Simplified BSD License | ||||
set forth in Section 4.c of the IETF Trust's Legal Provisions | ||||
Relating to IETF Documents | ||||
(http://trustee.ietf.org/license-info). | ||||
This version of this YANG module is part of RFC XXXX; see | ||||
the RFC itself for full legal notices."; | ||||
// RFC Ed.: replace XXXX with actual RFC number and remove this | ||||
// note. | ||||
// RFC Ed.: remove this note | ||||
// Note: extracted from draft-ietf-netconf-restconf-02.txt | ||||
// RFC Ed.: update the date below with the date of RFC publication | ||||
// and remove this note. | ||||
revision 2014-10-07 { | ||||
description | ||||
"Initial revision."; | ||||
reference | ||||
"RFC XXXX: RESTCONF Protocol."; | ||||
} | ||||
container restconf-state { | ||||
config false; | ||||
description | ||||
"Contains RESTCONF protocol monitoring information."; | ||||
container capabilities { | ||||
description | ||||
"Contains a list of protocol capability URIs"; | ||||
leaf-list capability { | ||||
type inet:uri; | ||||
description "A RESTCONF protocol capability URI."; | ||||
} | ||||
} | } | |||
leaf insert { | container streams { | |||
type enumeration { | description | |||
enum first { | "Container representing the notification event streams | |||
description "Insert the new data as the new first entry."; | supported by the server."; | |||
reference | ||||
"RFC 5277, Section 3.4, <streams> element."; | ||||
list stream { | ||||
key name; | ||||
description | ||||
"Each entry describes an event stream supported by | ||||
the server."; | ||||
leaf name { | ||||
type string; | ||||
description "The stream name"; | ||||
reference "RFC 5277, Section 3.4, <name> element."; | ||||
} | } | |||
enum last { | ||||
description "Insert the new data as the new last entry."; | leaf description { | |||
type string; | ||||
description "Description of stream content"; | ||||
reference | ||||
"RFC 5277, Section 3.4, <description> element."; | ||||
} | } | |||
enum before { | ||||
leaf replay-support { | ||||
type boolean; | ||||
description | description | |||
"Insert the new data before the insertion point, | "Indicates if replay buffer supported for this stream. | |||
specified by the value of the 'point' parameter."; | If 'true', then the server MUST support the 'start-time' | |||
and 'stop-time' query parameters for this stream."; | ||||
reference | ||||
"RFC 5277, Section 3.4, <replaySupport> element."; | ||||
} | } | |||
enum after { | ||||
leaf replay-log-creation-time { | ||||
when "../replay-support"; | ||||
type yang:date-and-time; | ||||
description | description | |||
"Insert the new data after the insertion point, | "Indicates the time the replay log for this stream | |||
specified by the value of the 'point' parameter."; | was created."; | |||
reference | ||||
"RFC 5277, Section 3.4, <replayLogCreationTime> | ||||
element."; | ||||
} | ||||
leaf events { | ||||
type inet:uri; | ||||
mandatory true; | ||||
description | ||||
"Contains a URL that represents the entry point | ||||
for establishing notification delivery via server | ||||
sent events."; | ||||
} | } | |||
} | } | |||
default last; | } | |||
description | } | |||
"The 'insert' parameter is used to specify how a | ||||
resource should be inserted within a user-ordered list. | ||||
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 that data represents | ||||
a YANG list or leaf-list that is ordered by the user. | ||||
If the values 'before' or 'after' are used, | <CODE ENDS> | |||
then a 'point' query parameter for the insertion | ||||
parameter MUST also be present, or a 400 Bad Request | ||||
error is returned."; | ||||
} | ||||
leaf point { | 9. YANG Module Library | |||
type data-resource-identifier; | ||||
description | ||||
"The 'point' parameter is used to specify the | ||||
insertion point for a data resource that is being | ||||
created or moved within a user ordered list or leaf-list. | ||||
This parameter is only supported for the POST and PUT | The "ietf-yang-library" module provides information about the YANG | |||
methods. It is also only supported if the target | modules and submodules used by the RESTCONF server. Implementation | |||
resource is a data resource, and that data represents | is mandatory for RESTCONF servers. All YANG modules and submodules | |||
a YANG list or leaf-list that is ordered by the user. | used by the server MUST be identified in the YANG module library. | |||
If the 'insert' query parameter is not present, or has | YANG Tree Diagram for "ietf-yang-library" module: | |||
a value other than 'before' or 'after', then a 400 | ||||
Bad Request error is returned. | ||||
This parameter contains the instance identifier of the | +--ro modules | |||
resource to be used as the insertion point for a | +--ro module-set-id? string | |||
POST or PUT method."; | +--ro module* [name revision] | |||
} | +--ro name yang:yang-identifier | |||
+--ro revision union | ||||
+--ro schema? inet:uri | ||||
+--ro namespace inet:uri | ||||
+--ro feature* yang:yang-identifier | ||||
+--ro deviation* yang:yang-identifier | ||||
+--ro conformance boolean | ||||
+--ro submodules | ||||
+--ro submodule* [name revision] | ||||
+--ro name yang:yang-identifier | ||||
+--ro revision union | ||||
+--ro schema? inet:uri | ||||
leaf select { | 9.1. modules | |||
type string { | ||||
length "1 .. max"; | ||||
} | ||||
description | ||||
"The 'select' query parameter is used to optionally identify | ||||
data 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 in a resource. | ||||
A value of the 'select' query parameter matches the | This mandatory container holds the identifiers for the YANG data | |||
following rule: | model modules supported by the server. | |||
select-expr = path '(' select-expr / '*' ')' / | The server MUST maintain a last-modified timestamp for this | |||
path ';' select-expr / | container, and return the "Last-Modified" header when this data node | |||
path | is retrieved with the GET or HEAD methods. | |||
path = api-identifier [ '/' path ] | ||||
'api-identifier' is defined in section 5.3.1.1. | The server SHOULD maintain an entity-tag for this container, and | |||
return the "ETag" header when this data node is retrieved with the | ||||
GET or HEAD methods. | ||||
';' is used to select multiple nodes. For example, to | 9.1.1. modules/module | |||
retreive only the 'genre' and 'year' of an album, use: | ||||
'select=genre;year'. | ||||
Parentheses are used to specify sub-selectors of a node. | This mandatory list contains one entry for each YANG data model | |||
For example, to retreive only the 'label' and | module supported by the server. There MUST be an instance of this | |||
'catalogue-number' of an album, use: | list for every YANG module that is used by the server. | |||
'select=admin(label;catalogue-number)'. | ||||
'/' is used in a path to retreive a child node of a node. | The contents of the "module" list are defined in the "module" YANG | |||
For example, to retreive only the 'label' of an album, use: | list statement in Section 9.2. | |||
'select=admin/label'. | ||||
This parameter is only allowed for GET methods on api, | The server MAY maintain a last-modified timestamp for each instance | |||
datastore, and data resources. A 400 Bad Request error | of this list entry, and return the "Last-Modified" header when this | |||
is returned if used for other methods or resource types."; | data node is retrieved with the GET or HEAD methods. If not | |||
reference | supported then the timestamp for the parent "modules" container MAY | |||
"RFC XXXX: [sec. 5.3.1.1 ABNF For Data Resource Identifiers]"; | be used instead. | |||
} | ||||
leaf start-time { | The server MAY maintain an entity-tag for each instance of this list | |||
type yang:date-and-time; | entry, and return the "ETag" header when this data node is retrieved | |||
description | with the GET or HEAD methods. If not supported then the timestamp | |||
"The 'start-time' parameter is used to trigger | for the parent "modules" container MAY be used instead. | |||
the notification replay feature and indicate | ||||
that the replay should start at the time specified. | ||||
If the stream does not support replay, per the | ||||
'replay-support' attribute returned by | ||||
the /restconf/streams resource, then the server MUST | ||||
return the HTTP error code 400 Bad Request. | ||||
This parameter is only allowed for GET methods on a | 9.2. YANG Library Module | |||
text/event-stream data resource. A 400 Bad Request error | ||||
is returned if used for other methods or resource types. | ||||
If this parameter is not present, then a replay subscription | The "ietf-yang-library" module defines monitoring information for the | |||
is not begin requested. It is not valid to specify start | YANG modules used by a RESTCONF server. | |||
times that are later than the current time. If the value | ||||
specified is earlier than the log can support, the replay | ||||
will begin with the earliest available notification"; | ||||
} | ||||
leaf stop-time { | The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] | |||
type yang:date-and-time; | are used by this module for some type definitions. | |||
description | ||||
"The 'stop-time' parameter is used with the | ||||
replay feature to indicate the newest notifications of | ||||
interest. This parameter MUST be used with and have a | ||||
value later than the 'start-time' parameter. | ||||
This parameter is only allowed for GET methods on a | RFC Ed.: update the date below with the date of RFC publication and | |||
text/event-stream data resource. A 400 Bad Request error | remove this note. | |||
is returned if used for other methods or resource types. | ||||
If this parameter is not present, the notifications will | <CODE BEGINS> file "ietf-yang-library@2014-10-07.yang" | |||
continue until the subscription is terminated. | ||||
Values in the future are valid."; | module ietf-yang-library { | |||
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library"; | ||||
prefix "yanglib"; | ||||
import ietf-yang-types { prefix yang; } | ||||
import ietf-inet-types { prefix inet; } | ||||
organization | ||||
"IETF NETCONF (Network Configuration) Working Group"; | ||||
contact | ||||
"WG Web: <http://tools.ietf.org/wg/netconf/> | ||||
WG List: <mailto:netconf@ietf.org> | ||||
WG Chair: Bert Wijnen | ||||
<mailto:bertietf@bwijnen.net> | ||||
WG Chair: Mehmet Ersue | ||||
<mailto:mehmet.ersue@nsn.com> | ||||
Editor: Andy Bierman | ||||
<mailto:andy@yumaworks.com> | ||||
Editor: Martin Bjorklund | ||||
<mailto:mbj@tail-f.com> | ||||
Editor: Kent Watsen | ||||
<mailto:kwatsen@juniper.net>"; | ||||
description | ||||
"This module contains monitoring information about the YANG | ||||
modules and submodules that are used within a RESTCONF | ||||
server. | ||||
Copyright (c) 2014 IETF Trust and the persons identified as | ||||
authors of the code. All rights reserved. | ||||
Redistribution and use in source and binary forms, with or | ||||
without modification, is permitted pursuant to, and subject | ||||
to the license terms contained in, the Simplified BSD License | ||||
set forth in Section 4.c of the IETF Trust's Legal Provisions | ||||
Relating to IETF Documents | ||||
(http://trustee.ietf.org/license-info). | ||||
This version of this YANG module is part of RFC XXXX; see | ||||
the RFC itself for full legal notices."; | ||||
// RFC Ed.: replace XXXX with actual RFC number and remove this | ||||
// note. | ||||
// RFC Ed.: remove this note | ||||
// Note: extracted from draft-ietf-netconf-restconf-02.txt | ||||
// RFC Ed.: update the date below with the date of RFC publication | ||||
// and remove this note. | ||||
revision 2014-09-26 { | ||||
description | ||||
"Initial revision."; | ||||
reference | ||||
"RFC XXXX: RESTCONF Protocol."; | ||||
} | ||||
typedef revision-identifier { | ||||
type string { | ||||
pattern '\d{4}-\d{2}-\d{2}'; | ||||
} | } | |||
description | ||||
"Represents a specific date in YYYY-MM-DD format. | ||||
TBD: make pattern more precise to exclude leading zeros."; | ||||
} | ||||
} // grouping query-parameters | grouping module { | |||
grouping notification { | ||||
description | description | |||
"Contains the notification message wrapper definition."; | "The module data structure is represented as a grouping | |||
so it can be reused in configuration or another monitoring | ||||
data structure."; | ||||
container notification { | grouping common-leafs { | |||
description | description | |||
"RESTCONF notification message wrapper."; | "Common parameters for YANG modules and submodules."; | |||
leaf event-time { | leaf name { | |||
type yang:date-and-time; | type yang:yang-identifier; | |||
description "The YANG module or submodule name."; | ||||
} | ||||
leaf revision { | ||||
type union { | ||||
type revision-identifier; | ||||
type string { length 0; } | ||||
} | ||||
description | ||||
"The YANG module or submodule revision date. | ||||
An empty string is used if no revision statement | ||||
is present in the YANG module or submodule."; | ||||
} | ||||
leaf schema { | ||||
type inet:uri; | ||||
description | ||||
"Contains a URL that represents the YANG schema | ||||
resource for this module or submodule. | ||||
This leaf will only be present if there is a URL | ||||
available for retrieval of the schema for this entry."; | ||||
} | ||||
} | ||||
list module { | ||||
key "name revision"; | ||||
description | ||||
"Each entry represents one module currently | ||||
supported by the server."; | ||||
uses common-leafs; | ||||
leaf namespace { | ||||
type inet:uri; | ||||
mandatory true; | mandatory true; | |||
description | description | |||
"The time the event was generated by the | "The XML namespace identifier for this module."; | |||
event source."; | ||||
reference | ||||
"RFC 5277, section 4, <eventTime> element."; | ||||
} | } | |||
leaf-list feature { | ||||
type yang:yang-identifier; | ||||
description | ||||
"List of YANG feature names from this module that are | ||||
supported by the server."; | ||||
} | ||||
leaf-list deviation { | ||||
type yang:yang-identifier; | ||||
description | ||||
"List of YANG deviation module names used by this | ||||
server to modify the conformance of the module | ||||
associated with this entry."; | ||||
} | ||||
leaf conformance { | ||||
type boolean; | ||||
mandatory true; | ||||
description | ||||
"If 'true', then the server is claiming conformance to | ||||
the YANG module identified in this entry. | ||||
/* The YANG-specific notification container is encoded | If 'false', then the server is not claiming any | |||
* after the 'event-time' element. The format | conformance for the YANG module identified by this | |||
* corresponds to the notificationContent element | entry. The module may be needed for reusable definitions | |||
* in RFC 5277, section 4. For example: | such as extensions, features, identifies, typedefs, | |||
* | or groupings."; | |||
* module example-one { | } | |||
* ... | container submodules { | |||
* notification event1 { ... } | description | |||
* | "Contains information about all the submodules used | |||
* } | by the parent module entry"; | |||
* | ||||
* Encoded as element 'event1' in the namespace | list submodule { | |||
* for module 'example-one'. | key "name revision"; | |||
*/ | description | |||
"Each entry represents one submodule within the | ||||
parent module."; | ||||
uses common-leafs; | ||||
} | ||||
} | ||||
} // list module | ||||
} // grouping module | ||||
container modules { | ||||
config false; | ||||
description | ||||
"Contains YANG module monitoring information."; | ||||
leaf module-set-id { | ||||
type string; | ||||
description | ||||
"Contains a server-specific identifier representing | ||||
the current set of modules and submodules. The | ||||
server MUST change the value of this leaf if the | ||||
information represented by the 'module' list instances | ||||
has changed."; | ||||
} | } | |||
} // grouping notification | ||||
uses module; | ||||
} | ||||
} | } | |||
<CODE ENDS> | <CODE ENDS> | |||
8. IANA Considerations | 10. IANA Considerations | |||
8.1. The "restconf" Relation Type | 10.1. The "restconf" Relation Type | |||
This specification registers the "restconf" relation type in the Link | This specification registers the "restconf" relation type in the Link | |||
Relation Type Registry defined by [RFC5988]: | Relation Type Registry defined by [RFC5988]: | |||
Relation Name: restconf | Relation Name: restconf | |||
Description: Identifies the root of RESTCONF API as configured | Description: Identifies the root of RESTCONF API as configured | |||
on this HTTP server. The "restconf" relation | on this HTTP server. The "restconf" relation | |||
defines the root of the API defined in RFCXXXX. | defines the root of the API defined in RFCXXXX. | |||
Subsequent revisions of RESTCONF will use alternate | Subsequent revisions of RESTCONF will use alternate | |||
relation values to support protocol versioning. | relation values to support protocol versioning. | |||
Reference: RFC XXXX | Reference: RFC XXXX | |||
` | ` | |||
8.2. YANG Module Registry | 10.2. YANG Module Registry | |||
This document registers one URI in the IETF XML registry [RFC3688]. | This document registers three URIs in the IETF XML registry | |||
Following the format in RFC 3688, the following registration is | [RFC3688]. Following the format in RFC 3688, the following | |||
requested to be made. | registration is requested to be made. | |||
URI: urn:ietf:params:xml:ns:yang:ietf-restconf | URI: urn:ietf:params:xml:ns:yang:ietf-restconf | |||
Registrant Contact: The NETMOD WG of the IETF. | Registrant Contact: The NETMOD WG of the IETF. | |||
XML: N/A, the requested URI is an XML namespace. | XML: N/A, the requested URI is an XML namespace. | |||
This document registers one YANG module in the YANG Module Names | URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring | |||
Registrant Contact: The NETMOD WG of the IETF. | ||||
XML: N/A, the requested URI is an XML namespace. | ||||
URI: urn:ietf:params:xml:ns:yang:ietf-yang-library | ||||
Registrant Contact: The NETMOD WG of the IETF. | ||||
XML: N/A, the requested URI is an XML namespace. | ||||
This document registers three YANG modules in the YANG Module Names | ||||
registry [RFC6020]. | registry [RFC6020]. | |||
name: ietf-restconf | name: ietf-restconf | |||
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf | namespace: urn:ietf:params:xml:ns:yang:ietf-restconf | |||
prefix: rc | prefix: rc | |||
// RFC Ed.: replace XXXX with RFC number and remove this note | // RFC Ed.: replace XXXX with RFC number and remove this note | |||
reference: RFC XXXX | reference: RFC XXXX | |||
8.3. application/yang Media Sub Types | name: ietf-restconf-monitoring | |||
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring | ||||
prefix: rcmon | ||||
// RFC Ed.: replace XXXX with RFC number and remove this note | ||||
reference: RFC XXXX | ||||
name: ietf-yang-library | ||||
namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library | ||||
prefix: yanglib | ||||
// RFC Ed.: replace XXXX with RFC number and remove this note | ||||
reference: RFC XXXX | ||||
10.3. application/yang Media Sub Types | ||||
The parent MIME media type for RESTCONF resources is application/ | The parent MIME media type for RESTCONF resources is application/ | |||
yang, which is defined in [RFC6020]. This document defines the | yang, which is defined in [RFC6020]. This document defines the | |||
following sub-types for this media type. | following sub-types for this media type. | |||
- api | - api | |||
- data | - data | |||
- datastore | - datastore | |||
- errors | - errors | |||
- operation | - operation | |||
skipping to change at page 63, line 5 | skipping to change at page 68, line 5 | |||
Encoding considerations: TBD | Encoding considerations: TBD | |||
Security considerations: TBD | Security considerations: TBD | |||
Interoperability considerations: TBD | Interoperability considerations: TBD | |||
// RFC Ed.: replace XXXX with RFC number and remove this note | // RFC Ed.: replace XXXX with RFC number and remove this note | |||
Published specification: RFC XXXX | Published specification: RFC XXXX | |||
9. Security Considerations | 10.4. NETCONF Capability URNs | |||
This document registers several capability identifiers in "Network | ||||
Configuration Protocol (NETCONF) Capability URNs" registry | ||||
Index | ||||
Capability Identifier | ||||
------------------------ | ||||
:content | ||||
urn:ietf:params:restconf:capability:content:1.0 | ||||
:depth | ||||
urn:ietf:params:restconf:capability:depth:1.0 | ||||
:filter | ||||
urn:ietf:params:restconf:capability:filter:1.0 | ||||
:insert | ||||
urn:ietf:params:restconf:capability:insert:1.0 | ||||
:select | ||||
urn:ietf:params:restconf:capability:select:1.0 | ||||
:replay | ||||
urn:ietf:params:restconf:capability:replay:1.0 | ||||
11. Security Considerations | ||||
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 [RFC2818]. Security considerations for the content | are defined in [RFC2818]. Security considerations for the content | |||
manipulated by RESTCONF can be found in the documents defining data | manipulated by RESTCONF can be found in the documents defining data | |||
models. | models. | |||
This document does not specify an authentication scheme, but it does | This document does not specify an authentication scheme, but it does | |||
require that an authenticated NETCONF username be associated with | require that an authenticated NETCONF username be associated with | |||
each HTTP request. The authentication scheme MAY be implemented in | each HTTP request. The authentication scheme MAY be implemented in | |||
the underlying transport layer (e.g., client certificates) or within | the underlying transport layer (e.g., client certificates) or within | |||
the HTTP layer (e.g., Basic Auth, OAuth, etc.). RESTCONF does not | the HTTP layer (e.g., Basic Auth, OAuth, etc.). RESTCONF does not | |||
itself define an authentication mechanism, authentication MUST occur | itself define an authentication mechanism, authentication MUST occur | |||
in a lower layer. Implementors SHOULD provide a comprehensive | in a lower layer. Implementors SHOULD provide a comprehensive | |||
authorization scheme with RESTCONF and ensure that the resulting | authorization scheme with RESTCONF and ensure that the resulting | |||
NETCONF username is made available to the RESTCONF server. | NETCONF username is made available to the RESTCONF server. | |||
Authorization of individual user access to operations and data MAY be | Authorization of individual user access to operations and data MAY be | |||
configured via NETCONF Access Control Model (NACM) [RFC6536], as | configured via NETCONF Access Control Model (NACM) [RFC6536], as | |||
specified in Section 2. Other authorization models MAY be used, but | specified in Section 3. Other authorization models MAY be used, but | |||
are outside of the scope of this document. | are outside of the scope of this document. | |||
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. Because of this, this protocol SHOULD be | |||
implemented carefully with adequate attention to all manner of attack | implemented carefully with adequate attention to all manner of attack | |||
one might expect to experience with other management interfaces. | one might expect to experience with other management interfaces. | |||
Different environments may well allow different rights prior to and | Different environments may well allow different rights prior to and | |||
then after authentication. When an operation is not properly | then after authentication. When an operation is not properly | |||
authorized, the RESTCONF server MUST return HTTP error status code | authorized, the RESTCONF server MUST return HTTP error status code | |||
401 Unauthorized. Note that authorization information can be | 401 Unauthorized. Note that authorization information can be | |||
exchanged in the form of configuration information, which is all the | exchanged in the form of configuration information, which is all the | |||
more reason to ensure the security of the connection. | more reason to ensure the security of the connection. | |||
10. References | 12. Acknowledgements | |||
10.1. Normative References | The authors would like to thank for following for lively discussions | |||
on list and in the halls (ordered by last name): Rex Fernando | ||||
13. References | ||||
13.1. Normative References | ||||
[I-D.lhotka-netmod-json] | [I-D.lhotka-netmod-json] | |||
Lhotka, L., "Modeling JSON Text with YANG", | Lhotka, L., "Modeling JSON Text with YANG", draft-lhotka- | |||
draft-lhotka-netmod-yang-json-02 (work in progress), | netmod-yang-json-02 (work in progress), September 2013. | |||
September 2013. | ||||
[JSON] Bray, T., Ed., "The JSON Data Interchange Format", | [JSON] Bray, T., Ed., "The JSON Data Interchange Format", draft- | |||
draft-ietf-json-rfc4627bis-10 (work in progress), | ietf-json-rfc4627bis-10 (work in progress), December 2013. | |||
December 2013. | ||||
[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. | |||
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol, Version 1.0", | [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol, Version 1.0", | |||
RFC 2246, January 1999. | RFC 2246, January 1999. | |||
[RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | |||
Resource Identifiers (URI): Generic Syntax", RFC 2396, | Resource Identifiers (URI): Generic Syntax", RFC 2396, | |||
August 1998. | August 1998. | |||
skipping to change at page 64, line 38 | skipping to change at page 70, line 11 | |||
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., | [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., | |||
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext | Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext | |||
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. | Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. | |||
[RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. | [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. | |||
[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, | Resource Identifier (URI): Generic Syntax", STD 66, RFC | |||
RFC 3986, January 2005. | 3986, January 2005. | |||
[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", | [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC | |||
RFC 5789, March 2010. | 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. | |||
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., | [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., | |||
and A. Bierman, Ed., "Network Configuration Protocol | and A. Bierman, Ed., "Network Configuration Protocol | |||
(NETCONF)", RFC 6241, June 2011. | (NETCONF)", RFC 6241, June 2011. | |||
[RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", | [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC | |||
RFC 6415, October 2011. | 6415, October 2011. | |||
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration | [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration | |||
Protocol (NETCONF) Access Control Model", RFC 6536, | Protocol (NETCONF) Access Control Model", RFC 6536, March | |||
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. | |||
[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>. | |||
[get-off-my-lawn] | [get-off-my-lawn] | |||
Nottingham, M., "URI Design and Ownership", Best Current | Nottingham, M., "URI Design and Ownership", Best Current | |||
Practice draft-ietf-appsawg-uri-get-off-my-lawn-05, | Practice draft-ietf-appsawg-uri-get-off-my-lawn-05, May | |||
May 2014. | 2014. | |||
[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. | |||
[wd-eventsource] | [wd-eventsource] | |||
Hickson, I., "Server-Sent Events", December 2012. | Hickson, I., "Server-Sent Events", December 2012. | |||
10.2. Informative References | 13.2. Informative References | |||
[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 | Version 1.0", World Wide Web Consortium Recommendation | |||
Recommendation REC-xpath-19991116, November 1999, | REC-xpath-19991116, November 1999, | |||
<http://www.w3.org/TR/1999/REC-xpath-19991116>. | <http://www.w3.org/TR/1999/REC-xpath-19991116>. | |||
Appendix A. Change Log | Appendix A. Change Log | |||
-- RFC Ed.: remove this section before publication. | -- RFC Ed.: remove this section before publication. | |||
A.1. 00 - 01 | A.1. 01 - 02 | |||
o moved query parameter definitions from the YANG module back to the | ||||
plain text sections | ||||
o made all query parameters optional to implement | ||||
o defined query parameter capability URI | ||||
o moved 'streams' to new YANG module (ietf-restconf-monitoring) | ||||
o added 'capabilities' container to new YANG module (ietf-restconf- | ||||
monitoring) | ||||
o moved 'modules' container to new YANG module (ietf-yang-library) | ||||
o added new leaf 'module-set-id' (ietf-yang-library) | ||||
o added new leaf 'conformance' (ietf-yang-library) | ||||
o changed 'schema' leaf to type inet:uri that returns the location | ||||
of the YANG schema (instead of returning the schema directly) | ||||
o changed 'events' leaf to type inet:uri that returns the location | ||||
of the event stream resource (instead of returning events | ||||
directly) | ||||
o changed examples for yang.api resource since the monitoring | ||||
information is no longer in this resource | ||||
o closed issue #1 'select parameter' since no objections to the | ||||
proposed syntax | ||||
o closed "encoding of list keys" issue since no objection to new | ||||
encoding of list keys in a target resource URI. | ||||
o moved open issues list to the issue tracker on github | ||||
A.2. 00 - 01 | ||||
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 67, line 5 | skipping to change at page 73, line 22 | |||
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.2. bierman:restconf-04 to ietf:restconf-00 | A.3. 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. | |||
B.1. select parameter | The RESTCONF issues are tracked on github.com: | |||
o What syntax should be used for the "select" query parameter? The | ||||
current choices are "XPath" and "path-expr". Perhaps an | ||||
additional parameter to identify the select string format is | ||||
needed to allow extensibility? | ||||
Status: solution proposal added by Martin. | ||||
B.2. netconf-state monitoring support | ||||
o Should long-term RESTCONF operations (i.e. SSE long-poll) be | ||||
considered sessions with regards to NETCONF monitoring "session" | ||||
list? If so, what text is needed in RESTCONF draft to standardize | ||||
the RESTCONF session entries? | ||||
Status: closed-update-pending | ||||
Resolution: | ||||
A new data structure to monitor streams can be added to the netconf- | ||||
state sub-tree. The session-id in this new data structure is not | ||||
restricted to the NETCONF-only rules for the sessions sub-tree. | ||||
B.3. secure transport | ||||
o Details to support secure operation over TLS are needed | ||||
Status: closed | ||||
o Security considerations need to be written | ||||
Status: closed | ||||
o Can call-home for RESTCONF be supported | ||||
Status: open | ||||
B.4. Encoding of key leafs in resource URIs | ||||
o The use of a forward slash '/' as the delimiter between key values | ||||
in a target resource URI is not not desirable. Only 1 segment per | ||||
YANG data node layer should be used. | ||||
Status: open | ||||
Proposals: | ||||
Example: list foo, int8 keys X and Y | ||||
Old: | ||||
/restconf/data/foo/19/22/foo-leaf | ||||
New: | ||||
/restconf/data/foo=19,22/foo-leaf | ||||
Or: | ||||
/restconf/data/foo/19,22/foo-leaf | ||||
B.5. get-bulk query parameters | ||||
o New query parameters (e.g., offset, limit) are needed to retrieve | ||||
a limited number of list instances. | ||||
Status: solution proposal pending | ||||
Resolution: This bulk retrieval mechanism will be added. | ||||
B.6. defaults handling | ||||
o The client does not really know what sort of defaults the server | ||||
will return in GET replies. Should the with-defaults query | ||||
parameter be added to RESTCONF? If so, should it be mandatory-to- | ||||
implement? | ||||
Status: open | ||||
B.7. protocol capability URIs | ||||
o The client does not know what vendor extensions (if any) are | ||||
implemented by the server. Should the server provide a read-only | ||||
container of capability URIs to identify protocol extensions? The | ||||
NETMOD WG may also want to extend the protocol in the future | ||||
without updating the core RESTCONF RFC. | ||||
Status: open | ||||
B.8. target resource list keys required for GET | ||||
o Should the client be able to GET all or a subset of all list | ||||
instances by issuing a GET without any list keys for the target | ||||
resource list? | ||||
GET /restconf/data/interfaces/interface | ||||
o Should a "collection" resource be required in order for such a | ||||
request to be considered valid by the server. | ||||
Status: open | https://github.com/netconf-wg/restconf/issues | |||
Appendix C. Example YANG Module | Appendix C. Example YANG Module | |||
The example YANG module used in this document represents a simple | The example YANG module used in this document represents a simple | |||
media jukebox interface. | media jukebox interface. | |||
YANG Tree Diagram for "example-jukebox" Module | YANG Tree Diagram for "example-jukebox" Module | |||
+--rw jukebox? | +--rw jukebox? | |||
+--rw library | +--rw library | |||
| +--rw artist [name] | | +--rw artist [name] | |||
| | +--rw name string | | | +--rw name string | |||
| | +--rw album [name] | | | +--rw album [name] | |||
| | +--rw name string | | | +--rw name string | |||
| | +--rw genre? identityref | | | +--rw genre? identityref | |||
| | +--rw year? uint16 | | | +--rw year? uint16 | |||
| | +--rw admin | | | +--rw admin | |||
| | | +--rw label? string | | | | +--rw label? string | |||
skipping to change at page 78, line 13 | skipping to change at page 80, line 27 | |||
The server might respond as follows: | The server might respond as follows: | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Date: Mon, 23 Apr 2012 17:01:00 GMT | Date: Mon, 23 Apr 2012 17:01:00 GMT | |||
Server: example-server | Server: example-server | |||
Content-Type: application/yang.api+json | Content-Type: application/yang.api+json | |||
{ | { | |||
"ietf-restconf:restconf": { | "ietf-restconf:restconf": { | |||
"data" : [ null ], | "data" : [ null ], | |||
"modules": { | ||||
"module": [ | ||||
{ | ||||
"name" : "example-jukebox", | ||||
"revision" : "2014-07-03", | ||||
"namespace" : "http://example.com/ns/example-jukebox", | ||||
"schema" : [ null ] | ||||
} | ||||
] | ||||
}, | ||||
"operations" : { | "operations" : { | |||
"play" : [ null ] | "play" : [ null ] | |||
}, | ||||
"streams" : { | ||||
"stream" : [ | ||||
{ | ||||
"name" : "NETCONF", | ||||
"description" : "default NETCONF event stream", | ||||
"replay-support" : true, | ||||
"replay-log-creation-time:" : "2007-07-08T00:00:00Z", | ||||
"events" : [ null ] | ||||
} | ||||
] | ||||
} | } | |||
} | } | |||
} | } | |||
To request that the response content to be encoded in XML, the | To request that the response content to be encoded in XML, the | |||
"Accept" header can be used, as in this example request: | "Accept" header can be used, as in this example request: | |||
GET /restconf HTTP/1.1 | GET /restconf HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Accept: application/yang.api+xml, | Accept: application/yang.api+xml, | |||
skipping to change at page 79, line 11 | skipping to change at page 81, line 4 | |||
The server will return the same response either way, which might be | The server will return the same response either way, which might be | |||
as follows : | as follows : | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Date: Mon, 23 Apr 2012 17:01:00 GMT | Date: Mon, 23 Apr 2012 17:01:00 GMT | |||
Server: example-server | Server: example-server | |||
Cache-Control: no-cache | Cache-Control: no-cache | |||
Pragma: no-cache | Pragma: no-cache | |||
Content-Type: application/yang.api+xml | Content-Type: application/yang.api+xml | |||
<restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> | <restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> | |||
<data/> | <data/> | |||
<modules> | ||||
<module> | ||||
<name>example-jukebox</name> | ||||
<revision>2014-07-03</revision> | ||||
<namespace> | ||||
http://example.com/ns/example-jukebox | ||||
</namespace> | ||||
<schema /> | ||||
</module> | ||||
</modules> | ||||
<operations> | <operations> | |||
<play xmlns="http://example.com/ns/example-jukebox"/> | <play xmlns="http://example.com/ns/example-jukebox"/> | |||
</operations> | </operations> | |||
<streams> | ||||
<stream> | ||||
<name>NETCONF</name> | ||||
<description>default NETCONF event stream | ||||
</description> | ||||
<replay-support>true</replay-support> | ||||
<replay-log-creation-time> | ||||
2007-07-08T00:00:00Z | ||||
</replay-log-creation-time> | ||||
<events/> | ||||
</stream> | ||||
</streams> | ||||
</restconf> | </restconf> | |||
D.1.2. Retrieve The Server Module Information | D.1.2. Retrieve The Server Module Information | |||
In this example the client is retrieving the modules resource from | In this example the client is retrieving the modules information from | |||
the server in JSON format: | the server in JSON format: | |||
GET /restconf/modules HTTP/1.1 | GET /restconf/data/modules HTTP/1.1 | |||
Host: example.com | Host: example.com | |||
Accept: application/yang.api+json, | Accept: application/yang.data+json, | |||
application/yang.errors+json | application/yang.errors+json | |||
The server might respond as follows. | The server might respond as follows. | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Date: Mon, 23 Apr 2012 17:01:00 GMT | Date: Mon, 23 Apr 2012 17:01:00 GMT | |||
Server: example-server | Server: example-server | |||
Cache-Control: no-cache | Cache-Control: no-cache | |||
Pragma: no-cache | Pragma: no-cache | |||
Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT | Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT | |||
Content-Type: application/yang.api+json | Content-Type: application/yang.data+json | |||
{ | { | |||
"ietf-restconf:modules": { | "ietf-yang-library:modules": { | |||
"module": [ | "module": [ | |||
{ | { | |||
"name" : "foo", | "name" : "foo", | |||
"revision" : "2012-01-02", | "revision" : "2012-01-02", | |||
"schema" : [null], | "schema" : "http://example.com/mymodules/foo/2012-01-02", | |||
"namespace" : "http://example.com/ns/foo", | "namespace" : "http://example.com/ns/foo", | |||
"feature" : [ "feature1", "feature2" ] | "feature" : [ "feature1", "feature2" ], | |||
"conformance" : true | ||||
}, | }, | |||
{ | { | |||
"name" : "foo-types", | "name" : "foo-types", | |||
"revision" : "2012-01-05", | "revision" : "2012-01-05", | |||
"schema" : | ||||
"http://example.com/mymodules/foo-types/2012-01-05", | ||||
"schema" : [null], | "schema" : [null], | |||
"namespace" : "http://example.com/ns/foo-types" | "namespace" : "http://example.com/ns/foo-types", | |||
"conformance" : false | ||||
}, | }, | |||
{ | { | |||
"name" : "bar", | "name" : "bar", | |||
"revision" : "2012-11-05", | "revision" : "2012-11-05", | |||
"schema" : [null], | "schema" : "http://example.com/mymodules/bar/2012-11-05", | |||
"namespace" : "http://example.com/ns/bar", | "namespace" : "http://example.com/ns/bar", | |||
"feature" : [ "bar-ext" ], | "feature" : [ "bar-ext" ], | |||
"conformance" : true, | ||||
"submodule" : [ | "submodule" : [ | |||
{ | { | |||
"name" : "bar-submod1", | "name" : "bar-submod1", | |||
"revision" : "2012-11-05", | "revision" : "2012-11-05", | |||
"schema" : [null] | "schema" : | |||
"http://example.com/mymodules/bar-submod1/2012-11-05" | ||||
}, | }, | |||
{ | { | |||
"name" : "bar-submod2", | "name" : "bar-submod2", | |||
"revision" : "2012-11-05", | "revision" : "2012-11-05", | |||
"schema" : [null] | "schema" : | |||
"http://example.com/mymodules/bar-submod2/2012-11-05" | ||||
} | } | |||
] | ] | |||
} | } | |||
] | ] | |||
} | } | |||
} | } | |||
D.1.3. Retrieve The Server Capability Information | ||||
In this example the client is retrieving the capability information | ||||
from the server in JSON format, and the server supports all the | ||||
RESTCONF query parameters, plus one vendor parameter: | ||||
GET /restconf/data/restconf-state/capabilities HTTP/1.1 | ||||
Host: example.com | ||||
Accept: application/yang.data+json, | ||||
application/yang.errors+json | ||||
The server might respond as follows. | ||||
HTTP/1.1 200 OK | ||||
Date: Mon, 23 Apr 2012 17:02:00 GMT | ||||
Server: example-server | ||||
Cache-Control: no-cache | ||||
Pragma: no-cache | ||||
Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT | ||||
Content-Type: application/yang.data+json | ||||
{ | ||||
"ietf-restconf-monitoring:capabilities": { | ||||
"capability": [ | ||||
"urn:ietf:params:restconf:capability:content:1.0", | ||||
"urn:ietf:params:restconf:capability:depth:1.0", | ||||
"urn:ietf:params:restconf:capability:filter:1.0", | ||||
"urn:ietf:params:restconf:capability:insert:1.0", | ||||
"urn:ietf:params:restconf:capability:point:1.0", | ||||
"urn:ietf:params:restconf:capability:select:1.0", | ||||
"urn:ietf:params:restconf:capability:start-time:1.0", | ||||
"urn:ietf:params:restconf:capability:stop-time:1.0", | ||||
"http://example.com/capabilities/myparam" | ||||
] | ||||
} | ||||
} | ||||
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 | |||
skipping to change at page 82, line 43 | skipping to change at page 85, line 26 | |||
In this example the datastore resource has changed since the time | In this example the datastore resource has changed since the time | |||
specified in the "If-Unmodified-Since" header. The server might | specified in the "If-Unmodified-Since" header. The server might | |||
respond: | respond: | |||
HTTP/1.1 412 Precondition Failed | HTTP/1.1 412 Precondition Failed | |||
Date: Mon, 23 Apr 2012 19:01:00 GMT | Date: Mon, 23 Apr 2012 19:01:00 GMT | |||
Server: example-server | Server: example-server | |||
Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT | Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT | |||
ETag: b34aed893a4c | ETag: b34aed893a4c | |||
D.3. Query String Parameter Examples | D.3. Query Parameter Examples | |||
D.3.1. "content" Parameter | D.3.1. "content" Parameter | |||
The "content" parameter is used to select the type of data child | The "content" parameter is used to select the type of data child | |||
resources (configuration and/or not configuration) that are returned | resources (configuration and/or not configuration) that are returned | |||
by the server for a GET method request. | by the server for a GET method request. | |||
In this example, a simple YANG list that has configuration and non- | In this example, a simple YANG list that has configuration and non- | |||
configuration child resources. | configuration child resources. | |||
skipping to change at page 88, line 42 | skipping to change at page 91, line 32 | |||
"description" : "example playlist 1", | "description" : "example playlist 1", | |||
"song" : [ null ] | "song" : [ null ] | |||
} | } | |||
], | ], | |||
"player" : { | "player" : { | |||
"gap" : 0.5 | "gap" : 0.5 | |||
} | } | |||
} | } | |||
} | } | |||
D.3.3. "filter" Parameter | D.3.3. "select" Parameter | |||
The following URIs show some examples of notification filter | ||||
specifications (lines wrapped for display purposes only): | ||||
// filter = /event/eventClass='fault' | ||||
GET /restconf/streams/stream=NETCONF/events? | ||||
filter=%2Fevent%2FeventClass%3D'fault' | ||||
// filter = /event/severityCode<=4 | In this example the client is retrieving the API resource, but | |||
GET /restconf/streams/stream=NETCONF/events? | selecting only the "name" and "revision" nodes from each module, in | |||
filter=%2Fevent%2FseverityCode%3C%3D4 | JSON format: | |||
// filter = /linkUp|/linkDown | GET /restconf/data?select=modules/module(name;revision) HTTP/1.1 | |||
GET /restconf/streams/stream=SNMP/events? | Host: example.com | |||
filter=%2FlinkUp%7C%2FlinkDown | Accept: application/yang.data+json, | |||
application/yang.errors+json | ||||
// filter = /*/reportingEntity/card!='Ethernet0' | The server might respond as follows. | |||
GET /restconf/streams/stream=NETCONF/events? | ||||
filter=%2F*%2FreportingEntity%2Fcard%21%3D'Ethernet0' | ||||
// filter = /*/email-addr[contains(.,'company.com')] | HTTP/1.1 200 OK | |||
GET /restconf/streams/stream=critical-syslog/events? | Date: Mon, 23 Apr 2012 17:01:00 GMT | |||
filter=%2F*%2Femail-addr[contains(.%2C'company.com')] | Server: example-server | |||
Content-Type: application/yang.data+json | ||||
// Note: the module name is used as prefix. | { | |||
// filter = (/example-mod:event1/name='joe' and | "ietf-yang-library:modules": { | |||
// /example-mod:event1/status='online') | "module": [ | |||
GET /restconf/streams/stream=NETCONF/events? | { | |||
filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and | "name" : "example-jukebox", | |||
%20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') | "revision" : "2014-07-03" | |||
}, | ||||
{ | ||||
"name" : "ietf-restconf-monitoring", | ||||
"revision" : "2014-10-07" | ||||
}, | ||||
{ | ||||
"name" : "ietf-yang-library", | ||||
"revision" : "2014-10-07" | ||||
} | ||||
] | ||||
} | ||||
} | ||||
D.3.4. "insert" Parameter | D.3.4. "insert" Parameter | |||
In this example, a new first entry in the "Foo-One" playlist is being | In this example, a new first entry in the "Foo-One" playlist is being | |||
created. | created. | |||
Request from client: | Request from client: | |||
POST /restconf/data/example-jukebox:jukebox/ | POST /restconf/data/example-jukebox:jukebox/ | |||
playlist=Foo-One?insert=first HTTP/1.1 | playlist=Foo-One?insert=first HTTP/1.1 | |||
skipping to change at page 90, line 48 | skipping to change at page 93, line 48 | |||
} | } | |||
Response from server: | Response from server: | |||
HTTP/1.1 204 No Content | HTTP/1.1 204 No Content | |||
Date: Mon, 23 Apr 2012 13:01:20 GMT | Date: Mon, 23 Apr 2012 13:01:20 GMT | |||
Server: example-server | Server: example-server | |||
Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT | Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT | |||
ETag: abcada438af | ETag: abcada438af | |||
D.3.6. "select" Parameter | D.3.6. "filter" Parameter | |||
In this example the client is retrieving the API resource, but | The following URIs show some examples of notification filter | |||
selecting only the "name" and "revision" nodes from each module, in | specifications (lines wrapped for display purposes only): | |||
JSON format: | ||||
GET /restconf?select=modules/module(name;revision) HTTP/1.1 | // filter = /event/eventClass='fault' | |||
Host: example.com | GET /mystreams/stream=NETCONF/events? | |||
Accept: application/yang.api+json, | filter=%2Fevent%2FeventClass%3D'fault' | |||
application/yang.errors+json | ||||
The server might respond as follows. | // filter = /event/severityCode<=4 | |||
GET /mystreams/stream=NETCONF/events? | ||||
filter=%2Fevent%2FseverityCode%3C%3D4 | ||||
HTTP/1.1 200 OK | // filter = /linkUp|/linkDown | |||
Date: Mon, 23 Apr 2012 17:01:00 GMT | GET /mystreams/stream=SNMP/events? | |||
Server: example-server | filter=%2FlinkUp%7C%2FlinkDown | |||
Content-Type: application/yang.api+json | ||||
{ | // filter = /*/reportingEntity/card!='Ethernet0' | |||
"ietf-restconf:restconf": { | GET /mystreams/stream=NETCONF/events? | |||
"modules": { | filter=%2F*%2FreportingEntity%2Fcard%21%3D'Ethernet0' | |||
"module": [ | ||||
{ | // filter = /*/email-addr[contains(.,'company.com')] | |||
"name" : "example-jukebox", | GET /mystreams/stream=critical-syslog/events? | |||
"revision" : "2014-07-03" | filter=%2F*%2Femail-addr[contains(.%2C'company.com')] | |||
} | ||||
] | // Note: the module name is used as prefix. | |||
} | // filter = (/example-mod:event1/name='joe' and | |||
} | // /example-mod:event1/status='online') | |||
} | GET /mystreams/stream=NETCONF/events? | |||
filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and | ||||
%20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') | ||||
D.3.7. "start-time" Parameter | D.3.7. "start-time" Parameter | |||
TBD | TBD | |||
D.3.8. "stop-time" Parameter | D.3.8. "stop-time" Parameter | |||
TBD | TBD | |||
Authors' Addresses | Authors' Addresses | |||
skipping to change at page 92, line 16 | skipping to change at page 95, line 4 | |||
Andy Bierman | Andy Bierman | |||
YumaWorks | YumaWorks | |||
Email: andy@yumaworks.com | Email: andy@yumaworks.com | |||
Martin Bjorklund | Martin Bjorklund | |||
Tail-f Systems | Tail-f Systems | |||
Email: mbj@tail-f.com | Email: mbj@tail-f.com | |||
Kent Watsen | Kent Watsen | |||
Juniper Networks | Juniper Networks | |||
Email: kwatsen@juniper.net | Email: kwatsen@juniper.net | |||
Rex Fernando | ||||
Cisco | ||||
Email: rex@cisco.com | ||||
End of changes. 181 change blocks. | ||||
1389 lines changed or deleted | 1699 lines changed or added | |||
This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |