draft-ietf-netconf-restconf-10.txt   draft-ietf-netconf-restconf-11.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: September 17, 2016 Tail-f Systems Expires: October 12, 2016 Tail-f Systems
K. Watsen K. Watsen
Juniper Networks Juniper Networks
March 16, 2016 April 10, 2016
RESTCONF Protocol RESTCONF Protocol
draft-ietf-netconf-restconf-10 draft-ietf-netconf-restconf-11
Abstract Abstract
This document describes an HTTP-based protocol that provides a This document describes an HTTP-based protocol that provides a
programmatic interface for accessing data defined in YANG, using the programmatic interface for accessing data defined in YANG, using the
datastores defined in NETCONF. datastores defined in NETCONF.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 17, 2016. This Internet-Draft will expire on October 12, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.5. URI Template . . . . . . . . . . . . . . . . . . . . 9 1.1.5. URI Template . . . . . . . . . . . . . . . . . . . . 9
1.1.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 9 1.1.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 9
1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 9 1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 9
1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 10 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 10
1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 11 1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 11
1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 12 1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 12
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 13 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 13
skipping to change at page 2, line 48 skipping to change at page 2, line 48
3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 17 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 17
3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18
3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 18 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 18
3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19
3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 19 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 19
3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20
3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21
3.5.1. Encoding Data Resource Identifiers in the Request URI 22 3.5.1. Encoding Data Resource Identifiers in the Request URI 22
3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 25 3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 25
3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 25 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 25
3.6.1. Encoding Operation Resource Input Parameters . . . . 26 3.6.1. Encoding Operation Resource Input Parameters . . . . 27
3.6.2. Encoding Operation Resource Output Parameters . . . . 29 3.6.2. Encoding Operation Resource Output Parameters . . . . 30
3.6.3. Encoding Operation Resource Errors . . . . . . . . . 31 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 31
3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 32 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 33
3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 33 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 34
3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 33 3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 34
4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 34 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 37 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 37
4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 38 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 38
4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 41 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 42
4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 42 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 43 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 43
4.8.1. The "content" Query Parameter . . . . . . . . . . . . 44 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 44
4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 45 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 45
4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 45 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 45
4.8.4. The "insert" Query Parameter . . . . . . . . . . . . 46 4.8.4. The "insert" Query Parameter . . . . . . . . . . . . 46
4.8.5. The "point" Query Parameter . . . . . . . . . . . . . 47 4.8.5. The "point" Query Parameter . . . . . . . . . . . . . 47
4.8.6. The "filter" Query Parameter . . . . . . . . . . . . 47 4.8.6. The "filter" Query Parameter . . . . . . . . . . . . 47
4.8.7. The "start-time" Query Parameter . . . . . . . . . . 48 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 48
4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 49 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 49
4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 50 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 50
skipping to change at page 4, line 16 skipping to change at page 4, line 16
11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 78 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 78
11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 78 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 78
11.3. application/yang Media Sub Types . . . . . . . . . . . . 79 11.3. application/yang Media Sub Types . . . . . . . . . . . . 79
11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 80 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 80
12. Security Considerations . . . . . . . . . . . . . . . . . . . 81 12. Security Considerations . . . . . . . . . . . . . . . . . . . 81
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 82 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 82
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 82 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 82
14.1. Normative References . . . . . . . . . . . . . . . . . . 82 14.1. Normative References . . . . . . . . . . . . . . . . . . 82
14.2. Informative References . . . . . . . . . . . . . . . . . 85 14.2. Informative References . . . . . . . . . . . . . . . . . 85
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 85 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 85
A.1. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 85 A.1. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 85
A.2. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 87 A.2. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 86
A.3. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.3. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 88
A.4. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.4. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 88
A.5. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.5. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 89
A.6. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.6. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 89
A.7. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 89 A.7. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 89
A.8. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 90 A.8. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 90
A.9. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 90 A.9. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 91
A.10. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 91 A.10. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 91
A.11. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 92 A.11. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 92
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 92 A.12. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 93
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 92 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 93
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 93 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 93
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 98 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 94
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 99
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 99 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 99
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 99 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 99
D.1.2. Retrieve The Server Module Information . . . . . . . 100 D.1.2. Retrieve The Server Module Information . . . . . . . 100
D.1.3. Retrieve The Server Capability Information . . . . . 101 D.1.3. Retrieve The Server Capability Information . . . . . 102
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 102 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 103
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 102 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 103
D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 103 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 104
D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 104 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 104
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 104 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 105
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 104 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 105
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 107 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 108
D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 110 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 111
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 111 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 112
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 112 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 112
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 113 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 113
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 113 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 114
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 113 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 114
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 114 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 114
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 116
1. Introduction 1. Introduction
There is a need for standard mechanisms to allow Web applications to There is a need for standard mechanisms to allow Web applications to
access the configuration data, operational data, data-model specific access the configuration data, state data, data-model specific
protocol operations, and event notifications within a networking protocol operations, and event notifications within a networking
device, in a modular and extensible manner. device, in a modular and extensible manner.
This document defines an HTTP [RFC7230] based protocol called This document defines an HTTP [RFC7230] based protocol called
RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or
YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using datastores YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using datastores
defined in NETCONF [RFC6241]. defined in NETCONF [RFC6241].
NETCONF defines configuration datastores and a set of Create, NETCONF defines configuration datastores and a set of Create,
Retrieve, Update, Delete (CRUD) operations that can be used to access Retrieve, Update, Delete (CRUD) operations that can be used to access
these datastores. The YANG language defines the syntax and semantics these datastores. The YANG language defines the syntax and semantics
of datastore content, operational data, protocol operations, and of datastore content, state data, protocol operations, and event
event notifications. notifications.
RESTCONF uses HTTP operations to provide CRUD operations on a RESTCONF uses HTTP operations to provide CRUD operations on a
conceptual datastore containing YANG-defined data, which is conceptual datastore containing YANG-defined data, which is
compatible with a server which implements NETCONF datastores. compatible with a server which implements NETCONF datastores.
If a RESTCONF server is co-located with a NETCONF server, then there If a RESTCONF server is co-located with a NETCONF server, then there
are protocol interactions to be considered, as described in are protocol interactions to be considered, as described in
Section 1.4. The server MAY provide access to specific datastores Section 1.4. The server MAY provide access to specific datastores
using operation resources, as described in Section 3.6. using operation resources, as described in Section 3.6.
skipping to change at page 7, line 36 skipping to change at page 7, line 32
o key leaf o key leaf
o leaf o leaf
o leaf-list o leaf-list
o list o list
o non-presence container (or NP-container) o non-presence container (or NP-container)
o ordered-by system
o ordered-by user o ordered-by user
o presence container (or P-container) o presence container (or P-container)
o RPC operation o RPC operation
o top-level data node o top-level data node
1.1.4. Terms 1.1.4. Terms
skipping to change at page 10, line 20 skipping to change at page 10, line 16
operations, enabling basic CRUD operations on a hierarchy of operations, enabling basic CRUD operations on a hierarchy of
conceptual resources. conceptual resources.
The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data
resources represented by YANG data models. These basic edit resources represented by YANG data models. These basic edit
operations allow the running configuration to be altered in an all- operations allow the running configuration to be altered in an all-
or-none fashion. or-none fashion.
RESTCONF is not intended to replace NETCONF, but rather provide an RESTCONF is not intended to replace NETCONF, but rather provide an
additional interface that follows Representational State Transfer additional interface that follows Representational State Transfer
(REST) principles and is compatible with a resource-oriented device (REST) principles [rest-dissertation], and is compatible with a
abstraction. resource-oriented device abstraction.
The following figure shows the system components if a RESTCONF server The following figure shows the system components if a RESTCONF server
is co-located with a NETCONF server: is co-located with a NETCONF server:
+-----------+ +-----------------+ +-----------+ +-----------------+
| Web app | <-------> | | | Web app | <-------> | |
+-----------+ HTTP | network device | +-----------+ HTTP | network device |
| | | |
+-----------+ | +-----------+ | +-----------+ | +-----------+ |
| NMS app | <-------> | | datastore | | | NMS app | <-------> | | datastore | |
skipping to change at page 12, line 9 skipping to change at page 11, line 46
configuration nodes in {+restconf}/data are performed in the configuration nodes in {+restconf}/data are performed in the
candidate configuration datastore. The candidate MUST be candidate configuration datastore. The candidate MUST be
automatically committed to running immediately after each successful automatically committed to running immediately after each successful
edit. Any edits from other sources that are in the candidate edit. Any edits from other sources that are in the candidate
datastore will also be committed. If a confirmed-commit procedure is datastore will also be committed. If a confirmed-commit procedure is
in progress, then this commit will act as the confirming commit. If in progress, then this commit will act as the confirming commit. If
the server is expecting a "persist-id" parameter to complete the the server is expecting a "persist-id" parameter to complete the
confirmed commit procedure then the RESTCONF edit operation MUST fail confirmed commit procedure then the RESTCONF edit operation MUST fail
with a "409 Conflict" status-line. with a "409 Conflict" status-line.
If the device supports :startup, the device automatically copies the If the device supports :startup, the device MUST automatically update
content of running to startup after running has been updated as a the non-volatile "startup datastore", after the running datastore has
consequence of a RESTCONF edit operation. been updated as a consequence of a RESTCONF edit operation.
If a datastore that would be modified by a RESTCONF operation has an If a datastore that would be modified by a RESTCONF operation has an
active lock, the RESTCONF edit operation MUST fail with a "409 active lock, the RESTCONF edit operation MUST fail with a "409
Conflict" status-line. Conflict" status-line.
1.5. RESTCONF Extensibility 1.5. RESTCONF Extensibility
There are two extensibility mechanisms built into RESTCONF: There are two extensibility mechanisms built into RESTCONF:
o protocol version o protocol version
skipping to change at page 13, line 45 skipping to change at page 13, line 38
be sent in the same order that requests are received. No other be sent in the same order that requests are received. No other
versions of HTTP are supported for use with RESTCONF. versions of HTTP are supported for use with RESTCONF.
2.2. HTTPS with X.509v3 Certificates 2.2. HTTPS with X.509v3 Certificates
Given the nearly ubiquitous support for HTTP over TLS [RFC7230], Given the nearly ubiquitous support for HTTP over TLS [RFC7230],
RESTCONF implementations MUST support the "https" URI scheme, which RESTCONF implementations MUST support the "https" URI scheme, which
has the IANA assigned default port 443. has the IANA assigned default port 443.
RESTCONF servers MUST present an X.509v3 based certificate when RESTCONF servers MUST present an X.509v3 based certificate when
establishing a TLS connection with a RESTCONF client. The exclusive establishing a TLS connection with a RESTCONF client. The use the
use the X.509v3 based certificates is consistent with NETCONF over X.509v3 based certificates is consistent with NETCONF over TLS
TLS [RFC7589]. [RFC7589].
2.3. Certificate Validation 2.3. Certificate Validation
The RESTCONF client MUST 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. The presented X.509 certificate MUST also be considered certificate, or match the presented X.509 certificate with locally
valid if it matches a locally configured certificate fingerprint. If configured certificate fingerprints.
X.509 certificate path validation fails and the presented X.509
certificate does not match a locally configured certificate The presented X.509 certificate MUST also be considered valid if it
fingerprint, the connection MUST be terminated as defined in matches a locally configured certificate fingerprint. If X.509
[RFC5246]. certificate path validation fails and the presented X.509 certificate
does not match a locally configured certificate fingerprint, the
connection MUST be terminated as defined in [RFC5246].
2.4. Authenticated Server Identity 2.4. Authenticated Server Identity
The RESTCONF client MUST check the identity of the server according The RESTCONF client MUST check the identity of the server according
to Section 6 of [RFC6125], including processing the outcome as to Section 6 of [RFC6125], including processing the outcome as
described in Section 6.6 of [RFC6125]. described in Section 6.6 of [RFC6125].
2.5. Authenticated Client Identity 2.5. Authenticated Client Identity
The RESTCONF server MUST authenticate client access to any protected The RESTCONF server MUST authenticate client access to any protected
skipping to change at page 15, line 31 skipping to change at page 15, line 28
The RESTCONF protocol does not include a data resource discovery The RESTCONF protocol does not include a data resource discovery
mechanism. Instead, the definitions within the YANG modules mechanism. Instead, the definitions within the YANG modules
advertised by the server are used to construct a predictable advertised by the server are used to construct a predictable
operation or data resource identifier. operation or data resource identifier.
3.1. Root Resource Discovery 3.1. Root Resource Discovery
In line with the best practices defined by [RFC7320], RESTCONF In line with the best practices defined by [RFC7320], RESTCONF
enables deployments to specify where the RESTCONF API is located. enables deployments to specify where the RESTCONF API is located.
When first connecting to a RESTCONF server, a RESTCONF client MUST When first connecting to a RESTCONF server, a RESTCONF client MUST
determine the root of the RESTCONF API. The client discovers this by determine the root of the RESTCONF API. There MUST be exactly one
getting the "/.well-known/host-meta" resource ([RFC6415]) and using "restconf" link relation returned by the device.
the <Link> element containing the "restconf" attribute :
The client discovers this by getting the "/.well-known/host-meta"
resource ([RFC6415]) and using the <Link> element containing the
"restconf" attribute :
Example returning /restconf: Example returning /restconf:
Request Request
------- -------
GET /.well-known/host-meta HTTP/1.1 GET /.well-known/host-meta HTTP/1.1
Host: example.com Host: example.com
Accept: application/xrd+xml Accept: application/xrd+xml
Response Response
skipping to change at page 18, line 20 skipping to change at page 18, line 20
| data | Contains all data resources | | data | Contains all data resources |
| operations | Data-model specific operations | | operations | Data-model specific operations |
| yang-library-version | ietf-yang-library module date | | yang-library-version | ietf-yang-library module date |
+----------------------+--------------------------------+ +----------------------+--------------------------------+
RESTCONF API Resource RESTCONF API Resource
3.3.1. {+restconf}/data 3.3.1. {+restconf}/data
This mandatory resource represents the combined configuration and This mandatory resource represents the combined configuration and
operational data resources that can be accessed by a client. It state data resources that can be accessed by a client. It cannot be
cannot be created or deleted by the client. The datastore resource created or deleted by the client. The datastore resource type is
type is defined in Section 3.4. defined in Section 3.4.
Example: Example:
This example request by the client would retrieve only the non- This example request by the client would retrieve only the non-
configuration data nodes that exist within the "library" resource, configuration data nodes that exist within the "library" resource,
using the "content" query parameter (see Section 4.8.1). using the "content" query parameter (see Section 4.8.1).
GET /restconf/data/example-jukebox:jukebox/library GET /restconf/data/example-jukebox:jukebox/library
?content=nonconfig HTTP/1.1 ?content=nonconfig HTTP/1.1
Host: example.com Host: example.com
skipping to change at page 19, line 37 skipping to change at page 19, line 37
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:30 GMT Date: Mon, 23 Apr 2012 17:01:30 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Pragma: no-cache
Content-Type: application/yang.data+xml Content-Type: application/yang.data+xml
<yang-library-version <yang-library-version
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
2016-02-01 2016-04-09
</yang-library-version> </yang-library-version>
3.4. Datastore Resource 3.4. Datastore Resource
The "{+restconf}/data" subtree represents the datastore resource The "{+restconf}/data" subtree represents the datastore resource
type, which is a collection of configuration and operational data type, which is a collection of configuration data and state data
nodes. nodes.
This resource type is an abstraction of the system's underlying This resource type is an abstraction of the system's underlying
datastore implementation. It is used to simplify resource editing datastore implementation. It is used to simplify resource editing
for the client. The RESTCONF datastore resource is a conceptual for the client. The RESTCONF datastore resource is a conceptual
collection of all configuration and operational data that is present collection of all configuration and state data that is present on the
on the device. device.
Configuration edit transaction management and configuration Configuration edit transaction management and configuration
persistence are handled by the server and not controlled by the persistence are handled by the server and not controlled by the
client. A datastore resource can be written directly with the POST client. A datastore resource can be written directly with the POST
and PATCH methods. Each RESTCONF edit of a datastore resource is and PATCH methods. Each RESTCONF edit of a datastore resource is
saved to non-volatile storage by the server. saved to non-volatile storage by the server, if the server supports
non-volatile storage of configuration data.
3.4.1. Edit Collision Detection 3.4.1. Edit Collision Detection
Two "edit collision detection" mechanisms are provided in RESTCONF, Two "edit collision detection" mechanisms are provided in RESTCONF,
for datastore and data resources. for datastore and data resources.
3.4.1.1. Timestamp 3.4.1.1. Timestamp
The last change time is maintained and the "Last-Modified" The last change time is maintained and the "Last-Modified"
([RFC7232], Section 2.2) header is returned in the response for a ([RFC7232], Section 2.2) header is returned in the response for a
skipping to change at page 21, line 26 skipping to change at page 21, line 21
targeted by the request-line of an HTTP operation. Containers, targeted by the request-line of an HTTP operation. Containers,
leafs, leaf-list entries, list entries, anydata and anyxml nodes are leafs, leaf-list entries, list entries, anydata and anyxml nodes are
data resources. data resources.
The representation maintained for each data resource is the YANG The representation maintained for each data resource is the YANG
defined subtree for that node. HTTP operations on a data resource defined subtree for that node. HTTP operations on a data resource
affect both the targeted data node and all its descendants, if any. affect both the targeted data node and all its descendants, if any.
For configuration data resources, the server SHOULD maintain a last- For configuration data resources, the server SHOULD maintain a last-
modified timestamp for the resource, and return the "Last-Modified" modified timestamp for the resource, and return the "Last-Modified"
header when it is retrieved with the GET or HEAD methods. If header when it is retrieved with the GET or HEAD methods.
maintained, the resource timestamp MUST be set to the current time
The "Last-Modified" header information can be used by a RESTCONF
client in subsequent requests, within the "If-Modified-Since" and
"If-Unmodified-Since" headers.
If maintained, the resource timestamp MUST be set to the current time
whenever the resource or any configuration resource within the whenever the resource or any configuration resource within the
resource is altered. If not maintained, then the resource timestamp resource is altered. If not maintained, then the resource timestamp
for the datastore MUST be used instead. for the datastore MUST be used instead.
This timestamp is only affected by configuration data resources, and This timestamp is only affected by configuration data resources, and
MUST NOT be updated for changes to non-configuration data. MUST NOT be updated for changes to non-configuration data.
For configuration data resources, the server SHOULD maintain a For configuration data resources, the server SHOULD maintain a
resource entity tag for the resource, and return the "ETag" header resource entity tag for the resource, and return the "ETag" header
when it is retrieved as the target resource with the GET or HEAD when it is retrieved as the target resource with the GET or HEAD
methods. If maintained, the resource entity tag MUST be updated methods. If maintained, the resource entity tag MUST be updated
whenever the resource or any configuration resource within the whenever the resource or any configuration resource within the
resource is altered. If not maintained, then the resource entity tag resource is altered. If not maintained, then the resource entity tag
for the datastore MUST be used instead. for the datastore MUST be used instead.
The "ETag" header information can be used by a RESTCONF client in
subsequent requests, within the "If-Match" and "If-None-Match"
headers.
This entity tag is only affected by configuration data resources, and This entity tag is only affected by configuration data resources, and
MUST NOT be updated for changes to non-configuration data. MUST NOT be updated for changes to non-configuration data.
A data resource can be retrieved with the GET method. Data resources A data resource can be retrieved with the GET method. Data resources
are accessed via the "{+restconf}/data" entry point. This sub-tree are accessed via the "{+restconf}/data" entry point. This sub-tree
is used to retrieve and edit data resources. is used to retrieve and edit data resources.
A configuration data resource can be altered by the client with some A configuration data resource can be altered by the client with some
or all of the edit operations, depending on the target resource and or all of the edit operations, depending on the target resource and
the specific operation. Refer to Section 4 for more details on edit the specific operation. Refer to Section 4 for more details on edit
skipping to change at page 25, line 21 skipping to change at page 25, line 33
RESTCONF requires that a server report its default handling mode (see RESTCONF requires that a server report its default handling mode (see
Section 9.1.2 for details). If the optional "with-defaults" query Section 9.1.2 for details). If the optional "with-defaults" query
parameter is supported by the server, a client may use it to control parameter is supported by the server, a client may use it to control
retrieval of default values (see Section 4.8.9 for details). retrieval of default values (see Section 4.8.9 for details).
If a leaf or leaf-list is missing from the configuration and there is If a leaf or leaf-list is missing from the configuration and there is
a YANG-defined default for that data resource, then the server MUST a YANG-defined default for that data resource, then the server MUST
use the YANG-defined default as the configured value. use the YANG-defined default as the configured value.
If the target of a GET method is a data node that represents a leaf If the target of a GET method is a data node that represents a leaf
that has a default value, and the leaf has not been given a value that has a default value, and the leaf has not been configured yet,
yet, the server MUST return the default value that is in use by the the server MUST return the default value that is in use by the
server. server.
If the target of a GET method is a data node that represents a If the target of a GET method is a data node that represents a
container or list that has any child resources with default values, container or list that has any child resources with default values,
for the child resources that have not been given value yet, the for the child resources that have not been given value yet, the
server MAY return the default values that are in use by the server, server MAY return the default values that are in use by the server,
in accordance with its reported default handing mode and query in accordance with its reported default handing mode and query
parameters passed by the client. parameters passed by the client.
3.6. Operation Resource 3.6. Operation Resource
skipping to change at page 26, line 20 skipping to change at page 26, line 33
For example, if "module-A" defined a "reset-all" action in the For example, if "module-A" defined a "reset-all" action in the
container "interfaces", then invoking this action would be requested container "interfaces", then invoking this action would be requested
as follows: as follows:
POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1
Server example.com Server example.com
If the "rpc" or "action" statement has an "input" section, then a If the "rpc" or "action" statement has an "input" section, then a
message-body MAY be sent by the client in the request, otherwise the message-body MAY be sent by the client in the request, otherwise the
request message MUST NOT include a message-body. If the "input" request message MUST NOT include a message-body. If the "input"
section contains mandatory parameters, then a message-body MUST be objcet tree contains mandatory parameters, then a message-body MUST
sent by the client. be sent by the client. A mandatory parameter is a leaf or choice
with a "mandatory" statement set to "true", or a list or leaf-list
than have a "min-elements" statement value greater than zero.
If the operation is invoked without errors, and if the "rpc" or If the operation is invoked without errors, and if the "rpc" or
"action" statement has an "output" section, then a message-body MAY "action" statement has an "output" section, then a message-body MAY
be sent by the server in the response, otherwise the response message be sent by the server in the response, otherwise the response message
MUST NOT include a message-body in the response message, and MUST MUST NOT include a message-body in the response message, and MUST
send a "204 No Content" status-line instead. send a "204 No Content" status-line instead.
If the operation input is not valid, or the operation is invoked but If the operation input is not valid, or the operation is invoked but
errors occur, then a message-body MUST be sent by the server, errors occur, then a message-body MUST be sent by the server,
containing an "errors" resource, as defined in Section 3.9. A containing an "errors" resource, as defined in Section 3.9. A
skipping to change at page 29, line 35 skipping to change at page 29, line 50
The server might respond: The server might respond:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 25 Apr 2012 11:01:00 GMT Date: Mon, 25 Apr 2012 11:01:00 GMT
Server: example-server Server: example-server
The same example request message is shown here using JSON encoding The same example request message is shown here using JSON encoding
(text wrap for display purposes): (text wrap for display purposes):
POST /restconf/data/example-action:interfaces/interface=eth0 POST /restconf/data/example-actions:interfaces/interface=eth0
/reset HTTP/1.1 /reset HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang.operation+json Content-Type: application/yang.operation+json
{ "example-action:input" : { { "example-actions:input" : {
"delay" : 600 "delay" : 600
} }
} }
3.6.2. Encoding Operation Resource Output Parameters 3.6.2. Encoding Operation Resource Output Parameters
If the "rpc" or "action" statement has an "output" section, then the If the "rpc" or "action" statement has an "output" section, then the
"output" node is provided in the message-body, corresponding to the "output" node is provided in the message-body, corresponding to the
YANG data definition statements within the "output" section. YANG data definition statements within the "output" section.
The request URI is not returned in the response. This URI might have
context information required to associate the output to the specific
"rpc" or "action" statement used in the request.
Examples: Examples:
RPC Output Example: RPC Output Example:
The "example-ops" YANG module defined in Section 3.6.1 is used for The "example-ops" YANG module defined in Section 3.6.1 is used for
this example. this example.
The client might send the following POST request message to invoke The client might send the following POST request message to invoke
the "get-reboot-info" operation: the "get-reboot-info" operation:
skipping to change at page 36, line 7 skipping to change at page 36, line 23
4.3. GET 4.3. GET
The GET method is sent by the client to retrieve data and meta-data The GET method is sent by the client to retrieve data and meta-data
for a resource. It is supported for all resource types, except for a resource. It is supported for all resource types, except
operation resources. The request MUST contain a request URI that operation resources. The request MUST contain a request URI that
contains at least the entry point. contains at least the entry point.
The server MUST NOT return any data resources for which the user does The server MUST NOT return any data resources for which the user does
not have read privileges. If the user is not authorized to read the not have read privileges. If the user is not authorized to read the
target resource, an error response containing a "403 Forbidden" target resource, an error response containing a "401 Unauthorized"
status-line SHOULD be returned. A server MAY return a "404 Not status-line SHOULD be returned. A server MAY return a "404 Not
Found" status-line, as described in section 6.5.3 in [RFC7231]. Found" status-line, as described in section 6.5.3 in [RFC7231].
If the user is authorized to read some but not all of the target If the user is authorized to read some but not all of the target
resource, the unauthorized content is omitted from the response resource, the unauthorized content is omitted from the response
message-body, and the authorized content is returned to the client. message-body, and the authorized content is returned to the client.
If any content is returned to the client, then the server MUST send a If any content is returned to the client, then the server MUST send a
valid response message-body. More than one element MUST NOT be valid response message-body. More than one element MUST NOT be
returned for XML encoding. returned for XML encoding.
skipping to change at page 37, line 41 skipping to change at page 38, line 8
4.4.1. Create Resource Mode 4.4.1. Create Resource Mode
If the target resource type is a datastore or data resource, then the If the target resource type is a datastore or data resource, then the
POST is treated as a request to create a top-level resource or child POST is treated as a request to create a top-level resource or child
resource, respectively. The message-body is expected to contain the resource, respectively. The message-body is expected to contain the
content of a child resource to create within the parent (target content of a child resource to create within the parent (target
resource). The message-body MUST NOT contain more than one instance resource). The message-body MUST NOT contain more than one instance
of the expected data resource. The data-model for the child tree is of the expected data resource. The data-model for the child tree is
the subtree as defined by YANG for the child resource. the subtree as defined by YANG for the child resource.
The "insert" and "point" query parameters are supported by the POST The "insert" and "point" query parameters MUST be supported by the
method for datastore and data resources. If the server implements POST method for datastore and data resources. These parameters are
any YANG module that contains a configuration data node that is only allowed if the list or leaf-list is ordered-by user.
"ordered-by" user, then the "insert" and "point" query parameters
MUST be supported. If not, then these parameters are not applicable.
If the POST method succeeds, a "201 Created" status-line is returned If the POST method succeeds, a "201 Created" status-line is returned
and there is no response message-body. A "Location" header and there is no response message-body. A "Location" header
identifying the child resource that was created MUST be present in identifying the child resource that was created MUST be present in
the response in this case. the response in this case.
If the data resource already exists, then the POST request MUST fail If the data resource already exists, then the POST request MUST fail
and a "409 Conflict" status-line MUST be returned. and a "409 Conflict" status-line MUST be returned.
If the user is not authorized to create the target resource, an error If the user is not authorized to create the target resource, an error
skipping to change at page 39, line 41 skipping to change at page 40, line 6
The PUT method is sent by the client to create or replace the target The PUT method is sent by the client to create or replace the target
data resource. A request message-body MUST be present, representing data resource. A request message-body MUST be present, representing
the new data resource, or the server MUST return "400 Bad Request" the new data resource, or the server MUST return "400 Bad Request"
status-line. status-line.
The only target resource media type that supports PUT is the data The only target resource media type that supports PUT is the data
resource. The message-body is expected to contain the content used resource. The message-body is expected to contain the content used
to create or replace the target resource. to create or replace the target resource.
The "insert" (Section 4.8.4) and "point" (Section 4.8.5) query The "insert" (Section 4.8.4) and "point" (Section 4.8.5) query
parameters are supported by the PUT method for data resources. parameters MUST be supported by the PUT method for data resources.
These parameters are only allowed if the list or leaf-list is
ordered-by user.
Consistent with [RFC7231], if the PUT request creates a new resource, Consistent with [RFC7231], if the PUT request creates a new resource,
a "201 Created" status-line is returned. If an existing resource is a "201 Created" status-line is returned. If an existing resource is
modified, a "204 No Content" status-line is returned. modified, a "204 No Content" status-line is returned.
If the user is not authorized to create or replace the target If the user is not authorized to create or replace the target
resource an error response containing a "403 Forbidden" status-line resource an error response containing a "403 Forbidden" status-line
SHOULD be returned. A server MAY return a "404 Not Found" status- SHOULD be returned. A server MAY return a "404 Not Found" status-
line, as described in section 6.5.3 in [RFC7231]. All other error line, as described in section 6.5.3 in [RFC7231]. All other error
responses are handled according to the procedures defined in responses are handled according to the procedures defined in
Section 7. Section 7.
If the target resource represents a YANG leaf-list, then the PUT If the target resource represents a YANG leaf-list, then the PUT
method MUST not change the value of the leaf-list instance. method MUST NOT change the value of the leaf-list instance.
If the target resource represents a YANG list instance, then the PUT If the target resource represents a YANG list instance, then the PUT
method MUST NOT change any key leaf values in the message-body method MUST NOT change any key leaf values in the message-body
representation. representation.
If the server implements any YANG module that contains a
configuration data node that is "ordered-by" user, then the "insert"
and "point" query parameters MUST be supported. If not, then these
parameters are not applicable.
Example: Example:
An "album" child resource defined in the "example-jukebox" YANG An "album" child resource defined in the "example-jukebox" YANG
module is replaced or created if it does not already exist. module is replaced or created if it does not already exist.
To replace the "album" resource contents, the client might send as To replace the "album" resource contents, the client might send as
follows. Note that the request-line is wrapped for display purposes follows. Note that the request-line is wrapped for display purposes
only: only:
PUT /restconf/data/example-jukebox:jukebox/ PUT /restconf/data/example-jukebox:jukebox/
skipping to change at page 43, line 50 skipping to change at page 44, line 7
| Name | Methods | Description | | Name | Methods | Description |
+-------------------+-------------+---------------------------------+ +-------------------+-------------+---------------------------------+
| content | GET | Select config and/or non-config | | content | GET | Select config and/or non-config |
| | | data resources | | | | data resources |
| depth | GET | Request limited sub-tree depth | | depth | GET | Request limited sub-tree depth |
| | | in the reply content | | | | in the reply content |
| fields | GET | Request a subset of the target | | fields | GET | Request a subset of the target |
| | | resource contents | | | | resource contents |
| filter | GET | Boolean notification filter for | | filter | GET | Boolean notification filter for |
| | | event stream resources | | | | event stream resources |
| insert | POST, PUT | Insertion mode for user-ordered | | insert | POST, PUT | Insertion mode for ordered-by |
| | | data resources | | | | user data resources |
| point | POST, PUT | Insertion point for user- | | point | POST, PUT | Insertion point for ordered-yb |
| | | ordered data resources | | | | user data resources |
| start-time | GET | Replay buffer start time for | | start-time | GET | Replay buffer start time for |
| | | event stream resources | | | | event stream resources |
| stop-time | GET | Replay buffer stop time for | | stop-time | GET | Replay buffer stop time for |
| | | event stream resources | | | | event stream resources |
| with-defaults | GET | Control retrieval of default | | with-defaults | GET | Control retrieval of default |
| | | values | | | | values |
+-------------------+-------------+---------------------------------+ +-------------------+-------------+---------------------------------+
RESTCONF Query Parameters RESTCONF Query Parameters
skipping to change at page 46, line 34 skipping to change at page 46, line 34
If more than one instance is present, then a "400 Bad Request" If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server. status-line MUST be returned by the server.
If the "fields" query parameter URI is listed in the "capability" If the "fields" query parameter URI is listed in the "capability"
leaf-list in Section 9.3, then the server supports the "fields" leaf-list in Section 9.3, then the server supports the "fields"
parameter. parameter.
4.8.4. The "insert" Query Parameter 4.8.4. The "insert" Query Parameter
The "insert" parameter is used to specify how a resource should be The "insert" parameter is used to specify how a resource should be
inserted within a user-ordered list. inserted within a ordered-by user list.
The allowed values are: The allowed values are:
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
| Value | Description | | Value | Description |
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
| first | Insert the new data as the new first entry. | | first | Insert the new data as the new first entry. |
| last | Insert the new data as the new last entry. | | last | Insert the new data as the new last entry. |
| before | Insert the new data before the insertion point, as | | before | Insert the new data before the insertion point, as |
| | specified by the value of the "point" parameter. | | | specified by the value of the "point" parameter. |
| after | Insert the new data after the insertion point, as | | after | Insert the new data after the insertion point, as |
| | specified by the value of the "point" parameter. | | | specified by the value of the "point" parameter. |
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
The default value is "last". The default value is "last".
This parameter is only supported for the POST and PUT methods. It is This parameter is only supported for the POST and PUT methods. It is
also only supported if the target resource is a data resource, and also only supported if the target resource is a data resource, and
that data represents a YANG list or leaf-list that is ordered by the that data represents a YANG list or leaf-list that is ordered-by
user. user.
More than one "insert" query parameter MUST NOT appear in a request. More than one "insert" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request" If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server. status-line MUST be returned by the server.
If the values "before" or "after" are used, then a "point" query If the values "before" or "after" are used, then a "point" query
parameter for the insertion parameter MUST also be present, or a "400 parameter for the insertion parameter MUST also be present, or a "400
Bad Request" status-line is returned. Bad Request" status-line is returned.
The "insert" query parameter MUST be supported by the server. The "insert" query parameter MUST be supported by the server.
4.8.5. The "point" Query Parameter 4.8.5. The "point" Query Parameter
The "point" parameter is used to specify the insertion point for a The "point" parameter is used to specify the insertion point for a
data resource that is being created or moved within a user ordered data resource that is being created or moved within an ordered-by
list or leaf-list. user list or leaf-list.
The value of the "point" parameter is a string that identifies the The value of the "point" parameter is a string that identifies the
path to the insertion point object. The format is the same as a path to the insertion point object. The format is the same as a
target resource URI string. target resource URI string.
This parameter is only supported for the POST and PUT methods. It is This parameter is only supported for the POST and PUT methods. It is
also only supported if the target resource is a data resource, and also only supported if the target resource is a data resource, and
that data represents a YANG list or leaf-list that is ordered by the that data represents a YANG list or leaf-list that is ordered-by
user. user.
If the "insert" query parameter is not present, or has a value other If the "insert" query parameter is not present, or has a value other
than "before" or "after", then a "400 Bad Request" status-line is than "before" or "after", then a "400 Bad Request" status-line is
returned. returned.
More than one "point" query parameter MUST NOT appear in a request. More than one "point" query parameter MUST NOT appear in a request.
If more than one instance is present, then a "400 Bad Request" If more than one instance is present, then a "400 Bad Request"
status-line MUST be returned by the server. status-line MUST be returned by the server.
skipping to change at page 66, line 36 skipping to change at page 66, line 36
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from draft-ietf-netconf-restconf-10.txt // Note: extracted from draft-ietf-netconf-restconf-11.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2016-03-16 { revision 2016-03-16 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
skipping to change at page 70, line 17 skipping to change at page 70, line 17
container restconf { container restconf {
description description
"Conceptual container representing the "Conceptual container representing the
application/yang.api resource type."; application/yang.api resource type.";
container data { container data {
description description
"Container representing the application/yang.datastore "Container representing the application/yang.datastore
resource type. Represents the conceptual root of all resource type. Represents the conceptual root of all
operational data and configuration data supported by state data and configuration data supported by
the server. The child nodes of this container can be the server. The child nodes of this container can be
any data resource (application/yang.data), which are any data resource (application/yang.data), which are
defined as top-level data nodes from the YANG modules defined as top-level data nodes from the YANG modules
advertised by the server in the ietf-restconf-monitoring advertised by the server in the ietf-restconf-monitoring
module."; module.";
} }
container operations { container operations {
description description
"Container for all operation resources "Container for all operation resources
skipping to change at page 75, line 19 skipping to change at page 75, line 19
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from draft-ietf-netconf-restconf-10.txt // Note: extracted from draft-ietf-netconf-restconf-11.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2016-03-16 { revision 2016-03-16 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
skipping to change at page 82, line 37 skipping to change at page 82, line 37
and conclusions or recommendations expressed in this material are and conclusions or recommendations expressed in this material are
those of the author(s) and do not necessarily reflect the views of those of the author(s) and do not necessarily reflect the views of
The Space & Terrestrial Communications Directorate (S&TCD). The Space & Terrestrial Communications Directorate (S&TCD).
14. References 14. References
14.1. Normative References 14.1. Normative References
[I-D.ietf-netconf-yang-library] [I-D.ietf-netconf-yang-library]
Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
Library", draft-ietf-netconf-yang-library-01 (work in Library", draft-ietf-netconf-yang-library-05 (work in
progress), July 2015. progress), April 2016.
[I-D.ietf-netmod-rfc6020bis] [I-D.ietf-netmod-rfc6020bis]
Bjorklund, M., "The YANG 1.1 Data Modeling Language", Bjorklund, M., "The YANG 1.1 Data Modeling Language",
draft-ietf-netmod-rfc6020bis-11 (work in progress), draft-ietf-netmod-rfc6020bis-11 (work in progress),
February 2016. February 2016.
[I-D.ietf-netmod-yang-json] [I-D.ietf-netmod-yang-json]
Lhotka, L., "JSON Encoding of Data Modeled with YANG", Lhotka, L., "JSON Encoding of Data Modeled with YANG",
draft-ietf-netmod-yang-json-06 (work in progress), October draft-ietf-netmod-yang-json-06 (work in progress), October
2015. 2015.
skipping to change at page 85, line 45 skipping to change at page 85, line 45
Fielding, R., "Architectural Styles and the Design of Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000. Network-based Software Architectures", 2000.
Appendix A. Change Log Appendix A. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
The RESTCONF issue tracker can be found here: https://github.com/ The RESTCONF issue tracker can be found here: https://github.com/
netconf-wg/restconf/issues netconf-wg/restconf/issues
A.1. v09 - v10 A.1. v10 - v11
o change term 'operational data' to 'state data'
o clarify :startup behavior
o clarify X.509 security text
o change '403 Forbidden' to '401 Unauthorized' for GET error
o clarify MUST have one "restconf" link relation
o clarify that NV-storage is not mandatory
o clarify how "Last-Modified" and "ETag" header info can be used by
a client
o clarify meaning of mandatory parameter
o fix module name in action examples
o clarify operation resource request needs to be known to parse the
output
o clarify ordered-by user terminology
o fixed JSON example in D.1.1
A.2. 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
o fixed forward references to URI template (w/reference at first o fixed forward references to URI template (w/reference at first
use) use)
o added reference to HTML5 o added reference to HTML5
o made error terminology more consistent o made error terminology more consistent
skipping to change at page 87, line 45 skipping to change at page 88, line 23
o added mandatory /restconf/yang-library-version leaf to advertise o added mandatory /restconf/yang-library-version leaf to advertise
revision-date of the YANG library implemented by the server revision-date of the YANG library implemented by the server
o clarified URI encoding rules for leaf-list o clarified URI encoding rules for leaf-list
o clarified sec. 2.2 wrt/ certificates and TLS o clarified sec. 2.2 wrt/ certificates and TLS
o added update procedure for entity tag and timestamp o added update procedure for entity tag and timestamp
A.2. v08 - v09 A.3. 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.3. v07 - v08 A.4. v07 - v08
o add support for YANG 1.1 action statement o add support for YANG 1.1 action statement
o changed mandatory encoding from XML to XML or JSON o changed mandatory encoding from XML to XML or JSON
o fix syntax in fields parameter definition o fix syntax in fields parameter definition
o add meta-data encoding examples for XML and JSON o add meta-data encoding examples for XML and JSON
o remove RFC 2396 references and update with 3986 o remove RFC 2396 references and update with 3986
skipping to change at page 88, line 23 skipping to change at page 89, line 4
o add support for YANG 1.1 action statement o add support for YANG 1.1 action statement
o changed mandatory encoding from XML to XML or JSON o changed mandatory encoding from XML to XML or JSON
o fix syntax in fields parameter definition o fix syntax in fields parameter definition
o add meta-data encoding examples for XML and JSON o add meta-data encoding examples for XML and JSON
o remove RFC 2396 references and update with 3986 o remove RFC 2396 references and update with 3986
o change encoding of a key so quoted string are not used, since they o change encoding of a key so quoted string are not used, since they
are already percent-encoded. A zero-length string is not encoded are already percent-encoded. A zero-length string is not encoded
(/list=foo,,baz) (/list=foo,,baz)
o Add example of percent-encoded key value o Add example of percent-encoded key value
A.4. v06 - v07 A.5. 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.5. v05 - v06 A.6. v05 - v06
o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug)
A.6. v04 - v05 A.7. 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
o removed text about not immediate persistence of edits o removed text about not immediate persistence of edits
o removed RESTCONF-specific data-resource-identifier typedef and its o removed RESTCONF-specific data-resource-identifier typedef and its
skipping to change at page 89, line 37 skipping to change at page 90, line 17
o renamed stream/encoding/events to stream/access/location o renamed stream/encoding/events to stream/access/location
o changed XPath from informative to normative reference o changed XPath from informative to normative reference
o changed rest-dissertation from normative to informative reference o changed rest-dissertation from normative to informative reference
o changed example-jukebox playlist 'id' from a data-resource- o changed example-jukebox playlist 'id' from a data-resource-
identifier to a leafref pointing at the song name identifier to a leafref pointing at the song name
A.7. v03 - v04 A.8. 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 90, line 24 skipping to change at page 91, line 5
o changed lock-denied error example o changed lock-denied error example
o added with-defaults query parameter example o added with-defaults query parameter example
o added term "RESTCONF Capability" o added term "RESTCONF Capability"
o changed NETCONF Capability URI registry usage to new RESTCONF o changed NETCONF Capability URI registry usage to new RESTCONF
Capability URI Registry usage Capability URI Registry usage
A.8. v02 - v03 A.9. v02 - v03
o added collection resource o added collection resource
o added "page" query parameter capability o added "page" query parameter capability
o added "limit" and "offset" query parameters, which are available o added "limit" and "offset" query parameters, which are available
if the "page" capability is supported if the "page" capability is supported
o added "stream list" term o added "stream list" term
skipping to change at page 90, line 46 skipping to change at page 91, line 27
o added "encoding" list within the "stream" list to allow different o added "encoding" list within the "stream" list to allow different
<events> URLs for XML and JSON encoding. <events> URLs for XML and JSON encoding.
o made XML MUST implement and JSON MAY implement for servers o made XML MUST implement and JSON MAY implement for servers
o re-add JSON notification examples (previously removed) o re-add JSON notification examples (previously removed)
o updated JSON references o updated JSON references
A.9. v01 - v02 A.10. 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)
o added 'capabilities' container to new YANG module (ietf-restconf- o added 'capabilities' container to new YANG module (ietf-restconf-
monitoring) monitoring)
o moved 'modules' container to new YANG module (ietf-yang-library) o moved 'modules' container to new YANG module (ietf-yang-library)
o added new leaf 'module-set-id' (ietf-yang-library) o added new leaf 'module-set-id' (ietf-yang-library)
skipping to change at page 91, line 35 skipping to change at page 92, line 16
information is no longer in this resource information is no longer in this resource
o closed issue #1 'select parameter' since no objections to the o closed issue #1 'select parameter' since no objections to the
proposed syntax proposed syntax
o closed "encoding of list keys" issue since no objection to new o closed "encoding of list keys" issue since no objection to new
encoding of list keys in a target resource URI. encoding of list keys in a target resource URI.
o moved open issues list to the issue tracker on github o moved open issues list to the issue tracker on github
A.10. v00 - v01 A.11. 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 92, line 26 skipping to change at page 93, line 4
o closed open issue '_self links for HATEOAS support'. It was o closed open issue '_self links for HATEOAS support'. It was
decided that they are redundant because they can be derived from decided that they are redundant because they can be derived from
the YANG module for the specific data. the YANG module for the specific data.
o added explanatory text for the 'select' parameter. o added explanatory text for the 'select' parameter.
o added RESTCONF Path Resolution section for discovering the root of o added RESTCONF Path Resolution section for discovering the root of
the RESTCONF API using the /.well-known/host-meta. the RESTCONF API using the /.well-known/host-meta.
o added an "error" media type to for structured error messages o added an "error" media type to for structured error messages
o added Secure Transport section requiring TLS o added Secure Transport section requiring TLS
o added Security Considerations section o added Security Considerations section
o removed all references to "REST-like" o removed all references to "REST-like"
A.11. bierman:restconf-04 to ietf:restconf-00 A.12. 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 99, line 26 skipping to change at page 99, line 49
The server might respond as follows: The server might respond as follows:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang.api+json Content-Type: application/yang.api+json
{ {
"ietf-restconf:restconf": { "ietf-restconf:restconf": {
"data" : {}, "data" : {},
"operations" : {} "operations" : {},
"yang-library-version" : "2016-04-09"
} }
} }
To request that the response content to be encoded in XML, the To request that the response content to be encoded in XML, the
"Accept" header can be used, as in this example request: "Accept" header can be used, as in this example request:
GET /restconf HTTP/1.1 GET /restconf HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.api+xml Accept: application/yang.api+xml
skipping to change at page 99, line 50 skipping to change at page 100, line 28
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Pragma: no-cache
Content-Type: application/yang.api+xml Content-Type: application/yang.api+xml
<restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<data/> <data/>
<operations/> <operations/>
<yang-library-version>2016-02-01</yang-library-version> <yang-library-version>2016-04-09</yang-library-version>
</restconf> </restconf>
D.1.2. Retrieve The Server Module Information D.1.2. Retrieve The Server Module Information
In this example the client is retrieving the modules 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 HTTP/1.1 GET /restconf/data/ietf-yang-library:modules HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json Accept: application/yang.data+json
skipping to change at page 100, line 38 skipping to change at page 101, line 15
{ {
"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" ],
"conformance-type" : "implement" "conformance-type" : "implement"
}, },
{ {
"name" : "ietf-yang-library", "name" : "ietf-yang-library",
"revision" : "2016-02-01", "revision" : "2016-04-09",
"schema" : "https://example.com/modules/ietf-yang- "schema" : "https://example.com/modules/ietf-yang-
library/2016-02-01", library/2016-04-09",
"namespace" : "namespace" :
"urn:ietf:params:xml:ns:yang:ietf-yang-library", "urn:ietf:params:xml:ns:yang:ietf-yang-library",
"conformance-type" : "implement" "conformance-type" : "implement"
}, },
{ {
"name" : "foo-types", "name" : "foo-types",
"revision" : "2012-01-05", "revision" : "2012-01-05",
"schema" : "schema" :
"https://example.com/modules/foo-types/2012-01-05", "https://example.com/modules/foo-types/2012-01-05",
"namespace" : "http://example.com/ns/foo-types", "namespace" : "http://example.com/ns/foo-types",
skipping to change at page 111, line 32 skipping to change at page 112, line 5
{ {
"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" : "2015-06-19" "revision" : "2015-06-19"
}, },
{ {
"name" : "ietf-yang-library", "name" : "ietf-yang-library",
"revision" : "2016-02-01" "revision" : "2016-04-09"
}, },
{ {
"name" : "ietf-yang-types", "name" : "ietf-yang-types",
"revision" : "2013-07-15" "revision" : "2013-07-15"
} }
] ]
} }
} }
D.3.4. "insert" Parameter D.3.4. "insert" Parameter
In this example, a new first entry in the "Foo-One" playlist is being In this example, a new first song entry in the "Foo-One" playlist is
created. being created.
Request from client: Request from client:
POST /restconf/data/example-jukebox:jukebox/ POST /restconf/data/example-jukebox:jukebox/
playlist=Foo-One?insert=first HTTP/1.1 playlist=Foo-One?insert=first HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang.data+json Content-Type: application/yang.data+json
{ {
"example-jukebox:song" : { "example-jukebox:song" : {
 End of changes. 75 change blocks. 
127 lines changed or deleted 176 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/