draft-ietf-netconf-restconf-11.txt   draft-ietf-netconf-restconf-12.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track M. Bjorklund Intended status: Standards Track M. Bjorklund
Expires: October 12, 2016 Tail-f Systems Expires: October 14, 2016 Tail-f Systems
K. Watsen K. Watsen
Juniper Networks Juniper Networks
April 10, 2016 April 12, 2016
RESTCONF Protocol RESTCONF Protocol
draft-ietf-netconf-restconf-11 draft-ietf-netconf-restconf-12
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
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 12, 2016. This Internet-Draft will expire on October 14, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 48 skipping to change at page 2, line 48
3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 17 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 17
3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18
3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 18 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 18
3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19
3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 19 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 19
3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20
3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21
3.5.1. Encoding Data Resource Identifiers in the Request URI 22 3.5.1. Encoding Data Resource Identifiers in the Request URI 22
3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 25 3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 25
3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 25 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 25
3.6.1. Encoding Operation Resource Input Parameters . . . . 27 3.6.1. Encoding Operation Resource Input Parameters . . . . 26
3.6.2. Encoding Operation Resource Output Parameters . . . . 30 3.6.2. Encoding Operation Resource Output Parameters . . . . 29
3.6.3. Encoding Operation Resource Errors . . . . . . . . . 31 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 31
3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 33 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 32
3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 34 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 33
3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 34 3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 34
4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 34 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 37 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 37
4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 38 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 38
4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 42 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 41
4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 43 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 43 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 43
4.8.1. The "content" Query Parameter . . . . . . . . . . . . 44 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 44
4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 45 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 45
4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 45 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 45
4.8.4. The "insert" Query Parameter . . . . . . . . . . . . 46 4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 46
4.8.5. The "point" Query Parameter . . . . . . . . . . . . . 47 4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 47
4.8.6. The "filter" Query Parameter . . . . . . . . . . . . 47 4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 48
4.8.7. The "start-time" Query Parameter . . . . . . . . . . 48 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 48
4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 49 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 49
4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 50 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 50
5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 51 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 51 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 51
5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 52 5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 52
5.3. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 53 5.3. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 53
5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 53 5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 53
5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 54 5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 54
5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 54 5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 54
5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 54 5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 54
6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 55 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 55
6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 55 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 55
6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 55 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 55
6.3. Subscribing to Receive Notifications . . . . . . . . . . 58 6.3. Subscribing to Receive Notifications . . . . . . . . . . 57
6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 59 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 58
6.4. Receiving Event Notifications . . . . . . . . . . . . . . 59 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 58
7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 61 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 60
7.1. Error Response Message . . . . . . . . . . . . . . . . . 63 7.1. Error Response Message . . . . . . . . . . . . . . . . . 62
8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 65 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 64
9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 71 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 70
9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 71 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 70
9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 72 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 71
9.1.2. The "defaults" Protocol Capability URI . . . . . . . 72 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 71
9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 73 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 72
9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 74 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 72
10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 77 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 76
10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 77 10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 76
10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 78 10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 77
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77
11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 78 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 77
11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 78 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 77
11.3. application/yang Media Sub Types . . . . . . . . . . . . 79 11.3. application/yang Media Sub Types . . . . . . . . . . . . 78
11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 80 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 79
12. Security Considerations . . . . . . . . . . . . . . . . . . . 81 12. Security Considerations . . . . . . . . . . . . . . . . . . . 79
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 82 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 80
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 82 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 81
14.1. Normative References . . . . . . . . . . . . . . . . . . 82 14.1. Normative References . . . . . . . . . . . . . . . . . . 81
14.2. Informative References . . . . . . . . . . . . . . . . . 85 14.2. Informative References . . . . . . . . . . . . . . . . . 83
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 85 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 84
A.1. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 85 A.1. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 84
A.2. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 86 A.2. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 84
A.3. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.3. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 85
A.4. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.4. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 87
A.5. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 89 A.5. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 87
A.6. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 89 A.6. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 88
A.7. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 89 A.7. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 88
A.8. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 90 A.8. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 88
A.9. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 91 A.9. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 89
A.10. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 91 A.10. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 90
A.11. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 92 A.11. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 90
A.12. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 93 A.12. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 91
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 93 A.13. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 92
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 93 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 92
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 94 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 92
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 99 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 93
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 99 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 98
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 99 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 98
D.1.2. Retrieve The Server Module Information . . . . . . . 100 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 98
D.1.3. Retrieve The Server Capability Information . . . . . 102 D.1.2. Retrieve The Server Module Information . . . . . . . 99
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 103 D.1.3. Retrieve The Server Capability Information . . . . . 101
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 103 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 102
D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 104 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 102
D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 104 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 103
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 105 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 103
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 105 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 104
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 108 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 104
D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 111 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 107
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 112 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 110
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 112 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 111
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 113 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 111
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 114 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 112
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 114 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 113
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 114 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 113
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 116 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 113
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 115
1. Introduction 1. Introduction
There is a need for standard mechanisms to allow Web applications to There is a need for standard mechanisms to allow Web applications to
access the configuration data, state data, data-model specific access the configuration data, state data, data-model specific
protocol operations, and event notifications within a networking protocol operations, and event notifications within a networking
device, in a modular and extensible manner. device, in a modular and extensible manner.
This document defines an HTTP [RFC7230] based protocol called This document defines an HTTP [RFC7230] based protocol called
RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or
skipping to change at page 20, line 25 skipping to change at page 20, line 25
for datastore and data resources. for datastore and data resources.
3.4.1.1. Timestamp 3.4.1.1. Timestamp
The last change time is maintained and the "Last-Modified" The last change time is maintained and the "Last-Modified"
([RFC7232], Section 2.2) header is returned in the response for a ([RFC7232], Section 2.2) header is returned in the response for a
retrieval request. The "If-Unmodified-Since" header can be used in retrieval request. The "If-Unmodified-Since" header can be used in
edit operation requests to cause the server to reject the request if edit operation requests to cause the server to reject the request if
the resource has been modified since the specified timestamp. the resource has been modified since the specified timestamp.
The server MUST maintain a last-modified timestamp for the top-level The server SHOULD maintain a last-modified timestamp for the top-
{+restconf}/data resource. This timestamp is only affected by level {+restconf}/data resource. This timestamp is only affected by
configuration data resources, and MUST NOT be updated for changes to configuration data resources, and MUST NOT be updated for changes to
non-configuration data. non-configuration data.
3.4.1.2. Entity tag 3.4.1.2. Entity tag
A unique opaque string is maintained and the "ETag" ([RFC7232], A unique opaque string is maintained and the "ETag" ([RFC7232],
Section 2.3) header is returned in the response for a retrieval Section 2.3) header is returned in the response for a retrieval
request. The "If-Match" header can be used in edit operation request. The "If-Match" header can be used in edit operation
requests to cause the server to reject the request if the resource requests to cause the server to reject the request if the resource
entity tag does not match the specified value. entity tag does not match the specified value.
skipping to change at page 21, line 19 skipping to change at page 21, line 19
A data resource represents a YANG data node that is a descendant node A data resource represents a YANG data node that is a descendant node
of a datastore resource. Each YANG-defined data node can be uniquely of a datastore resource. Each YANG-defined data node can be uniquely
targeted by the request-line of an HTTP operation. Containers, targeted by the request-line of an HTTP operation. Containers,
leafs, leaf-list entries, list entries, anydata and anyxml nodes are leafs, leaf-list entries, list entries, anydata and anyxml nodes are
data resources. data resources.
The representation maintained for each data resource is the YANG The representation maintained for each data resource is the YANG
defined subtree for that node. HTTP operations on a data resource defined subtree for that node. HTTP operations on a data resource
affect both the targeted data node and all its descendants, if any. affect both the targeted data node and all its descendants, if any.
For configuration data resources, the server SHOULD maintain a last- For configuration data resources, the server MAY maintain a last-
modified timestamp for the resource, and return the "Last-Modified" modified timestamp for the resource, and return the "Last-Modified"
header when it is retrieved with the GET or HEAD methods. header when it is retrieved with the GET or HEAD methods.
The "Last-Modified" header information can be used by a RESTCONF The "Last-Modified" header information can be used by a RESTCONF
client in subsequent requests, within the "If-Modified-Since" and client in subsequent requests, within the "If-Modified-Since" and
"If-Unmodified-Since" headers. "If-Unmodified-Since" headers.
If maintained, the resource timestamp MUST be set to the current time If maintained, the resource timestamp MUST be set to the current time
whenever the resource or any configuration resource within the whenever the resource or any configuration resource within the
resource is altered. If not maintained, then the resource timestamp resource is altered. If not maintained, then the resource timestamp
skipping to change at page 22, line 14 skipping to change at page 22, line 14
A data resource can be retrieved with the GET method. Data resources A data resource can be retrieved with the GET method. Data resources
are accessed via the "{+restconf}/data" entry point. This sub-tree are accessed via the "{+restconf}/data" entry point. This sub-tree
is used to retrieve and edit data resources. is used to retrieve and edit data resources.
A configuration data resource can be altered by the client with some A configuration data resource can be altered by the client with some
or all of the edit operations, depending on the target resource and or all of the edit operations, depending on the target resource and
the specific operation. Refer to Section 4 for more details on edit the specific operation. Refer to Section 4 for more details on edit
operations. 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.
3.5.1. Encoding Data Resource Identifiers in the Request URI 3.5.1. Encoding Data Resource Identifiers in the Request URI
In YANG, data nodes are named with an absolute XPath expression, In YANG, data nodes are identified with an absolute XPath expression,
defined in [XPath], starting from the document root to the target defined in [XPath], starting from the document root to the target
resource. In RESTCONF, URL encoded path expressions are used resource. In RESTCONF, URI-encoded path expressions are used
instead. instead.
A predictable location for a data resource is important, since A predictable location for a data resource is important, since
applications will code to the YANG data model module, which uses applications will code to the YANG data model module, which uses
static naming and defines an absolute path location for all data static naming and defines an absolute path location for all data
nodes. nodes.
A RESTCONF data resource identifier is not an XPath expression. It A RESTCONF data resource identifier is not an XPath expression. It
is encoded from left to right, starting with the top-level data node, is encoded from left to right, starting with the top-level data node,
according to the "api-path" rule in Section 3.5.1.1. The node name according to the "api-path" rule in Section 3.5.1.1. The node name
skipping to change at page 40, line 5 skipping to change at page 39, line 45
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
data resource. A request message-body MUST be present, representing data resource. A request message-body MUST be present, representing
the new data resource, or the server MUST return "400 Bad Request" the new data resource, or the server MUST return "400 Bad Request"
status-line. status-line.
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" (Section 4.8.4) and "point" (Section 4.8.5) query The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query
parameters MUST be supported by the PUT method for data resources. parameters MUST be supported by the PUT method for data resources.
These parameters are only allowed if the list or leaf-list is These parameters are only allowed if the list or leaf-list is
ordered-by user. ordered-by user.
Consistent with [RFC7231], if the PUT request creates a new resource, Consistent with [RFC7231], if the PUT request creates a new resource,
a "201 Created" status-line is returned. If an existing resource is a "201 Created" status-line is returned. If an existing resource is
modified, a "204 No Content" status-line is returned. modified, a "204 No Content" status-line is returned.
If the user is not authorized to create or replace the target If the user is not authorized to create or replace the target
resource an error response containing a "403 Forbidden" status-line resource an error response containing a "403 Forbidden" status-line
skipping to change at page 43, line 45 skipping to change at page 43, line 39
Date: Mon, 23 Apr 2012 17:49:40 GMT Date: Mon, 23 Apr 2012 17:49:40 GMT
Server: example-server Server: example-server
4.8. Query Parameters 4.8. Query Parameters
Each RESTCONF operation allows zero or more query parameters to be Each RESTCONF operation allows zero or more query parameters to be
present in the request URI. The specific parameters that are allowed present in the request URI. The specific parameters that are allowed
depends on the resource type, and sometimes the specific target depends on the resource type, and sometimes the specific target
resource used, in the request. resource used, in the request.
o Query parameters can be given in any order.
o Each parameter can appear at most once in a request URI.
o A default value may apply if the parameter is missing.
o Query parameter names and values are case-sensitive
o A server MUST return an error with a '400 Bad Request' status-line
if a query parameter is unexpected.
+-------------------+-------------+---------------------------------+ +-------------------+-------------+---------------------------------+
| Name | Methods | Description | | Name | Methods | Description |
+-------------------+-------------+---------------------------------+ +-------------------+-------------+---------------------------------+
| content | GET | Select config and/or non-config | | content | GET | Select config and/or non-config |
| | | data resources | | | | data resources |
| depth | GET | Request limited sub-tree depth | | depth | GET | Request limited sub-tree depth |
| | | in the reply content | | | | in the reply content |
| fields | GET | Request a subset of the target | | fields | GET | Request a subset of the target |
| | | resource contents | | | | resource contents |
| filter | GET | Boolean notification filter for | | filter | GET | Boolean notification filter for |
skipping to change at page 44, line 21 skipping to change at page 44, line 26
| start-time | GET | Replay buffer start time for | | start-time | GET | Replay buffer start time for |
| | | event stream resources | | | | event stream resources |
| stop-time | GET | Replay buffer stop time for | | stop-time | GET | Replay buffer stop time for |
| | | event stream resources | | | | event stream resources |
| with-defaults | GET | Control retrieval of default | | with-defaults | GET | Control retrieval of default |
| | | values | | | | values |
+-------------------+-------------+---------------------------------+ +-------------------+-------------+---------------------------------+
RESTCONF Query Parameters RESTCONF Query Parameters
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
the parameter is missing.
Refer to Appendix D.3 for examples of query parameter usage. Refer to Appendix D.3 for examples of query parameter usage.
If vendors define additional query parameters, they SHOULD use a If vendors define additional query parameters, they SHOULD use a
prefix (such as the enterprise or organization name) for query prefix (such as the enterprise or organization name) for query
parameter names in order to avoid collisions with other parameters. parameter names in order to avoid collisions with other parameters.
4.8.1. The "content" Query Parameter 4.8.1. The "content" Query Parameter
The "content" parameter controls how descendant nodes of the The "content" parameter controls how descendant nodes of the
requested data nodes will be processed in the reply. requested data nodes will be processed in the reply.
skipping to change at page 45, line 31 skipping to change at page 45, line 34
data resources. A "400 Bad Request" status-line is returned if it data resources. A "400 Bad Request" status-line is returned if it
used for other methods or resource types. used for other methods or resource types.
More than one "depth" query parameter MUST NOT appear in a request. More than one "depth" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request" If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server. status-line MUST be returned by the server.
By default, the server will include all sub-resources within a By default, the server will include all sub-resources within a
retrieved resource, which have the same resource type as the retrieved resource, which have the same resource type as the
requested resource. Only one level of sub-resources with a different requested resource. Only one level of sub-resources with a different
media type than the target resource will be returned. media type than the target resource will be returned. The exception
is the datastore resource. If this resource type is retrieved then
by default the datastore and all child data resources are returned.
If the "depth" query parameter URI is listed in the "capability" If the "depth" query parameter URI is listed in the "capability"
leaf-list in Section 9.3, then the server supports the "depth" query leaf-list in Section 9.3, then the server supports the "depth" query
parameter. parameter.
4.8.3. The "fields" Query Parameter 4.8.3. The "fields" Query Parameter
The "fields" query parameter is used to optionally identify data The "fields" query parameter is used to optionally identify data
nodes within the target resource to be retrieved in a GET method. nodes within the target resource to be retrieved in a GET method.
The client can use this parameter to retrieve a subset of all nodes The client can use this parameter to retrieve a subset of all nodes
skipping to change at page 46, line 31 skipping to change at page 46, line 35
for other methods or resource types. for other methods or resource types.
More than one "fields" query parameter MUST NOT appear in a request. More than one "fields" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request" If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server. status-line MUST be returned by the server.
If the "fields" query parameter URI is listed in the "capability" If the "fields" query parameter URI is listed in the "capability"
leaf-list in Section 9.3, then the server supports the "fields" leaf-list in Section 9.3, then the server supports the "fields"
parameter. parameter.
4.8.4. The "insert" Query Parameter 4.8.4. 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" status-line 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.
More than one "filter" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server.
The filter is used as defined in [RFC5277], Section 3.6. If the
boolean result of the expression is true when applied to the
conceptual "notification" document root, then the event notification
is delivered to the client.
If the "filter" query parameter URI is listed in the "capability"
leaf-list in Section 9.3, then the server supports the "filter" query
parameter.
4.8.5. The "insert" Query Parameter
The "insert" parameter is used to specify how a resource should be The "insert" parameter is used to specify how a resource should be
inserted within a ordered-by user list. inserted within a ordered-by user list.
The allowed values are: The allowed values are:
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
| Value | Description | | Value | Description |
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
| first | Insert the new data as the new first entry. | | first | Insert the new data as the new first entry. |
skipping to change at page 47, line 17 skipping to change at page 48, line 11
More than one "insert" query parameter MUST NOT appear in a request. More than one "insert" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request" If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server. status-line MUST be returned by the server.
If the values "before" or "after" are used, then a "point" query If the values "before" or "after" are used, then a "point" query
parameter for the insertion parameter MUST also be present, or a "400 parameter for the insertion parameter MUST also be present, or a "400
Bad Request" status-line is returned. Bad Request" status-line is returned.
The "insert" query parameter MUST be supported by the server. The "insert" query parameter MUST be supported by the server.
4.8.5. The "point" Query Parameter 4.8.6. The "point" Query Parameter
The "point" parameter is used to specify the insertion point for a The "point" parameter is used to specify the insertion point for a
data resource that is being created or moved within an ordered-by data resource that is being created or moved within an ordered-by
user list or leaf-list. user list or leaf-list.
The value of the "point" parameter is a string that identifies the The value of the "point" parameter is a string that identifies the
path to the insertion point object. The format is the same as a path to the insertion point object. The format is the same as a
target resource URI string. target resource URI string.
This parameter is only supported for the POST and PUT methods. It is This parameter is only supported for the POST and PUT methods. It is
skipping to change at page 47, line 45 skipping to change at page 48, line 39
More than one "point" query parameter MUST NOT appear in a request. More than one "point" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request" If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server. status-line MUST be returned by the server.
This parameter contains the instance identifier of the resource to be This parameter contains the instance identifier of the resource to be
used as the insertion point for a POST or PUT method. used as the insertion point for a POST or PUT method.
The "point" query parameter MUST be supported by the server. The "point" query parameter MUST be supported by the server.
4.8.6. 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" status-line 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.
More than one "filter" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server.
The filter is used as defined in [RFC5277], Section 3.6. If the
boolean result of the expression is true when applied to the
conceptual "notification" document root, then the event notification
is delivered to the client.
If the "filter" query parameter URI is listed in the "capability"
leaf-list in Section 9.3, then the server supports the "filter" query
parameter.
4.8.7. The "start-time" Query Parameter 4.8.7. The "start-time" Query Parameter
The "start-time" parameter is used to trigger the notification replay The "start-time" parameter is used to trigger the notification replay
feature and indicate that the replay should start at the time feature and indicate that the replay should start at the time
specified. If the stream does not support replay, per the specified. If the stream does not support replay, per the
"replay-support" attribute returned by stream list entry for the "replay-support" attribute returned by stream list entry for the
stream resource, then the server MUST return a "400 Bad Request" stream resource, then the server MUST return a "400 Bad Request"
status-line. status-line.
The value of the "start-time" parameter is of type "date-and-time", The value of the "start-time" parameter is of type "date-and-time",
skipping to change at page 49, line 20 skipping to change at page 49, line 24
being requested. It is not valid to specify start times that are being requested. It is not valid to specify start times that are
later than the current time. If the value specified is earlier than later than the current time. If the value specified is earlier than
the log can support, the replay will begin with the earliest the log can support, the replay will begin with the earliest
available notification. available notification.
If this query parameter is supported by the server, then the "replay" If this query parameter is supported by the server, then the "replay"
query parameter URI MUST be listed in the "capability" leaf-list in query parameter URI MUST be listed in the "capability" leaf-list in
Section 9.3. The "stop-time" query parameter MUST also be supported Section 9.3. The "stop-time" query parameter MUST also be supported
by the server. by the server.
If the "replay-support" leaf is present in the "stream" entry If the "replay-support" leaf has the value 'true' in the "stream"
(defined in Section 9.3) then the server MUST support the entry (defined in Section 9.3) then the server MUST support the
"start-time" and "stop-time" query parameters for that stream. "start-time" and "stop-time" query parameters for that stream.
4.8.8. The "stop-time" Query Parameter 4.8.8. The "stop-time" Query Parameter
The "stop-time" parameter is used with the replay feature to indicate The "stop-time" parameter is used with the replay feature to indicate
the newest notifications of interest. This parameter MUST be used the newest notifications of interest. This parameter MUST be used
with and have a value later than the "start-time" parameter. with and have a value later than the "start-time" parameter.
The value of the "stop-time" parameter is of type "date-and-time", The value of the "stop-time" parameter is of type "date-and-time",
defined in the "ietf-yang" YANG module [RFC6991]. defined in the "ietf-yang" YANG module [RFC6991].
skipping to change at page 59, line 25 skipping to change at page 58, line 30
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. These query parameters are optional to implement, and only receive. These query parameters are optional to implement, and only
available if the server supports them. available if the server supports them.
+------------+---------+-------------------------+ +------------+---------+-------------------------+
| Name | Section | Description | | Name | Section | Description |
+------------+---------+-------------------------+ +------------+---------+-------------------------+
| start-time | 4.8.7 | replay event start time | | start-time | 4.8.7 | replay event start time |
| stop-time | 4.8.8 | replay event stop time | | stop-time | 4.8.8 | replay event stop time |
| filter | 4.8.6 | boolean content filter | | filter | 4.8.4 | 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 sections listed above. The YANG encoding MUST be converted to the sections listed above. The YANG definition MUST be converted to
URL-encoded string for use in the request URI. a URI-encoded string for use in the request URI.
Refer to Appendix D.3.6 for filter parameter examples. Refer to Appendix D.3.6 for filter parameter examples.
6.4. Receiving Event Notifications 6.4. Receiving Event Notifications
RESTCONF notifications are encoded according to the definition of the RESTCONF notifications are encoded according to the definition of the
event stream. The NETCONF stream defined in [RFC5277] is encoded in event stream. The NETCONF stream defined in [RFC5277] is encoded in
XML format. XML format.
The structure of the event data is based on the "notification" The structure of the event data is based on the "notification"
skipping to change at page 63, line 14 skipping to change at page 62, line 20
| operation-not-supported | 501 | | operation-not-supported | 501 |
| operation-failed | 500 | | operation-failed | 500 |
| partial-operation | 500 | | partial-operation | 500 |
| malformed-message | 400 | | malformed-message | 400 |
+-------------------------+-------------+ +-------------------------+-------------+
Mapping from error-tag to status code Mapping from error-tag to status code
7.1. Error Response Message 7.1. Error Response Message
When an error occurs for a request message on a data resource or an When an error occurs for a request message on any resource type, and
operation resource, and a "4xx" class of status codes will be a "4xx" class of status codes will be returned (except for status
returned (except for status code "403 Forbidden"), then the server code "403 Forbidden"), then the server SHOULD send a response
SHOULD send a response message-body containing the information message-body containing the information described by the "errors"
described by the "errors" container definition within the YANG module container definition within the YANG module Section 8. The Content-
Section 8. The Content-Type of this response message MUST be Type of this response message MUST be a subtype of application/
application/yang.errors (see example below). yang.errors (see example below).
The client MAY specify the desired encoding for error messages by The client SHOULD specify the desired encoding for error messages by
specifying the appropriate media-type in the Accept header. If no specifying the appropriate media-type in the Accept header. If no
error media is specified, then the media type of the request message error media is specified, then the media subtype (e.g., XML or JSON)
SHOULD be used, or the server MAY choose any supported message of the request message SHOULD be used, or the server MAY choose any
encoding format. If there is no request message the server MUST supported message encoding format. If there is no request message
select "application/yang.errors+xml" or "application/ the server MUST select "application/yang.errors+xml" or "application/
yang.errors+json", depending on server preference. All of the yang.errors+json", depending on server preference. All of the
examples in this document, except for the one below, assume that XML examples in this document, except for the one below, assume that XML
encoding will be returned if there is an error. encoding will be returned if there is an error.
YANG Tree Diagram for <errors> data: YANG Tree Diagram for <errors> data:
+--ro errors +--ro errors
+--ro error* +--ro error*
+--ro error-type enumeration +--ro error-type enumeration
+--ro error-tag string +--ro error-tag string
skipping to change at page 64, line 5 skipping to change at page 63, line 11
The semantics and syntax for RESTCONF error messages are defined in The semantics and syntax for RESTCONF error messages are defined in
the "application/yang.errors" restconf-media-type extension in the "application/yang.errors" restconf-media-type extension in
Section 8. Section 8.
Examples: Examples:
The following example shows an error returned for an "lock-denied" The following example shows an error returned for an "lock-denied"
error that can occur if a NETCONF client has locked a datastore. The error that can occur if a NETCONF client has locked a datastore. The
RESTCONF client is attempting to delete a data resource. Note that RESTCONF client is attempting to delete a data resource. Note that
an Accept header is used to specify the desired encoding for the an Accept header is used to specify the desired encoding for the
error message. This example's use of the Accept header is especially error message. No response message-body content is expected by the
notable since the DELETE method typically doesn't return a message- client in this example.
body and hence Accept headers are typically not passed.
DELETE /restconf/data/example-jukebox:jukebox/ DELETE /restconf/data/example-jukebox:jukebox/
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.errors+json Accept: application/yang.errors+json
The server might respond: The server might respond:
HTTP/1.1 409 Conflict HTTP/1.1 409 Conflict
Date: Mon, 23 Apr 2012 17:11:00 GMT Date: Mon, 23 Apr 2012 17:11:00 GMT
skipping to change at page 65, line 30 skipping to change at page 64, line 33
datastore contents by a server. E.g., the "restconf" container is datastore contents by a server. E.g., the "restconf" container is
not intended to be implemented as a top-level data node (under the "/ not intended to be implemented as a top-level data node (under the "/
restconf/data" entry point). restconf/data" entry point).
RFC Ed.: update the date below with the date of RFC publication and RFC Ed.: update the date below with the date of RFC publication and
remove this note. remove this note.
<CODE BEGINS> file "ietf-restconf@2016-03-16.yang" <CODE BEGINS> file "ietf-restconf@2016-03-16.yang"
module ietf-restconf { module ietf-restconf {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; namespace "urn:ietf:params:xml:ns:yang:ietf-restconf";
prefix "rc"; prefix "rc";
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
contact contact
"WG Web: <http://tools.ietf.org/wg/netconf/> "WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org> WG List: <mailto:netconf@ietf.org>
skipping to change at page 66, line 36 skipping to change at page 65, line 39
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from draft-ietf-netconf-restconf-11.txt // Note: extracted from draft-ietf-netconf-restconf-12.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2016-03-16 { revision 2016-03-16 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
skipping to change at page 69, line 41 skipping to change at page 68, line 44
"The YANG instance identifier associated "The YANG instance identifier associated
with the error node."; with the error node.";
} }
leaf error-message { leaf error-message {
type string; type string;
description description
"A message describing the error."; "A message describing the error.";
} }
anyxml error-info { anydata error-info {
description description
"This anyxml value MUST represent a container with "This anydata value MUST represent a container with
zero or more data nodes representing additional zero or more data nodes representing additional
error information."; error information.";
} }
} }
} }
} }
grouping restconf { grouping restconf {
description description
"Conceptual container representing the "Conceptual container representing the
application/yang.api resource type."; application/yang.api resource type.";
container restconf { container restconf {
description description
"Conceptual container representing the "Conceptual container representing the
skipping to change at page 72, line 27 skipping to change at page 71, line 30
optional query parameter that it supports. optional query parameter that it supports.
+-------------+-------+---------------------------------------------+ +-------------+-------+---------------------------------------------+
| Name | Secti | URI | | Name | Secti | URI |
| | on | | | | on | |
+-------------+-------+---------------------------------------------+ +-------------+-------+---------------------------------------------+
| depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 | | depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 |
| | | .0 | | | | .0 |
| fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: | | fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: |
| | | 1.0 | | | | 1.0 |
| filter | 4.8.6 | urn:ietf:params:restconf:capability:filter: | | filter | 4.8.4 | urn:ietf:params:restconf:capability:filter: |
| | | 1.0 | | | | 1.0 |
| replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: | | replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: |
| | 4.8.8 | 1.0 | | | 4.8.8 | 1.0 |
| with- | 4.8.9 | urn:ietf:params:restconf:capability:with- | | with- | 4.8.9 | urn:ietf:params:restconf:capability:with- |
| defaults | | defaults:1.0 | | defaults | | defaults:1.0 |
+-------------+-------+---------------------------------------------+ +-------------+-------+---------------------------------------------+
RESTCONF Query Parameter URIs RESTCONF Query Parameter URIs
9.1.2. The "defaults" Protocol Capability URI 9.1.2. The "defaults" Protocol Capability URI
skipping to change at page 75, line 19 skipping to change at page 74, line 17
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-11.txt // Note: extracted from draft-ietf-netconf-restconf-12.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2016-03-16 { revision 2016-03-16 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
skipping to change at page 80, line 21 skipping to change at page 79, line 15
Published specification: RFC XXXX Published specification: RFC XXXX
11.4. RESTCONF Capability URNs 11.4. RESTCONF Capability URNs
[Note to RFC Editor: [Note to RFC Editor:
The RESTCONF Protocol Capability Registry does not yet exist; The RESTCONF Protocol Capability Registry does not yet exist;
Need to ask IANA to create it; remove this note for publication Need to ask IANA to create it; remove this note for publication
] ]
This document defines a registry for RESTCONF capability identifiers. This document defines a registry for RESTCONF capability identifiers.
The name of the registry is "RESTCONF Capability URNs". The registry The name of the registry is "RESTCONF Capability URNs". The review
shall record for each entry: policy for this registry is "IETF Review". The registry shall record
for each entry:
o the name of the RESTCONF capability. By convention, this name is o the name of the RESTCONF capability. By convention, this name is
prefixed with the colon ':' character. prefixed with the colon ':' character.
o the URN for the RESTCONF capability. o the URN for the RESTCONF capability.
This document registers several capability identifiers in "RESTCONF This document registers several capability identifiers in "RESTCONF
Capability URNs" registry: Capability URNs" registry:
Index Index
skipping to change at page 85, line 45 skipping to change at page 84, line 16
Fielding, R., "Architectural Styles and the Design of Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000. Network-based Software Architectures", 2000.
Appendix A. Change Log Appendix A. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
The RESTCONF issue tracker can be found here: https://github.com/ The RESTCONF issue tracker can be found here: https://github.com/
netconf-wg/restconf/issues netconf-wg/restconf/issues
A.1. v10 - v11 A.1. v11 - v12
o clarify query parameter requirements
o move filter query section to match table order in sec. 4.8
o clarify that depth default is entire subtree for datastore
resource
o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml
o made implementation of timestamps optional since ETags are
mandatory
o removed confusing text about data resource definition revision
date
o clarify that errors should be returned for any resource type
o clarified media subtype (not type) for error response
o clarified client SHOULD (not MAY) specify errors format in Accept
header
o clarified terminology in many sections
A.2. v10 - v11
o change term 'operational data' to 'state data' o change term 'operational data' to 'state data'
o clarify :startup behavior o clarify :startup behavior
o clarify X.509 security text o clarify X.509 security text
o change '403 Forbidden' to '401 Unauthorized' for GET error o change '403 Forbidden' to '401 Unauthorized' for GET error
o clarify MUST have one "restconf" link relation o clarify MUST have one "restconf" link relation
o clarify that NV-storage is not mandatory o clarify that NV-storage is not mandatory
o clarify how "Last-Modified" and "ETag" header info can be used by o clarify how "Last-Modified" and "ETag" header info can be used by
a client a client
o clarify meaning of mandatory parameter o clarify meaning of mandatory parameter
o fix module name in action examples o fix module name in action examples
o clarify operation resource request needs to be known to parse the o clarify operation resource request needs to be known to parse the
skipping to change at page 86, line 24 skipping to change at page 85, line 20
o fix module name in action examples o fix module name in action examples
o clarify operation resource request needs to be known to parse the o clarify operation resource request needs to be known to parse the
output output
o clarify ordered-by user terminology o clarify ordered-by user terminology
o fixed JSON example in D.1.1 o fixed JSON example in D.1.1
A.2. v09 - v10 A.3. v09 - v10
o address review comments: github issue #36 o address review comments: github issue #36
o removed intro text about no knowledge of NETCONF needed o removed intro text about no knowledge of NETCONF needed
o clarified candidate and confirmed-commit behavior in sec. 1.3 o clarified candidate and confirmed-commit behavior in sec. 1.3
o clarified that a RESTCONF server MUST support TLS o clarified that a RESTCONF server MUST support TLS
o clarified choice of 403 or 404 error o clarified choice of 403 or 404 error
skipping to change at page 88, line 4 skipping to change at page 86, line 50
o remove sec. 5.2 Message Headers o remove sec. 5.2 Message Headers
o remove 202 Accepted from list of used status-lines -- not allowed o remove 202 Accepted from list of used status-lines -- not allowed
o made implementation of OPTIONS MUST instead of SHOULD o made implementation of OPTIONS MUST instead of SHOULD
o clarified that successful PUT for altering data returns 204 o clarified that successful PUT for altering data returns 204
o fixed "point" parameter example o fixed "point" parameter example
o added example of alternate value for root resource discovery
o added example of alternate value for root resource discovery
o added YANG action examples o added YANG action examples
o fixed some JSON examples o fixed some JSON examples
o changed default value for content query parameter to "all" o changed default value for content query parameter to "all"
o changed empty container JSON encoding from "[null]" to "{}" o changed empty container JSON encoding from "[null]" to "{}"
o added mandatory /restconf/yang-library-version leaf to advertise o added mandatory /restconf/yang-library-version leaf to advertise
revision-date of the YANG library implemented by the server revision-date of the YANG library implemented by the server
o clarified URI encoding rules for leaf-list o clarified URI encoding rules for leaf-list
o clarified sec. 2.2 wrt/ certificates and TLS o clarified sec. 2.2 wrt/ certificates and TLS
o added update procedure for entity tag and timestamp o added update procedure for entity tag and timestamp
A.3. v08 - v09 A.4. v08 - v09
o fix introduction text regarding implementation requirements for o fix introduction text regarding implementation requirements for
the ietf-yang-library the ietf-yang-library
o clarified HTTP authentication requirements o clarified HTTP authentication requirements
o fix host-meta example o fix host-meta example
o changed list key encoding to clarify that quoted strings are not o changed list key encoding to clarify that quoted strings are not
allowed. Percent-encoded values are used if quotes would be allowed. Percent-encoded values are used if quotes would be
required. A missing key is treated as a zero-length string required. A missing key is treated as a zero-length string
o Fixed example of percent-encoded string to match YANG model o Fixed example of percent-encoded string to match YANG model
o Changed streams examples to align with naming already used o Changed streams examples to align with naming already used
A.4. v07 - v08 A.5. v07 - v08
o add support for YANG 1.1 action statement o add support for YANG 1.1 action statement
o changed mandatory encoding from XML to XML or JSON o changed mandatory encoding from XML to XML or JSON
o fix syntax in fields parameter definition o fix syntax in fields parameter definition
o add meta-data encoding examples for XML and JSON o add meta-data encoding examples for XML and JSON
o remove RFC 2396 references and update with 3986 o remove RFC 2396 references and update with 3986
o change encoding of a key so quoted string are not used, since they o change encoding of a key so quoted string are not used, since they
are already percent-encoded. A zero-length string is not encoded are already percent-encoded. A zero-length string is not encoded
(/list=foo,,baz) (/list=foo,,baz)
o Add example of percent-encoded key value o Add example of percent-encoded key value
A.5. v06 - v07 A.6. v06 - v07
o fixed all issues identified in email from Jernej Tuljak in netconf o fixed all issues identified in email from Jernej Tuljak in netconf
email 2015-06-22 email 2015-06-22
o fixed error example bug where error-urlpath was still used. o fixed error example bug where error-urlpath was still used.
Changed to error-path. Changed to error-path.
o added mention of YANG Patch and informative reference o added mention of YANG Patch and informative reference
o added support for YANG 1.1, specifically support for anydata and o added support for YANG 1.1, specifically support for anydata and
actions actions
o removed the special field value "*", since it is no longer needed o removed the special field value "*", since it is no longer needed
A.6. v05 - v06 A.7. v05 - v06
o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug)
A.7. v04 - v05 A.8. v04 - v05
o changed term 'notification event' to 'event notification' o changed term 'notification event' to 'event notification'
o removed intro text about framework and meta-model o removed intro text about framework and meta-model
o removed early mention of API resources o removed early mention of API resources
o removed term unified datastore and cleaned up text about NETCONF o removed term unified datastore and cleaned up text about NETCONF
datastores datastores
skipping to change at page 90, line 17 skipping to change at page 89, line 17
o renamed stream/encoding/events to stream/access/location o renamed stream/encoding/events to stream/access/location
o changed XPath from informative to normative reference o changed XPath from informative to normative reference
o changed rest-dissertation from normative to informative reference o changed rest-dissertation from normative to informative reference
o changed example-jukebox playlist 'id' from a data-resource- o changed example-jukebox playlist 'id' from a data-resource-
identifier to a leafref pointing at the song name identifier to a leafref pointing at the song name
A.8. v03 - v04 A.9. v03 - v04
o renamed 'select' to 'fields' (#1) o renamed 'select' to 'fields' (#1)
o moved collection resource and page capability to draft-ietf- o moved collection resource and page capability to draft-ietf-
netconf-restconf-collection-00 (#3) netconf-restconf-collection-00 (#3)
o added mandatory "defaults" protocol capability URI (#4) o added mandatory "defaults" protocol capability URI (#4)
o added optional "with-defaults" query parameter URI (#4) o added optional "with-defaults" query parameter URI (#4)
skipping to change at page 91, line 5 skipping to change at page 90, line 5
o changed lock-denied error example o changed lock-denied error example
o added with-defaults query parameter example o added with-defaults query parameter example
o added term "RESTCONF Capability" o added term "RESTCONF Capability"
o changed NETCONF Capability URI registry usage to new RESTCONF o changed NETCONF Capability URI registry usage to new RESTCONF
Capability URI Registry usage Capability URI Registry usage
A.9. v02 - v03 A.10. v02 - v03
o added collection resource o added collection resource
o added "page" query parameter capability o added "page" query parameter capability
o added "limit" and "offset" query parameters, which are available o added "limit" and "offset" query parameters, which are available
if the "page" capability is supported if the "page" capability is supported
o added "stream list" term o added "stream list" term
skipping to change at page 91, line 27 skipping to change at page 90, line 27
o added "encoding" list within the "stream" list to allow different o added "encoding" list within the "stream" list to allow different
<events> URLs for XML and JSON encoding. <events> URLs for XML and JSON encoding.
o made XML MUST implement and JSON MAY implement for servers o made XML MUST implement and JSON MAY implement for servers
o re-add JSON notification examples (previously removed) o re-add JSON notification examples (previously removed)
o updated JSON references o updated JSON references
A.10. v01 - v02 A.11. v01 - v02
o moved query parameter definitions from the YANG module back to the o moved query parameter definitions from the YANG module back to the
plain text sections plain text sections
o made all query parameters optional to implement o made all query parameters optional to implement
o defined query parameter capability URI o defined query parameter capability URI
o moved 'streams' to new YANG module (ietf-restconf-monitoring) o moved 'streams' to new YANG module (ietf-restconf-monitoring)
skipping to change at page 92, line 16 skipping to change at page 91, line 16
information is no longer in this resource information is no longer in this resource
o closed issue #1 'select parameter' since no objections to the o closed issue #1 'select parameter' since no objections to the
proposed syntax proposed syntax
o closed "encoding of list keys" issue since no objection to new o closed "encoding of list keys" issue since no objection to new
encoding of list keys in a target resource URI. encoding of list keys in a target resource URI.
o moved open issues list to the issue tracker on github o moved open issues list to the issue tracker on github
A.11. v00 - v01 A.12. v00 - v01
o fixed content=nonconfig example (non-config was incorrect) o fixed content=nonconfig example (non-config was incorrect)
o closed open issue 'message-id'. There is no need for a message-id o closed open issue 'message-id'. There is no need for a message-id
field, and RFC 2392 does not apply. field, and RFC 2392 does not apply.
o closed open issue 'server support verification'. The headers used o closed open issue 'server support verification'. The headers used
by RESTCONF are widely supported. by RESTCONF are widely supported.
o removed encoding rules from section on RESTCONF Meta-Data. This o removed encoding rules from section on RESTCONF Meta-Data. This
skipping to change at page 93, line 10 skipping to change at page 92, line 10
o added RESTCONF Path Resolution section for discovering the root of o added RESTCONF Path Resolution section for discovering the root of
the RESTCONF API using the /.well-known/host-meta. the RESTCONF API using the /.well-known/host-meta.
o added an "error" media type to for structured error messages o added an "error" media type to for structured error messages
o added Secure Transport section requiring TLS o added Secure Transport section requiring TLS
o added Security Considerations section o added Security Considerations section
o removed all references to "REST-like" o removed all references to "REST-like"
A.12. bierman:restconf-04 to ietf:restconf-00 A.13. bierman:restconf-04 to ietf:restconf-00
o updated open issues section o updated open issues section
Appendix B. Open Issues Appendix B. Open Issues
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
The RESTCONF issues are tracked on github.com: The RESTCONF issues are tracked on github.com:
https://github.com/netconf-wg/restconf/issues https://github.com/netconf-wg/restconf/issues
 End of changes. 54 change blocks. 
171 lines changed or deleted 205 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/