idnits 2.17.1 draft-ietf-netconf-restconf-04.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1957 has weird spacing: '... method entry...' == Line 2857 has weird spacing: '... events ine...' == Line 3594 has weird spacing: '...ocation str...' == Line 3604 has weird spacing: '...w index uin...' == Line 3614 has weird spacing: '...-number uin...' == 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 (January 30, 2015) is 3374 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-06) exists of draft-ietf-netconf-yang-library-00 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-yang-json-02 == Outdated reference: A later version (-01) exists of draft-lhotka-netmod-yang-metadata-00 ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** 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) == Outdated reference: A later version (-14) exists of draft-ietf-netconf-yang-patch-03 Summary: 12 errors (**), 0 flaws (~~), 12 warnings (==), 2 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: August 3, 2015 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 January 30, 2015 10 RESTCONF Protocol 11 draft-ietf-netconf-restconf-04 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 August 3, 2015. 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. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 57 1.3.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 7 58 1.3.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 8 59 1.3.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 9 60 1.3.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 9 61 1.3.5. URI Template . . . . . . . . . . . . . . . . . . . . 11 62 1.3.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 11 63 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 11 64 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 11 65 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 12 66 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 12 67 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 12 68 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 12 69 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 13 70 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 14 71 3.2. RESTCONF Resource Types . . . . . . . . . . . . . . . . . 15 72 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 15 73 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 16 74 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 17 75 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 17 76 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 18 77 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 19 78 3.5.1. Encoding Data Resource Identifiers in the Request URI 19 79 3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 22 80 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 22 81 3.6.1. Encoding Operation Input Parameters . . . . . . . . . 23 82 3.6.2. Encoding Operation Output Parameters . . . . . . . . 24 83 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 24 84 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 25 85 3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 26 86 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 26 87 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 27 88 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 27 89 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 90 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 28 91 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 29 92 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 30 93 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 94 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 32 95 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 32 97 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 33 98 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 34 99 4.8.1. Query Parameter URIs . . . . . . . . . . . . . . . . 35 100 4.8.2. The "defaults" Protocol Capability URI . . . . . . . 35 101 4.8.3. The "content" Query Parameter . . . . . . . . . . . . 36 102 4.8.4. The "depth" Query Parameter . . . . . . . . . . . . . 36 103 4.8.5. The "fields" Query Parameter . . . . . . . . . . . . 37 104 4.8.6. The "insert" Query Parameter . . . . . . . . . . . . 38 105 4.8.7. The "point" Query Parameter . . . . . . . . . . . . . 38 106 4.8.8. The "filter" Query Parameter . . . . . . . . . . . . 39 107 4.8.9. The "start-time" Query Parameter . . . . . . . . . . 40 108 4.8.10. The "stop-time" Query Parameter . . . . . . . . . . . 40 109 4.8.11. The "with-defaults" Query Parameter . . . . . . . . . 41 110 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 42 111 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 42 112 5.2. Message Headers . . . . . . . . . . . . . . . . . . . . . 43 113 5.3. Message Encoding . . . . . . . . . . . . . . . . . . . . 44 114 5.4. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 45 115 5.5. Return Status . . . . . . . . . . . . . . . . . . . . . . 45 116 5.6. Message Caching . . . . . . . . . . . . . . . . . . . . . 45 117 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 46 118 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 46 119 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 46 120 6.3. Subscribing to Receive Notifications . . . . . . . . . . 48 121 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 49 122 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 49 123 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 51 124 7.1. Error Response Message . . . . . . . . . . . . . . . . . 52 125 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 55 126 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 61 127 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 62 128 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 62 129 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 62 130 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 66 131 10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 66 132 10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 67 133 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 67 134 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 67 135 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 67 136 11.3. application/yang Media Sub Types . . . . . . . . . . . . 68 137 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 69 138 12. Security Considerations . . . . . . . . . . . . . . . . . . . 70 139 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 71 140 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 71 141 14.1. Normative References . . . . . . . . . . . . . . . . . . 71 142 14.2. Informative References . . . . . . . . . . . . . . . . . 74 143 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 74 144 A.1. 03 - 04 . . . . . . . . . . . . . . . . . . . . . . . . . 74 145 A.2. 02 - 03 . . . . . . . . . . . . . . . . . . . . . . . . . 75 146 A.3. 01 - 02 . . . . . . . . . . . . . . . . . . . . . . . . . 76 147 A.4. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 76 148 A.5. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 77 149 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 77 150 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 78 151 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 78 152 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 84 153 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 84 154 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 84 155 D.1.2. Retrieve The Server Module Information . . . . . . . 85 156 D.1.3. Retrieve The Server Capability Information . . . . . 86 157 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 87 158 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 87 159 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 88 160 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 89 161 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 89 162 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 92 163 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 95 164 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 96 165 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 97 166 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 97 167 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 98 168 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 98 169 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 98 170 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 100 172 1. Introduction 174 There is a need for standard mechanisms to allow Web applications to 175 access the configuration data, operational data, data-model specific 176 protocol operations, and notification events within a networking 177 device, in a modular and extensible manner. 179 This document describes an HTTP [RFC7230] based protocol called 180 RESTCONF, for accessing data defined in YANG [RFC6020], using 181 datastores defined in NETCONF [RFC6241]. 183 The NETCONF protocol defines configuration datastores and a set of 184 Create, Retrieve, Update, Delete (CRUD) operations that can be used 185 to access these datastores. The YANG language defines the syntax and 186 semantics of datastore content, operational data, protocol 187 operations, and notification events. RESTCONF uses HTTP operations 188 to provide CRUD operations on a NETCONF datastore containing YANG- 189 defined data. Since NETCONF protocol operations are not relevant, 190 the user should not need any prior knowledge of NETCONF in order to 191 use RESTCONF. 193 Configuration data and state data are exposed as resources that can 194 be retrieved with the GET method. Resources representing 195 configuration data can be modified with the DELETE, PATCH, POST, and 196 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 197 or JSON [RFC7158]. 199 Data-model specific protocol operations defined with the YANG "rpc" 200 statement can be invoked with the POST method. Data-model specific 201 notification events defined with the YANG "notification" statement 202 can be accessed. 204 1.1. Simple Subset of NETCONF Functionality 206 The framework and meta-model used for an HTTP-based API does not need 207 to mirror those used by the NETCONF protocol, but it needs to be 208 compatible with NETCONF. Instead, a simplified framework and 209 protocol is needed that co-exists with the three NETCONF datastores 210 (candidate, running, startup), but hides the complexity of multiple 211 datastores from the client. 213 A simplified transaction model is needed that allows basic CRUD 214 operations on a hierarchy of conceptual resources. This represents a 215 limited subset of the transaction capabilities of the NETCONF 216 protocol. 218 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 219 resources represented by YANG data models. These basic edit 220 operations allow the running configuration to be altered in an all- 221 or-none fashion. This is similar to the "rollback-on-error" 222 capability in NETCONF. Edits are usually applied to one data 223 resource instance at a time. 225 Applications that require more complex transaction capabilities might 226 consider NETCONF instead of RESTCONF. The following transaction 227 features are not directly provided in RESTCONF: 229 o datastore locking (full or partial) 231 o candidate datastore 233 o startup datastore 235 o validate operation 237 o confirmed-commit procedure 238 RESTCONF is not intended to replace NETCONF, but rather provide an 239 additional simplified interface that follows REST principles and is 240 compatible with a resource-oriented device abstraction. 242 The following figure shows the system components: 244 +-----------+ +-----------------+ 245 | Web app | <-------> | | 246 +-----------+ HTTP | network device | 247 | | 248 +-----------+ | +-----------+ | 249 | NMS app | <-------> | | datastore | | 250 +-----------+ NETCONF | +-----------+ | 251 +-----------------+ 253 1.2. Data Model Driven API 255 RESTCONF combines the simplicity of the HTTP protocol with the 256 predictability and automation potential of a schema-driven API. 257 Using YANG, a client can predict all resource endpoints, much like 258 using URI Templates [RFC6570], but in a more holistic manner. This 259 strategy obviates the need for responses provided by the server to 260 contain HATEOAS links, originally described in Roy Fielding's 261 doctoral dissertation [rest-dissertation]. 263 In contrast, a REST client using HATEOAS principles would not use any 264 data modeling language to define the application-specific content of 265 the API. The client would need to discover each new child resource 266 as it traverses the URIs to discover the server capabilities. This 267 approach has the following significant weaknesses with regards to 268 control of complex networking devices: 270 o inefficient performance: configuration APIs will be quite complex 271 and may require thousands of protocol messages to discover all the 272 schema information. Typically the data type information has to be 273 passed in the protocol messages, which is also wasteful overhead. 275 o no data model richness: without a data model, the schema-level 276 semantics and validation constraints are not available to the 277 application. 279 o no tool automation: API automation tools need some sort of content 280 schema to function. Such tools can automate various programming 281 and documentation tasks related to specific data models. 283 Data models such as YANG modules serve as an "API contract" that will 284 be honored by the server. An application designer can code to the 285 data model, knowing in advance important details about the exact 286 protocol operations and datastore content a conforming server 287 implementation will support. 289 RESTCONF provides the YANG module capability information supported by 290 the server, in case the client wants to use it. The URIs for custom 291 protocol operations and datastore content are predictable, based on 292 the YANG module definitions. 294 Operational experience with CLI and SNMP indicates that operators 295 learn the 'location' of specific service or device related data and 296 do not expect such information to be arbitrary and discovered each 297 time the client opens a management session to a server. 299 The RESTCONF protocol operates on a conceptual datastore defined with 300 the YANG data modeling language. The server lists each YANG module 301 it supports using the "ietf-yang-library" YANG module, defined in 302 [I-D.ietf-netconf-yang-library]. 304 The conceptual datastore contents, data-model-specific operations and 305 notification events are identified by this set of YANG modules. All 306 RESTCONF content identified as either a data resource, operation 307 resource, or event stream resource is defined with the YANG language. 309 The classification of data as configuration or non-configuration is 310 derived from the YANG "config" statement. Data ordering behavior is 311 derived from the YANG "ordered-by" statement. 313 The RESTCONF datastore editing model is simple and direct, similar to 314 the behavior of the ":writable-running" capability in NETCONF. Each 315 RESTCONF edit of a datastore resource is activated upon successful 316 completion of the transaction. 318 1.3. Terminology 320 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 321 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 322 "OPTIONAL" in this document are to be interpreted as described in BCP 323 14, [RFC2119]. 325 1.3.1. NETCONF 327 The following terms are defined in [RFC6241]: 329 o candidate configuration datastore 331 o client 333 o configuration data 334 o datastore 336 o configuration datastore 338 o protocol operation 340 o running configuration datastore 342 o server 344 o startup configuration datastore 346 o state data 348 o user 350 1.3.2. HTTP 352 The following terms are defined in [RFC3986]: 354 o fragment 356 o path 358 o query 360 The following terms are defined in [RFC7230]: 362 o header 364 o message-body 366 o request-line 368 o request URI 370 o status-line 372 The following terms are defined in [RFC7231]: 374 o method 376 o request 378 o resource 380 The following terms are defined in [RFC7232]: 382 o entity tag 384 1.3.3. YANG 386 The following terms are defined in [RFC6020]: 388 o container 390 o data node 392 o key leaf 394 o leaf 396 o leaf-list 398 o list 400 o presence container (or P-container) 402 o RPC operation (now called protocol operation) 404 o non-presence container (or NP-container) 406 o ordered-by system 408 o ordered-by user 410 1.3.4. Terms 412 The following terms are used within this document: 414 o API resource: a resource with the media type "application/ 415 yang.api+xml" or "application/yang.api+json". 417 o data resource: a resource with the media type "application/ 418 yang.data+xml" or "application/yang.data+json". Containers, 419 leafs, list entries and anyxml nodes can be data resources. 421 o datastore resource: a resource with the media type "application/ 422 yang.datastore+xml" or "application/yang.datastore+json". 423 Represents a datastore. 425 o edit operation: a RESTCONF operation on a data resource using 426 either a POST, PUT, PATCH, or DELETE method. 428 o event stream resource: This resource represents an SSE (Server- 429 Sent Events) event stream. The content consists of text using the 430 media type "text/event-stream", as defined by the HTML5 431 specification. Each event represents one message 432 generated by the server. It contains a conceptual system or data- 433 model specific event that is delivered within a notification event 434 stream. Also called a "stream resource". 436 o media-type: HTTP uses Internet media types [RFC2046] in the 437 Content-Type and Accept header fields in order to provide open and 438 extensible data typing and type negotiation. 440 o operation: the conceptual RESTCONF operation for a message, 441 derived from the HTTP method, request URI, headers, and message- 442 body. 444 o operation resource: a resource with the media type "application/ 445 yang.operation+xml" or "application/yang.operation+json". 447 o patch: a generic PATCH request on the target datastore or data 448 resource. The media type of the message-body content will 449 identify the patch type in use. 451 o plain patch: a specific PATCH request type that can be used for 452 simple merge operations. 454 o query parameter: a parameter (and its value if any), encoded 455 within the query component of the request URI. 457 o RESTCONF capability: An optional RESTCONF protocol feature 458 supported by the server, which is identified by an IANA registered 459 NETCONF Capability URI, and advertised with an entry in the 460 "capability" leaf-list in Section 9.3. 462 o retrieval request: a request using the GET or HEAD methods. 464 o target resource: the resource that is associated with a particular 465 message, identified by the "path" component of the request URI. 467 o unified datastore: A conceptual representation of the device 468 running configuration. The server will hide all NETCONF datastore 469 details for edit operations, such as the ":candidate" and 470 ":startup" capabilities. 472 o schema resource: a resource with the media type "application/ 473 yang". The YANG representation of the schema can be retrieved by 474 the client with the GET method. 476 o stream list: the set of data resource instances that describe the 477 event stream resources available from the server. This 478 information is defined in the "ietf-restconf-monitoring" module as 479 the "stream" list. It can be retrieved using the target resource 480 "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/ 481 stream". The stream list contains information about each stream, 482 such as the URL to retrieve the event stream data. 484 1.3.5. URI Template 486 Throughout this document, the URI template [RFC6570] syntax 487 "{+restconf}" is used to refer to the RESTCONF API entry point 488 outside of an example. See Section 3.1 for details. 490 For simplicity, all of the examples in this document assume 491 "/restconf" as the discovered RESTCONF API root path. 493 1.3.6. Tree Diagrams 495 A simplified graphical representation of the data model is used in 496 this document. The meaning of the symbols in these diagrams is as 497 follows: 499 o Brackets "[" and "]" enclose list keys. 501 o Abbreviations before data node names: "rw" means configuration 502 data (read-write) and "ro" state data (read-only). 504 o Symbols after data node names: "?" means an optional node, "!" 505 means a presence container, and "*" denotes a list and leaf-list. 507 o Parentheses enclose choice and case nodes, and case nodes are also 508 marked with a colon (":"). 510 o Ellipsis ("...") stands for contents of subtrees that are not 511 shown. 513 2. Transport Protocol Requirements 515 2.1. Integrity and Confidentiality 517 HTTP [RFC7230] is an application layer protocol that may be layered 518 on any reliable transport-layer protocol. RESTCONF is defined on top 519 of HTTP, but due to the sensitive nature of the information conveyed, 520 RESTCONF requires that the transport-layer protocol provides both 521 data integrity and confidentiality, such as are provided by the TLS 522 protocol [RFC5246]. 524 2.2. HTTPS with X.509v3 Certificates 526 Given the nearly ubiquitous support for HTTP over TLS [RFC7230], 527 RESTCONF implementations MUST support the "https" URI scheme, which 528 has the IANA assigned default port 443. Consistent with the 529 exclusive use of X.509v3 certificates for NETCONF over TLS 530 [draft-ietf-netconf-rfc5539bis-07], use of certificates in RESTCONF 531 is also limited to X.509v3 certificates. 533 2.3. Certificate Validation 535 When presented an X.509 certificate, the RESTCONF peer MUST use X.509 536 certificate path validation [RFC5280] to verify the integrity of the 537 certificate. The presented X.509 certificate MAY also be considered 538 valid if it matches a locally configured certificate fingerprint. If 539 X.509 certificate path validation fails and the presented X.509 540 certificate does not match a locally configured certificate 541 fingerprint, the connection MUST be terminated as defined in 542 [RFC5246]. 544 2.4. Authenticated Server Identity 546 The RESTCONF client MUST carefully examine the certificate presented 547 by the RESTCONF server to determine if it meets the client's 548 expectations. If the RESTCONF client has external information as to 549 the expected identity of the RESTCONF server, the hostname check MAY 550 be omitted. Otherwise, the RESTCONF client MUST check its 551 understanding of the RESTCONF server hostname against the server's 552 identity as presented in the server certificate message. Matching is 553 performed according to the rules and guidelines defined in [RFC6125]. 554 If the match fails, the RESTCONF client MUST either ask for explicit 555 user confirmation or terminate the connection with an indication that 556 the RESTCONF server's identity is suspect. 558 2.5. Authenticated Client Identity 560 The RESTCONF server MUST authenticate the client access to any 561 protected resource using HTTP Authentication [RFC7235]. If the 562 RESTCONF client is not authenticated to access a resource, the server 563 MUST send a response with status code 401 (Unauthorized) and a WWW- 564 Authenticate header field containing at least one challenge 565 applicable to the target resource. The RESTCONF server MAY advertise 566 support for any number of authentication schemes but, in order to 567 ensure interoperability, the RESTCONF server MUST advertise at least 568 one of the following authentication schemes: 570 o Basic [draft-ietf-httpauth-basicauth-update-03] 571 o Digest [draft-ietf-httpauth-digest-09] 573 o ClientCertificate [draft-thomson-httpbis-cant-01] 575 These authentication schemes are selected due to their similarity to 576 authentication schemes supported by NETCONF. In particular, the 577 Basic and Digest authentication schemes both directly provide an 578 identity and verification of a shared secret, much like NETCONF over 579 SSH, when using the SSH "password" authentication method [RFC4252]. 580 Similarly, the ClientCertificate authentication scheme is much like 581 NETCONF over TLS's use of X.509 client-certificates. When using the 582 ClientCertificate authentication scheme, the RESTCONF server MUST 583 verify the identity of the RESTCONF client using the algorithm 584 defined in section 7 of [draft-ietf-netconf-rfc5539bis-07]. 586 The RESTCONF client identity determined from any HTTP authentication 587 scheme is hereafter known as the "RESTCONF username" and subject to 588 the NETCONF Access Control Module (NACM) [RFC6536]. 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 notification events. 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 notification event 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 users 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; e.g. in this example a 651 custom "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" : { "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 state and access points for the 698 RESTCONF features. 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 This resource has the following child resources: 715 +----------------+--------------------------------+ 716 | Child Resource | Description | 717 +----------------+--------------------------------+ 718 | data | Contains all data resources | 719 | operations | Data-model specific operations | 720 +----------------+--------------------------------+ 722 RESTCONF API Resource 724 3.3.1. {+restconf}/data 726 This mandatory resource represents the combined configuration and 727 operational data resources that can be accessed by a client. It 728 cannot be created or deleted by the client. The datastore resource 729 type is defined in Section 3.4. 731 Example: 733 This example request by the client would retrieve only the non- 734 configuration data nodes that exist within the "library" resource, 735 using the "content" query parameter (see Section 4.8.3). 737 GET /restconf/data/example-jukebox:jukebox/library 738 ?content=nonconfig HTTP/1.1 739 Host: example.com 740 Accept: application/yang.data+json 742 The server might respond: 744 HTTP/1.1 200 OK 745 Date: Mon, 23 Apr 2012 17:01:30 GMT 746 Server: example-server 747 Cache-Control: no-cache 748 Pragma: no-cache 749 Content-Type: application/yang.data+json 751 { 752 "example-jukebox:library" : { 753 "artist-count" : 42, 754 "album-count" : 59, 755 "song-count" : 374 756 } 757 } 759 3.3.2. {+restconf}/operations 761 This optional resource is a container that provides access to the 762 data-model specific protocol operations supported by the server. The 763 server MAY omit this resource if no data-model specific operations 764 are advertised. 766 Any data-model specific operations defined in the YANG modules 767 advertised by the server MAY be available as child nodes of this 768 resource. 770 Operation resources are defined in Section 3.6. 772 3.4. Datastore Resource 774 The "{+restconf}/data" subtree represents the datastore resource 775 type, which is a collection of configuration and operational data 776 nodes. 778 A "unified datastore" interface is used to simplify resource editing 779 for the client. The RESTCONF unified datastore is a conceptual 780 interface to the native configuration datastores that are present on 781 the device. 783 The underlying NETCONF datastores (i.e., candidate, running, startup) 784 can be used to implement the unified datastore, but the server design 785 is not limited to the exact datastore procedures defined in NETCONF. 787 The "candidate" and "startup" datastores are not visible in the 788 RESTCONF protocol. Transaction management and configuration 789 persistence are handled by the server and not controlled by the 790 client. 792 A datastore resource can only be written directly with the PATCH 793 method. Only the configuration data resources within the datastore 794 resource can be edited directly with all methods. 796 Each RESTCONF edit of a datastore resource is saved to non-volatile 797 storage in an implementation-specific matter by the server. There is 798 no guarantee that configuration changes are saved immediately, or 799 that the saved configuration is always a mirror of the NETCONF 800 running datastore, if the server also supports NETCONF. 802 3.4.1. Edit Collision Detection 804 Two "edit collision detection" mechanisms are provided in RESTCONF, 805 for datastore and data resources. 807 3.4.1.1. Timestamp 809 The last change time is maintained and the "Last-Modified" 810 ([RFC7232], section 2.2) header is returned in the response for a 811 retrieval request. The "If-Unmodified-Since" header can be used in 812 edit operation requests to cause the server to reject the request if 813 the resource has been modified since the specified timestamp. 815 The server MUST maintain a last-modified timestamp for the top-level 816 {+restconf}/data resource and SHOULD maintain last-modified 817 timestamps for descendant resources. For all resources, the server 818 MUST return the "Last-Modified" header when the resource is retrieved 819 with the GET or HEAD methods. If the server does not maintain a 820 timestamp for a resource, it MUST return the timestamp of the 821 resource's ancestor, a process that may recurse up to the top-level 822 {+restconf}/data resource. Only changes to configuration data 823 resources within the datastore affect the timestamp. 825 3.4.1.2. Entity tag 827 A unique opaque string is maintained and the "ETag" ([RFC7232], 828 section 2.3) header is returned in the response for a retrieval 829 request. The "If-Match" header can be used in edit operation 830 requests to cause the server to reject the request if the resource 831 entity tag does not match the specified value. 833 The server MUST maintain an entity tag for the top-level 834 {+restconf}/data resource and SHOULD maintain entity tags for 835 descendant resources. For all resources, the server MUST return the 836 "ETag" header when the resource is retrieved with the GET or HEAD 837 methods. If the server does not maintain an entity tag for a 838 resource, it MUST return the entity tag of the resource's ancestor, a 839 process that may recurse up to the top-level {+restconf}/data 840 resource. Only changes to configuration data resources within the 841 datastore affect the entity tag. 843 3.5. Data Resource 845 A data resource represents a YANG data node that is a descendant node 846 of a datastore resource. Each YANG-defined data node can be uniquely 847 targeted by the request-line of an HTTP operation. Containers, 848 leafs, list entries and anyxml nodes are data resources. 850 The representation maintained for each data resource is the YANG 851 defined subtree for that node. HTTP operations on a data resource 852 affect both the targeted data node and all its descendants, if any. 854 For configuration data resources, the server MAY maintain a last- 855 modified timestamp for the resource, and return the "Last-Modified" 856 header when it is retrieved with the GET or HEAD methods. If 857 maintained, the resource timestamp MUST be set to the current time 858 whenever the resource or any configuration resource within the 859 resource is altered. 861 For configuration data resources, the server MAY maintain a resource 862 entity tag for the resource, and return the "ETag" header when it is 863 retrieved as the target resource with the GET or HEAD methods. If 864 maintained, the resource entity tag MUST be updated whenever the 865 resource or any configuration resource within the resource is 866 altered. 868 A data resource can be retrieved with the GET method. Data resources 869 are accessed via the "{+restconf}/data" entry point. This sub-tree 870 is used to retrieve and edit data resources. 872 A configuration data resource can be altered by the client with some 873 or all of the edit operations, depending on the target resource and 874 the specific operation. Refer to Section 4 for more details on edit 875 operations. 877 The resource definition version for a data resource is identified by 878 the revision date of the YANG module containing the YANG definition 879 for the data resource. 881 3.5.1. Encoding Data Resource Identifiers in the Request URI 883 In YANG, data nodes are named with an absolute XPath expression, 884 defined in [XPath], starting from the document root to the target 885 resource. In RESTCONF, URL encoded path expressions are used 886 instead. 888 A predictable location for a data resource is important, since 889 applications will code to the YANG data model module, which uses 890 static naming and defines an absolute path location for all data 891 nodes. 893 A RESTCONF data resource identifier is not an XPath expression. It 894 is encoded from left to right, starting with the top-level data node, 895 according to the "api-path" rule in Section 3.5.1.1. The node name 896 of each ancestor of the target resource node is encoded in order, 897 ending with the node name for the target resource. 899 If a data node in the path expression is a YANG list node, then the 900 key values for the list (if any) MUST be encoded according to the 901 following rules. 903 o The key leaf values for a data resource representing a YANG list 904 MUST be encoded using one path segment [RFC3986]. 906 o If there is only one key leaf value, the path segment is 907 constructed by having the list name followed by an "=" followed by 908 the single key leaf value. 910 o If there are multiple key leaf values, the value of each leaf 911 identified in the "key" statement is encoded in the order 912 specified in the YANG "key" statement, with a comma separating 913 them. 915 o All the components in the "key" statement MUST be encoded. 916 Partial instance identifiers are not supported. 918 o Quoted strings are supported in the key leaf values. Quoted 919 strings MUST be used to express empty strings. (example: 920 list=foo,'',baz). 922 o The "list-instance" ABNF rule defined in Section 3.5.1.1 923 represents the syntax of a list instance identifier. 925 o Resource URI values returned in Location headers for data 926 resources MUST identify the module name, even if there are no 927 conflicting local names when the resource is created. This 928 ensures the correct resource will be identified even if the server 929 loads a new module that the old client does not know about. 931 Examples: 933 container top { 934 list list1 { 935 key "key1 key2 key3"; 936 ... 937 list list2 { 938 key "key4 key5"; 939 ... 940 leaf X { type string; } 941 } 942 } 943 } 945 For the above YANG definition, URI with key leaf values will be 946 encoded as follows (line wrapped for display purposes only): 948 /restconf/data/example-top:top/list1=key1val,key2val,key3val3/ 949 list2=key4val,key5val/X 951 3.5.1.1. ABNF For Data Resource Identifiers 953 The "api-path" ABNF syntax is used to construct RESTCONF path 954 identifiers: 956 api-path = "/" | 957 ("/" api-identifier 958 0*("/" (api-identifier | list-instance ))) 960 api-identifier = [module-name ":"] identifier ;; note 1 962 module-name = identifier 964 list-instance = api-identifier "=" key-value ["," key-value]* 966 key-value = string 968 string = 970 ;; An identifier MUST NOT start with 971 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 972 identifier = (ALPHA / "_") 973 *(ALPHA / DIGIT / "_" / "-" / ".") 975 Note 1: The syntax for "api-identifier" MUST conform to the JSON 976 identifier encoding rules in section 4 of 977 [I-D.ietf-netmod-yang-json]. 979 3.5.2. Defaults Handling 981 RESTCONF requires that a server report its default handling mode (see 982 Section 4.8.2 for details). If the optional "with-defaults" query 983 parameter is supported by the server, a client may use it to control 984 retrieval of default values (see Section 4.8.11 for details). 986 If the target of a GET method is a data node that represents a leaf 987 that has a default value, and the leaf has not been given a value 988 yet, the server MUST return the default value that is in use by the 989 server. 991 If the target of a GET method is a data node that represents a 992 container or list that has any child resources with default values, 993 for the child resources that have not been given value yet, the 994 server MAY return the default values that are in use by the server, 995 in accordance with its reported default handing mode and query 996 parameters passed by the client. 998 3.6. Operation Resource 1000 An operation resource represents a protocol operation defined with 1001 the YANG "rpc" statement. 1003 All operation resources share the same module namespace as any top- 1004 level data resources, so the name of an operation resource cannot 1005 conflict with the name of a top-level data resource defined within 1006 the same module. 1008 If 2 different YANG modules define the same "rpc" identifier, then 1009 the module name MUST be used in the request URI. For example, if 1010 "module-A" and "module-B" both defined a "reset" operation, then 1011 invoking the operation from "module-A" would be requested as follows: 1013 POST /restconf/operations/module-A:reset HTTP/1.1 1014 Server example.com 1016 Any usage of an operation resource from the same module, with the 1017 same name, refers to the same "rpc" statement definition. This 1018 behavior can be used to design protocol operations that perform the 1019 same general function on different resource types. 1021 If the "rpc" statement has an "input" section, then a message-body 1022 MAY be sent by the client in the request, otherwise the request 1023 message MUST NOT include a message-body. If the "rpc" statement has 1024 an "output" section, then a message-body MAY be sent by the server in 1025 the response, otherwise the response message MUST NOT include a 1026 message-body in the response message, and MUST send a "204 No 1027 Content" status-line instead. 1029 3.6.1. Encoding Operation Input Parameters 1031 If the "rpc" statement has an "input" section, then the "input" node 1032 is provided in the message-body, corresponding to the YANG data 1033 definition statements within the "input" section. 1035 Example: 1037 The following YANG definition is used for the examples in this 1038 section. 1040 rpc reboot { 1041 input { 1042 leaf delay { 1043 units seconds; 1044 type uint32; 1045 default 0; 1046 } 1047 leaf message { type string; } 1048 leaf language { type string; } 1049 } 1050 } 1052 The client might send the following POST request message: 1054 POST /restconf/operations/example-ops:reboot HTTP/1.1 1055 Host: example.com 1056 Content-Type: application/yang.operation+json 1058 { 1059 "example-ops:input" : { 1060 "delay" : 600, 1061 "message" : "Going down for system maintenance", 1062 "language" : "en-US" 1063 } 1064 } 1066 The server might respond: 1068 HTTP/1.1 204 No Content 1069 Date: Mon, 25 Apr 2012 11:01:00 GMT 1070 Server: example-server 1072 3.6.2. Encoding Operation Output Parameters 1074 If the "rpc" statement has an "output" section, then the "output" 1075 node is provided in the message-body, corresponding to the YANG data 1076 definition statements within the "output" section. 1078 Example: 1080 The following YANG definition is used for the examples in this 1081 section. 1083 rpc get-reboot-info { 1084 output { 1085 leaf reboot-time { 1086 units seconds; 1087 type uint32; 1088 } 1089 leaf message { type string; } 1090 leaf language { type string; } 1091 } 1092 } 1094 The client might send the following POST request message: 1096 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 1097 Host: example.com 1098 Accept: application/yang.operation+json 1100 The server might respond: 1102 HTTP/1.1 200 OK 1103 Date: Mon, 25 Apr 2012 11:10:30 GMT 1104 Server: example-server 1105 Content-Type: application/yang.operation+json 1107 { 1108 "example-ops:output" : { 1109 "reboot-time" : 30, 1110 "message" : "Going down for system maintenance", 1111 "language" : "en-US" 1112 } 1113 } 1115 3.7. Schema Resource 1117 The server can optionally support retrieval of the YANG modules it 1118 supports. To retrieve a YANG module, a client first needs to get the 1119 URL for retrieving the schema. 1121 The client might send the following GET request message: 1123 GET /restconf/data/ietf-yang-library:modules/module= 1124 example-jukebox,2014-07-03/schema HTTP/1.1 1125 Host: example.com 1126 Accept: application/yang.data+json 1128 The server might respond: 1130 HTTP/1.1 200 OK 1131 Date: Mon, 25 Apr 2012 11:10:30 GMT 1132 Server: example-server 1133 Content-Type: application/yang.data+json 1135 { 1136 "ietf-yang-library:schema": 1137 "https://example.com/mymodules/example-jukebox/2014-07-03" 1138 } 1140 Next the client needs to retrieve the actual YANG schema. 1142 The client might send the following GET request message: 1144 GET https://example.com/mymodules/example-jukebox/2014-07-03 1145 HTTP/1.1 1146 Host: example.com 1147 Accept: application/yang 1149 The server might respond: 1151 module example-jukebox { 1153 namespace "http://example.com/ns/example-jukebox"; 1154 prefix "jbox"; 1156 // rest of YANG module content deleted... 1157 } 1159 3.8. Event Stream Resource 1161 An "event stream" resource represents a source for system generated 1162 event notifications. Each stream is created and modified by the 1163 server only. A client can retrieve a stream resource or initiate a 1164 long-poll server sent event stream, using the procedure specified in 1165 Section 6.3. 1167 A notification stream functions according to the NETCONF 1168 Notifications specification [RFC5277]. The available streams can be 1169 retrieved from the stream list, which specifies the syntax and 1170 semantics of a stream resource. 1172 3.9. Errors Media Type 1174 An "errors" media type is a collection of error information that is 1175 sent as the message-body in a server response message, if an error 1176 occurs while processing a request message. It is not considered a 1177 resource type because no instances can be retrieved with a GET 1178 request. 1180 The "ietf-restconf" YANG module contains the "application/ 1181 yang.errors" restconf-media-type extension which specifies the syntax 1182 and semantics of an "errors" media type. RESTCONF error handling 1183 behavior is defined in Section 7. 1185 4. Operations 1187 The RESTCONF protocol uses HTTP methods to identify the CRUD 1188 operation requested for a particular resource. 1190 The following table shows how the RESTCONF operations relate to 1191 NETCONF protocol operations: 1193 +----------+-------------------------------------+ 1194 | RESTCONF | NETCONF | 1195 +----------+-------------------------------------+ 1196 | OPTIONS | none | 1197 | HEAD | none | 1198 | GET | , | 1199 | POST | (operation="create") | 1200 | PUT | (operation="replace") | 1201 | PATCH | (operation="merge") | 1202 | DELETE | (operation="delete") | 1203 +----------+-------------------------------------+ 1205 Table 1: CRUD Methods in RESTCONF 1207 The NETCONF "remove" operation attribute is not supported by the HTTP 1208 DELETE method. The resource must exist or the DELETE method will 1209 fail. The PATCH method is equivalent to a "merge" operation when 1210 using a plain patch (see Section 4.6.1), other media-types may 1211 provide more granular control. 1213 Access control mechanisms may be used to limit what operations can be 1214 used. In particular, RESTCONF is compatible with the NETCONF Access 1215 Control Model (NACM) [RFC6536], as there is a specific mapping 1216 between RESTCONF and NETCONF operations, defined in Table 1. The 1217 resource path needs to be converted internally by the server to the 1218 corresponding YANG instance-identifier. Using this information, the 1219 server can apply the NACM access control rules to RESTCONF messages. 1221 The server MUST NOT allow any operation to any resources that the 1222 client is not authorized to access. 1224 Implementation of all methods (except PATCH) are defined in 1225 [RFC7231]. This section defines the RESTCONF protocol usage for each 1226 HTTP method. 1228 4.1. OPTIONS 1230 The OPTIONS method is sent by the client to discover which methods 1231 are supported by the server for a specific resource (e.g., GET, POST, 1232 DELETE, etc.). 1234 The server SHOULD implement this method, however the same information 1235 could be extracted from the YANG modules and the RESTCONF protocol 1236 specification. 1238 If the PATCH method is supported, then the "Accept-Patch" header MUST 1239 be supported and returned in the response to the OPTIONS request, as 1240 defined in [RFC5789]. 1242 4.2. HEAD 1244 The HEAD method is sent by the client to retrieve just the headers 1245 that would be returned for the comparable GET method, without the 1246 response message-body. It is supported for all resource types, 1247 except operation resources. 1249 The request MUST contain a request URI that contains at least the 1250 entry point component. The same query parameters supported by the 1251 GET method are supported by the HEAD method. 1253 The access control behavior is enforced as if the method was GET 1254 instead of HEAD. The server MUST respond the same as if the method 1255 was GET instead of HEAD, except that no response message-body is 1256 included. 1258 4.3. GET 1260 The GET method is sent by the client to retrieve data and meta-data 1261 for a resource. It is supported for all resource types, except 1262 operation resources. The request MUST contain a request URI that 1263 contains at least the entry point component. 1265 The server MUST NOT return any data resources for which the user does 1266 not have read privileges. If the user is not authorized to read the 1267 target resource, an error response containing a "403 Forbidden" or 1268 "404 Not Found" status-line is returned to the client. 1270 If the user is authorized to read some but not all of the target 1271 resource, the unauthorized content is omitted from the response 1272 message-body, and the authorized content is returned to the client. 1274 Example: 1276 The client might request the response headers for a JSON 1277 representation of the "library" resource: 1279 GET /restconf/data/example-jukebox:jukebox/ 1280 library/artist=Foo%20Fighters/album HTTP/1.1 1281 Host: example.com 1282 Accept: application/yang.data+json 1284 The server might respond: 1286 HTTP/1.1 200 OK 1287 Date: Mon, 23 Apr 2012 17:02:40 GMT 1288 Server: example-server 1289 Content-Type: application/yang.data+json 1290 Cache-Control: no-cache 1291 Pragma: no-cache 1292 ETag: a74eefc993a2b 1293 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1295 { 1296 "example-jukebox:album" : [ 1297 { 1298 "name" : "Wasting Light", 1299 "genre" : "example-jukebox:alternative", 1300 "year" : 2011 1301 } 1302 ] 1303 } 1305 4.4. POST 1307 The POST method is sent by the client to create a data resource or 1308 invoke an operation resource. The server uses the target resource 1309 media type to determine how to process the request. 1311 +-----------+------------------------------------------------+ 1312 | Type | Description | 1313 +-----------+------------------------------------------------+ 1314 | Datastore | Create a top-level configuration data resource | 1315 | Data | Create a configuration data child resource | 1316 | Operation | Invoke a protocol operation | 1317 +-----------+------------------------------------------------+ 1319 Resource Types that Support POST 1321 4.4.1. Create Resource Mode 1323 If the target resource type is a datastore or data resource, then the 1324 POST is treated as a request to create a top-level resource or child 1325 resource, respectively. The message-body is expected to contain the 1326 content of a child resource to create within the parent (target 1327 resource). The data-model for the child tree is the subtree is 1328 defined by YANG for the child resource. 1330 The "insert" and "point" query parameters are supported by the POST 1331 method for datastore and data resource types, as specified in the 1332 YANG definition in Section 8. 1334 If the POST method succeeds, a "201 Created" status-line is returned 1335 and there is no response message-body. A "Location" header 1336 identifying the child resource that was created MUST be present in 1337 the response in this case. 1339 If the user is not authorized to create the target resource, an error 1340 response containing a "403 Forbidden" or "404 Not Found" status-line 1341 is returned to the client. All other error responses are handled 1342 according to the procedures defined in Section 7. 1344 Example: 1346 To create a new "jukebox" resource, the client might send: 1348 POST /restconf/data HTTP/1.1 1349 Host: example.com 1350 Content-Type: application/yang.data+json 1352 { "example-jukebox:jukebox" : [null] } 1354 If the resource is created, the server might respond as follows: 1356 HTTP/1.1 201 Created 1357 Date: Mon, 23 Apr 2012 17:01:00 GMT 1358 Server: example-server 1359 Location: https://example.com/restconf/data/example-jukebox:jukebox 1360 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 1361 ETag: b3a3e673be2 1363 Refer to Appendix D.2.1 for more resource creation examples. 1365 4.4.2. Invoke Operation Mode 1367 If the target resource type is an operation resource, then the POST 1368 method is treated as a request to invoke that operation. The 1369 message-body (if any) is processed as the operation input parameters. 1370 Refer to Section 3.6 for details on operation resources. 1372 If the POST request succeeds, a "200 OK" status-line is returned if 1373 there is a response message-body, and a "204 No Content" status-line 1374 is returned if there is no response message-body. 1376 If the user is not authorized to invoke the target operation, an 1377 error response containing a "403 Forbidden" or "404 Not Found" 1378 status-line is returned to the client. All other error responses are 1379 handled according to the procedures defined in Section 7. 1381 Example: 1383 In this example, the client is invoking the "play" operation defined 1384 in the "example-jukebox" YANG module. 1386 A client might send a "play" request as follows: 1388 POST /restconf/operations/example-jukebox:play HTTP/1.1 1389 Host: example.com 1390 Content-Type: application/yang.operation+json 1392 { 1393 "example-jukebox:input" : { 1394 "playlist" : "Foo-One", 1395 "song-number" : 2 1396 } 1397 } 1399 The server might respond: 1401 HTTP/1.1 204 No Content 1402 Date: Mon, 23 Apr 2012 17:50:00 GMT 1403 Server: example-server 1405 4.5. PUT 1407 The PUT method is sent by the client to create or replace the target 1408 resource. 1410 The only target resource media type that supports PUT is the data 1411 resource. The message-body is expected to contain the content used 1412 to create or replace the target resource. 1414 The "insert" (Section 4.8.6) and "point" (Section 4.8.7) query 1415 parameters are supported by the PUT method for data resources. 1417 Consistent with [RFC7231], if the PUT request creates a new resource, 1418 a "201 Created" status-line is returned. If an existing resource is 1419 modified, either "200 OK" or "204 No Content" are returned. 1421 If the user is not authorized to create or replace the target 1422 resource an error response containing a "403 Forbidden" or "404 Not 1423 Found" status-line is returned to the client. All other error 1424 responses are handled according to the procedures defined in 1425 Section 7. 1427 Example: 1429 An "album" child resource defined in the "example-jukebox" YANG 1430 module is replaced or created if it does not already exist. 1432 To replace the "album" resource contents, the client might send as 1433 follows. Note that the request-line is wrapped for display purposes 1434 only: 1436 PUT /restconf/data/example-jukebox:jukebox/ 1437 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1438 Host: example.com 1439 Content-Type: application/yang.data+json 1441 { 1442 "example-jukebox:album" : { 1443 "name" : "Wasting Light", 1444 "genre" : "example-jukebox:alternative", 1445 "year" : 2011 1446 } 1447 } 1449 If the resource is updated, the server might respond: 1451 HTTP/1.1 204 No Content 1452 Date: Mon, 23 Apr 2012 17:04:00 GMT 1453 Server: example-server 1454 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 1455 ETag: b27480aeda4c 1457 4.6. PATCH 1459 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 1460 an extensible framework for resource patching mechanisms. It is 1461 optional to implement by the server. Each patch type needs a unique 1462 media type. Zero or more PATCH media types MAY be supported by the 1463 server. The media types supported by a server can be discovered by 1464 the client by sending an OPTIONS request (see Section 4.1). 1466 If the target resource instance does not exist, the server MUST NOT 1467 create it. 1469 If the PATCH request succeeds, a "200 OK" status-line is returned if 1470 there is a message-body, and "204 No Content" is returned if no 1471 response message-body is sent. 1473 If the user is not authorized to alter the target resource an error 1474 response containing a "403 Forbidden" or "404 Not Found" status-line 1475 is returned to the client. All other error responses are handled 1476 according to the procedures defined in Section 7. 1478 4.6.1. Plain Patch 1480 The plain patch mechanism merges the contents of the message body 1481 with the target resource. If the target resource is a datastore 1482 resource (see Section 3.4), the message body MUST be either 1483 application/yang.datastore+xml or application/yang.datastore+json. 1484 If then the target resource is a data resource (see Section 3.5), 1485 then the message body MUST be either application/yang.data+xml or 1486 application/yang.data+json. 1488 Plain patch can used to create or update, but not delete, a child 1489 resource within the target resource. Please see 1490 [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting 1491 more granular control. 1493 Example: 1495 To replace just the "year" field in the "album" resource (instead of 1496 replacing the entire resource with the PUT method), the client might 1497 send a plain patch as follows. Note that the request-line is wrapped 1498 for display purposes only: 1500 PATCH /restconf/data/example-jukebox:jukebox/ 1501 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1502 Host: example.com 1503 If-Match: b8389233a4c 1504 Content-Type: application/yang.data+json 1506 { 1507 "example-jukebox:album" : { 1508 "year" : 2011 1509 } 1510 } 1512 If the field is updated, the server might respond: 1514 HTTP/1.1 204 No Content 1515 Date: Mon, 23 Apr 2012 17:49:30 GMT 1516 Server: example-server 1517 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 1518 ETag: b2788923da4c 1520 The XML encoding for the same request might be: 1522 PATCH /restconf/data/example-jukebox:jukebox/ 1523 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1524 Host: example.com 1525 If-Match: b8389233a4c 1526 Content-Type: application/yang.data+xml 1528 1529 2011 1530 1532 4.7. DELETE 1534 The DELETE method is used to delete the target resource. If the 1535 DELETE request succeeds, a "204 No Content" status-line is returned, 1536 and there is no response message-body. 1538 If the user is not authorized to delete the target resource then an 1539 error response containing a "403 Forbidden" or "404 Not Found" 1540 status-line is returned to the client. All other error responses are 1541 handled according to the procedures defined in Section 7. 1543 Example: 1545 To delete a resource such as the "album" resource, the client might 1546 send: 1548 DELETE /restconf/data/example-jukebox:jukebox/ 1549 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1550 Host: example.com 1552 If the resource is deleted, the server might respond: 1554 HTTP/1.1 204 No Content 1555 Date: Mon, 23 Apr 2012 17:49:40 GMT 1556 Server: example-server 1558 4.8. Query Parameters 1560 Each RESTCONF operation allows zero or more query parameters to be 1561 present in the request URI. The specific parameters that are allowed 1562 depends on the resource type, and sometimes the specific target 1563 resource used, in the request. 1565 +---------------+---------+-----------------------------------------+ 1566 | Name | Methods | Description | 1567 +---------------+---------+-----------------------------------------+ 1568 | content | GET | Select config and/or non-config data | 1569 | | | resources | 1570 | depth | GET | Request limited sub-tree depth in the | 1571 | | | reply content | 1572 | fields | GET | Request a subset of the target resource | 1573 | | | contents | 1574 | filter | GET | Boolean notification filter for event | 1575 | | | stream resources | 1576 | insert | POST, | Insertion mode for user-ordered data | 1577 | | PUT | resources | 1578 | point | POST, | Insertion point for user-ordered data | 1579 | | PUT | resources | 1580 | start-time | GET | Replay buffer start time for event | 1581 | | | stream resources | 1582 | stop-time | GET | Replay buffer stop time for event | 1583 | | | stream resources | 1584 | with-defaults | GET | Control retrieval of default values | 1585 +---------------+---------+-----------------------------------------+ 1587 RESTCONF Query Parameters 1589 Query parameters can be given in any order. Each parameter can 1590 appear at most once in a request URI. A default value may apply if 1591 the parameter is missing. 1593 Refer to Appendix D.3 for examples of query parameter usage. 1595 If vendors define additional query parameters, they SHOULD use a 1596 prefix (such as the enterprise or organization name) for query 1597 parameter names in order to avoid collisions with other parameters. 1599 4.8.1. Query Parameter URIs 1601 A new set of RESTCONF Capability URIs are defined to identify the 1602 specific query parameters and protocol features supported by the 1603 server. 1605 +--------------+----------------------------------------------------+ 1606 | Name | URI | 1607 +--------------+----------------------------------------------------+ 1608 | defaults | urn:ietf:params:restconf:capability:defaults:1.0 | 1609 | depth | urn:ietf:params:restconf:capability:depth:1.0 | 1610 | fields | urn:ietf:params:restconf:capability:fields:1.0 | 1611 | filter | urn:ietf:params:restconf:capability:filter:1.0 | 1612 | insert | urn:ietf:params:restconf:capability:insert:1.0 | 1613 | replay | urn:ietf:params:restconf:capability:replay:1.0 | 1614 | with- | urn:ietf:params:restconf:capability:with- | 1615 | defaults | defaults:1.0 | 1616 +--------------+----------------------------------------------------+ 1618 RESTCONF Query Parameter URIs 1620 4.8.2. The "defaults" Protocol Capability URI 1622 This URI identifies the defaults handling mode that is used by the 1623 server for processing default leafs in the unified datastore. A 1624 parameter named "basic-mode" is required for this capability URI. 1625 The "basic-mode" definitions are specified in the "With-Defaults 1626 Capability for NETCONF" [RFC6243]. 1628 This protocol capability URI MUST be supported by the server, and the 1629 MUST be listed in the "capability" leaf-list in Section 9.3. 1631 +------------+------------------------------------------------------+ 1632 | Value | Description | 1633 +------------+------------------------------------------------------+ 1634 | report-all | No data nodes are considered default | 1635 | trim | Values set to the YANG default-stmt value are | 1636 | | default | 1637 | explicit | Values set by the client are never considered | 1638 | | default | 1639 +------------+------------------------------------------------------+ 1640 If the "basic-mode" is set to "report-all" then the server MUST 1641 adhere to the defaults handling behavior defined in section 2.1 of 1642 [RFC6243]. 1644 If the "basic-mode" is set to "trim" then the server MUST adhere to 1645 the defaults handling behavior defined in section 2.2 of [RFC6243]. 1647 If the "basic-mode" is set to "explicit" then the server MUST adhere 1648 to the defaults handling behavior defined in section 2.3 of 1649 [RFC6243]. 1651 Example: (split for display purposes only) 1653 urn:ietf:params:restconf:capability:defaults:1.0? 1654 basic-mode=explicit 1656 4.8.3. The "content" Query Parameter 1658 The "content" parameter controls how descendant nodes of the 1659 requested data nodes will be processed in the reply. 1661 The allowed values are: 1663 +-----------+-----------------------------------------------------+ 1664 | Value | Description | 1665 +-----------+-----------------------------------------------------+ 1666 | config | Return only configuration descendant data nodes | 1667 | nonconfig | Return only non-configuration descendant data nodes | 1668 | all | Return all descendant data nodes | 1669 +-----------+-----------------------------------------------------+ 1671 This parameter is only allowed for GET methods on datastore and data 1672 resources. A 400 Bad Request error is returned if used for other 1673 methods or resource types. 1675 The default value is determined by the "config" statement value of 1676 the requested data nodes. If the "config" value is "false", then the 1677 default for the "content" parameter is "nonconfig". If "config" is 1678 "true" then the default for the "content" parameter is "config". 1680 This query parameter MUST be supported by the server. 1682 4.8.4. The "depth" Query Parameter 1684 The "depth" parameter is used to specify the number of nest levels 1685 returned in a response for a GET method. The first nest-level 1686 consists of the requested data node itself. Any child nodes which 1687 are contained within a parent node have a depth value that is 1 1688 greater than its parent. 1690 The value of the "depth" parameter is either an integer between 1 and 1691 65535, or the string "unbounded". "unbounded" is the default. 1693 This parameter is only allowed for GET methods on API, datastore, and 1694 data resources. A 400 Bad Request error is returned if it used for 1695 other methods or resource types. 1697 By default, the server will include all sub-resources within a 1698 retrieved resource, which have the same resource type as the 1699 requested resource. Only one level of sub-resources with a different 1700 media type than the target resource will be returned. 1702 If this query parameter is supported by the server, then the "depth" 1703 query parameter URI MUST be listed in the "capability" leaf-list in 1704 Section 9.3. 1706 4.8.5. The "fields" Query Parameter 1708 The "fields" query parameter is used to optionally identify data 1709 nodes within the target resource to be retrieved in a GET method. 1710 The client can use this parameter to retrieve a subset of all nodes 1711 in a resource. 1713 A value of the "fields" query parameter matches the following rule: 1715 fields-expr = path '(' fields-expr / '*' ')' / 1716 path ';' fields-expr / 1717 path 1718 path = api-identifier [ '/' path ] 1720 "api-identifier" is defined in Section 3.5.1.1. 1722 ";" is used to select multiple nodes. For example, to retrieve only 1723 the "genre" and "year" of an album, use: "fields=genre;year". 1725 Parentheses are used to specify sub-selectors of a node. For 1726 example, to retrieve only the "label" and "catalogue-number" of an 1727 album, use: "fields=admin(label;catalogue-number)". 1729 "/" is used in a path to retrieve a child node of a node. For 1730 example, to retrieve only the "label" of an album, use: 1731 "fields=admin/label". 1733 This parameter is only allowed for GET methods on api, datastore, and 1734 data resources. A 400 Bad Request error is returned if used for 1735 other methods or resource types. 1737 If this query parameter is supported by the server, then the "fields" 1738 query parameter URI MUST be listed in the "capability" leaf-list in 1739 Section 9.3. 1741 4.8.6. The "insert" Query Parameter 1743 The "insert" parameter is used to specify how a resource should be 1744 inserted within a user-ordered list. 1746 The allowed values are: 1748 +--------+----------------------------------------------------------+ 1749 | Value | Description | 1750 +--------+----------------------------------------------------------+ 1751 | first | Insert the new data as the new first entry. | 1752 | last | Insert the new data as the new last entry. | 1753 | before | Insert the new data before the insertion point, as | 1754 | | specified by the value of the "point" parameter. | 1755 | after | Insert the new data after the insertion point, as | 1756 | | specified by the value of the "point" parameter. | 1757 +--------+----------------------------------------------------------+ 1759 The default value is "last". 1761 This parameter is only supported for the POST and PUT methods. It is 1762 also only supported if the target resource is a data resource, and 1763 that data represents a YANG list or leaf-list that is ordered by the 1764 user. 1766 If the values "before" or "after" are used, then a "point" query 1767 parameter for the insertion parameter MUST also be present, or a 400 1768 Bad Request error is returned. 1770 If this query parameter is supported by the server, then the "insert" 1771 query parameter URI MUST be listed in the "capability" leaf-list in 1772 Section 9.3. The "point" query parameter MUST also be supported by 1773 the server. 1775 4.8.7. The "point" Query Parameter 1777 The "point" parameter is used to specify the insertion point for a 1778 data resource that is being created or moved within a user ordered 1779 list or leaf-list. 1781 The value of the "point" parameter is of type 1782 "data-resource-identifier", defined in the "ietf-restconf" YANG 1783 module Section 8. 1785 This parameter is only supported for the POST and PUT methods. It is 1786 also only supported if the target resource is a data resource, and 1787 that data represents a YANG list or leaf-list that is ordered by the 1788 user. 1790 If the "insert" query parameter is not present, or has a value other 1791 than "before" or "after", then a 400 Bad Request error is returned. 1793 This parameter contains the instance identifier of the resource to be 1794 used as the insertion point for a POST or PUT method. 1796 If the server includes the "insert" query parameter URI in the 1797 "capability" leaf-list in Section 9.3, then the "point" query 1798 parameter MUST be supported. 1800 4.8.8. The "filter" Query Parameter 1802 The "filter" parameter is used to indicate which subset of all 1803 possible events are of interest. If not present, all events not 1804 precluded by other parameters will be sent. 1806 This parameter is only allowed for GET methods on a text/event-stream 1807 data resource. A 400 Bad Request error is returned if used for other 1808 methods or resource types. 1810 The format of this parameter is an XPath 1.0 expression, and is 1811 evaluated in the following context: 1813 o The set of namespace declarations is the set of prefix and 1814 namespace pairs for all supported YANG modules, where the prefix 1815 is the YANG module name, and the namespace is as defined by the 1816 "namespace" statement in the YANG module. 1818 o The function library is the core function library defined in XPath 1819 1.0. 1821 o The set of variable bindings is empty. 1823 o The context node is the root node. 1825 The filter is used as defined in [RFC5277], section 3.6. If the 1826 boolean result of the expression is true when applied to the 1827 conceptual "notification" document root, then the notification event 1828 is delivered to the client. 1830 If this query parameter is supported by the server, then the "filter" 1831 query parameter URI MUST be listed in the "capability" leaf-list in 1832 Section 9.3. 1834 4.8.9. The "start-time" Query Parameter 1836 The "start-time" parameter is used to trigger the notification replay 1837 feature and indicate that the replay should start at the time 1838 specified. If the stream does not support replay, per the 1839 "replay-support" attribute returned by stream list entry for the 1840 stream resource, then the server MUST return the HTTP error code 400 1841 Bad Request. 1843 The value of the "start-time" parameter is of type "date-and-time", 1844 defined in the "ietf-yang" YANG module [RFC6991]. 1846 This parameter is only allowed for GET methods on a text/event-stream 1847 data resource. A 400 Bad Request error is returned if used for other 1848 methods or resource types. 1850 If this parameter is not present, then a replay subscription is not 1851 being requested. It is not valid to specify start times that are 1852 later than the current time. If the value specified is earlier than 1853 the log can support, the replay will begin with the earliest 1854 available notification. 1856 If this query parameter is supported by the server, then the "replay" 1857 query parameter URI MUST be listed in the "capability" leaf-list in 1858 Section 9.3. The "stop-time" query parameter MUST also be supported 1859 by the server. 1861 If the "replay-support" leaf is present in the "stream" entry 1862 (defined in Section 9.3) then the server MUST support the 1863 "start-time" and "stop-time" query parameters for that stream. 1865 4.8.10. The "stop-time" Query Parameter 1867 The "stop-time" parameter is used with the replay feature to indicate 1868 the newest notifications of interest. This parameter MUST be used 1869 with and have a value later than the "start-time" parameter. 1871 The value of the "stop-time" parameter is of type "date-and-time", 1872 defined in the "ietf-yang" YANG module [RFC6991]. 1874 This parameter is only allowed for GET methods on a text/event-stream 1875 data resource. A 400 Bad Request error is returned if used for other 1876 methods or resource types. 1878 If this parameter is not present, the notifications will continue 1879 until the subscription is terminated. Values in the future are 1880 valid. 1882 If this query parameter is supported by the server, then the "replay" 1883 query parameter URI MUST be listed in the "capability" leaf-list in 1884 Section 9.3. The "start-time" query parameter MUST also be supported 1885 by the server. 1887 If the "replay-support" leaf is present in the "stream" entry 1888 (defined in Section 9.3) then the server MUST support the 1889 "start-time" and "stop-time" query parameters for that stream. 1891 4.8.11. The "with-defaults" Query Parameter 1893 The "with-defaults" parameter is used to specify how information 1894 about default data nodes should be returned in response to GET 1895 requests on data resources. 1897 If the server supports this capability, then it MUST implement the 1898 behavior in section 4.5.1 of [RFC6243], except applied to the 1899 RESTCONF GET operation, instead of the NETCONF operations. 1901 +-------------------+-----------------------------------------------+ 1902 | Value | Description | 1903 +-------------------+-----------------------------------------------+ 1904 | report-all | All data nodes are reported | 1905 | trim | Data nodes set to the YANG default are not | 1906 | | reported | 1907 | explicit | Data nodes set by the client are not reported | 1908 | report-all-tagged | All data nodes are reported and defaults are | 1909 | | tagged | 1910 +-------------------+-----------------------------------------------+ 1912 If the "with-defaults" parameter is set to "report-all" then the 1913 server MUST adhere to the defaults reporting behavior defined in 1914 section 3.1 of [RFC6243]. 1916 If the "with-defaults" parameter is set to "trim" then the server 1917 MUST adhere to the defaults reporting behavior defined in section 3.2 1918 of [RFC6243]. 1920 If the "with-defaults" parameter is set to "explicit" then the server 1921 MUST adhere to the defaults reporting behavior defined in section 3.3 1922 of [RFC6243]. 1924 If the "with-defaults" parameter is set to "report-all-tagged" then 1925 the server MUST adhere to the defaults reporting behavior defined in 1926 section 3.4 of [RFC6243]. 1928 If the "with-defaults" parameter is not present then the server MUST 1929 adhere to the defaults reporting behavior defined in its "basic-mode" 1930 parameter for the "defaults" protocol capability URI, defined in 1931 Section 4.8.2. 1933 If the server includes the "with-defaults" query parameter URI in the 1934 "capability" leaf-list in Section 9.3, then the "with-defaults" query 1935 parameter MUST be supported. 1937 5. Messages 1939 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 1940 message corresponds to a single protocol method. Most messages can 1941 perform a single task on a single resource, such as retrieving a 1942 resource or editing a resource. The exception is the PATCH method, 1943 which allows multiple datastore edits within a single message. 1945 5.1. Request URI Structure 1947 Resources are represented with URIs following the structure for 1948 generic URIs in [RFC3986]. 1950 A RESTCONF operation is derived from the HTTP method and the request 1951 URI, using the following conceptual fields: 1953 //?# 1955 ^ ^ ^ ^ ^ 1956 | | | | | 1957 method entry resource query fragment 1959 M M O O I 1961 M=mandatory, O=optional, I=ignored 1963 replaced by client with real values 1965 o method: the HTTP method identifying the RESTCONF operation 1966 requested by the client, to act upon the target resource specified 1967 in the request URI. RESTCONF operation details are described in 1968 Section 4. 1970 o entry: the root of the RESTCONF API configured on this HTTP 1971 server, discovered by getting the ".well-known/host-meta" 1972 resource, as described in Section 3.1. 1974 o resource: the path expression identifying the resource that is 1975 being accessed by the operation. If this field is not present, 1976 then the target resource is the API itself, represented by the 1977 media type "application/yang.api". 1979 o query: the set of parameters associated with the RESTCONF message. 1980 These have the familiar form of "name=value" pairs. All query 1981 parameters are optional to implement by the server and optional to 1982 use by the client. Each query parameter is identified by a URI. 1983 The server MUST list the query parameter URIs it supports in the 1984 "capabilities" list defined in Section 9.3. 1986 There is a specific set of parameters defined, although the server 1987 MAY choose to support query parameters not defined in this document. 1988 The contents of the any query parameter value MUST be encoded 1989 according to [RFC2396], section 3.4. Any reserved characters MUST be 1990 encoded with escape sequences, according to [RFC2396], section 2.4. 1992 o fragment: This field is not used by the RESTCONF protocol. 1994 When new resources are created by the client, a "Location" header is 1995 returned, which identifies the path of the newly created resource. 1996 The client MUST use this exact path identifier to access the resource 1997 once it has been created. 1999 The "target" of an operation is a resource. The "path" field in the 2000 request URI represents the target resource for the operation. 2002 5.2. Message Headers 2004 There are several HTTP header lines utilized in RESTCONF messages. 2005 Messages are not limited to the HTTP headers listed in this section. 2007 HTTP defines which header lines are required for particular 2008 circumstances. Refer to each operation definition section in 2009 Section 4 for examples on how particular headers are used. 2011 There are some request headers that are used within RESTCONF, usually 2012 applied to data resources. The following tables summarize the 2013 headers most relevant in RESTCONF message requests: 2015 +---------------------+---------------------------------------------+ 2016 | Name | Description | 2017 +---------------------+---------------------------------------------+ 2018 | Accept | Response Content-Types that are acceptable | 2019 | Content-Type | The media type of the request body | 2020 | Host | The host address of the server | 2021 | If-Match | Only perform the action if the entity | 2022 | | matches ETag | 2023 | If-Modified-Since | Only perform the action if modified since | 2024 | | time | 2025 | If-Unmodified-Since | Only perform the action if un-modified | 2026 | | since time | 2027 +---------------------+---------------------------------------------+ 2029 RESTCONF Request Headers 2031 The following tables summarize the headers most relevant in RESTCONF 2032 message responses: 2034 +---------------+---------------------------------------------------+ 2035 | Name | Description | 2036 +---------------+---------------------------------------------------+ 2037 | Allow | Valid actions when 405 error returned | 2038 | Cache-Control | The cache control parameters for the response | 2039 | Content-Type | The media type of the response message-body | 2040 | Date | The date and time the message was sent | 2041 | ETag | An identifier for a specific version of a | 2042 | | resource | 2043 | Last-Modified | The last modified date and time of a resource | 2044 | Location | The resource identifier for a newly created | 2045 | | resource | 2046 +---------------+---------------------------------------------------+ 2048 RESTCONF Response Headers 2050 5.3. Message Encoding 2052 RESTCONF messages are encoded in HTTP according to [RFC7230]. The 2053 "utf-8" character set is used for all messages. RESTCONF message 2054 content is sent in the HTTP message-body. 2056 Content is encoded in either JSON or XML format. A server MUST 2057 support XML encoding and MAY support JSON encoding. XML encoding 2058 rules for data nodes are defined in [RFC6020]. The same encoding 2059 rules are used for all XML content. JSON encoding rules are defined 2060 in [I-D.ietf-netmod-yang-json]. This encoding is valid JSON, but 2061 also has special encoding rules to identify module namespaces and 2062 provide consistent type processing of YANG data. 2064 Request input content encoding format is identified with the Content- 2065 Type header. This field MUST be present if a message-body is sent by 2066 the client. 2068 Response output content encoding format is identified with the Accept 2069 header in the request, or if is not specified, the request input 2070 encoding format is used. If there was no request input, then the 2071 default output encoding is XML. File extensions encoded in the 2072 request are not used to identify format encoding. 2074 5.4. RESTCONF Meta-Data 2076 The RESTCONF protocol needs to retrieve the same meta-data that is 2077 used in the NETCONF protocol. Information about default leafs, last- 2078 modified timestamps, etc. are commonly used to annotate 2079 representations of the datastore contents. This meta-data is not 2080 defined in the YANG schema because it applies to the datastore, and 2081 is common across all data nodes. 2083 This information is encoded as attributes in XML. JSON encoding of 2084 meta-data is defined in [I-D.lhotka-netmod-yang-metadata]. 2086 5.5. Return Status 2088 Each message represents some sort of resource access. An HTTP 2089 "status-line" header line is returned for each request. If a 4xx or 2090 5xx range status code is returned in the status-line, then the error 2091 information will be returned in the response, according to the format 2092 defined in Section 7.1. 2094 5.6. Message Caching 2096 Since the datastore contents change at unpredictable times, responses 2097 from a RESTCONF server generally SHOULD NOT be cached. 2099 The server SHOULD include a "Cache-Control" header in every response 2100 that specifies whether the response should be cached. A "Pragma" 2101 header specifying "no-cache" MAY also be sent in case the 2102 "Cache-Control" header is not supported. 2104 Instead of using HTTP caching, the client SHOULD track the "ETag" 2105 and/or "Last-Modified" headers returned by the server for the 2106 datastore resource (or data resource if the server supports it). A 2107 retrieval request for a resource can include the "If-None-Match" and/ 2108 or "If-Modified-Since" headers, which will cause the server to return 2109 a "304 Not Modified" status-line if the resource has not changed. 2110 The client MAY use the HEAD method to retrieve just the message 2111 headers, which SHOULD include the "ETag" and "Last-Modified" headers, 2112 if this meta-data is maintained for the target resource. 2114 6. Notifications 2116 The RESTCONF protocol supports YANG-defined event notifications. The 2117 solution preserves aspects of NETCONF Event Notifications [RFC5277] 2118 while utilizing the Server-Sent Events [W3C.CR-eventsource-20121211] 2119 transport strategy. 2121 6.1. Server Support 2123 A RESTCONF server is not required to support RESTCONF notifications. 2124 Clients may determine if a server supports RESTCONF notifications by 2125 using the HTTP operation OPTIONS, HEAD, or GET on the stream list. 2126 The server does not support RESTCONF notifications if an HTTP error 2127 code is returned (e.g., 404 Not Found). 2129 6.2. Event Streams 2131 A RESTCONF server that supports notifications will populate a stream 2132 resource for each notification delivery service access point. A 2133 RESTCONF client can retrieve the list of supported event streams from 2134 a RESTCONF server using the GET operation on the stream list. 2136 The "restconf-state/streams" container definition in the 2137 "ietf-restconf-monitoring" module (defined in Section 9.3) is used to 2138 specify the structure and syntax of the conceptual child resources 2139 within the "streams" resource. 2141 For example: 2143 The client might send the following request: 2145 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2146 streams HTTP/1.1 2147 Host: example.com 2148 Accept: application/yang.data+xml 2150 The server might send the following response: 2152 HTTP/1.1 200 OK 2153 Content-Type: application/yang.api+xml 2154 2156 2157 NETCONF 2158 default NETCONF event stream 2159 2160 true 2161 2162 2007-07-08T00:00:00Z 2163 2164 2165 xml 2166 https://example.com/streams/NETCONF 2167 2168 2169 json 2170 https://example.com/streams/NETCONF-JSON 2171 2172 2173 2174 SNMP 2175 SNMP notifications 2176 false 2177 2178 xml 2179 https://example.com/streams/SNMP 2180 2181 2182 2183 syslog-critical 2184 Critical and higher severity 2185 2186 true 2187 2188 2007-07-01T00:00:00Z 2189 2190 2191 xml 2192 2193 https://example.com/streams/syslog-critical 2194 2195 2196 2197 2199 6.3. Subscribing to Receive Notifications 2201 RESTCONF clients can determine the URL for the subscription resource 2202 (to receive notifications) by sending an HTTP GET request for the 2203 "events" leaf with the stream list entry. The value returned by the 2204 server can be used for the actual notification subscription. 2206 The client will send an HTTP GET request for the URL returned by the 2207 server with the "Accept" type "text/event-stream". 2209 The server will treat the connection as an event stream, using the 2210 Server Sent Events [W3C.CR-eventsource-20121211] transport strategy. 2212 The server MAY support query parameters for a GET method on this 2213 resource. These parameters are specific to each notification stream. 2215 For example: 2217 The client might send the following request: 2219 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2220 streams/stream=NETCONF/encoding=xml/events HTTP/1.1 2221 Host: example.com 2222 Accept: application/yang.data+xml 2224 The server might send the following response: 2226 HTTP/1.1 200 OK 2227 Content-Type: application/yang.api+xml 2229 2231 https://example.com/streams/NETCONF 2232 2234 The RESTCONF client can then use this URL value to start monitoring 2235 the event stream: 2237 GET /streams/NETCONF HTTP/1.1 2238 Host: example.com 2239 Accept: text/event-stream 2240 Cache-Control: no-cache 2241 Connection: keep-alive 2243 A RESTCONF client MAY request the server compress the events using 2244 the HTTP header field "Accept-Encoding". For instance: 2246 GET /streams/NETCONF HTTP/1.1 2247 Host: example.com 2248 Accept: text/event-stream 2249 Cache-Control: no-cache 2250 Connection: keep-alive 2251 Accept-Encoding: gzip, deflate 2253 6.3.1. NETCONF Event Stream 2255 The server SHOULD support the "NETCONF" notification stream defined 2256 in [RFC5277]. For this stream, RESTCONF notification subscription 2257 requests MAY specify parameters indicating the events it wishes to 2258 receive. These query parameters are optional to implement, and only 2259 available if the server supports them. 2261 +------------+---------+-------------------------+ 2262 | Name | Section | Description | 2263 +------------+---------+-------------------------+ 2264 | start-time | 4.8.9 | replay event start time | 2265 | stop-time | 4.8.10 | replay event stop time | 2266 | filter | 4.8.8 | boolean content filter | 2267 +------------+---------+-------------------------+ 2269 NETCONF Stream Query Parameters 2271 The semantics and syntax for these query parameters are defined in 2272 the sections listed above. The YANG encoding MUST be converted to 2273 URL-encoded string for use in the request URI. 2275 Refer to Appendix D.3.6 for filter parameter examples. 2277 6.4. Receiving Event Notifications 2279 RESTCONF notifications are encoded according to the definition of the 2280 event stream. The NETCONF stream defined in [RFC5277] is encoded in 2281 XML format. 2283 The structure of the event data is based on the "notification" 2284 element definition in section 4 of [RFC5277]. It MUST conform to the 2285 schema for the "notification" element in section 4 of [RFC5277], 2286 except the XML namespace for this element is defined as: 2288 urn:ietf:params:xml:ns:yang:ietf-restconf 2290 For JSON encoding purposes, the module name is "ietf-restconf". 2292 An example SSE notification encoded using XML: 2294 data: 2296 data: 2013-12-21T00:01:00Z 2297 data: 2298 data: fault 2299 data: 2300 data: Ethernet0 2301 data: 2302 data: major 2303 data: 2304 data: 2306 An example SSE notification encoded using JSON: 2308 data: { 2309 data: "ietf-restconf:notification": { 2310 data: "event-time": "2013-12-21T00:01:00Z", 2311 data: "example-mod:event": { 2312 data: "event-class": "fault", 2313 data: "reporting-entity": { "card": "Ethernet0" }, 2314 data: "severity": "major" 2315 data: } 2316 data: } 2317 data: } 2319 Alternatively, since neither XML nor JSON are whitespace sensitive, 2320 the above messages can be encoded onto a single line. For example: 2322 For example: ('\' line wrapping added for formatting only) 2324 XML: 2326 data: 2013-12-21T00:01:00ZfaultEthernet0\ 2330 major 2332 JSON: 2334 data: {"ietf-restconf:notification":{"event-time":"2013-12-21\ 2335 T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ 2336 tingEntity":{"card":"Ethernet0"},"severity":"major"}}} 2338 The SSE specifications supports the following additional fields: 2339 event, id and retry. A RESTCONF server MAY send the "retry" field 2340 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 2341 SHOULD NOT send the "event" or "id" fields, as there are no 2342 meaningful values that could be used for them that would not be 2343 redundant to the contents of the notification itself. RESTCONF 2344 servers that do not send the "id" field also do not need to support 2345 the HTTP header "Last-Event-Id". RESTCONF servers that do send the 2346 "id" field MUST still support the "startTime" query parameter as the 2347 preferred means for a client to specify where to restart the event 2348 stream. 2350 7. Error Reporting 2352 HTTP status-lines are used to report success or failure for RESTCONF 2353 operations. The element returned in NETCONF error 2354 responses contains some useful information. This error information 2355 is adapted for use in RESTCONF, and error information is returned for 2356 "4xx" class of status codes. 2358 The following table summarizes the return status codes used 2359 specifically by RESTCONF operations: 2361 +---------------------------+---------------------------------------+ 2362 | Status-Line | Description | 2363 +---------------------------+---------------------------------------+ 2364 | 100 Continue | POST accepted, 201 should follow | 2365 | 200 OK | Success with response message-body | 2366 | 201 Created | POST to create a resource success | 2367 | 202 Accepted | POST to create a resource accepted | 2368 | 204 No Content | Success without response message-body | 2369 | 304 Not Modified | Conditional operation not done | 2370 | 400 Bad Request | Invalid request message | 2371 | 403 Forbidden | Access to resource denied | 2372 | 404 Not Found | Resource target or resource node not | 2373 | | found | 2374 | 405 Method Not Allowed | Method not allowed for target | 2375 | | resource | 2376 | 409 Conflict | Resource or lock in use | 2377 | 412 Precondition Failed | Conditional method is false | 2378 | 413 Request Entity Too | too-big error | 2379 | Large | | 2380 | 414 Request-URI Too Large | too-big error | 2381 | 415 Unsupported Media | non RESTCONF media type | 2382 | Type | | 2383 | 500 Internal Server Error | operation-failed | 2384 | 501 Not Implemented | unknown-operation | 2385 | 503 Service Unavailable | Recoverable server error | 2386 +---------------------------+---------------------------------------+ 2388 HTTP Status Codes used in RESTCONF 2390 Since an operation resource is defined with a YANG "rpc" statement, a 2391 mapping between the NETCONF value and the HTTP status 2392 code is needed. The specific error condition and response code to 2393 use are data-model specific and might be contained in the YANG 2394 "description" statement for the "rpc" statement. 2396 +-------------------------+-------------+ 2397 | | status code | 2398 +-------------------------+-------------+ 2399 | in-use | 409 | 2400 | invalid-value | 400 | 2401 | too-big | 413 | 2402 | missing-attribute | 400 | 2403 | bad-attribute | 400 | 2404 | unknown-attribute | 400 | 2405 | bad-element | 400 | 2406 | unknown-element | 400 | 2407 | unknown-namespace | 400 | 2408 | access-denied | 403 | 2409 | lock-denied | 409 | 2410 | resource-denied | 409 | 2411 | rollback-failed | 500 | 2412 | data-exists | 409 | 2413 | data-missing | 409 | 2414 | operation-not-supported | 501 | 2415 | operation-failed | 500 | 2416 | partial-operation | 500 | 2417 | malformed-message | 400 | 2418 +-------------------------+-------------+ 2420 Mapping from error-tag to status code 2422 7.1. Error Response Message 2424 When an error occurs for a request message on a data resource or an 2425 operation resource, and a "4xx" class of status codes (except for 2426 status code "403 Forbidden"), then the server SHOULD send a response 2427 message-body containing the information described by the "errors" 2428 container definition within the YANG module Section 8. The Content- 2429 Type of this response message MUST be application/yang.errors (see 2430 example below). 2432 The client MAY specify the desired encoding for error messages by 2433 specifying the appropriate media-type in the Accept header. If no 2434 error media is specified, the server MUST assume that "application/ 2435 yang.errors+xml" was specified. All of the examples in this 2436 document, except for the one below, assume the default XML encoding 2437 will be returned if there is an error. 2439 YANG Tree Diagram for Data: 2441 +--ro errors 2442 +--ro error 2443 +--ro error-type enumeration 2444 +--ro error-tag string 2445 +--ro error-app-tag? string 2446 +--ro (error-node)? 2447 | +--:(error-path) 2448 | | +--ro error-path? instance-identifier 2449 | +--:(error-urlpath) 2450 | +--ro error-urlpath? data-resource-identifier 2451 +--ro error-message? string 2452 +--ro error-info 2454 The semantics and syntax for RESTCONF error messages are defined in 2455 the "application/yang.errors" restconf-media-type extension in 2456 Section 8. 2458 Examples: 2460 The following example shows an error returned for an "lock-denied" 2461 error that can occur if a NETCONF client has locked a datastore. The 2462 RESTCONF client is attempting to delete a data resource. Note that 2463 an Accept header is used to specify the desired encoding for the 2464 error message. This example's use of the Accept header is especially 2465 notable since the DELETE method typically doesn't return a message- 2466 body and hence Accept headers are typically not passed. 2468 DELETE /restconf/data/example-jukebox:jukebox/ 2469 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2470 Host: example.com 2471 Accept: application/yang.errors+json 2473 The server might respond: 2475 HTTP/1.1 409 Conflict 2476 Date: Mon, 23 Apr 2012 17:11:00 GMT 2477 Server: example-server 2478 Content-Type: application/yang.errors+json 2480 { 2481 "ietf-restconf:errors": { 2482 "error": { 2483 "error-type": "protocol", 2484 "error-tag": "lock-denied", 2485 "error-message": "Lock failed, lock already held" 2486 } 2487 } 2488 } 2490 The following example shows an error returned for a "data-exists" 2491 error on a data resource. The "jukebox" resource already exists so 2492 it cannot be created. 2494 The client might send: 2496 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 2497 Host: example.com 2499 The server might respond: 2501 HTTP/1.1 409 Conflict 2502 Date: Mon, 23 Apr 2012 17:11:00 GMT 2503 Server: example-server 2504 Content-Type: application/yang.errors+json 2506 { 2507 "ietf-restconf:errors": { 2508 "error": { 2509 "error-type": "protocol", 2510 "error-tag": "data-exists", 2511 "error-urlpath": "https://example.com/restconf/data/ 2512 example-jukebox:jukebox", 2513 "error-message": 2514 "Data already exists, cannot create new resource" 2515 } 2516 } 2517 } 2519 8. RESTCONF module 2521 The "ietf-restconf" module defines conceptual definitions within an 2522 extension and two groupings, which are not meant to be implemented as 2523 datastore contents by a server. E.g., the "restconf" container is 2524 not intended to be implemented as a top-level data node (under the 2525 "/restconf/data" entry point). 2527 RFC Ed.: update the date below with the date of RFC publication and 2528 remove this note. 2530 file "ietf-restconf@2015-01-30.yang" 2532 module ietf-restconf { 2533 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 2534 prefix "rc"; 2536 organization 2537 "IETF NETCONF (Network Configuration) Working Group"; 2539 contact 2540 "WG Web: 2541 WG List: 2543 WG Chair: Mehmet Ersue 2544 2546 WG Chair: Mahesh Jethanandani 2547 2549 Editor: Andy Bierman 2550 2552 Editor: Martin Bjorklund 2553 2555 Editor: Kent Watsen 2556 "; 2558 description 2559 "This module contains conceptual YANG specifications 2560 for basic RESTCONF media type definitions used in 2561 RESTCONF protocol messages. 2563 Note that the YANG definitions within this module do not 2564 represent configuration data of any kind. 2565 The 'restconf-media-type' YANG extension statement 2566 provides a normative syntax for XML and JSON message 2567 encoding purposes. 2569 Copyright (c) 2015 IETF Trust and the persons identified as 2570 authors of the code. All rights reserved. 2572 Redistribution and use in source and binary forms, with or 2573 without modification, is permitted pursuant to, and subject 2574 to the license terms contained in, the Simplified BSD License 2575 set forth in Section 4.c of the IETF Trust's Legal Provisions 2576 Relating to IETF Documents 2577 (http://trustee.ietf.org/license-info). 2579 This version of this YANG module is part of RFC XXXX; see 2580 the RFC itself for full legal notices."; 2582 // RFC Ed.: replace XXXX with actual RFC number and remove this 2583 // note. 2585 // RFC Ed.: remove this note 2586 // Note: extracted from draft-ietf-netconf-restconf-04.txt 2588 // RFC Ed.: update the date below with the date of RFC publication 2589 // and remove this note. 2590 revision 2015-01-30 { 2591 description 2592 "Initial revision."; 2593 reference 2594 "RFC XXXX: RESTCONF Protocol."; 2595 } 2597 extension restconf-media-type { 2598 argument media-type-id { 2599 yin-element true; 2600 } 2601 description 2602 "This extension is used to specify a YANG data structure which 2603 represents a conceptual RESTCONF media type template. 2604 Data definition statements within this extension specify 2605 the 'generic syntax' for the specific media type. 2607 YANG is mapped to specific encoding formats outside the 2608 scope of this extension statement. RFC 6020 defines XML 2609 encoding rules for all RESTCONF media types that use 2610 the '+xml' suffix. draft-ietf-netmod-yang-json defines 2611 JSON encoding rules for all RESTCONF media types that 2612 use the '+json' suffix. 2614 The 'media-type-id' parameter value identifies the media type 2615 that is being defined. It contains the string associated 2616 with the generic media type, i.e., no suffix is specified. 2618 This extension is ignored unless it appears as a top-level 2619 statement. It SHOULD contain data definition statements 2620 that result in exactly one container data node definition. 2621 This allows compliant translation to an XML instance 2622 document for each media type. 2624 The module name and namespace value for the YANG module using 2625 the extension statement is assigned to instance document data 2626 conforming to the data definition statements within 2627 this extension. 2629 The sub-statements of this extension MUST follow the 2630 'data-def-stmt' rule in the YANG ABNF. 2632 The XPath document root is the extension statement itself, 2633 such that the child nodes of the document root are 2634 represented by the data-def-stmt sub-statements within 2635 this extension. This conceptual document is the context 2636 for the following YANG statements: 2638 - must-stmt 2639 - when-stmt 2640 - path-stmt 2641 - min-elements-stmt 2642 - max-elements-stmt 2643 - mandatory-stmt 2644 - unique-stmt 2645 - ordered-by 2646 - instance-identifier data type 2648 The following data-def-stmt sub-statements have special 2649 meaning when used within a restconf-resource extension 2650 statement. 2652 - The list-stmt is not required to have a key-stmt defined. 2653 - The if-feature-stmt is ignored if present. 2654 - The config-stmt is ignored if present. 2655 - The available identity values for any 'identityref' 2656 leaf or leaf-list nodes is limited to the module 2657 containing this extension statement, and the modules 2658 imported into that module. 2659 "; 2660 } 2661 rc:restconf-media-type "application/yang.errors" { 2662 uses errors; 2663 } 2665 rc:restconf-media-type "application/yang.api" { 2666 uses restconf; 2667 } 2669 typedef data-resource-identifier { 2670 type string { 2671 length "1 .. max"; 2672 } 2673 description 2674 "Contains a Data Resource Identifier formatted string 2675 to identify a specific data resource instance. 2676 The document root for all data resources is a 2677 datastore resource container. Each top-level YANG 2678 data nodes supported by the server will be represented 2679 as a child node of the document root. 2681 The canonical representation of a data resource identifier 2682 includes the full server specification that is returned 2683 in the Location header when a new data resource is created 2684 with the POST method. 2686 The abbreviated representation does not contain any server 2687 location identification. Instead the identifier will start 2688 with the '/' character to represent the datastore document 2689 root for the data resource instance. 2691 The server MUST accept either representation and SHOULD 2692 return the canonical representation in any response message."; 2693 reference 2694 "RFC XXXX: [sec. 5.3.1.1 ABNF For Data Resource Identifiers]"; 2695 } 2697 grouping errors { 2698 description 2699 "A grouping that contains a YANG container 2700 representing the syntax and semantics of a 2701 YANG Patch errors report within a response message."; 2703 container errors { 2704 description 2705 "Represents an error report returned by the server if 2706 a request results in an error."; 2708 list error { 2709 description 2710 "An entry containing information about one 2711 specific error that occurred while processing 2712 a RESTCONF request."; 2713 reference "RFC 6241, Section 4.3"; 2715 leaf error-type { 2716 type enumeration { 2717 enum transport { 2718 description "The transport layer"; 2719 } 2720 enum rpc { 2721 description "The rpc or notification layer"; 2722 } 2723 enum protocol { 2724 description "The protocol operation layer"; 2725 } 2726 enum application { 2727 description "The server application layer"; 2728 } 2729 } 2730 mandatory true; 2731 description 2732 "The protocol layer where the error occurred."; 2733 } 2735 leaf error-tag { 2736 type string; 2737 mandatory true; 2738 description 2739 "The enumerated error tag."; 2740 } 2742 leaf error-app-tag { 2743 type string; 2744 description 2745 "The application-specific error tag."; 2746 } 2748 choice error-node { 2749 description 2750 "The server will return the location of the error node 2751 in a format that is appropriate for the protocol. 2752 If no specific node within the request message body 2753 caused the error then this choice will not be present."; 2755 leaf error-path { 2756 type instance-identifier; 2757 description 2758 "The YANG instance identifier associated 2759 with the error node. This leaf will only be 2760 present if the error node is not a data resource, 2761 e.g., the error node is an input parameter 2762 for an operation resource."; 2763 } 2764 leaf error-urlpath { 2765 type data-resource-identifier; 2766 description 2767 "The target data resource identifier associated 2768 with the error node. This leaf will only be 2769 present if the error node is associated with 2770 a data resource (either within the server or 2771 in the request message)."; 2772 } 2773 } 2775 leaf error-message { 2776 type string; 2777 description 2778 "A message describing the error."; 2779 } 2781 anyxml error-info { 2782 description 2783 "Arbitrary XML that represents a container 2784 of additional information for the error report."; 2785 } 2786 } 2787 } 2788 } // grouping errors 2790 grouping restconf { 2791 description 2792 "Conceptual container representing the 2793 application/yang.api resource type."; 2795 container restconf { 2796 description 2797 "Conceptual container representing the 2798 application/yang.api resource type."; 2800 container data { 2801 description 2802 "Container representing the application/yang.datastore 2803 resource type. Represents the conceptual root of all 2804 operational data and configuration data supported by 2805 the server. The child nodes of this container can be 2806 any data resource (application/yang.data), which are 2807 defined as top-level data nodes from the YANG modules 2808 advertised by the server in the ietf-restconf-monitoring 2809 module."; 2810 } 2812 container operations { 2813 description 2814 "Container for all operation resources 2815 (application/yang.operation), 2817 Each resource is represented as an empty leaf with the 2818 name of the RPC operation from the YANG rpc statement. 2820 E.g.; 2822 POST /restconf/operations/show-log-errors 2824 leaf show-log-errors { 2825 type empty; 2826 } 2827 "; 2828 } 2829 } // container restconf 2830 } // grouping restconf 2832 } 2834 2836 9. RESTCONF Monitoring 2838 The "ietf-restconf-monitoring" module provides information about the 2839 RESTCONF protocol capabilities and notification event streams 2840 available from the server. Implementation is mandatory for RESTCONF 2841 servers, if any protocol capabilities or notification event streams 2842 are supported. 2844 YANG Tree Diagram for "ietf-restconf-monitoring" module: 2846 +--ro restconf-state 2847 +--ro capabilities 2848 | +--ro capability* inet:uri 2849 +--ro streams 2850 +--ro stream* [name] 2851 +--ro name string 2852 +--ro description? string 2853 +--ro replay-support? boolean 2854 +--ro replay-log-creation-time? yang:date-and-time 2855 +--ro encoding* [type] 2856 +--ro type string 2857 +--ro events inet:uri 2859 9.1. restconf-state/capabilities 2861 This mandatory container holds the RESTCONF protocol capability URIs 2862 supported by the server. 2864 The server MUST maintain a last-modified timestamp for this 2865 container, and return the "Last-Modified" header when this data node 2866 is retrieved with the GET or HEAD methods. 2868 The server SHOULD maintain an entity-tag for this container, and 2869 return the "ETag" header when this data node is retrieved with the 2870 GET or HEAD methods. 2872 9.2. restconf-state/streams 2874 This optional container provides access to the notification event 2875 streams supported by the server. The server MAY omit this container 2876 if no notification event streams are supported. 2878 The server will populate this container with a stream list entry for 2879 each stream type it supports. Each stream contains a leaf called 2880 "events" which contains a URI that represents an event stream 2881 resource. 2883 Stream resources are defined in Section 3.8. Notifications are 2884 defined in Section 6. 2886 9.3. RESTCONF Monitoring Module 2888 The "ietf-restconf-monitoring" module defines monitoring information 2889 for the RESTCONF protocol. 2891 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 2892 are used by this module for some type definitions. 2894 RFC Ed.: update the date below with the date of RFC publication and 2895 remove this note. 2897 file "ietf-restconf-monitoring@2015-01-30.yang" 2899 module ietf-restconf-monitoring { 2900 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; 2901 prefix "rcmon"; 2903 import ietf-yang-types { prefix yang; } 2904 import ietf-inet-types { prefix inet; } 2906 organization 2907 "IETF NETCONF (Network Configuration) Working Group"; 2909 contact 2910 "WG Web: 2911 WG List: 2913 WG Chair: Mehmet Ersue 2914 2916 WG Chair: Mahesh Jethanandani 2917 2919 Editor: Andy Bierman 2920 2922 Editor: Martin Bjorklund 2923 2925 Editor: Kent Watsen 2926 "; 2928 description 2929 "This module contains monitoring information for the 2930 RESTCONF protocol. 2932 Copyright (c) 2015 IETF Trust and the persons identified as 2933 authors of the code. All rights reserved. 2935 Redistribution and use in source and binary forms, with or 2936 without modification, is permitted pursuant to, and subject 2937 to the license terms contained in, the Simplified BSD License 2938 set forth in Section 4.c of the IETF Trust's Legal Provisions 2939 Relating to IETF Documents 2940 (http://trustee.ietf.org/license-info). 2941 This version of this YANG module is part of RFC XXXX; see 2942 the RFC itself for full legal notices."; 2944 // RFC Ed.: replace XXXX with actual RFC number and remove this 2945 // note. 2947 // RFC Ed.: remove this note 2948 // Note: extracted from draft-ietf-netconf-restconf-04.txt 2950 // RFC Ed.: update the date below with the date of RFC publication 2951 // and remove this note. 2952 revision 2015-01-30 { 2953 description 2954 "Initial revision."; 2955 reference 2956 "RFC XXXX: RESTCONF Protocol."; 2957 } 2959 container restconf-state { 2960 config false; 2961 description 2962 "Contains RESTCONF protocol monitoring information."; 2964 container capabilities { 2965 description 2966 "Contains a list of protocol capability URIs"; 2968 leaf-list capability { 2969 type inet:uri; 2970 description "A RESTCONF protocol capability URI."; 2971 } 2972 } 2974 container streams { 2975 description 2976 "Container representing the notification event streams 2977 supported by the server."; 2978 reference 2979 "RFC 5277, Section 3.4, element."; 2981 list stream { 2982 key name; 2983 description 2984 "Each entry describes an event stream supported by 2985 the server."; 2987 leaf name { 2988 type string; 2989 description "The stream name"; 2990 reference "RFC 5277, Section 3.4, element."; 2991 } 2993 leaf description { 2994 type string; 2995 description "Description of stream content"; 2996 reference 2997 "RFC 5277, Section 3.4, element."; 2998 } 3000 leaf replay-support { 3001 type boolean; 3002 description 3003 "Indicates if replay buffer supported for this stream. 3004 If 'true', then the server MUST support the 'start-time' 3005 and 'stop-time' query parameters for this stream."; 3006 reference 3007 "RFC 5277, Section 3.4, element."; 3008 } 3010 leaf replay-log-creation-time { 3011 when "../replay-support" { 3012 description 3013 "Only present if notification replay is supported"; 3014 } 3015 type yang:date-and-time; 3016 description 3017 "Indicates the time the replay log for this stream 3018 was created."; 3019 reference 3020 "RFC 5277, Section 3.4, 3021 element."; 3022 } 3024 list encoding { 3025 key type; 3026 min-elements 1; 3027 description 3028 "The server will create an entry in this list for each 3029 encoding format that is supported for this stream. 3030 The media type 'application/yang.stream' is expected 3031 for all event streams. This list identifies the 3032 sub-types supported for this stream."; 3034 leaf type { 3035 type string; 3036 description 3037 "This is the secondary encoding format within the 3038 'text/event-stream' encoding used by all streams. 3039 The type 'xml' is supported for the media type 3040 'application/yang.stream+xml'. The type 'json' 3041 is supported for the media type 3042 'application/yang.stream+json'."; 3044 } 3046 leaf events { 3047 type inet:uri; 3048 mandatory true; 3049 description 3050 "Contains a URL that represents the entry point 3051 for establishing notification delivery via server 3052 sent events."; 3053 } 3054 } 3055 } 3056 } 3057 } 3059 } 3061 3063 10. YANG Module Library 3065 The "ietf-yang-library" module defined in 3066 [I-D.ietf-netconf-yang-library] provides information about the YANG 3067 modules and submodules used by the RESTCONF server. Implementation 3068 is mandatory for RESTCONF servers. All YANG modules and submodules 3069 used by the server MUST be identified in the YANG module library. 3071 10.1. modules 3073 This mandatory container holds the identifiers for the YANG data 3074 model modules supported by the server. 3076 The server MUST maintain a last-modified timestamp for this 3077 container, and return the "Last-Modified" header when this data node 3078 is retrieved with the GET or HEAD methods. 3080 The server SHOULD maintain an entity-tag for this container, and 3081 return the "ETag" header when this data node is retrieved with the 3082 GET or HEAD methods. 3084 10.1.1. modules/module 3086 This mandatory list contains one entry for each YANG data model 3087 module supported by the server. There MUST be an instance of this 3088 list for every YANG module that is used by the server. 3090 The contents of this list are defined in the "module" YANG list 3091 statement in [I-D.ietf-netconf-yang-library]. 3093 The server MAY maintain a last-modified timestamp for each instance 3094 of this list entry, and return the "Last-Modified" header when this 3095 data node is retrieved with the GET or HEAD methods. If not 3096 supported then the timestamp for the parent "modules" container MAY 3097 be used instead. 3099 The server MAY maintain an entity-tag for each instance of this list 3100 entry, and return the "ETag" header when this data node is retrieved 3101 with the GET or HEAD methods. If not supported then the timestamp 3102 for the parent "modules" container MAY be used instead. 3104 11. IANA Considerations 3106 11.1. The "restconf" Relation Type 3108 This specification registers the "restconf" relation type in the Link 3109 Relation Type Registry defined by [RFC5988]: 3111 Relation Name: restconf 3113 Description: Identifies the root of RESTCONF API as configured 3114 on this HTTP server. The "restconf" relation 3115 defines the root of the API defined in RFCXXXX. 3116 Subsequent revisions of RESTCONF will use alternate 3117 relation values to support protocol versioning. 3119 Reference: RFC XXXX 3121 ` 3123 11.2. YANG Module Registry 3125 This document registers two URIs in the IETF XML registry [RFC3688]. 3126 Following the format in RFC 3688, the following registration is 3127 requested to be made. 3129 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 3130 Registrant Contact: The NETMOD WG of the IETF. 3131 XML: N/A, the requested URI is an XML namespace. 3133 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3134 Registrant Contact: The NETMOD WG of the IETF. 3135 XML: N/A, the requested URI is an XML namespace. 3137 This document registers two YANG modules in the YANG Module Names 3138 registry [RFC6020]. 3140 name: ietf-restconf 3141 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3142 prefix: rc 3143 // RFC Ed.: replace XXXX with RFC number and remove this note 3144 reference: RFC XXXX 3146 name: ietf-restconf-monitoring 3147 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3148 prefix: rcmon 3149 // RFC Ed.: replace XXXX with RFC number and remove this note 3150 reference: RFC XXXX 3152 11.3. application/yang Media Sub Types 3154 The parent MIME media type for RESTCONF resources is application/ 3155 yang, which is defined in [RFC6020]. This document defines the 3156 following sub-types for this media type. 3158 - api 3159 - data 3160 - datastore 3161 - errors 3162 - operation 3163 - stream 3165 Type name: application 3167 Subtype name: yang.xxx 3169 Required parameters: TBD 3171 Optional parameters: TBD 3173 Encoding considerations: TBD 3175 Security considerations: TBD 3177 Interoperability considerations: TBD 3179 // RFC Ed.: replace XXXX with RFC number and remove this note 3180 Published specification: RFC XXXX 3182 11.4. RESTCONF Capability URNs 3184 [Note to RFC Editor: 3185 The RESTCONF Protocol Capability Registry does not yet exist; 3186 Need to ask IANA to create it; remove this note for publication 3187 ] 3189 This document registers several capability identifiers in "RESTCONF 3190 Protocol Capability URNs" registry 3191 Index 3192 Capability Identifier 3193 ------------------------ 3195 :defaults 3196 urn:ietf:params:restconf:capability:defaults:1.0 3198 :depth 3199 urn:ietf:params:restconf:capability:depth:1.0 3201 :fields 3202 urn:ietf:params:restconf:capability:fields:1.0 3204 :filter 3205 urn:ietf:params:restconf:capability:filter:1.0 3207 :insert 3208 urn:ietf:params:restconf:capability:insert:1.0 3210 :replay 3211 urn:ietf:params:restconf:capability:replay:1.0 3213 :with-defaults 3214 urn:ietf:params:restconf:capability:with-defaults:1.0 3216 12. Security Considerations 3218 This section provides security considerations for the resources 3219 defined by the RESTCONF protocol. Security considerations for HTTPS 3220 are defined in [RFC2818]. Security considerations for the content 3221 manipulated by RESTCONF can be found in the documents defining data 3222 models. 3224 This document does not specify an authentication scheme, but it does 3225 require that an authenticated NETCONF username be associated with 3226 each HTTP request. The authentication scheme MAY be implemented in 3227 the underlying transport layer (e.g., client certificates) or within 3228 the HTTP layer (e.g., Basic Auth, OAuth, etc.). RESTCONF does not 3229 itself define an authentication mechanism, authentication MUST occur 3230 in a lower layer. Implementors SHOULD provide a comprehensive 3231 authorization scheme with RESTCONF and ensure that the resulting 3232 NETCONF username is made available to the RESTCONF server. 3234 Authorization of individual user access to operations and data MAY be 3235 configured via NETCONF Access Control Model (NACM) [RFC6536], as 3236 specified in Section 4. Other authorization models MAY be used, but 3237 are outside of the scope of this document. 3239 Configuration information is by its very nature sensitive. Its 3240 transmission in the clear and without integrity checking leaves 3241 devices open to classic eavesdropping and false data injection 3242 attacks. Configuration information often contains passwords, user 3243 names, service descriptions, and topological information, all of 3244 which are sensitive. Because of this, this protocol SHOULD be 3245 implemented carefully with adequate attention to all manner of attack 3246 one might expect to experience with other management interfaces. 3248 Different environments may well allow different rights prior to and 3249 then after authentication. When an operation is not properly 3250 authorized, the RESTCONF server MUST return HTTP error status code 3251 401 Unauthorized. Note that authorization information can be 3252 exchanged in the form of configuration information, which is all the 3253 more reason to ensure the security of the connection. 3255 13. Acknowledgements 3257 The authors would like to thank the following people for their 3258 contributions to this document: Ladislav Lhotka, Juergen 3259 Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. 3261 14. References 3263 14.1. Normative References 3265 [I-D.ietf-netconf-yang-library] 3266 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 3267 Library", draft-ietf-netconf-yang-library-00 (work in 3268 progress), January 2015. 3270 [I-D.ietf-netmod-yang-json] 3271 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3272 draft-ietf-netmod-yang-json-02 (work in progress), 3273 November 2014. 3275 [I-D.lhotka-netmod-yang-metadata] 3276 Lhotka, L., "Defining and Using Metadata with YANG", 3277 draft-lhotka-netmod-yang-metadata-00 (work in progress), 3278 September 2014. 3280 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3281 Extensions (MIME) Part Two: Media Types", RFC 2046, 3282 November 1996. 3284 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3285 Requirement Levels", BCP 14, RFC 2119, March 1997. 3287 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3288 Resource Identifiers (URI): Generic Syntax", RFC 2396, 3289 August 1998. 3291 [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. 3293 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3294 January 2004. 3296 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3297 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3298 3986, January 2005. 3300 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 3301 Authentication Protocol", RFC 4252, January 2006. 3303 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3304 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3306 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3307 Notifications", RFC 5277, July 2008. 3309 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3310 Housley, R., and T. Polk, "Internet X.509 Public Key 3311 Infrastructure Certificate and Certificate Revocation List 3312 (CRL) Profile", RFC 5280, May 2008. 3314 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3315 5789, March 2010. 3317 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3319 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 3320 Network Configuration Protocol (NETCONF)", RFC 6020, 3321 October 2010. 3323 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3324 Verification of Domain-Based Application Service Identity 3325 within Internet Public Key Infrastructure Using X.509 3326 (PKIX) Certificates in the Context of Transport Layer 3327 Security (TLS)", RFC 6125, March 2011. 3329 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3330 and A. Bierman, Ed., "Network Configuration Protocol 3331 (NETCONF)", RFC 6241, June 2011. 3333 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 3334 NETCONF", RFC 6243, June 2011. 3336 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 3337 6415, October 2011. 3339 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 3340 Protocol (NETCONF) Access Control Model", RFC 6536, March 3341 2012. 3343 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3344 and D. Orchard, "URI Template", RFC 6570, March 2012. 3346 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 3347 July 2013. 3349 [RFC7158] Bray, T., Ed., "The JSON Data Interchange Format", RFC 3350 7158, March 2013. 3352 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3353 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 3354 2014. 3356 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3357 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3359 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3360 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 3362 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3363 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3365 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 3366 7320, July 2014. 3368 [W3C.CR-eventsource-20121211] 3369 Hickson, I., "Server-Sent Events", World Wide Web 3370 Consortium CR CR-eventsource-20121211, December 2012, 3371 . 3373 [W3C.REC-xml-20081126] 3374 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 3375 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 3376 Edition)", World Wide Web Consortium Recommendation REC- 3377 xml-20081126, November 2008, 3378 . 3380 [draft-ietf-httpauth-basicauth-update-03] 3381 Reschke, J., "The 'Basic' HTTP Authentication Scheme", 3382 draft-ietf-httpauth-basicauth-update-03 (work in 3383 progress), Dec 2014. 3385 [draft-ietf-httpauth-digest-09] 3386 Shekh-Yusef, R., Reschke, D., and S. Bremer, "HTTP Digest 3387 Access Authentication", draft-ietf-httpauth-digest-09 3388 (work in progress), Dec 2014. 3390 [draft-ietf-netconf-rfc5539bis-07] 3391 Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 3392 NETCONF Protocol over Transport Layer Security (TLS) with 3393 Mutual X.509 Authentication", draft-ietf-netconf- 3394 rfc5539bis-07 (work in progress), Dec 2014. 3396 [draft-thomson-httpbis-cant-01] 3397 Thomson, M., "Client Authentication over New TLS 3398 Connection", draft-thomson-httpbis-cant-01 (work in 3399 progress), Jul 2014. 3401 [rest-dissertation] 3402 Fielding, R., "Architectural Styles and the Design of 3403 Network-based Software Architectures", 2000. 3405 14.2. Informative References 3407 [I-D.ietf-netconf-yang-patch] 3408 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 3409 Media Type", draft-ietf-netconf-yang-patch-03 (work in 3410 progress), January 2015. 3412 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 3413 Version 1.0", World Wide Web Consortium Recommendation 3414 REC-xpath-19991116, November 1999, 3415 . 3417 Appendix A. Change Log 3419 -- RFC Ed.: remove this section before publication. 3421 The RESTCONF issue tracker can be found here: https://github.com/ 3422 netconf-wg/restconf/issues 3424 A.1. 03 - 04 3426 o renamed 'select' to 'fields' (#1) 3428 o moved collection resource and page capability to draft-ietf- 3429 netconf-restconf-collection-00 (#3) 3431 o added mandatory "defaults" protocol capability URI (#4) 3432 o added optional "with-defaults" query parameter URI (#4) 3434 o clarified authentication procedure (#9) 3436 o moved ietf-yang-library module to draft-ietf-netconf-yang- 3437 library-00 (#13) 3439 o clarified that JSON encoding of module name in a URI MUST follow 3440 the netmod-yang-json encoding rules (#14) 3442 o added restconf-media-type extension (#15) 3444 o remove 'content" query parameter URI and made this parameter 3445 mandatory (#16) 3447 o clarified datastore usage 3449 o changed lock-denied error example 3451 o added with-defaults query parameter example 3453 o added term "RESTCONF Capability" 3455 o changed NETCONF Capability URI registry usage to new RESTCONF 3456 Capability URI Registry usage 3458 A.2. 02 - 03 3460 o added collection resource 3462 o added "page" query parameter capability 3464 o added "limit" and "offset" query parameters, which are available 3465 if the "page" capability is supported 3467 o added "stream list" term 3469 o fixed bugs in some examples 3471 o added "encoding" list within the "stream" list to allow different 3472 URLs for XML and JSON encoding. 3474 o made XML MUST implement and JSON MAY implement for servers 3476 o re-add JSON notification examples (previously removed) 3478 o updated JSON references 3480 A.3. 01 - 02 3482 o moved query parameter definitions from the YANG module back to the 3483 plain text sections 3485 o made all query parameters optional to implement 3487 o defined query parameter capability URI 3489 o moved 'streams' to new YANG module (ietf-restconf-monitoring) 3491 o added 'capabilities' container to new YANG module (ietf-restconf- 3492 monitoring) 3494 o moved 'modules' container to new YANG module (ietf-yang-library) 3496 o added new leaf 'module-set-id' (ietf-yang-library) 3498 o added new leaf 'conformance' (ietf-yang-library) 3500 o changed 'schema' leaf to type inet:uri that returns the location 3501 of the YANG schema (instead of returning the schema directly) 3503 o changed 'events' leaf to type inet:uri that returns the location 3504 of the event stream resource (instead of returning events 3505 directly) 3507 o changed examples for yang.api resource since the monitoring 3508 information is no longer in this resource 3510 o closed issue #1 'select parameter' since no objections to the 3511 proposed syntax 3513 o closed "encoding of list keys" issue since no objection to new 3514 encoding of list keys in a target resource URI. 3516 o moved open issues list to the issue tracker on github 3518 A.4. 00 - 01 3520 o fixed content=nonconfig example (non-config was incorrect) 3522 o closed open issue 'message-id'. There is no need for a message-id 3523 field, and RFC 2392 does not apply. 3525 o closed open issue 'server support verification'. The headers used 3526 by RESTCONF are widely supported. 3528 o removed encoding rules from section on RESTCONF Meta-Data. This 3529 is now defined in "I-D.lhotka-netmod-yang-json". 3531 o added media type application/yang.errors to map to errors YANG 3532 grouping. Updated error examples to use new media type. 3534 o closed open issue 'additional datastores'. Support may be added 3535 in the future to identify new datastores. 3537 o closed open issue 'PATCH media type discovery'. The section on 3538 PATCH has an added sentence on the Accept-Patch header. 3540 o closed open issue 'YANG to resource mapping'. Current mapping of 3541 all data nodes to resources will be used in order to allow 3542 mandatory DELETE support. The PATCH operation is optional, as 3543 well as the YANG Patch media type. 3545 o closed open issue '_self links for HATEOAS support'. It was 3546 decided that they are redundant because they can be derived from 3547 the YANG module for the specific data. 3549 o added explanatory text for the 'select' parameter. 3551 o added RESTCONF Path Resolution section for discovering the root of 3552 the RESTCONF API using the /.well-known/host-meta. 3554 o added an "error" media type to for structured error messages 3556 o added Secure Transport section requiring TLS 3558 o added Security Considerations section 3560 o removed all references to "REST-like" 3562 A.5. bierman:restconf-04 to ietf:restconf-00 3564 o updated open issues section 3566 Appendix B. Open Issues 3568 -- RFC Ed.: remove this section before publication. 3570 The RESTCONF issues are tracked on github.com: 3572 https://github.com/netconf-wg/restconf/issues 3574 Appendix C. Example YANG Module 3576 The example YANG module used in this document represents a simple 3577 media jukebox interface. 3579 YANG Tree Diagram for "example-jukebox" Module 3581 +--rw jukebox? 3582 +--rw library 3583 | +--rw artist [name] 3584 | | +--rw name string 3585 | | +--rw album [name] 3586 | | +--rw name string 3587 | | +--rw genre? identityref 3588 | | +--rw year? uint16 3589 | | +--rw admin 3590 | | | +--rw label? string 3591 | | | +--rw catalogue-number? string 3592 | | +--rw song [name] 3593 | | +--rw name string 3594 | | +--rw location string 3595 | | +--rw format? string 3596 | | +--rw length? uint32 3597 | +--ro artist-count? uint32 3598 | +--ro album-count? uint32 3599 | +--ro song-count? uint32 3600 +--rw playlist [name] 3601 | +--rw name string 3602 | +--rw description? string 3603 | +--rw song [index] 3604 | +--rw index uint32 3605 | +--rw id instance-identifier 3606 +--rw player 3607 +--rw gap? decimal64 3609 rpcs: 3611 +---x play 3612 +--ro input 3613 +--ro playlist string 3614 +--ro song-number uint32 3616 C.1. example-jukebox YANG Module 3618 module example-jukebox { 3620 namespace "http://example.com/ns/example-jukebox"; 3621 prefix "jbox"; 3622 import ietf-restconf { prefix rc; } 3624 organization "Example, Inc."; 3625 contact "support at example.com"; 3626 description "Example Jukebox Data Model Module"; 3627 revision "2014-07-03" { 3628 description "Initial version."; 3629 reference "example.com document 1-4673"; 3630 } 3632 identity genre { 3633 description "Base for all genre types"; 3634 } 3636 // abbreviated list of genre classifications 3637 identity alternative { 3638 base genre; 3639 description "Alternative music"; 3640 } 3641 identity blues { 3642 base genre; 3643 description "Blues music"; 3644 } 3645 identity country { 3646 base genre; 3647 description "Country music"; 3648 } 3649 identity jazz { 3650 base genre; 3651 description "Jazz music"; 3652 } 3653 identity pop { 3654 base genre; 3655 description "Pop music"; 3656 } 3657 identity rock { 3658 base genre; 3659 description "Rock music"; 3660 } 3662 container jukebox { 3663 presence 3664 "An empty container indicates that the jukebox 3665 service is available"; 3667 description 3668 "Represents a jukebox resource, with a library, playlists, 3669 and a play operation."; 3671 container library { 3673 description "Represents the jukebox library resource."; 3675 list artist { 3676 key name; 3678 description 3679 "Represents one artist resource within the 3680 jukebox library resource."; 3682 leaf name { 3683 type string { 3684 length "1 .. max"; 3685 } 3686 description "The name of the artist."; 3687 } 3689 list album { 3690 key name; 3692 description 3693 "Represents one album resource within one 3694 artist resource, within the jukebox library."; 3696 leaf name { 3697 type string { 3698 length "1 .. max"; 3699 } 3700 description "The name of the album."; 3701 } 3703 leaf genre { 3704 type identityref { base genre; } 3705 description 3706 "The genre identifying the type of music on 3707 the album."; 3708 } 3710 leaf year { 3711 type uint16 { 3712 range "1900 .. max"; 3713 } 3714 description "The year the album was released"; 3715 } 3717 container admin { 3718 description 3719 "Administrative information for the album."; 3721 leaf label { 3722 type string; 3723 description "The label that released the album."; 3724 } 3725 leaf catalogue-number { 3726 type string; 3727 description "The album's catalogue number."; 3728 } 3729 } 3731 list song { 3732 key name; 3734 description 3735 "Represents one song resource within one 3736 album resource, within the jukebox library."; 3738 leaf name { 3739 type string { 3740 length "1 .. max"; 3741 } 3742 description "The name of the song"; 3743 } 3744 leaf location { 3745 type string; 3746 mandatory true; 3747 description 3748 "The file location string of the 3749 media file for the song"; 3750 } 3751 leaf format { 3752 type string; 3753 description 3754 "An identifier string for the media type 3755 for the file associated with the 3756 'location' leaf for this entry."; 3757 } 3758 leaf length { 3759 type uint32; 3760 units "seconds"; 3761 description 3762 "The duration of this song in seconds."; 3763 } 3764 } // end list 'song' 3765 } // end list 'album' 3766 } // end list 'artist' 3767 leaf artist-count { 3768 type uint32; 3769 units "songs"; 3770 config false; 3771 description "Number of artists in the library"; 3772 } 3773 leaf album-count { 3774 type uint32; 3775 units "albums"; 3776 config false; 3777 description "Number of albums in the library"; 3778 } 3779 leaf song-count { 3780 type uint32; 3781 units "songs"; 3782 config false; 3783 description "Number of songs in the library"; 3784 } 3785 } // end library 3787 list playlist { 3788 key name; 3790 description 3791 "Example configuration data resource"; 3793 leaf name { 3794 type string; 3795 description 3796 "The name of the playlist."; 3797 } 3798 leaf description { 3799 type string; 3800 description 3801 "A comment describing the playlist."; 3802 } 3803 list song { 3804 key index; 3805 ordered-by user; 3807 description 3808 "Example nested configuration data resource"; 3810 leaf index { // not really needed 3811 type uint32; 3812 description 3813 "An arbitrary integer index for this 3814 playlist song."; 3816 } 3817 leaf id { 3818 type rc:data-resource-identifier; 3819 mandatory true; 3820 description 3821 "Song identifier. Must identify an instance of 3822 /jukebox/library/artist/album/song/name."; 3823 } 3824 } 3825 } 3827 container player { 3828 description 3829 "Represents the jukebox player resource."; 3831 leaf gap { 3832 type decimal64 { 3833 fraction-digits 1; 3834 range "0.0 .. 2.0"; 3835 } 3836 units "tenths of seconds"; 3837 description "Time gap between each song"; 3838 } 3839 } 3840 } 3842 rpc play { 3843 description "Control function for the jukebox player"; 3844 input { 3845 leaf playlist { 3846 type string; 3847 mandatory true; 3848 description "playlist name"; 3849 } 3850 leaf song-number { 3851 type uint32; 3852 mandatory true; 3853 description "Song number in playlist to play"; 3854 } 3855 } 3856 } 3857 } 3859 Appendix D. RESTCONF Message Examples 3861 The examples within this document use the normative YANG module 3862 defined in Section 8 and the non-normative example YANG module 3863 defined in Appendix C.1. 3865 This section shows some typical RESTCONF message exchanges. 3867 D.1. Resource Retrieval Examples 3869 D.1.1. Retrieve the Top-level API Resource 3871 The client may start by retrieving the top-level API resource, using 3872 the entry point URI "{+restconf}". 3874 GET /restconf HTTP/1.1 3875 Host: example.com 3876 Accept: application/yang.api+json 3878 The server might respond as follows: 3880 HTTP/1.1 200 OK 3881 Date: Mon, 23 Apr 2012 17:01:00 GMT 3882 Server: example-server 3883 Content-Type: application/yang.api+json 3885 { 3886 "ietf-restconf:restconf": { 3887 "data" : [ null ], 3888 "operations" : { 3889 "play" : [ null ] 3890 } 3891 } 3892 } 3894 To request that the response content to be encoded in XML, the 3895 "Accept" header can be used, as in this example request: 3897 GET /restconf HTTP/1.1 3898 Host: example.com 3899 Accept: application/yang.api+xml 3901 The server will return the same response either way, which might be 3902 as follows : 3904 HTTP/1.1 200 OK 3905 Date: Mon, 23 Apr 2012 17:01:00 GMT 3906 Server: example-server 3907 Cache-Control: no-cache 3908 Pragma: no-cache 3909 Content-Type: application/yang.api+xml 3911 3912 3913 3914 3915 3916 3918 D.1.2. Retrieve The Server Module Information 3920 In this example the client is retrieving the modules information from 3921 the server in JSON format: 3923 GET /restconf/data/ietf-yang-library:modules HTTP/1.1 3924 Host: example.com 3925 Accept: application/yang.data+json 3927 The server might respond as follows. 3929 HTTP/1.1 200 OK 3930 Date: Mon, 23 Apr 2012 17:01:00 GMT 3931 Server: example-server 3932 Cache-Control: no-cache 3933 Pragma: no-cache 3934 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 3935 Content-Type: application/yang.data+json 3937 { 3938 "ietf-yang-library:modules": { 3939 "module": [ 3940 { 3941 "name" : "foo", 3942 "revision" : "2012-01-02", 3943 "schema" : "https://example.com/mymodules/foo/2012-01-02", 3944 "namespace" : "http://example.com/ns/foo", 3945 "feature" : [ "feature1", "feature2" ], 3946 "conformance" : true 3947 }, 3948 { 3949 "name" : "foo-types", 3950 "revision" : "2012-01-05", 3951 "schema" : 3953 "https://example.com/mymodules/foo-types/2012-01-05", 3954 "schema" : [null], 3955 "namespace" : "http://example.com/ns/foo-types", 3956 "conformance" : false 3957 }, 3958 { 3959 "name" : "bar", 3960 "revision" : "2012-11-05", 3961 "schema" : "https://example.com/mymodules/bar/2012-11-05", 3962 "namespace" : "http://example.com/ns/bar", 3963 "feature" : [ "bar-ext" ], 3964 "conformance" : true, 3965 "submodule" : [ 3966 { 3967 "name" : "bar-submod1", 3968 "revision" : "2012-11-05", 3969 "schema" : 3970 "https://example.com/mymodules/bar-submod1/2012-11-05" 3971 }, 3972 { 3973 "name" : "bar-submod2", 3974 "revision" : "2012-11-05", 3975 "schema" : 3976 "https://example.com/mymodules/bar-submod2/2012-11-05" 3977 } 3978 ] 3979 } 3980 ] 3981 } 3982 } 3984 D.1.3. Retrieve The Server Capability Information 3986 In this example the client is retrieving the capability information 3987 from the server in JSON format, and the server supports all the 3988 RESTCONF query parameters, plus one vendor parameter: 3990 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 3991 capabilities HTTP/1.1 3992 Host: example.com 3993 Accept: application/yang.data+json 3995 The server might respond as follows. 3997 HTTP/1.1 200 OK 3998 Date: Mon, 23 Apr 2012 17:02:00 GMT 3999 Server: example-server 4000 Cache-Control: no-cache 4001 Pragma: no-cache 4002 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4003 Content-Type: application/yang.data+json 4005 { 4006 "ietf-restconf-monitoring:capabilities": { 4007 "capability": [ 4008 "urn:ietf:params:restconf:capability:content:1.0", 4009 "urn:ietf:params:restconf:capability:depth:1.0", 4010 "urn:ietf:params:restconf:capability:fields:1.0", 4011 "urn:ietf:params:restconf:capability:filter:1.0", 4012 "urn:ietf:params:restconf:capability:insert:1.0", 4013 "urn:ietf:params:restconf:capability:point:1.0", 4014 "urn:ietf:params:restconf:capability:start-time:1.0", 4015 "urn:ietf:params:restconf:capability:stop-time:1.0", 4016 "http://example.com/capabilities/myparam" 4017 ] 4018 } 4019 } 4021 D.2. Edit Resource Examples 4023 D.2.1. Create New Data Resources 4025 To create a new "artist" resource within the "library" resource, the 4026 client might send the following request. 4028 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 4029 Host: example.com 4030 Content-Type: application/yang.data+json 4032 { "example-jukebox:artist" : { 4033 "name" : "Foo Fighters" 4034 } 4035 } 4037 If the resource is created, the server might respond as follows. 4038 Note that the "Location" header line is wrapped for display purposes 4039 only: 4041 HTTP/1.1 201 Created 4042 Date: Mon, 23 Apr 2012 17:02:00 GMT 4043 Server: example-server 4044 Location: https://example.com/restconf/data/ 4045 example-jukebox:jukebox/library/artist=Foo%20Fighters 4046 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 4047 ETag: b3830f23a4c 4049 To create a new "album" resource for this artist within the "jukebox" 4050 resource, the client might send the following request. Note that the 4051 request URI header line is wrapped for display purposes only: 4053 POST /restconf/data/example-jukebox:jukebox/ 4054 library/artist=Foo%20Fighters HTTP/1.1 4055 Host: example.com 4056 Content-Type: application/yang.data+json 4058 { 4059 "example-jukebox:album" : { 4060 "name" : "Wasting Light", 4061 "genre" : "example-jukebox:alternative", 4062 "year" : 2012 # note this is the wrong date 4063 } 4064 } 4066 If the resource is created, the server might respond as follows. 4067 Note that the "Location" header line is wrapped for display purposes 4068 only: 4070 HTTP/1.1 201 Created 4071 Date: Mon, 23 Apr 2012 17:03:00 GMT 4072 Server: example-server 4073 Location: https://example.com/restconf/data/ 4074 example-jukebox:jukebox/library/artist=Foo%20Fighters/ 4075 album=Wasting%20Light 4076 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 4077 ETag: b8389233a4c 4079 D.2.2. Detect Resource Entity Tag Change 4081 In this example, the server just supports the mandatory datastore 4082 last-changed timestamp. The client has previously retrieved the 4083 "Last-Modified" header and has some value cached to provide in the 4084 following request to patch an "album" list entry with key value 4085 "Wasting Light". Only the "year" field is being updated. 4087 PATCH /restconf/data/example-jukebox:jukebox/ 4088 library/artist=Foo%20Fighters/album=Wasting%20Light/year 4089 HTTP/1.1 4090 Host: example.com 4091 Accept: application/yang.data+json 4092 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 4093 Content-Type: application/yang.data+json 4095 { "example-jukebox:year" : "2011" } 4097 In this example the datastore resource has changed since the time 4098 specified in the "If-Unmodified-Since" header. The server might 4099 respond: 4101 HTTP/1.1 412 Precondition Failed 4102 Date: Mon, 23 Apr 2012 19:01:00 GMT 4103 Server: example-server 4104 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 4105 ETag: b34aed893a4c 4107 D.3. Query Parameter Examples 4109 D.3.1. "content" Parameter 4111 The "content" parameter is used to select the type of data child 4112 resources (configuration and/or not configuration) that are returned 4113 by the server for a GET method request. 4115 In this example, a simple YANG list that has configuration and non- 4116 configuration child resources. 4118 container events 4119 list event { 4120 key name; 4121 leaf name { type string; } 4122 leaf description { type string; } 4123 leaf event-count { 4124 type uint32; 4125 config false; 4126 } 4127 } 4128 } 4130 Example 1: content=all 4132 To retrieve all the child resources, the "content" parameter is set 4133 to "all". The client might send: 4135 GET /restconf/data/example-events:events?content=all 4136 HTTP/1.1 4137 Host: example.com 4138 Accept: application/yang.data+json 4140 The server might respond: 4142 HTTP/1.1 200 OK 4143 Date: Mon, 23 Apr 2012 17:11:30 GMT 4144 Server: example-server 4145 Cache-Control: no-cache 4146 Pragma: no-cache 4147 Content-Type: application/yang.data+json 4149 { 4150 "example-events:events" : { 4151 "event" : [ 4152 { 4153 "name" : "interface-up", 4154 "description" : "Interface up notification count", 4155 "event-count" : 42 4156 }, 4157 { 4158 "name" : "interface-down", 4159 "description" : "Interface down notification count", 4160 "event-count" : 4 4161 } 4162 ] 4163 } 4164 } 4166 Example 2: content=config 4168 To retrieve only the configuration child resources, the "content" 4169 parameter is set to "config" or omitted since this is the default 4170 value. Note that the "ETag" and "Last-Modified" headers are only 4171 returned if the content parameter value is "config". 4173 GET /restconf/data/example-events:events?content=config 4174 HTTP/1.1 4175 Host: example.com 4176 Accept: application/yang.data+json 4178 The server might respond: 4180 HTTP/1.1 200 OK 4181 Date: Mon, 23 Apr 2012 17:11:30 GMT 4182 Server: example-server 4183 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4184 ETag: eeeada438af 4185 Cache-Control: no-cache 4186 Pragma: no-cache 4187 Content-Type: application/yang.data+json 4189 { 4190 "example-events:events" : { 4191 "event" : [ 4192 { 4193 "name" : "interface-up", 4194 "description" : "Interface up notification count" 4195 }, 4196 { 4197 "name" : "interface-down", 4198 "description" : "Interface down notification count" 4199 } 4200 ] 4201 } 4202 } 4204 Example 3: content=nonconfig 4206 To retrieve only the non-configuration child resources, the "content" 4207 parameter is set to "nonconfig". Note that configuration ancestors 4208 (if any) and list key leafs (if any) are also returned. The client 4209 might send: 4211 GET /restconf/data/example-events:events?content=nonconfig 4212 HTTP/1.1 4213 Host: example.com 4214 Accept: application/yang.data+json 4216 The server might respond: 4218 HTTP/1.1 200 OK 4219 Date: Mon, 23 Apr 2012 17:11:30 GMT 4220 Server: example-server 4221 Cache-Control: no-cache 4222 Pragma: no-cache 4223 Content-Type: application/yang.data+json 4225 { 4226 "example-events:events" : { 4227 "event" : [ 4228 { 4229 "name" : "interface-up", 4230 "event-count" : 42 4231 }, 4232 { 4233 "name" : "interface-down", 4234 "event-count" : 4 4235 } 4236 ] 4237 } 4238 } 4240 D.3.2. "depth" Parameter 4242 The "depth" parameter is used to limit the number of levels of child 4243 resources that are returned by the server for a GET method request. 4245 This example shows how different values of the "depth" parameter 4246 would affect the reply content for retrieval of the top-level 4247 "jukebox" data resource. 4249 Example 1: depth=unbounded 4251 To retrieve all the child resources, the "depth" parameter is not 4252 present or set to the default value "unbounded". Note that some 4253 strings are wrapped for display purposes only. 4255 GET /restconf/data/example-jukebox:jukebox?depth=unbounded 4256 HTTP/1.1 4257 Host: example.com 4258 Accept: application/yang.data+json 4260 The server might respond: 4262 HTTP/1.1 200 OK 4263 Date: Mon, 23 Apr 2012 17:11:30 GMT 4264 Server: example-server 4265 Cache-Control: no-cache 4266 Pragma: no-cache 4267 Content-Type: application/yang.data+json 4269 { 4270 "example-jukebox:jukebox" : { 4271 "library" : { 4272 "artist" : [ 4273 { 4274 "name" : "Foo Fighters", 4275 "album" : [ 4276 { 4277 "name" : "Wasting Light", 4278 "genre" : "example-jukebox:alternative", 4279 "year" : 2011, 4280 "song" : [ 4281 { 4282 "name" : "Wasting Light", 4283 "location" : 4284 "/media/foo/a7/wasting-light.mp3", 4285 "format" : "MP3", 4286 "length" " 286 4287 }, 4288 { 4289 "name" : "Rope", 4290 "location" : "/media/foo/a7/rope.mp3", 4291 "format" : "MP3", 4292 "length" " 259 4293 } 4294 ] 4295 } 4296 ] 4297 } 4298 ] 4299 }, 4300 "playlist" : [ 4301 { 4302 "name" : "Foo-One", 4303 "description" : "example playlist 1", 4304 "song" : [ 4305 { 4306 "index" : 1, 4307 "id" : "https://example.com/restconf/data/ 4308 example-jukebox:jukebox/library/artist= 4309 Foo%20Fighters/album/Wasting%20Light/ 4310 song/Rope" 4311 }, 4312 { 4313 "index" : 2, 4314 "id" : "https://example.com/restconf/data/ 4315 example-jukebox:jukebox/library/artist= 4316 Foo%20Fighters/album/Wasting%20Light/song/ 4317 Bridge%20Burning" 4318 } 4319 ] 4320 } 4321 ], 4322 "player" : { 4323 "gap" : 0.5 4324 } 4325 } 4326 } 4328 Example 2: depth=1 4330 To determine if 1 or more resource instances exist for a given target 4331 resource, the value "1" is used. 4333 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 4334 Host: example.com 4335 Accept: application/yang.data+json 4337 The server might respond: 4339 HTTP/1.1 200 OK 4340 Date: Mon, 23 Apr 2012 17:11:30 GMT 4341 Server: example-server 4342 Cache-Control: no-cache 4343 Pragma: no-cache 4344 Content-Type: application/yang.data+json 4346 { 4347 "example-jukebox:jukebox" : [null] 4348 } 4350 Example 3: depth=3 4352 To limit the depth level to the target resource plus 2 child resource 4353 layers the value "3" is used. 4355 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 4356 Host: example.com 4357 Accept: application/yang.data+json 4359 The server might respond: 4361 HTTP/1.1 200 OK 4362 Date: Mon, 23 Apr 2012 17:11:30 GMT 4363 Server: example-server 4364 Cache-Control: no-cache 4365 Pragma: no-cache 4366 Content-Type: application/yang.data+json 4368 { 4369 "example-jukebox:jukebox" : { 4370 "library" : { 4371 "artist" : [ null ] 4372 }, 4373 "playlist" : [ 4374 { 4375 "name" : "Foo-One", 4376 "description" : "example playlist 1", 4377 "song" : [ null ] 4378 } 4379 ], 4380 "player" : { 4381 "gap" : 0.5 4382 } 4383 } 4384 } 4386 D.3.3. "fields" Parameter 4388 In this example the client is retrieving the API resource, but 4389 retrieving only the "name" and "revision" nodes from each module, in 4390 JSON format: 4392 GET /restconf/data?fields=modules/module(name;revision) HTTP/1.1 4393 Host: example.com 4394 Accept: application/yang.data+json 4396 The server might respond as follows. 4398 HTTP/1.1 200 OK 4399 Date: Mon, 23 Apr 2012 17:01:00 GMT 4400 Server: example-server 4401 Content-Type: application/yang.data+json 4403 { 4404 "ietf-yang-library:modules": { 4405 "module": [ 4406 { 4407 "name" : "example-jukebox", 4408 "revision" : "2014-07-03" 4409 }, 4410 { 4411 "name" : "ietf-restconf-monitoring", 4412 "revision" : "2015-01-30" 4413 }, 4414 { 4415 "name" : "ietf-yang-library", 4416 "revision" : "2015-01-30" 4417 } 4418 ] 4419 } 4420 } 4422 D.3.4. "insert" Parameter 4424 In this example, a new first entry in the "Foo-One" playlist is being 4425 created. 4427 Request from client: 4429 POST /restconf/data/example-jukebox:jukebox/ 4430 playlist=Foo-One?insert=first HTTP/1.1 4431 Host: example.com 4432 Content-Type: application/yang.data+json 4434 { 4435 "example-jukebox:song" : { 4436 "index" : 1, 4437 "id" : "/example-jukebox:jukebox/library/ 4438 artist=Foo%20Fighters/album/Wasting%20Light/song/Rope" 4439 } 4440 } 4442 Response from server: 4444 HTTP/1.1 201 Created 4445 Date: Mon, 23 Apr 2012 13:01:20 GMT 4446 Server: example-server 4447 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4448 Location: https://example.com/restconf/data/ 4449 example-jukebox:jukebox/playlist=Foo-One/song=1 4450 ETag: eeeada438af 4452 D.3.5. "point" Parameter 4454 In this example, the client is inserting a new "song" resource within 4455 an "album" resource after another song. The request URI is split for 4456 display purposes only. 4458 Request from client: 4460 POST /restconf/data/example-jukebox:jukebox/ 4461 library/artist=Foo%20Fighters/album/Wasting%20Light? 4462 insert=after&point=%2Fexample-jukebox%3Ajukebox%2F 4463 library%2Fartist%2FFoo%20Fighters%2Falbum%2F 4464 Wasting%20Light%2Fsong%2FBridge%20Burning HTTP/1.1 4465 Host: example.com 4466 Content-Type: application/yang.data+json 4468 { 4469 "example-jukebox:song" : { 4470 "name" : "Rope", 4471 "location" : "/media/foo/a7/rope.mp3", 4472 "format" : "MP3", 4473 "length" : 259 4474 } 4475 } 4477 Response from server: 4479 HTTP/1.1 204 No Content 4481 1. Date: Mon, 23 Apr 2012 13:01:20 GMT Server: example-server Last- 4482 Modified: Mon, 23 Apr 2012 13:01:20 GMT ETag: abcada438af 4484 D.3.6. "filter" Parameter 4486 The following URIs show some examples of notification filter 4487 specifications (lines wrapped for display purposes only): 4489 // filter = /event/event-class='fault' 4490 GET /mystreams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' 4492 // filter = /event/severity<=4 4493 GET /mystreams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 4495 // filter = /linkUp|/linkDown 4496 GET /mystreams/SNMP?filter=%2FlinkUp%7C%2FlinkDown 4498 // filter = /*/reporting-entity/card!='Ethernet0' 4499 GET /mystreams/NETCONF? 4500 filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' 4502 // filter = /*/email-addr[contains(.,'company.com')] 4503 GET /mystreams/critical-syslog? 4504 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 4506 // Note: the module name is used as prefix. 4507 // filter = (/example-mod:event1/name='joe' and 4508 // /example-mod:event1/status='online') 4509 GET /mystreams/NETCONF? 4510 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and 4511 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 4513 D.3.7. "start-time" Parameter 4515 // start-time = 2014-10-25T10:02:00Z 4516 GET /mystreams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z 4518 D.3.8. "stop-time" Parameter 4520 // stop-time = 2014-10-25T12:31:00Z 4521 GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z 4523 D.3.9. "with-defaults" Parameter 4525 Assume the same data model as defined in Appendix A.1 of [RFC6243]. 4526 Assume the same data set as defined in Appendix A.2 of [RFC6243]. If 4527 the server defaults-uri basic-mode is "trim", the the following 4528 request for interface "eth1" might be as follows: 4530 Without query parameter: 4532 GET /restconf/data/interfaces/interface=eth1 HTTP/1.1 4533 Host: example.com 4534 Accept: application/yang.data+json 4536 The server might respond as follows. 4538 HTTP/1.1 200 OK 4539 Date: Mon, 23 Apr 2012 17:01:00 GMT 4540 Server: example-server 4541 Content-Type: application/yang.data+json 4543 { 4544 "example:interface": [ 4545 { 4546 "name" : "eth1", 4547 "status" : "up" 4548 } 4549 ] 4550 } 4552 Note that the "mtu" leaf is missing because it is set to the default 4553 "1500", and the server defaults handling basic-mode is "trim". 4555 With query parameter: 4557 GET /restconf/data/interfaces/interface=eth1 4558 ?with-defaults=report-all HTTP/1.1 4559 Host: example.com 4560 Accept: application/yang.data+json 4562 The server might respond as follows. 4564 HTTP/1.1 200 OK 4565 Date: Mon, 23 Apr 2012 17:01:00 GMT 4566 Server: example-server 4567 Content-Type: application/yang.data+json 4569 { 4570 "example:interface": [ 4571 { 4572 "name" : "eth1", 4573 "mtu" : 1500, 4574 "status" : "up" 4575 } 4576 ] 4577 } 4579 Note that the server returns the "mtu" leaf because the "report-all" 4580 mode was requested with the "with-defaults" query parameter. 4582 Authors' Addresses 4584 Andy Bierman 4585 YumaWorks 4587 Email: andy@yumaworks.com 4589 Martin Bjorklund 4590 Tail-f Systems 4592 Email: mbj@tail-f.com 4594 Kent Watsen 4595 Juniper Networks 4597 Email: kwatsen@juniper.net