idnits 2.17.1 draft-ietf-netconf-restconf-09.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 1947 has weird spacing: '... method entry...' == Line 2893 has weird spacing: '...ncoding strin...' == Line 2894 has weird spacing: '...ocation inet:...' == Line 3794 has weird spacing: '...ocation str...' == Line 3804 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 (December 15, 2015) is 3052 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) -- Looks like a reference, but probably isn't: '1' on line 3772 == 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 (==), 4 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: June 17, 2016 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 December 15, 2015 10 RESTCONF Protocol 11 draft-ietf-netconf-restconf-09 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 June 17, 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 . . . . . . . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . . 17 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 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 . . . . . . . . . . . . . 39 105 4.8.6. The "filter" Query Parameter . . . . . . . . . . . . 39 106 4.8.7. The "start‑time" Query Parameter . . . . . . . 40 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 . . . . . . . . . . . . . . . . . . . . 45 113 5.4. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 45 114 5.4.1. XML MetaData Encoding Example . . . . . . . . . . . . 45 115 5.4.2. JSON MetaData Encoding Example . . . . . . . . . . . 46 116 5.5. Return Status . . . . . . . . . . . . . . . . . . . . . . 47 117 5.6. Message Caching . . . . . . . . . . . . . . . . . . . . . 47 118 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 47 119 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 47 120 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 48 121 6.3. Subscribing to Receive Notifications . . . . . . . . . . 49 122 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 50 123 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 51 124 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 53 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 . . . . . . . 64 131 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 64 132 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 65 133 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 68 134 10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 69 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 . . . . . . . . . . . . . . . . . . 70 139 11.3. application/yang Media Sub Types . . . . . . . . . . . . 70 140 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 71 141 12. Security Considerations . . . . . . . . . . . . . . . . . . . 72 142 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 73 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. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 76 148 A.2. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 76 149 A.3. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 77 150 A.4. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 77 151 A.5. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 77 152 A.6. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 78 153 A.7. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 79 154 A.8. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 79 155 A.9. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 80 156 A.10. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 81 157 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 81 158 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 81 159 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 82 160 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 87 161 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 87 162 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 87 163 D.1.2. Retrieve The Server Module Information . . . . . . . 88 164 D.1.3. Retrieve The Server Capability Information . . . . . 90 165 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 90 166 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 91 167 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 92 168 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 92 169 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 93 170 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 93 171 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 96 172 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 99 173 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 100 174 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 100 175 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 101 176 D.3.7. "start‑time" Parameter . . . . . . . . . . . . 102 177 D.3.8. "stop‑time" Parameter . . . . . . . . . . . . . 102 178 D.3.9. "with‑defaults" Parameter . . . . . . . . . . . 102 179 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 104 181 1. Introduction 183 There is a need for standard mechanisms to allow Web applications to 184 access the configuration data, operational data, data-model specific 185 protocol operations, and event notifications within a networking 186 device, in a modular and extensible manner. 188 This document describes an HTTP [RFC7230] based protocol called 189 RESTCONF, for accessing data defined in YANG version 1 [RFC6020] or 190 YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using datastores 191 defined in NETCONF [RFC6241]. 193 The NETCONF protocol defines configuration datastores and a set of 194 Create, Retrieve, Update, Delete (CRUD) operations that can be used 195 to access these datastores. The YANG language defines the syntax and 196 semantics of datastore content, operational data, protocol 197 operations, and event notifications. RESTCONF uses HTTP operations 198 to provide CRUD operations on a NETCONF datastore containing YANG- 199 defined data. Since NETCONF protocol operations are not relevant, 200 the user should not need any prior knowledge of NETCONF in order to 201 use RESTCONF. 203 Configuration data and state data are exposed as resources that can 204 be retrieved with the GET method. Resources representing 205 configuration data can be modified with the DELETE, PATCH, POST, and 206 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 207 or JSON [RFC7158]. 209 Data-model specific operations defined with the YANG "rpc" or 210 "action" statements can be invoked with the POST method. Data-model 211 specific event notifications defined with the YANG "notification" 212 statement can be accessed. 214 1.1. Simple Subset of NETCONF Functionality 216 An HTTP-based management protocol does not need to mirror the 217 functionality of the NETCONF protocol, but it needs to be compatible 218 with NETCONF. A simplified transaction model is needed that allows 219 basic CRUD operations on a hierarchy of conceptual resources. This 220 represents a limited subset of the transaction capabilities of the 221 NETCONF protocol. 223 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 224 resources represented by YANG data models. These basic edit 225 operations allow the running configuration to be altered in an all- 226 or-none fashion. This is similar to the "rollback-on-error" 227 capability in NETCONF. Edits are usually applied to one data 228 resource instance at a time. 230 The base RESTCONF protocol is intentionally simple to allow 231 deployment for as many use cases as possible. Additional 232 functionality can be defined in external documents, outside the scope 233 of this document. 235 RESTCONF is not intended to replace NETCONF, but rather provide an 236 additional simplified interface that follows REST principles and is 237 compatible with a resource-oriented device abstraction. 239 The following figure shows the system components: 241 +-----------+ +-----------------+ 242 | Web app | <-------> | | 243 +-----------+ HTTP | network device | 244 | | 245 +-----------+ | +-----------+ | 246 | NMS app | <-------> | | datastore | | 247 +-----------+ NETCONF | +-----------+ | 248 +-----------------+ 250 1.2. Data Model Driven API 252 RESTCONF combines the simplicity of the HTTP protocol with the 253 predictability and automation potential of a schema-driven API. 254 Using YANG, a client can predict all resource endpoints, much like 255 using URI Templates [RFC6570], but in a more holistic manner. This 256 strategy obviates the need for responses provided by the server to 257 contain HATEOAS links, originally described in Roy Fielding's 258 doctoral dissertation [rest-dissertation]. 260 In contrast, a REST client using HATEOAS principles would not use any 261 data modeling language to define the application-specific content of 262 the API. The client would need to discover each new child resource 263 as it traverses the URIs to discover the server capabilities. This 264 approach has the following significant weaknesses with regards to 265 control of complex networking devices: 267 o inefficient performance: configuration APIs will be quite complex 268 and may require thousands of protocol messages to discover all the 269 schema information. Typically the data type information has to be 270 passed in the protocol messages, which is also wasteful overhead. 272 o no data model richness: without a data model, the schema-level 273 semantics and validation constraints are not available to the 274 application. 276 o no tool automation: API automation tools need some sort of content 277 schema to function. Such tools can automate various programming 278 and documentation tasks related to specific data models. 280 Data models such as YANG modules serve as an "API contract" that will 281 be honored by the server. An application designer can code to the 282 data model, knowing in advance important details about the exact 283 protocol operations and datastore content a conforming server 284 implementation will support. 286 RESTCONF provides the YANG module capability information supported by 287 the server, in case the client wants to use it. The URIs for custom 288 protocol operations and datastore content are predictable, based on 289 the YANG module definitions. 291 Operational experience with CLI and SNMP indicates that operators 292 learn the location of specific service or device related data and do 293 not expect such information to be arbitrary and discovered each time 294 the client opens a management session to a server. 296 The RESTCONF protocol operates on a conceptual datastore defined with 297 the YANG data modeling language. The server lists each YANG module 298 it supports using the "ietf-yang-library" YANG module, defined in 299 [I-D.ietf-netconf-yang-library]. The server MUST implement the 300 "ietf-yang-library" module, which MUST identify all the YANG modules 301 used by the server. 303 The conceptual datastore contents, data-model-specific operations and 304 event notifications are identified by this set of YANG modules. All 305 RESTCONF content identified as either a data resource, operation 306 resource, or event stream resource is defined with the YANG language. 308 The classification of data as configuration or non-configuration is 309 derived from the YANG "config" statement. Data ordering behavior is 310 derived from the YANG "ordered-by" statement. 312 The RESTCONF datastore editing model is simple and direct, similar to 313 the behavior of the :writable-running capability in NETCONF. Each 314 RESTCONF edit of a datastore resource is activated upon successful 315 completion of the transaction. 317 1.3. Coexistence with NETCONF 319 RESTCONF can be implemented on a device that supports NETCONF. 321 If the device supports :writable-running, all edits to configuration 322 nodes in {+restconf}/data are performed in the running configuration 323 datastore. 325 Otherwise, if the device supports :candidate, all edits to 326 configuration nodes in {+restconf}/data are performed in the 327 candidate configuration datastore. The candidate is automatically 328 committed to running after a successful edit. 330 If the device supports :startup, the device automatically copies the 331 content of running to startup after running has been updated as a 332 consequence of a RESTCONF edit operation. 334 If a datastore that would be modified by a RESTCONF operation has an 335 active lock, the RESTCONF edit operation MUST fail with a 409 336 (Conflict) error code. 338 1.4. Terminology 340 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 341 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 342 "OPTIONAL" in this document are to be interpreted as described in BCP 343 14, [RFC2119]. 345 1.4.1. NETCONF 347 The following terms are defined in [RFC6241]: 349 o candidate configuration datastore 351 o client 353 o configuration data 355 o datastore 357 o configuration datastore 359 o protocol operation 361 o running configuration datastore 363 o server 365 o startup configuration datastore 367 o state data 369 o user 371 1.4.2. HTTP 372 The following terms are defined in [RFC3986]: 374 o fragment 376 o path 378 o query 380 The following terms are defined in [RFC7230]: 382 o header 384 o message-body 386 o request-line 388 o request URI 390 o status-line 392 The following terms are defined in [RFC7231]: 394 o method 396 o request 398 o resource 400 The following terms are defined in [RFC7232]: 402 o entity tag 404 1.4.3. YANG 406 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 408 o action 410 o container 412 o data node 414 o key leaf 416 o leaf 418 o leaf-list 419 o list 421 o non-presence container (or NP-container) 423 o ordered-by system 425 o ordered-by user 427 o presence container (or P-container) 429 o RPC operation (now called protocol operation) 431 1.4.4. Terms 433 The following terms are used within this document: 435 o API resource: a resource with the media type "application/ 436 yang.api+xml" or "application/yang.api+json". 438 o data resource: a resource with the media type "application/ 439 yang.data+xml" or "application/yang.data+json". Containers, 440 leafs, list entries, anydata and anyxml nodes can be data 441 resources. 443 o datastore resource: a resource with the media type "application/ 444 yang.datastore+xml" or "application/yang.datastore+json". 445 Represents a datastore. 447 o edit operation: a RESTCONF operation on a data resource using 448 either a POST, PUT, PATCH, or DELETE method. 450 o event stream resource: This resource represents an SSE (Server- 451 Sent Events) event stream. The content consists of text using the 452 media type "text/event-stream", as defined by the HTML5 453 specification. Each event represents one message 454 generated by the server. It contains a conceptual system or data- 455 model specific event that is delivered within an event 456 notification stream. Also called a "stream resource". 458 o media-type: HTTP uses Internet media types [RFC2046] in the 459 Content-Type and Accept header fields in order to provide open and 460 extensible data typing and type negotiation. 462 o operation: the conceptual RESTCONF operation for a message, 463 derived from the HTTP method, request URI, headers, and message- 464 body. 466 o operation resource: a resource with the media type "application/ 467 yang.operation+xml" or "application/yang.operation+json". 469 o patch: a generic PATCH request on the target datastore or data 470 resource. The media type of the message-body content will 471 identify the patch type in use. 473 o plain patch: a specific PATCH request type that can be used for 474 simple merge operations. 476 o query parameter: a parameter (and its value if any), encoded 477 within the query component of the request URI. 479 o RESTCONF capability: An optional RESTCONF protocol feature 480 supported by the server, which is identified by an IANA registered 481 NETCONF Capability URI, and advertised with an entry in the 482 "capability" leaf-list in Section 9.3. 484 o retrieval request: a request using the GET or HEAD methods. 486 o target resource: the resource that is associated with a particular 487 message, identified by the "path" component of the request URI. 489 o schema resource: a resource with the media type "application/ 490 yang". The YANG representation of the schema can be retrieved by 491 the client with the GET method. 493 o stream list: the set of data resource instances that describe the 494 event stream resources available from the server. This 495 information is defined in the "ietf-restconf-monitoring" module as 496 the "stream" list. It can be retrieved using the target resource 497 "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/ 498 stream". The stream list contains information about each stream, 499 such as the URL to retrieve the event stream data. 501 1.4.5. URI Template 503 Throughout this document, the URI template [RFC6570] syntax 504 "{+restconf}" is used to refer to the RESTCONF API entry point 505 outside of an example. See Section 3.1 for details. 507 For simplicity, all of the examples in this document assume "/ 508 restconf" as the discovered RESTCONF API root path. 510 1.4.6. Tree Diagrams 511 A simplified graphical representation of the data model is used in 512 this document. The meaning of the symbols in these diagrams is as 513 follows: 515 o Brackets "[" and "]" enclose list keys. 517 o Abbreviations before data node names: "rw" means configuration 518 data (read-write) and "ro" state data (read-only). 520 o Symbols after data node names: "?" means an optional node, "!" 521 means a presence container, and "*" denotes a list and leaf-list. 523 o Parentheses enclose choice and case nodes, and case nodes are also 524 marked with a colon (":"). 526 o Ellipsis ("...") stands for contents of subtrees that are not 527 shown. 529 2. Transport Protocol Requirements 531 2.1. Integrity and Confidentiality 533 HTTP [RFC7230] is an application layer protocol that may be layered 534 on any reliable transport-layer protocol. RESTCONF is defined on top 535 of HTTP, but due to the sensitive nature of the information conveyed, 536 RESTCONF requires that the transport-layer protocol provides both 537 data integrity and confidentiality, such as are provided by the TLS 538 protocol [RFC5246]. 540 2.2. HTTPS with X.509v3 Certificates 542 Given the nearly ubiquitous support for HTTP over TLS [RFC7230], 543 RESTCONF implementations MUST support the "https" URI scheme, which 544 has the IANA assigned default port 443. Consistent with the 545 exclusive use of X.509v3 certificates for NETCONF over TLS [RFC7589], 546 use of certificates in RESTCONF is also limited to X.509v3 547 certificates. 549 2.3. Certificate Validation 551 When presented an X.509 certificate, the RESTCONF peer MUST use X.509 552 certificate path validation [RFC5280] to verify the integrity of the 553 certificate. The presented X.509 certificate MAY also be considered 554 valid if it matches a locally configured certificate fingerprint. If 555 X.509 certificate path validation fails and the presented X.509 556 certificate does not match a locally configured certificate 557 fingerprint, the connection MUST be terminated as defined in 558 [RFC5246]. 560 2.4. Authenticated Server Identity 562 The RESTCONF client MUST carefully examine the certificate presented 563 by the RESTCONF server to determine if it meets the client's 564 expectations. The RESTCONF client MUST check the identity of the 565 server according to Section 6 of [RFC6125], including processing the 566 outcome as described in Section 6.6 of [RFC6125]. 568 2.5. Authenticated Client Identity 570 The RESTCONF server MUST authenticate client access to any protected 571 resource. If the RESTCONF client is not authenticated to access a 572 resource, the server MUST send an HTTP response with status code 401 573 (Unauthorized), as defined in Section 3.1 of [RFC7235]. 575 RESTCONF client authentication MUST either use TLS client 576 certificates, like NETCONF over TLS [RFC7589], or use a standard HTTP 577 Authentication scheme, see Section 5.1 in [RFC7235]. A combination 578 of both client certificates and an HTTP Authentication scheme is also 579 allowed, with the determination of how to process this combination 580 left as an implementation decision. 582 The RESTCONF client identity derived from the authentication 583 mechanism used is hereafter known as the "RESTCONF username" and 584 subject to the NETCONF Access Control Module (NACM) [RFC6536]. For 585 when a client certificate is presented, this identity MUST be derived 586 using the algorithm defined in Section 7 of [RFC7589]. For all other 587 cases, when HTTP Authentication is used, the identity is provided by 588 the HTTP Authentication scheme used. 590 3. Resources 592 The RESTCONF protocol operates on a hierarchy of resources, starting 593 with the top-level API resource itself (Section 3.1). Each resource 594 represents a manageable component within the device. 596 A resource can be considered a collection of conceptual data and the 597 set of allowed methods on that data. It can contain nested child 598 resources. The child resource types and methods allowed on them are 599 data-model specific. 601 A resource has its own media type identifier, represented by the 602 "Content-Type" header in the HTTP response message. A resource can 603 contain zero or more nested resources. A resource can be created and 604 deleted independently of its parent resource, as long as the parent 605 resource exists. 607 All RESTCONF resources are defined in this document except specific 608 datastore contents, protocol operations, and event notifications. 609 The syntax and semantics for these resource types are defined in YANG 610 modules. 612 The RESTCONF resources are accessed via a set of URIs defined in this 613 document. The set of YANG modules supported by the server will 614 determine the data model specific operations, top-level data node 615 resources, and event notification messages supported by the server. 617 The RESTCONF protocol does not include a resource discovery 618 mechanism. Instead, the definitions within the YANG modules 619 advertised by the server are used to construct a predictable 620 operation or data resource identifier. 622 3.1. Root Resource Discovery 624 In line with the best practices defined by [RFC7320], RESTCONF 625 enables deployments to specify where the RESTCONF API is located. 626 When first connecting to a RESTCONF server, a RESTCONF client MUST 627 determine the root of the RESTCONF API. The client discovers this by 628 getting the "/.well-known/host-meta" resource ([RFC6415]) and using 629 the element containing the "restconf" attribute : 631 Request 632 ------- 633 GET /.well-known/host-meta HTTP/1.1 634 Host: example.com 635 Accept: application/xrd+xml 637 Response 638 -------- 639 HTTP/1.1 200 OK 640 Content-Type: application/xrd+xml 641 Content-Length: nnn 643 644 645 647 Once discovering the RESTCONF API root, the client MUST prepend it to 648 any subsequent request to a RESTCONF resource. For instance, using 649 the "/restconf" path discovered above, the client can now determine 650 the operations supported by the the server. In this example a custom 651 "play" operation is supported: 653 Request 654 ------- 655 GET /restconf/operations HTTP/1.1 656 Host: example.com 657 Accept: application/yang.api+json 659 Response 660 -------- 661 HTTP/1.1 200 OK 662 Date: Mon, 23 Apr 2012 17:01:00 GMT 663 Server: example-server 664 Cache-Control: no-cache 665 Pragma: no-cache 666 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 667 Content-Type: application/yang.api+json 669 { "operations" : { "example-jukebox:play" : [ null ] } } 671 3.2. RESTCONF Resource Types 673 The RESTCONF protocol defines a set of application specific media 674 types to identify each of the available resource types. The 675 following resource types are defined in RESTCONF: 677 +-----------+---------------------------------+ 678 | Resource | Media Type | 679 +-----------+---------------------------------+ 680 | API | application/yang.api+xml | 681 | | application/yang.api+json | 682 | Datastore | application/yang.datastore+xml | 683 | | application/yang.datastore+json | 684 | Data | application/yang.data+xml | 685 | | application/yang.data+json | 686 | Errors | application/yang.errors+xml | 687 | | application/yang.errors+json | 688 | Operation | application/yang.operation+xml | 689 | | application/yang.operation+json | 690 | Schema | application/yang | 691 +-----------+---------------------------------+ 693 RESTCONF Media Types 695 3.3. API Resource 697 The API resource contains the entry points for the RESTCONF datastore 698 and operation resources. It is the top-level resource located at 699 {+restconf} and has the media type "application/yang.api+xml" or 700 "application/yang.api+json". 702 YANG Tree Diagram for an API Resource: 704 +--rw restconf 705 +--rw data 706 +--rw operations 708 The "application/yang.api" restconf-media-type extension in the 709 "ietf-restconf" module defined in Section 8 is used to specify the 710 structure and syntax of the conceptual child resources within the API 711 resource. 713 The API resource can be retrieved with the GET method. 715 This resource has the following child resources: 717 +----------------+--------------------------------+ 718 | Child Resource | Description | 719 +----------------+--------------------------------+ 720 | data | Contains all data resources | 721 | operations | Data-model specific operations | 722 +----------------+--------------------------------+ 724 RESTCONF API Resource 726 3.3.1. {+restconf}/data 728 This mandatory resource represents the combined configuration and 729 operational data resources that can be accessed by a client. It 730 cannot be created or deleted by the client. The datastore resource 731 type is defined in Section 3.4. 733 Example: 735 This example request by the client would retrieve only the non- 736 configuration data nodes that exist within the "library" resource, 737 using the "content" query parameter (see Section 4.8.1). 739 GET /restconf/data/example-jukebox:jukebox/library 740 ?content=nonconfig HTTP/1.1 741 Host: example.com 742 Accept: application/yang.data+xml 744 The server might respond: 746 HTTP/1.1 200 OK 747 Date: Mon, 23 Apr 2012 17:01:30 GMT 748 Server: example-server 749 Cache-Control: no-cache 750 Pragma: no-cache 751 Content-Type: application/yang.data+xml 752 753 42 754 59 755 374 756 758 3.3.2. {+restconf}/operations 760 This optional resource is a container that provides access to the 761 data-model specific protocol operations supported by the server. The 762 server MAY omit this resource if no data-model specific operations 763 are advertised. 765 Any data-model specific protocol operations defined in the YANG 766 modules advertised by the server MAY be available as child nodes of 767 this resource. 769 Operation resources are defined in Section 3.6. 771 3.4. Datastore Resource 773 The "{+restconf}/data" subtree represents the datastore resource 774 type, which is a collection of configuration and operational data 775 nodes. 777 This resource type is an abstraction of the system's underlying 778 datastore implementation. It is used to simplify resource editing 779 for the client. The RESTCONF datastore resource is a conceptual 780 collection of all configuration and operational data that is present 781 on the device. 783 Configuration edit transaction management and configuration 784 persistence are handled by the server and not controlled by the 785 client. A datastore resource can only be written directly with the 786 PATCH method. Each RESTCONF edit of a datastore resource is saved to 787 non-volatile storage by the server. 789 3.4.1. Edit Collision Detection 791 Two "edit collision detection" mechanisms are provided in RESTCONF, 792 for datastore and data resources. 794 3.4.1.1. Timestamp 795 The last change time is maintained and the "Last-Modified" 796 ([RFC7232], Section 2.2) header is returned in the response for a 797 retrieval request. The "If-Unmodified-Since" header can be used in 798 edit operation requests to cause the server to reject the request if 799 the resource has been modified since the specified timestamp. 801 The server MUST maintain a last-modified timestamp for the top-level 802 {+restconf}/data resource and SHOULD maintain last-modified 803 timestamps for descendant resources. For all resources, the server 804 MUST return the "Last-Modified" header when the resource is retrieved 805 with the GET or HEAD methods. If the server does not maintain a 806 timestamp for a resource, it MUST return the timestamp of the 807 resource's ancestor, a process that may recurse up to the top-level 808 {+restconf}/data resource. Only changes to configuration data 809 resources within the datastore affect the timestamp. 811 3.4.1.2. Entity tag 813 A unique opaque string is maintained and the "ETag" ([RFC7232], 814 Section 2.3) header is returned in the response for a retrieval 815 request. The "If-Match" header can be used in edit operation 816 requests to cause the server to reject the request if the resource 817 entity tag does not match the specified value. 819 The server MUST maintain an entity tag for the top-level {+restconf}/ 820 data resource and SHOULD maintain entity tags for descendant 821 resources. For all resources, the server MUST return the "ETag" 822 header when the resource is retrieved with the GET or HEAD methods. 823 If the server does not maintain an entity tag for a resource, it MUST 824 return the entity tag of the resource's ancestor, a process that may 825 recurse up to the top-level {+restconf}/data resource. Only changes 826 to configuration data resources within the datastore affect the 827 entity tag. 829 3.5. Data Resource 831 A data resource represents a YANG data node that is a descendant node 832 of a datastore resource. Each YANG-defined data node can be uniquely 833 targeted by the request-line of an HTTP operation. Containers, 834 leafs, list entries, anydata and anyxml nodes are data resources. 836 The representation maintained for each data resource is the YANG 837 defined subtree for that node. HTTP operations on a data resource 838 affect both the targeted data node and all its descendants, if any. 840 For configuration data resources, the server MAY maintain a last- 841 modified timestamp for the resource, and return the "Last-Modified" 842 header when it is retrieved with the GET or HEAD methods. If 843 maintained, the resource timestamp MUST be set to the current time 844 whenever the resource or any configuration resource within the 845 resource is altered. 847 For configuration data resources, the server MAY maintain a resource 848 entity tag for the resource, and return the "ETag" header when it is 849 retrieved as the target resource with the GET or HEAD methods. If 850 maintained, the resource entity tag MUST be updated whenever the 851 resource or any configuration resource within the resource is 852 altered. 854 A data resource can be retrieved with the GET method. Data resources 855 are accessed via the "{+restconf}/data" entry point. This sub-tree 856 is used to retrieve and edit data resources. 858 A configuration data resource can be altered by the client with some 859 or all of the edit operations, depending on the target resource and 860 the specific operation. Refer to Section 4 for more details on edit 861 operations. 863 The resource definition version for a data resource is identified by 864 the revision date of the YANG module containing the YANG definition 865 for the data resource. 867 3.5.1. Encoding Data Resource Identifiers in the Request URI 869 In YANG, data nodes are named with an absolute XPath expression, 870 defined in [XPath], starting from the document root to the target 871 resource. In RESTCONF, URL encoded path expressions are used 872 instead. 874 A predictable location for a data resource is important, since 875 applications will code to the YANG data model module, which uses 876 static naming and defines an absolute path location for all data 877 nodes. 879 A RESTCONF data resource identifier is not an XPath expression. It 880 is encoded from left to right, starting with the top-level data node, 881 according to the "api-path" rule in Section 3.5.1.1. The node name 882 of each ancestor of the target resource node is encoded in order, 883 ending with the node name for the target resource. If a node in the 884 path is defined in another module than its parent node, then module 885 name followed by a colon character (":") is prepended to the node 886 name in the resource identifier. See Section 3.5.1.1 for details. 888 If a data node in the path expression is a YANG list node, then the 889 key values for the list (if any) MUST be encoded according to the 890 following rules: 892 o The key leaf values for a data resource representing a YANG list 893 MUST be encoded using one path segment [RFC3986]. 895 o If there is only one key leaf value, the path segment is 896 constructed by having the list name followed by an "=" followed by 897 the single key leaf value. 899 o If there are multiple key leaf values, the value of each leaf 900 identified in the "key" statement is encoded in the order 901 specified in the YANG "key" statement, with a comma separating 902 them. 904 o The key value is specified as a string, using the canonical 905 representation for the YANG data type. Any reserved characters 906 MUST be percent-encoded, according to [RFC3986], section 2.1. 908 o All the components in the "key" statement MUST be encoded. 909 Partial instance identifiers are not supported. 911 o A missing key value is interpreted a zero-length string. 912 (example: list=foo,,baz). 914 o The "list-instance" ABNF rule defined in Section 3.5.1.1 915 represents the syntax of a list instance identifier. 917 o Resource URI values returned in Location headers for data 918 resources MUST identify the module name, even if there are no 919 conflicting local names when the resource is created. This 920 ensures the correct resource will be identified even if the server 921 loads a new module that the old client does not know about. 923 Examples: 925 container top { 926 list list1 { 927 key "key1 key2 key3"; 928 ... 929 list list2 { 930 key "key4 key5"; 931 ... 932 leaf X { type string; } 933 } 934 } 935 } 937 For the above YANG definition, URI with key leaf values will be 938 encoded as follows (line wrapped for display purposes only): 940 /restconf/data/example-top:top/list1=key1val,key2val,key3val/ 941 list2=key4val,key5val/X 943 The following example shows how reserved characters are percent- 944 encoded within a key value. The value of "key1" contains a comma, 945 single-quote, double-quote, colon, double-quote, space, and forward 946 slash. (,'":" /). Note that double-quote is not a reserved 947 characters and does not need to be percent-encoded. The value of 948 "key2" is the empty string, and the value of "key3" is the string 949 "foo". 951 Example URL: 953 /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo 955 3.5.1.1. ABNF For Data Resource Identifiers 957 The "api-path" ABNF syntax is used to construct RESTCONF path 958 identifiers: 960 api-path = "/" | 961 ("/" api-identifier 962 0*("/" (api-identifier | list-instance ))) 964 api-identifier = [module-name ":"] identifier ;; note 1 966 module-name = identifier 968 list-instance = api-identifier "=" key-value ["," key-value]* 970 key-value = string ;; note 1 972 string = 974 ;; An identifier MUST NOT start with 975 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 976 identifier = (ALPHA / "_") 977 *(ALPHA / DIGIT / "_" / "-" / ".") 979 Note 1: The syntax for "api-identifier" and "key-value" MUST conform 980 to the JSON identifier encoding rules in Section 4 of 981 [I-D.ietf-netmod-yang-json]. 983 3.5.2. Defaults Handling 985 RESTCONF requires that a server report its default handling mode (see 986 Section 9.1.2 for details). If the optional "with-defaults" query 987 parameter is supported by the server, a client may use it to control 988 retrieval of default values (see Section 4.8.9 for details). 990 If the target of a GET method is a data node that represents a leaf 991 that has a default value, and the leaf has not been given a value 992 yet, the server MUST return the default value that is in use by the 993 server. 995 If the target of a GET method is a data node that represents a 996 container or list that has any child resources with default values, 997 for the child resources that have not been given value yet, the 998 server MAY return the default values that are in use by the server, 999 in accordance with its reported default handing mode and query 1000 parameters passed by the client. 1002 3.6. Operation Resource 1004 An operation resource represents a protocol operation defined with 1005 one of the YANG "action" or "rpc" statements. It is invoked using a 1006 POST method on the operation resource. 1008 An RPC operation is invoked as: 1010 POST {+restconf}/operations/ 1012 The field identifies the module name and rpc identifier 1013 string for the desired operation. 1015 For example, if "module-A" defined a "reset" rpc operation, then 1016 invoking the operation from "module-A" would be requested as follows: 1018 POST /restconf/operations/module-A:reset HTTP/1.1 1019 Server example.com 1021 An action is invoked as: 1023 POST {+restconf}/data// 1025 where contains the path to the data node 1026 where the action is defined, and is the name of the 1027 action. 1029 For example, if "module-A" defined a "reset-all" action in the 1030 container "interfaces", then invoking this action would be requested 1031 as follows: 1033 POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 1034 Server example.com 1036 If the "action" or "rpc" statement has an "input" section, then a 1037 message-body MAY be sent by the client in the request, otherwise the 1038 request message MUST NOT include a message-body. 1040 If the operation is successfully invoked, and if the "action" or 1041 "rpc" statement has an "output" section, then a message-body MAY be 1042 sent by the server in the response, otherwise the response message 1043 MUST NOT include a message-body in the response message, and MUST 1044 send a "204 No Content" status-line instead. 1046 If the operation is not successfully invoked, then a message-body 1047 SHOULD be sent by the server, containing an "errors" resource, as 1048 defined in Section 3.9. 1050 3.6.1. Encoding Operation Input Parameters 1052 If the "action" or "rpc" statement has an "input" section, then the 1053 "input" node is provided in the message-body, corresponding to the 1054 YANG data definition statements within the "input" section. 1056 Example: 1058 The following YANG definition is used for the examples in this 1059 section. 1061 module example-ops { 1062 namespace "https://example.com/ns/example-ops"; 1063 prefix "ops"; 1065 rpc reboot { 1066 input { 1067 leaf delay { 1068 units seconds; 1069 type uint32; 1070 default 0; 1071 } 1072 leaf message { type string; } 1073 leaf language { type string; } 1074 } 1075 } 1076 rpc get-reboot-info { 1077 output { 1078 leaf reboot-time { 1079 units seconds; 1080 type uint32; 1081 } 1082 leaf message { type string; } 1083 leaf language { type string; } 1084 } 1085 } 1086 } 1088 The client might send the following POST request message: 1090 POST /restconf/operations/example-ops:reboot HTTP/1.1 1091 Host: example.com 1092 Content-Type: application/yang.operation+xml 1094 1095 600 1096 Going down for system maintenance 1097 en-US 1098 1100 The server might respond: 1102 HTTP/1.1 204 No Content 1103 Date: Mon, 25 Apr 2012 11:01:00 GMT 1104 Server: example-server 1106 3.6.2. Encoding Operation Output Parameters 1108 If the "action" or "rpc" statement has an "output" section, then the 1109 "output" node is provided in the message-body, corresponding to the 1110 YANG data definition statements within the "output" section. 1112 Example: 1114 The "example-ops" YANG module defined in Section 3.6.1 is used for 1115 the examples in this section. 1117 The client might send the following POST request message: 1119 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 1120 Host: example.com 1121 Accept: application/yang.operation+json 1123 The server might respond: 1125 HTTP/1.1 200 OK 1126 Date: Mon, 25 Apr 2012 11:10:30 GMT 1127 Server: example-server 1128 Content-Type: application/yang.operation+json 1130 { 1131 "example-ops:output" : { 1132 "reboot-time" : 30, 1133 "message" : "Going down for system maintenance", 1134 "language" : "en-US" 1135 } 1136 } 1138 3.6.3. Encoding Operation Errors 1140 If any errors occur while attempting to invoke the operation, then an 1141 "errors" data structure is returned with the appropriate error 1142 status. 1144 Using the "reset" operation example above, the client might send the 1145 following POST request message: 1147 POST /restconf/operations/example-ops:reboot HTTP/1.1 1148 Host: example.com 1149 Content-Type: application/yang.operation+xml 1151 1152 -33 1153 Going down for system maintenance 1154 en-US 1155 1157 The server might respond with an "invalid-value" error: 1159 HTTP/1.1 400 Bad Request 1160 Date: Mon, 25 Apr 2012 11:10:30 GMT 1161 Server: example-server 1162 Content-Type: application/yang.errors+xml 1163 1164 1165 protocol 1166 invalid-value 1167 1168 err:input/err:delay 1169 1170 Invalid input parameter 1171 1172 1174 3.7. Schema Resource 1176 The server can optionally support retrieval of the YANG modules it 1177 supports, using the "ietf-yang-library" module, defined in 1178 [I-D.ietf-netconf-yang-library]. 1180 To retrieve a YANG module, a client first needs to get the URL for 1181 retrieving the schema. 1183 The client might send the following GET request message: 1185 GET /restconf/data/ietf-yang-library:modules/module= 1186 example-jukebox,2014-07-03/schema HTTP/1.1 1187 Host: example.com 1188 Accept: application/yang.data+json 1190 The server might respond: 1192 HTTP/1.1 200 OK 1193 Date: Mon, 25 Apr 2012 11:10:30 GMT 1194 Server: example-server 1195 Content-Type: application/yang.data+json 1197 { 1198 "ietf-yang-library:schema": 1199 "https://example.com/mymodules/example-jukebox/2015-06-04" 1200 } 1202 Next the client needs to retrieve the actual YANG schema. 1204 The client might send the following GET request message: 1206 GET https://example.com/mymodules/example-jukebox/2015-06-04 1207 HTTP/1.1 1208 Host: example.com 1209 Accept: application/yang 1210 The server might respond: 1212 module example-jukebox { 1214 // contents of YANG module deleted for this example... 1216 } 1218 3.8. Event Stream Resource 1220 An "event stream" resource represents a source for system generated 1221 event notifications. Each stream is created and modified by the 1222 server only. A client can retrieve a stream resource or initiate a 1223 long-poll server sent event stream, using the procedure specified in 1224 Section 6.3. 1226 A notification stream functions according to the NETCONF 1227 Notifications specification [RFC5277]. The available streams can be 1228 retrieved from the stream list, which specifies the syntax and 1229 semantics of a stream resource. 1231 3.9. Errors Media Type 1233 An "errors" media type is a collection of error information that is 1234 sent as the message-body in a server response message, if an error 1235 occurs while processing a request message. It is not considered a 1236 resource type because no instances can be retrieved with a GET 1237 request. 1239 The "ietf-restconf" YANG module contains the "application/ 1240 yang.errors" restconf-media-type extension which specifies the syntax 1241 and semantics of an "errors" media type. RESTCONF error handling 1242 behavior is defined in Section 7. 1244 4. Operations 1246 The RESTCONF protocol uses HTTP methods to identify the CRUD 1247 operation requested for a particular resource. 1249 The following table shows how the RESTCONF operations relate to 1250 NETCONF protocol operations: 1252 +----------+--------------------------------------------+ 1253 | RESTCONF | NETCONF | 1254 +----------+--------------------------------------------+ 1255 | OPTIONS | none | 1256 | HEAD | none | 1257 | GET | , | 1258 | POST | (operation="create") | 1259 | PUT | (operation="create/replace") | 1260 | PATCH | (operation="merge") | 1261 | DELETE | (operation="delete") | 1262 +----------+--------------------------------------------+ 1264 Table 1: CRUD Methods in RESTCONF 1266 The NETCONF "remove" operation attribute is not supported by the HTTP 1267 DELETE method. The resource must exist or the DELETE method will 1268 fail. The PATCH method is equivalent to a "merge" operation when 1269 using a plain patch (see Section 4.6.1), other media-types may 1270 provide more granular control. 1272 Access control mechanisms may be used to limit what operations can be 1273 used. In particular, RESTCONF is compatible with the NETCONF Access 1274 Control Model (NACM) [RFC6536], as there is a specific mapping 1275 between RESTCONF and NETCONF operations, defined in Table 1. The 1276 resource path needs to be converted internally by the server to the 1277 corresponding YANG instance-identifier. Using this information, the 1278 server can apply the NACM access control rules to RESTCONF messages. 1280 The server MUST NOT allow any operation to any resources that the 1281 client is not authorized to access. 1283 Implementation of all methods (except PATCH) are defined in 1284 [RFC7231]. This section defines the RESTCONF protocol usage for each 1285 HTTP method. 1287 4.1. OPTIONS 1289 The OPTIONS method is sent by the client to discover which methods 1290 are supported by the server for a specific resource (e.g., GET, POST, 1291 DELETE, etc.). 1293 The server SHOULD implement this method, however the same information 1294 could be extracted from the YANG modules and the RESTCONF protocol 1295 specification. 1297 If the PATCH method is supported, then the "Accept-Patch" header MUST 1298 be supported and returned in the response to the OPTIONS request, as 1299 defined in [RFC5789]. 1301 4.2. HEAD 1303 The HEAD method is sent by the client to retrieve just the headers 1304 that would be returned for the comparable GET method, without the 1305 response message-body. It is supported for all resource types, 1306 except operation resources. 1308 The request MUST contain a request URI that contains at least the 1309 entry point. The same query parameters supported by the GET method 1310 are supported by the HEAD method. 1312 The access control behavior is enforced as if the method was GET 1313 instead of HEAD. The server MUST respond the same as if the method 1314 was GET instead of HEAD, except that no response message-body is 1315 included. 1317 4.3. GET 1319 The GET method is sent by the client to retrieve data and meta-data 1320 for a resource. It is supported for all resource types, except 1321 operation resources. The request MUST contain a request URI that 1322 contains at least the entry point. 1324 The server MUST NOT return any data resources for which the user does 1325 not have read privileges. If the user is not authorized to read the 1326 target resource, an error response containing a "403 Forbidden" or 1327 "404 Not Found" status-line is returned to the client. 1329 If the user is authorized to read some but not all of the target 1330 resource, the unauthorized content is omitted from the response 1331 message-body, and the authorized content is returned to the client. 1333 Example: 1335 The client might request the response headers for an XML 1336 representation of the a specific "album" resource: 1338 GET /restconf/data/example-jukebox:jukebox/ 1339 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1340 Host: example.com 1341 Accept: application/yang.data+xml 1343 The server might respond: 1345 HTTP/1.1 200 OK 1346 Date: Mon, 23 Apr 2012 17:02:40 GMT 1347 Server: example-server 1348 Content-Type: application/yang.data+xml 1349 Cache-Control: no-cache 1350 Pragma: no-cache 1351 ETag: a74eefc993a2b 1352 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1354 1355 Wasting Light 1356 1357 g:alternative 1358 1359 2011 1360 1362 4.4. POST 1364 The POST method is sent by the client to create a data resource or 1365 invoke an operation resource. The server uses the target resource 1366 media type to determine how to process the request. 1368 +-----------+------------------------------------------------+ 1369 | Type | Description | 1370 +-----------+------------------------------------------------+ 1371 | Datastore | Create a top-level configuration data resource | 1372 | Data | Create a configuration data child resource | 1373 | Operation | Invoke a protocol operation | 1374 +-----------+------------------------------------------------+ 1376 Resource Types that Support POST 1378 4.4.1. Create Resource Mode 1380 If the target resource type is a datastore or data resource, then the 1381 POST is treated as a request to create a top-level resource or child 1382 resource, respectively. The message-body is expected to contain the 1383 content of a child resource to create within the parent (target 1384 resource). The data-model for the child tree is the subtree is 1385 defined by YANG for the child resource. 1387 The "insert" and "point" query parameters are supported by the POST 1388 method for datastore and data resource types, as specified in the 1389 YANG definition in Section 8. 1391 If the POST method succeeds, a "201 Created" status-line is returned 1392 and there is no response message-body. A "Location" header 1393 identifying the child resource that was created MUST be present in 1394 the response in this case. 1396 If the user is not authorized to create the target resource, an error 1397 response containing a "403 Forbidden" or "404 Not Found" status-line 1398 is returned to the client. All other error responses are handled 1399 according to the procedures defined in Section 7. 1401 Example: 1403 To create a new "jukebox" resource, the client might send: 1405 POST /restconf/data HTTP/1.1 1406 Host: example.com 1407 Content-Type: application/yang.data+json 1409 { "example-jukebox:jukebox" : [null] } 1411 If the resource is created, the server might respond as follows. 1412 Note that the "Location" header line is wrapped for display purposes 1413 only: 1415 HTTP/1.1 201 Created 1416 Date: Mon, 23 Apr 2012 17:01:00 GMT 1417 Server: example-server 1418 Location: https://example.com/restconf/data/ 1419 example-jukebox:jukebox 1420 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 1421 ETag: b3a3e673be2 1423 Refer to Appendix D.2.1 for more resource creation examples. 1425 4.4.2. Invoke Operation Mode 1427 If the target resource type is an operation resource, then the POST 1428 method is treated as a request to invoke that operation. The 1429 message-body (if any) is processed as the operation input parameters. 1430 Refer to Section 3.6 for details on operation resources. 1432 If the POST request succeeds, a "200 OK" status-line is returned if 1433 there is a response message-body, and a "204 No Content" status-line 1434 is returned if there is no response message-body. 1436 If the user is not authorized to invoke the target operation, an 1437 error response containing a "403 Forbidden" or "404 Not Found" 1438 status-line is returned to the client. All other error responses are 1439 handled according to the procedures defined in Section 7. 1441 Example: 1443 In this example, the client is invoking the "play" operation defined 1444 in the "example-jukebox" YANG module. 1446 A client might send a "play" request as follows: 1448 POST /restconf/operations/example-jukebox:play HTTP/1.1 1449 Host: example.com 1450 Content-Type: application/yang.operation+json 1452 { 1453 "example-jukebox:input" : { 1454 "playlist" : "Foo-One", 1455 "song-number" : 2 1456 } 1457 } 1459 The server might respond: 1461 HTTP/1.1 204 No Content 1462 Date: Mon, 23 Apr 2012 17:50:00 GMT 1463 Server: example-server 1465 4.5. PUT 1467 The PUT method is sent by the client to create or replace the target 1468 resource. 1470 The only target resource media type that supports PUT is the data 1471 resource. The message-body is expected to contain the content used 1472 to create or replace the target resource. 1474 The "insert" (Section 4.8.4) and "point" (Section 4.8.5) query 1475 parameters are supported by the PUT method for data resources. 1477 Consistent with [RFC7231], if the PUT request creates a new resource, 1478 a "201 Created" status-line is returned. If an existing resource is 1479 modified, either "200 OK" or "204 No Content" are returned. 1481 If the user is not authorized to create or replace the target 1482 resource an error response containing a "403 Forbidden" or "404 Not 1483 Found" status-line is returned to the client. All other error 1484 responses are handled according to the procedures defined in 1485 Section 7. 1487 Example: 1489 An "album" child resource defined in the "example-jukebox" YANG 1490 module is replaced or created if it does not already exist. 1492 To replace the "album" resource contents, the client might send as 1493 follows. Note that the request-line is wrapped for display purposes 1494 only: 1496 PUT /restconf/data/example-jukebox:jukebox/ 1497 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1498 Host: example.com 1499 Content-Type: application/yang.data+json 1501 { 1502 "example-jukebox:album" : { 1503 "name" : "Wasting Light", 1504 "genre" : "example-jukebox:alternative", 1505 "year" : 2011 1506 } 1507 } 1509 If the resource is updated, the server might respond: 1511 HTTP/1.1 204 No Content 1512 Date: Mon, 23 Apr 2012 17:04:00 GMT 1513 Server: example-server 1514 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 1515 ETag: b27480aeda4c 1517 4.6. PATCH 1519 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 1520 an extensible framework for resource patching mechanisms. It is 1521 optional to implement by the server. Each patch type needs a unique 1522 media type. Zero or more PATCH media types MAY be supported by the 1523 server. The media types supported by a server can be discovered by 1524 the client by sending an OPTIONS request (see Section 4.1). 1526 If the target resource instance does not exist, the server MUST NOT 1527 create it. 1529 If the PATCH request succeeds, a "200 OK" status-line is returned if 1530 there is a message-body, and "204 No Content" is returned if no 1531 response message-body is sent. 1533 If the user is not authorized to alter the target resource an error 1534 response containing a "403 Forbidden" or "404 Not Found" status-line 1535 is returned to the client. All other error responses are handled 1536 according to the procedures defined in Section 7. 1538 4.6.1. Plain Patch 1539 The plain patch mechanism merges the contents of the message body 1540 with the target resource. If the target resource is a datastore 1541 resource (see Section 3.4), the message body MUST be either 1542 application/yang.datastore+xml or application/yang.datastore+json. 1543 If then the target resource is a data resource (see Section 3.5), 1544 then the message body MUST be either application/yang.data+xml or 1545 application/yang.data+json. 1547 Plain patch can used to create or update, but not delete, a child 1548 resource within the target resource. Please see 1549 [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting 1550 more granular control. The YANG Patch Media Type allows multiple 1551 sub-operations (e.g., merge, delete) within a single PATCH operation. 1553 Example: 1555 To replace just the "year" field in the "album" resource (instead of 1556 replacing the entire resource with the PUT method), the client might 1557 send a plain patch as follows. Note that the request-line is wrapped 1558 for display purposes only: 1560 PATCH /restconf/data/example-jukebox:jukebox/ 1561 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1562 Host: example.com 1563 If-Match: b8389233a4c 1564 Content-Type: application/yang.data+xml 1566 1567 2011 1568 1570 If the field is updated, the server might respond: 1572 HTTP/1.1 204 No Content 1573 Date: Mon, 23 Apr 2012 17:49:30 GMT 1574 Server: example-server 1575 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 1576 ETag: b2788923da4c 1578 4.7. DELETE 1580 The DELETE method is used to delete the target resource. If the 1581 DELETE request succeeds, a "204 No Content" status-line is returned, 1582 and there is no response message-body. 1584 If the user is not authorized to delete the target resource then an 1585 error response containing a "403 Forbidden" or "404 Not Found" 1586 status-line is returned to the client. All other error responses are 1587 handled according to the procedures defined in Section 7. 1589 Example: 1591 To delete a resource such as the "album" resource, the client might 1592 send: 1594 DELETE /restconf/data/example-jukebox:jukebox/ 1595 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1596 Host: example.com 1598 If the resource is deleted, the server might respond: 1600 HTTP/1.1 204 No Content 1601 Date: Mon, 23 Apr 2012 17:49:40 GMT 1602 Server: example-server 1604 4.8. Query Parameters 1606 Each RESTCONF operation allows zero or more query parameters to be 1607 present in the request URI. The specific parameters that are allowed 1608 depends on the resource type, and sometimes the specific target 1609 resource used, in the request. 1611 +-------------------+-------------+---------------------------------+ 1612 | Name | Methods | Description | 1613 +-------------------+-------------+---------------------------------+ 1614 | content | GET | Select config and/or non-config | 1615 | | | data resources | 1616 | depth | GET | Request limited sub-tree depth | 1617 | | | in the reply content | 1618 | fields | GET | Request a subset of the target | 1619 | | | resource contents | 1620 | filter | GET | Boolean notification filter for | 1621 | | | event stream resources | 1622 | insert | POST, PUT | Insertion mode for user-ordered | 1623 | | | data resources | 1624 | point | POST, PUT | Insertion point for user- | 1625 | | | ordered data resources | 1626 | start-time | GET | Replay buffer start time for | 1627 | | | event stream resources | 1628 | stop-time | GET | Replay buffer stop time for | 1629 | | | event stream resources | 1630 | with-defaults | GET | Control retrieval of default | 1631 | | | values | 1632 +-------------------+-------------+---------------------------------+ 1634 RESTCONF Query Parameters 1636 Query parameters can be given in any order. Each parameter can 1637 appear at most once in a request URI. A default value may apply if 1638 the parameter is missing. 1640 Refer to Appendix D.3 for examples of query parameter usage. 1642 If vendors define additional query parameters, they SHOULD use a 1643 prefix (such as the enterprise or organization name) for query 1644 parameter names in order to avoid collisions with other parameters. 1646 4.8.1. The "content" Query Parameter 1648 The "content" parameter controls how descendant nodes of the 1649 requested data nodes will be processed in the reply. 1651 The allowed values are: 1653 +-----------+-----------------------------------------------------+ 1654 | Value | Description | 1655 +-----------+-----------------------------------------------------+ 1656 | config | Return only configuration descendant data nodes | 1657 | nonconfig | Return only non-configuration descendant data nodes | 1658 | all | Return all descendant data nodes | 1659 +-----------+-----------------------------------------------------+ 1661 This parameter is only allowed for GET methods on datastore and data 1662 resources. A 400 Bad Request error is returned if used for other 1663 methods or resource types. 1665 The default value is determined by the "config" statement value of 1666 the requested data nodes. If the "config" value is "false", then the 1667 default for the "content" parameter is "nonconfig". If "config" is 1668 "true" then the default for the "content" parameter is "config". 1670 This query parameter MUST be supported by the server. 1672 4.8.2. The "depth" Query Parameter 1673 The "depth" parameter is used to specify the number of nest levels 1674 returned in a response for a GET method. The first nest-level 1675 consists of the requested data node itself. If the "fields" 1676 parameter (Section 4.8.3) is used to select descendant data nodes, 1677 these nodes all have a depth value of 1. Any child nodes which are 1678 contained within a parent node have a depth value that is 1 greater 1679 than its parent. 1681 The value of the "depth" parameter is either an integer between 1 and 1682 65535, or the string "unbounded". "unbounded" is the default. 1684 This parameter is only allowed for GET methods on API, datastore, and 1685 data resources. A 400 Bad Request error is returned if it used for 1686 other methods or resource types. 1688 By default, the server will include all sub-resources within a 1689 retrieved resource, which have the same resource type as the 1690 requested resource. Only one level of sub-resources with a different 1691 media type than the target resource will be returned. 1693 If the "depth" query parameter URI is listed in the "capability" 1694 leaf-list in Section 9.3, then the server supports the "depth" query 1695 parameter. 1697 4.8.3. The "fields" Query Parameter 1699 The "fields" query parameter is used to optionally identify data 1700 nodes within the target resource to be retrieved in a GET method. 1701 The client can use this parameter to retrieve a subset of all nodes 1702 in a resource. 1704 A value of the "fields" query parameter matches the following rule: 1706 fields-expr = path '(' fields-expr ')' / 1707 path ';' fields-expr / 1708 path 1709 path = api-identifier [ '/' path ] 1711 "api-identifier" is defined in Section 3.5.1.1. 1713 ";" is used to select multiple nodes. For example, to retrieve only 1714 the "genre" and "year" of an album, use: "fields=genre;year". 1716 Parentheses are used to specify sub-selectors of a node. 1718 For example, assume the target resource is the "album" list. To 1719 retrieve only the "label" and "catalogue-number" of the "admin" 1720 container within an album, use: 1721 "fields=admin(label;catalogue-number)". 1723 "/" is used in a path to retrieve a child node of a node. For 1724 example, to retrieve only the "label" of an album, use: "fields=admin 1725 /label". 1727 This parameter is only allowed for GET methods on api, datastore, and 1728 data resources. A 400 Bad Request error is returned if used for 1729 other methods or resource types. 1731 If the "fields" query parameter URI is listed in the "capability" 1732 leaf-list in Section 9.3, then the server supports the "fields" 1733 parameter. 1735 4.8.4. The "insert" Query Parameter 1737 The "insert" parameter is used to specify how a resource should be 1738 inserted within a user-ordered list. 1740 The allowed values are: 1742 +-----------+-------------------------------------------------------+ 1743 | Value | Description | 1744 +-----------+-------------------------------------------------------+ 1745 | first | Insert the new data as the new first entry. | 1746 | last | Insert the new data as the new last entry. | 1747 | before | Insert the new data before the insertion point, as | 1748 | | specified by the value of the "point" parameter. | 1749 | after | Insert the new data after the insertion point, as | 1750 | | specified by the value of the "point" parameter. | 1751 +-----------+-------------------------------------------------------+ 1753 The default value is "last". 1755 This parameter is only supported for the POST and PUT methods. It is 1756 also only supported if the target resource is a data resource, and 1757 that data represents a YANG list or leaf-list that is ordered by the 1758 user. 1760 If the values "before" or "after" are used, then a "point" query 1761 parameter for the insertion parameter MUST also be present, or a 400 1762 Bad Request error is returned. 1764 The "insert" query parameter MUST be supported by the server. 1766 4.8.5. The "point" Query Parameter 1768 The "point" parameter is used to specify the insertion point for a 1769 data resource that is being created or moved within a user ordered 1770 list or leaf-list. 1772 The value of the "point" parameter is a string that identifies the 1773 path to the insertion point object. The format is the same as a 1774 target resource URI string. 1776 This parameter is only supported for the POST and PUT methods. It is 1777 also only supported if the target resource is a data resource, and 1778 that data represents a YANG list or leaf-list that is ordered by the 1779 user. 1781 If the "insert" query parameter is not present, or has a value other 1782 than "before" or "after", then a 400 Bad Request error is returned. 1784 This parameter contains the instance identifier of the resource to be 1785 used as the insertion point for a POST or PUT method. 1787 The "point" query parameter MUST be supported by the server. 1789 4.8.6. The "filter" Query Parameter 1791 The "filter" parameter is used to indicate which subset of all 1792 possible events are of interest. If not present, all events not 1793 precluded by other parameters will be sent. 1795 This parameter is only allowed for GET methods on a text/event-stream 1796 data resource. A 400 Bad Request error is returned if used for other 1797 methods or resource types. 1799 The format of this parameter is an XPath 1.0 expression, and is 1800 evaluated in the following context: 1802 o The set of namespace declarations is the set of prefix and 1803 namespace pairs for all supported YANG modules, where the prefix 1804 is the YANG module name, and the namespace is as defined by the 1805 "namespace" statement in the YANG module. 1807 o The function library is the core function library defined in XPath 1808 1.0. 1810 o The set of variable bindings is empty. 1812 o The context node is the root node. 1814 The filter is used as defined in [RFC5277], Section 3.6. If the 1815 boolean result of the expression is true when applied to the 1816 conceptual "notification" document root, then the event notification 1817 is delivered to the client. 1819 If the "filter" query parameter URI is listed in the "capability" 1820 leaf-list in Section 9.3, then the server supports the "filter" query 1821 parameter. 1823 4.8.7. The "start-time" Query Parameter 1825 The "start-time" parameter is used to trigger the notification replay 1826 feature and indicate that the replay should start at the time 1827 specified. If the stream does not support replay, per the 1828 "replay-support" attribute returned by stream list entry for the 1829 stream resource, then the server MUST return the HTTP error code 400 1830 Bad Request. 1832 The value of the "start-time" parameter is of type "date-and-time", 1833 defined in the "ietf-yang" YANG module [RFC6991]. 1835 This parameter is only allowed for GET methods on a text/event-stream 1836 data resource. A 400 Bad Request error is returned if used for other 1837 methods or resource types. 1839 If this parameter is not present, then a replay subscription is not 1840 being requested. It is not valid to specify start times that are 1841 later than the current time. If the value specified is earlier than 1842 the log can support, the replay will begin with the earliest 1843 available notification. 1845 If this query parameter is supported by the server, then the "replay" 1846 query parameter URI MUST be listed in the "capability" leaf-list in 1847 Section 9.3. The "stop-time" query parameter MUST also be supported 1848 by the server. 1850 If the "replay-support" leaf is present in the "stream" entry 1851 (defined in Section 9.3) then the server MUST support the 1852 "start-time" and "stop-time" query parameters for that stream. 1854 4.8.8. The "stop-time" Query Parameter 1856 The "stop-time" parameter is used with the replay feature to indicate 1857 the newest notifications of interest. This parameter MUST be used 1858 with and have a value later than the "start-time" parameter. 1860 The value of the "stop-time" parameter is of type "date-and-time", 1861 defined in the "ietf-yang" YANG module [RFC6991]. 1863 This parameter is only allowed for GET methods on a text/event-stream 1864 data resource. A 400 Bad Request error is returned if used for other 1865 methods or resource types. 1867 If this parameter is not present, the notifications will continue 1868 until the subscription is terminated. Values in the future are 1869 valid. 1871 If this query parameter is supported by the server, then the "replay" 1872 query parameter URI MUST be listed in the "capability" leaf-list in 1873 Section 9.3. The "start-time" query parameter MUST also be supported 1874 by the server. 1876 If the "replay-support" leaf is present in the "stream" entry 1877 (defined in Section 9.3) then the server MUST support the 1878 "start-time" and "stop-time" query parameters for that stream. 1880 4.8.9. The "with-defaults" Query Parameter 1882 The "with-defaults" parameter is used to specify how information 1883 about default data nodes should be returned in response to GET 1884 requests on data resources. 1886 If the server supports this capability, then it MUST implement the 1887 behavior in Section 4.5.1 of [RFC6243], except applied to the 1888 RESTCONF GET operation, instead of the NETCONF operations. 1890 +---------------------------+---------------------------------------+ 1891 | Value | Description | 1892 +---------------------------+---------------------------------------+ 1893 | report-all | All data nodes are reported | 1894 | trim | Data nodes set to the YANG default | 1895 | | are not reported | 1896 | explicit | Data nodes set by the client are not | 1897 | | reported | 1898 | report-all-tagged | All data nodes are reported and | 1899 | | defaults are tagged | 1900 +---------------------------+---------------------------------------+ 1902 If the "with-defaults" parameter is set to "report-all" then the 1903 server MUST adhere to the defaults reporting behavior defined in 1904 Section 3.1 of [RFC6243]. 1906 If the "with-defaults" parameter is set to "trim" then the server 1907 MUST adhere to the defaults reporting behavior defined in Section 3.2 1908 of [RFC6243]. 1910 If the "with-defaults" parameter is set to "explicit" then the server 1911 MUST adhere to the defaults reporting behavior defined in Section 3.3 1912 of [RFC6243]. 1914 If the "with-defaults" parameter is set to "report-all-tagged" then 1915 the server MUST adhere to the defaults reporting behavior defined in 1916 Section 3.4 of [RFC6243]. 1918 If the "with-defaults" parameter is not present then the server MUST 1919 adhere to the defaults reporting behavior defined in its "basic-mode" 1920 parameter for the "defaults" protocol capability URI, defined in 1921 Section 9.1.2. 1923 If the server includes the "with-defaults" query parameter URI in the 1924 "capability" leaf-list in Section 9.3, then the "with-defaults" query 1925 parameter MUST be supported. 1927 5. Messages 1929 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 1930 message corresponds to a single protocol method. Most messages can 1931 perform a single task on a single resource, such as retrieving a 1932 resource or editing a resource. The exception is the PATCH method, 1933 which allows multiple datastore edits within a single message. 1935 5.1. Request URI Structure 1937 Resources are represented with URIs following the structure for 1938 generic URIs in [RFC3986]. 1940 A RESTCONF operation is derived from the HTTP method and the request 1941 URI, using the following conceptual fields: 1943 //?# 1945 ^ ^ ^ ^ ^ 1946 | | | | | 1947 method entry resource query fragment 1949 M M O O I 1951 M=mandatory, O=optional, I=ignored 1953 replaced by client with real values 1955 o method: the HTTP method identifying the RESTCONF operation 1956 requested by the client, to act upon the target resource specified 1957 in the request URI. RESTCONF operation details are described in 1958 Section 4. 1960 o entry: the root of the RESTCONF API configured on this HTTP 1961 server, discovered by getting the ".well-known/host-meta" 1962 resource, as described in Section 3.1. 1964 o resource: the path expression identifying the resource that is 1965 being accessed by the operation. If this field is not present, 1966 then the target resource is the API itself, represented by the 1967 media type "application/yang.api". 1969 o query: the set of parameters associated with the RESTCONF message. 1970 These have the familiar form of "name=value" pairs. Most query 1971 parameters are optional to implement by the server and optional to 1972 use by the client. Each optional query parameter is identified by 1973 a URI. The server MUST list the optional query parameter URIs it 1974 supports in the "capabilities" list defined in Section 9.3. 1976 There is a specific set of parameters defined, although the server 1977 MAY choose to support query parameters not defined in this document. 1978 The contents of the any query parameter value MUST be encoded 1979 according to [RFC3986], Section 3.4. Any reserved characters MUST be 1980 percent-encoded, according to [RFC3986], section 2.1. 1982 o fragment: This field is not used by the RESTCONF protocol. 1984 When new resources are created by the client, a "Location" header is 1985 returned, which identifies the path of the newly created resource. 1986 The client MUST use this exact path identifier to access the resource 1987 once it has been created. 1989 The "target" of an operation is a resource. The "path" field in the 1990 request URI represents the target resource for the operation. 1992 5.2. Message Headers 1994 There are several HTTP header lines utilized in RESTCONF messages. 1995 Messages are not limited to the HTTP headers listed in this section. 1997 HTTP defines which header lines are required for particular 1998 circumstances. Refer to each operation definition section in 1999 Section 4 for examples on how particular headers are used. 2001 There are some request headers that are used within RESTCONF, usually 2002 applied to data resources. The following tables summarize the 2003 headers most relevant in RESTCONF message requests: 2005 +-----------------------------+-------------------------------------+ 2006 | Name | Description | 2007 +-----------------------------+-------------------------------------+ 2008 | Accept | Response Content-Types that are | 2009 | | acceptable | 2010 | Content-Type | The media type of the request body | 2011 | Host | The host address of the server | 2012 | If-Match | Only perform the action if the | 2013 | | entity matches ETag | 2014 | If-Modified-Since | Only perform the action if modified | 2015 | | since time | 2016 | If-Unmodified-Since | Only perform the action if un- | 2017 | | modified since time | 2018 +-----------------------------+-------------------------------------+ 2020 RESTCONF Request Headers 2022 The following tables summarize the headers most relevant in RESTCONF 2023 message responses: 2025 +-----------------------+-------------------------------------------+ 2026 | Name | Description | 2027 +-----------------------+-------------------------------------------+ 2028 | Allow | Valid actions when 405 error returned | 2029 | Cache-Control | The cache control parameters for the | 2030 | | response | 2031 | Content-Type | The media type of the response message- | 2032 | | body | 2033 | Date | The date and time the message was sent | 2034 | ETag | An identifier for a specific version of a | 2035 | | resource | 2036 | Last-Modified | The last modified date and time of a | 2037 | | resource | 2038 | Location | The resource identifier for a newly | 2039 | | created resource | 2040 +-----------------------+-------------------------------------------+ 2042 RESTCONF Response Headers 2044 5.3. Message Encoding 2046 RESTCONF messages are encoded in HTTP according to [RFC7230]. The 2047 "utf-8" character set is used for all messages. RESTCONF message 2048 content is sent in the HTTP message-body. 2050 Content is encoded in either JSON or XML format. A server MUST 2051 support XML or JSON encoding. XML encoding rules for data nodes are 2052 defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are 2053 used for all XML content. JSON encoding rules are defined in 2054 [I-D.ietf-netmod-yang-json]. JSON encoding of meta-data is defined 2055 in [I-D.ietf-netmod-yang-metadata]. This encoding is valid JSON, but 2056 also has special encoding rules to identify module namespaces and 2057 provide consistent type processing of YANG data. 2059 Request input content encoding format is identified with the Content- 2060 Type header. This field MUST be present if a message-body is sent by 2061 the client. 2063 The server MUST support the "Accept" header and "406 Not Acceptable" 2064 status code, as defined in [RFC7231]. Response output content 2065 encoding format is identified with the Accept header in the request. 2066 If is not specified, the request input encoding format is used. If 2067 there was no request input, then the default output encoding is XML 2068 or JSON, depending or server preference. File extensions encoded in 2069 the request are not used to identify format encoding. 2071 5.4. RESTCONF Meta-Data 2073 The RESTCONF protocol needs to retrieve the same meta-data that is 2074 used in the NETCONF protocol. Information about default leafs, last- 2075 modified timestamps, etc. are commonly used to annotate 2076 representations of the datastore contents. This meta-data is not 2077 defined in the YANG schema because it applies to the datastore, and 2078 is common across all data nodes. 2080 This information is encoded as attributes in XML. JSON encoding of 2081 meta-data is defined in [I-D.ietf-netmod-yang-metadata]. 2083 The following examples are based on the example in Appendix D.3.9. 2084 The "report-all-tagged" mode for the "with-defaults" query parameter 2085 requires that a "default" attribute be returned for default nodes. 2086 This example shows that attribute for the "mtu" leaf . 2088 5.4.1. XML MetaData Encoding Example 2090 GET /restconf/data/interfaces/interface=eth1 2091 ?with-defaults=report-all-tagged HTTP/1.1 2093 Host: example.com 2094 Accept: application/yang.data+xml 2096 The server might respond as follows. 2098 HTTP/1.1 200 OK 2099 Date: Mon, 23 Apr 2012 17:01:00 GMT 2100 Server: example-server 2101 Content-Type: application/yang.data+xml 2103 2105 eth1 2106 1500 2108 up 2109 2111 5.4.2. JSON MetaData Encoding Example 2113 Note that RFC 6243 defines the "default" attribute with XSD, not 2114 YANG, so the YANG module name has to be assigned manually. The value 2115 "ietf-netconf-with-defaults" is assigned for JSON meta-data encoding. 2117 GET /restconf/data/interfaces/interface=eth1 2118 ?with-defaults=report-all-tagged HTTP/1.1 2119 Host: example.com 2120 Accept: application/yang.data+json 2122 The server might respond as follows. 2124 HTTP/1.1 200 OK 2125 Date: Mon, 23 Apr 2012 17:01:00 GMT 2126 Server: example-server 2127 Content-Type: application/yang.data+json 2129 { 2130 "example:interface": [ 2131 { 2132 "name" : "eth1", 2133 "mtu" : 1500, 2134 "@mtu": { 2135 "ietf-netconf-with-defaults:default" : true 2136 }, 2137 "status" : "up" 2138 } 2139 ] 2140 } 2142 5.5. Return Status 2144 Each message represents some sort of resource access. An HTTP 2145 "status-line" header line is returned for each request. If a 4xx or 2146 5xx range status code is returned in the status-line, then the error 2147 information will be returned in the response, according to the format 2148 defined in Section 7.1. 2150 5.6. Message Caching 2152 Since the datastore contents change at unpredictable times, responses 2153 from a RESTCONF server generally SHOULD NOT be cached. 2155 The server SHOULD include a "Cache-Control" header in every response 2156 that specifies whether the response should be cached. A "Pragma" 2157 header specifying "no-cache" MAY also be sent in case the 2158 "Cache-Control" header is not supported. 2160 Instead of using HTTP caching, the client SHOULD track the "ETag" and 2161 /or "Last-Modified" headers returned by the server for the datastore 2162 resource (or data resource if the server supports it). A retrieval 2163 request for a resource can include the "If-None-Match" and/or 2164 "If-Modified-Since" headers, which will cause the server to return a 2165 "304 Not Modified" status-line if the resource has not changed. The 2166 client MAY use the HEAD method to retrieve just the message headers, 2167 which SHOULD include the "ETag" and "Last-Modified" headers, if this 2168 meta-data is maintained for the target resource. 2170 6. Notifications 2172 The RESTCONF protocol supports YANG-defined event notifications. The 2173 solution preserves aspects of NETCONF Event Notifications [RFC5277] 2174 while utilizing the Server-Sent Events [W3C.CR-eventsource-20121211] 2175 transport strategy. 2177 6.1. Server Support 2179 A RESTCONF server is not required to support RESTCONF notifications. 2180 Clients may determine if a server supports RESTCONF notifications by 2181 using the HTTP operation OPTIONS, HEAD, or GET on the stream list. 2182 The server does not support RESTCONF notifications if an HTTP error 2183 code is returned (e.g., 404 Not Found). 2185 6.2. Event Streams 2187 A RESTCONF server that supports notifications will populate a stream 2188 resource for each notification delivery service access point. A 2189 RESTCONF client can retrieve the list of supported event streams from 2190 a RESTCONF server using the GET operation on the stream list. 2192 The "restconf-state/streams" container definition in the 2193 "ietf-restconf-monitoring" module (defined in Section 9.3) is used to 2194 specify the structure and syntax of the conceptual child resources 2195 within the "streams" resource. 2197 For example: 2199 The client might send the following request: 2201 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2202 streams HTTP/1.1 2203 Host: example.com 2204 Accept: application/yang.data+xml 2206 The server might send the following response: 2208 HTTP/1.1 200 OK 2209 Content-Type: application/yang.api+xml 2211 2213 2214 NETCONF 2215 default NETCONF event stream 2216 2217 true 2218 2219 2007-07-08T00:00:00Z 2220 2221 2222 xml 2223 https://example.com/streams/NETCONF 2224 2225 2226 2227 json 2228 https://example.com/streams/NETCONF-JSON 2229 2230 2231 2232 2233 SNMP 2234 SNMP notifications 2235 false 2236 2237 xml 2238 https://example.com/streams/SNMP 2239 2240 2241 2242 syslog-critical 2243 Critical and higher severity 2244 2245 true 2246 2247 2007-07-01T00:00:00Z 2248 2249 2250 xml 2251 2252 https://example.com/streams/syslog-critical 2253 2254 2255 2256 2258 6.3. Subscribing to Receive Notifications 2260 RESTCONF clients can determine the URL for the subscription resource 2261 (to receive notifications) by sending an HTTP GET request for the 2262 "location" leaf with the stream list entry. The value returned by 2263 the server can be used for the actual notification subscription. 2265 The client will send an HTTP GET request for the URL returned by the 2266 server with the "Accept" type "text/event-stream". 2268 The server will treat the connection as an event stream, using the 2269 Server Sent Events [W3C.CR-eventsource-20121211] transport strategy. 2271 The server MAY support query parameters for a GET method on this 2272 resource. These parameters are specific to each notification stream. 2274 For example: 2276 The client might send the following request: 2278 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2279 streams/stream=NETCONF/access=xml/location HTTP/1.1 2280 Host: example.com 2281 Accept: application/yang.data+xml 2283 The server might send the following response: 2285 HTTP/1.1 200 OK 2286 Content-Type: application/yang.api+xml 2288 2290 https://example.com/streams/NETCONF 2291 2293 The RESTCONF client can then use this URL value to start monitoring 2294 the event stream: 2296 GET /streams/NETCONF HTTP/1.1 2297 Host: example.com 2298 Accept: text/event-stream 2299 Cache-Control: no-cache 2300 Connection: keep-alive 2302 A RESTCONF client MAY request the server compress the events using 2303 the HTTP header field "Accept-Encoding". For instance: 2305 GET /streams/NETCONF HTTP/1.1 2306 Host: example.com 2307 Accept: text/event-stream 2308 Cache-Control: no-cache 2309 Connection: keep-alive 2310 Accept-Encoding: gzip, deflate 2312 6.3.1. NETCONF Event Stream 2314 The server SHOULD support the "NETCONF" notification stream defined 2315 in [RFC5277]. For this stream, RESTCONF notification subscription 2316 requests MAY specify parameters indicating the events it wishes to 2317 receive. These query parameters are optional to implement, and only 2318 available if the server supports them. 2320 +------------+---------+-------------------------+ 2321 | Name | Section | Description | 2322 +------------+---------+-------------------------+ 2323 | start-time | 4.8.7 | replay event start time | 2324 | stop-time | 4.8.8 | replay event stop time | 2325 | filter | 4.8.6 | boolean content filter | 2326 +------------+---------+-------------------------+ 2328 NETCONF Stream Query Parameters 2330 The semantics and syntax for these query parameters are defined in 2331 the sections listed above. The YANG encoding MUST be converted to 2332 URL-encoded string for use in the request URI. 2334 Refer to Appendix D.3.6 for filter parameter examples. 2336 6.4. Receiving Event Notifications 2338 RESTCONF notifications are encoded according to the definition of the 2339 event stream. The NETCONF stream defined in [RFC5277] is encoded in 2340 XML format. 2342 The structure of the event data is based on the "notification" 2343 element definition in Section 4 of [RFC5277]. It MUST conform to the 2344 schema for the "notification" element in Section 4 of [RFC5277], 2345 except the XML namespace for this element is defined as: 2347 urn:ietf:params:xml:ns:yang:ietf-restconf 2349 For JSON encoding purposes, the module name for the "notification" 2350 element is "ietf-restconf". 2352 Two child nodes within the "notification" container are expected, 2353 representing the event time and the event payload. The "event-time" 2354 node is defined within the "ietf-restconf" module namespace. The 2355 name and namespace of the payload element are determined by the YANG 2356 module containing the notification-stmt. 2358 In the following example, the YANG module "example-mod" is used: 2360 module example-mod { 2361 namespace "http://example.com/event/1.0"; 2363 notification event { 2364 leaf event-class { type string; } 2365 container reporting-entity { 2366 leaf card { type string; } 2367 } 2368 leaf severity { type string; } 2369 } 2370 } 2372 An example SSE event notification encoded using XML: 2374 data: 2376 data: 2013-12-21T00:01:00Z 2377 data: 2378 data: fault 2379 data: 2380 data: Ethernet0 2381 data: 2382 data: major 2383 data: 2384 data: 2386 An example SSE event notification encoded using JSON: 2388 data: { 2389 data: "ietf-restconf:notification": { 2390 data: "event-time": "2013-12-21T00:01:00Z", 2391 data: "example-mod:event": { 2392 data: "event-class": "fault", 2393 data: "reporting-entity": { "card": "Ethernet0" }, 2394 data: "severity": "major" 2395 data: } 2396 data: } 2397 data: } 2399 Alternatively, since neither XML nor JSON are whitespace sensitive, 2400 the above messages can be encoded onto a single line. For example: 2402 For example: ('\' line wrapping added for formatting only) 2404 XML: 2406 data: 2013-12-21T00:01:00ZfaultEthernet0\ 2410 major 2412 JSON: 2414 data: {"ietf-restconf:notification":{"event-time":"2013-12-21\ 2415 T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ 2416 tingEntity":{"card":"Ethernet0"},"severity":"major"}}} 2418 The SSE specifications supports the following additional fields: 2419 event, id and retry. A RESTCONF server MAY send the "retry" field 2420 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 2421 SHOULD NOT send the "event" or "id" fields, as there are no 2422 meaningful values that could be used for them that would not be 2423 redundant to the contents of the notification itself. RESTCONF 2424 servers that do not send the "id" field also do not need to support 2425 the HTTP header "Last-Event-Id". RESTCONF servers that do send the 2426 "id" field MUST still support the "startTime" query parameter as the 2427 preferred means for a client to specify where to restart the event 2428 stream. 2430 7. Error Reporting 2432 HTTP status-lines are used to report success or failure for RESTCONF 2433 operations. The element returned in NETCONF error 2434 responses contains some useful information. This error information 2435 is adapted for use in RESTCONF, and error information is returned for 2436 "4xx" class of status codes. 2438 The following table summarizes the return status codes used 2439 specifically by RESTCONF operations: 2441 +----------------------------+--------------------------------------+ 2442 | Status-Line | Description | 2443 +----------------------------+--------------------------------------+ 2444 | 100 Continue | POST accepted, 201 should follow | 2445 | 200 OK | Success with response message-body | 2446 | 201 Created | POST to create a resource success | 2447 | 202 Accepted | POST to create a resource accepted | 2448 | 204 No Content | Success without response message- | 2449 | | body | 2450 | 304 Not Modified | Conditional operation not done | 2451 | 400 Bad Request | Invalid request message | 2452 | 403 Forbidden | Access to resource denied | 2453 | 404 Not Found | Resource target or resource node not | 2454 | | found | 2455 | 405 Method Not Allowed | Method not allowed for target | 2456 | | resource | 2457 | 409 Conflict | Resource or lock in use | 2458 | 412 Precondition Failed | Conditional method is false | 2459 | 413 Request Entity Too | too-big error | 2460 | Large | | 2461 | 414 Request-URI Too Large | too-big error | 2462 | 415 Unsupported Media Type | non RESTCONF media type | 2463 | 500 Internal Server Error | operation-failed | 2464 | 501 Not Implemented | unknown-operation | 2465 | 503 Service Unavailable | Recoverable server error | 2466 +----------------------------+--------------------------------------+ 2468 HTTP Status Codes used in RESTCONF 2470 Since an operation resource is defined with a YANG "action" or "rpc" 2471 statement, a mapping between the NETCONF value and the 2472 HTTP status code is needed. The specific error condition and 2473 response code to use are data-model specific and might be contained 2474 in the YANG "description" statement for the "action" or "rpc" 2475 statement. 2477 +-------------------------+-------------+ 2478 | | status code | 2479 +-------------------------+-------------+ 2480 | in-use | 409 | 2481 | invalid-value | 400 | 2482 | too-big | 413 | 2483 | missing-attribute | 400 | 2484 | bad-attribute | 400 | 2485 | unknown-attribute | 400 | 2486 | bad-element | 400 | 2487 | unknown-element | 400 | 2488 | unknown-namespace | 400 | 2489 | access-denied | 403 | 2490 | lock-denied | 409 | 2491 | resource-denied | 409 | 2492 | rollback-failed | 500 | 2493 | data-exists | 409 | 2494 | data-missing | 409 | 2495 | operation-not-supported | 501 | 2496 | operation-failed | 500 | 2497 | partial-operation | 500 | 2498 | malformed-message | 400 | 2499 +-------------------------+-------------+ 2501 Mapping from error-tag to status code 2503 7.1. Error Response Message 2505 When an error occurs for a request message on a data resource or an 2506 operation resource, and a "4xx" class of status codes (except for 2507 status code "403 Forbidden"), then the server SHOULD send a response 2508 message-body containing the information described by the "errors" 2509 container definition within the YANG module Section 8. The Content- 2510 Type of this response message MUST be application/yang.errors (see 2511 example below). 2513 The client MAY specify the desired encoding for error messages by 2514 specifying the appropriate media-type in the Accept header. If no 2515 error media is specified, then the media type of the request message 2516 is used. If there is no request message the server MUST select 2517 "application/yang.errors+xml" or "application/yang.errors+json", 2518 depending on server preference. All of the examples in this 2519 document, except for the one below, assume that XML encoding will be 2520 returned if there is an error. 2522 YANG Tree Diagram for data: 2524 +--ro errors 2525 +--ro error* 2526 +--ro error-type enumeration 2527 +--ro error-tag string 2528 +--ro error-app-tag? string 2529 +--ro error-path? instance-identifier 2530 +--ro error-message? string 2531 +--ro error-info 2533 The semantics and syntax for RESTCONF error messages are defined in 2534 the "application/yang.errors" restconf-media-type extension in 2535 Section 8. 2537 Examples: 2539 The following example shows an error returned for an "lock-denied" 2540 error that can occur if a NETCONF client has locked a datastore. The 2541 RESTCONF client is attempting to delete a data resource. Note that 2542 an Accept header is used to specify the desired encoding for the 2543 error message. This example's use of the Accept header is especially 2544 notable since the DELETE method typically doesn't return a message- 2545 body and hence Accept headers are typically not passed. 2547 DELETE /restconf/data/example-jukebox:jukebox/ 2548 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2549 Host: example.com 2550 Accept: application/yang.errors+json 2552 The server might respond: 2554 HTTP/1.1 409 Conflict 2555 Date: Mon, 23 Apr 2012 17:11:00 GMT 2556 Server: example-server 2557 Content-Type: application/yang.errors+json 2559 { 2560 "ietf-restconf:errors": { 2561 "error": [ 2562 { 2563 "error-type": "protocol", 2564 "error-tag": "lock-denied", 2565 "error-message": "Lock failed, lock already held" 2567 } 2568 ] 2569 } 2570 } 2572 The following example shows an error returned for a "data-exists" 2573 error on a data resource. The "jukebox" resource already exists so 2574 it cannot be created. 2576 The client might send: 2578 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 2579 Host: example.com 2581 The server might respond (some lines wrapped for display purposes): 2583 HTTP/1.1 409 Conflict 2584 Date: Mon, 23 Apr 2012 17:11:00 GMT 2585 Server: example-server 2586 Content-Type: application/yang.errors+xml 2588 2589 2590 protocol 2591 data-exists 2592 2595 /rc:restconf/rc:data/jb:jukebox 2596 2597 2598 Data already exists, cannot create new resource 2599 2600 2601 2603 8. RESTCONF module 2605 The "ietf-restconf" module defines conceptual definitions within an 2606 extension and two groupings, which are not meant to be implemented as 2607 datastore contents by a server. E.g., the "restconf" container is 2608 not intended to be implemented as a top-level data node (under the "/ 2609 restconf/data" entry point). 2611 RFC Ed.: update the date below with the date of RFC publication and 2612 remove this note. 2614 file "ietf-restconf@2015-10-18.yang" 2615 module ietf-restconf { 2616 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 2617 prefix "rc"; 2619 organization 2620 "IETF NETCONF (Network Configuration) Working Group"; 2622 contact 2623 "WG Web: 2624 WG List: 2626 WG Chair: Mehmet Ersue 2627 2629 WG Chair: Mahesh Jethanandani 2630 2632 Editor: Andy Bierman 2633 2635 Editor: Martin Bjorklund 2636 2638 Editor: Kent Watsen 2639 "; 2641 description 2642 "This module contains conceptual YANG specifications 2643 for basic RESTCONF media type definitions used in 2644 RESTCONF protocol messages. 2646 Note that the YANG definitions within this module do not 2647 represent configuration data of any kind. 2648 The 'restconf-media-type' YANG extension statement 2649 provides a normative syntax for XML and JSON message 2650 encoding purposes. 2652 Copyright (c) 2015 IETF Trust and the persons identified as 2653 authors of the code. All rights reserved. 2655 Redistribution and use in source and binary forms, with or 2656 without modification, is permitted pursuant to, and subject 2657 to the license terms contained in, the Simplified BSD License 2658 set forth in Section 4.c of the IETF Trust's Legal Provisions 2659 Relating to IETF Documents 2660 (http://trustee.ietf.org/license-info). 2662 This version of this YANG module is part of RFC XXXX; see 2663 the RFC itself for full legal notices."; 2665 // RFC Ed.: replace XXXX with actual RFC number and remove this 2666 // note. 2668 // RFC Ed.: remove this note 2669 // Note: extracted from draft-ietf-netconf-restconf-08.txt 2671 // RFC Ed.: update the date below with the date of RFC publication 2672 // and remove this note. 2673 revision 2015-10-18 { 2674 description 2675 "Initial revision."; 2676 reference 2677 "RFC XXXX: RESTCONF Protocol."; 2678 } 2680 extension restconf-media-type { 2681 argument media-type-id { 2682 yin-element true; 2683 } 2684 // RFC Ed.: replace draft-ietf-netmod-yang-json with RFC number 2685 // in the description below, and remove this note. 2686 description 2687 "This extension is used to specify a YANG data structure which 2688 represents a conceptual RESTCONF media type. 2689 Data definition statements within this extension specify 2690 the generic syntax for the specific media type. 2692 YANG is mapped to specific encoding formats outside the 2693 scope of this extension statement. RFC 6020 defines XML 2694 encoding rules for all RESTCONF media types that use 2695 the '+xml' suffix. draft-ietf-netmod-yang-json defines 2696 JSON encoding rules for all RESTCONF media types that 2697 use the '+json' suffix. 2699 The 'media-type-id' parameter value identifies the media type 2700 that is being defined. It contains the string associated 2701 with the generic media type, i.e., no suffix is specified. 2703 This extension is ignored unless it appears as a top-level 2704 statement. It SHOULD contain data definition statements 2705 that result in exactly one container data node definition. 2706 This allows compliant translation to an XML instance 2707 document for each media type. 2709 The module name and namespace value for the YANG module using 2710 the extension statement is assigned to instance document data 2711 conforming to the data definition statements within 2712 this extension. 2714 The sub-statements of this extension MUST follow the 2715 'data-def-stmt' rule in the YANG ABNF. 2717 The XPath document root is the extension statement itself, 2718 such that the child nodes of the document root are 2719 represented by the data-def-stmt sub-statements within 2720 this extension. This conceptual document is the context 2721 for the following YANG statements: 2723 - must-stmt 2724 - when-stmt 2725 - path-stmt 2726 - min-elements-stmt 2727 - max-elements-stmt 2728 - mandatory-stmt 2729 - unique-stmt 2730 - ordered-by 2731 - instance-identifier data type 2733 The following data-def-stmt sub-statements have special 2734 meaning when used within a restconf-resource extension 2735 statement. 2737 - The list-stmt is not required to have a key-stmt defined. 2738 - The if-feature-stmt is ignored if present. 2739 - The config-stmt is ignored if present. 2740 - The available identity values for any 'identityref' 2741 leaf or leaf-list nodes is limited to the module 2742 containing this extension statement, and the modules 2743 imported into that module. 2744 "; 2745 } 2747 rc:restconf-media-type "application/yang.errors" { 2748 uses errors; 2749 } 2751 rc:restconf-media-type "application/yang.api" { 2752 uses restconf; 2753 } 2755 grouping errors { 2756 description 2757 "A grouping that contains a YANG container 2758 representing the syntax and semantics of a 2759 YANG Patch errors report within a response message."; 2761 container errors { 2762 description 2763 "Represents an error report returned by the server if 2764 a request results in an error."; 2766 list error { 2767 description 2768 "An entry containing information about one 2769 specific error that occurred while processing 2770 a RESTCONF request."; 2771 reference "RFC 6241, Section 4.3"; 2773 leaf error-type { 2774 type enumeration { 2775 enum transport { 2776 description "The transport layer"; 2777 } 2778 enum rpc { 2779 description "The rpc or notification layer"; 2780 } 2781 enum protocol { 2782 description "The protocol operation layer"; 2783 } 2784 enum application { 2785 description "The server application layer"; 2786 } 2787 } 2788 mandatory true; 2789 description 2790 "The protocol layer where the error occurred."; 2791 } 2793 leaf error-tag { 2794 type string; 2795 mandatory true; 2796 description 2797 "The enumerated error tag."; 2798 } 2800 leaf error-app-tag { 2801 type string; 2802 description 2803 "The application-specific error tag."; 2804 } 2806 leaf error-path { 2807 type instance-identifier; 2808 description 2809 "The YANG instance identifier associated 2810 with the error node."; 2811 } 2813 leaf error-message { 2814 type string; 2815 description 2816 "A message describing the error."; 2817 } 2819 anyxml error-info { 2820 description 2821 "This anyxml value MUST represent a container with 2822 zero or more data nodes representing additional 2823 error information."; 2824 } 2825 } 2826 } 2827 } 2829 grouping restconf { 2830 description 2831 "Conceptual container representing the 2832 application/yang.api resource type."; 2834 container restconf { 2835 description 2836 "Conceptual container representing the 2837 application/yang.api resource type."; 2839 container data { 2840 description 2841 "Container representing the application/yang.datastore 2842 resource type. Represents the conceptual root of all 2843 operational data and configuration data supported by 2844 the server. The child nodes of this container can be 2845 any data resource (application/yang.data), which are 2846 defined as top-level data nodes from the YANG modules 2847 advertised by the server in the ietf-restconf-monitoring 2848 module."; 2849 } 2851 container operations { 2852 description 2853 "Container for all operation resources 2854 (application/yang.operation), 2855 Each resource is represented as an empty leaf with the 2856 name of the RPC operation from the YANG rpc statement. 2858 E.g.; 2860 POST /restconf/operations/show-log-errors 2862 leaf show-log-errors { 2863 type empty; 2864 } 2865 "; 2866 } 2867 } 2868 } 2870 } 2872 2874 9. RESTCONF Monitoring 2876 The "ietf-restconf-monitoring" module provides information about the 2877 RESTCONF protocol capabilities and event notification streams 2878 available from the server. A RESTCONF server MUST implement the "/ 2879 restconf-state/capabilities" container in this module. 2881 YANG Tree Diagram for "ietf-restconf-monitoring" module: 2883 +--ro restconf-state 2884 +--ro capabilities 2885 | +--ro capability* inet:uri 2886 +--ro streams 2887 +--ro stream* [name] 2888 +--ro name string 2889 +--ro description? string 2890 +--ro replay-support? boolean 2891 +--ro replay-log-creation-time? yang:date-and-time 2892 +--ro access* [encoding] 2893 +--ro encoding string 2894 +--ro location inet:uri 2896 9.1. restconf-state/capabilities 2898 This mandatory container holds the RESTCONF protocol capability URIs 2899 supported by the server. 2901 The server MUST maintain a last-modified timestamp for this 2902 container, and return the "Last-Modified" header when this data node 2903 is retrieved with the GET or HEAD methods. 2905 The server SHOULD maintain an entity-tag for this container, and 2906 return the "ETag" header when this data node is retrieved with the 2907 GET or HEAD methods. 2909 The server MUST include a "capability" URI leaf-list entry for the 2910 "defaults" mode used by the server, defined in Section 9.1.2. 2912 The server MUST include a "capability" URI leaf-list entry 2913 identifying each supported optional protocol feature. This includes 2914 optional query parameters and MAY include other capability URIs 2915 defined outside this document. 2917 9.1.1. Query Parameter URIs 2919 A new set of RESTCONF Capability URIs are defined to identify the 2920 specific query parameters (defined in Section 4.8) supported by the 2921 server. 2923 The server MUST include a "capability" leaf-list entry for each 2924 optional query parameter that it supports. 2926 +-------------+-------+---------------------------------------------+ 2927 | Name | Secti | URI | 2928 | | on | | 2929 +-------------+-------+---------------------------------------------+ 2930 | depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 | 2931 | | | .0 | 2932 | fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: | 2933 | | | 1.0 | 2934 | filter | 4.8.6 | urn:ietf:params:restconf:capability:filter: | 2935 | | | 1.0 | 2936 | replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: | 2937 | | 4.8.8 | 1.0 | 2938 | with- | 4.8.9 | urn:ietf:params:restconf:capability:with- | 2939 | defaults | | defaults:1.0 | 2940 +-------------+-------+---------------------------------------------+ 2942 RESTCONF Query Parameter URIs 2944 9.1.2. The "defaults" Protocol Capability URI 2946 This URI identifies the defaults handling mode that is used by the 2947 server for processing default leafs in requests for data resources. 2948 A parameter named "basic-mode" is required for this capability URI. 2949 The "basic-mode" definitions are specified in the "With-Defaults 2950 Capability for NETCONF" [RFC6243]. 2952 +----------+--------------------------------------------------+ 2953 | Name | URI | 2954 +----------+--------------------------------------------------+ 2955 | defaults | urn:ietf:params:restconf:capability:defaults:1.0 | 2956 +----------+--------------------------------------------------+ 2958 RESTCONF defaults capability URI 2960 This protocol capability URI MUST be supported by the server, and 2961 MUST be listed in the "capability" leaf-list in Section 9.3. 2963 +------------------+------------------------------------------------+ 2964 | Value | Description | 2965 +------------------+------------------------------------------------+ 2966 | report-all | No data nodes are considered default | 2967 | trim | Values set to the YANG default-stmt value are | 2968 | | default | 2969 | explicit | Values set by the client are never considered | 2970 | | default | 2971 +------------------+------------------------------------------------+ 2973 If the "basic-mode" is set to "report-all" then the server MUST 2974 adhere to the defaults handling behavior defined in Section 2.1 of 2975 [RFC6243]. 2977 If the "basic-mode" is set to "trim" then the server MUST adhere to 2978 the defaults handling behavior defined in Section 2.2 of [RFC6243]. 2980 If the "basic-mode" is set to "explicit" then the server MUST adhere 2981 to the defaults handling behavior defined in Section 2.3 of 2982 [RFC6243]. 2984 Example: (split for display purposes only) 2986 urn:ietf:params:restconf:capability:defaults:1.0? 2987 basic-mode=explicit 2989 9.2. restconf-state/streams 2990 This optional container provides access to the event notification 2991 streams supported by the server. The server MAY omit this container 2992 if no event notification streams are supported. 2994 The server will populate this container with a stream list entry for 2995 each stream type it supports. Each stream contains a leaf called 2996 "events" which contains a URI that represents an event stream 2997 resource. 2999 Stream resources are defined in Section 3.8. Notifications are 3000 defined in Section 6. 3002 9.3. RESTCONF Monitoring Module 3004 The "ietf-restconf-monitoring" module defines monitoring information 3005 for the RESTCONF protocol. 3007 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 3008 are used by this module for some type definitions. 3010 RFC Ed.: update the date below with the date of RFC publication and 3011 remove this note. 3013 file "ietf-restconf-monitoring@2015-06-19.yang" 3015 module ietf-restconf-monitoring { 3016 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; 3017 prefix "rcmon"; 3019 import ietf-yang-types { prefix yang; } 3020 import ietf-inet-types { prefix inet; } 3022 organization 3023 "IETF NETCONF (Network Configuration) Working Group"; 3025 contact 3026 "WG Web: 3027 WG List: 3029 WG Chair: Mehmet Ersue 3030 3032 WG Chair: Mahesh Jethanandani 3033 3035 Editor: Andy Bierman 3036 3038 Editor: Martin Bjorklund 3039 3041 Editor: Kent Watsen 3042 "; 3044 description 3045 "This module contains monitoring information for the 3046 RESTCONF protocol. 3048 Copyright (c) 2015 IETF Trust and the persons identified as 3049 authors of the code. All rights reserved. 3051 Redistribution and use in source and binary forms, with or 3052 without modification, is permitted pursuant to, and subject 3053 to the license terms contained in, the Simplified BSD License 3054 set forth in Section 4.c of the IETF Trust's Legal Provisions 3055 Relating to IETF Documents 3056 (http://trustee.ietf.org/license-info). 3058 This version of this YANG module is part of RFC XXXX; see 3059 the RFC itself for full legal notices."; 3061 // RFC Ed.: replace XXXX with actual RFC number and remove this 3062 // note. 3064 // RFC Ed.: remove this note 3065 // Note: extracted from draft-ietf-netconf-restconf-08.txt 3067 // RFC Ed.: update the date below with the date of RFC publication 3068 // and remove this note. 3069 revision 2015-06-19 { 3070 description 3071 "Initial revision."; 3072 reference 3073 "RFC XXXX: RESTCONF Protocol."; 3074 } 3076 container restconf-state { 3077 config false; 3078 description 3079 "Contains RESTCONF protocol monitoring information."; 3081 container capabilities { 3082 description 3083 "Contains a list of protocol capability URIs"; 3085 leaf-list capability { 3086 type inet:uri; 3087 description "A RESTCONF protocol capability URI."; 3088 } 3089 } 3091 container streams { 3092 description 3093 "Container representing the notification event streams 3094 supported by the server."; 3095 reference 3096 "RFC 5277, Section 3.4, element."; 3098 list stream { 3099 key name; 3100 description 3101 "Each entry describes an event stream supported by 3102 the server."; 3104 leaf name { 3105 type string; 3106 description "The stream name"; 3107 reference "RFC 5277, Section 3.4, element."; 3108 } 3110 leaf description { 3111 type string; 3112 description "Description of stream content"; 3113 reference 3114 "RFC 5277, Section 3.4, element."; 3115 } 3117 leaf replay-support { 3118 type boolean; 3119 description 3120 "Indicates if replay buffer supported for this stream. 3121 If 'true', then the server MUST support the 'start-time' 3122 and 'stop-time' query parameters for this stream."; 3123 reference 3124 "RFC 5277, Section 3.4, element."; 3125 } 3127 leaf replay-log-creation-time { 3128 when "../replay-support" { 3129 description 3130 "Only present if notification replay is supported"; 3131 } 3132 type yang:date-and-time; 3133 description 3134 "Indicates the time the replay log for this stream 3135 was created."; 3136 reference 3137 "RFC 5277, Section 3.4, 3138 element."; 3139 } 3141 list access { 3142 key encoding; 3143 min-elements 1; 3144 description 3145 "The server will create an entry in this list for each 3146 encoding format that is supported for this stream. 3147 The media type 'application/yang.stream' is expected 3148 for all event streams. This list identifies the 3149 sub-types supported for this stream."; 3151 leaf encoding { 3152 type string; 3153 description 3154 "This is the secondary encoding format within the 3155 'text/event-stream' encoding used by all streams. 3156 The type 'xml' is supported for the media type 3157 'application/yang.stream+xml'. The type 'json' 3158 is supported for the media type 3159 'application/yang.stream+json'."; 3161 } 3163 leaf location { 3164 type inet:uri; 3165 mandatory true; 3166 description 3167 "Contains a URL that represents the entry point 3168 for establishing notification delivery via server 3169 sent events."; 3170 } 3171 } 3172 } 3173 } 3174 } 3176 } 3178 3180 10. YANG Module Library 3181 The "ietf-yang-library" module defined in 3182 [I-D.ietf-netconf-yang-library] provides information about the YANG 3183 modules and submodules used by the RESTCONF server. Implementation 3184 is mandatory for RESTCONF servers. All YANG modules and submodules 3185 used by the server MUST be identified in the YANG module library. 3187 10.1. modules 3189 This mandatory container holds the identifiers for the YANG data 3190 model modules supported by the server. 3192 The server MUST maintain a last-modified timestamp for this 3193 container, and return the "Last-Modified" header when this data node 3194 is retrieved with the GET or HEAD methods. 3196 The server SHOULD maintain an entity-tag for this container, and 3197 return the "ETag" header when this data node is retrieved with the 3198 GET or HEAD methods. 3200 10.1.1. modules/module 3202 This mandatory list contains one entry for each YANG data model 3203 module supported by the server. There MUST be an instance of this 3204 list for every YANG module that is used by the server. 3206 The contents of this list are defined in the "module" YANG list 3207 statement in [I-D.ietf-netconf-yang-library]. 3209 The server MAY maintain a last-modified timestamp for each instance 3210 of this list entry, and return the "Last-Modified" header when this 3211 data node is retrieved with the GET or HEAD methods. If not 3212 supported then the timestamp for the parent "modules" container MAY 3213 be used instead. 3215 The server MAY maintain an entity-tag for each instance of this list 3216 entry, and return the "ETag" header when this data node is retrieved 3217 with the GET or HEAD methods. If not supported then the timestamp 3218 for the parent "modules" container MAY be used instead. 3220 11. IANA Considerations 3222 11.1. The "restconf" Relation Type 3224 This specification registers the "restconf" relation type in the Link 3225 Relation Type Registry defined by [RFC5988]: 3227 Relation Name: restconf 3228 Description: Identifies the root of RESTCONF API as configured 3229 on this HTTP server. The "restconf" relation 3230 defines the root of the API defined in RFCXXXX. 3231 Subsequent revisions of RESTCONF will use alternate 3232 relation values to support protocol versioning. 3234 Reference: RFC XXXX 3236 ` 3238 11.2. YANG Module Registry 3240 This document registers two URIs in the IETF XML registry [RFC3688]. 3241 Following the format in RFC 3688, the following registration is 3242 requested to be made. 3244 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 3245 Registrant Contact: The NETMOD WG of the IETF. 3246 XML: N/A, the requested URI is an XML namespace. 3248 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3249 Registrant Contact: The NETMOD WG of the IETF. 3250 XML: N/A, the requested URI is an XML namespace. 3252 This document registers two YANG modules in the YANG Module Names 3253 registry [RFC6020]. 3255 name: ietf-restconf 3256 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3257 prefix: rc 3258 // RFC Ed.: replace XXXX with RFC number and remove this note 3259 reference: RFC XXXX 3261 name: ietf-restconf-monitoring 3262 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3263 prefix: rcmon 3264 // RFC Ed.: replace XXXX with RFC number and remove this note 3265 reference: RFC XXXX 3267 11.3. application/yang Media Sub Types 3269 The parent MIME media type for RESTCONF resources is application/ 3270 yang, which is defined in [RFC6020]. This document defines the 3271 following sub-types for this media type. 3273 - api 3274 - data 3275 - datastore 3276 - errors 3277 - operation 3278 - stream 3280 Type name: application 3282 Subtype name: yang.xxx 3284 Required parameters: none 3286 Optional parameters: See section 4.8 in RFC XXXX 3288 Encoding considerations: 8-bit 3290 Security considerations: See Section 12 in RFC XXXX 3292 Interoperability considerations: none 3294 // RFC Ed.: replace XXXX with RFC number and remove this note 3295 Published specification: RFC XXXX 3297 11.4. RESTCONF Capability URNs 3299 [Note to RFC Editor: 3300 The RESTCONF Protocol Capability Registry does not yet exist; 3301 Need to ask IANA to create it; remove this note for publication 3302 ] 3304 This document defines a registry for RESTCONF capability identifiers. 3305 The name of the registry is "RESTCONF Capability URNs". The registry 3306 shall record for each entry: 3308 o the name of the RESTCONF capability. By convention, this name is 3309 prefixed with the colon ':' character. 3311 o the URN for the RESTCONF capability. 3313 This document registers several capability identifiers in "RESTCONF 3314 Capability URNs" registry: 3316 Index 3317 Capability Identifier 3318 ------------------------ 3320 :defaults 3321 urn:ietf:params:restconf:capability:defaults:1.0 3323 :depth 3324 urn:ietf:params:restconf:capability:depth:1.0 3326 :fields 3327 urn:ietf:params:restconf:capability:fields:1.0 3329 :filter 3330 urn:ietf:params:restconf:capability:filter:1.0 3332 :replay 3333 urn:ietf:params:restconf:capability:replay:1.0 3335 :with-defaults 3336 urn:ietf:params:restconf:capability:with-defaults:1.0 3338 12. Security Considerations 3340 This section provides security considerations for the resources 3341 defined by the RESTCONF protocol. Security considerations for HTTPS 3342 are defined in [RFC2818]. Security considerations for the content 3343 manipulated by RESTCONF can be found in the documents defining data 3344 models. 3346 This document does not specify an authentication scheme, but it does 3347 require that an authenticated NETCONF username be associated with 3348 each HTTP request. The authentication scheme MAY be implemented in 3349 the underlying transport layer (e.g., client certificates) or within 3350 the HTTP layer (e.g., Basic Auth, OAuth, etc.). RESTCONF does not 3351 itself define an authentication mechanism. Authentication MUST occur 3352 in a lower layer. Implementors SHOULD provide a comprehensive 3353 authorization scheme with RESTCONF and ensure that the resulting 3354 NETCONF username is made available to the RESTCONF server. 3356 Authorization of individual user access to operations and data MAY be 3357 configured via NETCONF Access Control Model (NACM) [RFC6536], as 3358 specified in Section 4. 3360 Configuration information is by its very nature sensitive. Its 3361 transmission in the clear and without integrity checking leaves 3362 devices open to classic eavesdropping and false data injection 3363 attacks. Configuration information often contains passwords, user 3364 names, service descriptions, and topological information, all of 3365 which are sensitive. Because of this, this protocol SHOULD be 3366 implemented carefully with adequate attention to all manner of attack 3367 one might expect to experience with other management interfaces. 3369 Different environments may well allow different rights prior to and 3370 then after authentication. When an operation is not properly 3371 authorized, the RESTCONF server MUST return HTTP error status code 3372 401 Unauthorized. Note that authorization information can be 3373 exchanged in the form of configuration information, which is all the 3374 more reason to ensure the security of the connection. 3376 13. Acknowledgements 3378 The authors would like to thank the following people for their 3379 contributions to this document: Ladislav Lhotka, Juergen 3380 Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. 3382 Contributions to this material by Andy Bierman are based upon work 3383 supported by the The Space & Terrestrial Communications Directorate 3384 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 3385 and conclusions or recommendations expressed in this material are 3386 those of the author(s) and do not necessarily reflect the views of 3387 The Space & Terrestrial Communications Directorate (S&TCD). 3389 14. References 3391 14.1. Normative References 3393 [I-D.ietf-netconf-yang-library] 3394 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 3395 Library", draft-ietf-netconf-yang-library-01 (work in 3396 progress), July 2015. 3398 [I-D.ietf-netmod-rfc6020bis] 3399 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 3400 draft-ietf-netmod-rfc6020bis-07 (work in progress), 3401 September 2015. 3403 [I-D.ietf-netmod-yang-json] 3404 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3405 draft-ietf-netmod-yang-json-06 (work in progress), October 3406 2015. 3408 [I-D.ietf-netmod-yang-metadata] 3409 Lhotka, L., "Defining and Using Metadata with YANG", 3410 draft-ietf-netmod-yang-metadata-02 (work in progress), 3411 September 2015. 3413 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3414 Extensions (MIME) Part Two: Media Types", RFC 2046, 3415 November 1996. 3417 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3418 Requirement Levels", BCP 14, RFC 2119, March 1997. 3420 [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. 3422 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3423 January 2004. 3425 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3426 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3427 3986, January 2005. 3429 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3430 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3432 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3433 Notifications", RFC 5277, July 2008. 3435 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3436 Housley, R., and T. Polk, "Internet X.509 Public Key 3437 Infrastructure Certificate and Certificate Revocation List 3438 (CRL) Profile", RFC 5280, May 2008. 3440 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3441 5789, March 2010. 3443 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3445 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 3446 Network Configuration Protocol (NETCONF)", RFC 6020, 3447 October 2010. 3449 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3450 Verification of Domain-Based Application Service Identity 3451 within Internet Public Key Infrastructure Using X.509 3452 (PKIX) Certificates in the Context of Transport Layer 3453 Security (TLS)", RFC 6125, March 2011. 3455 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3456 and A. Bierman, Ed., "Network Configuration Protocol 3457 (NETCONF)", RFC 6241, June 2011. 3459 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 3460 NETCONF", RFC 6243, June 2011. 3462 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 3463 6415, October 2011. 3465 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 3466 Protocol (NETCONF) Access Control Model", RFC 6536, March 3467 2012. 3469 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3470 and D. Orchard, "URI Template", RFC 6570, March 2012. 3472 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 3473 July 2013. 3475 [RFC7158] Bray, T., Ed., "The JSON Data Interchange Format", RFC 3476 7158, March 2013. 3478 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3479 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 3480 2014. 3482 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3483 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3485 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3486 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 3488 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3489 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3491 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 3492 7320, July 2014. 3494 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 3495 NETCONF Protocol over Transport Layer Security (TLS) with 3496 Mutual X.509 Authentication", RFC 7589, DOI 10.17487/ 3497 RFC7589, June 2015, 3498 . 3500 [W3C.CR-eventsource-20121211] 3501 Hickson, I., "Server-Sent Events", World Wide Web 3502 Consortium CR CR-eventsource-20121211, December 2012, 3503 . 3505 [W3C.REC-xml-20081126] 3506 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 3507 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 3508 Edition)", World Wide Web Consortium Recommendation REC- 3509 xml-20081126, November 2008, 3510 . 3512 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 3513 Version 1.0", World Wide Web Consortium Recommendation 3514 REC-xpath-19991116, November 1999, 3515 . 3517 14.2. Informative References 3519 [I-D.ietf-netconf-yang-patch] 3520 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 3521 Media Type", draft-ietf-netconf-yang-patch-06 (work in 3522 progress), October 2015. 3524 [rest-dissertation] 3525 Fielding, R., "Architectural Styles and the Design of 3526 Network-based Software Architectures", 2000. 3528 Appendix A. Change Log 3530 -- RFC Ed.: remove this section before publication. 3532 The RESTCONF issue tracker can be found here: https://github.com/ 3533 netconf-wg/restconf/issues 3535 A.1. v08 - v09 3537 o fix introduction text regarding implementation requirements for 3538 the ietf-yang-library 3540 o clarified HTTP authentication requirements 3542 o fix host-meta example 3544 o changed list key encoding to clarify that quoted strings are not 3545 allowed. Percent-encoded values are used if quotes would be 3546 required. A missing key is treated as a zero-length string 3548 o Fixed example of percent-encoded string to match YANG model 3550 o Changed streams examples to align with naming already used 3552 A.2. v07 - v08 3554 o add support for YANG 1.1 action statement 3556 o changed mandatory encoding from XML to XML or JSON 3558 o fix syntax in fields parameter definition 3560 o add meta-data encoding examples for XML and JSON 3562 o remove RFC 2396 references and update with 3986 3563 o change encoding of a key so quoted string are not used, since they 3564 are already percent-encoded. A zero-length string is not encoded 3565 (/list=foo,,baz) 3567 o Add example of percent-encoded key value 3569 A.3. v06 - v07 3571 o fixed all issues identified in email from Jernej Tuljak in netconf 3572 email 2015-06-22 3574 o fixed error example bug where error-urlpath was still used. 3575 Changed to error-path. 3577 o added mention of YANG Patch and informative reference 3579 o added support for YANG 1.1, specifically support for anydata and 3580 actions 3582 o removed the special field value "*", since it is no longer needed 3584 A.4. v05 - v06 3586 o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) 3588 A.5. v04 - v05 3590 o changed term 'notification event' to 'event notification' 3592 o removed intro text about framework and meta-model 3594 o removed early mention of API resources 3596 o removed term unified datastore and cleaned up text about NETCONF 3597 datastores 3599 o removed text about not immediate persistence of edits 3601 o removed RESTCONF-specific data-resource-identifier typedef and its 3602 usage 3604 o clarified encoding of key leafs 3606 o changed several examples from JSON to XML encoding 3608 o made 'insert' and 'point' query parameters mandatory to implement 3610 o removed ":insert" capability URI 3611 o renamed stream/encoding to stream/access 3613 o renamed stream/encoding/type to stream/access/encoding 3615 o renamed stream/encoding/events to stream/access/location 3617 o changed XPath from informative to normative reference 3619 o changed rest-dissertation from normative to informative reference 3621 o changed example-jukebox playlist 'id' from a data-resource- 3622 identifier to a leafref pointing at the song name 3624 A.6. v03 - v04 3626 o renamed 'select' to 'fields' (#1) 3628 o moved collection resource and page capability to draft-ietf- 3629 netconf-restconf-collection-00 (#3) 3631 o added mandatory "defaults" protocol capability URI (#4) 3633 o added optional "with-defaults" query parameter URI (#4) 3635 o clarified authentication procedure (#9) 3637 o moved ietf-yang-library module to draft-ietf-netconf-yang- 3638 library-00 (#13) 3640 o clarified that JSON encoding of module name in a URI MUST follow 3641 the netmod-yang-json encoding rules (#14) 3643 o added restconf-media-type extension (#15) 3645 o remove "content" query parameter URI and made this parameter 3646 mandatory (#16) 3648 o clarified datastore usage 3650 o changed lock-denied error example 3652 o added with-defaults query parameter example 3654 o added term "RESTCONF Capability" 3656 o changed NETCONF Capability URI registry usage to new RESTCONF 3657 Capability URI Registry usage 3659 A.7. v02 - v03 3661 o added collection resource 3663 o added "page" query parameter capability 3665 o added "limit" and "offset" query parameters, which are available 3666 if the "page" capability is supported 3668 o added "stream list" term 3670 o fixed bugs in some examples 3672 o added "encoding" list within the "stream" list to allow different 3673 URLs for XML and JSON encoding. 3675 o made XML MUST implement and JSON MAY implement for servers 3677 o re-add JSON notification examples (previously removed) 3679 o updated JSON references 3681 A.8. v01 - v02 3683 o moved query parameter definitions from the YANG module back to the 3684 plain text sections 3686 o made all query parameters optional to implement 3688 o defined query parameter capability URI 3690 o moved 'streams' to new YANG module (ietf-restconf-monitoring) 3692 o added 'capabilities' container to new YANG module (ietf-restconf- 3693 monitoring) 3695 o moved 'modules' container to new YANG module (ietf-yang-library) 3697 o added new leaf 'module-set-id' (ietf-yang-library) 3699 o added new leaf 'conformance' (ietf-yang-library) 3701 o changed 'schema' leaf to type inet:uri that returns the location 3702 of the YANG schema (instead of returning the schema directly) 3704 o changed 'events' leaf to type inet:uri that returns the location 3705 of the event stream resource (instead of returning events 3706 directly) 3708 o changed examples for yang.api resource since the monitoring 3709 information is no longer in this resource 3711 o closed issue #1 'select parameter' since no objections to the 3712 proposed syntax 3714 o closed "encoding of list keys" issue since no objection to new 3715 encoding of list keys in a target resource URI. 3717 o moved open issues list to the issue tracker on github 3719 A.9. v00 - v01 3721 o fixed content=nonconfig example (non-config was incorrect) 3723 o closed open issue 'message-id'. There is no need for a message-id 3724 field, and RFC 2392 does not apply. 3726 o closed open issue 'server support verification'. The headers used 3727 by RESTCONF are widely supported. 3729 o removed encoding rules from section on RESTCONF Meta-Data. This 3730 is now defined in "I-D.lhotka-netmod-yang-json". 3732 o added media type application/yang.errors to map to errors YANG 3733 grouping. Updated error examples to use new media type. 3735 o closed open issue 'additional datastores'. Support may be added 3736 in the future to identify new datastores. 3738 o closed open issue 'PATCH media type discovery'. The section on 3739 PATCH has an added sentence on the Accept-Patch header. 3741 o closed open issue 'YANG to resource mapping'. Current mapping of 3742 all data nodes to resources will be used in order to allow 3743 mandatory DELETE support. The PATCH operation is optional, as 3744 well as the YANG Patch media type. 3746 o closed open issue '_self links for HATEOAS support'. It was 3747 decided that they are redundant because they can be derived from 3748 the YANG module for the specific data. 3750 o added explanatory text for the 'select' parameter. 3752 o added RESTCONF Path Resolution section for discovering the root of 3753 the RESTCONF API using the /.well-known/host-meta. 3755 o added an "error" media type to for structured error messages 3756 o added Secure Transport section requiring TLS 3758 o added Security Considerations section 3760 o removed all references to "REST-like" 3762 A.10. bierman:restconf-04 to ietf:restconf-00 3764 o updated open issues section 3766 Appendix B. Open Issues 3768 -- RFC Ed.: remove this section before publication. 3770 The RESTCONF issues are tracked on github.com: 3772 https://github.com/netconf-wg/restconf/issues [1] 3774 Appendix C. Example YANG Module 3776 The example YANG module used in this document represents a simple 3777 media jukebox interface. 3779 YANG Tree Diagram for "example-jukebox" Module 3781 +--rw jukebox! 3782 +--rw library 3783 | +--rw artist* [name] 3784 | | +--rw name string 3785 | | +--rw album* [name] 3786 | | +--rw name string 3787 | | +--rw genre? identityref 3788 | | +--rw year? uint16 3789 | | +--rw admin 3790 | | | +--rw label? string 3791 | | | +--rw catalogue-number? string 3792 | | +--rw song* [name] 3793 | | +--rw name string 3794 | | +--rw location string 3795 | | +--rw format? string 3796 | | +--rw length? uint32 3797 | +--ro artist-count? uint32 3798 | +--ro album-count? uint32 3799 | +--ro song-count? uint32 3800 +--rw playlist* [name] 3801 | +--rw name string 3802 | +--rw description? string 3803 | +--rw song* [index] 3804 | +--rw index uint32 3805 | +--rw id leafref 3806 +--rw player 3807 +--rw gap? decimal64 3809 rpcs: 3811 +---x play 3812 +--ro input 3813 +--ro playlist string 3814 +--ro song-number uint32 3816 C.1. example-jukebox YANG Module 3818 module example-jukebox { 3820 namespace "http://example.com/ns/example-jukebox"; 3821 prefix "jbox"; 3823 organization "Example, Inc."; 3824 contact "support at example.com"; 3825 description "Example Jukebox Data Model Module"; 3826 revision "2015-04-04" { 3827 description "Initial version."; 3828 reference "example.com document 1-4673"; 3829 } 3831 identity genre { 3832 description "Base for all genre types"; 3833 } 3835 // abbreviated list of genre classifications 3836 identity alternative { 3837 base genre; 3838 description "Alternative music"; 3839 } 3840 identity blues { 3841 base genre; 3842 description "Blues music"; 3843 } 3844 identity country { 3845 base genre; 3846 description "Country music"; 3847 } 3848 identity jazz { 3849 base genre; 3850 description "Jazz music"; 3851 } 3852 identity pop { 3853 base genre; 3854 description "Pop music"; 3855 } 3856 identity rock { 3857 base genre; 3858 description "Rock music"; 3859 } 3861 container jukebox { 3862 presence 3863 "An empty container indicates that the jukebox 3864 service is available"; 3866 description 3867 "Represents a jukebox resource, with a library, playlists, 3868 and a play operation."; 3870 container library { 3872 description "Represents the jukebox library resource."; 3874 list artist { 3875 key name; 3877 description 3878 "Represents one artist resource within the 3879 jukebox library resource."; 3881 leaf name { 3882 type string { 3883 length "1 .. max"; 3884 } 3885 description "The name of the artist."; 3886 } 3888 list album { 3889 key name; 3891 description 3892 "Represents one album resource within one 3893 artist resource, within the jukebox library."; 3895 leaf name { 3896 type string { 3897 length "1 .. max"; 3898 } 3899 description "The name of the album."; 3901 } 3903 leaf genre { 3904 type identityref { base genre; } 3905 description 3906 "The genre identifying the type of music on 3907 the album."; 3908 } 3910 leaf year { 3911 type uint16 { 3912 range "1900 .. max"; 3913 } 3914 description "The year the album was released"; 3915 } 3917 container admin { 3918 description 3919 "Administrative information for the album."; 3921 leaf label { 3922 type string; 3923 description "The label that released the album."; 3924 } 3925 leaf catalogue-number { 3926 type string; 3927 description "The album's catalogue number."; 3928 } 3929 } 3931 list song { 3932 key name; 3934 description 3935 "Represents one song resource within one 3936 album resource, within the jukebox library."; 3938 leaf name { 3939 type string { 3940 length "1 .. max"; 3941 } 3942 description "The name of the song"; 3943 } 3944 leaf location { 3945 type string; 3946 mandatory true; 3947 description 3948 "The file location string of the 3949 media file for the song"; 3950 } 3951 leaf format { 3952 type string; 3953 description 3954 "An identifier string for the media type 3955 for the file associated with the 3956 'location' leaf for this entry."; 3957 } 3958 leaf length { 3959 type uint32; 3960 units "seconds"; 3961 description 3962 "The duration of this song in seconds."; 3963 } 3964 } // end list 'song' 3965 } // end list 'album' 3966 } // end list 'artist' 3968 leaf artist-count { 3969 type uint32; 3970 units "songs"; 3971 config false; 3972 description "Number of artists in the library"; 3973 } 3974 leaf album-count { 3975 type uint32; 3976 units "albums"; 3977 config false; 3978 description "Number of albums in the library"; 3979 } 3980 leaf song-count { 3981 type uint32; 3982 units "songs"; 3983 config false; 3984 description "Number of songs in the library"; 3985 } 3986 } // end library 3988 list playlist { 3989 key name; 3991 description 3992 "Example configuration data resource"; 3994 leaf name { 3995 type string; 3996 description 3997 "The name of the playlist."; 3998 } 3999 leaf description { 4000 type string; 4001 description 4002 "A comment describing the playlist."; 4003 } 4004 list song { 4005 key index; 4006 ordered-by user; 4008 description 4009 "Example nested configuration data resource"; 4011 leaf index { // not really needed 4012 type uint32; 4013 description 4014 "An arbitrary integer index for this playlist song."; 4015 } 4016 leaf id { 4017 type leafref { 4018 path "/jbox:jukebox/jbox:library/jbox:artist/" + 4019 "jbox:album/jbox:song/jbox:name"; 4020 } 4021 mandatory true; 4022 description 4023 "Song identifier. Must identify an instance of 4024 /jukebox/library/artist/album/song/name."; 4025 } 4026 } 4027 } 4029 container player { 4030 description 4031 "Represents the jukebox player resource."; 4033 leaf gap { 4034 type decimal64 { 4035 fraction-digits 1; 4036 range "0.0 .. 2.0"; 4037 } 4038 units "tenths of seconds"; 4039 description "Time gap between each song"; 4040 } 4041 } 4042 } 4044 rpc play { 4045 description "Control function for the jukebox player"; 4046 input { 4047 leaf playlist { 4048 type string; 4049 mandatory true; 4050 description "playlist name"; 4051 } 4052 leaf song-number { 4053 type uint32; 4054 mandatory true; 4055 description "Song number in playlist to play"; 4056 } 4057 } 4058 } 4059 } 4061 Appendix D. RESTCONF Message Examples 4063 The examples within this document use the normative YANG module 4064 defined in Section 8 and the non-normative example YANG module 4065 defined in Appendix C.1. 4067 This section shows some typical RESTCONF message exchanges. 4069 D.1. Resource Retrieval Examples 4071 D.1.1. Retrieve the Top-level API Resource 4073 The client may start by retrieving the top-level API resource, using 4074 the entry point URI "{+restconf}". 4076 GET /restconf HTTP/1.1 4077 Host: example.com 4078 Accept: application/yang.api+json 4080 The server might respond as follows: 4082 HTTP/1.1 200 OK 4083 Date: Mon, 23 Apr 2012 17:01:00 GMT 4084 Server: example-server 4085 Content-Type: application/yang.api+json 4087 { 4088 "ietf-restconf:restconf": { 4089 "data" : [ null ], 4090 "operations" : [ null ] 4091 } 4092 } 4094 To request that the response content to be encoded in XML, the 4095 "Accept" header can be used, as in this example request: 4097 GET /restconf HTTP/1.1 4098 Host: example.com 4099 Accept: application/yang.api+xml 4101 The server will return the same response either way, which might be 4102 as follows : 4104 HTTP/1.1 200 OK 4105 Date: Mon, 23 Apr 2012 17:01:00 GMT 4106 Server: example-server 4107 Cache-Control: no-cache 4108 Pragma: no-cache 4109 Content-Type: application/yang.api+xml 4111 4112 4113 4114 4116 D.1.2. Retrieve The Server Module Information 4118 In this example the client is retrieving the modules information from 4119 the server in JSON format: 4121 GET /restconf/data/ietf-yang-library:modules HTTP/1.1 4122 Host: example.com 4123 Accept: application/yang.data+json 4125 The server might respond as follows. 4127 HTTP/1.1 200 OK 4128 Date: Mon, 23 Apr 2012 17:01:00 GMT 4129 Server: example-server 4130 Cache-Control: no-cache 4131 Pragma: no-cache 4132 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4133 Content-Type: application/yang.data+json 4135 { 4136 "ietf-yang-library:modules": { 4137 "module": [ 4138 { 4139 "name" : "foo", 4140 "revision" : "2012-01-02", 4141 "schema" : "https://example.com/modules/foo/2012-01-02", 4142 "namespace" : "http://example.com/ns/foo", 4143 "feature" : [ "feature1", "feature2" ], 4144 "conformance" : "implement" 4145 }, 4146 { 4147 "name" : "foo-types", 4148 "revision" : "2012-01-05", 4149 "schema" : 4150 "https://example.com/modules/foo-types/2012-01-05", 4151 "schema" : [null], 4152 "namespace" : "http://example.com/ns/foo-types", 4153 "conformance" : "import" 4154 }, 4155 { 4156 "name" : "bar", 4157 "revision" : "2012-11-05", 4158 "schema" : "https://example.com/modules/bar/2012-11-05", 4159 "namespace" : "http://example.com/ns/bar", 4160 "feature" : [ "bar-ext" ], 4161 "conformance" : "implement", 4162 "submodule" : [ 4163 { 4164 "name" : "bar-submod1", 4165 "revision" : "2012-11-05", 4166 "schema" : 4167 "https://example.com/modules/bar-submod1/2012-11-05" 4168 }, 4169 { 4170 "name" : "bar-submod2", 4171 "revision" : "2012-11-05", 4172 "schema" : 4173 "https://example.com/modules/bar-submod2/2012-11-05" 4174 } 4175 ] 4176 } 4177 ] 4179 } 4180 } 4182 D.1.3. Retrieve The Server Capability Information 4184 In this example the client is retrieving the capability information 4185 from the server in JSON format, and the server supports all the 4186 RESTCONF query parameters, plus one vendor parameter: 4188 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 4189 capabilities HTTP/1.1 4190 Host: example.com 4191 Accept: application/yang.data+xml 4193 The server might respond as follows. The extra whitespace in 4194 'capability' elements for display purposes only. 4196 HTTP/1.1 200 OK 4197 Date: Mon, 23 Apr 2012 17:02:00 GMT 4198 Server: example-server 4199 Cache-Control: no-cache 4200 Pragma: no-cache 4201 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4202 Content-Type: application/yang.data+xml 4204 4205 4206 urn:ietf:params:restconf:capability:depth:1.0 4207 4208 4209 urn:ietf:params:restconf:capability:fields:1.0 4210 4211 4212 urn:ietf:params:restconf:capability:filter:1.0 4213 4214 4215 urn:ietf:params:restconf:capability:start-time:1.0 4216 4217 4218 urn:ietf:params:restconf:capability:stop-time:1.0 4219 4220 4221 http://example.com/capabilities/myparam 4222 4223 4225 D.2. Edit Resource Examples 4226 D.2.1. Create New Data Resources 4228 To create a new "artist" resource within the "library" resource, the 4229 client might send the following request. 4231 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 4232 Host: example.com 4233 Content-Type: application/yang.data+json 4235 { 4236 "example-jukebox:artist" : { 4237 "name" : "Foo Fighters" 4238 } 4239 } 4241 If the resource is created, the server might respond as follows. 4242 Note that the "Location" header line is wrapped for display purposes 4243 only: 4245 HTTP/1.1 201 Created 4246 Date: Mon, 23 Apr 2012 17:02:00 GMT 4247 Server: example-server 4248 Location: https://example.com/restconf/data/ 4249 example-jukebox:jukebox/library/artist=Foo%20Fighters 4250 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 4251 ETag: b3830f23a4c 4253 To create a new "album" resource for this artist within the "jukebox" 4254 resource, the client might send the following request. Note that the 4255 request URI header line is wrapped for display purposes only: 4257 POST /restconf/data/example-jukebox:jukebox/ 4258 library/artist=Foo%20Fighters HTTP/1.1 4259 Host: example.com 4260 Content-Type: application/yang.data+json 4262 { 4263 "example-jukebox:album" : { 4264 "name" : "Wasting Light", 4265 "genre" : "example-jukebox:alternative", 4266 "year" : 2012 # note this is the wrong date 4267 } 4268 } 4270 If the resource is created, the server might respond as follows. 4271 Note that the "Location" header line is wrapped for display purposes 4272 only: 4274 HTTP/1.1 201 Created 4275 Date: Mon, 23 Apr 2012 17:03:00 GMT 4276 Server: example-server 4277 Location: https://example.com/restconf/data/ 4278 example-jukebox:jukebox/library/artist=Foo%20Fighters/ 4279 album=Wasting%20Light 4280 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 4281 ETag: b8389233a4c 4283 D.2.2. Detect Resource Entity Tag Change 4285 In this example, the server just supports the mandatory datastore 4286 last-changed timestamp. The client has previously retrieved the 4287 "Last-Modified" header and has some value cached to provide in the 4288 following request to patch an "album" list entry with key value 4289 "Wasting Light". Only the "year" field is being updated. 4291 PATCH /restconf/data/example-jukebox:jukebox/ 4292 library/artist=Foo%20Fighters/album=Wasting%20Light/year 4293 HTTP/1.1 4294 Host: example.com 4295 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 4296 Content-Type: application/yang.data+json 4298 { "example-jukebox:year" : "2011" } 4300 In this example the datastore resource has changed since the time 4301 specified in the "If-Unmodified-Since" header. The server might 4302 respond: 4304 HTTP/1.1 412 Precondition Failed 4305 Date: Mon, 23 Apr 2012 19:01:00 GMT 4306 Server: example-server 4307 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 4308 ETag: b34aed893a4c 4310 D.2.3. Edit a Datastore Resource 4312 In this example, the client modifies two different data nodes by 4313 sending a PATCH to the datastore resource: 4315 PATCH /restconf/data HTTP/1.1 4316 Host: example.com 4317 Content-Type: application/yang.datastore+xml 4319 4320 4321 4322 4323 Foo Fighters 4324 4325 Wasting Light 4326 2011 4327 4328 4329 4330 Nick Cave 4331 4332 Tender Prey 4333 1988 4334 4335 4336 4337 4338 4340 D.3. Query Parameter Examples 4342 D.3.1. "content" Parameter 4344 The "content" parameter is used to select the type of data child 4345 resources (configuration and/or not configuration) that are returned 4346 by the server for a GET method request. 4348 In this example, a simple YANG list that has configuration and non- 4349 configuration child resources. 4351 container events 4352 list event { 4353 key name; 4354 leaf name { type string; } 4355 leaf description { type string; } 4356 leaf event-count { 4357 type uint32; 4358 config false; 4359 } 4360 } 4361 } 4363 Example 1: content=all 4365 To retrieve all the child resources, the "content" parameter is set 4366 to "all". The client might send: 4368 GET /restconf/data/example-events:events?content=all 4369 HTTP/1.1 4371 Host: example.com 4372 Accept: application/yang.data+json 4374 The server might respond: 4376 HTTP/1.1 200 OK 4377 Date: Mon, 23 Apr 2012 17:11:30 GMT 4378 Server: example-server 4379 Cache-Control: no-cache 4380 Pragma: no-cache 4381 Content-Type: application/yang.data+json 4383 { 4384 "example-events:events" : { 4385 "event" : [ 4386 { 4387 "name" : "interface-up", 4388 "description" : "Interface up notification count", 4389 "event-count" : 42 4390 }, 4391 { 4392 "name" : "interface-down", 4393 "description" : "Interface down notification count", 4394 "event-count" : 4 4395 } 4396 ] 4397 } 4398 } 4400 Example 2: content=config 4402 To retrieve only the configuration child resources, the "content" 4403 parameter is set to "config" or omitted since this is the default 4404 value. Note that the "ETag" and "Last-Modified" headers are only 4405 returned if the content parameter value is "config". 4407 GET /restconf/data/example-events:events?content=config 4408 HTTP/1.1 4409 Host: example.com 4410 Accept: application/yang.data+json 4412 The server might respond: 4414 HTTP/1.1 200 OK 4415 Date: Mon, 23 Apr 2012 17:11:30 GMT 4416 Server: example-server 4417 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4418 ETag: eeeada438af 4419 Cache-Control: no-cache 4420 Pragma: no-cache 4421 Content-Type: application/yang.data+json 4423 { 4424 "example-events:events" : { 4425 "event" : [ 4426 { 4427 "name" : "interface-up", 4428 "description" : "Interface up notification count" 4429 }, 4430 { 4431 "name" : "interface-down", 4432 "description" : "Interface down notification count" 4433 } 4434 ] 4435 } 4436 } 4438 Example 3: content=nonconfig 4440 To retrieve only the non-configuration child resources, the "content" 4441 parameter is set to "nonconfig". Note that configuration ancestors 4442 (if any) and list key leafs (if any) are also returned. The client 4443 might send: 4445 GET /restconf/data/example-events:events?content=nonconfig 4446 HTTP/1.1 4447 Host: example.com 4448 Accept: application/yang.data+json 4450 The server might respond: 4452 HTTP/1.1 200 OK 4453 Date: Mon, 23 Apr 2012 17:11:30 GMT 4454 Server: example-server 4455 Cache-Control: no-cache 4456 Pragma: no-cache 4457 Content-Type: application/yang.data+json 4459 { 4460 "example-events:events" : { 4461 "event" : [ 4462 { 4463 "name" : "interface-up", 4464 "event-count" : 42 4465 }, 4466 { 4467 "name" : "interface-down", 4468 "event-count" : 4 4469 } 4470 ] 4471 } 4472 } 4474 D.3.2. "depth" Parameter 4476 The "depth" parameter is used to limit the number of levels of child 4477 resources that are returned by the server for a GET method request. 4479 The depth parameter starts counting levels at the level of the target 4480 resource that is specified, so that a depth level of "1" includes 4481 just the target resource level itself. A depth level of "2" includes 4482 the target resource level and its child nodes. 4484 This example shows how different values of the "depth" parameter 4485 would affect the reply content for retrieval of the top-level 4486 "jukebox" data resource. 4488 Example 1: depth=unbounded 4490 To retrieve all the child resources, the "depth" parameter is not 4491 present or set to the default value "unbounded". Note that some 4492 strings are wrapped for display purposes only. 4494 GET /restconf/data/example-jukebox:jukebox?depth=unbounded 4495 HTTP/1.1 4496 Host: example.com 4497 Accept: application/yang.data+json 4499 The server might respond: 4501 HTTP/1.1 200 OK 4502 Date: Mon, 23 Apr 2012 17:11:30 GMT 4503 Server: example-server 4504 Cache-Control: no-cache 4505 Pragma: no-cache 4506 Content-Type: application/yang.data+json 4508 { 4509 "example-jukebox:jukebox" : { 4510 "library" : { 4511 "artist" : [ 4512 { 4513 "name" : "Foo Fighters", 4514 "album" : [ 4515 { 4516 "name" : "Wasting Light", 4517 "genre" : "example-jukebox:alternative", 4518 "year" : 2011, 4519 "song" : [ 4520 { 4521 "name" : "Wasting Light", 4522 "location" : 4523 "/media/foo/a7/wasting-light.mp3", 4524 "format" : "MP3", 4525 "length" " 286 4526 }, 4527 { 4528 "name" : "Rope", 4529 "location" : "/media/foo/a7/rope.mp3", 4530 "format" : "MP3", 4531 "length" " 259 4532 } 4533 ] 4534 } 4535 ] 4536 } 4537 ] 4538 }, 4539 "playlist" : [ 4540 { 4541 "name" : "Foo-One", 4542 "description" : "example playlist 1", 4543 "song" : [ 4544 { 4545 "index" : 1, 4546 "id" : "https://example.com/restconf/data/ 4547 example-jukebox:jukebox/library/artist= 4548 Foo%20Fighters/album=Wasting%20Light/ 4549 song=Rope" 4550 }, 4551 { 4552 "index" : 2, 4553 "id" : "https://example.com/restconf/data/ 4554 example-jukebox:jukebox/library/artist= 4555 Foo%20Fighters/album=Wasting%20Light/song= 4556 Bridge%20Burning" 4557 } 4558 ] 4559 } 4560 ], 4561 "player" : { 4562 "gap" : 0.5 4564 } 4565 } 4566 } 4568 Example 2: depth=1 4570 To determine if 1 or more resource instances exist for a given target 4571 resource, the value "1" is used. 4573 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 4574 Host: example.com 4575 Accept: application/yang.data+json 4577 The server might respond: 4579 HTTP/1.1 200 OK 4580 Date: Mon, 23 Apr 2012 17:11:30 GMT 4581 Server: example-server 4582 Cache-Control: no-cache 4583 Pragma: no-cache 4584 Content-Type: application/yang.data+json 4586 { 4587 "example-jukebox:jukebox" : [null] 4588 } 4590 Example 3: depth=3 4592 To limit the depth level to the target resource plus 2 child resource 4593 layers the value "3" is used. 4595 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 4596 Host: example.com 4597 Accept: application/yang.data+json 4599 The server might respond: 4601 HTTP/1.1 200 OK 4602 Date: Mon, 23 Apr 2012 17:11:30 GMT 4603 Server: example-server 4604 Cache-Control: no-cache 4605 Pragma: no-cache 4606 Content-Type: application/yang.data+json 4608 { 4609 "example-jukebox:jukebox" : { 4610 "library" : { 4611 "artist" : [ null ] 4613 }, 4614 "playlist" : [ 4615 { 4616 "name" : "Foo-One", 4617 "description" : "example playlist 1", 4618 "song" : [ null ] 4619 } 4620 ], 4621 "player" : { 4622 "gap" : 0.5 4623 } 4624 } 4625 } 4627 D.3.3. "fields" Parameter 4629 In this example the client is retrieving the API resource, but 4630 retrieving only the "name" and "revision" nodes from each module, in 4631 JSON format: 4633 GET /restconf/data?fields=ietf-yang-library:modules/ 4634 module(name;revision) HTTP/1.1 4635 Host: example.com 4636 Accept: application/yang.data+json 4638 The server might respond as follows. 4640 HTTP/1.1 200 OK 4641 Date: Mon, 23 Apr 2012 17:01:00 GMT 4642 Server: example-server 4643 Content-Type: application/yang.data+json 4645 { 4646 "ietf-yang-library:modules": { 4647 "module": [ 4648 { 4649 "name" : "example-jukebox", 4650 "revision" : "2015-06-04" 4651 }, 4652 { 4653 "name" : "ietf-inet-types", 4654 "revision" : "2013-07-15" 4655 }, 4656 { 4657 "name" : "ietf-restconf-monitoring", 4658 "revision" : "2015-06-19" 4659 }, 4660 { 4661 "name" : "ietf-yang-library", 4662 "revision" : "2015-07-03" 4663 }, 4664 { 4665 "name" : "ietf-yang-types", 4666 "revision" : "2013-07-15" 4667 } 4669 ] 4670 } 4671 } 4673 D.3.4. "insert" Parameter 4675 In this example, a new first entry in the "Foo-One" playlist is being 4676 created. 4678 Request from client: 4680 POST /restconf/data/example-jukebox:jukebox/ 4681 playlist=Foo-One?insert=first HTTP/1.1 4682 Host: example.com 4683 Content-Type: application/yang.data+json 4685 { 4686 "example-jukebox:song" : { 4687 "index" : 1, 4688 "id" : "/example-jukebox:jukebox/library/ 4689 artist=Foo%20Fighters/album=Wasting%20Light/song=Rope" 4690 } 4691 } 4693 Response from server: 4695 HTTP/1.1 201 Created 4696 Date: Mon, 23 Apr 2012 13:01:20 GMT 4697 Server: example-server 4698 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4699 Location: https://example.com/restconf/data/ 4700 example-jukebox:jukebox/playlist=Foo-One/song=1 4701 ETag: eeeada438af 4703 D.3.5. "point" Parameter 4705 In this example, the client is inserting a new "song" resource within 4706 an "album" resource after another song. The request URI is split for 4707 display purposes only. 4709 Request from client: 4711 POST /restconf/data/example-jukebox:jukebox/ 4712 library/artist=Foo%20Fighters/album=Wasting%20Light? 4713 insert=after&point=%2Fexample-jukebox%3Ajukebox%2F 4714 library%2Fartist%2FFoo%20Fighters%2Falbum%2F 4715 Wasting%20Light%2Fsong%2FBridge%20Burning HTTP/1.1 4716 Host: example.com 4717 Content-Type: application/yang.data+json 4719 { 4720 "example-jukebox:song" : { 4721 "name" : "Rope", 4722 "location" : "/media/foo/a7/rope.mp3", 4723 "format" : "MP3", 4724 "length" : 259 4725 } 4726 } 4728 Response from server: 4730 HTTP/1.1 204 No Content 4731 Date: Mon, 23 Apr 2012 13:01:20 GMT 4732 Server: example-server 4733 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4734 ETag: abcada438af 4736 D.3.6. "filter" Parameter 4738 The following URIs show some examples of notification filter 4739 specifications (lines wrapped for display purposes only): 4741 // filter = /event/event-class='fault' 4742 GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' 4744 // filter = /event/severity<=4 4745 GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 4747 // filter = /linkUp|/linkDown 4748 GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown 4750 // filter = /*/reporting-entity/card!='Ethernet0' 4751 GET /streams/NETCONF? 4752 filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' 4754 // filter = /*/email-addr[contains(.,'company.com')] 4755 GET /streams/critical-syslog? 4756 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 4758 // Note: the module name is used as prefix. 4759 // filter = (/example-mod:event1/name='joe' and 4760 // /example-mod:event1/status='online') 4761 GET /streams/NETCONF? 4762 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and 4763 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 4765 // To get notifications from just two modules (e.g., m1 + m2) 4766 // filter=(/m1:* or /m2:*) 4767 GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*) 4769 D.3.7. "start-time" Parameter 4771 // start-time = 2014-10-25T10:02:00Z 4772 GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z 4774 D.3.8. "stop-time" Parameter 4776 // stop-time = 2014-10-25T12:31:00Z 4777 GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z 4779 D.3.9. "with-defaults" Parameter 4781 The following YANG module is assumed for this example. 4783 module example-interface { 4784 prefix "exif"; 4785 namespace "urn:example.com:params:xml:ns:yang:example-interface"; 4787 container interfaces { 4788 list interface { 4789 key name; 4790 leaf name { type string; } 4791 leaf mtu { type uint32; } 4792 leaf status { 4793 config false; 4794 type enumeration { 4795 enum up; 4796 enum down; 4797 enum testing; 4798 } 4799 } 4800 } 4801 } 4802 } 4804 Assume the same data model as defined in Appendix A.1 of [RFC6243]. 4805 Assume the same data set as defined in Appendix A.2 of [RFC6243]. If 4806 the server defaults-uri basic-mode is "trim", the the following 4807 request for interface "eth1" might be as follows: 4809 Without query parameter: 4811 GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1 4812 Host: example.com 4813 Accept: application/yang.data+json 4815 The server might respond as follows. 4817 HTTP/1.1 200 OK 4818 Date: Mon, 23 Apr 2012 17:01:00 GMT 4819 Server: example-server 4820 Content-Type: application/yang.data+json 4822 { 4823 "example:interface": [ 4824 { 4825 "name" : "eth1", 4826 "status" : "up" 4827 } 4828 ] 4829 } 4831 Note that the "mtu" leaf is missing because it is set to the default 4832 "1500", and the server defaults handling basic-mode is "trim". 4834 With query parameter: 4836 GET /restconf/data/example:interfaces/interface=eth1 4837 ?with-defaults=report-all HTTP/1.1 4838 Host: example.com 4839 Accept: application/yang.data+json 4841 The server might respond as follows. 4843 HTTP/1.1 200 OK 4844 Date: Mon, 23 Apr 2012 17:01:00 GMT 4845 Server: example-server 4846 Content-Type: application/yang.data+json 4848 { 4849 "example:interface": [ 4850 { 4851 "name" : "eth1", 4852 "mtu" : 1500, 4853 "status" : "up" 4855 } 4856 ] 4857 } 4859 Note that the server returns the "mtu" leaf because the "report-all" 4860 mode was requested with the "with-defaults" query parameter. 4862 Authors' Addresses 4864 Andy Bierman 4865 YumaWorks 4867 Email: andy@yumaworks.com 4869 Martin Bjorklund 4870 Tail-f Systems 4872 Email: mbj@tail-f.com 4874 Kent Watsen 4875 Juniper Networks 4877 Email: kwatsen@juniper.net