draft-ietf-netconf-restconf-02.txt   draft-ietf-netconf-restconf-03.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track M. Bjorklund Intended status: Standards Track M. Bjorklund
Expires: April 11, 2015 Tail-f Systems Expires: April 28, 2015 Tail-f Systems
K. Watsen K. Watsen
Juniper Networks Juniper Networks
October 8, 2014 October 25, 2014
RESTCONF Protocol RESTCONF Protocol
draft-ietf-netconf-restconf-02 draft-ietf-netconf-restconf-03
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 April 11, 2015. This Internet-Draft will expire on April 28, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 16 skipping to change at page 2, line 16
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Secure Transport . . . . . . . . . . . . . . . . . . . . 5 1.1. Secure Transport . . . . . . . . . . . . . . . . . . . . 5
1.2. Simple Subset of NETCONF Functionality . . . . . . . . . 5 1.2. Simple Subset of NETCONF Functionality . . . . . . . . . 5
1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 6 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 6
1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7
1.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 7 1.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 7
1.4.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 8 1.4.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 8 1.4.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 9 1.4.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.5. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10 1.4.5. URI Template . . . . . . . . . . . . . . . . . . . . 11
1.4.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 11
2. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.1. RESTCONF Resource Types . . . . . . . . . . . . . . . . . 11 2.1. RESTCONF Resource Types . . . . . . . . . . . . . . . . . 12
2.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 12 2.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 12
2.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 12 2.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 13
2.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 13 2.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 13
2.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 14 2.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 14
2.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 14 2.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 14
2.4.1. Edit Collision Detection . . . . . . . . . . . . . . 14 2.4.1. Edit Collision Detection . . . . . . . . . . . . . . 15
2.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 15 2.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 15
2.5.1. Encoding YANG Instance Identifiers in the Request URI 16 2.5.1. Encoding YANG Instance Identifiers in the Request URI 16
2.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 18 2.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 18
2.6. Operation Resource . . . . . . . . . . . . . . . . . . . 19 2.6. Collection Resource . . . . . . . . . . . . . . . . . . . 19
2.6.1. Encoding Operation Input Parameters . . . . . . . . . 19 2.7. Operation Resource . . . . . . . . . . . . . . . . . . . 19
2.6.2. Encoding Operation Output Parameters . . . . . . . . 20 2.7.1. Encoding Operation Input Parameters . . . . . . . . . 20
2.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 21 2.7.2. Encoding Operation Output Parameters . . . . . . . . 21
2.8. Stream Resource . . . . . . . . . . . . . . . . . . . . . 22 2.8. Schema Resource . . . . . . . . . . . . . . . . . . . . . 22
2.9. Errors Resource . . . . . . . . . . . . . . . . . . . . . 23 2.9. Stream Resource . . . . . . . . . . . . . . . . . . . . . 23
2.10. Errors Resource . . . . . . . . . . . . . . . . . . . . . 23
3. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 23 3. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 24 3.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 24 3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 3.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 25 3.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 26 3.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 26
3.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 26 3.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 27
3.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 3.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 28 3.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 30 3.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 30 3.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 31
3.8.1. Query Parameter URIs . . . . . . . . . . . . . . . . 31 3.8.1. Query Parameter URIs . . . . . . . . . . . . . . . . 31
3.8.2. The "content" Query Parameter . . . . . . . . . . . . 32 3.8.2. The "content" Query Parameter . . . . . . . . . . . . 32
3.8.3. The "depth" Query Parameter . . . . . . . . . . . . . 32 3.8.3. The "depth" Query Parameter . . . . . . . . . . . . . 32
3.8.4. The "select" Query Parameter . . . . . . . . . . . . 33 3.8.4. The "select" Query Parameter . . . . . . . . . . . . 33
3.8.5. The "insert" Query Parameter . . . . . . . . . . . . 34 3.8.5. The "insert" Query Parameter . . . . . . . . . . . . 34
3.8.6. The "point" Query Parameter . . . . . . . . . . . . . 34 3.8.6. The "point" Query Parameter . . . . . . . . . . . . . 34
3.8.7. The "filter" Query Parameter . . . . . . . . . . . . 35 3.8.7. The "limit" Query Parameter . . . . . . . . . . . . . 35
3.8.8. The "start-time" Query Parameter . . . . . . . . . . 36 3.8.8. The "offset" Query Parameter . . . . . . . . . . . . 35
3.8.9. The "stop-time" Query Parameter . . . . . . . . . . . 36 3.8.9. The "filter" Query Parameter . . . . . . . . . . . . 36
4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 37 3.8.10. The "start-time" Query Parameter . . . . . . . . . . 36
4.1. Request URI Structure . . . . . . . . . . . . . . . . . . 37 3.8.11. The "stop-time" Query Parameter . . . . . . . . . . . 37
4.2. RESTCONF Path Resolution . . . . . . . . . . . . . . . . 38 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.3. Message Headers . . . . . . . . . . . . . . . . . . . . . 39 4.1. Request URI Structure . . . . . . . . . . . . . . . . . . 38
4.4. Message Encoding . . . . . . . . . . . . . . . . . . . . 40 4.2. RESTCONF Path Resolution . . . . . . . . . . . . . . . . 39
4.3. Message Headers . . . . . . . . . . . . . . . . . . . . . 40
4.4. Message Encoding . . . . . . . . . . . . . . . . . . . . 41
4.5. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 41 4.5. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 41
4.6. Return Status . . . . . . . . . . . . . . . . . . . . . . 41 4.6. Return Status . . . . . . . . . . . . . . . . . . . . . . 42
4.7. Message Caching . . . . . . . . . . . . . . . . . . . . . 41 4.7. Message Caching . . . . . . . . . . . . . . . . . . . . . 42
5. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 42 5. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 42
5.1. Server Support . . . . . . . . . . . . . . . . . . . . . 42 5.1. Server Support . . . . . . . . . . . . . . . . . . . . . 42
5.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 42 5.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 43
5.3. Subscribing to Receive Notifications . . . . . . . . . . 43 5.3. Subscribing to Receive Notifications . . . . . . . . . . 45
5.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 44 5.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 46
5.4. Receiving Event Notifications . . . . . . . . . . . . . . 45 5.4. Receiving Event Notifications . . . . . . . . . . . . . . 46
6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 46 6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 48
6.1. Error Response Message . . . . . . . . . . . . . . . . . 48 6.1. Error Response Message . . . . . . . . . . . . . . . . . 49
7. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 50 7. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 51
8. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 56 8. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 57
8.1. restconf-state/capabilities . . . . . . . . . . . . . . . 56 8.1. restconf-state/capabilities . . . . . . . . . . . . . . . 58
8.2. restconf-state/streams . . . . . . . . . . . . . . . . . 57 8.2. restconf-state/streams . . . . . . . . . . . . . . . . . 58
8.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 57 8.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 58
9. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 60 9. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 62
9.1. modules . . . . . . . . . . . . . . . . . . . . . . . . . 61 9.1. modules . . . . . . . . . . . . . . . . . . . . . . . . . 63
9.1.1. modules/module . . . . . . . . . . . . . . . . . . . 61 9.1.1. modules/module . . . . . . . . . . . . . . . . . . . 63
9.2. YANG Library Module . . . . . . . . . . . . . . . . . . . 62 9.2. YANG Library Module . . . . . . . . . . . . . . . . . . . 64
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 66 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 68
10.1. The "restconf" Relation Type . . . . . . . . . . . . . . 66 10.1. The "restconf" Relation Type . . . . . . . . . . . . . . 68
10.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 66 10.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 68
10.3. application/yang Media Sub Types . . . . . . . . . . . . 67 10.3. application/yang Media Sub Types . . . . . . . . . . . . 69
10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . 68 10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . 70
11. Security Considerations . . . . . . . . . . . . . . . . . . . 68 11. Security Considerations . . . . . . . . . . . . . . . . . . . 70
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 69 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 71
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 69 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 71
13.1. Normative References . . . . . . . . . . . . . . . . . . 69 13.1. Normative References . . . . . . . . . . . . . . . . . . 71
13.2. Informative References . . . . . . . . . . . . . . . . . 71 13.2. Informative References . . . . . . . . . . . . . . . . . 73
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 71 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 73
A.1. 01 - 02 . . . . . . . . . . . . . . . . . . . . . . . . . 71 A.1. 02 - 03 . . . . . . . . . . . . . . . . . . . . . . . . . 73
A.2. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 72 A.2. 01 - 02 . . . . . . . . . . . . . . . . . . . . . . . . . 74
A.3. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 73 A.3. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 75
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 73 A.4. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 76
Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 73
C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 74 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 76
Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 79 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 76
D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 80 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 77
D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 80 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 82
D.1.2. Retrieve The Server Module Information . . . . . . . 81 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 82
D.1.3. Retrieve The Server Capability Information . . . . . 82 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 82
D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 83 D.1.2. Retrieve The Server Module Information . . . . . . . 83
D.2.1. Create New Data Resources . . . . . . . . . . . . . . 83 D.1.3. Retrieve The Server Capability Information . . . . . 84
D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 84 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 85
D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 85 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 85
D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 85 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 86
D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 88 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 87
D.3.3. "select" Parameter . . . . . . . . . . . . . . . . . 91 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 87
D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 92 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 90
D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 93 D.3.3. "select" Parameter . . . . . . . . . . . . . . . . . 93
D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 93 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 94
D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 94 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 95
D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 94 D.3.6. "limit" Parameter . . . . . . . . . . . . . . . . . . 95
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 94 D.3.7. "offset" Parameter . . . . . . . . . . . . . . . . . 96
D.3.8. "filter" Parameter . . . . . . . . . . . . . . . . . 97
D.3.9. "start-time" Parameter . . . . . . . . . . . . . . . 98
D.3.10. "stop-time" Parameter . . . . . . . . . . . . . . . . 98
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 98
1. Introduction 1. Introduction
There is a need for standard mechanisms to allow WEB applications to There is a need for standard mechanisms to allow WEB applications to
access the configuration data, operational data, data-model specific access the configuration data, operational data, data-model specific
protocol operations, and notification events within a networking protocol operations, and notification events within a networking
device, in a modular and extensible manner. device, in a modular and extensible manner.
This document describes an HTTP [RFC2616] based protocol called This document describes an HTTP [RFC2616] based protocol called
RESTCONF, for accessing data defined in YANG [RFC6020], using RESTCONF, for accessing data defined in YANG [RFC6020], using
skipping to change at page 4, line 46 skipping to change at page 5, line 5
operations, and notification events. RESTCONF uses HTTP operations operations, and notification events. RESTCONF uses HTTP operations
to provide CRUD operations on a NETCONF datastore containing YANG- to provide CRUD operations on a NETCONF datastore containing YANG-
defined data. Since NETCONF protocol operations are not relevant, defined data. Since NETCONF protocol operations are not relevant,
the user should not need any prior knowledge of NETCONF in order to the user should not need any prior knowledge of NETCONF in order to
use RESTCONF. use RESTCONF.
Configuration data and state data are exposed as resources that can Configuration data and state data are exposed as resources that can
be retrieved with the GET method. Resources representing be retrieved with the GET method. Resources representing
configuration data can be modified with the DELETE, PATCH, POST, and configuration data can be modified with the DELETE, PATCH, POST, and
PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126]
or JSON [JSON]. or JSON [RFC7158].
Data-model specific protocol operations defined with the YANG "rpc" Data-model specific protocol operations defined with the YANG "rpc"
statement can be invoked with the POST method. Data-model specific statement can be invoked with the POST method. Data-model specific
notification events defined with the YANG "notification" statement notification events defined with the YANG "notification" statement
can be accessed. can be accessed.
1.1. Secure Transport 1.1. Secure Transport
RESTCONF relies on TLS [RFC2246] to provide privacy and data RESTCONF relies on TLS [RFC2246] to provide privacy and data
integrity for its HTTP operations. More specifically, RESTCONF integrity for its HTTP operations. More specifically, RESTCONF
skipping to change at page 7, line 14 skipping to change at page 7, line 19
protocol operations and datastore content are predictable, based on protocol operations and datastore content are predictable, based on
the YANG module definitions. the YANG module definitions.
Operational experience with CLI and SNMP indicates that operators Operational experience with CLI and SNMP indicates that operators
learn the 'location' of specific service or device related data and learn the 'location' of specific service or device related data and
do not expect such information to be arbitrary and discovered each do not expect such information to be arbitrary and discovered each
time the client opens a management session to a server. time the client opens a management session to a server.
The RESTCONF protocol operates on a conceptual datastore defined with The RESTCONF protocol operates on a conceptual datastore defined with
the YANG data modeling language. The server lists each YANG module the YANG data modeling language. The server lists each YANG module
it supports under "{+restconf}/modules" in the top-level API resource it supports under "/modules" defined in the "ietf-yang-library" YANG
type, using a structure based on the YANG module capability URI module.
format defined in [RFC6020].
The conceptual datastore contents, data-model-specific operations and The conceptual datastore contents, data-model-specific operations and
notification events are identified by this set of YANG module notification events are identified by this set of YANG module
resources. All RESTCONF content identified as either a data resources. All RESTCONF content identified as either a data
resource, operation resource, or event stream resource is defined resource, operation resource, or event stream resource is defined
with the YANG language. with the YANG language.
The classification of data as configuration or non-configuration is The classification of data as configuration or non-configuration is
derived from the YANG "config" statement. Data ordering behavior is derived from the YANG "config" statement. Data ordering behavior is
derived from the YANG "ordered-by" statement. derived from the YANG "ordered-by" statement.
skipping to change at page 9, line 30 skipping to change at page 9, line 39
o ordered-by user o ordered-by user
1.4.4. Terms 1.4.4. Terms
The following terms are used within this document: The following terms are used within this document:
o API resource: a resource with the media type "application/ o API resource: a resource with the media type "application/
yang.api+xml" or "application/yang.api+json". API resources can yang.api+xml" or "application/yang.api+json". API resources can
only be edited by the server. only be edited by the server.
o collection resource: a resource with the media type "application/
yang.collection+xml" or "application/yang.collection+json".
Contains a set of data resources.
o data resource: a resource with the media type "application/ o data resource: a resource with the media type "application/
yang.data+xml" or "application/yang.data+json". Data resources yang.data+xml" or "application/yang.data+json". Containers,
can be edited by clients or the server. All YANG data node types leafs, list entries and anyxml nodes can be data resources.
can be data resources. YANG terminal nodes cannot contain child
resources.
o datastore resource: a resource with the media type "application/ o datastore resource: a resource with the media type "application/
yang.datastore+xml" or "application/yang.datastore+json". yang.datastore+xml" or "application/yang.datastore+json".
Represents a configuration datastore. Represents a configuration datastore.
o edit operation: a RESTCONF operation on a data resource using the o edit operation: a RESTCONF operation on a data resource using the
POST, PUT, PATCH, or DELETE method. POST, PUT, PATCH, or DELETE method.
o event stream resource: This resource represents an SSE (Server- o event stream resource: This resource represents an SSE (Server-
Sent Events) event stream. The content consists of text using the Sent Events) event stream. The content consists of text using the
media type "text/event-stream", as defined by the HTML5 media type "text/event-stream", as defined by the HTML5
specification. Each event represents one <notification> message specification. Each event represents one <notification> message
generated by the server. It contains a conceptual system or data- generated by the server. It contains a conceptual system or data-
model specific event that is delivered within a notification event model specific event that is delivered within a notification event
stream. stream. Also called a "stream resource".
o operation: the conceptual RESTCONF operation for a message, o operation: the conceptual RESTCONF operation for a message,
derived from the HTTP method, request URI, headers, and message derived from the HTTP method, request URI, headers, and message
body. body.
o operation resource: a resource with the media type "application/ o operation resource: a resource with the media type "application/
yang.operation+xml" or "application/yang.operation+json". yang.operation+xml" or "application/yang.operation+json".
o patch: a generic PATCH request on the target datastore or data o patch: a generic PATCH request on the target datastore or data
resource. The media type of the message body content will resource. The media type of the message body content will
skipping to change at page 10, line 36 skipping to change at page 10, line 44
o unified datastore: A conceptual representation of the device o unified datastore: A conceptual representation of the device
running configuration. The server will hide all NETCONF datastore running configuration. The server will hide all NETCONF datastore
details for edit operations, such as the ":candidate" and details for edit operations, such as the ":candidate" and
":startup" capabilities. ":startup" capabilities.
o schema resource: a resource with the media type "application/ o schema resource: a resource with the media type "application/
yang". The YANG representation of the schema can be retrieved by yang". The YANG representation of the schema can be retrieved by
the client with the GET method. the client with the GET method.
o YANG terminal node: a YANG node representing a leaf, leaf-list, or o stream list: the set of data resource instances that describe the
anyxml definition. event stream resources available from the server. This
information is defined in the "ietf-restconf-monitoring" module as
the "stream" list. It can be retrieved using the target resource
"{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/
stream". The stream list contains information about each stream,
such as the URL to retrieve the event stream data.
1.4.5. Tree Diagrams 1.4.5. URI Template
Throughout this document, the URI template [RFC6570] syntax
"{+restconf}" is used to refer to the RESTCONF API entry point
outside of an example. See @path-resolution@ for details.
All of the examples in this document assume "/restconf" as the
discovered RESTCONF API root path.
1.4.6. Tree Diagrams
A simplified graphical representation of the data model is used in A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these diagrams is as this document. The meaning of the symbols in these diagrams is as
follows: follows:
o Brackets "[" and "]" enclose list keys. o Brackets "[" and "]" enclose list keys.
o Abbreviations before data node names: "rw" means configuration o Abbreviations before data node names: "rw" means configuration
data (read-write) and "ro" state data (read-only). data (read-write) and "ro" state data (read-only).
skipping to change at page 12, line 5 skipping to change at page 12, line 24
The resources used in the RESTCONF protocol are identified by the The resources used in the RESTCONF protocol are identified by the
"path" component in the request URI. Each operation is performed on "path" component in the request URI. Each operation is performed on
a target resource. a target resource.
2.1. RESTCONF Resource Types 2.1. RESTCONF Resource Types
The RESTCONF protocol defines a set of application specific media The RESTCONF protocol defines a set of application specific media
types to identify each of the available resource types. The types to identify each of the available resource types. The
following resource types are defined in RESTCONF: following resource types are defined in RESTCONF:
+-----------+----------------------------+ +------------+-----------------------------+
| Resource | Media Type | | Resource | Media Type |
+-----------+----------------------------+ +------------+-----------------------------+
| API | application/yang.api | | API | application/yang.api |
| Datastore | application/yang.datastore | | Collection | application/yang.collection |
| Data | application/yang.data | | Datastore | application/yang.datastore |
| Errors | application/yang.errors | | Data | application/yang.data |
| Operation | application/yang.operation | | Errors | application/yang.errors |
| Schema | application/yang | | Operation | application/yang.operation |
+-----------+----------------------------+ | Schema | application/yang |
+------------+-----------------------------+
RESTCONF Media Types RESTCONF Media Types
2.2. Resource Discovery 2.2. Resource Discovery
A client SHOULD start by retrieving the top-level API resource, using A client SHOULD start by retrieving the top-level API resource, using
the entry point URI defined in Section 4.2. the entry point URI defined in Section 4.2.
The RESTCONF protocol does not include a resource discovery The RESTCONF protocol does not include a resource discovery
mechanism. Instead, the definitions within the YANG modules mechanism. Instead, the definitions within the YANG modules
skipping to change at page 14, line 16 skipping to change at page 14, line 31
This optional resource is a container that provides access to the This optional resource is a container that provides access to the
data-model specific protocol operations supported by the server. The data-model specific protocol operations supported by the server. The
server MAY omit this resource if no data-model specific operations server MAY omit this resource if no data-model specific operations
are advertised. are advertised.
Any data-model specific operations defined in the YANG modules Any data-model specific operations defined in the YANG modules
advertised by the server MAY be available as child nodes of this advertised by the server MAY be available as child nodes of this
resource. resource.
Operation resources are defined in Section 2.6. Operation resources are defined in Section 2.7.
2.4. Datastore Resource 2.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 and operational data
nodes. nodes.
A "unified datastore" interface is used to simplify resource editing A "unified datastore" interface is used to simplify resource editing
for the client. The RESTCONF unified datastore is a conceptual for the client. The RESTCONF unified datastore is a conceptual
interface to the native configuration datastores that are present on interface to the native configuration datastores that are present on
skipping to change at page 15, line 35 skipping to change at page 15, line 50
The server MUST maintain a resource entity tag for this resource, and The server MUST maintain a resource entity tag for this resource, and
return the "ETag" header when this resource is retrieved with the GET return the "ETag" header when this resource is retrieved with the GET
or HEAD methods. The resource entity tag MUST be changed to a new or HEAD methods. The resource entity tag MUST be changed to a new
previously unused value if changes to any configuration data previously unused value if changes to any configuration data
resources within the datastore are made. resources within the datastore are made.
2.5. Data Resource 2.5. Data Resource
A data resource represents a YANG data node that is a descendant node A data resource represents a YANG data node that is a descendant node
of a datastore resource. of a datastore resource. Containers, leafs, list entries and anyxml
nodes are data resources.
For configuration data resources, the server MAY maintain a last- For configuration data resources, the server MAY maintain a last-
modified timestamp for the resource, and return the "Last-Modified" modified timestamp for the resource, and return the "Last-Modified"
header when it is retrieved with the GET or HEAD methods. If header when it is retrieved with the GET or HEAD methods. If
maintained, the resource timestamp MUST be set to the current time 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. resource is altered.
For configuration data resources, the server MAY maintain a resource For configuration data resources, the server MAY maintain a resource
entity tag for the resource, and return the "ETag" header when it is entity tag for the resource, and return the "ETag" header when it is
skipping to change at page 18, line 5 skipping to change at page 18, line 19
list list2 { list list2 {
key "key4 key5"; key "key4 key5";
... ...
leaf X { type string; } leaf X { type string; }
} }
} }
For the above YANG definition, URI with key leaf values will be For the above YANG definition, URI with key leaf values will be
encoded as follows (line wrapped for display purposes only): encoded as follows (line wrapped for display purposes only):
/restconf/data/top/list1=key1val,key2val,key3val3/ /restconf/data/example-top:top/list1=key1val,key2val,key3val3/
list2=key4val,key5val/X list2=key4val,key5val/X
2.5.1.1. ABNF For Data Resource Identifiers 2.5.1.1. ABNF For Data Resource Identifiers
The "api-path" ABNF syntax is used to construct RESTCONF path The "api-path" ABNF syntax is used to construct RESTCONF path
identifiers: identifiers:
api-path = "/" | api-path = "/" |
("/" api-identifier ("/" api-identifier
0*("/" (api-identifier | list-instance ))) 0*("/" (api-identifier | list-instance )))
skipping to change at page 19, line 5 skipping to change at page 19, line 15
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 given a value
yet, the server MUST return the default value that is in use by the yet, 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.
2.6. Operation Resource 2.6. Collection Resource
A collection resource contains a set of data resources. It is used
to represent a all instances or a subset of all instances in a YANG
list or leaf-list.
A collection resource can be retrieved with the GET method,
optionally with the query parameters "limit" (Section 3.8.7) and
"offset" (Section 3.8.8).
The "ietf-restconf" YANG module contains the "collection" grouping
which specifies the syntax of a collection resource.
2.7. Operation Resource
An operation resource represents an protocol operation defined with An operation resource represents an protocol operation defined with
the YANG "rpc" statement. the YANG "rpc" statement.
All operation resources share the same module namespace as any top- All operation resources share the same module namespace as any top-
level data resources, so the name of an operation resource cannot level data resources, so the name of an operation resource cannot
conflict with the name of a top-level data resource defined within conflict with the name of a top-level data resource defined within
the same module. the same module.
If 2 different YANG modules define the same "rpc" identifier, then If 2 different YANG modules define the same "rpc" identifier, then
skipping to change at page 19, line 36 skipping to change at page 20, line 10
same general function on different resource types. same general function on different resource types.
If the "rpc" statement has an "input" section, then a message body If the "rpc" statement has an "input" section, then a message body
MAY be sent by the client in the request, otherwise the request MAY be sent by the client in the request, otherwise the request
message MUST NOT include a message body. If the "rpc" statement has message MUST NOT include a message body. If the "rpc" statement has
an "output" section, then a message body MAY be sent by the server in an "output" section, then a message body MAY be sent by the server in
the response. Otherwise the server MUST NOT include a message body the response. Otherwise the server MUST NOT include a message body
in the response message, and MUST send a "204 No Content" Status-Line in the response message, and MUST send a "204 No Content" Status-Line
instead. instead.
2.6.1. Encoding Operation Input Parameters 2.7.1. Encoding Operation Input Parameters
If the "rpc" statement has an "input" section, then the "input" node If the "rpc" statement has an "input" section, then the "input" node
is provided in the message body, corresponding to the YANG data is provided in the message body, corresponding to the YANG data
definition statements within the "input" section. definition statements within the "input" section.
Example: Example:
The following YANG definition is used for the examples in this The following YANG definition is used for the examples in this
section. section.
skipping to change at page 20, line 37 skipping to change at page 21, line 5
"language" : "en-US" "language" : "en-US"
} }
} }
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
2.6.2. Encoding Operation Output Parameters 2.7.2. Encoding Operation Output Parameters
If the "rpc" statement has an "output" section, then the "output" If the "rpc" statement has an "output" section, then the "output"
node is provided in the message body, corresponding to the YANG data node is provided in the message body, corresponding to the YANG data
definition statements within the "output" section. definition statements within the "output" section.
Example: Example:
The following YANG definition is used for the examples in this The following YANG definition is used for the examples in this
section. section.
skipping to change at page 21, line 38 skipping to change at page 22, line 5
Content-Type: application/yang.operation+json Content-Type: application/yang.operation+json
{ {
"example-ops:output" : { "example-ops:output" : {
"reboot-time" : 30, "reboot-time" : 30,
"message" : "Going down for system maintenance", "message" : "Going down for system maintenance",
"language" : "en-US" "language" : "en-US"
} }
} }
2.7. Schema Resource 2.8. Schema Resource
If the server supports the "schema" leaf within the API then the If the server supports the "schema" leaf within the API then the
client can retrieve the YANG schema text for the associated YANG client can retrieve the YANG schema text for the associated YANG
module or submodule, using the GET method. First the client needs to module or submodule, using the GET method. First the client needs to
retrieve the URL for retrieving the schema. retrieve the URL for retrieving the schema.
The client might send the following GET request message: The client might send the following GET request message:
GET /restconf/data/modules/module= GET /restconf/data/ietf-yang-library:modules/module=
example-jukebox,2014-07-03/schema HTTP/1.1 example-jukebox,2014-07-03/schema HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json, Accept: application/yang.data+json,
application/yang.errors+json application/yang.errors+json
The server might respond: The server might respond:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 25 Apr 2012 11:10:30 GMT Date: Mon, 25 Apr 2012 11:10:30 GMT
Server: example-server Server: example-server
Content-Type: application/yang.data+json Content-Type: application/yang.data+json
{ {
"schema": "ietf-yang-library:schema":
"http://example.com/mymodules/example-jukebox/2014-07-03" "http://example.com/mymodules/example-jukebox/2014-07-03"
} }
Next the client needs to retrieve the actual YANG schema. Next the client needs to retrieve the actual YANG schema.
The client might send the following GET request message: The client might send the following GET request message:
GET http://example.com/mymodules/example-jukebox/2014-07-03 GET http://example.com/mymodules/example-jukebox/2014-07-03
HTTP/1.1 HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json, Accept: application/yang, application/yang.errors+json
application/yang.errors+json
The server might respond: The server might respond:
module example-jukebox { module example-jukebox {
namespace "http://example.com/ns/example-jukebox"; namespace "http://example.com/ns/example-jukebox";
prefix "jbox"; prefix "jbox";
// rest of YANG module content deleted... // rest of YANG module content deleted...
} }
2.8. Stream Resource 2.9. Stream Resource
A "stream" resource represents a source for system generated event A "stream" resource represents a source for system generated event
notifications. Each stream is created and modified by the server notifications. Each stream is created and modified by the server
only. A client can retrieve a stream resource or initiate a long- only. A client can retrieve a stream resource or initiate a long-
poll server sent event stream, using the procedure specified in poll server sent event stream, using the procedure specified in
Section 5.3. Section 5.3.
A notification stream functions according to the NETCONF A notification stream functions according to the NETCONF
Notifications specification [RFC5277]. The "ietf-restconf" YANG Notifications specification [RFC5277]. The available streams can be
module contains the "stream" list ("{+restconf}/streams/stream") retrieved from the stream list, which specifies the syntax and
which specifies the syntax and semantics of a stream resource. semantics of a stream resource.
2.9. Errors Resource 2.10. Errors Resource
An "errors" resource is a collection of error information that is An "errors" resource is a collection of error information that is
sent as the message body in a server response message, if an error sent as the message body in a server response message, if an error
occurs while processing a request message. occurs while processing a request message.
The "ietf-restconf" YANG module contains the "errors" grouping which The "ietf-restconf" YANG module contains the "errors" grouping which
specifies the syntax and semantics of an errors resource. RESTCONF specifies the syntax and semantics of an errors resource. RESTCONF
error handling behavior is defined in Section 6. error handling behavior is defined in Section 6.
3. Operations 3. Operations
skipping to change at page 25, line 28 skipping to change at page 25, line 44
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:02:40 GMT Date: Mon, 23 Apr 2012 17:02:40 GMT
Server: example-server Server: example-server
Content-Type: application/yang.data+json Content-Type: application/yang.data+json
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Pragma: no-cache
ETag: a74eefc993a2b ETag: a74eefc993a2b
Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT
{ {
"album" : [ "example-jukebox:album" : [
{ {
"name" : "Wasting Light", "name" : "Wasting Light",
"genre" : "example-jukebox:alternative", "genre" : "example-jukebox:alternative",
"year" : 2011 "year" : 2011
} }
] ]
} }
3.4. POST 3.4. POST
skipping to change at page 26, line 52 skipping to change at page 27, line 19
Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT
ETag: b3a3e673be2 ETag: b3a3e673be2
Refer to Appendix D.2.1 for more resource creation examples. Refer to Appendix D.2.1 for more resource creation examples.
3.4.2. Invoke Operation Mode 3.4.2. Invoke Operation Mode
If the target resource type is an operation resource, then the POST If the target resource type is an operation resource, then the POST
method is treated as a request to invoke that operation. The message method is treated as a request to invoke that operation. The message
body (if any) is processed as the operation input parameters. Refer body (if any) is processed as the operation input parameters. Refer
to Section 2.6 for details on operation resources. to Section 2.7 for details on operation resources.
If the POST request succeeds, a "200 OK" Status-Line is returned if If the POST request succeeds, a "200 OK" Status-Line is returned if
there is a response message body, and a "204 No Content" Status-Line there is a response message body, and a "204 No Content" Status-Line
is returned if there is no response message body. is returned if there is no response message body.
If the user is not authorized to invoke the target operation, an If the user is not authorized to invoke the target operation, an
error response containing a "403 Forbidden" or "404 Not Found" error response containing a "403 Forbidden" or "404 Not Found"
Status-Line is returned to the client. All other error responses are Status-Line is returned to the client. All other error responses are
handled according to the procedures defined in Section 6. handled according to the procedures defined in Section 6.
skipping to change at page 31, line 16 skipping to change at page 31, line 23
| Name | Methods | Description | | Name | Methods | Description |
+------------+----------+-------------------------------------------+ +------------+----------+-------------------------------------------+
| content | GET | Select config and/or non-config data | | content | GET | Select config and/or non-config data |
| | | resources | | | | resources |
| depth | GET | Request limited sub-tree depth in the | | depth | GET | Request limited sub-tree depth in the |
| | | reply content | | | | reply content |
| filter | GET | Boolean notification filter for event- | | filter | GET | Boolean notification filter for event- |
| | | stream resources | | | | stream resources |
| insert | POST, | Insertion mode for user-ordered data | | insert | POST, | Insertion mode for user-ordered data |
| | PUT | resources | | | PUT | resources |
| limit | GET | Number of entries to return for |
| | | collection resources |
| offset | GET | Starting point for collection resources |
| point | POST, | Insertion point for user-ordered data | | point | POST, | Insertion point for user-ordered data |
| | PUT | resources | | | PUT | resources |
| select | GET | Request a subset of the target resource | | select | GET | Request a subset of the target resource |
| | | contents | | | | contents |
| start-time | GET | Replay buffer start time for event-stream | | start-time | GET | Replay buffer start time for event-stream |
| | | resources | | | | resources |
| stop-time | GET | Replay buffer stop time for event-stream | | stop-time | GET | Replay buffer stop time for event-stream |
| | | resources | | | | resources |
+------------+----------+-------------------------------------------+ +------------+----------+-------------------------------------------+
skipping to change at page 32, line 12 skipping to change at page 32, line 12
A new set of NETCONF Capability URNs are defined to identify the A new set of NETCONF Capability URNs are defined to identify the
specific query parameters supported by the server. specific query parameters supported by the server.
+---------+-------------------------------------------------+ +---------+-------------------------------------------------+
| Name | URI | | Name | URI |
+---------+-------------------------------------------------+ +---------+-------------------------------------------------+
| content | urn:ietf:params:restconf:capability:content:1.0 | | content | urn:ietf:params:restconf:capability:content:1.0 |
| depth | urn:ietf:params:restconf:capability:depth:1.0 | | depth | urn:ietf:params:restconf:capability:depth:1.0 |
| filter | urn:ietf:params:restconf:capability:filter:1.0 | | filter | urn:ietf:params:restconf:capability:filter:1.0 |
| insert | urn:ietf:params:restconf:capability:insert:1.0 | | insert | urn:ietf:params:restconf:capability:insert:1.0 |
| page | urn:ietf:params:restconf:capability:page:1.0 |
| select | urn:ietf:params:restconf:capability:select:1.0 | | select | urn:ietf:params:restconf:capability:select:1.0 |
| replay | urn:ietf:params:restconf:capability:replay:1.0 | | replay | urn:ietf:params:restconf:capability:replay:1.0 |
+---------+-------------------------------------------------+ +---------+-------------------------------------------------+
RESTCONF Query Parameter URIs RESTCONF Query Parameter URIs
3.8.2. The "content" Query Parameter 3.8.2. The "content" Query Parameter
The "content" parameter controls how descendant nodes of the The "content" parameter controls how descendant nodes of the
requested data nodes will be processed in the reply. requested data nodes will be processed in the reply.
skipping to change at page 35, line 20 skipping to change at page 35, line 24
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 error is returned. than "before" or "after", then a 400 Bad Request error is returned.
This parameter contains the instance identifier of the resource to be This parameter contains the instance identifier of the resource to be
used as the insertion point for a POST or PUT method. used as the insertion point for a POST or PUT method.
If the server includes the "insert" query parameter URI in the If the server includes the "insert" query parameter URI in the
"capability" leaf-list in Section 8.3, then the "point" query "capability" leaf-list in Section 8.3, then the "point" query
parameter MUST be supported. parameter MUST be supported.
3.8.7. The "filter" Query Parameter 3.8.7. The "limit" Query Parameter
The "limit" parameter is used to restrict the number of data
resources to return in response to GET requests on collection
resources.
The value of the "limit" parameter is either an integer greater than
or equal to 1, or the string "unbounded". The string "unbounded" is
the default value.
If the server includes the "page" query parameter URI in the
"capability" leaf-list in Section 8.3, then the "limit" query
parameter MUST be supported.
3.8.8. The "offset" Query Parameter
The "offset" parameter is used to specify the first data resource to
return in response to GET requests on collection resources.
Resources instances are numbered with consecutive integers from 1 to
the number of resource instances.
The value of the "offset" parameter is an integer greater than or
equal to 1. The default value is 1.
If the server includes the "page" query parameter URI in the
"capability" leaf-list in Section 8.3, then the "offset" query
parameter MUST be supported.
3.8.9. The "filter" Query Parameter
The "filter" parameter is used to indicate which subset of all The "filter" parameter is used to indicate which subset of all
possible events are of interest. If not present, all events not possible events are of interest. If not present, all events not
precluded by other parameters will be sent. precluded by other parameters will be sent.
This parameter is only allowed for GET methods on a text/event-stream This parameter is only allowed for GET methods on a text/event-stream
data resource. A 400 Bad Request error is returned if used for other data resource. A 400 Bad Request error is returned if used for other
methods or resource types. methods or resource types.
The format of this parameter is an XPath 1.0 expression, and is The format of this parameter is an XPath 1.0 expression, and is
skipping to change at page 36, line 5 skipping to change at page 36, line 39
The filter is used as defined in [RFC5277], section 3.6. If the The filter is used as defined in [RFC5277], section 3.6. If the
boolean result of the expression is true when applied to the boolean result of the expression is true when applied to the
conceptual "notification" document root, then the notification event conceptual "notification" document root, then the notification event
is delivered to the client. is delivered to the client.
If this query parameter is supported by the server, then the "filter" If this query parameter is supported by the server, then the "filter"
query parameter URI MUST be listed in the "capability" leaf-list in query parameter URI MUST be listed in the "capability" leaf-list in
Section 8.3. Section 8.3.
3.8.8. The "start-time" Query Parameter 3.8.10. The "start-time" Query Parameter
The "start-time" parameter is used to trigger the notification replay The "start-time" parameter is used to trigger the notification replay
feature and indicate that the replay should start at the time feature and indicate that the replay should start at the time
specified. If the stream does not support replay, per the specified. If the stream does not support replay, per the
"replay-support" attribute returned by the /restconf/streams "replay-support" attribute returned by stream list entry for the
resource, then the server MUST return the HTTP error code 400 Bad stream resource, then the server MUST return the HTTP error code 400
Request. Bad Request.
The value of the "start-time" parameter is of type "date-and-time", The value of the "start-time" parameter is of type "date-and-time",
defined in the "ietf-yang" YANG module [RFC6991]. defined in the "ietf-yang" YANG module [RFC6991].
This parameter is only allowed for GET methods on a text/event-stream This parameter is only allowed for GET methods on a text/event-stream
data resource. A 400 Bad Request error is returned if used for other data resource. A 400 Bad Request error is returned if used for other
methods or resource types. methods or resource types.
If this parameter is not present, then a replay subscription is not If this parameter is not present, then a replay subscription is not
being requested. It is not valid to specify start times that are being requested. It is not valid to specify start times that are
skipping to change at page 36, line 36 skipping to change at page 37, line 24
If this query parameter is supported by the server, then the "replay" If this query parameter is supported by the server, then the "replay"
query parameter URI MUST be listed in the "capability" leaf-list in query parameter URI MUST be listed in the "capability" leaf-list in
Section 8.3. The "stop-time" query parameter MUST also be supported Section 8.3. The "stop-time" query parameter MUST also be supported
by the server. by the server.
If the "replay-support" leaf is present in the "stream" entry If the "replay-support" leaf is present in the "stream" entry
(defined in Section 8.3) then the server MUST support the (defined in Section 8.3) then the server MUST support the
"start-time" and "stop-time" query parameters for that stream. "start-time" and "stop-time" query parameters for that stream.
3.8.9. The "stop-time" Query Parameter 3.8.11. The "stop-time" Query Parameter
The "stop-time" parameter is used with the replay feature to indicate The "stop-time" parameter is used with the replay feature to indicate
the newest notifications of interest. This parameter MUST be used the newest notifications of interest. This parameter MUST be used
with and have a value later than the "start-time" parameter. with and have a value later than the "start-time" parameter.
The value of the "stop-time" parameter is of type "date-and-time", The value of the "stop-time" parameter is of type "date-and-time",
defined in the "ietf-yang" YANG module [RFC6991]. defined in the "ietf-yang" YANG module [RFC6991].
This parameter is only allowed for GET methods on a text/event-stream This parameter is only allowed for GET methods on a text/event-stream
data resource. A 400 Bad Request error is returned if used for other data resource. A 400 Bad Request error is returned if used for other
skipping to change at page 37, line 49 skipping to change at page 38, line 40
<text> replaced by client with real values <text> replaced by client with real values
o method: the HTTP method identifying the RESTCONF operation o method: the HTTP method identifying the RESTCONF operation
requested by the client, to act upon the target resource specified requested by the client, to act upon the target resource specified
in the request URI. RESTCONF operation details are described in in the request URI. RESTCONF operation details are described in
Section 3. Section 3.
o entry: the root of the RESTCONF API configured on this HTTP o entry: the root of the RESTCONF API configured on this HTTP
server, discovered by getting the ".well-known/host-meta" server, discovered by getting the ".well-known/host-meta"
resource, as described in Section 4.2. All of the examples in resource, as described in Section 4.2.
this document assume "/restconf" as the discovered RESTCONF API
root path. The URI template [RFC6570] syntax "{+restconf}" is
used to refer to the entry point outside of an example.
o resource: the path expression identifying the resource that is o resource: the path expression identifying the resource that is
being accessed by the operation. If this field is not present, being accessed by the operation. If this field is not present,
then the target resource is the API itself, represented by the then the target resource is the API itself, represented by the
media type "application/yang.api". media type "application/yang.api".
o query: the set of parameters associated with the RESTCONF message. o query: the set of parameters associated with the RESTCONF message.
These have the familiar form of "name=value" pairs. All query These have the familiar form of "name=value" pairs. All query
parameters are optional to implement by the server and optional to parameters are optional to implement by the server and optional to
use by the client. Each query parameter is identified by a URI. use by the client. Each query parameter is identified by a URI.
skipping to change at page 40, line 46 skipping to change at page 41, line 30
+---------------+---------------------------------------------------+ +---------------+---------------------------------------------------+
RESTCONF Response Headers RESTCONF Response Headers
4.4. Message Encoding 4.4. Message Encoding
RESTCONF messages are encoded in HTTP according to RFC 2616. The RESTCONF messages are encoded in HTTP according to RFC 2616. The
"utf-8" character set is used for all messages. RESTCONF message "utf-8" character set is used for all messages. RESTCONF message
content is sent in the HTTP message body. content is sent in the HTTP message body.
Content is encoded in either JSON or XML format. Content is encoded in either JSON or XML format. A server MUST
support XML encoding and MAY support JSON encoding. XML encoding
XML encoding rules for data nodes are defined in [RFC6020]. The same rules for data nodes are defined in [RFC6020]. The same encoding
encoding rules are used for all XML content. rules are used for all XML content. JSON encoding rules are defined
in [I-D.ietf-netmod-json]. This encoding is valid JSON, but also has
JSON encoding rules are defined in [I-D.lhotka-netmod-json]. This special encoding rules to identify module namespaces and provide
encoding is valid JSON, but also has special encoding rules to consistent type processing of YANG data.
identify module namespaces and provide consistent type processing of
YANG data.
Request input content encoding format is identified with the Content- Request input content encoding format is identified with the Content-
Type header. This field MUST be present if a message body is sent by Type header. This field MUST be present if a message body is sent by
the client. the client.
Response output content encoding format is identified with the Accept Response output content encoding format is identified with the Accept
header in the request, or if is not specified, the request input header in the request, or if is not specified, the request input
encoding format is used. If there was no request input, then the encoding format is used. If there was no request input, then the
default output encoding is XML. File extensions encoded in the default output encoding is XML. File extensions encoded in the
request are not used to identify format encoding. request are not used to identify format encoding.
skipping to change at page 41, line 27 skipping to change at page 42, line 9
4.5. RESTCONF Meta-Data 4.5. RESTCONF Meta-Data
The RESTCONF protocol needs to retrieve the same meta-data that is The RESTCONF protocol needs to retrieve the same meta-data that is
used in the NETCONF protocol. Information about default leafs, last- used in the NETCONF protocol. Information about default leafs, last-
modified timestamps, etc. are commonly used to annotate modified timestamps, etc. are commonly used to annotate
representations of the datastore contents. This meta-data is not representations of the datastore contents. This meta-data is not
defined in the YANG schema because it applies to the datastore, and defined in the YANG schema because it applies to the datastore, and
is common across all data nodes. is common across all data nodes.
This information is encoded as attributes in XML. JSON encoding of This information is encoded as attributes in XML. JSON encoding of
meta-data is defined in [I-D.lhotka-netmod-json]. meta-data is defined in [I-D.lhotka-netmod-yang-metadata].
4.6. Return Status 4.6. Return Status
Each message represents some sort of resource access. An HTTP Each message represents some sort of resource access. An HTTP
"Status-Line" header line is returned for each request. If a 4xx or "Status-Line" header line is returned for each request. If a 4xx or
5xx range status code is returned in the Status-Line, then the error 5xx range status code is returned in the Status-Line, then the error
information will be returned in the response, according to the format information will be returned in the response, according to the format
defined in Section 6.1. defined in Section 6.1.
4.7. Message Caching 4.7. Message Caching
skipping to change at page 42, line 13 skipping to change at page 42, line 43
or "If-Modified-Since" headers, which will cause the server to return or "If-Modified-Since" headers, which will cause the server to return
a "304 Not Modified" Status-Line if the resource has not changed. a "304 Not Modified" Status-Line if the resource has not changed.
The client MAY use the HEAD method to retrieve just the message The client MAY use the HEAD method to retrieve just the message
headers, which SHOULD include the "ETag" and "Last-Modified" headers, headers, which SHOULD include the "ETag" and "Last-Modified" headers,
if this meta-data is maintained for the target resource. if this meta-data is maintained for the target resource.
5. Notifications 5. Notifications
The RESTCONF protocol supports YANG-defined event notifications. The The RESTCONF protocol supports YANG-defined event notifications. The
solution preserves aspects of NETCONF Event Notifications [RFC5277] solution preserves aspects of NETCONF Event Notifications [RFC5277]
while utilizing the Server-Sent Events [wd-eventsource] transport while utilizing the Server-Sent Events [W3C.CR-eventsource-20121211]
strategy. transport strategy.
5.1. Server Support 5.1. Server Support
A RESTCONF server is not required to support RESTCONF notifications. A RESTCONF server is not required to support RESTCONF notifications.
Clients may determine if a server supports RESTCONF notifications by Clients may determine if a server supports RESTCONF notifications by
using the HTTP operation OPTIONS, HEAD, or GET on the using the HTTP operation OPTIONS, HEAD, or GET on the stream list.
"{+restconf}/streams" resource described below. The server does not
support RESTCONF notifications if an HTTP error code is returned The server does not support RESTCONF notifications if an HTTP error
(e.g., 404 Not Found). code is returned (e.g., 404 Not Found).
5.2. Event Streams 5.2. Event Streams
A RESTCONF server that supports notifications will populate a stream A RESTCONF server that supports notifications will populate a stream
resource for each notification delivery service access point. A resource for each notification delivery service access point. A
RESTCONF client can retrieve the list of supported event streams from RESTCONF client can retrieve the list of supported event streams from
a RESTCONF server using the GET operation on the "restconf-state/ a RESTCONF server using the GET operation on the stream list.
streams" data resource defined in Section 8.3.
The "restconf-state/streams" container definition in the The "restconf-state/streams" container definition in the
"ietf-restconf-monitoring" module (defined in Section 8.3) is used to "ietf-restconf-monitoring" module (defined in Section 8.3) is used to
specify the structure and syntax of the conceptual child resources specify the structure and syntax of the conceptual child resources
within the "streams" resource. within the "streams" resource.
For example: For example:
The client might send the following request: The client might send the following request:
GET /restconf/data/restconf-state/streams HTTP/1.1 GET /restconf/data/ietf-restconf-monitoring:restconf-state/
streams HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+xml, Accept: application/yang.data+xml,
application/yang.errors+xml application/yang.errors+xml
The server might send the following response: The server might send the following response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/yang.api+xml Content-Type: application/yang.api+xml
<streams <streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<stream> <stream>
<name>NETCONF</name> <name>NETCONF</name>
<description>default NETCONF event stream <description>default NETCONF event stream
</description> </description>
<replay-support>true</replay-support> <replay-support>true</replay-support>
<replay-log-creation-time> <replay-log-creation-time>
2007-07-08T00:00:00Z 2007-07-08T00:00:00Z
</replay-log-creation-time> </replay-log-creation-time>
<events>http://example.com/streams/NETCONF</events> <encoding>
<type>xml</type>
<events>http://example.com/streams/NETCONF</events>
</encoding>
<encoding>
<type>json</type>
<events>http://example.com/streams/NETCONF-JSON</events>
</encoding>
</stream> </stream>
<stream> <stream>
<name>SNMP</name> <name>SNMP</name>
<description>SNMP notifications</description> <description>SNMP notifications</description>
<replay-support>false</replay-support> <replay-support>false</replay-support>
<events>http://example.com/streams/SNMP</events> <encoding>
<type>xml</type>
<events>http://example.com/streams/SNMP</events>
</encoding>
</stream> </stream>
<stream> <stream>
<name>syslog-critical</name> <name>syslog-critical</name>
<description>Critical and higher severity <description>Critical and higher severity
</description> </description>
<replay-support>true</replay-support> <replay-support>true</replay-support>
<replay-log-creation-time> <replay-log-creation-time>
2007-07-01T00:00:00Z 2007-07-01T00:00:00Z
</replay-log-creation-time> </replay-log-creation-time>
<events>http://example.com/streams/syslog-critical</events> <encoding>
<type>xml</type>
<events>
http://example.com/streams/syslog-critical
</events>
</encoding>
</stream> </stream>
</streams> </streams>
5.3. Subscribing to Receive Notifications 5.3. Subscribing to Receive Notifications
RESTCONF clients can determine the URL for the subscription resource RESTCONF clients can determine the URL for the subscription resource
(to receive notifications) by sending an HTTP GET request for the (to receive notifications) by sending an HTTP GET request for the
"{+restconf}/streams/stream/<stream-name>/events" data resource. "events" leaf with the stream list entry. The value returned by the
server can be used for the actual notification subscription.
The value returned by the server can be used for the actual
notification subscription.
The client will send an HTTP GET request for the URL returned by the The client will send an HTTP GET request for the URL returned by the
server with the "Accept" type "text/event-stream". server with the "Accept" type "text/event-stream".
The server will treat the connection as an event stream, using the The server will treat the connection as an event stream, using the
Server Sent Events [wd-eventsource] transport strategy. Server Sent Events [W3C.CR-eventsource-20121211] transport strategy.
The server MAY support query parameters for a GET method on this The server MAY support query parameters for a GET method on this
resource. These parameters are specific to each notification stream. resource. These parameters are specific to each notification stream.
For example: For example:
The client might send the following request: The client might send the following request:
GET /restconf/data/restconf-state/streams/stream=NETCONF/events GET /restconf/data/ietf-restconf-monitoring:restconf-state/
HTTP/1.1 streams/stream=NETCONF/encoding=xml/events HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+xml, Accept: application/yang.data+xml,
application/yang.errors+xml application/yang.errors+xml
The server might send the following response: The server might send the following response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/yang.api+xml Content-Type: application/yang.api+xml
<ietf-restconf-monitoring:events <events
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
http://example.com/streams/NETCONF http://example.com/streams/NETCONF
</events> </events>
The RESTCONF client can then use this URL value to start monitoring The RESTCONF client can then use this URL value to start monitoring
the event stream: the event stream:
GET /streams/NETCONF HTTP/1.1 GET /streams/NETCONF HTTP/1.1
Host: example.com Host: example.com
Accept: text/event-stream Accept: text/event-stream
skipping to change at page 45, line 5 skipping to change at page 46, line 20
Accept-Encoding: gzip, deflate Accept-Encoding: gzip, deflate
5.3.1. NETCONF Event Stream 5.3.1. NETCONF Event Stream
The server SHOULD support the "NETCONF" notification stream defined The server SHOULD support the "NETCONF" notification stream defined
in [RFC5277]. For this stream, RESTCONF notification subscription in [RFC5277]. For this stream, RESTCONF notification subscription
requests MAY specify parameters indicating the events it wishes to requests MAY specify parameters indicating the events it wishes to
receive. These query parameters are optional to implement, and only receive. These query parameters are optional to implement, and only
available if the server supports them. available if the server supports them.
+------------+-------------------------+ +------------+---------+-------------------------+
| Name | Description | | Name | Section | Description |
+------------+-------------------------+ +------------+---------+-------------------------+
| start-time | replay event start time | | start-time | 3.8.10 | replay event start time |
| stop-time | replay event stop time | | stop-time | 3.8.11 | replay event stop time |
| filter | boolean content filter | | filter | 3.8.9 | boolean content filter |
+------------+-------------------------+ +------------+---------+-------------------------+
NETCONF Stream Query Parameters NETCONF Stream Query Parameters
The semantics and syntax for these query parameters are defined in The semantics and syntax for these query parameters are defined in
the "query-parameters" YANG grouping in Section 7. The YANG encoding the sections listed above. The YANG encoding MUST be converted to
MUST be converted to URL-encoded string for use in the request URI. URL-encoded string for use in the request URI.
Refer to Appendix D.3.6 for filter parameter examples. Refer to Appendix D.3.8 for filter parameter examples.
5.4. Receiving Event Notifications 5.4. Receiving Event Notifications
RESTCONF notifications are encoded according to the definition of the RESTCONF notifications are encoded according to the definition of the
event stream. The NETCONF stream defined in [RFC5277] is encoded in event stream. The NETCONF stream defined in [RFC5277] is encoded in
XML format. XML format.
The structure of the event data is based on the "notification" The structure of the event data is based on the "notification"
element definition in section 4 of [RFC5277]. It MUST conform to the element definition in section 4 of [RFC5277]. It MUST conform to the
"notification" YANG container definition in Section 7. "notification" YANG container definition in Section 7.
An example SSE notification encoded using XML: An example SSE notification encoded using XML:
data: <notification data: <notification
data: xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> data: xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
data: <event-time>2013-12-21T00:01:00Z</event-time> data: <event-time>2013-12-21T00:01:00Z</event-time>
data: <event xmlns="http://example.com/event/1.0"> data: <event xmlns="http://example.com/event/1.0">
data: <eventClass>fault</eventClass> data: <event-class>fault</event-class>
data: <reportingEntity> data: <reporting-entity>
data: <card>Ethernet0</card> data: <card>Ethernet0</card>
data: </reportingEntity> data: </reporting-entity>
data: <severity>major</severity> data: <severity>major</severity>
data: </event> data: </event>
data: </notification> data: </notification>
Since XML is not whitespace sensitive, the above message can be An example SSE notification encoded using JSON:
encoded onto a single line.
data: {
data: "ietf-restconf:notification": {
data: "event-time": "2013-12-21T00:01:00Z",
data: "example-mod:event": {
data: "event-class": "fault",
data: "reporting-entity": { "card": "Ethernet0" },
data: "severity": "major"
data: }
data: }
data: }
Alternatively, since neither XML nor JSON are whitespace sensitive,
the above messages can be encoded onto a single line. For example:
For example: ('\' line wrapping added for formatting only) For example: ('\' line wrapping added for formatting only)
XML:
data: <notification xmlns="urn:ietf:params:xml:ns:yang:ietf-rest\ data: <notification xmlns="urn:ietf:params:xml:ns:yang:ietf-rest\
conf"><event-time>2013-12-21T00:01:00Z</event-time><event xmlns="\ conf"><event-time>2013-12-21T00:01:00Z</event-time><event xmlns="\
http://example.com/event/1.0"><eventClass>fault</eventClass><repo\ http://example.com/event/1.0"><event-class>fault</event-class><re\
rtingEntity><card>Ethernet0</card></reportingEntity><severity>maj\ portingEntity><card>Ethernet0</card></reporting-entity><severity>\
or</severity></event></notification> major</severity></event></notification>
JSON:
data: {"ietf-restconf:notification":{"event-time":"2013-12-21\
T00:01:00Z","example-mod:event":{"event-class": "fault","repor\
tingEntity":{"card":"Ethernet0"},"severity":"major"}}}
The SSE specifications supports the following additional fields: The SSE specifications supports the following additional fields:
event, id and retry. A RESTCONF server MAY send the "retry" field event, id and retry. A RESTCONF server MAY send the "retry" field
and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server
SHOULD NOT send the "event" or "id" fields, as there are no SHOULD NOT send the "event" or "id" fields, as there are no
meaningful values that could be used for them that would not be meaningful values that could be used for them that would not be
redundant to the contents of the notification itself. RESTCONF redundant to the contents of the notification itself. RESTCONF
servers that do not send the "id" field also do not need to support servers that do not send the "id" field also do not need to support
the HTTP header "Last-Event-Id". RESTCONF servers that do send the the HTTP header "Last-Event-Id". RESTCONF servers that do send the
"id" field MUST still support the "startTime" query parameter as the "id" field MUST still support the "startTime" query parameter as the
skipping to change at page 50, line 42 skipping to change at page 51, line 42
contents by a server. The "restconf" container is not intended to be contents by a server. The "restconf" container is not intended to be
implemented as a top-level data node (under the "/restconf/data" implemented as a top-level data node (under the "/restconf/data"
entry point). entry point).
The "ietf-yang-types" module from [RFC6991] is used by this module The "ietf-yang-types" module from [RFC6991] is used by this module
for some type definitions. for some type definitions.
RFC Ed.: update the date below with the date of RFC publication and RFC Ed.: update the date below with the date of RFC publication and
remove this note. remove this note.
<CODE BEGINS> file "ietf-restconf@2014-10-07.yang" <CODE BEGINS> file "ietf-restconf@2014-10-25.yang"
module ietf-restconf { module ietf-restconf {
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; namespace "urn:ietf:params:xml:ns:yang:ietf-restconf";
prefix "rc"; prefix "rc";
import ietf-yang-types { prefix yang; } import ietf-yang-types { prefix yang; }
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
skipping to change at page 52, line 4 skipping to change at page 53, line 4
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this // RFC Ed.: replace XXXX with actual RFC number and remove this
// note. // note.
// RFC Ed.: remove this note // RFC Ed.: remove this note
// Note: extracted from draft-ietf-netconf-restconf-02.txt // Note: extracted from draft-ietf-netconf-restconf-03.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2014-10-07 { revision 2014-10-25 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
typedef data-resource-identifier { typedef data-resource-identifier {
type string { type string {
length "1 .. max"; length "1 .. max";
} }
skipping to change at page 54, line 44 skipping to change at page 55, line 44
anyxml error-info { anyxml error-info {
description description
"Arbitrary XML that represents a container "Arbitrary XML that represents a container
of additional information for the error report."; of additional information for the error report.";
} }
} }
} }
} // grouping errors } // grouping errors
grouping restconf { grouping restconf {
description
"Conceptual container representing the
application/yang.api resource type.";
container restconf { container restconf {
description description
"Conceptual container representing the "Conceptual container representing the
application/yang.api resource type."; application/yang.api resource type.";
container data { container data {
description description
"Container representing the application/yang.datastore "Container representing the application/yang.datastore
resource type. Represents the conceptual root of all resource type. Represents the conceptual root of all
operational data and configuration data supported by operational data and configuration data supported by
skipping to change at page 55, line 33 skipping to change at page 56, line 37
POST /restconf/operations/show-log-errors POST /restconf/operations/show-log-errors
leaf show-log-errors { leaf show-log-errors {
type empty; type empty;
} }
"; ";
} }
} // container restconf } // container restconf
} // grouping restconf } // grouping restconf
grouping collection {
description
"Conceptual container representing the
application/yang.collection resource type.";
container collection {
description
"Container representing the application/yang.collection
resource type.";
}
} // grouping collection
grouping notification { grouping notification {
description description
"Contains the notification message wrapper definition."; "Contains the notification message wrapper definition.";
container notification { container notification {
description description
"RESTCONF notification message wrapper."; "RESTCONF notification message wrapper.";
leaf event-time { leaf event-time {
type yang:date-and-time; type yang:date-and-time;
skipping to change at page 56, line 44 skipping to change at page 58, line 14
+--ro restconf-state +--ro restconf-state
+--ro capabilities +--ro capabilities
| +--ro capability* inet:uri | +--ro capability* inet:uri
+--ro streams +--ro streams
+--ro stream* [name] +--ro stream* [name]
+--ro name string +--ro name string
+--ro description? string +--ro description? string
+--ro replay-support? boolean +--ro replay-support? boolean
+--ro replay-log-creation-time? yang:date-and-time +--ro replay-log-creation-time? yang:date-and-time
+--ro events inet:uri +--ro encoding* [type]
+--ro type string
+--ro events inet:uri
8.1. restconf-state/capabilities 8.1. restconf-state/capabilities
This mandatory container holds the RESTCONF protocol capability URIs This mandatory container holds the RESTCONF protocol capability URIs
supported by the server. supported by the server.
The server MUST maintain a last-modified timestamp for this The server MUST maintain a last-modified timestamp for this
container, and return the "Last-Modified" header when this data node container, and return the "Last-Modified" header when this data node
is retrieved with the GET or HEAD methods. is retrieved with the GET or HEAD methods.
skipping to change at page 57, line 24 skipping to change at page 58, line 42
This optional container provides access to the notification event This optional container provides access to the notification event
streams supported by the server. The server MAY omit this container streams supported by the server. The server MAY omit this container
if no notification event streams are supported. if no notification event streams are supported.
The server will populate this container with a stream list entry for The server will populate this container with a stream list entry for
each stream type it supports. Each stream contains a leaf called each stream type it supports. Each stream contains a leaf called
"events" which contains a URI that represents an event stream "events" which contains a URI that represents an event stream
resource. resource.
Stream resources are defined in Section 2.8. Notifications are Stream resources are defined in Section 2.9. Notifications are
defined in Section 5. defined in Section 5.
8.3. RESTCONF Monitoring Module 8.3. RESTCONF Monitoring Module
The "ietf-restconf-monitoring" module defines monitoring information The "ietf-restconf-monitoring" module defines monitoring information
for the RESTCONF protocol. for the RESTCONF protocol.
The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991]
are used by this module for some type definitions. are used by this module for some type definitions.
RFC Ed.: update the date below with the date of RFC publication and RFC Ed.: update the date below with the date of RFC publication and
remove this note. remove this note.
<CODE BEGINS> file "ietf-restconf-monitoring@2014-10-07.yang" <CODE BEGINS> file "ietf-restconf-monitoring@2014-10-25.yang"
module ietf-restconf-monitoring { module ietf-restconf-monitoring {
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring";
prefix "rcmon"; prefix "rcmon";
import ietf-yang-types { prefix yang; } import ietf-yang-types { prefix yang; }
import ietf-inet-types { prefix inet; } import ietf-inet-types { prefix inet; }
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
skipping to change at page 58, line 32 skipping to change at page 60, line 4
Copyright (c) 2014 IETF Trust and the persons identified as Copyright (c) 2014 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-02.txt // Note: extracted from draft-ietf-netconf-restconf-03.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2014-10-07 { revision 2014-10-25 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
container restconf-state { container restconf-state {
config false; config false;
description description
"Contains RESTCONF protocol monitoring information."; "Contains RESTCONF protocol monitoring information.";
skipping to change at page 60, line 4 skipping to change at page 61, line 23
} }
leaf replay-support { leaf replay-support {
type boolean; type boolean;
description description
"Indicates if replay buffer supported for this stream. "Indicates if replay buffer supported for this stream.
If 'true', then the server MUST support the 'start-time' If 'true', then the server MUST support the 'start-time'
and 'stop-time' query parameters for this stream."; and 'stop-time' query parameters for this stream.";
reference reference
"RFC 5277, Section 3.4, <replaySupport> element."; "RFC 5277, Section 3.4, <replaySupport> element.";
} }
leaf replay-log-creation-time { leaf replay-log-creation-time {
when "../replay-support"; when "../replay-support" {
description
"Only present if notification replay is supported";
}
type yang:date-and-time; type yang:date-and-time;
description description
"Indicates the time the replay log for this stream "Indicates the time the replay log for this stream
was created."; was created.";
reference reference
"RFC 5277, Section 3.4, <replayLogCreationTime> "RFC 5277, Section 3.4, <replayLogCreationTime>
element."; element.";
} }
leaf events { list encoding {
type inet:uri; key type;
mandatory true; min-elements 1;
description description
"Contains a URL that represents the entry point "The server will create an entry in this list for each
for establishing notification delivery via server encoding format that is supported for this stream.
sent events."; The media type 'application/yang.stream' is expected
for all event streams. This list identifies the
sub-types supported for this stream.";
leaf type {
type string;
description
"This is the secondary encoding format within the
'text/event-stream' encoding used by all streams.
The type 'xml' is supported for the media type
'application/yang.stream+xml'. The type 'json'
is supported for the media type
'application/yang.stream+json'.";
}
leaf events {
type inet:uri;
mandatory true;
description
"Contains a URL that represents the entry point
for establishing notification delivery via server
sent events.";
}
} }
} }
} }
} }
} }
<CODE ENDS> <CODE ENDS>
9. YANG Module Library 9. YANG Module Library
skipping to change at page 62, line 16 skipping to change at page 64, line 16
The "ietf-yang-library" module defines monitoring information for the The "ietf-yang-library" module defines monitoring information for the
YANG modules used by a RESTCONF server. YANG modules used by a RESTCONF server.
The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991]
are used by this module for some type definitions. are used by this module for some type definitions.
RFC Ed.: update the date below with the date of RFC publication and RFC Ed.: update the date below with the date of RFC publication and
remove this note. remove this note.
<CODE BEGINS> file "ietf-yang-library@2014-10-07.yang" <CODE BEGINS> file "ietf-yang-library@2014-10-25.yang"
module ietf-yang-library { module ietf-yang-library {
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library";
prefix "yanglib"; prefix "yanglib";
import ietf-yang-types { prefix yang; } import ietf-yang-types { prefix yang; }
import ietf-inet-types { prefix inet; } import ietf-inet-types { prefix inet; }
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
skipping to change at page 63, line 20 skipping to change at page 65, line 20
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-02.txt // Note: extracted from draft-ietf-netconf-restconf-03.txt
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2014-09-26 { revision 2014-10-25 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: RESTCONF Protocol."; "RFC XXXX: RESTCONF Protocol.";
} }
typedef revision-identifier { typedef revision-identifier {
type string { type string {
pattern '\d{4}-\d{2}-\d{2}'; pattern '\d{4}-\d{2}-\d{2}';
} }
skipping to change at page 67, line 32 skipping to change at page 69, line 32
10.3. application/yang Media Sub Types 10.3. application/yang Media Sub Types
The parent MIME media type for RESTCONF resources is application/ The parent MIME media type for RESTCONF resources is application/
yang, which is defined in [RFC6020]. This document defines the yang, which is defined in [RFC6020]. This document defines the
following sub-types for this media type. following sub-types for this media type.
- api - api
- data - data
- datastore - datastore
- collection
- errors - errors
- operation - operation
- stream - stream
Type name: application Type name: application
Subtype name: yang.xxx Subtype name: yang.xxx
Required parameters: TBD Required parameters: TBD
skipping to change at page 68, line 26 skipping to change at page 70, line 26
:depth :depth
urn:ietf:params:restconf:capability:depth:1.0 urn:ietf:params:restconf:capability:depth:1.0
:filter :filter
urn:ietf:params:restconf:capability:filter:1.0 urn:ietf:params:restconf:capability:filter:1.0
:insert :insert
urn:ietf:params:restconf:capability:insert:1.0 urn:ietf:params:restconf:capability:insert:1.0
:page
urn:ietf:params:restconf:capability:page:1.0
:select :select
urn:ietf:params:restconf:capability:select:1.0 urn:ietf:params:restconf:capability:select:1.0
:replay :replay
urn:ietf:params:restconf:capability:replay:1.0 urn:ietf:params:restconf:capability:replay:1.0
11. Security Considerations 11. Security Considerations
This section provides security considerations for the resources This section provides security considerations for the resources
defined by the RESTCONF protocol. Security considerations for HTTPS defined by the RESTCONF protocol. Security considerations for HTTPS
skipping to change at page 69, line 32 skipping to change at page 71, line 35
12. Acknowledgements 12. Acknowledgements
The authors would like to thank for following for lively discussions The authors would like to thank for following for lively discussions
on list and in the halls (ordered by last name): Rex Fernando on list and in the halls (ordered by last name): Rex Fernando
13. References 13. References
13.1. Normative References 13.1. Normative References
[I-D.lhotka-netmod-json] [I-D.ietf-netmod-json]
Lhotka, L., "Modeling JSON Text with YANG", draft-lhotka- Lhotka, L., "Modeling JSON Text with YANG", draft-ietf-
netmod-yang-json-02 (work in progress), September 2013. netmod-yang-json-01 (work in progress), October 2014.
[JSON] Bray, T., Ed., "The JSON Data Interchange Format", draft- [I-D.lhotka-netmod-yang-metadata]
ietf-json-rfc4627bis-10 (work in progress), December 2013. Lhotka, L., "Defining and Using Metadata with YANG",
draft-lhotka-netmod-yang-metadata-00 (work in progress),
September 2014.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol, Version 1.0", [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol, Version 1.0",
RFC 2246, January 1999. RFC 2246, January 1999.
[RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396, Resource Identifiers (URI): Generic Syntax", RFC 2396,
August 1998. August 1998.
skipping to change at page 71, line 5 skipping to change at page 73, line 5
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536, March Protocol (NETCONF) Access Control Model", RFC 6536, March
2012. 2012.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, March 2012. and D. Orchard, "URI Template", RFC 6570, March 2012.
[RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991,
July 2013. July 2013.
[RFC7158] Bray, T., Ed., "The JSON Data Interchange Format", RFC
7158, March 2013.
[W3C.CR-eventsource-20121211]
Hickson, I., "Server-Sent Events", World Wide Web
Consortium CR CR-eventsource-20121211, December 2012,
<http://www.w3.org/TR/2012/CR-eventsource-20121211>.
[W3C.REC-xml-20081126] [W3C.REC-xml-20081126]
Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C.,
and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC- Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008, xml-20081126, November 2008,
<http://www.w3.org/TR/2008/REC-xml-20081126>. <http://www.w3.org/TR/2008/REC-xml-20081126>.
[get-off-my-lawn] [get-off-my-lawn]
Nottingham, M., "URI Design and Ownership", Best Current Nottingham, M., "URI Design and Ownership", Best Current
Practice draft-ietf-appsawg-uri-get-off-my-lawn-05, May Practice draft-ietf-appsawg-uri-get-off-my-lawn-05, May
2014. 2014.
[rest-dissertation] [rest-dissertation]
Fielding, R., "Architectural Styles and the Design of Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000. Network-based Software Architectures", 2000.
[wd-eventsource]
Hickson, I., "Server-Sent Events", December 2012.
13.2. Informative References 13.2. Informative References
[XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Recommendation Version 1.0", World Wide Web Consortium Recommendation
REC-xpath-19991116, November 1999, REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
Appendix A. Change Log Appendix A. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
A.1. 01 - 02 A.1. 02 - 03
o added collection resource
o added "page" query parameter capability
o added "limit" and "offset" query parameters, which are available
if the "page" capability is supported
o added "stream list" term
o fixed bugs in some examples
o added "encoding" list within the "stream" list to allow different
<events> URLs for XML and JSON encoding.
o made XML MUST implement and JSON MAY implement for servers
o re-add JSON notification examples (previously removed)
o updated JSON references
A.2. 01 - 02
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 72, line 24 skipping to change at page 75, 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.2. 00 - 01 A.3. 00 - 01
o fixed content=nonconfig example (non-config was incorrect) o fixed content=nonconfig example (non-config was incorrect)
o closed open issue 'message-id'. There is no need for a message-id o closed open issue 'message-id'. There is no need for a message-id
field, and RFC 2392 does not apply. field, and RFC 2392 does not apply.
o closed open issue 'server support verification'. The headers used o closed open issue 'server support verification'. The headers used
by RESTCONF are widely supported. by RESTCONF are widely supported.
o removed encoding rules from section on RESTCONF Meta-Data. This o removed encoding rules from section on RESTCONF Meta-Data. This
is now defined in [I-D.lhotka-netmod-json]. is now defined in "I-D.lhotka-netmod-json".
o added media type application/yang.errors to map to errors YANG o added media type application/yang.errors to map to errors YANG
grouping. Updated error examples to use new media type. grouping. Updated error examples to use new media type.
o closed open issue 'additional datastores'. Support may be added o closed open issue 'additional datastores'. Support may be added
in the future to identify new datastores. in the future to identify new datastores.
o closed open issue 'PATCH media type discovery'. The section on o closed open issue 'PATCH media type discovery'. The section on
PATCH has an added sentence on the Accept-Patch header. PATCH has an added sentence on the Accept-Patch header.
skipping to change at page 73, line 22 skipping to change at page 76, line 5
the RESTCONF API using the /.well-known/host-meta. the RESTCONF API using the /.well-known/host-meta.
o added an "error" media type to for structured error messages o added an "error" media type to for structured error messages
o added Secure Transport section requiring TLS o added Secure Transport section requiring TLS
o added Security Considerations section o added Security Considerations section
o removed all references to "REST-like" o removed all references to "REST-like"
A.3. bierman:restconf-04 to ietf:restconf-00 A.4. 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 81, line 16 skipping to change at page 83, line 32
<operations> <operations>
<play xmlns="http://example.com/ns/example-jukebox"/> <play xmlns="http://example.com/ns/example-jukebox"/>
</operations> </operations>
</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/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,
application/yang.errors+json application/yang.errors+json
The server might respond as follows. The server might respond as follows.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
skipping to change at page 82, line 35 skipping to change at page 85, line 5
] ]
} }
} }
D.1.3. Retrieve The Server Capability Information D.1.3. Retrieve The Server Capability Information
In this example the client is retrieving the capability information In this example the client is retrieving the capability information
from the server in JSON format, and the server supports all the from the server in JSON format, and the server supports all the
RESTCONF query parameters, plus one vendor parameter: RESTCONF query parameters, plus one vendor parameter:
GET /restconf/data/restconf-state/capabilities HTTP/1.1 GET /restconf/data/ietf-restconf-monitoring:restconf-state/
capabilities HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+json, Accept: application/yang.data+json,
application/yang.errors+json application/yang.errors+json
The server might respond as follows. The server might respond as follows.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:02:00 GMT Date: Mon, 23 Apr 2012 17:02:00 GMT
Server: example-server Server: example-server
Cache-Control: no-cache Cache-Control: no-cache
skipping to change at page 89, line 47 skipping to change at page 91, line 47
] ]
}, },
"playlist" : [ "playlist" : [
{ {
"name" : "Foo-One", "name" : "Foo-One",
"description" : "example playlist 1", "description" : "example playlist 1",
"song" : [ "song" : [
{ {
"index" : 1, "index" : 1,
"id" : "http://example.com/restconf/data/ "id" : "http://example.com/restconf/data/
example-jukebox:jukebox/library/artist/ example-jukebox:jukebox/library/artist=
Foo%20Fighters/album/Wasting%20Light/ Foo%20Fighters/album/Wasting%20Light/
song/Rope" song/Rope"
}, },
{ {
"index" : 2, "index" : 2,
"id" : "http://example.com/restconf/data/ "id" : "http://example.com/restconf/data/
example-jukebox:jukebox/library/artist/ example-jukebox:jukebox/library/artist=
Foo%20Fighters/album/Wasting%20Light/song/ Foo%20Fighters/album/Wasting%20Light/song/
Bridge%20Burning" Bridge%20Burning"
} }
] ]
} }
], ],
"player" : { "player" : {
"gap" : 0.5 "gap" : 0.5
} }
} }
skipping to change at page 92, line 19 skipping to change at page 94, line 19
{ {
"ietf-yang-library:modules": { "ietf-yang-library:modules": {
"module": [ "module": [
{ {
"name" : "example-jukebox", "name" : "example-jukebox",
"revision" : "2014-07-03" "revision" : "2014-07-03"
}, },
{ {
"name" : "ietf-restconf-monitoring", "name" : "ietf-restconf-monitoring",
"revision" : "2014-10-07" "revision" : "2014-10-25"
}, },
{ {
"name" : "ietf-yang-library", "name" : "ietf-yang-library",
"revision" : "2014-10-07" "revision" : "2014-10-25"
} }
] ]
} }
} }
D.3.4. "insert" Parameter D.3.4. "insert" Parameter
In this example, a new first entry in the "Foo-One" playlist is being In this example, a new first entry in the "Foo-One" playlist is being
created. created.
Request from client: Request from client:
POST /restconf/data/example-jukebox:jukebox/ POST /restconf/data/example-jukebox:jukebox/
playlist=Foo-One?insert=first HTTP/1.1 playlist=Foo-One?insert=first HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang.data+json Content-Type: application/yang.data+json
{ {
"example-jukebox:song" : { "example-jukebox:song" : {
"index" : 1, "index" : 1,
"id" : "/example-jukebox:jukebox/library/artist/ "id" : "/example-jukebox:jukebox/library/
Foo%20Fighters/album/Wasting%20Light/song/Rope" artist=Foo%20Fighters/album/Wasting%20Light/song/Rope"
} }
} }
Response from server: Response from server:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Date: Mon, 23 Apr 2012 13:01:20 GMT Date: Mon, 23 Apr 2012 13:01:20 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
Location: http://example.com/restconf/data/ Location: http://example.com/restconf/data/
example-jukebox:jukebox/playlist=Foo-One/song=1 example-jukebox:jukebox/playlist=Foo-One/song=1
ETag: eeeada438af ETag: eeeada438af
D.3.5. "point" Parameter D.3.5. "point" Parameter
Example:
In this example, the client is inserting a new "song" resource within In this example, the client is inserting a new "song" resource within
an "album" resource after another song. The request URI is split for an "album" resource after another song. The request URI is split for
display purposes only. display purposes only.
Request from client: Request from client:
POST /restconf/data/example-jukebox:jukebox/ POST /restconf/data/example-jukebox:jukebox/
library/artist/Foo%20Fighters/album/Wasting%20Light? library/artist=Foo%20Fighters/album/Wasting%20Light?
insert=after&point=%2Fexample-jukebox%3Ajukebox%2F insert=after&point=%2Fexample-jukebox%3Ajukebox%2F
library%2Fartist%2FFoo%20Fighters%2Falbum%2F library%2Fartist%2FFoo%20Fighters%2Falbum%2F
Wasting%20Light%2Fsong%2FBridge%20Burning HTTP/1.1 Wasting%20Light%2Fsong%2FBridge%20Burning 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" : {
"name" : "Rope", "name" : "Rope",
"location" : "/media/foo/a7/rope.mp3", "location" : "/media/foo/a7/rope.mp3",
"format" : "MP3", "format" : "MP3",
"length" : 259 "length" : 259
} }
} }
Response from server: Response from server:
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Date: Mon, 23 Apr 2012 13:01:20 GMT Date: Mon, 23 Apr 2012 13:01:20 GMT
Server: example-server Server: example-server
Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT
ETag: abcada438af ETag: abcada438af
D.3.6. "filter" Parameter D.3.6. "limit" Parameter
In this example, the client requests the first two "album" resources
for a given artist:
Request from client:
GET /restconf/data/example-jukebox:jukebox/
library/artist=Foo%20Fighters/album/?limit=2 HTTP/1.1
Host: example.com
Content-Type: application/yang.collection+xml
Response from server:
HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/yang.collection+xml
<collection xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"
<album xmlns="http://example.com/ns/example-jukebox">
<name>Foo Fighters</name>
<year>1995</year>
...
</album>
<album xmlns="http://example.com/ns/example-jukebox">
<name>The Color and the Shape</name>
<year>1997</year>
...
</album>
</collection>
D.3.7. "offset" Parameter
In this example, the client requests the next two albums, i.e., two
albums starting from two.
Request from client:
GET /restconf/data/example-jukebox:jukebox/
library/artist=Foo%20Fighters/album/?limit=2&offset=2 HTTP/1.1
Host: example.com
Content-Type: application/yang.collection+json
Response from server:
HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:02:00 GMT
Server: example-server
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/yang.collection+json
{
"collection": {
"example-jukebox:album" : [
{
"year" : 1999,
"name" : "There is Nothing Left to Loose",
...
},
{
"year" : 2002,
"name" : "One by One",
...
}
]
}
}
D.3.8. "filter" Parameter
The following URIs show some examples of notification filter The following URIs show some examples of notification filter
specifications (lines wrapped for display purposes only): specifications (lines wrapped for display purposes only):
// filter = /event/eventClass='fault' // filter = /event/event-class='fault'
GET /mystreams/stream=NETCONF/events? GET /mystreams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault'
filter=%2Fevent%2FeventClass%3D'fault'
// filter = /event/severityCode<=4 // filter = /event/severity<=4
GET /mystreams/stream=NETCONF/events? GET /mystreams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4
filter=%2Fevent%2FseverityCode%3C%3D4
// filter = /linkUp|/linkDown // filter = /linkUp|/linkDown
GET /mystreams/stream=SNMP/events? GET /mystreams/SNMP?filter=%2FlinkUp%7C%2FlinkDown
filter=%2FlinkUp%7C%2FlinkDown
// filter = /*/reportingEntity/card!='Ethernet0' // filter = /*/reporting-entity/card!='Ethernet0'
GET /mystreams/stream=NETCONF/events? GET /mystreams/NETCONF?
filter=%2F*%2FreportingEntity%2Fcard%21%3D'Ethernet0' filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0'
// filter = /*/email-addr[contains(.,'company.com')] // filter = /*/email-addr[contains(.,'company.com')]
GET /mystreams/stream=critical-syslog/events? GET /mystreams/critical-syslog?
filter=%2F*%2Femail-addr[contains(.%2C'company.com')] filter=%2F*%2Femail-addr[contains(.%2C'company.com')]
// Note: the module name is used as prefix. // Note: the module name is used as prefix.
// filter = (/example-mod:event1/name='joe' and // filter = (/example-mod:event1/name='joe' and
// /example-mod:event1/status='online') // /example-mod:event1/status='online')
GET /mystreams/stream=NETCONF/events? GET /mystreams/NETCONF?
filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and
%20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online')
D.3.7. "start-time" Parameter D.3.9. "start-time" Parameter
TBD // start-time = 2014-10-25T10:02:00Z
GET /mystreams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z
D.3.8. "stop-time" Parameter D.3.10. "stop-time" Parameter
TBD // stop-time = 2014-10-25T12:31:00Z
GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z
Authors' Addresses Authors' Addresses
Andy Bierman Andy Bierman
YumaWorks YumaWorks
Email: andy@yumaworks.com Email: andy@yumaworks.com
Martin Bjorklund Martin Bjorklund
Tail-f Systems Tail-f Systems
 End of changes. 116 change blocks. 
244 lines changed or deleted 487 lines changed or added

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