draft-ietf-netconf-restconf-12.txt   draft-ietf-netconf-restconf-13.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track M. Bjorklund Intended status: Standards Track M. Bjorklund
Expires: October 14, 2016 Tail-f Systems Expires: October 29, 2016 Tail-f Systems
K. Watsen K. Watsen
Juniper Networks Juniper Networks
April 12, 2016 April 27, 2016
RESTCONF Protocol RESTCONF Protocol
draft-ietf-netconf-restconf-12 draft-ietf-netconf-restconf-13
Abstract Abstract
This document describes an HTTP-based protocol that provides a This document describes an HTTP-based protocol that provides a
programmatic interface for accessing data defined in YANG, using the programmatic interface for accessing data defined in YANG, using the
datastores defined in NETCONF. datastores defined in NETCONF.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 14, 2016. This Internet-Draft will expire on October 29, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 48 skipping to change at page 2, line 48
3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 17 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 17
3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18
3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 18 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 18
3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19
3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 19 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 19
3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20
3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21
3.5.1. Encoding Data Resource Identifiers in the Request URI 22 3.5.1. Encoding Data Resource Identifiers in the Request URI 22
3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 25 3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 25
3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 25 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 25
3.6.1. Encoding Operation Resource Input Parameters . . . . 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 . . . . . . . . . . . . . . . . . . . . 34 3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 34
4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 34 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 "filter" Query Parameter . . . . . . . . . . . . 46 4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 46
4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 47 4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 47
4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 48 4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 48
4.8.7. The "start-time" Query Parameter . . . . . . . . . . 48 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 49
4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 49 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 49
4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 50 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 50
5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 51 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 51 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 51
5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 52 5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 52
5.3. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 53 5.3. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 53
5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 53 5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 53
5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 54 5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 54
5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 54 5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 55
5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 54 5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 55
6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 55 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 55
6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 55 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 55
6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 55 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 56
6.3. Subscribing to Receive Notifications . . . . . . . . . . 57 6.3. Subscribing to Receive Notifications . . . . . . . . . . 57
6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 58 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 58
6.4. Receiving Event Notifications . . . . . . . . . . . . . . 58 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 59
7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 60 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 61
7.1. Error Response Message . . . . . . . . . . . . . . . . . 62 7.1. Error Response Message . . . . . . . . . . . . . . . . . 62
8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 64 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 64
9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 70 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 70
9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 70 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 71
9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 71 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 71
9.1.2. The "defaults" Protocol Capability URI . . . . . . . 71 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 72
9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 72 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 73
9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 72 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 73
10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 76 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 77
10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 76 10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 77
10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 77 10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 77
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77
11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 77 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 77
11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 77 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 78
11.3. application/yang Media Sub Types . . . . . . . . . . . . 78 11.3. application/yang Media Sub Types . . . . . . . . . . . . 78
11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 79 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 79
12. Security Considerations . . . . . . . . . . . . . . . . . . . 79 12. Security Considerations . . . . . . . . . . . . . . . . . . . 80
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 80 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 81
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 81 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 81
14.1. Normative References . . . . . . . . . . . . . . . . . . 81 14.1. Normative References . . . . . . . . . . . . . . . . . . 81
14.2. Informative References . . . . . . . . . . . . . . . . . 83 14.2. Informative References . . . . . . . . . . . . . . . . . 84
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 84 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 84
A.1. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 84 A.1. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 84
A.2. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 84 A.2. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 84
A.3. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 85 A.3. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 85
A.4. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 87 A.4. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 86
A.5. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 87 A.5. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 88
A.6. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.6. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 88
A.7. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.7. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 88
A.8. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 88 A.8. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 89
A.9. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 89 A.9. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 89
A.10. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 90 A.10. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 90
A.11. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 90 A.11. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 90
A.12. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 91 A.12. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 91
A.13. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 92 A.13. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 92
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 92 A.14. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 92
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
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 98 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 99
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 98 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 99
D.1.2. Retrieve The Server Module Information . . . . . . . 99 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 99
D.1.3. Retrieve The Server Capability Information . . . . . 101 D.1.2. Retrieve The Server Module Information . . . . . . . 100
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 102 D.1.3. Retrieve The Server Capability Information . . . . . 102
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 102 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 103
D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 103 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 103
D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 103 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 104
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 104 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 104
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 104 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 105
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 107 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 105
D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 110 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 108
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 111 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 111
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 111 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 112
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 112 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 113
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 113 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 113
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 113 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 114
D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 113 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 114
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 115 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 114
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, state data, data-model specific access the configuration data, state data, data-model specific
protocol operations, and event notifications within a networking protocol operations, and event notifications within a networking
device, in a modular and extensible manner. device, in a modular and extensible manner.
This document defines an HTTP [RFC7230] based protocol called This document defines an HTTP [RFC7230] based protocol called
RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or
skipping to change at page 19, line 20 skipping to change at page 19, line 20
modules advertised by the server MUST be available as child nodes of modules advertised by the server MUST be available as child nodes of
this resource. this resource.
Operation resources are defined in Section 3.6. Operation resources are defined in Section 3.6.
3.3.3. {+restconf}/yang-library-version 3.3.3. {+restconf}/yang-library-version
This mandatory leaf identifies the revision date of the This mandatory leaf identifies the revision date of the
"ietf-yang-library" YANG module that is implemented by this server. "ietf-yang-library" YANG module that is implemented by this server.
[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.]
Example: Example:
GET /restconf/yang-library-version HTTP/1.1 GET /restconf/yang-library-version HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+xml Accept: application/yang.data+xml
The server might respond (response wrapped for display purposes): The server might respond (response wrapped for display purposes):
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
skipping to change at page 33, line 5 skipping to change at page 33, line 19
present in the associated "module" list entry, defined in present in the associated "module" list entry, defined in
[I-D.ietf-netconf-yang-library]. [I-D.ietf-netconf-yang-library].
To retrieve a YANG module, a client first needs to get the URL for To retrieve a YANG module, a client first needs to get the URL for
retrieving the schema, which is stored in the "schema" leaf. Note retrieving the schema, which is stored in the "schema" leaf. Note
that there is no required structure for this URL. The URL value that there is no required structure for this URL. The URL value
shown below is just an example. shown below is just an example.
The client might send the following GET request message: The client might send the following GET request message:
GET /restconf/data/ietf-yang-library:modules/module= GET /restconf/data/ietf-yang-library:modules-state/module=
example-jukebox,2015-04-04/schema HTTP/1.1 example-jukebox,2015-04-04/schema HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json Accept: application/yang.data+json
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Thu, 11 Feb 2016 11:10:30 GMT Date: Thu, 11 Feb 2016 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang.data+json Content-Type: application/yang.data+json
skipping to change at page 42, line 12 skipping to change at page 42, line 22
then the message body MUST be either application/yang.data+xml or then the message body MUST be either application/yang.data+xml or
application/yang.data+json. application/yang.data+json.
Plain patch can be used to create or update, but not delete, a child Plain patch can be used to create or update, but not delete, a child
resource within the target resource. Please see resource within the target resource. Please see
[I-D.ietf-netconf-yang-patch] for an alternate media-type supporting [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting
more granular control. The YANG Patch Media Type allows multiple more granular control. The YANG Patch Media Type allows multiple
sub-operations (e.g., merge, delete) within a single PATCH operation. sub-operations (e.g., merge, delete) within a single PATCH operation.
If the target resource represents a YANG leaf-list, then the PATCH If the target resource represents a YANG leaf-list, then the PATCH
method MUST not change the value of the leaf-list instance. method MUST NOT change the value of the leaf-list instance.
If the target resource represents a YANG list instance, then the If the target resource represents a YANG list instance, then the
PATCH method MUST NOT change any key leaf values in the message-body PATCH method MUST NOT change any key leaf values in the message-body
representation. representation.
Example: Example:
To replace just the "year" field in the "album" resource (instead of To replace just the "year" field in the "album" resource (instead of
replacing the entire resource with the PUT method), the client might replacing the entire resource with the PUT method), the client might
send a plain patch as follows. Note that the request-line is wrapped send a plain patch as follows. Note that the request-line is wrapped
skipping to change at page 65, line 31 skipping to change at page 66, line 4
Copyright (c) 2016 IETF Trust and the persons identified as Copyright (c) 2016 IETF Trust and the persons identified as
authors of the code. All rights reserved. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
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-12.txt // Note: extracted from draft-ietf-netconf-restconf-13.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 74, line 17 skipping to change at page 74, line 38
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-12.txt // Note: extracted from draft-ietf-netconf-restconf-13.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2016-03-16 { revision 2016-03-16 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
skipping to change at page 80, line 4 skipping to change at page 80, line 23
: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
12. Security Considerations 12. Security Considerations
This section provides security considerations for the resources This section provides security considerations for the resources
defined by the RESTCONF protocol. Security considerations for HTTPS defined by the RESTCONF protocol. Security considerations for HTTPS
are defined in [RFC2818]. RESTCONF does not specify which YANG are defined in [RFC7230]. RESTCONF does not specify which YANG
modules a server needs to support. Security considerations for the modules a server needs to support. Security considerations for the
YANG-defined content manipulated by RESTCONF can be found in the YANG-defined content manipulated by RESTCONF can be found in the
documents defining those YANG modules. documents defining those YANG modules.
This document does not require use of a specific client This document does not require use of a specific client
authentication mechanism or authorization model, but it does require authentication mechanism or authorization model, but it does require
that a client authentication mechanism and authorization model is that a client authentication mechanism and authorization model is
used whenever a client accesses a protected resource. Client used whenever a client accesses a protected resource. Client
authentication MUST be implemented using client certificates or MUST authentication MUST be implemented using client certificates or MUST
be implemented using an HTTP authentication scheme. Client be implemented using an HTTP authentication scheme. Client
skipping to change at page 80, line 43 skipping to change at page 81, line 15
the form of configuration information, which is all the more reason the form of configuration information, which is all the more reason
to ensure the security of the connection. to ensure the security of the connection.
13. Acknowledgements 13. Acknowledgements
The authors would like to thank the following people for their The authors would like to thank the following people for their
contributions to this document: Ladislav Lhotka, Juergen contributions to this document: Ladislav Lhotka, Juergen
Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford.
The authors would like to thank the following people for their The authors would like to thank the following people for their
excellent review comments and contributions to this document: Qin Wu, excellent review comments and contributions to this document: Mehmet
Joe Clarke, Bert Wijnen, Ladislav Lhotka, Rodney Cummings, Frank Ersue, Mahesh Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav
Xialiang, Tom Petch, Robert Sparks, Balint Uveges, Randy Presuhn, and Lhotka, Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks,
Sue Hares. Balint Uveges, Randy Presuhn, and Sue Hares.
Contributions to this material by Andy Bierman are based upon work Contributions to this material by Andy Bierman are based upon work
supported by the The Space & Terrestrial Communications Directorate supported by the The Space & Terrestrial Communications Directorate
(S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings
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-05 (work in Library", draft-ietf-netconf-yang-library-06 (work in
progress), April 2016. 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
skipping to change at page 81, line 38 skipping to change at page 82, line 12
draft-ietf-netmod-yang-metadata-02 (work in progress), draft-ietf-netmod-yang-metadata-02 (work in progress),
September 2015. September 2015.
[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.
[RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005. 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 84, line 16 skipping to change at page 84, line 37
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. v11 - v12 A.1. v12 - v13
o fix YANG library module examples (now called module-state)
o fix MUST not term (should be MUST NOT)
o removed RFC 2818 reference (changed citation to RFC 7230)
A.2. v11 - v12
o clarify query parameter requirements o clarify query parameter requirements
o move filter query section to match table order in sec. 4.8 o move filter query section to match table order in sec. 4.8
o clarify that depth default is entire subtree for datastore o clarify that depth default is entire subtree for datastore
resource resource
o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml
o made implementation of timestamps optional since ETags are o made implementation of timestamps optional since ETags are
mandatory mandatory
o removed confusing text about data resource definition revision o removed confusing text about data resource definition revision
date date
skipping to change at page 84, line 42 skipping to change at page 85, line 24
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.2. v10 - v11 A.3. 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 85, line 20 skipping to change at page 86, line 5
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.3. v09 - v10 A.4. 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 87, line 21 skipping to change at page 88, line 5
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.4. v08 - v09 A.5. 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.5. v07 - v08 A.6. 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 4 skipping to change at page 88, line 33
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.6. v06 - v07 A.7. 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.7. v05 - v06 A.8. v05 - v06
o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug)
A.8. v04 - v05 A.9. 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 89, line 17 skipping to change at page 90, line 5
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.9. v03 - v04 A.10. 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 5 skipping to change at page 90, line 40
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.10. v02 - v03 A.11. 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 17 skipping to change at page 91, line 4
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.11. v01 - v02 A.12. 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 91, line 16 skipping to change at page 92, line 5
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.12. v00 - v01 A.13. 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 4 skipping to change at page 92, line 42
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.13. bierman:restconf-04 to ietf:restconf-00 A.14. 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 98, line 41 skipping to change at page 99, line 34
The client may start by retrieving the top-level API resource, using The client may start by retrieving the top-level API resource, using
the entry point URI "{+restconf}". the entry point URI "{+restconf}".
GET /restconf HTTP/1.1 GET /restconf HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.api+json Accept: application/yang.api+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 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" "yang-library-version" : "2016-04-09"
skipping to change at page 99, line 18 skipping to change at page 100, line 15
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
The server will return the same response either way, which might be The server will return the same response either way, which might be
as follows : as follows :
[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 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-04-09</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-state HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json Accept: application/yang.data+json
The server might respond as follows (some strings wrapped for display The server might respond as follows (some strings wrapped for display
purposes): purposes):
[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 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Pragma: no-cache
Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT
Content-Type: application/yang.data+json Content-Type: application/yang.data+json
{ {
"ietf-yang-library:modules": { "ietf-yang-library:modules-state": {
"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" ],
"conformance-type" : "implement" "conformance-type" : "implement"
}, },
{ {
skipping to change at page 110, line 25 skipping to change at page 111, line 26
} }
} }
} }
D.3.3. "fields" Parameter D.3.3. "fields" Parameter
In this example the client is retrieving the API resource, but In this example the client is retrieving the API resource, but
retrieving only the "name" and "revision" nodes from each module, in retrieving only the "name" and "revision" nodes from each module, in
JSON format: JSON format:
GET /restconf/data?fields=ietf-yang-library:modules/ 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
to the date in the published ietf-restconf-monitoring YANG module,
and remove this note.]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server Server: example-server
Content-Type: application/yang.data+json Content-Type: application/yang.data+json
{ {
"ietf-yang-library:modules": { "ietf-yang-library:modules-state": {
"module-set-id": "cb4c422111a779e1eed55bffc8d6b46a3a0999e2",
"module": [ "module": [
{ {
"name" : "example-jukebox", "name" : "example-jukebox",
"revision" : "2015-06-04" "revision" : "2015-06-04"
}, },
{ {
"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" : "2016-03-16"
}, },
{ {
"name" : "ietf-yang-library", "name" : "ietf-yang-library",
"revision" : "2016-04-09" "revision" : "2016-04-09"
}, },
{ {
"name" : "ietf-yang-types", "name" : "ietf-yang-types",
"revision" : "2013-07-15" "revision" : "2013-07-15"
} }
 End of changes. 55 change blocks. 
96 lines changed or deleted 129 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/