draft-ietf-netconf-restconf-17.txt   draft-ietf-netconf-restconf-18.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: April 1, 2017 Tail-f Systems Expires: April 30, 2017 Tail-f Systems
K. Watsen K. Watsen
Juniper Networks Juniper Networks
September 28, 2016 October 27, 2016
RESTCONF Protocol RESTCONF Protocol
draft-ietf-netconf-restconf-17 draft-ietf-netconf-restconf-18
Abstract Abstract
This document describes an HTTP-based protocol that provides a This document describes an HTTP-based protocol that provides a
programmatic interface for accessing data defined in YANG, using the programmatic interface for accessing data defined in YANG, using the
datastore concepts defined in NETCONF. datastore concepts defined in NETCONF.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 1, 2017. This Internet-Draft will expire on April 30, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 22 skipping to change at page 2, line 22
1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.4. NETCONF Notifications . . . . . . . . . . . . . . . . 7 1.1.4. NETCONF Notifications . . . . . . . . . . . . . . . . 7
1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 8 1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 8
1.1.6. URI Template and Examples . . . . . . . . . . . . . . 10 1.1.6. URI Template and Examples . . . . . . . . . . . . . . 10
1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10 1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10
1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 11 1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 11
1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 11 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 11
1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 12 1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 12
1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 13 1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 13
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 15 2. Transport Protocol . . . . . . . . . . . . . . . . . . . . . 15
2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 15 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 15
2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 15 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 15
2.3. Certificate Validation . . . . . . . . . . . . . . . . . 15 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 15
2.4. Authenticated Server Identity . . . . . . . . . . . . . . 15 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 15
2.5. Authenticated Client Identity . . . . . . . . . . . . . . 16 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 16
3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 17 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 17
3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 19 3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 19
3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 19 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 19
3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 20 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 20
3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 20 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 20
3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 21 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 21
3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 21 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 21
3.4.1. Edit Collision Prevention . . . . . . . . . . . . . . 22 3.4.1. Edit Collision Prevention . . . . . . . . . . . . . . 22
3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 23 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 23
3.5.1. Timestamp . . . . . . . . . . . . . . . . . . . . . . 24 3.5.1. Timestamp . . . . . . . . . . . . . . . . . . . . . . 24
3.5.2. Entity-Tag . . . . . . . . . . . . . . . . . . . . . 24 3.5.2. Entity-Tag . . . . . . . . . . . . . . . . . . . . . 24
3.5.3. Encoding Data Resource Identifiers in the Request URI 24 3.5.3. Encoding Data Resource Identifiers in the Request URI 24
3.5.4. Default Handling . . . . . . . . . . . . . . . . . . 28 3.5.4. Default Handling . . . . . . . . . . . . . . . . . . 28
3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 29 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 28
3.6.1. Encoding Operation Resource Input Parameters . . . . 30 3.6.1. Encoding Operation Resource Input Parameters . . . . 29
3.6.2. Encoding Operation Resource Output Parameters . . . . 34 3.6.2. Encoding Operation Resource Output Parameters . . . . 34
3.6.3. Encoding Operation Resource Errors . . . . . . . . . 36 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 36
3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 37 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 37
3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 38 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 38
3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 39 3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 39
4. RESTCONF Methods . . . . . . . . . . . . . . . . . . . . . . 39 4. RESTCONF Methods . . . . . . . . . . . . . . . . . . . . . . 39
4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 40 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 40 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 42 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 42
skipping to change at page 4, line 6 skipping to change at page 4, line 6
9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 79 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 79
10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 83 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 83
10.1. modules-state/module . . . . . . . . . . . . . . . . . . 83 10.1. modules-state/module . . . . . . . . . . . . . . . . . . 83
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 83 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 83
11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 84 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 84
11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 84 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 84
11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 85 11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 85
11.3.1. Media Type application/yang-data+xml . . . . . . . . 85 11.3.1. Media Type application/yang-data+xml . . . . . . . . 85
11.3.2. Media Type application/yang-data+json . . . . . . . 86 11.3.2. Media Type application/yang-data+json . . . . . . . 86
11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 88 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 88
11.5. Registration of "restconf" URN sub-namespace . . . . . . 89
12. Security Considerations . . . . . . . . . . . . . . . . . . . 89 12. Security Considerations . . . . . . . . . . . . . . . . . . . 89
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 90 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 90
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 90 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 91
14.1. Normative References . . . . . . . . . . . . . . . . . . 90 14.1. Normative References . . . . . . . . . . . . . . . . . . 91
14.2. Informative References . . . . . . . . . . . . . . . . . 93 14.2. Informative References . . . . . . . . . . . . . . . . . 94
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 93 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 94
A.1. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . 93 A.1. v17 to v18 . . . . . . . . . . . . . . . . . . . . . . . 94
A.2. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . 94 A.2. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . 94
A.3. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . 94 A.3. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . 95
A.4. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 95 A.4. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . 95
A.5. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 96 A.5. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 96
A.6. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 97 A.6. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 98
A.7. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 97 A.7. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 98
A.8. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 98 A.8. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 98
A.9. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 100 A.9. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 99
A.10. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 100 A.10. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 101
A.11. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 100 A.11. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 101
A.12. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 101 A.12. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 102
A.13. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 101 A.13. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 102
A.14. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 102 A.14. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 102
A.15. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 102 A.15. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 103
A.16. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 103 A.16. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 103
A.17. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 104 A.17. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 104
A.18. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 105 A.18. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 105
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 105 A.19. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 106
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 105 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 106
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 106 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 106
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 111 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 107
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 111 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 112
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 111 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 112
D.1.2. Retrieve The Server Module Information . . . . . . . 112 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 112
D.1.3. Retrieve The Server Capability Information . . . . . 114 D.1.2. Retrieve The Server Module Information . . . . . . . 113
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 115 D.1.3. Retrieve The Server Capability Information . . . . . 115
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 115 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 116
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 116
D.2.2. Detect Resource Entity-Tag Change . . . . . . . . . . 117 D.2.2. Detect Resource Entity-Tag Change . . . . . . . . . . 117
D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 117 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 118
D.2.4. Edit a Data Resource . . . . . . . . . . . . . . . . 118 D.2.4. Replace a Datastore Resource . . . . . . . . . . . . 119
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 118 D.2.5. Edit a Data Resource . . . . . . . . . . . . . . . . 120
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 119 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 120
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 122 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 120
D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 125 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 124
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 126 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 127
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 127 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 128
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 128 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 129
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 129 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 130
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 129 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 131
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 130 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 131
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 131 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 132
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 133
1. Introduction 1. Introduction
There is a need for standard mechanisms to allow Web applications to There is a need for standard mechanisms to allow Web applications to
access the configuration data, state data, data-model-specific RPC access the configuration data, state data, data-model-specific RPC
operations, and event notifications within a networking device, in a operations, and event notifications within a networking device, in a
modular and extensible manner. modular and extensible manner.
This document defines an HTTP [RFC7230] based protocol called This document defines an HTTP [RFC7230] based protocol called
RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or
skipping to change at page 13, line 14 skipping to change at page 13, line 14
The following figure shows the system components if a RESTCONF server The following figure shows the system components if a RESTCONF server
is implemented in a device that does not have a NETCONF server: is implemented in a device that does not have a NETCONF server:
+-----------+ +-----------------+ +-----------+ +-----------------+
| Web app | <-------> | | | Web app | <-------> | |
+-----------+ RESTCONF | network device | +-----------+ RESTCONF | network device |
| | | |
+-----------------+ +-----------------+
Note that there are no interactions at all between the NETCONF There are interactions between the NETCONF protocol and RESTCONF
protocol and RESTCONF protocol. It is possible that locks are in use protocol related to edit operations. It is possible that locks are
on a RESTCONF server, even though RESTCONF cannot manipulate locks. in use on a RESTCONF server, even though RESTCONF cannot manipulate
In such a case, the RESTCONF protocol will not be granted write locks. In such a case, the RESTCONF protocol will not be granted
access to data resources within a datastore. write access to data resources within a datastore.
If the NETCONF server supports :writable-running, all edits to If the NETCONF server supports :writable-running, all edits to
configuration nodes in {+restconf}/data are performed in the running configuration nodes in {+restconf}/data are performed in the running
configuration datastore. The URI template "{+restconf}" is defined configuration datastore. The URI template "{+restconf}" is defined
in Section 1.1.6. in Section 1.1.6.
Otherwise, if the device supports :candidate, all edits to Otherwise, if the device supports :candidate, all edits to
configuration nodes in {+restconf}/data are performed in the configuration nodes in {+restconf}/data are performed in the
candidate configuration datastore. The candidate MUST be candidate configuration datastore. The candidate MUST be
automatically committed to running immediately after each successful automatically committed to running immediately after each successful
edit. Any edits from other sources that are in the candidate edit. Any edits from other sources that are in the candidate
datastore will also be committed. If a confirmed commit procedure is datastore will also be committed. If a confirmed commit procedure is
in progress by any NETCONF client, then this commit will act as the in progress by any NETCONF client, then any new commit will act as
confirming commit. If the NETCONF server is expecting a "persist-id" the confirming commit. If the NETCONF server is expecting a
parameter to complete the confirmed commit procedure then the "persist-id" parameter to complete the confirmed commit procedure
RESTCONF edit operation MUST fail with a "409 Conflict" status-line. then the RESTCONF edit operation MUST fail with a "409 Conflict"
There error-tag "in-use" is returned in this case. The error-tag status-line. There error-tag "in-use" is returned in this case. The
value "resource-denied" is used in this case. error-tag value "resource-denied" is used in this case.
If the NETCONF server supports :startup, the RESTCONF server MUST If the NETCONF server supports :startup, the RESTCONF server MUST
automatically update the non-volatile startup configuration automatically update the non-volatile startup configuration
datastore, after the running datastore has been altered as a datastore, after the running datastore has been altered as a
consequence of a RESTCONF edit operation. consequence of a RESTCONF edit operation.
If a datastore that would be modified by a RESTCONF operation has an If a datastore that would be modified by a RESTCONF operation has an
active lock from a NETCONF client, the RESTCONF edit operation MUST active lock from a NETCONF client, the RESTCONF edit operation MUST
fail with a "409 Conflict" status-line. There error-tag "in-use" is fail with a "409 Conflict" status-line. There error-tag "in-use" is
returned in this case. returned in this case.
skipping to change at page 15, line 5 skipping to change at page 15, line 5
The "capabilities" list can identify any sort of server extension. The "capabilities" list can identify any sort of server extension.
Currently this extension mechanism is used to identify optional query Currently this extension mechanism is used to identify optional query
parameters that are supported, but it is not limited to that purpose. parameters that are supported, but it is not limited to that purpose.
For example, the "defaults" URI defined in Section 9.1.2 specifies a For example, the "defaults" URI defined in Section 9.1.2 specifies a
mandatory URI identifying server defaults handling behavior. mandatory URI identifying server defaults handling behavior.
A new sub-resource type could be identified with a capability if it A new sub-resource type could be identified with a capability if it
is optional to implement. Mandatory protocol features and new is optional to implement. Mandatory protocol features and new
resource types require a new revision of the RESTCONF protocol. resource types require a new revision of the RESTCONF protocol.
2. Transport Protocol Requirements 2. Transport Protocol
2.1. Integrity and Confidentiality 2.1. Integrity and Confidentiality
HTTP [RFC7230] is an application layer protocol that may be layered HTTP [RFC7230] is an application layer protocol that may be layered
on any reliable transport-layer protocol. RESTCONF is defined on top on any reliable transport-layer protocol. RESTCONF is defined on top
of HTTP, but due to the sensitive nature of the information conveyed, of HTTP, but due to the sensitive nature of the information conveyed,
RESTCONF requires that the transport-layer protocol provides both RESTCONF requires that the transport-layer protocol provides both
data integrity and confidentiality. A RESTCONF server MUST support data integrity and confidentiality. A RESTCONF server MUST support
the TLS protocol [RFC5246]. The RESTCONF protocol MUST NOT be used the TLS protocol [RFC5246], and SHOULD adhere to [RFC7525]. The
over HTTP without using the TLS protocol. RESTCONF protocol MUST NOT be used over HTTP without using the TLS
protocol.
RESTCONF does not require a specific version of HTTP. However, it is RESTCONF does not require a specific version of HTTP. However, it is
RECOMMENDED that at least HTTP/1.1 [RFC7230] be supported by all RECOMMENDED that at least HTTP/1.1 [RFC7230] be supported by all
implementations. implementations.
2.2. HTTPS with X.509v3 Certificates 2.2. HTTPS with X.509v3 Certificates
Given the nearly ubiquitous support for HTTP over TLS [RFC7230], Given the nearly ubiquitous support for HTTP over TLS [RFC7230],
RESTCONF implementations MUST support the "https" URI scheme, which RESTCONF implementations MUST support the "https" URI scheme, which
has the IANA assigned default port 443. has the IANA assigned default port 443.
skipping to change at page 15, line 37 skipping to change at page 15, line 38
RESTCONF servers MUST present an X.509v3 based certificate when RESTCONF servers MUST present an X.509v3 based certificate when
establishing a TLS connection with a RESTCONF client. The use of establishing a TLS connection with a RESTCONF client. The use of
X.509v3 based certificates is consistent with NETCONF over TLS X.509v3 based certificates is consistent with NETCONF over TLS
[RFC7589]. [RFC7589].
2.3. Certificate Validation 2.3. Certificate Validation
The RESTCONF client MUST either use X.509 certificate path validation The RESTCONF client MUST either use X.509 certificate path validation
[RFC5280] to verify the integrity of the RESTCONF server's TLS [RFC5280] to verify the integrity of the RESTCONF server's TLS
certificate, or match the server's TLS certificate with a certificate certificate, or match the server's TLS certificate with a certificate
obtained by a trusted mechanism (e.g. a pinned certificate). If obtained by a trusted mechanism (e.g., a pinned certificate). If
X.509 certificate path validation fails, and the presented X.509 X.509 certificate path validation fails, and the presented X.509
certificate does not match a certificate obtained by a trusted certificate does not match a certificate obtained by a trusted
mechanism, the connection MUST be terminated, as described in mechanism, the connection MUST be terminated, as described in
Section 7.2.1 of [RFC5246]. Section 7.2.1 of [RFC5246].
2.4. Authenticated Server Identity 2.4. Authenticated Server Identity
The RESTCONF client MUST check the identity of the server according The RESTCONF client MUST check the identity of the server according
to Section 6 of [RFC6125], including processing the outcome as to Section 3.1 of [RFC2818].
described in Section 6.6 of [RFC6125].
2.5. Authenticated Client Identity 2.5. Authenticated Client Identity
The RESTCONF server MUST authenticate client access to any protected The RESTCONF server MUST authenticate client access to any protected
resource. If the RESTCONF client is not authenticated, the server resource. If the RESTCONF client is not authenticated, the server
SHOULD send an HTTP response with "401 Unauthorized" status-line, as SHOULD send an HTTP response with "401 Unauthorized" status-line, as
defined in Section 3.1 of [RFC7235]. The error-tag value defined in Section 3.1 of [RFC7235]. The error-tag value
"access-denied" is used in this case. "access-denied" is used in this case.
To authenticate a client, a RESTCONF server MUST use TLS based client To authenticate a client, a RESTCONF server SHOULD require TLS client
certificates (Section 7.4.6 of [RFC5246]), or MUST use any HTTP certificate based authentication (Section 7.4.6 of [RFC5246]). If
authentication scheme defined in the HTTP Authentication Scheme certificate based authentication is not feasible (e.g., because one
Registry (Section 5.1 in [RFC7235]). A server MAY also support the cannot build the required PKI for clients) then an HTTP
combination of both client certificates and an HTTP client authentication MAY be used. In the latter case, one of the HTTP
authentication scheme, with the determination of how to process this authentication schemes defined in the HTTP Authentication Scheme
combination left as an implementation decision. Registry (Section 5.1 in [RFC7235]) MUST be used.
A server MAY also support the combination of both client certificates
and an HTTP client authentication scheme, with the determination of
how to process this combination left as an implementation decision.
The RESTCONF client identity derived from the authentication The RESTCONF client identity derived from the authentication
mechanism used is hereafter known as the "RESTCONF username" and mechanism used is hereafter known as the "RESTCONF username" and
subject to the NETCONF Access Control Module (NACM) [RFC6536]. When subject to the NETCONF Access Control Module (NACM) [RFC6536]. When
a client certificate is presented, the RESTCONF username MUST be a client certificate is presented, the RESTCONF username MUST be
derived using the algorithm defined in Section 7 of [RFC7589]. For derived using the algorithm defined in Section 7 of [RFC7589]. For
all other cases, when HTTP authentication is used, the RESTCONF all other cases, when HTTP authentication is used, the RESTCONF
username MUST be provided by the HTTP authentication scheme used. username MUST be provided by the HTTP authentication scheme used.
3. Resources 3. Resources
skipping to change at page 23, line 11 skipping to change at page 23, line 11
resource and MUST return it in the "ETag" ([RFC7232], Section 2.3) resource and MUST return it in the "ETag" ([RFC7232], Section 2.3)
header in the response for a retrieval request. The client MAY use header in the response for a retrieval request. The client MAY use
an "If-Match" header in edit operation requests to cause the server an "If-Match" header in edit operation requests to cause the server
to reject the request if the resource entity-tag does not match the to reject the request if the resource entity-tag does not match the
specified value. specified value.
The server MUST maintain an entity-tag for the top-level The server MUST maintain an entity-tag for the top-level
{+restconf}/data resource. This entity-tag is only affected by {+restconf}/data resource. This entity-tag 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. Entity-tags for data resources are discussed non-configuration data. Entity-tags for data resources are discussed
in Section 3.5. Note that each representation (e.g. XML vs. JSON) in Section 3.5. Note that each representation (e.g., XML vs. JSON)
requires a different entity-tag. requires a different entity-tag.
If the RESTCONF server is colocated with a NETCONF server, then this If the RESTCONF server is colocated with a NETCONF server, then this
entity-tag MUST be for the "running" datastore. Note that it is entity-tag MUST be for the "running" datastore. Note that it is
possible other protocols can cause the entity-tag to be updated. possible other protocols can cause the entity-tag to be updated.
Such mechanisms are out of scope for this document. Such mechanisms are out of scope for this document.
3.4.1.3. Update Procedure 3.4.1.3. Update Procedure
Changes to configuration data resources affect the timestamp and Changes to configuration data resources affect the timestamp and
skipping to change at page 25, line 39 skipping to change at page 25, line 39
o The leaf-list value is specified as a string, using the canonical o The leaf-list value is specified as a string, using the canonical
representation for the YANG data type. Any reserved characters representation for the YANG data type. Any reserved characters
MUST be percent-encoded, according to [RFC3986], section 2.1 and MUST be percent-encoded, according to [RFC3986], section 2.1 and
2.5. 2.5.
o YANG 1.1 allows duplicate leaf-list values for non-configuration o YANG 1.1 allows duplicate leaf-list values for non-configuration
data. In this case there is no mechanism to specify the exact data. In this case there is no mechanism to specify the exact
matching leaf-list instance. matching leaf-list instance.
o The comma (',') character is percent-encoded, even though multiple o The comma (',') character is percent-encoded [RFC3986], even
key values are not possible for a leaf-list. This is more though multiple key values are not possible for a leaf-list. This
consistent and avoids special processing rules. is more consistent and avoids special processing rules.
If a data node in the path expression is a YANG list node, then the If a data node in the path expression is a YANG list node, then the
key values for the list (if any) MUST be encoded according to the key values for the list (if any) MUST be encoded according to the
following rules: following rules:
o The key leaf values for a data resource representing a YANG list o The key leaf values for a data resource representing a YANG list
MUST be encoded using one path segment [RFC3986]. MUST be encoded using one path segment [RFC3986].
o If there is only one key leaf value, the path segment is o If there is only one key leaf value, the path segment is
constructed by having the list name, followed by an "=" character, constructed by having the list name, followed by an "=" character,
skipping to change at page 28, line 5 skipping to change at page 28, line 5
subtree "+{restconf}/data". subtree "+{restconf}/data".
An identifier is not allowed to start with the case-insensitive An identifier is not allowed to start with the case-insensitive
string "XML", according to YANG identifier rules. The syntax for string "XML", according to YANG identifier rules. The syntax for
"api-identifier" and "key-value" MUST conform to the JSON identifier "api-identifier" and "key-value" MUST conform to the JSON identifier
encoding rules in Section 4 of [RFC7951]: The RESTCONF root resource encoding rules in Section 4 of [RFC7951]: The RESTCONF root resource
path is required. Additional sub-resource identifiers are optional. path is required. Additional sub-resource identifiers are optional.
The characters in a key value string are constrained, and some The characters in a key value string are constrained, and some
characters need to be percent-encoded, as described in Section 3.5.3. characters need to be percent-encoded, as described in Section 3.5.3.
api-path = root ["/" (api-identifier | list-instance)]* api-path = root *("/" (api-identifier / list-instance))
root = string ;; replacement string for {+restconf} root = string ;; replacement string for {+restconf}
api-identifier = [module-name ":"] identifier api-identifier = [module-name ":"] identifier
module-name = identifier module-name = identifier
list-instance = api-identifier "=" key-value ["," key-value]* list-instance = api-identifier "=" key-value *("," key-value)
key-value = string ;; constrained chars are percent-encoded key-value = string ;; constrained chars are percent-encoded
string = <an unquoted string> string = <an unquoted string>
;; An identifier MUST NOT start with identifier = (ALPHA / "_")
;; (('X'|'x') ('M'|'m') ('L'|'l')) *(ALPHA / DIGIT / "_" / "-" / ".")
identifier = (ALPHA / "_")
*(ALPHA / DIGIT / "_" / "-" / ".")
3.5.4. Default Handling 3.5.4. Default Handling
RESTCONF requires that a server report its default handling mode (see RESTCONF requires that a server report its default handling mode (see
Section 9.1.2 for details). If the optional "with-defaults" query Section 9.1.2 for details). If the optional "with-defaults" query
parameter is supported by the server, a client may use it to control parameter is supported by the server, a client may use it to control
retrieval of default values (see Section 4.8.9 for details). retrieval of default values (see Section 4.8.9 for details).
If a leaf or leaf-list is missing from the configuration and there is If a leaf or leaf-list is missing from the configuration and there is
a YANG-defined default for that data resource, then the server MUST a YANG-defined default for that data resource, then the server MUST
skipping to change at page 40, line 21 skipping to change at page 40, line 21
Implementation of all methods (except PATCH [RFC5789]) are defined in Implementation of all methods (except PATCH [RFC5789]) are defined in
[RFC7231]. This section defines the RESTCONF protocol usage for each [RFC7231]. This section defines the RESTCONF protocol usage for each
HTTP method. HTTP method.
4.1. OPTIONS 4.1. OPTIONS
The OPTIONS method is sent by the client to discover which methods The OPTIONS method is sent by the client to discover which methods
are supported by the server for a specific resource (e.g., GET, POST, are supported by the server for a specific resource (e.g., GET, POST,
DELETE, etc.). The server MUST implement this method. DELETE, etc.). The server MUST implement this method.
If the PATCH method is supported, then the "Accept-Patch" header The "Accept-Patch" header field MUST be supported and returned in the
field MUST be supported and returned in the response to the OPTIONS response to the OPTIONS request, as defined in [RFC5789].
request, as defined in [RFC5789].
4.2. HEAD 4.2. HEAD
The RESTCONF server MUST support the HEAD method. The HEAD method is The RESTCONF server MUST support the HEAD method. The HEAD method is
sent by the client to retrieve just the header fields (which contain sent by the client to retrieve just the header fields (which contain
the metadata for a resource) that would be returned for the the metadata for a resource) that would be returned for the
comparable GET method, without the response message-body. It is comparable GET method, without the response message-body. It is
supported for all resources that support the GET method. supported for all resources that support the GET method.
The request MUST contain a request URI that contains at least the The request MUST contain a request URI that contains at least the
skipping to change at page 44, line 17 skipping to change at page 44, line 17
If the target resource type is an operation resource, then the POST If the target resource type is an operation resource, then the POST
method is treated as a request to invoke that operation. The method is treated as a request to invoke that operation. The
message-body (if any) is processed as the operation input parameters. message-body (if any) is processed as the operation input parameters.
Refer to Section 3.6 for details on operation resources. Refer to Section 3.6 for details on operation resources.
If the POST request succeeds, a "200 OK" status-line is returned if If the POST request succeeds, a "200 OK" status-line is returned if
there is a response message-body, and a "204 No Content" status-line there is a response message-body, and a "204 No Content" status-line
is returned if there is no response message-body. is returned if there is no response message-body.
If the user is not authorized to invoke the target operation, an If the user is not authorized to invoke the target operation, an
error response containing a "403 Forbidden" status-line is returned error response containing a "403 Forbidden" status-line SHOULD be
to the client. The error-tag value "access-denied" is used in this returned. The error-tag value "access-denied" is used in this case.
case. All other error responses are handled according to the A server MAY return a "404 Not Found" status-line, as described in
procedures defined in Section 7. section 6.5.3 in [RFC7231]. All other error responses are handled
according to the procedures defined in Section 7.
Example: Example:
In this example, the client is invoking the "play" operation defined In this example, the client is invoking the "play" operation defined
in the "example-jukebox" YANG module. in the "example-jukebox" YANG module.
A client might send a "play" request as follows: A client might send a "play" request as follows:
POST /restconf/operations/example-jukebox:play HTTP/1.1 POST /restconf/operations/example-jukebox:play HTTP/1.1
Host: example.com Host: example.com
skipping to change at page 46, line 42 skipping to change at page 46, line 45
Host: example.com Host: example.com
Content-Type: application/yang-data+xml Content-Type: application/yang-data+xml
<album xmlns="http://example.com/ns/example-jukebox" <album xmlns="http://example.com/ns/example-jukebox"
xmlns:jbox="http://example.com/ns/example-jukebox"> xmlns:jbox="http://example.com/ns/example-jukebox">
<name>Wasting Light</name> <name>Wasting Light</name>
<genre>jbox:alternative</genre> <genre>jbox:alternative</genre>
<year>2011</year> <year>2011</year>
</album> </album>
Refer to Appendix D.2.4 for an example using the PUT method to
replace the contents of the datastore resource.
4.6. PATCH 4.6. PATCH
The RESTCONF server MUST support the PATCH method. RESTCONF uses the The RESTCONF server MUST support the PATCH method for a plain patch,
HTTP PATCH method defined in [RFC5789] to provide an extensible and MAY support additional media types. The PATCH media types
framework for resource patching mechanisms. It is optional to supported by a server can be discovered by the client by sending an
implement by the server. Each patch mechanism needs a unique media OPTIONS request, and examining the Accept-Patch header field in the
type. Zero or more patch media types MAY be supported by the server. response. (see Section 4.1).
The media types supported by a server can be discovered by the client
by sending an OPTIONS request, and examining the Accept-Patch header RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide
field in the response. (see Section 4.1). an extensible framework for resource patching mechanisms. Each patch
mechanism needs a unique media type.
This document defines one patch mechanism (Section 4.6.1). Another This document defines one patch mechanism (Section 4.6.1). Another
patch mechanism, the YANG PATCH mechanism, is defined in patch mechanism, the YANG PATCH mechanism, is defined in
[I-D.ietf-netconf-yang-patch]. Other patch mechanisms may be defined [I-D.ietf-netconf-yang-patch]. Other patch mechanisms may be defined
by future specifications. by future specifications.
If the target resource instance does not exist, the server MUST NOT If the target resource instance does not exist, the server MUST NOT
create it. create it.
If the PATCH request succeeds, a "200 OK" status-line is returned if If the PATCH request succeeds, a "200 OK" status-line is returned if
skipping to change at page 47, line 46 skipping to change at page 48, line 5
PATCH method. PATCH method.
If the target resource represents a YANG leaf-list, then the PATCH If the target resource represents a YANG leaf-list, then the PATCH
method MUST NOT change the value of the leaf-list instance. method MUST NOT change the value of the leaf-list instance.
If the target resource represents a YANG list instance, then the key If the target resource represents a YANG list instance, then the key
leaf values in message-body representation MUST be the same as the leaf values in message-body representation MUST be the same as the
key leaf values in the request URI. The PATCH method MUST NOT be key leaf values in the request URI. The PATCH method MUST NOT be
used to change the key leaf values for a data resource instance. used to change the key leaf values for a data resource instance.
After the plain patch is processed by the server. a response will be After the plain patch is processed by the server a response will be
returned to the client, as specified in Section 4.6. returned to the client, as specified in Section 4.6.
Example: Example:
To replace just the "year" field in the "album" resource (instead of To replace just the "year" field in the "album" resource (instead of
replacing the entire resource with the PUT method), the client might replacing the entire resource with the PUT method), the client might
send a plain patch as follows. send a plain patch as follows.
PATCH /restconf/data/example-jukebox:jukebox/\ PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
skipping to change at page 52, line 50 skipping to change at page 52, line 50
4.8.4. The "filter" Query Parameter 4.8.4. The "filter" Query Parameter
The "filter" parameter is used to indicate which subset of all The "filter" parameter is used to indicate which subset of all
possible events are of interest. If not present, all events not possible events are of interest. If not present, all events not
precluded by other parameters will be sent. precluded by other parameters will be sent.
This parameter is only allowed for GET methods on an event stream This parameter is only allowed for GET methods on an event stream
resource. A "400 Bad Request" status-line is returned if used for resource. A "400 Bad Request" status-line is returned if used for
other methods or resource types. other methods or resource types.
The format of this parameter is an XPath 1.0 expression, and is The format of this parameter is an XPath 1.0 expression [XPath], and
evaluated in the following context: is evaluated in the following context:
o The set of namespace declarations is the set of prefix and o The set of namespace declarations is the set of prefix and
namespace pairs for all supported YANG modules, where the prefix namespace pairs for all supported YANG modules, where the prefix
is the YANG module name, and the namespace is as defined by the is the YANG module name, and the namespace is as defined by the
"namespace" statement in the YANG module. "namespace" statement in the YANG module.
o The function library is the core function library defined in XPath o The function library is the core function library defined in XPath
1.0, plus any functions defined by the data model. 1.0, plus any functions defined by the data model.
o The set of variable bindings is empty. o The set of variable bindings is empty.
skipping to change at page 58, line 51 skipping to change at page 58, line 51
Refer to Appendix D for examples of RESTCONF Request URIs. Refer to Appendix D for examples of RESTCONF Request URIs.
5.2. Message Encoding 5.2. Message Encoding
RESTCONF messages are encoded in HTTP according to [RFC7230]. The RESTCONF messages are encoded in HTTP according to [RFC7230]. The
"utf-8" character set is used for all messages. RESTCONF message "utf-8" character set is used for all messages. RESTCONF message
content is sent in the HTTP message-body. content is sent in the HTTP message-body.
Content is encoded in either JSON or XML format. A server MUST Content is encoded in either JSON or XML format. A server MUST
support one of either XML or JSON encoding. A server MAY support support one of either XML or JSON encoding. A server MAY support
both XML and JSON encoding. XML encoding rules for data nodes are both XML and JSON encoding. A client will need to support both XML
defined in [RFC7950]. The same encoding rules are used for all XML and JSON to interoperate with all RESTCONF servers.
content. JSON encoding rules are defined in [RFC7951]. Additional
JSON encoding rules for metadata are defined in [RFC7952]. This XML encoding rules for data nodes are defined in [RFC7950]. The same
encoding is valid JSON, but also has special encoding rules to encoding rules are used for all XML content. JSON encoding rules are
identify module namespaces and provide consistent type processing of defined in [RFC7951]. Additional JSON encoding rules for metadata
YANG data. are defined in [RFC7952]. This encoding is valid JSON, but also has
special encoding rules to identify module namespaces and provide
consistent type processing of YANG data.
Request input content encoding format is identified with the Content- Request input content encoding format is identified with the Content-
Type header field. This field MUST be present if a message-body is Type header field. This field MUST be present if a message-body is
sent by the client. sent by the client.
The server MUST support the "Accept" header field and "406 Not The server MUST support the "Accept" header field and "406 Not
Acceptable" status-line, as defined in [RFC7231]. The response Acceptable" status-line, as defined in [RFC7231]. The response
output content encoding formats that the client will accept are output content encoding formats that the client will accept are
identified with the Accept header field in the request. If it is not identified with the Accept header field in the request. If it is not
specified, the request input encoding format SHOULD be used, or the specified, the request input encoding format SHOULD be used, or the
skipping to change at page 59, line 36 skipping to change at page 59, line 38
format by sending a request using a specific format in the Content- format by sending a request using a specific format in the Content-
Type and/or Accept header field. If the server does not support the Type and/or Accept header field. If the server does not support the
requested input encoding for a request, then it MUST return an error requested input encoding for a request, then it MUST return an error
response with a '415 Unsupported Media Type' status-line. If the response with a '415 Unsupported Media Type' status-line. If the
server does not support any of the requested output encodings for a server does not support any of the requested output encodings for a
request, then it MUST return an error response with a '406 Not request, then it MUST return an error response with a '406 Not
Acceptable' status-line. Acceptable' status-line.
5.3. RESTCONF Metadata 5.3. RESTCONF Metadata
The RESTCONF protocol needs support retrieval of the same metadata The RESTCONF protocol needs to support retrieval of the same metadata
that is used in the NETCONF protocol. Information about default that is used in the NETCONF protocol. Information about default
leafs, last-modified timestamps, etc. are commonly used to annotate leafs, last-modified timestamps, etc. are commonly used to annotate
representations of the datastore contents. representations of the datastore contents.
With the XML encoding, the metadata is encoded as attributes in XML, With the XML encoding, the metadata is encoded as attributes in XML,
according to section 3.3 of [W3C.REC-xml-20081126]. With the JSON according to section 3.3 of [W3C.REC-xml-20081126]. With the JSON
encoding, the metadata is encoded as specified in [RFC7952]. encoding, the metadata is encoded as specified in [RFC7952].
The following examples are based on the example in Appendix D.3.9. The following examples are based on the example in Appendix D.3.9.
The "report-all-tagged" mode for the "with-defaults" query parameter The "report-all-tagged" mode for the "with-defaults" query parameter
skipping to change at page 61, line 41 skipping to change at page 61, line 41
returned in the response, according to the format defined in returned in the response, according to the format defined in
Section 7.1. If a 1xx, 2xx, or 3xx range status code is returned in Section 7.1. If a 1xx, 2xx, or 3xx range status code is returned in
the status-line, then error information MUST NOT be returned in the the status-line, then error information MUST NOT be returned in the
response, since these ranges do not represent error conditions. response, since these ranges do not represent error conditions.
5.5. Message Caching 5.5. Message Caching
Since the datastore contents change at unpredictable times, responses Since the datastore contents change at unpredictable times, responses
from a RESTCONF server generally SHOULD NOT be cached. from a RESTCONF server generally SHOULD NOT be cached.
The server SHOULD include a "Cache-Control" header field in every The server MUST include a "Cache-Control" header field in every
response that specifies whether the response should be cached. response that specifies whether the response should be cached.
Instead of relying on HTTP caching, the client SHOULD track the Instead of relying on HTTP caching, the client SHOULD track the
"ETag" and/or "Last-Modified" header fields returned by the server "ETag" and/or "Last-Modified" header fields returned by the server
for the datastore resource (or data resource if the server supports for the datastore resource (or data resource if the server supports
it). A retrieval request for a resource can include the it). A retrieval request for a resource can include the
"If-None-Match" and/or "If-Modified-Since" header fields, which will "If-None-Match" and/or "If-Modified-Since" header fields, which will
cause the server to return a "304 Not Modified" status-line if the cause the server to return a "304 Not Modified" status-line if the
resource has not changed. The client MAY use the HEAD method to resource has not changed. The client MAY use the HEAD method to
retrieve just the message header fields, which SHOULD include the retrieve just the message header fields, which SHOULD include the
skipping to change at page 85, line 11 skipping to change at page 85, line 11
prefix: rcmon prefix: rcmon
// RFC Ed.: replace XXXX with RFC number and remove this note // RFC Ed.: replace XXXX with RFC number and remove this note
reference: RFCXXXX reference: RFCXXXX
11.3. Media Types 11.3. Media Types
11.3.1. Media Type application/yang-data+xml 11.3.1. Media Type application/yang-data+xml
Type name: application Type name: application
Subtype name: yang-data Subtype name: yang-data+xml
Required parameters: None Required parameters: None
Optional parameters: None Optional parameters: None
Encoding considerations: 8-bit Encoding considerations: 8-bit
Each conceptual YANG data node is encoded according to the Each conceptual YANG data node is encoded according to the
XML Encoding Rules and Canonical Format for the specific XML Encoding Rules and Canonical Format for the specific
YANG data node type defined in [RFC7950]. YANG data node type defined in [RFC7950].
skipping to change at page 86, line 10 skipping to change at page 86, line 10
that utilize YANG defined data structures. that utilize YANG defined data structures.
Fragment identifier considerations: Fragment identifiers for Fragment identifier considerations: Fragment identifiers for
this type are not defined. All YANG data nodes are this type are not defined. All YANG data nodes are
accessible as resources using the path in the request URI. accessible as resources using the path in the request URI.
Additional information: Additional information:
Deprecated alias names for this type: N/A Deprecated alias names for this type: N/A
Magic number(s): N/A Magic number(s): N/A
File extension(s): .xml File extension(s): None
Macintosh file type code(s): "TEXT" Macintosh file type code(s): "TEXT"
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
Person & email address to contact for further information: See Person & email address to contact for further information: See
Authors' Addresses section of [RFCXXXX]. Authors' Addresses section of [RFCXXXX].
Intended usage: COMMON Intended usage: COMMON
skipping to change at page 87, line 36 skipping to change at page 87, line 36
that utilize YANG defined data structures. that utilize YANG defined data structures.
Fragment identifier considerations: The syntax and semantics Fragment identifier considerations: The syntax and semantics
of fragment identifiers are the same as specified for the of fragment identifiers are the same as specified for the
"application/json" media type. "application/json" media type.
Additional information: Additional information:
Deprecated alias names for this type: N/A Deprecated alias names for this type: N/A
Magic number(s): N/A Magic number(s): N/A
File extension(s): .json File extension(s): None
Macintosh file type code(s): "TEXT" Macintosh file type code(s): "TEXT"
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
Person & email address to contact for further information: See Person & email address to contact for further information: See
Authors' Addresses section of [RFCXXXX]. Authors' Addresses section of [RFCXXXX].
Intended usage: COMMON Intended usage: COMMON
skipping to change at page 89, line 5 skipping to change at page 89, line 5
:filter :filter
urn:ietf:params:restconf:capability:filter:1.0 urn:ietf:params:restconf:capability:filter:1.0
:replay :replay
urn:ietf:params:restconf:capability:replay:1.0 urn:ietf:params:restconf:capability:replay:1.0
:with-defaults :with-defaults
urn:ietf:params:restconf:capability:with-defaults:1.0 urn:ietf:params:restconf:capability:with-defaults:1.0
11.5. Registration of "restconf" URN sub-namespace
IANA has registered a new URN sub-namespace within the IETF URN Sub-
namespace for Registered Protocol Parameter Identifiers defined in
[RFC3553].
Registry Name: restconf
Specification: RFC XXXX
// RFC Ed.: replace XXXX with RFC number and remove this note
Repository: RESTCONF Capability URNs registry (Section 11.4)
Index value: Sub-parameters MUST be specified in UTF-8, using
standard URI encoding where necessary.
12. Security Considerations 12. Security Considerations
Section 2.1 states "A RESTCONF server MUST support the TLS protocol
[RFC5246]". This language leaves open the possibility that a
RESTCONF server might also support future versions of the TLS
protocol. Of specific concern, TLS 1.3 [I-D.ietf-tls-tls13]
introduces support for 0-RTT handshakes that can lead to security
issues for REST APIs, as described in the Appendix of the TLS 1.3
specification. It is therefore RECOMMENDED that RESTCONF servers do
not support 0-RTT at all (not even for idempotent requests) until an
update to this RFC guides otherwise.
Section 2.5 recommends TLS client certificate based authentication,
but allows the use of any authentication scheme defined in the HTTP
Authentication Scheme Registry. Implementations need to be aware
that the strength of these methods vary greatly, and that some may be
considered experimental. Selection of any of these schemes SHOULD be
performed after reading the Security Considerations section of the
RFC associated with the scheme's registry entry.
The "ietf-restconf-monitoring" YANG module defined in this memo is The "ietf-restconf-monitoring" YANG module defined in this memo is
designed to be accessed via the NETCONF protocol [RFC6241]. The designed to be accessed via the NETCONF protocol [RFC6241]. The
lowest NETCONF layer is the secure transport layer, and the lowest NETCONF layer is the secure transport layer, and the
mandatory-to-implement secure transport is Secure Shell (SSH) mandatory-to-implement secure transport is Secure Shell (SSH)
[RFC6242]. The NETCONF access control model [RFC6536] provides the [RFC6242]. The NETCONF access control model [RFC6536] provides the
means to restrict access for particular NETCONF users to a pre- means to restrict access for particular NETCONF users to a pre-
configured subset of all available NETCONF protocol operations and configured subset of all available NETCONF protocol operations and
content. content.
The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement
skipping to change at page 89, line 30 skipping to change at page 90, line 15
subset of all available RESTCONF protocol operations and content. subset of all available RESTCONF protocol operations and content.
This section provides security considerations for the resources This section provides security considerations for the resources
defined by the RESTCONF protocol. Security considerations for HTTPS defined by the RESTCONF protocol. Security considerations for HTTPS
are defined in [RFC7230]. RESTCONF does not specify which YANG are defined in [RFC7230]. RESTCONF does not specify which YANG
modules a server needs to support, except the modules a server needs to support, except the
"ietf-restconf-monitoring" module. Security considerations for the "ietf-restconf-monitoring" module. Security considerations for the
other modules manipulated by RESTCONF can be found in the documents other modules manipulated by RESTCONF can be found in the documents
defining those YANG modules. defining those YANG modules.
This document does not require use of a specific client
authentication mechanism or authorization model, but it does require
that a client authentication mechanism and authorization model is
used whenever a client accesses a protected resource. Client
authentication MUST be implemented using client certificates or MUST
be implemented using an HTTP authentication scheme. Client
authorization MAY be configured using the NETCONF Access Control
Model (NACM) [RFC6536].
Configuration information is by its very nature sensitive. Its Configuration information is by its very nature sensitive. Its
transmission in the clear and without integrity checking leaves transmission in the clear and without integrity checking leaves
devices open to classic eavesdropping and false data injection devices open to classic eavesdropping and false data injection
attacks. Configuration information often contains passwords, user attacks. Configuration information often contains passwords, user
names, service descriptions, and topological information, all of names, service descriptions, and topological information, all of
which are sensitive. There are many patterns of attack that have which are sensitive. There are many patterns of attack that have
been observed through operational practice with existing management been observed through operational practice with existing management
interfaces. It would be wise for implementers to research them, and interfaces. It would be wise for implementers to research them, and
take them into account when implementing this protocol. take them into account when implementing this protocol.
skipping to change at page 90, line 49 skipping to change at page 91, line 26
14.1. Normative References 14.1. Normative References
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996. November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
IETF URN Sub-namespace for Registered Protocol
Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June
2003, <http://www.rfc-editor.org/info/rfc3553>.
[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 3986, January 2005. RFC 3986, January 2005.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
skipping to change at page 91, line 29 skipping to change at page 92, line 11
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, March 2010. RFC 5789, March 2010.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020, Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010. October 2010.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, March 2011.
[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.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<http://www.rfc-editor.org/info/rfc6242>. <http://www.rfc-editor.org/info/rfc6242>.
[RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for
NETCONF", RFC 6243, June 2011. NETCONF", RFC 6243, June 2011.
skipping to change at page 92, line 31 skipping to change at page 93, line 8
[RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Conditional Requests", RFC 7232, June 2014. (HTTP/1.1): Conditional Requests", RFC 7232, June 2014.
[RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Authentication", RFC 7235, June 2014. (HTTP/1.1): Authentication", RFC 7235, June 2014.
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190,
RFC 7320, July 2014. RFC 7320, July 2014.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
2015, <http://www.rfc-editor.org/info/rfc7525>.
[RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the
NETCONF Protocol over Transport Layer Security (TLS) with NETCONF Protocol over Transport Layer Security (TLS) with
Mutual X.509 Authentication", RFC 7589, Mutual X.509 Authentication", RFC 7589,
DOI 10.17487/RFC7589, June 2015, DOI 10.17487/RFC7589, June 2015,
<http://www.rfc-editor.org/info/rfc7589>. <http://www.rfc-editor.org/info/rfc7589>.
[RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
Library", RFC 7895, June 2016. Library", RFC 7895, June 2016.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
skipping to change at page 93, line 27 skipping to change at page 94, line 9
[XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Recommendation Version 1.0", World Wide Web Consortium Recommendation
REC-xpath-19991116, November 1999, REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
14.2. Informative References 14.2. Informative References
[I-D.ietf-netconf-yang-patch] [I-D.ietf-netconf-yang-patch]
Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
Media Type", draft-ietf-netconf-yang-patch-08 (work in Media Type", draft-ietf-netconf-yang-patch-12 (work in
progress), March 2016. progress), October 2016.
[I-D.ietf-tls-tls13]
Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", draft-ietf-tls-tls13-18 (work in progress),
October 2016.
[rest-dissertation] [rest-dissertation]
Fielding, R., "Architectural Styles and the Design of Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000. Network-based Software Architectures", 2000.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 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. v16 to v17 A.1. v17 to v18
o addressed IESG review comments and clarifications
o addressed Alexey's DISCUSS items
o made Cache-Control MUST support, not SHOULD support
o add example for PUT on a datastore
o add IANA section for "restconf" URN sub-namespace
o clarify media type file extensions
A.2. v16 to v17
o various clarifications from NETCONF WG mailing list o various clarifications from NETCONF WG mailing list
o updated YANG 1.1 and YANG/JSON references to RFC numbers o updated YANG 1.1 and YANG/JSON references to RFC numbers
o fixed notification namespace and eventTime name bug o fixed notification namespace and eventTime name bug
o changed media type application/yang-data-xml to application/yang- o changed media type application/yang-data-xml to application/yang-
data+xml data+xml
o update fragment identifier considerations section for application/ o update fragment identifier considerations section for application/
yang-data+xml yang-data+xml
o clarify HTTP version requirements o clarify HTTP version requirements
A.2. v15 to v16 A.3. v15 to v16
o changed media type application/yang-data to application/yang-data- o changed media type application/yang-data to application/yang-data-
xml xml
o changed header to header field o changed header to header field
o added linewrap convention in terminology and applied in many o added linewrap convention in terminology and applied in many
examples examples
o clarified DELETE for leaf-list and list o clarified DELETE for leaf-list and list
skipping to change at page 94, line 35 skipping to change at page 95, line 37
o added 'yang-data extension' term and clarified 'YANG data o added 'yang-data extension' term and clarified 'YANG data
template' term template' term
o clarified that the fragment component is not part of the request o clarified that the fragment component is not part of the request
URI, per HTTP URI, per HTTP
o clarified request URI "api-path" syntax o clarified request URI "api-path" syntax
o clarified many examples o clarified many examples
A.3. v14 to v15 A.4. v14 to v15
o added text for HTTP/2 usage o added text for HTTP/2 usage
o changed media type definitions per review comments o changed media type definitions per review comments
o added some clarifications and typos o added some clarifications and typos
o added error-tag mapping for 406 and 412 errors o added error-tag mapping for 406 and 412 errors
o added clarifications based on ops-dir review by Lionel Morand o added clarifications based on ops-dir review by Lionel Morand
skipping to change at page 94, line 50 skipping to change at page 96, line 4
o added some clarifications and typos o added some clarifications and typos
o added error-tag mapping for 406 and 412 errors o added error-tag mapping for 406 and 412 errors
o added clarifications based on ops-dir review by Lionel Morand o added clarifications based on ops-dir review by Lionel Morand
o clarified PUT and POST differences for creating a data resource o clarified PUT and POST differences for creating a data resource
o clarify PUT for a datastore resource o clarify PUT for a datastore resource
o added clarifications from Gen-Art review by Robert Sparks o added clarifications from Gen-Art review by Robert Sparks
o clarified terminology in many places o clarified terminology in many places
A.4. v13 - v14 A.5. v13 - v14
This release addresses github issues #61, #62, #63, #65, #66, and This release addresses github issues #61, #62, #63, #65, #66, and
#67. #67.
o change term 'server' to 'NETCONF server' o change term 'server' to 'NETCONF server'
o add term 'RESTCONF server' also called 'server' o add term 'RESTCONF server' also called 'server'
o change term 'client' to 'NETCONF client' o change term 'client' to 'NETCONF client'
skipping to change at page 96, line 46 skipping to change at page 98, line 5
o update SSE reference o update SSE reference
o clarify leaf-list identifier encoding o clarify leaf-list identifier encoding
o removed all media types except yang-data o removed all media types except yang-data
o changed restconf-media-type extension to be more generic yang-data o changed restconf-media-type extension to be more generic yang-data
extension extension
A.5. v12 - v13 A.6. v12 - v13
o fix YANG library module examples (now called module-state) o fix YANG library module examples (now called module-state)
o fix terminology idnit issue o fix terminology idnit issue
o removed RFC 2818 reference (changed citation to RFC 7230) o removed RFC 2818 reference (changed citation to RFC 7230)
A.6. v11 - v12 A.7. v11 - v12
o clarify query parameter requirements o clarify query parameter requirements
o move filter query section to match table order in sec. 4.8 o move filter query section to match table order in sec. 4.8
o clarify that depth default is entire subtree for datastore o clarify that depth default is entire subtree for datastore
resource resource
o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml
skipping to change at page 97, line 32 skipping to change at page 98, line 39
o clarify that errors should be returned for any resource type o clarify that errors should be returned for any resource type
o clarified media subtype (not type) for error response o clarified media subtype (not type) for error response
o clarified client SHOULD (not MAY) specify errors format in Accept o clarified client SHOULD (not MAY) specify errors format in Accept
header header
o clarified terminology in many sections o clarified terminology in many sections
A.7. v10 - v11 A.8. v10 - v11
o change term 'operational data' to 'state data' o change term 'operational data' to 'state data'
o clarify :startup behavior o clarify :startup behavior
o clarify X.509 security text o clarify X.509 security text
o change '403 Forbidden' to '401 Unauthorized' for GET error o change '403 Forbidden' to '401 Unauthorized' for GET error
o clarify MUST have one "restconf" link relation o clarify MUST have one "restconf" link relation
skipping to change at page 97, line 45 skipping to change at page 99, line 4
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
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.8. v09 - v10 A.9. 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 100, line 11 skipping to change at page 101, line 17
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.9. v08 - v09 A.10. 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.10. v07 - v08 A.11. 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.11. v06 - v07 A.12. 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.12. v05 - v06 A.13. v05 - v06
o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug)
A.13. v04 - v05 A.14. 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 101, line 45 skipping to change at page 103, line 4
o made 'insert' and 'point' query parameters mandatory to implement o made 'insert' and 'point' query parameters mandatory to implement
o removed ":insert" capability URI o removed ":insert" capability URI
o renamed stream/encoding to stream/access o renamed stream/encoding to stream/access
o renamed stream/encoding/type to stream/access/encoding o renamed stream/encoding/type to stream/access/encoding
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.14. v03 - v04 A.15. 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 102, line 40 skipping to change at page 103, line 46
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.15. v02 - v03 A.16. 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
o fixed bugs in some examples o fixed bugs in some examples
o added "encoding" list within the "stream" list to allow different o added "encoding" list within the "stream" list to allow different
<events> URLs for XML and JSON encoding. <events> URLs for XML and JSON encoding.
o made XML MUST implement and JSON MAY implement for servers o made XML MUST implement and JSON MAY implement for servers
o re-add JSON notification examples (previously removed) o re-add JSON notification examples (previously removed)
o updated JSON references o updated JSON references
A.16. v01 - v02 A.17. 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 104, line 5 skipping to change at page 105, line 10
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.17. v00 - v01 A.18. 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 105, line 5 skipping to change at page 106, line 5
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.18. bierman:restconf-04 to ietf:restconf-00 A.19. bierman:restconf-04 to ietf:restconf-00
o updated open issues section o updated open issues section
Appendix B. Open Issues Appendix B. Open Issues
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
The RESTCONF issues are tracked on github.com: The RESTCONF issues are tracked on github.com:
https://github.com/netconf-wg/restconf/issues https://github.com/netconf-wg/restconf/issues
skipping to change at page 111, line 47 skipping to change at page 113, line 5
The client may then retrieve the top-level API resource, using the The client may then retrieve the top-level API resource, using the
root resource "/restconf". root resource "/restconf".
GET /restconf HTTP/1.1 GET /restconf HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data+json Accept: application/yang-data+json
The server might respond as follows: The server might respond as follows:
[RFC Editor Note: Adjust the date (2016-04-09) for ietf-yang-library
below to the date in the published ietf-yang-library YANG module, and
remove this note.]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2016 17:01:00 GMT Date: Mon, 23 Apr 2016 17:01:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+json Content-Type: application/yang-data+json
{ {
"ietf-restconf:restconf" : { "ietf-restconf:restconf" : {
"data" : {}, "data" : {},
"operations" : {}, "operations" : {},
"yang-library-version" : "2016-06-21" "yang-library-version" : "2016-06-21"
skipping to change at page 112, line 27 skipping to change at page 113, line 28
To request that the response content to be encoded in XML, the To request that the response content to be encoded in XML, the
"Accept" header can be used, as in this example request: "Accept" header can be used, as in this example request:
GET /restconf HTTP/1.1 GET /restconf HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data+xml Accept: application/yang-data+xml
The server will return the same conceptual data either way, which The server will return the same conceptual data either way, which
might be as follows : might be as follows :
[RFC Editor Note: Adjust the date for ietf-yang-library below to the
date in the published ietf-yang-library YANG module, and remove this
note.]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2016 17:01:00 GMT Date: Mon, 23 Apr 2016 17:01:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Content-Type: application/yang-data+xml Content-Type: application/yang-data+xml
<restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<data/> <data/>
<operations/> <operations/>
<yang-library-version>2016-06-21</yang-library-version> <yang-library-version>2016-06-21</yang-library-version>
skipping to change at page 113, line 11 skipping to change at page 114, line 7
In this example the client is retrieving the modules information from In this example the client is retrieving the modules information from
the server in JSON format: the server in JSON format:
GET /restconf/data/ietf-yang-library:modules-state HTTP/1.1 GET /restconf/data/ietf-yang-library:modules-state HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data+json Accept: application/yang-data+json
The server might respond as follows: The server might respond as follows:
[RFC Editor Note: Adjust the date for ietf-yang-library below to the
date in the published ietf-yang-library YANG module, and remove this
note.]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2016 17:01:00 GMT Date: Mon, 23 Apr 2016 17:01:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Last-Modified: Sun, 22 Apr 2016 01:00:14 GMT Last-Modified: Sun, 22 Apr 2016 01:00:14 GMT
Content-Type: application/yang-data+json Content-Type: application/yang-data+json
{ {
"ietf-yang-library:modules-state" : { "ietf-yang-library:modules-state" : {
"module-set-id" : "5479120c17a619545ea6aff7aa19838b036ebbd7", "module-set-id" : "5479120c17a619545ea6aff7aa19838b036ebbd7",
"module" : [ "module" : [
{ {
"name" : "foo", "name" : "foo",
"revision" : "2012-01-02", "revision" : "2012-01-02",
"schema" : "https://example.com/modules/foo/2012-01-02", "schema" : "https://example.com/modules/foo/2012-01-02",
"namespace" : "http://example.com/ns/foo", "namespace" : "http://example.com/ns/foo",
"feature" : [ "feature1", "feature2" ], "feature" : [ "feature1", "feature2" ],
"deviation" : [ "deviation" : [
{ {
"name" : "foo-dev", "name" : "foo-dev",
"revision" "2012-02-16" "revision" : "2012-02-16"
} }
], ],
"conformance-type" : "implement" "conformance-type" : "implement"
}, },
{ {
"name" : "ietf-yang-library", "name" : "ietf-yang-library",
"revision" : "2016-06-21", "revision" : "2016-06-21",
"schema" : "https://example.com/modules/\ "schema" : "https://example.com/modules/\
ietf-yang-library/2016-06-21", ietf-yang-library/2016-06-21",
"namespace" : "namespace" :
skipping to change at page 118, line 28 skipping to change at page 119, line 28
<name>Nick Cave and the Bad Seeds</name> <name>Nick Cave and the Bad Seeds</name>
<album> <album>
<name>Tender Prey</name> <name>Tender Prey</name>
<year>1988</year> <year>1988</year>
</album> </album>
</artist> </artist>
</library> </library>
</jukebox> </jukebox>
</data> </data>
D.2.4. Edit a Data Resource D.2.4. Replace a Datastore Resource
In this example, the entire configuration datastore contents are
being replaced. Any child nodes not present in the <data> element
but present in the server will be deleted.
PUT /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<jukebox xmlns="http://example.com/ns/example-jukebox">
<library>
<artist>
<name>Foo Fighters</name>
<album>
<name>One by One</name>
<year>2012</year>
</album>
</artist>
<artist>
<name>Nick Cave and the Bad Seeds</name>
<album>
<name>Tender Prey</name>
<year>1988</year>
</album>
</artist>
</library>
</jukebox>
</data>
D.2.5. Edit a Data Resource
In this example, the client modifies one data node by adding an In this example, the client modifies one data node by adding an
"album" sub-resource by sending a PATCH for the data resource: "album" sub-resource by sending a PATCH for the data resource:
PATCH /restconf/data/example-jukebox:jukebox/library/\ PATCH /restconf/data/example-jukebox:jukebox/library/\
artist=Nick%20Cave%20and%20the%20Bad%20Seeds HTTP/1.1 artist=Nick%20Cave%20and%20the%20Bad%20Seeds HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data+xml Content-Type: application/yang-data+xml
<artist xmlns="http://example.com/ns/example-jukebox"> <artist xmlns="http://example.com/ns/example-jukebox">
skipping to change at page 123, line 26 skipping to change at page 125, line 26
{ {
"name" : "Wasting Light", "name" : "Wasting Light",
"genre" : "example-jukebox:alternative", "genre" : "example-jukebox:alternative",
"year" : 2011, "year" : 2011,
"song" : [ "song" : [
{ {
"name" : "Wasting Light", "name" : "Wasting Light",
"location" : "location" :
"/media/foo/a7/wasting-light.mp3", "/media/foo/a7/wasting-light.mp3",
"format" : "MP3", "format" : "MP3",
"length" " 286 "length" : 286
}, },
{ {
"name" : "Rope", "name" : "Rope",
"location" : "/media/foo/a7/rope.mp3", "location" : "/media/foo/a7/rope.mp3",
"format" : "MP3", "format" : "MP3",
"length" " 259 "length" : 259
} }
] ]
} }
] ]
} }
] ]
}, },
"playlist" : [ "playlist" : [
{ {
"name" : "Foo-One", "name" : "Foo-One",
skipping to change at page 125, line 45 skipping to change at page 127, line 45
(which is "data" in this example). The "module-set-id" leaf is not (which is "data" in this example). The "module-set-id" leaf is not
returned because it is not selected in the fields expression. returned because it is not selected in the fields expression.
GET /restconf/data?fields=ietf-yang-library:modules-state/\ GET /restconf/data?fields=ietf-yang-library:modules-state/\
module(name;revision) HTTP/1.1 module(name;revision) HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang-data+json Accept: application/yang-data+json
The server might respond as follows. The server might respond as follows.
[RFC Editor Note: Adjust the date for ietf-yang-library below to the
date in the published ietf-yang-library YANG module, and remove this
note.]
[RFC Editor Note: Adjust the date for ietf-restconf-monitoring below [RFC Editor Note: Adjust the date for ietf-restconf-monitoring below
to the date in the published ietf-restconf-monitoring YANG module, to the date in the published ietf-restconf-monitoring YANG module,
and remove this note.] and remove this note.]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2016 17:01:00 GMT Date: Mon, 23 Apr 2016 17:01:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang-data+json Content-Type: application/yang-data+json
{ {
"ietf-restconf:data" : { "ietf-restconf:data" : {
skipping to change at page 126, line 27 skipping to change at page 128, line 27
{ {
"name" : "ietf-inet-types", "name" : "ietf-inet-types",
"revision" : "2013-07-15" "revision" : "2013-07-15"
}, },
{ {
"name" : "ietf-restconf-monitoring", "name" : "ietf-restconf-monitoring",
"revision" : "2016-03-16" "revision" : "2016-03-16"
}, },
{ {
"name" : "ietf-yang-library", "name" : "ietf-yang-library",
"revision" : "2016-04-09" "revision" : "2016-06-21"
}, },
{ {
"name" : "ietf-yang-types", "name" : "ietf-yang-types",
"revision" : "2013-07-15" "revision" : "2013-07-15"
} }
] ]
} }
} }
} }
 End of changes. 82 change blocks. 
181 lines changed or deleted 257 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/