idnits 2.17.1 draft-ietf-netconf-restconf-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1963 has weird spacing: '... method entry...' == Line 2907 has weird spacing: '...ncoding strin...' == Line 2908 has weird spacing: '...ocation inet:...' == Line 3813 has weird spacing: '...ocation str...' == Line 3823 has weird spacing: '...w index uin...' == (1 more instance...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (October 18, 2015) is 3084 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-06) exists of draft-ietf-netconf-yang-library-01 == Outdated reference: A later version (-14) exists of draft-ietf-netmod-rfc6020bis-07 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-yang-json-06 == Outdated reference: A later version (-07) exists of draft-ietf-netmod-yang-metadata-02 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) ** Obsolete normative reference: RFC 7158 (Obsoleted by RFC 7159) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7320 (Obsoleted by RFC 8820) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPath' == Outdated reference: A later version (-14) exists of draft-ietf-netconf-yang-patch-06 Summary: 11 errors (**), 0 flaws (~~), 13 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track M. Bjorklund 5 Expires: April 20, 2016 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 October 18, 2015 10 RESTCONF Protocol 11 draft-ietf-netconf-restconf-08 13 Abstract 15 This document describes an HTTP-based protocol that provides a 16 programmatic interface for accessing data defined in YANG, using the 17 datastores defined in NETCONF. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on April 20, 2016. 36 Copyright Notice 38 Copyright (c) 2015 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 54 1.1. Simple Subset of NETCONF Functionality . . . . . . . . . 5 55 1.2. Data Model Driven API . . . . . . . . . . . . . . . . . . 6 56 1.3. Coexistence with NETCONF . . . . . . . . . . . . . . . . 7 57 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 58 1.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 8 59 1.4.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 8 60 1.4.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 9 61 1.4.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 10 62 1.4.5. URI Template . . . . . . . . . . . . . . . . . . . . 11 63 1.4.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 11 64 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 12 65 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 12 66 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 12 67 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 12 68 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 13 69 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 13 70 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 13 71 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 14 72 3.2. RESTCONF Resource Types . . . . . . . . . . . . . . . . . 15 73 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 16 74 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 16 75 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 17 76 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 17 77 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 18 78 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 18 79 3.5.1. Encoding Data Resource Identifiers in the Request URI 19 80 3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 22 81 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 22 82 3.6.1. Encoding Operation Input Parameters . . . . . . . . . 23 83 3.6.2. Encoding Operation Output Parameters . . . . . . . . 24 84 3.6.3. Encoding Operation Errors . . . . . . . . . . . . . . 25 85 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 26 86 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 27 87 3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 27 88 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 27 89 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 28 90 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 28 91 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 92 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 30 93 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 30 94 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 31 95 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 96 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 33 97 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 33 98 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 34 99 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 35 100 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 36 101 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 36 102 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 37 103 4.8.4. The "insert" Query Parameter . . . . . . . . . . . . 38 104 4.8.5. The "point" Query Parameter . . . . . . . . . . . . . 38 105 4.8.6. The "filter" Query Parameter . . . . . . . . . . . . 39 106 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 39 107 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 40 108 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 41 109 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 42 110 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 42 111 5.2. Message Headers . . . . . . . . . . . . . . . . . . . . . 43 112 5.3. Message Encoding . . . . . . . . . . . . . . . . . . . . 44 113 5.4. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 44 114 5.4.1. XML MetaData Encoding Example . . . . . . . . . . . . 45 115 5.4.2. JSON MetaData Encoding Example . . . . . . . . . . . 45 116 5.5. Return Status . . . . . . . . . . . . . . . . . . . . . . 46 117 5.6. Message Caching . . . . . . . . . . . . . . . . . . . . . 46 118 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 47 119 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 47 120 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 47 121 6.3. Subscribing to Receive Notifications . . . . . . . . . . 48 122 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 50 123 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 50 124 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 52 125 7.1. Error Response Message . . . . . . . . . . . . . . . . . 54 126 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 56 127 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 62 128 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 62 129 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 63 130 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 63 131 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 64 132 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 64 133 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 68 134 10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 68 135 10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 69 136 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 137 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 69 138 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 69 139 11.3. application/yang Media Sub Types . . . . . . . . . . . . 70 140 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 71 141 12. Security Considerations . . . . . . . . . . . . . . . . . . . 71 142 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 72 143 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 144 14.1. Normative References . . . . . . . . . . . . . . . . . . 73 145 14.2. Informative References . . . . . . . . . . . . . . . . . 76 146 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 76 147 A.1. 07 - 08 . . . . . . . . . . . . . . . . . . . . . . . . . 76 148 A.2. 06 - 07 . . . . . . . . . . . . . . . . . . . . . . . . . 76 149 A.3. 05 - 06 . . . . . . . . . . . . . . . . . . . . . . . . . 77 150 A.4. 04 - 05 . . . . . . . . . . . . . . . . . . . . . . . . . 77 151 A.5. 03 - 04 . . . . . . . . . . . . . . . . . . . . . . . . . 78 152 A.6. 02 - 03 . . . . . . . . . . . . . . . . . . . . . . . . . 78 153 A.7. 01 - 02 . . . . . . . . . . . . . . . . . . . . . . . . . 79 154 A.8. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 80 155 A.9. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 80 156 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 81 157 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 81 158 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 82 159 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 87 160 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 87 161 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 87 162 D.1.2. Retrieve The Server Module Information . . . . . . . 88 163 D.1.3. Retrieve The Server Capability Information . . . . . 89 164 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 90 165 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 90 166 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 91 167 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 92 168 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 93 169 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 93 170 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 96 171 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 99 172 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 100 173 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 100 174 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 101 175 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 102 176 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 102 177 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 102 178 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 103 180 1. Introduction 182 There is a need for standard mechanisms to allow Web applications to 183 access the configuration data, operational data, data-model specific 184 protocol operations, and event notifications within a networking 185 device, in a modular and extensible manner. 187 This document describes an HTTP [RFC7230] based protocol called 188 RESTCONF, for accessing data defined in YANG version 1 [RFC6020] or 189 YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using datastores 190 defined in NETCONF [RFC6241]. 192 The NETCONF protocol defines configuration datastores and a set of 193 Create, Retrieve, Update, Delete (CRUD) operations that can be used 194 to access these datastores. The YANG language defines the syntax and 195 semantics of datastore content, operational data, protocol 196 operations, and event notifications. RESTCONF uses HTTP operations 197 to provide CRUD operations on a NETCONF datastore containing YANG- 198 defined data. Since NETCONF protocol operations are not relevant, 199 the user should not need any prior knowledge of NETCONF in order to 200 use RESTCONF. 202 Configuration data and state data are exposed as resources that can 203 be retrieved with the GET method. Resources representing 204 configuration data can be modified with the DELETE, PATCH, POST, and 205 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 206 or JSON [RFC7158]. 208 Data-model specific protocol operations defined with the YANG "rpc" 209 or "action" statements can be invoked with the POST method. Data- 210 model specific event notifications defined with the YANG 211 "notification" statement can be accessed. 213 1.1. Simple Subset of NETCONF Functionality 215 An HTTP-based management protocol does not need to mirror the 216 functionality of the NETCONF protocol, but it needs to be compatible 217 with NETCONF. A simplified transaction model is needed that allows 218 basic CRUD operations on a hierarchy of conceptual resources. This 219 represents a limited subset of the transaction capabilities of the 220 NETCONF protocol. 222 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 223 resources represented by YANG data models. These basic edit 224 operations allow the running configuration to be altered in an all- 225 or-none fashion. This is similar to the "rollback-on-error" 226 capability in NETCONF. Edits are usually applied to one data 227 resource instance at a time. 229 The base RESTCONF protocol is intentionally simple to allow 230 deployment for as many use cases as possible. Additional 231 functionality can be defined in external documents, outside the scope 232 of this document. 234 RESTCONF is not intended to replace NETCONF, but rather provide an 235 additional simplified interface that follows REST principles and is 236 compatible with a resource-oriented device abstraction. 238 The following figure shows the system components: 240 +-----------+ +-----------------+ 241 | Web app | <-------> | | 242 +-----------+ HTTP | network device | 243 | | 244 +-----------+ | +-----------+ | 245 | NMS app | <-------> | | datastore | | 246 +-----------+ NETCONF | +-----------+ | 247 +-----------------+ 249 1.2. Data Model Driven API 251 RESTCONF combines the simplicity of the HTTP protocol with the 252 predictability and automation potential of a schema-driven API. 253 Using YANG, a client can predict all resource endpoints, much like 254 using URI Templates [RFC6570], but in a more holistic manner. This 255 strategy obviates the need for responses provided by the server to 256 contain HATEOAS links, originally described in Roy Fielding's 257 doctoral dissertation [rest-dissertation]. 259 In contrast, a REST client using HATEOAS principles would not use any 260 data modeling language to define the application-specific content of 261 the API. The client would need to discover each new child resource 262 as it traverses the URIs to discover the server capabilities. This 263 approach has the following significant weaknesses with regards to 264 control of complex networking devices: 266 o inefficient performance: configuration APIs will be quite complex 267 and may require thousands of protocol messages to discover all the 268 schema information. Typically the data type information has to be 269 passed in the protocol messages, which is also wasteful overhead. 271 o no data model richness: without a data model, the schema-level 272 semantics and validation constraints are not available to the 273 application. 275 o no tool automation: API automation tools need some sort of content 276 schema to function. Such tools can automate various programming 277 and documentation tasks related to specific data models. 279 Data models such as YANG modules serve as an "API contract" that will 280 be honored by the server. An application designer can code to the 281 data model, knowing in advance important details about the exact 282 protocol operations and datastore content a conforming server 283 implementation will support. 285 RESTCONF provides the YANG module capability information supported by 286 the server, in case the client wants to use it. The URIs for custom 287 protocol operations and datastore content are predictable, based on 288 the YANG module definitions. 290 Operational experience with CLI and SNMP indicates that operators 291 learn the 'location' of specific service or device related data and 292 do not expect such information to be arbitrary and discovered each 293 time the client opens a management session to a server. 295 The RESTCONF protocol operates on a conceptual datastore defined with 296 the YANG data modeling language. The server lists each YANG module 297 it supports using the "ietf-yang-library" YANG module, defined in 298 [I-D.ietf-netconf-yang-library]. The server MUST implement the 299 "ietf-yang-library" module, which SHOULD identify all the YANG 300 modules used by the server. 302 The conceptual datastore contents, data-model-specific operations and 303 event notifications are identified by this set of YANG modules. All 304 RESTCONF content identified as either a data resource, operation 305 resource, or event stream resource is defined with the YANG language. 307 The classification of data as configuration or non-configuration is 308 derived from the YANG "config" statement. Data ordering behavior is 309 derived from the YANG "ordered-by" statement. 311 The RESTCONF datastore editing model is simple and direct, similar to 312 the behavior of the :writable-running capability in NETCONF. Each 313 RESTCONF edit of a datastore resource is activated upon successful 314 completion of the transaction. 316 1.3. Coexistence with NETCONF 318 RESTCONF can be implemented on a device that supports NETCONF. 320 If the device supports :writable-running, all edits to configuration 321 nodes in {+restconf}/data are performed in the running configuration 322 datastore. 324 Otherwise, if the device supports :candidate, all edits to 325 configuration nodes in {+restconf}/data are performed in the 326 candidate configuration datastore. The candidate is automatically 327 committed to running after a successful edit. 329 If the device supports :startup, the device automatically copies the 330 content of running to startup after running has been updated as a 331 consequence of a RESTCONF edit operation. 333 If a datastore that would be modified by a RESTCONF operation has an 334 active lock, the RESTCONF edit operation MUST fail with a 409 335 (Conflict) error code. 337 1.4. Terminology 339 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 340 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 341 "OPTIONAL" in this document are to be interpreted as described in BCP 342 14, [RFC2119]. 344 1.4.1. NETCONF 346 The following terms are defined in [RFC6241]: 348 o candidate configuration datastore 350 o client 352 o configuration data 354 o datastore 356 o configuration datastore 358 o protocol operation 360 o running configuration datastore 362 o server 364 o startup configuration datastore 366 o state data 368 o user 370 1.4.2. HTTP 371 The following terms are defined in [RFC3986]: 373 o fragment 375 o path 377 o query 379 The following terms are defined in [RFC7230]: 381 o header 383 o message-body 385 o request-line 387 o request URI 389 o status-line 391 The following terms are defined in [RFC7231]: 393 o method 395 o request 397 o resource 399 The following terms are defined in [RFC7232]: 401 o entity tag 403 1.4.3. YANG 405 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 407 o action 409 o container 411 o data node 413 o key leaf 415 o leaf 417 o leaf-list 418 o list 420 o non-presence container (or NP-container) 422 o ordered-by system 424 o ordered-by user 426 o presence container (or P-container) 428 o RPC operation (now called protocol operation) 430 1.4.4. Terms 432 The following terms are used within this document: 434 o API resource: a resource with the media type "application/ 435 yang.api+xml" or "application/yang.api+json". 437 o data resource: a resource with the media type "application/ 438 yang.data+xml" or "application/yang.data+json". Containers, 439 leafs, list entries, anydata and anyxml nodes can be data 440 resources. 442 o datastore resource: a resource with the media type "application/ 443 yang.datastore+xml" or "application/yang.datastore+json". 444 Represents a datastore. 446 o edit operation: a RESTCONF operation on a data resource using 447 either a POST, PUT, PATCH, or DELETE method. 449 o event stream resource: This resource represents an SSE (Server- 450 Sent Events) event stream. The content consists of text using the 451 media type "text/event-stream", as defined by the HTML5 452 specification. Each event represents one message 453 generated by the server. It contains a conceptual system or data- 454 model specific event that is delivered within an event 455 notification stream. Also called a "stream resource". 457 o media-type: HTTP uses Internet media types [RFC2046] in the 458 Content-Type and Accept header fields in order to provide open and 459 extensible data typing and type negotiation. 461 o operation: the conceptual RESTCONF operation for a message, 462 derived from the HTTP method, request URI, headers, and message- 463 body. 465 o operation resource: a resource with the media type "application/ 466 yang.operation+xml" or "application/yang.operation+json". 468 o patch: a generic PATCH request on the target datastore or data 469 resource. The media type of the message-body content will 470 identify the patch type in use. 472 o plain patch: a specific PATCH request type that can be used for 473 simple merge operations. 475 o query parameter: a parameter (and its value if any), encoded 476 within the query component of the request URI. 478 o RESTCONF capability: An optional RESTCONF protocol feature 479 supported by the server, which is identified by an IANA registered 480 NETCONF Capability URI, and advertised with an entry in the 481 "capability" leaf-list in Section 9.3. 483 o retrieval request: a request using the GET or HEAD methods. 485 o target resource: the resource that is associated with a particular 486 message, identified by the "path" component of the request URI. 488 o schema resource: a resource with the media type "application/ 489 yang". The YANG representation of the schema can be retrieved by 490 the client with the GET method. 492 o stream list: the set of data resource instances that describe the 493 event stream resources available from the server. This 494 information is defined in the "ietf-restconf-monitoring" module as 495 the "stream" list. It can be retrieved using the target resource 496 "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/ 497 stream". The stream list contains information about each stream, 498 such as the URL to retrieve the event stream data. 500 1.4.5. URI Template 502 Throughout this document, the URI template [RFC6570] syntax 503 "{+restconf}" is used to refer to the RESTCONF API entry point 504 outside of an example. See Section 3.1 for details. 506 For simplicity, all of the examples in this document assume "/ 507 restconf" as the discovered RESTCONF API root path. 509 1.4.6. Tree Diagrams 510 A simplified graphical representation of the data model is used in 511 this document. The meaning of the symbols in these diagrams is as 512 follows: 514 o Brackets "[" and "]" enclose list keys. 516 o Abbreviations before data node names: "rw" means configuration 517 data (read-write) and "ro" state data (read-only). 519 o Symbols after data node names: "?" means an optional node, "!" 520 means a presence container, and "*" denotes a list and leaf-list. 522 o Parentheses enclose choice and case nodes, and case nodes are also 523 marked with a colon (":"). 525 o Ellipsis ("...") stands for contents of subtrees that are not 526 shown. 528 2. Transport Protocol Requirements 530 2.1. Integrity and Confidentiality 532 HTTP [RFC7230] is an application layer protocol that may be layered 533 on any reliable transport-layer protocol. RESTCONF is defined on top 534 of HTTP, but due to the sensitive nature of the information conveyed, 535 RESTCONF requires that the transport-layer protocol provides both 536 data integrity and confidentiality, such as are provided by the TLS 537 protocol [RFC5246]. 539 2.2. HTTPS with X.509v3 Certificates 541 Given the nearly ubiquitous support for HTTP over TLS [RFC7230], 542 RESTCONF implementations MUST support the "https" URI scheme, which 543 has the IANA assigned default port 443. Consistent with the 544 exclusive use of X.509v3 certificates for NETCONF over TLS 545 [draft-ietf-netconf-rfc5539bis-10], use of certificates in RESTCONF 546 is also limited to X.509v3 certificates. 548 2.3. Certificate Validation 550 When presented an X.509 certificate, the RESTCONF peer MUST use X.509 551 certificate path validation [RFC5280] to verify the integrity of the 552 certificate. The presented X.509 certificate MAY also be considered 553 valid if it matches a locally configured certificate fingerprint. If 554 X.509 certificate path validation fails and the presented X.509 555 certificate does not match a locally configured certificate 556 fingerprint, the connection MUST be terminated as defined in 557 [RFC5246]. 559 2.4. Authenticated Server Identity 561 The RESTCONF client MUST carefully examine the certificate presented 562 by the RESTCONF server to determine if it meets the client's 563 expectations. The RESTCONF client MUST check the identity of the 564 server according to Section 6 of [RFC6125], including processing the 565 outcome as described in Section 6.6 of [RFC6125]. 567 2.5. Authenticated Client Identity 569 The RESTCONF server MUST authenticate client access to any protected 570 resource using HTTP Authentication [RFC7235]. If the RESTCONF client 571 is not authenticated to access a resource, the server MUST send a 572 response with status code 401 (Unauthorized) and a WWW-Authenticate 573 header field containing at least one challenge applicable to the 574 target resource. The RESTCONF server MAY advertise support for any 575 number of authentication schemes but, in order to ensure 576 interoperability, the RESTCONF server MUST advertise at least one of 577 the following authentication schemes: 579 o Basic [draft-ietf-httpauth-basicauth-update-03] 581 o Digest [draft-ietf-httpauth-digest-09] 583 o ClientCertificate [draft-thomson-httpbis-cant-01] 585 These authentication schemes are selected for their similarity to the 586 authentication schemes supported by NETCONF. In particular, the 587 Basic and Digest authentication schemes both directly provide an 588 identity and verification of a shared secret, much like NETCONF over 589 SSH, when using the SSH "password" authentication method [RFC4252]. 590 Similarly, the ClientCertificate authentication scheme is much like 591 NETCONF over TLS's use of X.509 client-certificates. When using the 592 ClientCertificate authentication scheme, the RESTCONF server MUST 593 derive the identity of the RESTCONF client using the algorithm 594 defined in Section 7 of [draft-ietf-netconf-rfc5539bis-10]. 596 The RESTCONF client identity determined from any HTTP authentication 597 scheme is hereafter known as the "RESTCONF username" and subject to 598 the NETCONF Access Control Module (NACM) [RFC6536]. 600 3. Resources 602 The RESTCONF protocol operates on a hierarchy of resources, starting 603 with the top-level API resource itself (Section 3.1). Each resource 604 represents a manageable component within the device. 606 A resource can be considered a collection of conceptual data and the 607 set of allowed methods on that data. It can contain nested child 608 resources. The child resource types and methods allowed on them are 609 data-model specific. 611 A resource has its own media type identifier, represented by the 612 "Content-Type" header in the HTTP response message. A resource can 613 contain zero or more nested resources. A resource can be created and 614 deleted independently of its parent resource, as long as the parent 615 resource exists. 617 All RESTCONF resources are defined in this document except specific 618 datastore contents, protocol operations, and event notifications. 619 The syntax and semantics for these resource types are defined in YANG 620 modules. 622 The RESTCONF resources are accessed via a set of URIs defined in this 623 document. The set of YANG modules supported by the server will 624 determine the data model specific operations, top-level data node 625 resources, and event notification messages supported by the server. 627 The RESTCONF protocol does not include a resource discovery 628 mechanism. Instead, the definitions within the YANG modules 629 advertised by the server are used to construct a predictable 630 operation or data resource identifier. 632 3.1. Root Resource Discovery 634 In line with the best practices defined by [RFC7320], RESTCONF 635 enables deployments to specify where the RESTCONF API is located. 636 When first connecting to a RESTCONF server, a RESTCONF client MUST 637 determine the root of the RESTCONF API. The client discovers this by 638 getting the "/.well-known/host-meta" resource ([RFC6415]) and using 639 the element containing the "restconf" attribute : 641 Request 642 ------- 643 GET /.well-known/host-meta users HTTP/1.1 644 Host: example.com 645 Accept: application/xrd+xml 647 Response 648 -------- 649 HTTP/1.1 200 OK 650 Content-Type: application/xrd+xml 651 Content-Length: nnn 653 654 655 657 Once discovering the RESTCONF API root, the client MUST prepend it to 658 any subsequent request to a RESTCONF resource. For instance, using 659 the "/restconf" path discovered above, the client can now determine 660 the operations supported by the the server. In this example a custom 661 "play" operation is supported: 663 Request 664 ------- 665 GET /restconf/operations HTTP/1.1 666 Host: example.com 667 Accept: application/yang.api+json 669 Response 670 -------- 671 HTTP/1.1 200 OK 672 Date: Mon, 23 Apr 2012 17:01:00 GMT 673 Server: example-server 674 Cache-Control: no-cache 675 Pragma: no-cache 676 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 677 Content-Type: application/yang.api+json 679 { "operations" : { "example-jukebox:play" : [ null ] } } 681 3.2. RESTCONF Resource Types 683 The RESTCONF protocol defines a set of application specific media 684 types to identify each of the available resource types. The 685 following resource types are defined in RESTCONF: 687 +-----------+---------------------------------+ 688 | Resource | Media Type | 689 +-----------+---------------------------------+ 690 | API | application/yang.api+xml | 691 | | application/yang.api+json | 692 | Datastore | application/yang.datastore+xml | 693 | | application/yang.datastore+json | 694 | Data | application/yang.data+xml | 695 | | application/yang.data+json | 696 | Errors | application/yang.errors+xml | 697 | | application/yang.errors+json | 698 | Operation | application/yang.operation+xml | 699 | | application/yang.operation+json | 700 | Schema | application/yang | 701 +-----------+---------------------------------+ 703 RESTCONF Media Types 705 3.3. API Resource 707 The API resource contains the entry points for the RESTCONF datastore 708 and operation resources. It is the top-level resource located at 709 {+restconf} and has the media type "application/yang.api+xml" or 710 "application/yang.api+json". 712 YANG Tree Diagram for an API Resource: 714 +--rw restconf 715 +--rw data 716 +--rw operations 718 The "application/yang.api" restconf-media-type extension in the 719 "ietf-restconf" module defined in Section 8 is used to specify the 720 structure and syntax of the conceptual child resources within the API 721 resource. 723 The API resource can be retrieved with the GET method. 725 This resource has the following child resources: 727 +----------------+--------------------------------+ 728 | Child Resource | Description | 729 +----------------+--------------------------------+ 730 | data | Contains all data resources | 731 | operations | Data-model specific operations | 732 +----------------+--------------------------------+ 734 RESTCONF API Resource 736 3.3.1. {+restconf}/data 738 This mandatory resource represents the combined configuration and 739 operational data resources that can be accessed by a client. It 740 cannot be created or deleted by the client. The datastore resource 741 type is defined in Section 3.4. 743 Example: 745 This example request by the client would retrieve only the non- 746 configuration data nodes that exist within the "library" resource, 747 using the "content" query parameter (see Section 4.8.1). 749 GET /restconf/data/example-jukebox:jukebox/library 750 ?content=nonconfig HTTP/1.1 751 Host: example.com 752 Accept: application/yang.data+xml 754 The server might respond: 756 HTTP/1.1 200 OK 757 Date: Mon, 23 Apr 2012 17:01:30 GMT 758 Server: example-server 759 Cache-Control: no-cache 760 Pragma: no-cache 761 Content-Type: application/yang.data+xml 763 764 42 765 59 766 374 767 769 3.3.2. {+restconf}/operations 771 This optional resource is a container that provides access to the 772 data-model specific protocol operations supported by the server. The 773 server MAY omit this resource if no data-model specific operations 774 are advertised. 776 Any data-model specific protocol operations defined in the YANG 777 modules advertised by the server MAY be available as child nodes of 778 this resource. 780 Operation resources are defined in Section 3.6. 782 3.4. Datastore Resource 784 The "{+restconf}/data" subtree represents the datastore resource 785 type, which is a collection of configuration and operational data 786 nodes. 788 This resource type is an abstraction of the system's underlying 789 datastore implementation. It is used to simplify resource editing 790 for the client. The RESTCONF datastore resource is a conceptual 791 collection of all configuration and operational data that is present 792 on the device. 794 Configuration edit transaction management and configuration 795 persistence are handled by the server and not controlled by the 796 client. A datastore resource can only be written directly with the 797 PATCH method. Each RESTCONF edit of a datastore resource is saved to 798 non-volatile storage by the server. 800 3.4.1. Edit Collision Detection 802 Two "edit collision detection" mechanisms are provided in RESTCONF, 803 for datastore and data resources. 805 3.4.1.1. Timestamp 807 The last change time is maintained and the "Last-Modified" 808 ([RFC7232], Section 2.2) header is returned in the response for a 809 retrieval request. The "If-Unmodified-Since" header can be used in 810 edit operation requests to cause the server to reject the request if 811 the resource has been modified since the specified timestamp. 813 The server MUST maintain a last-modified timestamp for the top-level 814 {+restconf}/data resource and SHOULD maintain last-modified 815 timestamps for descendant resources. For all resources, the server 816 MUST return the "Last-Modified" header when the resource is retrieved 817 with the GET or HEAD methods. If the server does not maintain a 818 timestamp for a resource, it MUST return the timestamp of the 819 resource's ancestor, a process that may recurse up to the top-level 820 {+restconf}/data resource. Only changes to configuration data 821 resources within the datastore affect the timestamp. 823 3.4.1.2. Entity tag 825 A unique opaque string is maintained and the "ETag" ([RFC7232], 826 Section 2.3) header is returned in the response for a retrieval 827 request. The "If-Match" header can be used in edit operation 828 requests to cause the server to reject the request if the resource 829 entity tag does not match the specified value. 831 The server MUST maintain an entity tag for the top-level {+restconf}/ 832 data resource and SHOULD maintain entity tags for descendant 833 resources. For all resources, the server MUST return the "ETag" 834 header when the resource is retrieved with the GET or HEAD methods. 835 If the server does not maintain an entity tag for a resource, it MUST 836 return the entity tag of the resource's ancestor, a process that may 837 recurse up to the top-level {+restconf}/data resource. Only changes 838 to configuration data resources within the datastore affect the 839 entity tag. 841 3.5. Data Resource 843 A data resource represents a YANG data node that is a descendant node 844 of a datastore resource. Each YANG-defined data node can be uniquely 845 targeted by the request-line of an HTTP operation. Containers, 846 leafs, list entries, anydata and anyxml nodes are data resources. 848 The representation maintained for each data resource is the YANG 849 defined subtree for that node. HTTP operations on a data resource 850 affect both the targeted data node and all its descendants, if any. 852 For configuration data resources, the server MAY maintain a last- 853 modified timestamp for the resource, and return the "Last-Modified" 854 header when it is retrieved with the GET or HEAD methods. If 855 maintained, the resource timestamp MUST be set to the current time 856 whenever the resource or any configuration resource within the 857 resource is altered. 859 For configuration data resources, the server MAY maintain a resource 860 entity tag for the resource, and return the "ETag" header when it is 861 retrieved as the target resource with the GET or HEAD methods. If 862 maintained, the resource entity tag MUST be updated whenever the 863 resource or any configuration resource within the resource is 864 altered. 866 A data resource can be retrieved with the GET method. Data resources 867 are accessed via the "{+restconf}/data" entry point. This sub-tree 868 is used to retrieve and edit data resources. 870 A configuration data resource can be altered by the client with some 871 or all of the edit operations, depending on the target resource and 872 the specific operation. Refer to Section 4 for more details on edit 873 operations. 875 The resource definition version for a data resource is identified by 876 the revision date of the YANG module containing the YANG definition 877 for the data resource. 879 3.5.1. Encoding Data Resource Identifiers in the Request URI 881 In YANG, data nodes are named with an absolute XPath expression, 882 defined in [XPath], starting from the document root to the target 883 resource. In RESTCONF, URL encoded path expressions are used 884 instead. 886 A predictable location for a data resource is important, since 887 applications will code to the YANG data model module, which uses 888 static naming and defines an absolute path location for all data 889 nodes. 891 A RESTCONF data resource identifier is not an XPath expression. It 892 is encoded from left to right, starting with the top-level data node, 893 according to the "api-path" rule in Section 3.5.1.1. The node name 894 of each ancestor of the target resource node is encoded in order, 895 ending with the node name for the target resource. If a node in the 896 path is defined in another module than its parent node, then module 897 name followed by a colon character (":") is prepended to the node 898 name in the resource identifier. See Section 3.5.1.1 for details. 900 If a data node in the path expression is a YANG list node, then the 901 key values for the list (if any) MUST be encoded according to the 902 following rules: 904 o The key leaf values for a data resource representing a YANG list 905 MUST be encoded using one path segment [RFC3986]. 907 o If there is only one key leaf value, the path segment is 908 constructed by having the list name followed by an "=" followed by 909 the single key leaf value. 911 o If there are multiple key leaf values, the value of each leaf 912 identified in the "key" statement is encoded in the order 913 specified in the YANG "key" statement, with a comma separating 914 them. 916 o The key value is specified as a string, using the canonical 917 representation for the YANG data type. Any reserved characters 918 MUST be percent-encoded, according to [RFC3986], section 2.1. 920 o All the components in the "key" statement MUST be encoded. 921 Partial instance identifiers are not supported. 923 o Quoted strings are not allowed in the key leaf values. A missing 924 key value is interpreted a zero-length string. (example: 925 list=foo,,baz). 927 o The "list-instance" ABNF rule defined in Section 3.5.1.1 928 represents the syntax of a list instance identifier. 930 o Resource URI values returned in Location headers for data 931 resources MUST identify the module name, even if there are no 932 conflicting local names when the resource is created. This 933 ensures the correct resource will be identified even if the server 934 loads a new module that the old client does not know about. 936 Examples: 938 container top { 939 list list1 { 940 key "key1 key2 key3"; 941 ... 942 list list2 { 943 key "key4 key5"; 944 ... 945 leaf X { type string; } 946 } 947 } 948 } 950 For the above YANG definition, URI with key leaf values will be 951 encoded as follows (line wrapped for display purposes only): 953 /restconf/data/example-top:top/list1=key1val,key2val,key3val3/ 954 list2=key4val,key5val/X 956 The following example shows how reserved characters are percent- 957 encoded within a key value. The value of 'key1' contains a comma, 958 single-quote, double-quote, colon, space, and forward slash. (,'": / 959 ). Note that the angle brackets ('<', '>'), and double-quote ('"') 960 are not reserved characters and do not need to be percent-encoded. 962 Example URL: 964 /restconf/data/example-top:top/list2=key1/X 966 /restconf/data/example-top:top/list2=%2C%27"%3A%20%2F/X 968 3.5.1.1. ABNF For Data Resource Identifiers 970 The "api-path" ABNF syntax is used to construct RESTCONF path 971 identifiers: 973 api-path = "/" | 974 ("/" api-identifier 975 0*("/" (api-identifier | list-instance ))) 977 api-identifier = [module-name ":"] identifier ;; note 1 979 module-name = identifier 981 list-instance = api-identifier "=" key-value ["," key-value]* 983 key-value = string ;; note 1 985 string = 987 ;; An identifier MUST NOT start with 988 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 989 identifier = (ALPHA / "_") 990 *(ALPHA / DIGIT / "_" / "-" / ".") 992 Note 1: The syntax for "api-identifier" and "key-value" MUST conform 993 to the JSON identifier encoding rules in Section 4 of 994 [I-D.ietf-netmod-yang-json]. 996 3.5.2. Defaults Handling 998 RESTCONF requires that a server report its default handling mode (see 999 Section 9.1.2 for details). If the optional "with-defaults" query 1000 parameter is supported by the server, a client may use it to control 1001 retrieval of default values (see Section 4.8.9 for details). 1003 If the target of a GET method is a data node that represents a leaf 1004 that has a default value, and the leaf has not been given a value 1005 yet, the server MUST return the default value that is in use by the 1006 server. 1008 If the target of a GET method is a data node that represents a 1009 container or list that has any child resources with default values, 1010 for the child resources that have not been given value yet, the 1011 server MAY return the default values that are in use by the server, 1012 in accordance with its reported default handing mode and query 1013 parameters passed by the client. 1015 3.6. Operation Resource 1017 An operation resource represents a protocol operation defined with 1018 one of the YANG "action" or "rpc" statements. It is invoked using a 1019 POST method on the operation resource. 1021 An RPC operation is invoked as: 1023 POST {+restconf}/operations/ 1025 The field identifies the module name and rpc identifier 1026 string for the desired operation. 1028 For example, if "module-A" defined a "reset" rpc operation, then 1029 invoking the operation from "module-A" would be requested as follows: 1031 POST /restconf/operations/module-A:reset HTTP/1.1 1032 Server example.com 1034 An action is invoked as: 1036 POST {+restconf}/data// 1037 where contains the path to the data node 1038 where the action is defined, and is the name of the 1039 action. 1041 For example, if "module-A" defined a "reset-all" action in the 1042 container "interfaces", then invoking this action would be requested 1043 as follows: 1045 POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 1046 Server example.com 1048 If the "action" or "rpc" statement has an "input" section, then a 1049 message-body MAY be sent by the client in the request, otherwise the 1050 request message MUST NOT include a message-body. 1052 If the operation is successfully invoked, and if the "action" or 1053 "rpc" statement has an "output" section, then a message-body MAY be 1054 sent by the server in the response, otherwise the response message 1055 MUST NOT include a message-body in the response message, and MUST 1056 send a "204 No Content" status-line instead. 1058 If the operation is not successfully invoked, then a message-body 1059 SHOULD be sent by the server, containing an "errors" resource, as 1060 defined in Section 3.9. 1062 3.6.1. Encoding Operation Input Parameters 1064 If the "action" or "rpc" statement has an "input" section, then the 1065 "input" node is provided in the message-body, corresponding to the 1066 YANG data definition statements within the "input" section. 1068 Example: 1070 The following YANG definition is used for the examples in this 1071 section. 1073 module example-ops { 1074 namespace "https://example.com/ns/example-ops"; 1075 prefix "ops"; 1077 rpc reboot { 1078 input { 1079 leaf delay { 1080 units seconds; 1081 type uint32; 1082 default 0; 1083 } 1084 leaf message { type string; } 1085 leaf language { type string; } 1086 } 1087 } 1089 rpc get-reboot-info { 1090 output { 1091 leaf reboot-time { 1092 units seconds; 1093 type uint32; 1094 } 1095 leaf message { type string; } 1096 leaf language { type string; } 1097 } 1098 } 1099 } 1101 The client might send the following POST request message: 1103 POST /restconf/operations/example-ops:reboot HTTP/1.1 1104 Host: example.com 1105 Content-Type: application/yang.operation+xml 1107 1108 600 1109 Going down for system maintenance 1110 en-US 1111 1113 The server might respond: 1115 HTTP/1.1 204 No Content 1116 Date: Mon, 25 Apr 2012 11:01:00 GMT 1117 Server: example-server 1119 3.6.2. Encoding Operation Output Parameters 1121 If the "action" or "rpc" statement has an "output" section, then the 1122 "output" node is provided in the message-body, corresponding to the 1123 YANG data definition statements within the "output" section. 1125 Example: 1127 The "example-ops" YANG module defined in Section 3.6.1 is used for 1128 the examples in this section. 1130 The client might send the following POST request message: 1132 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 1133 Host: example.com 1134 Accept: application/yang.operation+json 1136 The server might respond: 1138 HTTP/1.1 200 OK 1139 Date: Mon, 25 Apr 2012 11:10:30 GMT 1140 Server: example-server 1141 Content-Type: application/yang.operation+json 1143 { 1144 "example-ops:output" : { 1145 "reboot-time" : 30, 1146 "message" : "Going down for system maintenance", 1147 "language" : "en-US" 1148 } 1149 } 1151 3.6.3. Encoding Operation Errors 1153 If any errors occur while attempting to invoke the operation, then an 1154 "errors" data structure is returned with the appropriate error 1155 status. 1157 Using the "reset" operation example above, the client might send the 1158 following POST request message: 1160 POST /restconf/operations/example-ops:reboot HTTP/1.1 1161 Host: example.com 1162 Content-Type: application/yang.operation+xml 1164 1165 -33 1166 Going down for system maintenance 1167 en-US 1168 1170 The server might respond with an "invalid-value" error: 1172 HTTP/1.1 400 Bad Request 1173 Date: Mon, 25 Apr 2012 11:10:30 GMT 1174 Server: example-server 1175 Content-Type: application/yang.errors+xml 1177 1178 1179 protocol 1180 invalid-value 1181 1182 err:input/err:delay 1183 1184 Invalid input parameter 1185 1186 1188 3.7. Schema Resource 1190 The server can optionally support retrieval of the YANG modules it 1191 supports, using the "ietf-yang-library" module, defined in 1192 [I-D.ietf-netconf-yang-library]. 1194 To retrieve a YANG module, a client first needs to get the URL for 1195 retrieving the schema. 1197 The client might send the following GET request message: 1199 GET /restconf/data/ietf-yang-library:modules/module= 1200 example-jukebox,2014-07-03/schema HTTP/1.1 1201 Host: example.com 1202 Accept: application/yang.data+json 1204 The server might respond: 1206 HTTP/1.1 200 OK 1207 Date: Mon, 25 Apr 2012 11:10:30 GMT 1208 Server: example-server 1209 Content-Type: application/yang.data+json 1211 { 1212 "ietf-yang-library:schema": 1213 "https://example.com/mymodules/example-jukebox/2015-06-04" 1214 } 1216 Next the client needs to retrieve the actual YANG schema. 1218 The client might send the following GET request message: 1220 GET https://example.com/mymodules/example-jukebox/2015-06-04 1221 HTTP/1.1 1222 Host: example.com 1223 Accept: application/yang 1225 The server might respond: 1227 module example-jukebox { 1229 // contents of YANG module deleted for this example... 1231 } 1233 3.8. Event Stream Resource 1235 An "event stream" resource represents a source for system generated 1236 event notifications. Each stream is created and modified by the 1237 server only. A client can retrieve a stream resource or initiate a 1238 long-poll server sent event stream, using the procedure specified in 1239 Section 6.3. 1241 A notification stream functions according to the NETCONF 1242 Notifications specification [RFC5277]. The available streams can be 1243 retrieved from the stream list, which specifies the syntax and 1244 semantics of a stream resource. 1246 3.9. Errors Media Type 1248 An "errors" media type is a collection of error information that is 1249 sent as the message-body in a server response message, if an error 1250 occurs while processing a request message. It is not considered a 1251 resource type because no instances can be retrieved with a GET 1252 request. 1254 The "ietf-restconf" YANG module contains the "application/ 1255 yang.errors" restconf-media-type extension which specifies the syntax 1256 and semantics of an "errors" media type. RESTCONF error handling 1257 behavior is defined in Section 7. 1259 4. Operations 1261 The RESTCONF protocol uses HTTP methods to identify the CRUD 1262 operation requested for a particular resource. 1264 The following table shows how the RESTCONF operations relate to 1265 NETCONF protocol operations: 1267 +----------+--------------------------------------------+ 1268 | RESTCONF | NETCONF | 1269 +----------+--------------------------------------------+ 1270 | OPTIONS | none | 1271 | HEAD | none | 1272 | GET | , | 1273 | POST | (operation="create") | 1274 | PUT | (operation="create/replace") | 1275 | PATCH | (operation="merge") | 1276 | DELETE | (operation="delete") | 1277 +----------+--------------------------------------------+ 1279 Table 1: CRUD Methods in RESTCONF 1281 The NETCONF "remove" operation attribute is not supported by the HTTP 1282 DELETE method. The resource must exist or the DELETE method will 1283 fail. The PATCH method is equivalent to a "merge" operation when 1284 using a plain patch (see Section 4.6.1), other media-types may 1285 provide more granular control. 1287 Access control mechanisms may be used to limit what operations can be 1288 used. In particular, RESTCONF is compatible with the NETCONF Access 1289 Control Model (NACM) [RFC6536], as there is a specific mapping 1290 between RESTCONF and NETCONF operations, defined in Table 1. The 1291 resource path needs to be converted internally by the server to the 1292 corresponding YANG instance-identifier. Using this information, the 1293 server can apply the NACM access control rules to RESTCONF messages. 1295 The server MUST NOT allow any operation to any resources that the 1296 client is not authorized to access. 1298 Implementation of all methods (except PATCH) are defined in 1299 [RFC7231]. This section defines the RESTCONF protocol usage for each 1300 HTTP method. 1302 4.1. OPTIONS 1304 The OPTIONS method is sent by the client to discover which methods 1305 are supported by the server for a specific resource (e.g., GET, POST, 1306 DELETE, etc.). 1308 The server SHOULD implement this method, however the same information 1309 could be extracted from the YANG modules and the RESTCONF protocol 1310 specification. 1312 If the PATCH method is supported, then the "Accept-Patch" header MUST 1313 be supported and returned in the response to the OPTIONS request, as 1314 defined in [RFC5789]. 1316 4.2. HEAD 1318 The HEAD method is sent by the client to retrieve just the headers 1319 that would be returned for the comparable GET method, without the 1320 response message-body. It is supported for all resource types, 1321 except operation resources. 1323 The request MUST contain a request URI that contains at least the 1324 entry point. The same query parameters supported by the GET method 1325 are supported by the HEAD method. 1327 The access control behavior is enforced as if the method was GET 1328 instead of HEAD. The server MUST respond the same as if the method 1329 was GET instead of HEAD, except that no response message-body is 1330 included. 1332 4.3. GET 1334 The GET method is sent by the client to retrieve data and meta-data 1335 for a resource. It is supported for all resource types, except 1336 operation resources. The request MUST contain a request URI that 1337 contains at least the entry point. 1339 The server MUST NOT return any data resources for which the user does 1340 not have read privileges. If the user is not authorized to read the 1341 target resource, an error response containing a "403 Forbidden" or 1342 "404 Not Found" status-line is returned to the client. 1344 If the user is authorized to read some but not all of the target 1345 resource, the unauthorized content is omitted from the response 1346 message-body, and the authorized content is returned to the client. 1348 Example: 1350 The client might request the response headers for an XML 1351 representation of the "library" resource: 1353 GET /restconf/data/example-jukebox:jukebox/ 1354 library/artist=Foo%20Fighters/album HTTP/1.1 1355 Host: example.com 1356 Accept: application/yang.data+xml 1358 The server might respond: 1360 HTTP/1.1 200 OK 1361 Date: Mon, 23 Apr 2012 17:02:40 GMT 1362 Server: example-server 1363 Content-Type: application/yang.data+xml 1364 Cache-Control: no-cache 1365 Pragma: no-cache 1366 ETag: a74eefc993a2b 1367 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1369 1370 Wasting Light 1371 1372 g:alternative 1373 1374 2011 1375 1377 4.4. POST 1379 The POST method is sent by the client to create a data resource or 1380 invoke an operation resource. The server uses the target resource 1381 media type to determine how to process the request. 1383 +-----------+------------------------------------------------+ 1384 | Type | Description | 1385 +-----------+------------------------------------------------+ 1386 | Datastore | Create a top-level configuration data resource | 1387 | Data | Create a configuration data child resource | 1388 | Operation | Invoke a protocol operation | 1389 +-----------+------------------------------------------------+ 1391 Resource Types that Support POST 1393 4.4.1. Create Resource Mode 1395 If the target resource type is a datastore or data resource, then the 1396 POST is treated as a request to create a top-level resource or child 1397 resource, respectively. The message-body is expected to contain the 1398 content of a child resource to create within the parent (target 1399 resource). The data-model for the child tree is the subtree is 1400 defined by YANG for the child resource. 1402 The "insert" and "point" query parameters are supported by the POST 1403 method for datastore and data resource types, as specified in the 1404 YANG definition in Section 8. 1406 If the POST method succeeds, a "201 Created" status-line is returned 1407 and there is no response message-body. A "Location" header 1408 identifying the child resource that was created MUST be present in 1409 the response in this case. 1411 If the user is not authorized to create the target resource, an error 1412 response containing a "403 Forbidden" or "404 Not Found" status-line 1413 is returned to the client. All other error responses are handled 1414 according to the procedures defined in Section 7. 1416 Example: 1418 To create a new "jukebox" resource, the client might send: 1420 POST /restconf/data HTTP/1.1 1421 Host: example.com 1422 Content-Type: application/yang.data+json 1424 { "example-jukebox:jukebox" : [null] } 1426 If the resource is created, the server might respond as follows. 1427 Note that the "Location" header line is wrapped for display purposes 1428 only: 1430 HTTP/1.1 201 Created 1431 Date: Mon, 23 Apr 2012 17:01:00 GMT 1432 Server: example-server 1433 Location: https://example.com/restconf/data/ 1434 example-jukebox:jukebox 1435 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 1436 ETag: b3a3e673be2 1438 Refer to Appendix D.2.1 for more resource creation examples. 1440 4.4.2. Invoke Operation Mode 1442 If the target resource type is an operation resource, then the POST 1443 method is treated as a request to invoke that operation. The 1444 message-body (if any) is processed as the operation input parameters. 1445 Refer to Section 3.6 for details on operation resources. 1447 If the POST request succeeds, a "200 OK" status-line is returned if 1448 there is a response message-body, and a "204 No Content" status-line 1449 is returned if there is no response message-body. 1451 If the user is not authorized to invoke the target operation, an 1452 error response containing a "403 Forbidden" or "404 Not Found" 1453 status-line is returned to the client. All other error responses are 1454 handled according to the procedures defined in Section 7. 1456 Example: 1458 In this example, the client is invoking the "play" operation defined 1459 in the "example-jukebox" YANG module. 1461 A client might send a "play" request as follows: 1463 POST /restconf/operations/example-jukebox:play HTTP/1.1 1464 Host: example.com 1465 Content-Type: application/yang.operation+json 1467 { 1468 "example-jukebox:input" : { 1469 "playlist" : "Foo-One", 1470 "song-number" : 2 1471 } 1472 } 1474 The server might respond: 1476 HTTP/1.1 204 No Content 1477 Date: Mon, 23 Apr 2012 17:50:00 GMT 1478 Server: example-server 1480 4.5. PUT 1482 The PUT method is sent by the client to create or replace the target 1483 resource. 1485 The only target resource media type that supports PUT is the data 1486 resource. The message-body is expected to contain the content used 1487 to create or replace the target resource. 1489 The "insert" (Section 4.8.4) and "point" (Section 4.8.5) query 1490 parameters are supported by the PUT method for data resources. 1492 Consistent with [RFC7231], if the PUT request creates a new resource, 1493 a "201 Created" status-line is returned. If an existing resource is 1494 modified, either "200 OK" or "204 No Content" are returned. 1496 If the user is not authorized to create or replace the target 1497 resource an error response containing a "403 Forbidden" or "404 Not 1498 Found" status-line is returned to the client. All other error 1499 responses are handled according to the procedures defined in 1500 Section 7. 1502 Example: 1504 An "album" child resource defined in the "example-jukebox" YANG 1505 module is replaced or created if it does not already exist. 1507 To replace the "album" resource contents, the client might send as 1508 follows. Note that the request-line is wrapped for display purposes 1509 only: 1511 PUT /restconf/data/example-jukebox:jukebox/ 1512 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1513 Host: example.com 1514 Content-Type: application/yang.data+json 1515 { 1516 "example-jukebox:album" : { 1517 "name" : "Wasting Light", 1518 "genre" : "example-jukebox:alternative", 1519 "year" : 2011 1520 } 1521 } 1523 If the resource is updated, the server might respond: 1525 HTTP/1.1 204 No Content 1526 Date: Mon, 23 Apr 2012 17:04:00 GMT 1527 Server: example-server 1528 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 1529 ETag: b27480aeda4c 1531 4.6. PATCH 1533 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 1534 an extensible framework for resource patching mechanisms. It is 1535 optional to implement by the server. Each patch type needs a unique 1536 media type. Zero or more PATCH media types MAY be supported by the 1537 server. The media types supported by a server can be discovered by 1538 the client by sending an OPTIONS request (see Section 4.1). 1540 If the target resource instance does not exist, the server MUST NOT 1541 create it. 1543 If the PATCH request succeeds, a "200 OK" status-line is returned if 1544 there is a message-body, and "204 No Content" is returned if no 1545 response message-body is sent. 1547 If the user is not authorized to alter the target resource an error 1548 response containing a "403 Forbidden" or "404 Not Found" status-line 1549 is returned to the client. All other error responses are handled 1550 according to the procedures defined in Section 7. 1552 4.6.1. Plain Patch 1554 The plain patch mechanism merges the contents of the message body 1555 with the target resource. If the target resource is a datastore 1556 resource (see Section 3.4), the message body MUST be either 1557 application/yang.datastore+xml or application/yang.datastore+json. 1558 If then the target resource is a data resource (see Section 3.5), 1559 then the message body MUST be either application/yang.data+xml or 1560 application/yang.data+json. 1562 Plain patch can used to create or update, but not delete, a child 1563 resource within the target resource. Please see 1564 [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting 1565 more granular control. The YANG Patch Media Type allows multiple 1566 sub-operations (e.g., merge, delete) within a single PATCH operation. 1568 Example: 1570 To replace just the "year" field in the "album" resource (instead of 1571 replacing the entire resource with the PUT method), the client might 1572 send a plain patch as follows. Note that the request-line is wrapped 1573 for display purposes only: 1575 PATCH /restconf/data/example-jukebox:jukebox/ 1576 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1577 Host: example.com 1578 If-Match: b8389233a4c 1579 Content-Type: application/yang.data+xml 1581 1582 2011 1583 1585 If the field is updated, the server might respond: 1587 HTTP/1.1 204 No Content 1588 Date: Mon, 23 Apr 2012 17:49:30 GMT 1589 Server: example-server 1590 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 1591 ETag: b2788923da4c 1593 4.7. DELETE 1595 The DELETE method is used to delete the target resource. If the 1596 DELETE request succeeds, a "204 No Content" status-line is returned, 1597 and there is no response message-body. 1599 If the user is not authorized to delete the target resource then an 1600 error response containing a "403 Forbidden" or "404 Not Found" 1601 status-line is returned to the client. All other error responses are 1602 handled according to the procedures defined in Section 7. 1604 Example: 1606 To delete a resource such as the "album" resource, the client might 1607 send: 1609 DELETE /restconf/data/example-jukebox:jukebox/ 1610 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1611 Host: example.com 1613 If the resource is deleted, the server might respond: 1615 HTTP/1.1 204 No Content 1616 Date: Mon, 23 Apr 2012 17:49:40 GMT 1617 Server: example-server 1619 4.8. Query Parameters 1621 Each RESTCONF operation allows zero or more query parameters to be 1622 present in the request URI. The specific parameters that are allowed 1623 depends on the resource type, and sometimes the specific target 1624 resource used, in the request. 1626 +-------------------+-------------+---------------------------------+ 1627 | Name | Methods | Description | 1628 +-------------------+-------------+---------------------------------+ 1629 | content | GET | Select config and/or non-config | 1630 | | | data resources | 1631 | depth | GET | Request limited sub-tree depth | 1632 | | | in the reply content | 1633 | fields | GET | Request a subset of the target | 1634 | | | resource contents | 1635 | filter | GET | Boolean notification filter for | 1636 | | | event stream resources | 1637 | insert | POST, PUT | Insertion mode for user-ordered | 1638 | | | data resources | 1639 | point | POST, PUT | Insertion point for user- | 1640 | | | ordered data resources | 1641 | start-time | GET | Replay buffer start time for | 1642 | | | event stream resources | 1643 | stop-time | GET | Replay buffer stop time for | 1644 | | | event stream resources | 1645 | with-defaults | GET | Control retrieval of default | 1646 | | | values | 1647 +-------------------+-------------+---------------------------------+ 1649 RESTCONF Query Parameters 1651 Query parameters can be given in any order. Each parameter can 1652 appear at most once in a request URI. A default value may apply if 1653 the parameter is missing. 1655 Refer to Appendix D.3 for examples of query parameter usage. 1657 If vendors define additional query parameters, they SHOULD use a 1658 prefix (such as the enterprise or organization name) for query 1659 parameter names in order to avoid collisions with other parameters. 1661 4.8.1. The "content" Query Parameter 1663 The "content" parameter controls how descendant nodes of the 1664 requested data nodes will be processed in the reply. 1666 The allowed values are: 1668 +-----------+-----------------------------------------------------+ 1669 | Value | Description | 1670 +-----------+-----------------------------------------------------+ 1671 | config | Return only configuration descendant data nodes | 1672 | nonconfig | Return only non-configuration descendant data nodes | 1673 | all | Return all descendant data nodes | 1674 +-----------+-----------------------------------------------------+ 1676 This parameter is only allowed for GET methods on datastore and data 1677 resources. A 400 Bad Request error is returned if used for other 1678 methods or resource types. 1680 The default value is determined by the "config" statement value of 1681 the requested data nodes. If the "config" value is "false", then the 1682 default for the "content" parameter is "nonconfig". If "config" is 1683 "true" then the default for the "content" parameter is "config". 1685 This query parameter MUST be supported by the server. 1687 4.8.2. The "depth" Query Parameter 1689 The "depth" parameter is used to specify the number of nest levels 1690 returned in a response for a GET method. The first nest-level 1691 consists of the requested data node itself. If the "fields" 1692 parameter (Section 4.8.3) is used to select descendant data nodes, 1693 these nodes all have a depth value of 1. Any child nodes which are 1694 contained within a parent node have a depth value that is 1 greater 1695 than its parent. 1697 The value of the "depth" parameter is either an integer between 1 and 1698 65535, or the string "unbounded". "unbounded" is the default. 1700 This parameter is only allowed for GET methods on API, datastore, and 1701 data resources. A 400 Bad Request error is returned if it used for 1702 other methods or resource types. 1704 By default, the server will include all sub-resources within a 1705 retrieved resource, which have the same resource type as the 1706 requested resource. Only one level of sub-resources with a different 1707 media type than the target resource will be returned. 1709 If the "depth" query parameter URI is listed in the "capability" 1710 leaf-list in Section 9.3, then the server supports the "depth" query 1711 parameter. 1713 4.8.3. The "fields" Query Parameter 1715 The "fields" query parameter is used to optionally identify data 1716 nodes within the target resource to be retrieved in a GET method. 1717 The client can use this parameter to retrieve a subset of all nodes 1718 in a resource. 1720 A value of the "fields" query parameter matches the following rule: 1722 fields-expr = path '(' fields-expr ')' / 1723 path ';' fields-expr / 1724 path 1725 path = api-identifier [ '/' path ] 1727 "api-identifier" is defined in Section 3.5.1.1. 1729 ";" is used to select multiple nodes. For example, to retrieve only 1730 the "genre" and "year" of an album, use: "fields=genre;year". 1732 Parentheses are used to specify sub-selectors of a node. 1734 For example, assume the target resource is the 'album' list. To 1735 retrieve only the "label" and "catalogue-number" of the "admin" 1736 container within an album, use: 1737 "fields=admin(label;catalogue-number)". 1739 "/" is used in a path to retrieve a child node of a node. For 1740 example, to retrieve only the "label" of an album, use: "fields=admin 1741 /label". 1743 This parameter is only allowed for GET methods on api, datastore, and 1744 data resources. A 400 Bad Request error is returned if used for 1745 other methods or resource types. 1747 If the "fields" query parameter URI is listed in the "capability" 1748 leaf-list in Section 9.3, then the server supports the "fields" 1749 parameter. 1751 4.8.4. The "insert" Query Parameter 1753 The "insert" parameter is used to specify how a resource should be 1754 inserted within a user-ordered list. 1756 The allowed values are: 1758 +-----------+-------------------------------------------------------+ 1759 | Value | Description | 1760 +-----------+-------------------------------------------------------+ 1761 | first | Insert the new data as the new first entry. | 1762 | last | Insert the new data as the new last entry. | 1763 | before | Insert the new data before the insertion point, as | 1764 | | specified by the value of the "point" parameter. | 1765 | after | Insert the new data after the insertion point, as | 1766 | | specified by the value of the "point" parameter. | 1767 +-----------+-------------------------------------------------------+ 1769 The default value is "last". 1771 This parameter is only supported for the POST and PUT methods. It is 1772 also only supported if the target resource is a data resource, and 1773 that data represents a YANG list or leaf-list that is ordered by the 1774 user. 1776 If the values "before" or "after" are used, then a "point" query 1777 parameter for the insertion parameter MUST also be present, or a 400 1778 Bad Request error is returned. 1780 The "insert" query parameter MUST be supported by the server. 1782 4.8.5. The "point" Query Parameter 1784 The "point" parameter is used to specify the insertion point for a 1785 data resource that is being created or moved within a user ordered 1786 list or leaf-list. 1788 The value of the "point" parameter is a string that identifies the 1789 path to the insertion point object. The format is the same as a 1790 target resource URI string. 1792 This parameter is only supported for the POST and PUT methods. It is 1793 also only supported if the target resource is a data resource, and 1794 that data represents a YANG list or leaf-list that is ordered by the 1795 user. 1797 If the "insert" query parameter is not present, or has a value other 1798 than "before" or "after", then a 400 Bad Request error is returned. 1800 This parameter contains the instance identifier of the resource to be 1801 used as the insertion point for a POST or PUT method. 1803 The "point" query parameter MUST be supported by the server. 1805 4.8.6. The "filter" Query Parameter 1807 The "filter" parameter is used to indicate which subset of all 1808 possible events are of interest. If not present, all events not 1809 precluded by other parameters will be sent. 1811 This parameter is only allowed for GET methods on a text/event-stream 1812 data resource. A 400 Bad Request error is returned if used for other 1813 methods or resource types. 1815 The format of this parameter is an XPath 1.0 expression, and is 1816 evaluated in the following context: 1818 o The set of namespace declarations is the set of prefix and 1819 namespace pairs for all supported YANG modules, where the prefix 1820 is the YANG module name, and the namespace is as defined by the 1821 "namespace" statement in the YANG module. 1823 o The function library is the core function library defined in XPath 1824 1.0. 1826 o The set of variable bindings is empty. 1828 o The context node is the root node. 1830 The filter is used as defined in [RFC5277], Section 3.6. If the 1831 boolean result of the expression is true when applied to the 1832 conceptual "notification" document root, then the event notification 1833 is delivered to the client. 1835 If the "filter" query parameter URI is listed in the "capability" 1836 leaf-list in Section 9.3, then the server supports the "filter" query 1837 parameter. 1839 4.8.7. The "start-time" Query Parameter 1841 The "start-time" parameter is used to trigger the notification replay 1842 feature and indicate that the replay should start at the time 1843 specified. If the stream does not support replay, per the 1844 "replay-support" attribute returned by stream list entry for the 1845 stream resource, then the server MUST return the HTTP error code 400 1846 Bad Request. 1848 The value of the "start-time" parameter is of type "date-and-time", 1849 defined in the "ietf-yang" YANG module [RFC6991]. 1851 This parameter is only allowed for GET methods on a text/event-stream 1852 data resource. A 400 Bad Request error is returned if used for other 1853 methods or resource types. 1855 If this parameter is not present, then a replay subscription is not 1856 being requested. It is not valid to specify start times that are 1857 later than the current time. If the value specified is earlier than 1858 the log can support, the replay will begin with the earliest 1859 available notification. 1861 If this query parameter is supported by the server, then the "replay" 1862 query parameter URI MUST be listed in the "capability" leaf-list in 1863 Section 9.3. The "stop-time" query parameter MUST also be supported 1864 by the server. 1866 If the "replay-support" leaf is present in the "stream" entry 1867 (defined in Section 9.3) then the server MUST support the 1868 "start-time" and "stop-time" query parameters for that stream. 1870 4.8.8. The "stop-time" Query Parameter 1872 The "stop-time" parameter is used with the replay feature to indicate 1873 the newest notifications of interest. This parameter MUST be used 1874 with and have a value later than the "start-time" parameter. 1876 The value of the "stop-time" parameter is of type "date-and-time", 1877 defined in the "ietf-yang" YANG module [RFC6991]. 1879 This parameter is only allowed for GET methods on a text/event-stream 1880 data resource. A 400 Bad Request error is returned if used for other 1881 methods or resource types. 1883 If this parameter is not present, the notifications will continue 1884 until the subscription is terminated. Values in the future are 1885 valid. 1887 If this query parameter is supported by the server, then the "replay" 1888 query parameter URI MUST be listed in the "capability" leaf-list in 1889 Section 9.3. The "start-time" query parameter MUST also be supported 1890 by the server. 1892 If the "replay-support" leaf is present in the "stream" entry 1893 (defined in Section 9.3) then the server MUST support the 1894 "start-time" and "stop-time" query parameters for that stream. 1896 4.8.9. The "with-defaults" Query Parameter 1898 The "with-defaults" parameter is used to specify how information 1899 about default data nodes should be returned in response to GET 1900 requests on data resources. 1902 If the server supports this capability, then it MUST implement the 1903 behavior in Section 4.5.1 of [RFC6243], except applied to the 1904 RESTCONF GET operation, instead of the NETCONF operations. 1906 +---------------------------+---------------------------------------+ 1907 | Value | Description | 1908 +---------------------------+---------------------------------------+ 1909 | report-all | All data nodes are reported | 1910 | trim | Data nodes set to the YANG default | 1911 | | are not reported | 1912 | explicit | Data nodes set by the client are not | 1913 | | reported | 1914 | report-all-tagged | All data nodes are reported and | 1915 | | defaults are tagged | 1916 +---------------------------+---------------------------------------+ 1918 If the "with-defaults" parameter is set to "report-all" then the 1919 server MUST adhere to the defaults reporting behavior defined in 1920 Section 3.1 of [RFC6243]. 1922 If the "with-defaults" parameter is set to "trim" then the server 1923 MUST adhere to the defaults reporting behavior defined in Section 3.2 1924 of [RFC6243]. 1926 If the "with-defaults" parameter is set to "explicit" then the server 1927 MUST adhere to the defaults reporting behavior defined in Section 3.3 1928 of [RFC6243]. 1930 If the "with-defaults" parameter is set to "report-all-tagged" then 1931 the server MUST adhere to the defaults reporting behavior defined in 1932 Section 3.4 of [RFC6243]. 1934 If the "with-defaults" parameter is not present then the server MUST 1935 adhere to the defaults reporting behavior defined in its "basic-mode" 1936 parameter for the "defaults" protocol capability URI, defined in 1937 Section 9.1.2. 1939 If the server includes the "with-defaults" query parameter URI in the 1940 "capability" leaf-list in Section 9.3, then the "with-defaults" query 1941 parameter MUST be supported. 1943 5. Messages 1945 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 1946 message corresponds to a single protocol method. Most messages can 1947 perform a single task on a single resource, such as retrieving a 1948 resource or editing a resource. The exception is the PATCH method, 1949 which allows multiple datastore edits within a single message. 1951 5.1. Request URI Structure 1953 Resources are represented with URIs following the structure for 1954 generic URIs in [RFC3986]. 1956 A RESTCONF operation is derived from the HTTP method and the request 1957 URI, using the following conceptual fields: 1959 //?# 1961 ^ ^ ^ ^ ^ 1962 | | | | | 1963 method entry resource query fragment 1965 M M O O I 1967 M=mandatory, O=optional, I=ignored 1969 replaced by client with real values 1971 o method: the HTTP method identifying the RESTCONF operation 1972 requested by the client, to act upon the target resource specified 1973 in the request URI. RESTCONF operation details are described in 1974 Section 4. 1976 o entry: the root of the RESTCONF API configured on this HTTP 1977 server, discovered by getting the ".well-known/host-meta" 1978 resource, as described in Section 3.1. 1980 o resource: the path expression identifying the resource that is 1981 being accessed by the operation. If this field is not present, 1982 then the target resource is the API itself, represented by the 1983 media type "application/yang.api". 1985 o query: the set of parameters associated with the RESTCONF message. 1986 These have the familiar form of "name=value" pairs. Most query 1987 parameters are optional to implement by the server and optional to 1988 use by the client. Each optional query parameter is identified by 1989 a URI. The server MUST list the optional query parameter URIs it 1990 supports in the "capabilities" list defined in Section 9.3. 1992 There is a specific set of parameters defined, although the server 1993 MAY choose to support query parameters not defined in this document. 1994 The contents of the any query parameter value MUST be encoded 1995 according to [RFC3986], Section 3.4. Any reserved characters MUST be 1996 percent-encoded, according to [RFC3986], section 2.1. 1998 o fragment: This field is not used by the RESTCONF protocol. 2000 When new resources are created by the client, a "Location" header is 2001 returned, which identifies the path of the newly created resource. 2002 The client MUST use this exact path identifier to access the resource 2003 once it has been created. 2005 The "target" of an operation is a resource. The "path" field in the 2006 request URI represents the target resource for the operation. 2008 5.2. Message Headers 2010 There are several HTTP header lines utilized in RESTCONF messages. 2011 Messages are not limited to the HTTP headers listed in this section. 2013 HTTP defines which header lines are required for particular 2014 circumstances. Refer to each operation definition section in 2015 Section 4 for examples on how particular headers are used. 2017 There are some request headers that are used within RESTCONF, usually 2018 applied to data resources. The following tables summarize the 2019 headers most relevant in RESTCONF message requests: 2021 +-----------------------------+-------------------------------------+ 2022 | Name | Description | 2023 +-----------------------------+-------------------------------------+ 2024 | Accept | Response Content-Types that are | 2025 | | acceptable | 2026 | Content-Type | The media type of the request body | 2027 | Host | The host address of the server | 2028 | If-Match | Only perform the action if the | 2029 | | entity matches ETag | 2030 | If-Modified-Since | Only perform the action if modified | 2031 | | since time | 2032 | If-Unmodified-Since | Only perform the action if un- | 2033 | | modified since time | 2034 +-----------------------------+-------------------------------------+ 2036 RESTCONF Request Headers 2038 The following tables summarize the headers most relevant in RESTCONF 2039 message responses: 2041 +-----------------------+-------------------------------------------+ 2042 | Name | Description | 2043 +-----------------------+-------------------------------------------+ 2044 | Allow | Valid actions when 405 error returned | 2045 | Cache-Control | The cache control parameters for the | 2046 | | response | 2047 | Content-Type | The media type of the response message- | 2048 | | body | 2049 | Date | The date and time the message was sent | 2050 | ETag | An identifier for a specific version of a | 2051 | | resource | 2052 | Last-Modified | The last modified date and time of a | 2053 | | resource | 2054 | Location | The resource identifier for a newly | 2055 | | created resource | 2056 +-----------------------+-------------------------------------------+ 2058 RESTCONF Response Headers 2060 5.3. Message Encoding 2062 RESTCONF messages are encoded in HTTP according to [RFC7230]. The 2063 "utf-8" character set is used for all messages. RESTCONF message 2064 content is sent in the HTTP message-body. 2066 Content is encoded in either JSON or XML format. A server MUST 2067 support XML or JSON encoding. XML encoding rules for data nodes are 2068 defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are 2069 used for all XML content. JSON encoding rules are defined in 2070 [I-D.ietf-netmod-yang-json]. JSON encoding of meta-data is defined 2071 in [I-D.ietf-netmod-yang-metadata]. This encoding is valid JSON, but 2072 also has special encoding rules to identify module namespaces and 2073 provide consistent type processing of YANG data. 2075 Request input content encoding format is identified with the Content- 2076 Type header. This field MUST be present if a message-body is sent by 2077 the client. 2079 The server MUST support the "Accept" header and "406 Not Acceptable" 2080 status code, as defined in [RFC7231]. Response output content 2081 encoding format is identified with the Accept header in the request. 2082 If is not specified, the request input encoding format is used. If 2083 there was no request input, then the default output encoding is XML 2084 or JSON, depending or server preference. File extensions encoded in 2085 the request are not used to identify format encoding. 2087 5.4. RESTCONF Meta-Data 2088 The RESTCONF protocol needs to retrieve the same meta-data that is 2089 used in the NETCONF protocol. Information about default leafs, last- 2090 modified timestamps, etc. are commonly used to annotate 2091 representations of the datastore contents. This meta-data is not 2092 defined in the YANG schema because it applies to the datastore, and 2093 is common across all data nodes. 2095 This information is encoded as attributes in XML. JSON encoding of 2096 meta-data is defined in [I-D.ietf-netmod-yang-metadata]. 2098 The following examples are based on the example in Appendix D.3.9. 2099 The "report-all-tagged" mode for the "with-defaults" query parameter 2100 requires that a "default" attribute be returned for default nodes. 2101 This example shows that attribute for the "mtu" leaf . 2103 5.4.1. XML MetaData Encoding Example 2105 GET /restconf/data/interfaces/interface=eth1 2106 ?with-defaults=report-all-tagged HTTP/1.1 2107 Host: example.com 2108 Accept: application/yang.data+xml 2110 The server might respond as follows. 2112 HTTP/1.1 200 OK 2113 Date: Mon, 23 Apr 2012 17:01:00 GMT 2114 Server: example-server 2115 Content-Type: application/yang.data+xml 2117 2119 eth1 2120 1500 2122 up 2123 2125 5.4.2. JSON MetaData Encoding Example 2127 Note that RFC 6243 defines the "default" attribute with XSD, not 2128 YANG, so the YANG module name has to be assigned manually. The value 2129 "ietf-netconf-with-defaults" is assigned for JSON meta-data encoding. 2131 GET /restconf/data/interfaces/interface=eth1 2132 ?with-defaults=report-all-tagged HTTP/1.1 2133 Host: example.com 2134 Accept: application/yang.data+json 2135 The server might respond as follows. 2137 HTTP/1.1 200 OK 2138 Date: Mon, 23 Apr 2012 17:01:00 GMT 2139 Server: example-server 2140 Content-Type: application/yang.data+json 2142 { 2143 "example:interface": [ 2144 { 2145 "name" : "eth1", 2146 "mtu" : 1500, 2147 "@mtu": { 2148 "ietf-netconf-with-defaults:default" : true 2149 }, 2150 "status" : "up" 2151 } 2152 ] 2153 } 2155 5.5. Return Status 2157 Each message represents some sort of resource access. An HTTP 2158 "status-line" header line is returned for each request. If a 4xx or 2159 5xx range status code is returned in the status-line, then the error 2160 information will be returned in the response, according to the format 2161 defined in Section 7.1. 2163 5.6. Message Caching 2165 Since the datastore contents change at unpredictable times, responses 2166 from a RESTCONF server generally SHOULD NOT be cached. 2168 The server SHOULD include a "Cache-Control" header in every response 2169 that specifies whether the response should be cached. A "Pragma" 2170 header specifying "no-cache" MAY also be sent in case the 2171 "Cache-Control" header is not supported. 2173 Instead of using HTTP caching, the client SHOULD track the "ETag" and 2174 /or "Last-Modified" headers returned by the server for the datastore 2175 resource (or data resource if the server supports it). A retrieval 2176 request for a resource can include the "If-None-Match" and/or 2177 "If-Modified-Since" headers, which will cause the server to return a 2178 "304 Not Modified" status-line if the resource has not changed. The 2179 client MAY use the HEAD method to retrieve just the message headers, 2180 which SHOULD include the "ETag" and "Last-Modified" headers, if this 2181 meta-data is maintained for the target resource. 2183 6. Notifications 2185 The RESTCONF protocol supports YANG-defined event notifications. The 2186 solution preserves aspects of NETCONF Event Notifications [RFC5277] 2187 while utilizing the Server-Sent Events [W3C.CR-eventsource-20121211] 2188 transport strategy. 2190 6.1. Server Support 2192 A RESTCONF server is not required to support RESTCONF notifications. 2193 Clients may determine if a server supports RESTCONF notifications by 2194 using the HTTP operation OPTIONS, HEAD, or GET on the stream list. 2195 The server does not support RESTCONF notifications if an HTTP error 2196 code is returned (e.g., 404 Not Found). 2198 6.2. Event Streams 2200 A RESTCONF server that supports notifications will populate a stream 2201 resource for each notification delivery service access point. A 2202 RESTCONF client can retrieve the list of supported event streams from 2203 a RESTCONF server using the GET operation on the stream list. 2205 The "restconf-state/streams" container definition in the 2206 "ietf-restconf-monitoring" module (defined in Section 9.3) is used to 2207 specify the structure and syntax of the conceptual child resources 2208 within the "streams" resource. 2210 For example: 2212 The client might send the following request: 2214 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2215 streams HTTP/1.1 2216 Host: example.com 2217 Accept: application/yang.data+xml 2219 The server might send the following response: 2221 HTTP/1.1 200 OK 2222 Content-Type: application/yang.api+xml 2224 2226 2227 NETCONF 2228 default NETCONF event stream 2229 2230 true 2231 2232 2007-07-08T00:00:00Z 2233 2234 2235 xml 2236 https://example.com/streams/NETCONF 2237 2238 2239 2240 json 2241 https://example.com/streams/NETCONF-JSON 2242 2243 2244 2245 2246 SNMP 2247 SNMP notifications 2248 false 2249 2250 xml 2251 https://example.com/streams/SNMP 2252 2253 2254 2255 syslog-critical 2256 Critical and higher severity 2257 2258 true 2259 2260 2007-07-01T00:00:00Z 2261 2262 2263 xml 2264 2265 https://example.com/streams/syslog-critical 2266 2267 2268 2269 2271 6.3. Subscribing to Receive Notifications 2273 RESTCONF clients can determine the URL for the subscription resource 2274 (to receive notifications) by sending an HTTP GET request for the 2275 "location" leaf with the stream list entry. The value returned by 2276 the server can be used for the actual notification subscription. 2278 The client will send an HTTP GET request for the URL returned by the 2279 server with the "Accept" type "text/event-stream". 2281 The server will treat the connection as an event stream, using the 2282 Server Sent Events [W3C.CR-eventsource-20121211] transport strategy. 2284 The server MAY support query parameters for a GET method on this 2285 resource. These parameters are specific to each notification stream. 2287 For example: 2289 The client might send the following request: 2291 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2292 streams/stream=NETCONF/access=xml/location HTTP/1.1 2293 Host: example.com 2294 Accept: application/yang.data+xml 2296 The server might send the following response: 2298 HTTP/1.1 200 OK 2299 Content-Type: application/yang.api+xml 2301 2303 https://example.com/streams/NETCONF 2304 2306 The RESTCONF client can then use this URL value to start monitoring 2307 the event stream: 2309 GET /streams/NETCONF HTTP/1.1 2310 Host: example.com 2311 Accept: text/event-stream 2312 Cache-Control: no-cache 2313 Connection: keep-alive 2315 A RESTCONF client MAY request the server compress the events using 2316 the HTTP header field "Accept-Encoding". For instance: 2318 GET /streams/NETCONF HTTP/1.1 2319 Host: example.com 2320 Accept: text/event-stream 2321 Cache-Control: no-cache 2322 Connection: keep-alive 2323 Accept-Encoding: gzip, deflate 2325 6.3.1. NETCONF Event Stream 2327 The server SHOULD support the "NETCONF" notification stream defined 2328 in [RFC5277]. For this stream, RESTCONF notification subscription 2329 requests MAY specify parameters indicating the events it wishes to 2330 receive. These query parameters are optional to implement, and only 2331 available if the server supports them. 2333 +------------+---------+-------------------------+ 2334 | Name | Section | Description | 2335 +------------+---------+-------------------------+ 2336 | start-time | 4.8.7 | replay event start time | 2337 | stop-time | 4.8.8 | replay event stop time | 2338 | filter | 4.8.6 | boolean content filter | 2339 +------------+---------+-------------------------+ 2341 NETCONF Stream Query Parameters 2343 The semantics and syntax for these query parameters are defined in 2344 the sections listed above. The YANG encoding MUST be converted to 2345 URL-encoded string for use in the request URI. 2347 Refer to Appendix D.3.6 for filter parameter examples. 2349 6.4. Receiving Event Notifications 2351 RESTCONF notifications are encoded according to the definition of the 2352 event stream. The NETCONF stream defined in [RFC5277] is encoded in 2353 XML format. 2355 The structure of the event data is based on the "notification" 2356 element definition in Section 4 of [RFC5277]. It MUST conform to the 2357 schema for the "notification" element in Section 4 of [RFC5277], 2358 except the XML namespace for this element is defined as: 2360 urn:ietf:params:xml:ns:yang:ietf-restconf 2362 For JSON encoding purposes, the module name for the "notification" 2363 element is "ietf-restconf". 2365 Two child nodes within the "notification" container are expected, 2366 representing the event time and the event payload. The "event-time" 2367 node is defined within the "ietf-restconf" module namespace. The 2368 name and namespace of the payload element are determined by the YANG 2369 module containing the notification-stmt. 2371 In the following example, the YANG module "example-mod" is used: 2373 module example-mod { 2374 namespace "http://example.com/event/1.0"; 2376 notification event { 2377 leaf event-class { type string; } 2378 container reporting-entity { 2379 leaf card { type string; } 2380 } 2381 leaf severity { type string; } 2382 } 2383 } 2385 An example SSE event notification encoded using XML: 2387 data: 2389 data: 2013-12-21T00:01:00Z 2390 data: 2391 data: fault 2392 data: 2393 data: Ethernet0 2394 data: 2395 data: major 2396 data: 2397 data: 2399 An example SSE event notification encoded using JSON: 2401 data: { 2402 data: "ietf-restconf:notification": { 2403 data: "event-time": "2013-12-21T00:01:00Z", 2404 data: "example-mod:event": { 2405 data: "event-class": "fault", 2406 data: "reporting-entity": { "card": "Ethernet0" }, 2407 data: "severity": "major" 2408 data: } 2409 data: } 2410 data: } 2412 Alternatively, since neither XML nor JSON are whitespace sensitive, 2413 the above messages can be encoded onto a single line. For example: 2415 For example: ('\' line wrapping added for formatting only) 2417 XML: 2419 data: 2013-12-21T00:01:00ZfaultEthernet0\ 2423 major 2425 JSON: 2427 data: {"ietf-restconf:notification":{"event-time":"2013-12-21\ 2428 T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ 2429 tingEntity":{"card":"Ethernet0"},"severity":"major"}}} 2431 The SSE specifications supports the following additional fields: 2432 event, id and retry. A RESTCONF server MAY send the "retry" field 2433 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 2434 SHOULD NOT send the "event" or "id" fields, as there are no 2435 meaningful values that could be used for them that would not be 2436 redundant to the contents of the notification itself. RESTCONF 2437 servers that do not send the "id" field also do not need to support 2438 the HTTP header "Last-Event-Id". RESTCONF servers that do send the 2439 "id" field MUST still support the "startTime" query parameter as the 2440 preferred means for a client to specify where to restart the event 2441 stream. 2443 7. Error Reporting 2445 HTTP status-lines are used to report success or failure for RESTCONF 2446 operations. The element returned in NETCONF error 2447 responses contains some useful information. This error information 2448 is adapted for use in RESTCONF, and error information is returned for 2449 "4xx" class of status codes. 2451 The following table summarizes the return status codes used 2452 specifically by RESTCONF operations: 2454 +----------------------------+--------------------------------------+ 2455 | Status-Line | Description | 2456 +----------------------------+--------------------------------------+ 2457 | 100 Continue | POST accepted, 201 should follow | 2458 | 200 OK | Success with response message-body | 2459 | 201 Created | POST to create a resource success | 2460 | 202 Accepted | POST to create a resource accepted | 2461 | 204 No Content | Success without response message- | 2462 | | body | 2463 | 304 Not Modified | Conditional operation not done | 2464 | 400 Bad Request | Invalid request message | 2465 | 403 Forbidden | Access to resource denied | 2466 | 404 Not Found | Resource target or resource node not | 2467 | | found | 2468 | 405 Method Not Allowed | Method not allowed for target | 2469 | | resource | 2470 | 409 Conflict | Resource or lock in use | 2471 | 412 Precondition Failed | Conditional method is false | 2472 | 413 Request Entity Too | too-big error | 2473 | Large | | 2474 | 414 Request-URI Too Large | too-big error | 2475 | 415 Unsupported Media Type | non RESTCONF media type | 2476 | 500 Internal Server Error | operation-failed | 2477 | 501 Not Implemented | unknown-operation | 2478 | 503 Service Unavailable | Recoverable server error | 2479 +----------------------------+--------------------------------------+ 2481 HTTP Status Codes used in RESTCONF 2483 Since an operation resource is defined with a YANG "action" or "rpc" 2484 statement, a mapping between the NETCONF value and the 2485 HTTP status code is needed. The specific error condition and 2486 response code to use are data-model specific and might be contained 2487 in the YANG "description" statement for the "action" or "rpc" 2488 statement. 2490 +-------------------------+-------------+ 2491 | | status code | 2492 +-------------------------+-------------+ 2493 | in-use | 409 | 2494 | invalid-value | 400 | 2495 | too-big | 413 | 2496 | missing-attribute | 400 | 2497 | bad-attribute | 400 | 2498 | unknown-attribute | 400 | 2499 | bad-element | 400 | 2500 | unknown-element | 400 | 2501 | unknown-namespace | 400 | 2502 | access-denied | 403 | 2503 | lock-denied | 409 | 2504 | resource-denied | 409 | 2505 | rollback-failed | 500 | 2506 | data-exists | 409 | 2507 | data-missing | 409 | 2508 | operation-not-supported | 501 | 2509 | operation-failed | 500 | 2510 | partial-operation | 500 | 2511 | malformed-message | 400 | 2512 +-------------------------+-------------+ 2514 Mapping from error-tag to status code 2516 7.1. Error Response Message 2518 When an error occurs for a request message on a data resource or an 2519 operation resource, and a "4xx" class of status codes (except for 2520 status code "403 Forbidden"), then the server SHOULD send a response 2521 message-body containing the information described by the "errors" 2522 container definition within the YANG module Section 8. The Content- 2523 Type of this response message MUST be application/yang.errors (see 2524 example below). 2526 The client MAY specify the desired encoding for error messages by 2527 specifying the appropriate media-type in the Accept header. If no 2528 error media is specified, then the media type of the request message 2529 is used. If there is no request message the server MUST select 2530 "application/yang.errors+xml" or "application/yang.errors+json", 2531 depending on server preference. All of the examples in this 2532 document, except for the one below, assume that XML encoding will be 2533 returned if there is an error. 2535 YANG Tree Diagram for data: 2537 +--ro errors 2538 +--ro error* 2539 +--ro error-type enumeration 2540 +--ro error-tag string 2541 +--ro error-app-tag? string 2542 +--ro error-path? instance-identifier 2543 +--ro error-message? string 2544 +--ro error-info 2546 The semantics and syntax for RESTCONF error messages are defined in 2547 the "application/yang.errors" restconf-media-type extension in 2548 Section 8. 2550 Examples: 2552 The following example shows an error returned for an "lock-denied" 2553 error that can occur if a NETCONF client has locked a datastore. The 2554 RESTCONF client is attempting to delete a data resource. Note that 2555 an Accept header is used to specify the desired encoding for the 2556 error message. This example's use of the Accept header is especially 2557 notable since the DELETE method typically doesn't return a message- 2558 body and hence Accept headers are typically not passed. 2560 DELETE /restconf/data/example-jukebox:jukebox/ 2561 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2562 Host: example.com 2563 Accept: application/yang.errors+json 2564 The server might respond: 2566 HTTP/1.1 409 Conflict 2567 Date: Mon, 23 Apr 2012 17:11:00 GMT 2568 Server: example-server 2569 Content-Type: application/yang.errors+json 2571 { 2572 "ietf-restconf:errors": { 2573 "error": [ 2574 { 2575 "error-type": "protocol", 2576 "error-tag": "lock-denied", 2577 "error-message": "Lock failed, lock already held" 2578 } 2579 ] 2580 } 2581 } 2583 The following example shows an error returned for a "data-exists" 2584 error on a data resource. The "jukebox" resource already exists so 2585 it cannot be created. 2587 The client might send: 2589 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 2590 Host: example.com 2592 The server might respond (some lines wrapped for display purposes): 2594 HTTP/1.1 409 Conflict 2595 Date: Mon, 23 Apr 2012 17:11:00 GMT 2596 Server: example-server 2597 Content-Type: application/yang.errors+xml 2598 2599 2600 protocol 2601 data-exists 2602 2605 /rc:restconf/rc:data/jb:jukebox 2606 2607 2608 Data already exists, cannot create new resource 2609 2610 2611 2613 8. RESTCONF module 2615 The "ietf-restconf" module defines conceptual definitions within an 2616 extension and two groupings, which are not meant to be implemented as 2617 datastore contents by a server. E.g., the "restconf" container is 2618 not intended to be implemented as a top-level data node (under the "/ 2619 restconf/data" entry point). 2621 RFC Ed.: update the date below with the date of RFC publication and 2622 remove this note. 2624 file "ietf-restconf@2015-10-18.yang" 2626 module ietf-restconf { 2627 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 2628 prefix "rc"; 2630 organization 2631 "IETF NETCONF (Network Configuration) Working Group"; 2633 contact 2634 "WG Web: 2635 WG List: 2637 WG Chair: Mehmet Ersue 2638 2640 WG Chair: Mahesh Jethanandani 2641 2643 Editor: Andy Bierman 2644 2646 Editor: Martin Bjorklund 2647 2649 Editor: Kent Watsen 2650 "; 2652 description 2653 "This module contains conceptual YANG specifications 2654 for basic RESTCONF media type definitions used in 2655 RESTCONF protocol messages. 2657 Note that the YANG definitions within this module do not 2658 represent configuration data of any kind. 2659 The 'restconf-media-type' YANG extension statement 2660 provides a normative syntax for XML and JSON message 2661 encoding purposes. 2663 Copyright (c) 2015 IETF Trust and the persons identified as 2664 authors of the code. All rights reserved. 2666 Redistribution and use in source and binary forms, with or 2667 without modification, is permitted pursuant to, and subject 2668 to the license terms contained in, the Simplified BSD License 2669 set forth in Section 4.c of the IETF Trust's Legal Provisions 2670 Relating to IETF Documents 2671 (http://trustee.ietf.org/license-info). 2673 This version of this YANG module is part of RFC XXXX; see 2674 the RFC itself for full legal notices."; 2676 // RFC Ed.: replace XXXX with actual RFC number and remove this 2677 // note. 2679 // RFC Ed.: remove this note 2680 // Note: extracted from draft-ietf-netconf-restconf-08.txt 2682 // RFC Ed.: update the date below with the date of RFC publication 2683 // and remove this note. 2684 revision 2015-10-18 { 2685 description 2686 "Initial revision."; 2687 reference 2688 "RFC XXXX: RESTCONF Protocol."; 2689 } 2691 extension restconf-media-type { 2692 argument media-type-id { 2693 yin-element true; 2695 } 2696 // RFC Ed.: replace draft-ietf-netmod-yang-json with RFC number 2697 // in the description below, and remove this note. 2698 description 2699 "This extension is used to specify a YANG data structure which 2700 represents a conceptual RESTCONF media type. 2701 Data definition statements within this extension specify 2702 the generic syntax for the specific media type. 2704 YANG is mapped to specific encoding formats outside the 2705 scope of this extension statement. RFC 6020 defines XML 2706 encoding rules for all RESTCONF media types that use 2707 the '+xml' suffix. draft-ietf-netmod-yang-json defines 2708 JSON encoding rules for all RESTCONF media types that 2709 use the '+json' suffix. 2711 The 'media-type-id' parameter value identifies the media type 2712 that is being defined. It contains the string associated 2713 with the generic media type, i.e., no suffix is specified. 2715 This extension is ignored unless it appears as a top-level 2716 statement. It SHOULD contain data definition statements 2717 that result in exactly one container data node definition. 2718 This allows compliant translation to an XML instance 2719 document for each media type. 2721 The module name and namespace value for the YANG module using 2722 the extension statement is assigned to instance document data 2723 conforming to the data definition statements within 2724 this extension. 2726 The sub-statements of this extension MUST follow the 2727 'data-def-stmt' rule in the YANG ABNF. 2729 The XPath document root is the extension statement itself, 2730 such that the child nodes of the document root are 2731 represented by the data-def-stmt sub-statements within 2732 this extension. This conceptual document is the context 2733 for the following YANG statements: 2735 - must-stmt 2736 - when-stmt 2737 - path-stmt 2738 - min-elements-stmt 2739 - max-elements-stmt 2740 - mandatory-stmt 2741 - unique-stmt 2742 - ordered-by 2743 - instance-identifier data type 2745 The following data-def-stmt sub-statements have special 2746 meaning when used within a restconf-resource extension 2747 statement. 2749 - The list-stmt is not required to have a key-stmt defined. 2750 - The if-feature-stmt is ignored if present. 2751 - The config-stmt is ignored if present. 2752 - The available identity values for any 'identityref' 2753 leaf or leaf-list nodes is limited to the module 2754 containing this extension statement, and the modules 2755 imported into that module. 2756 "; 2757 } 2759 rc:restconf-media-type "application/yang.errors" { 2760 uses errors; 2761 } 2763 rc:restconf-media-type "application/yang.api" { 2764 uses restconf; 2765 } 2767 grouping errors { 2768 description 2769 "A grouping that contains a YANG container 2770 representing the syntax and semantics of a 2771 YANG Patch errors report within a response message."; 2773 container errors { 2774 description 2775 "Represents an error report returned by the server if 2776 a request results in an error."; 2778 list error { 2779 description 2780 "An entry containing information about one 2781 specific error that occurred while processing 2782 a RESTCONF request."; 2783 reference "RFC 6241, Section 4.3"; 2785 leaf error-type { 2786 type enumeration { 2787 enum transport { 2788 description "The transport layer"; 2789 } 2790 enum rpc { 2791 description "The rpc or notification layer"; 2792 } 2793 enum protocol { 2794 description "The protocol operation layer"; 2795 } 2796 enum application { 2797 description "The server application layer"; 2798 } 2799 } 2800 mandatory true; 2801 description 2802 "The protocol layer where the error occurred."; 2803 } 2805 leaf error-tag { 2806 type string; 2807 mandatory true; 2808 description 2809 "The enumerated error tag."; 2810 } 2812 leaf error-app-tag { 2813 type string; 2814 description 2815 "The application-specific error tag."; 2816 } 2818 leaf error-path { 2819 type instance-identifier; 2820 description 2821 "The YANG instance identifier associated 2822 with the error node."; 2823 } 2825 leaf error-message { 2826 type string; 2827 description 2828 "A message describing the error."; 2829 } 2831 anyxml error-info { 2832 description 2833 "This anyxml value MUST represent a container with 2834 zero or more data nodes representing additional 2835 error information."; 2836 } 2837 } 2838 } 2840 } 2842 grouping restconf { 2843 description 2844 "Conceptual container representing the 2845 application/yang.api resource type."; 2847 container restconf { 2848 description 2849 "Conceptual container representing the 2850 application/yang.api resource type."; 2852 container data { 2853 description 2854 "Container representing the application/yang.datastore 2855 resource type. Represents the conceptual root of all 2856 operational data and configuration data supported by 2857 the server. The child nodes of this container can be 2858 any data resource (application/yang.data), which are 2859 defined as top-level data nodes from the YANG modules 2860 advertised by the server in the ietf-restconf-monitoring 2861 module."; 2862 } 2864 container operations { 2865 description 2866 "Container for all operation resources 2867 (application/yang.operation), 2869 Each resource is represented as an empty leaf with the 2870 name of the RPC operation from the YANG rpc statement. 2872 E.g.; 2874 POST /restconf/operations/show-log-errors 2876 leaf show-log-errors { 2877 type empty; 2878 } 2879 "; 2880 } 2881 } 2882 } 2884 } 2886 2888 9. RESTCONF Monitoring 2890 The "ietf-restconf-monitoring" module provides information about the 2891 RESTCONF protocol capabilities and event notification streams 2892 available from the server. A RESTCONF server MUST implement the "/ 2893 restconf-state/capabilities" container in this module. 2895 YANG Tree Diagram for "ietf-restconf-monitoring" module: 2897 +--ro restconf-state 2898 +--ro capabilities 2899 | +--ro capability* inet:uri 2900 +--ro streams 2901 +--ro stream* [name] 2902 +--ro name string 2903 +--ro description? string 2904 +--ro replay-support? boolean 2905 +--ro replay-log-creation-time? yang:date-and-time 2906 +--ro access* [encoding] 2907 +--ro encoding string 2908 +--ro location inet:uri 2910 9.1. restconf-state/capabilities 2912 This mandatory container holds the RESTCONF protocol capability URIs 2913 supported by the server. 2915 The server MUST maintain a last-modified timestamp for this 2916 container, and return the "Last-Modified" header when this data node 2917 is retrieved with the GET or HEAD methods. 2919 The server SHOULD maintain an entity-tag for this container, and 2920 return the "ETag" header when this data node is retrieved with the 2921 GET or HEAD methods. 2923 The server MUST include a "capability" URI leaf-list entry for the 2924 "defaults" mode used by the server, defined in Section 9.1.2. 2926 The server MUST include a "capability" URI leaf-list entry 2927 identifying each supported optional protocol feature. This includes 2928 optional query parameters and MAY include other capability URIs 2929 defined outside this document. 2931 9.1.1. Query Parameter URIs 2933 A new set of RESTCONF Capability URIs are defined to identify the 2934 specific query parameters (defined in Section 4.8) supported by the 2935 server. 2937 The server MUST include a "capability" leaf-list entry for each 2938 optional query parameter that it supports. 2940 +-------------+-------+---------------------------------------------+ 2941 | Name | Secti | URI | 2942 | | on | | 2943 +-------------+-------+---------------------------------------------+ 2944 | depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 | 2945 | | | .0 | 2946 | fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: | 2947 | | | 1.0 | 2948 | filter | 4.8.6 | urn:ietf:params:restconf:capability:filter: | 2949 | | | 1.0 | 2950 | replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: | 2951 | | 4.8.8 | 1.0 | 2952 | with- | 4.8.9 | urn:ietf:params:restconf:capability:with- | 2953 | defaults | | defaults:1.0 | 2954 +-------------+-------+---------------------------------------------+ 2956 RESTCONF Query Parameter URIs 2958 9.1.2. The "defaults" Protocol Capability URI 2960 This URI identifies the defaults handling mode that is used by the 2961 server for processing default leafs in requests for data resources. 2962 A parameter named "basic-mode" is required for this capability URI. 2963 The "basic-mode" definitions are specified in the "With-Defaults 2964 Capability for NETCONF" [RFC6243]. 2966 +----------+--------------------------------------------------+ 2967 | Name | URI | 2968 +----------+--------------------------------------------------+ 2969 | defaults | urn:ietf:params:restconf:capability:defaults:1.0 | 2970 +----------+--------------------------------------------------+ 2972 RESTCONF defaults capability URI 2974 This protocol capability URI MUST be supported by the server, and 2975 MUST be listed in the "capability" leaf-list in Section 9.3. 2977 +------------------+------------------------------------------------+ 2978 | Value | Description | 2979 +------------------+------------------------------------------------+ 2980 | report-all | No data nodes are considered default | 2981 | trim | Values set to the YANG default-stmt value are | 2982 | | default | 2983 | explicit | Values set by the client are never considered | 2984 | | default | 2985 +------------------+------------------------------------------------+ 2987 If the "basic-mode" is set to "report-all" then the server MUST 2988 adhere to the defaults handling behavior defined in Section 2.1 of 2989 [RFC6243]. 2991 If the "basic-mode" is set to "trim" then the server MUST adhere to 2992 the defaults handling behavior defined in Section 2.2 of [RFC6243]. 2994 If the "basic-mode" is set to "explicit" then the server MUST adhere 2995 to the defaults handling behavior defined in Section 2.3 of 2996 [RFC6243]. 2998 Example: (split for display purposes only) 3000 urn:ietf:params:restconf:capability:defaults:1.0? 3001 basic-mode=explicit 3003 9.2. restconf-state/streams 3005 This optional container provides access to the event notification 3006 streams supported by the server. The server MAY omit this container 3007 if no event notification streams are supported. 3009 The server will populate this container with a stream list entry for 3010 each stream type it supports. Each stream contains a leaf called 3011 "events" which contains a URI that represents an event stream 3012 resource. 3014 Stream resources are defined in Section 3.8. Notifications are 3015 defined in Section 6. 3017 9.3. RESTCONF Monitoring Module 3019 The "ietf-restconf-monitoring" module defines monitoring information 3020 for the RESTCONF protocol. 3022 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 3023 are used by this module for some type definitions. 3025 RFC Ed.: update the date below with the date of RFC publication and 3026 remove this note. 3028 file "ietf-restconf-monitoring@2015-06-19.yang" 3030 module ietf-restconf-monitoring { 3031 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; 3032 prefix "rcmon"; 3034 import ietf-yang-types { prefix yang; } 3035 import ietf-inet-types { prefix inet; } 3037 organization 3038 "IETF NETCONF (Network Configuration) Working Group"; 3040 contact 3041 "WG Web: 3042 WG List: 3044 WG Chair: Mehmet Ersue 3045 3047 WG Chair: Mahesh Jethanandani 3048 3050 Editor: Andy Bierman 3051 3053 Editor: Martin Bjorklund 3054 3056 Editor: Kent Watsen 3057 "; 3059 description 3060 "This module contains monitoring information for the 3061 RESTCONF protocol. 3063 Copyright (c) 2015 IETF Trust and the persons identified as 3064 authors of the code. All rights reserved. 3066 Redistribution and use in source and binary forms, with or 3067 without modification, is permitted pursuant to, and subject 3068 to the license terms contained in, the Simplified BSD License 3069 set forth in Section 4.c of the IETF Trust's Legal Provisions 3070 Relating to IETF Documents 3071 (http://trustee.ietf.org/license-info). 3073 This version of this YANG module is part of RFC XXXX; see 3074 the RFC itself for full legal notices."; 3076 // RFC Ed.: replace XXXX with actual RFC number and remove this 3077 // note. 3079 // RFC Ed.: remove this note 3080 // Note: extracted from draft-ietf-netconf-restconf-08.txt 3082 // RFC Ed.: update the date below with the date of RFC publication 3083 // and remove this note. 3084 revision 2015-06-19 { 3085 description 3086 "Initial revision."; 3087 reference 3088 "RFC XXXX: RESTCONF Protocol."; 3089 } 3091 container restconf-state { 3092 config false; 3093 description 3094 "Contains RESTCONF protocol monitoring information."; 3096 container capabilities { 3097 description 3098 "Contains a list of protocol capability URIs"; 3100 leaf-list capability { 3101 type inet:uri; 3102 description "A RESTCONF protocol capability URI."; 3103 } 3104 } 3106 container streams { 3107 description 3108 "Container representing the notification event streams 3109 supported by the server."; 3110 reference 3111 "RFC 5277, Section 3.4, element."; 3113 list stream { 3114 key name; 3115 description 3116 "Each entry describes an event stream supported by 3117 the server."; 3119 leaf name { 3120 type string; 3121 description "The stream name"; 3122 reference "RFC 5277, Section 3.4, element."; 3123 } 3124 leaf description { 3125 type string; 3126 description "Description of stream content"; 3127 reference 3128 "RFC 5277, Section 3.4, element."; 3129 } 3131 leaf replay-support { 3132 type boolean; 3133 description 3134 "Indicates if replay buffer supported for this stream. 3135 If 'true', then the server MUST support the 'start-time' 3136 and 'stop-time' query parameters for this stream."; 3137 reference 3138 "RFC 5277, Section 3.4, element."; 3139 } 3141 leaf replay-log-creation-time { 3142 when "../replay-support" { 3143 description 3144 "Only present if notification replay is supported"; 3145 } 3146 type yang:date-and-time; 3147 description 3148 "Indicates the time the replay log for this stream 3149 was created."; 3150 reference 3151 "RFC 5277, Section 3.4, 3152 element."; 3153 } 3155 list access { 3156 key encoding; 3157 min-elements 1; 3158 description 3159 "The server will create an entry in this list for each 3160 encoding format that is supported for this stream. 3161 The media type 'application/yang.stream' is expected 3162 for all event streams. This list identifies the 3163 sub-types supported for this stream."; 3165 leaf encoding { 3166 type string; 3167 description 3168 "This is the secondary encoding format within the 3169 'text/event-stream' encoding used by all streams. 3170 The type 'xml' is supported for the media type 3171 'application/yang.stream+xml'. The type 'json' 3172 is supported for the media type 3173 'application/yang.stream+json'."; 3175 } 3177 leaf location { 3178 type inet:uri; 3179 mandatory true; 3180 description 3181 "Contains a URL that represents the entry point 3182 for establishing notification delivery via server 3183 sent events."; 3184 } 3185 } 3186 } 3187 } 3188 } 3190 } 3192 3194 10. YANG Module Library 3196 The "ietf-yang-library" module defined in 3197 [I-D.ietf-netconf-yang-library] provides information about the YANG 3198 modules and submodules used by the RESTCONF server. Implementation 3199 is mandatory for RESTCONF servers. All YANG modules and submodules 3200 used by the server MUST be identified in the YANG module library. 3202 10.1. modules 3204 This mandatory container holds the identifiers for the YANG data 3205 model modules supported by the server. 3207 The server MUST maintain a last-modified timestamp for this 3208 container, and return the "Last-Modified" header when this data node 3209 is retrieved with the GET or HEAD methods. 3211 The server SHOULD maintain an entity-tag for this container, and 3212 return the "ETag" header when this data node is retrieved with the 3213 GET or HEAD methods. 3215 10.1.1. modules/module 3217 This mandatory list contains one entry for each YANG data model 3218 module supported by the server. There MUST be an instance of this 3219 list for every YANG module that is used by the server. 3221 The contents of this list are defined in the "module" YANG list 3222 statement in [I-D.ietf-netconf-yang-library]. 3224 The server MAY maintain a last-modified timestamp for each instance 3225 of this list entry, and return the "Last-Modified" header when this 3226 data node is retrieved with the GET or HEAD methods. If not 3227 supported then the timestamp for the parent "modules" container MAY 3228 be used instead. 3230 The server MAY maintain an entity-tag for each instance of this list 3231 entry, and return the "ETag" header when this data node is retrieved 3232 with the GET or HEAD methods. If not supported then the timestamp 3233 for the parent "modules" container MAY be used instead. 3235 11. IANA Considerations 3237 11.1. The "restconf" Relation Type 3239 This specification registers the "restconf" relation type in the Link 3240 Relation Type Registry defined by [RFC5988]: 3242 Relation Name: restconf 3244 Description: Identifies the root of RESTCONF API as configured 3245 on this HTTP server. The "restconf" relation 3246 defines the root of the API defined in RFCXXXX. 3247 Subsequent revisions of RESTCONF will use alternate 3248 relation values to support protocol versioning. 3250 Reference: RFC XXXX 3252 ` 3254 11.2. YANG Module Registry 3256 This document registers two URIs in the IETF XML registry [RFC3688]. 3257 Following the format in RFC 3688, the following registration is 3258 requested to be made. 3260 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 3261 Registrant Contact: The NETMOD WG of the IETF. 3262 XML: N/A, the requested URI is an XML namespace. 3264 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3265 Registrant Contact: The NETMOD WG of the IETF. 3266 XML: N/A, the requested URI is an XML namespace. 3268 This document registers two YANG modules in the YANG Module Names 3269 registry [RFC6020]. 3271 name: ietf-restconf 3272 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3273 prefix: rc 3274 // RFC Ed.: replace XXXX with RFC number and remove this note 3275 reference: RFC XXXX 3277 name: ietf-restconf-monitoring 3278 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3279 prefix: rcmon 3280 // RFC Ed.: replace XXXX with RFC number and remove this note 3281 reference: RFC XXXX 3283 11.3. application/yang Media Sub Types 3285 The parent MIME media type for RESTCONF resources is application/ 3286 yang, which is defined in [RFC6020]. This document defines the 3287 following sub-types for this media type. 3289 - api 3290 - data 3291 - datastore 3292 - errors 3293 - operation 3294 - stream 3296 Type name: application 3298 Subtype name: yang.xxx 3300 Required parameters: none 3302 Optional parameters: See section 4.8 in RFC XXXX 3304 Encoding considerations: 8-bit 3306 Security considerations: See Section 12 in RFC XXXX 3308 Interoperability considerations: none 3310 // RFC Ed.: replace XXXX with RFC number and remove this note 3311 Published specification: RFC XXXX 3313 11.4. RESTCONF Capability URNs 3315 [Note to RFC Editor: 3316 The RESTCONF Protocol Capability Registry does not yet exist; 3317 Need to ask IANA to create it; remove this note for publication 3318 ] 3320 This document defines a registry for RESTCONF capability identifiers. 3321 The name of the registry is "RESTCONF Capability URNs". The registry 3322 shall record for each entry: 3324 o the name of the RESTCONF capability. By convention, this name is 3325 prefixed with the colon ':' character. 3327 o the URN for the RESTCONF capability. 3329 This document registers several capability identifiers in "RESTCONF 3330 Capability URNs" registry: 3332 Index 3333 Capability Identifier 3334 ------------------------ 3336 :defaults 3337 urn:ietf:params:restconf:capability:defaults:1.0 3339 :depth 3340 urn:ietf:params:restconf:capability:depth:1.0 3342 :fields 3343 urn:ietf:params:restconf:capability:fields:1.0 3345 :filter 3346 urn:ietf:params:restconf:capability:filter:1.0 3348 :replay 3349 urn:ietf:params:restconf:capability:replay:1.0 3351 :with-defaults 3352 urn:ietf:params:restconf:capability:with-defaults:1.0 3354 12. Security Considerations 3356 This section provides security considerations for the resources 3357 defined by the RESTCONF protocol. Security considerations for HTTPS 3358 are defined in [RFC2818]. Security considerations for the content 3359 manipulated by RESTCONF can be found in the documents defining data 3360 models. 3362 This document does not specify an authentication scheme, but it does 3363 require that an authenticated NETCONF username be associated with 3364 each HTTP request. The authentication scheme MAY be implemented in 3365 the underlying transport layer (e.g., client certificates) or within 3366 the HTTP layer (e.g., Basic Auth, OAuth, etc.). RESTCONF does not 3367 itself define an authentication mechanism. Authentication MUST occur 3368 in a lower layer. Implementors SHOULD provide a comprehensive 3369 authorization scheme with RESTCONF and ensure that the resulting 3370 NETCONF username is made available to the RESTCONF server. 3372 Authorization of individual user access to operations and data MAY be 3373 configured via NETCONF Access Control Model (NACM) [RFC6536], as 3374 specified in Section 4. 3376 Configuration information is by its very nature sensitive. Its 3377 transmission in the clear and without integrity checking leaves 3378 devices open to classic eavesdropping and false data injection 3379 attacks. Configuration information often contains passwords, user 3380 names, service descriptions, and topological information, all of 3381 which are sensitive. Because of this, this protocol SHOULD be 3382 implemented carefully with adequate attention to all manner of attack 3383 one might expect to experience with other management interfaces. 3385 Different environments may well allow different rights prior to and 3386 then after authentication. When an operation is not properly 3387 authorized, the RESTCONF server MUST return HTTP error status code 3388 401 Unauthorized. Note that authorization information can be 3389 exchanged in the form of configuration information, which is all the 3390 more reason to ensure the security of the connection. 3392 13. Acknowledgements 3394 The authors would like to thank the following people for their 3395 contributions to this document: Ladislav Lhotka, Juergen 3396 Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. 3398 Contributions to this material by Andy Bierman are based upon work 3399 supported by the The Space & Terrestrial Communications Directorate 3400 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 3401 and conclusions or recommendations expressed in this material are 3402 those of the author(s) and do not necessarily reflect the views of 3403 The Space & Terrestrial Communications Directorate (S&TCD). 3405 14. References 3407 14.1. Normative References 3409 [I-D.ietf-netconf-yang-library] 3410 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 3411 Library", draft-ietf-netconf-yang-library-01 (work in 3412 progress), July 2015. 3414 [I-D.ietf-netmod-rfc6020bis] 3415 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 3416 draft-ietf-netmod-rfc6020bis-07 (work in progress), 3417 September 2015. 3419 [I-D.ietf-netmod-yang-json] 3420 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3421 draft-ietf-netmod-yang-json-06 (work in progress), October 3422 2015. 3424 [I-D.ietf-netmod-yang-metadata] 3425 Lhotka, L., "Defining and Using Metadata with YANG", 3426 draft-ietf-netmod-yang-metadata-02 (work in progress), 3427 September 2015. 3429 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3430 Extensions (MIME) Part Two: Media Types", RFC 2046, 3431 November 1996. 3433 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3434 Requirement Levels", BCP 14, RFC 2119, March 1997. 3436 [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. 3438 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3439 January 2004. 3441 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3442 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3443 3986, January 2005. 3445 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 3446 Authentication Protocol", RFC 4252, January 2006. 3448 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3449 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3451 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3452 Notifications", RFC 5277, July 2008. 3454 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3455 Housley, R., and T. Polk, "Internet X.509 Public Key 3456 Infrastructure Certificate and Certificate Revocation List 3457 (CRL) Profile", RFC 5280, May 2008. 3459 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3460 5789, March 2010. 3462 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3464 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 3465 Network Configuration Protocol (NETCONF)", RFC 6020, 3466 October 2010. 3468 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3469 Verification of Domain-Based Application Service Identity 3470 within Internet Public Key Infrastructure Using X.509 3471 (PKIX) Certificates in the Context of Transport Layer 3472 Security (TLS)", RFC 6125, March 2011. 3474 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3475 and A. Bierman, Ed., "Network Configuration Protocol 3476 (NETCONF)", RFC 6241, June 2011. 3478 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 3479 NETCONF", RFC 6243, June 2011. 3481 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 3482 6415, October 2011. 3484 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 3485 Protocol (NETCONF) Access Control Model", RFC 6536, March 3486 2012. 3488 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3489 and D. Orchard, "URI Template", RFC 6570, March 2012. 3491 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 3492 July 2013. 3494 [RFC7158] Bray, T., Ed., "The JSON Data Interchange Format", RFC 3495 7158, March 2013. 3497 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3498 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 3499 2014. 3501 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3502 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3504 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3505 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 3507 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3508 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3510 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 3511 7320, July 2014. 3513 [W3C.CR-eventsource-20121211] 3514 Hickson, I., "Server-Sent Events", World Wide Web 3515 Consortium CR CR-eventsource-20121211, December 2012, 3516 . 3518 [W3C.REC-xml-20081126] 3519 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 3520 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 3521 Edition)", World Wide Web Consortium Recommendation REC- 3522 xml-20081126, November 2008, 3523 . 3525 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 3526 Version 1.0", World Wide Web Consortium Recommendation 3527 REC-xpath-19991116, November 1999, 3528 . 3530 [draft-ietf-httpauth-basicauth-update-03] 3531 Reschke, J., "The 'Basic' HTTP Authentication Scheme", 3532 draft-ietf-httpauth-basicauth-update-03 (work in 3533 progress), Dec 2014. 3535 [draft-ietf-httpauth-digest-09] 3536 Shekh-Yusef, R., Reschke, D., and S. Bremer, "HTTP Digest 3537 Access Authentication", draft-ietf-httpauth-digest-09 3538 (work in progress), Dec 2014. 3540 [draft-ietf-netconf-rfc5539bis-10] 3541 Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 3542 NETCONF Protocol over Transport Layer Security (TLS) with 3543 Mutual X.509 Authentication", draft-ietf-netconf- 3544 rfc5539bis-10 (work in progress), Dec 2014. 3546 [draft-thomson-httpbis-cant-01] 3547 Thomson, M., "Client Authentication over New TLS 3548 Connection", draft-thomson-httpbis-cant-01 (work in 3549 progress), Jul 2014. 3551 14.2. Informative References 3553 [I-D.ietf-netconf-yang-patch] 3554 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 3555 Media Type", draft-ietf-netconf-yang-patch-06 (work in 3556 progress), October 2015. 3558 [rest-dissertation] 3559 Fielding, R., "Architectural Styles and the Design of 3560 Network-based Software Architectures", 2000. 3562 Appendix A. Change Log 3564 -- RFC Ed.: remove this section before publication. 3566 The RESTCONF issue tracker can be found here: https://github.com/ 3567 netconf-wg/restconf/issues 3569 A.1. 07 - 08 3571 o add support for YANG 1.1 action statement 3573 o changed mandatory encoding from XML to XML or JSON 3575 o fix syntax in fields parameter definition 3577 o add meta-data encoding examples for XML and JSON 3579 o remove RFC 2396 references and update with 3986 3581 o change encoding of a key so quoted string are not used, since they 3582 are already percent-encoded. A zero-length string is not encoded 3583 (/list=foo,,baz) 3585 o Add example of percent-encoded key value 3587 A.2. 06 - 07 3589 o fixed all issues identified in email from Jernej Tuljak in netconf 3590 email 2015-06-22 3592 o fixed error example bug where error-urlpath was still used. 3593 Changed to error-path. 3595 o added mention of YANG Patch and informative reference 3597 o added support for YANG 1.1, specifically support for anydata and 3598 actions 3600 o removed the special field value "*", since it is no longer needed 3602 A.3. 05 - 06 3604 o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) 3606 A.4. 04 - 05 3608 o changed term 'notification event' to 'event notification' 3610 o removed intro text about framework and meta-model 3612 o removed early mention of API resources 3614 o removed term unified datastore and cleaned up text about NETCONF 3615 datastores 3617 o removed text about not immediate persistence of edits 3619 o removed RESTCONF-specific data-resource-identifier typedef and its 3620 usage 3622 o clarified encoding of key leafs 3624 o changed several examples from JSON to XML encoding 3626 o made 'insert' and 'point' query parameters mandatory to implement 3628 o removed ":insert" capability URI 3630 o renamed stream/encoding to stream/access 3632 o renamed stream/encoding/type to stream/access/encoding 3634 o renamed stream/encoding/events to stream/access/location 3636 o changed XPath from informative to normative reference 3638 o changed rest-dissertation from normative to informative reference 3640 o changed example-jukebox playlist 'id' from a data-resource- 3641 identifier to a leafref pointing at the song name 3643 A.5. 03 - 04 3645 o renamed 'select' to 'fields' (#1) 3647 o moved collection resource and page capability to draft-ietf- 3648 netconf-restconf-collection-00 (#3) 3650 o added mandatory "defaults" protocol capability URI (#4) 3652 o added optional "with-defaults" query parameter URI (#4) 3654 o clarified authentication procedure (#9) 3656 o moved ietf-yang-library module to draft-ietf-netconf-yang- 3657 library-00 (#13) 3659 o clarified that JSON encoding of module name in a URI MUST follow 3660 the netmod-yang-json encoding rules (#14) 3662 o added restconf-media-type extension (#15) 3664 o remove "content" query parameter URI and made this parameter 3665 mandatory (#16) 3667 o clarified datastore usage 3669 o changed lock-denied error example 3671 o added with-defaults query parameter example 3673 o added term "RESTCONF Capability" 3675 o changed NETCONF Capability URI registry usage to new RESTCONF 3676 Capability URI Registry usage 3678 A.6. 02 - 03 3680 o added collection resource 3682 o added "page" query parameter capability 3684 o added "limit" and "offset" query parameters, which are available 3685 if the "page" capability is supported 3687 o added "stream list" term 3689 o fixed bugs in some examples 3690 o added "encoding" list within the "stream" list to allow different 3691 URLs for XML and JSON encoding. 3693 o made XML MUST implement and JSON MAY implement for servers 3695 o re-add JSON notification examples (previously removed) 3697 o updated JSON references 3699 A.7. 01 - 02 3701 o moved query parameter definitions from the YANG module back to the 3702 plain text sections 3704 o made all query parameters optional to implement 3706 o defined query parameter capability URI 3708 o moved 'streams' to new YANG module (ietf-restconf-monitoring) 3710 o added 'capabilities' container to new YANG module (ietf-restconf- 3711 monitoring) 3713 o moved 'modules' container to new YANG module (ietf-yang-library) 3715 o added new leaf 'module-set-id' (ietf-yang-library) 3717 o added new leaf 'conformance' (ietf-yang-library) 3719 o changed 'schema' leaf to type inet:uri that returns the location 3720 of the YANG schema (instead of returning the schema directly) 3722 o changed 'events' leaf to type inet:uri that returns the location 3723 of the event stream resource (instead of returning events 3724 directly) 3726 o changed examples for yang.api resource since the monitoring 3727 information is no longer in this resource 3729 o closed issue #1 'select parameter' since no objections to the 3730 proposed syntax 3732 o closed "encoding of list keys" issue since no objection to new 3733 encoding of list keys in a target resource URI. 3735 o moved open issues list to the issue tracker on github 3737 A.8. 00 - 01 3739 o fixed content=nonconfig example (non-config was incorrect) 3741 o closed open issue 'message-id'. There is no need for a message-id 3742 field, and RFC 2392 does not apply. 3744 o closed open issue 'server support verification'. The headers used 3745 by RESTCONF are widely supported. 3747 o removed encoding rules from section on RESTCONF Meta-Data. This 3748 is now defined in "I-D.lhotka-netmod-yang-json". 3750 o added media type application/yang.errors to map to errors YANG 3751 grouping. Updated error examples to use new media type. 3753 o closed open issue 'additional datastores'. Support may be added 3754 in the future to identify new datastores. 3756 o closed open issue 'PATCH media type discovery'. The section on 3757 PATCH has an added sentence on the Accept-Patch header. 3759 o closed open issue 'YANG to resource mapping'. Current mapping of 3760 all data nodes to resources will be used in order to allow 3761 mandatory DELETE support. The PATCH operation is optional, as 3762 well as the YANG Patch media type. 3764 o closed open issue '_self links for HATEOAS support'. It was 3765 decided that they are redundant because they can be derived from 3766 the YANG module for the specific data. 3768 o added explanatory text for the 'select' parameter. 3770 o added RESTCONF Path Resolution section for discovering the root of 3771 the RESTCONF API using the /.well-known/host-meta. 3773 o added an "error" media type to for structured error messages 3775 o added Secure Transport section requiring TLS 3777 o added Security Considerations section 3779 o removed all references to "REST-like" 3781 A.9. bierman:restconf-04 to ietf:restconf-00 3783 o updated open issues section 3785 Appendix B. Open Issues 3787 -- RFC Ed.: remove this section before publication. 3789 The RESTCONF issues are tracked on github.com: 3791 https://github.com/netconf-wg/restconf/issues 3793 Appendix C. Example YANG Module 3795 The example YANG module used in this document represents a simple 3796 media jukebox interface. 3798 YANG Tree Diagram for "example-jukebox" Module 3800 +--rw jukebox! 3801 +--rw library 3802 | +--rw artist* [name] 3803 | | +--rw name string 3804 | | +--rw album* [name] 3805 | | +--rw name string 3806 | | +--rw genre? identityref 3807 | | +--rw year? uint16 3808 | | +--rw admin 3809 | | | +--rw label? string 3810 | | | +--rw catalogue-number? string 3811 | | +--rw song* [name] 3812 | | +--rw name string 3813 | | +--rw location string 3814 | | +--rw format? string 3815 | | +--rw length? uint32 3816 | +--ro artist-count? uint32 3817 | +--ro album-count? uint32 3818 | +--ro song-count? uint32 3819 +--rw playlist* [name] 3820 | +--rw name string 3821 | +--rw description? string 3822 | +--rw song* [index] 3823 | +--rw index uint32 3824 | +--rw id leafref 3825 +--rw player 3826 +--rw gap? decimal64 3828 rpcs: 3830 +---x play 3831 +--ro input 3832 +--ro playlist string 3833 +--ro song-number uint32 3835 C.1. example-jukebox YANG Module 3837 module example-jukebox { 3839 namespace "http://example.com/ns/example-jukebox"; 3840 prefix "jbox"; 3842 organization "Example, Inc."; 3843 contact "support at example.com"; 3844 description "Example Jukebox Data Model Module"; 3845 revision "2015-04-04" { 3846 description "Initial version."; 3847 reference "example.com document 1-4673"; 3848 } 3850 identity genre { 3851 description "Base for all genre types"; 3852 } 3854 // abbreviated list of genre classifications 3855 identity alternative { 3856 base genre; 3857 description "Alternative music"; 3858 } 3859 identity blues { 3860 base genre; 3861 description "Blues music"; 3862 } 3863 identity country { 3864 base genre; 3865 description "Country music"; 3866 } 3867 identity jazz { 3868 base genre; 3869 description "Jazz music"; 3870 } 3871 identity pop { 3872 base genre; 3873 description "Pop music"; 3874 } 3875 identity rock { 3876 base genre; 3877 description "Rock music"; 3879 } 3881 container jukebox { 3882 presence 3883 "An empty container indicates that the jukebox 3884 service is available"; 3886 description 3887 "Represents a jukebox resource, with a library, playlists, 3888 and a play operation."; 3890 container library { 3892 description "Represents the jukebox library resource."; 3894 list artist { 3895 key name; 3897 description 3898 "Represents one artist resource within the 3899 jukebox library resource."; 3901 leaf name { 3902 type string { 3903 length "1 .. max"; 3904 } 3905 description "The name of the artist."; 3906 } 3908 list album { 3909 key name; 3911 description 3912 "Represents one album resource within one 3913 artist resource, within the jukebox library."; 3915 leaf name { 3916 type string { 3917 length "1 .. max"; 3918 } 3919 description "The name of the album."; 3920 } 3922 leaf genre { 3923 type identityref { base genre; } 3924 description 3925 "The genre identifying the type of music on 3926 the album."; 3928 } 3930 leaf year { 3931 type uint16 { 3932 range "1900 .. max"; 3933 } 3934 description "The year the album was released"; 3935 } 3937 container admin { 3938 description 3939 "Administrative information for the album."; 3941 leaf label { 3942 type string; 3943 description "The label that released the album."; 3944 } 3945 leaf catalogue-number { 3946 type string; 3947 description "The album's catalogue number."; 3948 } 3949 } 3951 list song { 3952 key name; 3954 description 3955 "Represents one song resource within one 3956 album resource, within the jukebox library."; 3958 leaf name { 3959 type string { 3960 length "1 .. max"; 3961 } 3962 description "The name of the song"; 3963 } 3964 leaf location { 3965 type string; 3966 mandatory true; 3967 description 3968 "The file location string of the 3969 media file for the song"; 3970 } 3971 leaf format { 3972 type string; 3973 description 3974 "An identifier string for the media type 3975 for the file associated with the 3976 'location' leaf for this entry."; 3977 } 3978 leaf length { 3979 type uint32; 3980 units "seconds"; 3981 description 3982 "The duration of this song in seconds."; 3983 } 3984 } // end list 'song' 3985 } // end list 'album' 3986 } // end list 'artist' 3988 leaf artist-count { 3989 type uint32; 3990 units "songs"; 3991 config false; 3992 description "Number of artists in the library"; 3993 } 3994 leaf album-count { 3995 type uint32; 3996 units "albums"; 3997 config false; 3998 description "Number of albums in the library"; 3999 } 4000 leaf song-count { 4001 type uint32; 4002 units "songs"; 4003 config false; 4004 description "Number of songs in the library"; 4005 } 4006 } // end library 4008 list playlist { 4009 key name; 4011 description 4012 "Example configuration data resource"; 4014 leaf name { 4015 type string; 4016 description 4017 "The name of the playlist."; 4018 } 4019 leaf description { 4020 type string; 4021 description 4022 "A comment describing the playlist."; 4023 } 4024 list song { 4025 key index; 4026 ordered-by user; 4028 description 4029 "Example nested configuration data resource"; 4031 leaf index { // not really needed 4032 type uint32; 4033 description 4034 "An arbitrary integer index for this playlist song."; 4035 } 4036 leaf id { 4037 type leafref { 4038 path "/jbox:jukebox/jbox:library/jbox:artist/" + 4039 "jbox:album/jbox:song/jbox:name"; 4040 } 4041 mandatory true; 4042 description 4043 "Song identifier. Must identify an instance of 4044 /jukebox/library/artist/album/song/name."; 4045 } 4046 } 4047 } 4049 container player { 4050 description 4051 "Represents the jukebox player resource."; 4053 leaf gap { 4054 type decimal64 { 4055 fraction-digits 1; 4056 range "0.0 .. 2.0"; 4057 } 4058 units "tenths of seconds"; 4059 description "Time gap between each song"; 4060 } 4061 } 4062 } 4064 rpc play { 4065 description "Control function for the jukebox player"; 4066 input { 4067 leaf playlist { 4068 type string; 4069 mandatory true; 4070 description "playlist name"; 4071 } 4072 leaf song-number { 4073 type uint32; 4074 mandatory true; 4075 description "Song number in playlist to play"; 4076 } 4077 } 4078 } 4079 } 4081 Appendix D. RESTCONF Message Examples 4083 The examples within this document use the normative YANG module 4084 defined in Section 8 and the non-normative example YANG module 4085 defined in Appendix C.1. 4087 This section shows some typical RESTCONF message exchanges. 4089 D.1. Resource Retrieval Examples 4091 D.1.1. Retrieve the Top-level API Resource 4093 The client may start by retrieving the top-level API resource, using 4094 the entry point URI "{+restconf}". 4096 GET /restconf HTTP/1.1 4097 Host: example.com 4098 Accept: application/yang.api+json 4100 The server might respond as follows: 4102 HTTP/1.1 200 OK 4103 Date: Mon, 23 Apr 2012 17:01:00 GMT 4104 Server: example-server 4105 Content-Type: application/yang.api+json 4107 { 4108 "ietf-restconf:restconf": { 4109 "data" : [ null ], 4110 "operations" : [ null ] 4111 } 4112 } 4114 To request that the response content to be encoded in XML, the 4115 "Accept" header can be used, as in this example request: 4117 GET /restconf HTTP/1.1 4118 Host: example.com 4119 Accept: application/yang.api+xml 4121 The server will return the same response either way, which might be 4122 as follows : 4124 HTTP/1.1 200 OK 4125 Date: Mon, 23 Apr 2012 17:01:00 GMT 4126 Server: example-server 4127 Cache-Control: no-cache 4128 Pragma: no-cache 4129 Content-Type: application/yang.api+xml 4131 4132 4133 4134 4136 D.1.2. Retrieve The Server Module Information 4138 In this example the client is retrieving the modules information from 4139 the server in JSON format: 4141 GET /restconf/data/ietf-yang-library:modules HTTP/1.1 4142 Host: example.com 4143 Accept: application/yang.data+json 4145 The server might respond as follows. 4147 HTTP/1.1 200 OK 4148 Date: Mon, 23 Apr 2012 17:01:00 GMT 4149 Server: example-server 4150 Cache-Control: no-cache 4151 Pragma: no-cache 4152 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4153 Content-Type: application/yang.data+json 4155 { 4156 "ietf-yang-library:modules": { 4157 "module": [ 4158 { 4159 "name" : "foo", 4160 "revision" : "2012-01-02", 4161 "schema" : "https://example.com/modules/foo/2012-01-02", 4162 "namespace" : "http://example.com/ns/foo", 4163 "feature" : [ "feature1", "feature2" ], 4164 "conformance" : "implement" 4166 }, 4167 { 4168 "name" : "foo-types", 4169 "revision" : "2012-01-05", 4170 "schema" : 4171 "https://example.com/modules/foo-types/2012-01-05", 4172 "schema" : [null], 4173 "namespace" : "http://example.com/ns/foo-types", 4174 "conformance" : "import" 4175 }, 4176 { 4177 "name" : "bar", 4178 "revision" : "2012-11-05", 4179 "schema" : "https://example.com/modules/bar/2012-11-05", 4180 "namespace" : "http://example.com/ns/bar", 4181 "feature" : [ "bar-ext" ], 4182 "conformance" : "implement", 4183 "submodule" : [ 4184 { 4185 "name" : "bar-submod1", 4186 "revision" : "2012-11-05", 4187 "schema" : 4188 "https://example.com/modules/bar-submod1/2012-11-05" 4189 }, 4190 { 4191 "name" : "bar-submod2", 4192 "revision" : "2012-11-05", 4193 "schema" : 4194 "https://example.com/modules/bar-submod2/2012-11-05" 4195 } 4196 ] 4197 } 4198 ] 4199 } 4200 } 4202 D.1.3. Retrieve The Server Capability Information 4204 In this example the client is retrieving the capability information 4205 from the server in JSON format, and the server supports all the 4206 RESTCONF query parameters, plus one vendor parameter: 4208 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 4209 capabilities HTTP/1.1 4210 Host: example.com 4211 Accept: application/yang.data+xml 4212 The server might respond as follows. The extra whitespace in 4213 'capability' elements for display purposes only. 4215 HTTP/1.1 200 OK 4216 Date: Mon, 23 Apr 2012 17:02:00 GMT 4217 Server: example-server 4218 Cache-Control: no-cache 4219 Pragma: no-cache 4220 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4221 Content-Type: application/yang.data+xml 4223 4224 4225 urn:ietf:params:restconf:capability:depth:1.0 4226 4227 4228 urn:ietf:params:restconf:capability:fields:1.0 4229 4230 4231 urn:ietf:params:restconf:capability:filter:1.0 4232 4233 4234 urn:ietf:params:restconf:capability:start-time:1.0 4235 4236 4237 urn:ietf:params:restconf:capability:stop-time:1.0 4238 4239 4240 http://example.com/capabilities/myparam 4241 4242 4244 D.2. Edit Resource Examples 4246 D.2.1. Create New Data Resources 4248 To create a new "artist" resource within the "library" resource, the 4249 client might send the following request. 4251 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 4252 Host: example.com 4253 Content-Type: application/yang.data+json 4255 { 4256 "example-jukebox:artist" : { 4257 "name" : "Foo Fighters" 4258 } 4259 } 4261 If the resource is created, the server might respond as follows. 4262 Note that the "Location" header line is wrapped for display purposes 4263 only: 4265 HTTP/1.1 201 Created 4266 Date: Mon, 23 Apr 2012 17:02:00 GMT 4267 Server: example-server 4268 Location: https://example.com/restconf/data/ 4269 example-jukebox:jukebox/library/artist=Foo%20Fighters 4270 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 4271 ETag: b3830f23a4c 4273 To create a new "album" resource for this artist within the "jukebox" 4274 resource, the client might send the following request. Note that the 4275 request URI header line is wrapped for display purposes only: 4277 POST /restconf/data/example-jukebox:jukebox/ 4278 library/artist=Foo%20Fighters HTTP/1.1 4279 Host: example.com 4280 Content-Type: application/yang.data+json 4282 { 4283 "example-jukebox:album" : { 4284 "name" : "Wasting Light", 4285 "genre" : "example-jukebox:alternative", 4286 "year" : 2012 # note this is the wrong date 4287 } 4288 } 4290 If the resource is created, the server might respond as follows. 4291 Note that the "Location" header line is wrapped for display purposes 4292 only: 4294 HTTP/1.1 201 Created 4295 Date: Mon, 23 Apr 2012 17:03:00 GMT 4296 Server: example-server 4297 Location: https://example.com/restconf/data/ 4298 example-jukebox:jukebox/library/artist=Foo%20Fighters/ 4299 album=Wasting%20Light 4300 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 4301 ETag: b8389233a4c 4303 D.2.2. Detect Resource Entity Tag Change 4304 In this example, the server just supports the mandatory datastore 4305 last-changed timestamp. The client has previously retrieved the 4306 "Last-Modified" header and has some value cached to provide in the 4307 following request to patch an "album" list entry with key value 4308 "Wasting Light". Only the "year" field is being updated. 4310 PATCH /restconf/data/example-jukebox:jukebox/ 4311 library/artist=Foo%20Fighters/album=Wasting%20Light/year 4312 HTTP/1.1 4313 Host: example.com 4314 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 4315 Content-Type: application/yang.data+json 4317 { "example-jukebox:year" : "2011" } 4319 In this example the datastore resource has changed since the time 4320 specified in the "If-Unmodified-Since" header. The server might 4321 respond: 4323 HTTP/1.1 412 Precondition Failed 4324 Date: Mon, 23 Apr 2012 19:01:00 GMT 4325 Server: example-server 4326 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 4327 ETag: b34aed893a4c 4329 D.2.3. Edit a Datastore Resource 4331 In this example, the client modifies two different data nodes by 4332 sending a PATCH to the datastore resource: 4334 PATCH /restconf/data HTTP/1.1 4335 Host: example.com 4336 Content-Type: application/yang.datastore+xml 4338 4339 4340 4341 4342 Foo Fighters 4343 4344 Wasting Light 4345 2011 4346 4347 4348 4349 Nick Cave 4350 4351 Tender Prey 4352 1988 4353 4354 4355 4356 4357 4359 D.3. Query Parameter Examples 4361 D.3.1. "content" Parameter 4363 The "content" parameter is used to select the type of data child 4364 resources (configuration and/or not configuration) that are returned 4365 by the server for a GET method request. 4367 In this example, a simple YANG list that has configuration and non- 4368 configuration child resources. 4370 container events 4371 list event { 4372 key name; 4373 leaf name { type string; } 4374 leaf description { type string; } 4375 leaf event-count { 4376 type uint32; 4377 config false; 4378 } 4379 } 4380 } 4382 Example 1: content=all 4384 To retrieve all the child resources, the "content" parameter is set 4385 to "all". The client might send: 4387 GET /restconf/data/example-events:events?content=all 4388 HTTP/1.1 4389 Host: example.com 4390 Accept: application/yang.data+json 4392 The server might respond: 4394 HTTP/1.1 200 OK 4395 Date: Mon, 23 Apr 2012 17:11:30 GMT 4396 Server: example-server 4397 Cache-Control: no-cache 4398 Pragma: no-cache 4399 Content-Type: application/yang.data+json 4400 { 4401 "example-events:events" : { 4402 "event" : [ 4403 { 4404 "name" : "interface-up", 4405 "description" : "Interface up notification count", 4406 "event-count" : 42 4407 }, 4408 { 4409 "name" : "interface-down", 4410 "description" : "Interface down notification count", 4411 "event-count" : 4 4412 } 4413 ] 4414 } 4415 } 4417 Example 2: content=config 4419 To retrieve only the configuration child resources, the "content" 4420 parameter is set to "config" or omitted since this is the default 4421 value. Note that the "ETag" and "Last-Modified" headers are only 4422 returned if the content parameter value is "config". 4424 GET /restconf/data/example-events:events?content=config 4425 HTTP/1.1 4426 Host: example.com 4427 Accept: application/yang.data+json 4429 The server might respond: 4431 HTTP/1.1 200 OK 4432 Date: Mon, 23 Apr 2012 17:11:30 GMT 4433 Server: example-server 4434 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4435 ETag: eeeada438af 4436 Cache-Control: no-cache 4437 Pragma: no-cache 4438 Content-Type: application/yang.data+json 4440 { 4441 "example-events:events" : { 4442 "event" : [ 4443 { 4444 "name" : "interface-up", 4445 "description" : "Interface up notification count" 4446 }, 4447 { 4448 "name" : "interface-down", 4449 "description" : "Interface down notification count" 4450 } 4451 ] 4452 } 4453 } 4455 Example 3: content=nonconfig 4457 To retrieve only the non-configuration child resources, the "content" 4458 parameter is set to "nonconfig". Note that configuration ancestors 4459 (if any) and list key leafs (if any) are also returned. The client 4460 might send: 4462 GET /restconf/data/example-events:events?content=nonconfig 4463 HTTP/1.1 4464 Host: example.com 4465 Accept: application/yang.data+json 4467 The server might respond: 4469 HTTP/1.1 200 OK 4470 Date: Mon, 23 Apr 2012 17:11:30 GMT 4471 Server: example-server 4472 Cache-Control: no-cache 4473 Pragma: no-cache 4474 Content-Type: application/yang.data+json 4476 { 4477 "example-events:events" : { 4478 "event" : [ 4479 { 4480 "name" : "interface-up", 4481 "event-count" : 42 4482 }, 4483 { 4484 "name" : "interface-down", 4485 "event-count" : 4 4486 } 4487 ] 4488 } 4489 } 4491 D.3.2. "depth" Parameter 4493 The "depth" parameter is used to limit the number of levels of child 4494 resources that are returned by the server for a GET method request. 4496 The depth parameter starts counting levels at the level of the target 4497 resource that is specified, so that a depth level of "1" includes 4498 just the target resource level itself. A depth level of "2" includes 4499 the target resource level and its child nodes. 4501 This example shows how different values of the "depth" parameter 4502 would affect the reply content for retrieval of the top-level 4503 "jukebox" data resource. 4505 Example 1: depth=unbounded 4507 To retrieve all the child resources, the "depth" parameter is not 4508 present or set to the default value "unbounded". Note that some 4509 strings are wrapped for display purposes only. 4511 GET /restconf/data/example-jukebox:jukebox?depth=unbounded 4512 HTTP/1.1 4513 Host: example.com 4514 Accept: application/yang.data+json 4516 The server might respond: 4518 HTTP/1.1 200 OK 4519 Date: Mon, 23 Apr 2012 17:11:30 GMT 4520 Server: example-server 4521 Cache-Control: no-cache 4522 Pragma: no-cache 4523 Content-Type: application/yang.data+json 4525 { 4526 "example-jukebox:jukebox" : { 4527 "library" : { 4528 "artist" : [ 4529 { 4530 "name" : "Foo Fighters", 4531 "album" : [ 4532 { 4533 "name" : "Wasting Light", 4534 "genre" : "example-jukebox:alternative", 4535 "year" : 2011, 4536 "song" : [ 4537 { 4538 "name" : "Wasting Light", 4539 "location" : 4540 "/media/foo/a7/wasting-light.mp3", 4541 "format" : "MP3", 4542 "length" " 286 4543 }, 4544 { 4545 "name" : "Rope", 4546 "location" : "/media/foo/a7/rope.mp3", 4547 "format" : "MP3", 4548 "length" " 259 4549 } 4550 ] 4551 } 4552 ] 4553 } 4554 ] 4555 }, 4556 "playlist" : [ 4557 { 4558 "name" : "Foo-One", 4559 "description" : "example playlist 1", 4560 "song" : [ 4561 { 4562 "index" : 1, 4563 "id" : "https://example.com/restconf/data/ 4564 example-jukebox:jukebox/library/artist= 4565 Foo%20Fighters/album=Wasting%20Light/ 4566 song=Rope" 4567 }, 4568 { 4569 "index" : 2, 4570 "id" : "https://example.com/restconf/data/ 4571 example-jukebox:jukebox/library/artist= 4572 Foo%20Fighters/album=Wasting%20Light/song= 4573 Bridge%20Burning" 4574 } 4575 ] 4576 } 4577 ], 4578 "player" : { 4579 "gap" : 0.5 4580 } 4581 } 4582 } 4584 Example 2: depth=1 4585 To determine if 1 or more resource instances exist for a given target 4586 resource, the value "1" is used. 4588 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 4589 Host: example.com 4590 Accept: application/yang.data+json 4592 The server might respond: 4594 HTTP/1.1 200 OK 4595 Date: Mon, 23 Apr 2012 17:11:30 GMT 4596 Server: example-server 4597 Cache-Control: no-cache 4598 Pragma: no-cache 4599 Content-Type: application/yang.data+json 4601 { 4602 "example-jukebox:jukebox" : [null] 4603 } 4605 Example 3: depth=3 4607 To limit the depth level to the target resource plus 2 child resource 4608 layers the value "3" is used. 4610 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 4611 Host: example.com 4612 Accept: application/yang.data+json 4614 The server might respond: 4616 HTTP/1.1 200 OK 4617 Date: Mon, 23 Apr 2012 17:11:30 GMT 4618 Server: example-server 4619 Cache-Control: no-cache 4620 Pragma: no-cache 4621 Content-Type: application/yang.data+json 4623 { 4624 "example-jukebox:jukebox" : { 4625 "library" : { 4626 "artist" : [ null ] 4627 }, 4628 "playlist" : [ 4629 { 4630 "name" : "Foo-One", 4631 "description" : "example playlist 1", 4632 "song" : [ null ] 4634 } 4635 ], 4636 "player" : { 4637 "gap" : 0.5 4638 } 4639 } 4640 } 4642 D.3.3. "fields" Parameter 4644 In this example the client is retrieving the API resource, but 4645 retrieving only the "name" and "revision" nodes from each module, in 4646 JSON format: 4648 GET /restconf/data?fields=ietf-yang-library:modules/ 4649 module(name;revision) HTTP/1.1 4650 Host: example.com 4651 Accept: application/yang.data+json 4653 The server might respond as follows. 4655 HTTP/1.1 200 OK 4656 Date: Mon, 23 Apr 2012 17:01:00 GMT 4657 Server: example-server 4658 Content-Type: application/yang.data+json 4660 { 4661 "ietf-yang-library:modules": { 4662 "module": [ 4663 { 4664 "name" : "example-jukebox", 4665 "revision" : "2015-06-04" 4666 }, 4667 { 4668 "name" : "ietf-inet-types", 4669 "revision" : "2013-07-15" 4670 }, 4671 { 4672 "name" : "ietf-restconf-monitoring", 4673 "revision" : "2015-06-19" 4674 }, 4675 { 4676 "name" : "ietf-yang-library", 4677 "revision" : "2015-07-03" 4678 }, 4679 { 4680 "name" : "ietf-yang-types", 4681 "revision" : "2013-07-15" 4683 } 4685 ] 4686 } 4687 } 4689 D.3.4. "insert" Parameter 4691 In this example, a new first entry in the "Foo-One" playlist is being 4692 created. 4694 Request from client: 4696 POST /restconf/data/example-jukebox:jukebox/ 4697 playlist=Foo-One?insert=first HTTP/1.1 4698 Host: example.com 4699 Content-Type: application/yang.data+json 4701 { 4702 "example-jukebox:song" : { 4703 "index" : 1, 4704 "id" : "/example-jukebox:jukebox/library/ 4705 artist=Foo%20Fighters/album=Wasting%20Light/song=Rope" 4706 } 4707 } 4709 Response from server: 4711 HTTP/1.1 201 Created 4712 Date: Mon, 23 Apr 2012 13:01:20 GMT 4713 Server: example-server 4714 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4715 Location: https://example.com/restconf/data/ 4716 example-jukebox:jukebox/playlist=Foo-One/song=1 4717 ETag: eeeada438af 4719 D.3.5. "point" Parameter 4721 In this example, the client is inserting a new "song" resource within 4722 an "album" resource after another song. The request URI is split for 4723 display purposes only. 4725 Request from client: 4727 POST /restconf/data/example-jukebox:jukebox/ 4728 library/artist=Foo%20Fighters/album=Wasting%20Light? 4729 insert=after&point=%2Fexample-jukebox%3Ajukebox%2F 4730 library%2Fartist%2FFoo%20Fighters%2Falbum%2F 4731 Wasting%20Light%2Fsong%2FBridge%20Burning HTTP/1.1 4732 Host: example.com 4733 Content-Type: application/yang.data+json 4735 { 4736 "example-jukebox:song" : { 4737 "name" : "Rope", 4738 "location" : "/media/foo/a7/rope.mp3", 4739 "format" : "MP3", 4740 "length" : 259 4741 } 4742 } 4744 Response from server: 4746 HTTP/1.1 204 No Content 4748 1. Date: Mon, 23 Apr 2012 13:01:20 GMT Server: example-server Last- 4749 Modified: Mon, 23 Apr 2012 13:01:20 GMT ETag: abcada438af 4751 D.3.6. "filter" Parameter 4753 The following URIs show some examples of notification filter 4754 specifications (lines wrapped for display purposes only): 4756 // filter = /event/event-class='fault' 4757 GET /mystreams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' 4759 // filter = /event/severity<=4 4760 GET /mystreams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 4762 // filter = /linkUp|/linkDown 4763 GET /mystreams/SNMP?filter=%2FlinkUp%7C%2FlinkDown 4765 // filter = /*/reporting-entity/card!='Ethernet0' 4766 GET /mystreams/NETCONF? 4767 filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' 4769 // filter = /*/email-addr[contains(.,'company.com')] 4770 GET /mystreams/critical-syslog? 4771 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 4773 // Note: the module name is used as prefix. 4774 // filter = (/example-mod:event1/name='joe' and 4775 // /example-mod:event1/status='online') 4776 GET /mystreams/NETCONF? 4777 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and 4778 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 4780 D.3.7. "start-time" Parameter 4782 // start-time = 2014-10-25T10:02:00Z 4783 GET /mystreams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z 4785 D.3.8. "stop-time" Parameter 4787 // stop-time = 2014-10-25T12:31:00Z 4788 GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z 4790 D.3.9. "with-defaults" Parameter 4792 The following YANG module is assumed for this example. 4794 module example-interface { 4795 prefix "exif"; 4796 namespace "urn:example.com:params:xml:ns:yang:example-interface"; 4798 container interfaces { 4799 list interface { 4800 key name; 4801 leaf name { type string; } 4802 leaf mtu { type uint32; } 4803 leaf status { 4804 config false; 4805 type enumeration { 4806 enum up; 4807 enum down; 4808 enum testing; 4809 } 4810 } 4811 } 4812 } 4813 } 4815 Assume the same data model as defined in Appendix A.1 of [RFC6243]. 4816 Assume the same data set as defined in Appendix A.2 of [RFC6243]. If 4817 the server defaults-uri basic-mode is "trim", the the following 4818 request for interface "eth1" might be as follows: 4820 Without query parameter: 4822 GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1 4823 Host: example.com 4824 Accept: application/yang.data+json 4826 The server might respond as follows. 4828 HTTP/1.1 200 OK 4829 Date: Mon, 23 Apr 2012 17:01:00 GMT 4830 Server: example-server 4831 Content-Type: application/yang.data+json 4833 { 4834 "example:interface": [ 4835 { 4836 "name" : "eth1", 4837 "status" : "up" 4838 } 4839 ] 4840 } 4842 Note that the "mtu" leaf is missing because it is set to the default 4843 "1500", and the server defaults handling basic-mode is "trim". 4845 With query parameter: 4847 GET /restconf/data/example:interfaces/interface=eth1 4848 ?with-defaults=report-all HTTP/1.1 4849 Host: example.com 4850 Accept: application/yang.data+json 4852 The server might respond as follows. 4854 HTTP/1.1 200 OK 4855 Date: Mon, 23 Apr 2012 17:01:00 GMT 4856 Server: example-server 4857 Content-Type: application/yang.data+json 4859 { 4860 "example:interface": [ 4861 { 4862 "name" : "eth1", 4863 "mtu" : 1500, 4864 "status" : "up" 4865 } 4866 ] 4867 } 4869 Note that the server returns the "mtu" leaf because the "report-all" 4870 mode was requested with the "with-defaults" query parameter. 4872 Authors' Addresses 4873 Andy Bierman 4874 YumaWorks 4876 Email: andy@yumaworks.com 4878 Martin Bjorklund 4879 Tail-f Systems 4881 Email: mbj@tail-f.com 4883 Kent Watsen 4884 Juniper Networks 4886 Email: kwatsen@juniper.net