idnits 2.17.1 draft-bierman-netconf-restconf-01.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 14 instances of lines with non-RFC2606-compliant FQDNs in the document. == 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 1696 has weird spacing: '... method entry...' == 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 (September 9, 2013) is 3881 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'TBD' is mentioned on line 2412, but not defined == Outdated reference: A later version (-02) exists of draft-lhotka-netmod-yang-json-01 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 2 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). 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: March 13, 2014 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 R. Fernando 9 Cisco 10 September 9, 2013 12 RESTCONF Protocol 13 draft-bierman-netconf-restconf-01 15 Abstract 17 This document describes a RESTful protocol that provides a 18 programmatic interface over HTTP for accessing data defined in YANG, 19 using the datastores defined in NETCONF. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 13, 2014. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.1. Simple Subset of NETCONF Functionality . . . . . . . . . . 5 57 1.2. Data Model Driven API . . . . . . . . . . . . . . . . . . 6 58 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 59 1.3.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 7 60 1.3.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 1.3.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 1.3.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 9 63 1.4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 10 64 1.4.1. Resource URI Map . . . . . . . . . . . . . . . . . . . 11 65 1.4.2. RESTCONF Message Examples . . . . . . . . . . . . . . 11 66 2. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 18 67 2.1. Message Model . . . . . . . . . . . . . . . . . . . . . . 18 68 2.2. Notification Model . . . . . . . . . . . . . . . . . . . . 18 69 2.3. Resource Model . . . . . . . . . . . . . . . . . . . . . . 18 70 2.3.1. RESTCONF Resource Types . . . . . . . . . . . . . . . 18 71 2.3.2. Resource Discovery . . . . . . . . . . . . . . . . . . 19 72 2.4. Datastore Model . . . . . . . . . . . . . . . . . . . . . 19 73 2.4.1. Content Model . . . . . . . . . . . . . . . . . . . . 20 74 2.4.2. Editing Model . . . . . . . . . . . . . . . . . . . . 20 75 2.4.3. Locking Model . . . . . . . . . . . . . . . . . . . . 22 76 2.4.4. Persistence Model . . . . . . . . . . . . . . . . . . 22 77 2.4.5. Defaults Model . . . . . . . . . . . . . . . . . . . . 22 78 2.5. Transaction Model . . . . . . . . . . . . . . . . . . . . 23 79 2.6. Extensibility Model . . . . . . . . . . . . . . . . . . . 23 80 2.7. Versioning Model . . . . . . . . . . . . . . . . . . . . . 23 81 2.8. Retrieval Filtering Model . . . . . . . . . . . . . . . . 24 82 2.9. Access Control Model . . . . . . . . . . . . . . . . . . . 24 83 3. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 25 84 3.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 25 85 3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 86 3.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 87 3.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 88 3.4.1. Create Resource Mode . . . . . . . . . . . . . . . . . 29 89 3.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 30 90 3.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 91 3.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 30 92 3.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 31 93 3.8. Query Parameters . . . . . . . . . . . . . . . . . . . . . 31 94 3.8.1. "config" Parameter . . . . . . . . . . . . . . . . . . 31 95 3.8.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 32 96 3.8.3. "format" Parameter . . . . . . . . . . . . . . . . . . 34 97 3.8.4. "insert" Parameter . . . . . . . . . . . . . . . . . . 35 98 3.8.5. "point" Parameter . . . . . . . . . . . . . . . . . . 36 99 3.8.6. "select" Parameter . . . . . . . . . . . . . . . . . . 37 100 3.9. Protocol Operations . . . . . . . . . . . . . . . . . . . 37 101 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 102 4.1. Request URI Structure . . . . . . . . . . . . . . . . . . 38 103 4.2. Message Headers . . . . . . . . . . . . . . . . . . . . . 39 104 4.3. Message Encoding . . . . . . . . . . . . . . . . . . . . . 40 105 4.4. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . . 40 106 4.4.1. JSON Encoding of RESTCONF Meta-Data . . . . . . . . . 41 107 4.5. Return Status . . . . . . . . . . . . . . . . . . . . . . 42 108 4.6. Message Caching . . . . . . . . . . . . . . . . . . . . . 42 109 5. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 44 110 5.1. API Resource (/restconf) . . . . . . . . . . . . . . . . . 44 111 5.1.1. /restconf/datastore . . . . . . . . . . . . . . . . . 45 112 5.1.2. /restconf/modules . . . . . . . . . . . . . . . . . . 45 113 5.1.3. /restconf/operations . . . . . . . . . . . . . . . . . 46 114 5.2. Datastore Resource . . . . . . . . . . . . . . . . . . . . 47 115 5.3. Data Resource . . . . . . . . . . . . . . . . . . . . . . 47 116 5.3.1. Encoding YANG Instance Identifiers in the Request 117 URI . . . . . . . . . . . . . . . . . . . . . . . . . 48 118 5.3.2. Data Resource Retrieval . . . . . . . . . . . . . . . 51 119 5.4. Operation Resource . . . . . . . . . . . . . . . . . . . . 52 120 5.4.1. Encoding Operation Input Parameters . . . . . . . . . 52 121 5.4.2. Encoding Operation Output Parameters . . . . . . . . . 53 122 5.5. Event Resource . . . . . . . . . . . . . . . . . . . . . . 54 123 6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 55 124 6.1. Error Response Message . . . . . . . . . . . . . . . . . . 56 125 7. YANG Patch . . . . . . . . . . . . . . . . . . . . . . . . . . 58 126 7.1. Why not use JSON Patch? . . . . . . . . . . . . . . . . . 58 127 7.2. YANG Patch Target Data Node . . . . . . . . . . . . . . . 59 128 7.3. YANG Patch Edit Operations . . . . . . . . . . . . . . . . 59 129 7.4. YANG Patch Error Handling . . . . . . . . . . . . . . . . 59 130 7.5. YANG Patch Response . . . . . . . . . . . . . . . . . . . 60 131 7.6. YANG Patch Examples . . . . . . . . . . . . . . . . . . . 60 132 7.6.1. Continue-on-error Example . . . . . . . . . . . . . . 60 133 7.6.2. Move list entry example . . . . . . . . . . . . . . . 63 134 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 65 135 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78 136 9.1. YANG Module Registry . . . . . . . . . . . . . . . . . . . 78 137 10. Security Considerations . . . . . . . . . . . . . . . . . . . 79 138 11. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 80 139 11.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . . 80 140 11.2. YANG-API-01 to RESTCONF-00 . . . . . . . . . . . . . . . . 80 141 12. Closed Issues . . . . . . . . . . . . . . . . . . . . . . . . 82 142 13. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 84 143 14. Example YANG Module . . . . . . . . . . . . . . . . . . . . . 86 144 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 91 145 15.1. Normative References . . . . . . . . . . . . . . . . . . . 91 146 15.2. Informative References . . . . . . . . . . . . . . . . . . 91 147 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 92 149 1. Introduction 151 There is a need for standard mechanisms to allow WEB applications to 152 access the configuration data, operational data, data-model specific 153 protocol operations, and notification events within a networking 154 device, in a modular and extensible manner. 156 This document describes a RESTful protocol called RESTCONF, running 157 over HTTP [RFC2616], for accessing data defined in YANG [RFC6020], 158 using datastores defined in NETCONF [RFC6241]. 160 The NETCONF protocol defines configuration datastores and a set of 161 Create, Retrieve, Update, Delete (CRUD) operations that can be used 162 to access these datastores. The YANG language defines the syntax and 163 semantics of datastore content, operational data, custom protocol 164 operations, and notification events. RESTful operations are used to 165 access the hierarchical data within a datastore. 167 A RESTful API can be created that provides CRUD operations on a 168 NETCONF datastore containing YANG-defined data. This can be done in 169 a simplified manner, compatible with HTTP and RESTful design 170 principles. Since NETCONF protocol operations are not relevant, the 171 user should not need any prior knowledge of NETCONF in order to use 172 the RESTful API. 174 Configuration data and state data are exposed as resources that can 175 be retrieved with the GET method. Resources representing 176 configuration data can be modified with the DELETE, PATCH, POST, and 177 PUT methods. Data-model specific protocol operations defined with 178 the YANG "rpc" statement can be invoked with the POST method. Data- 179 model specific notification events defined with the YANG 180 "notification" statement can be accessed (delivery method TBD). 182 1.1. Simple Subset of NETCONF Functionality 184 The framework and meta-model used for a RESTful API does not need to 185 mirror those used by the NETCONF protocol. It just needs to be 186 compatible with NETCONF. A simplified framework and protocol is 187 needed that utilizes the three NETCONF datastores (candidate, 188 running, startup), but hides the complexity of multiple datastores 189 from the client. 191 A simplified transaction model is needed that allows basic CRUD 192 operations on a hierarchy of conceptual resources. This represents a 193 limited subset of the transaction capabilities of the NETCONF 194 protocol. 196 Applications that require more complex transaction capabilities might 197 consider NETCONF instead of RESTCONF. The following transaction 198 features are not directly provided in RESTCONF: 200 o datastore locking (full or partial) 202 o candidate datastore 204 o startup datastore 206 o validate operation 208 o confirmed-commit procedure 210 It is possible that a server could expose NETCONF operations as data- 211 model specific operation resources, but that is out of scope within 212 this document. 214 The RESTful API is not intended to replace NETCONF, but rather 215 provide an additional simplified interface that follows RESTful 216 principles and is compatible with a resource-oriented device 217 abstraction. It is expected that applications that need the full 218 feature set of NETCONF such as notifications will continue to use 219 NETCONF. 221 The following figure shows the system components: 223 +-----------+ +-----------------+ 224 | WEB app | <-------> | | 225 +-----------+ HTTP | network device | 226 | | 227 +-----------+ | +-----------+ | 228 | NMS app | <-------> | | datastore | | 229 +-----------+ NETCONF | +-----------+ | 230 +-----------------+ 232 1.2. Data Model Driven API 234 RESTCONF combines the simplicity of a RESTful API over HTTP with the 235 predictability and automation potential of a schema-driven API. 237 A RESTful client using HATEOAS principles would not use any data 238 modelling language to define the application-specific content of the 239 API. The client would discover each new child resource as it 240 traverses the URIs return as Location IDs to discover the server 241 capabilities. 243 This approach has 3 significant weaknesses wrt/ control of complex 244 networking devices: 246 o inefficient performance: configuration APIs will be quite complex 247 and may require thousands of protocol messages to discover all the 248 schema information. Typically the data type information has to be 249 passed in the protocol messages, which is also wasteful overhead. 251 o no data model richness: without a data model, the schema-level 252 semantics and validation constraints are not available to the 253 application. 255 o no tool automation: API automation tools need some sort of content 256 schema to function. Such tools can automate various programming 257 and documentation tasks related to specific data models. 259 Data model modules such as YANG modules serve as an "API contract" 260 that will be honored by the server. An application designer can code 261 to the data model, knowing in advance important details about the 262 exact protocol operations and datastore content a conforming server 263 implementation will support. 265 RESTCONF provides the YANG module capability information supported by 266 the server, in case the client wants to use it. The URIs for custom 267 protocol operations and datastore content are predictable, based on 268 the YANG module definitions. Note that the YANG modules and 269 predictable URIs are optional to use by the client. They can be 270 completely ignored without any loss of protocol functionality. 272 Operational experience with CLI and SNMP indicates that operators 273 learn the 'location' of specific service or device related data and 274 do not expect such information to be arbitrary and discovered each 275 time the client opens a management session to a server. 277 1.3. Terminology 279 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 280 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 281 "OPTIONAL" in this document are to be interpreted as described in BCP 282 14, [RFC2119]. 284 1.3.1. NETCONF 286 The following terms are defined in [RFC6241]: 288 o candidate configuration datastore 290 o client 292 o configuration data 293 o datastore 295 o configuration datastore 297 o protocol operation 299 o running configuration datastore 301 o server 303 o startup configuration datastore 305 o state data 307 o user 309 1.3.2. HTTP 311 The following terms are defined in [RFC2616]: 313 o entity tag 315 o fragment 317 o header line 319 o message body 321 o method 323 o path 325 o query 327 o request URI 329 o response body 331 1.3.3. YANG 333 The following terms are defined in [RFC6020]: 335 o container 337 o data node 339 o key leaf 340 o leaf 342 o leaf-list 344 o list 346 o presence container (or P-container) 348 o RPC operation (now called protocol operation) 350 o non-presence container (or NP-container) 352 o ordered-by system 354 o ordered-by user 356 1.3.4. Terms 358 The following terms are used within this document: 360 o API resource: a resource with the media type "application/ 361 vnd.yang.api+xml" or "application/vnd.yang.api+json". API 362 resources can only be edited by the server. 364 o data resource: a resource with the media type "application/ 365 vnd.yang.data+xml" or "application/vnd.yang.data+json". Data 366 resources can be edited by clients or the server. Only YANG 367 containers and lists can be data resources. Top-level YANG 368 terminals are treated as fields within the datastore resource. 370 o datastore resource: a resource with the media type "application/ 371 vnd.yang.datastore+xml" or "application/vnd.yang.datastore+json". 372 Datastore resources can only be edited by the server. 374 o edit operation: a RESTCONF operation on a data resource using the 375 POST, PUT, PATCH, or DELETE method. 377 o event resource: a resource with the media type "application/ 378 vnd.yang.event+xml" or "application/vnd.yang.event+json". It 379 represents a conceptual system or data-model specific event that 380 is delivered within a notification message. 382 o field: a YANG terminal node within a resource. 384 o operation: the conceptual RESTCONF operation for a message, 385 derived from the HTTP method, request URI, headers, and message 386 body. 388 o operation resource: a resource with the media type "application/ 389 vnd.yang.operation+xml" or "application/vnd.yang.operation+json". 391 o patch: a generic PATCH operation on the target datastore. The 392 media type of the message body content will identity the patch 393 type in use. 395 o plain patch: a PATCH operation where the media type is 396 "application/vnd.yang.data+xml" or "application/ 397 vnd.yang.data+json". 399 o query parameter: a parameter (and its value if any), encoded 400 within the query portion of the request URI. 402 o resource: a conceptual object representing a manageable component 403 within a device. Refers to the resource itself of the resource 404 and all its fields. 406 o retrieval request: an operation using the GET or HEAD methods. 408 o target resource: the resource that is associated with a particular 409 message, identified by the "path" component of the request URI. 411 o unified datastore: A conceptual representation of the device 412 running configuration. The server will hide all NETCONF datastore 413 details for edit operations, such as the ":candidate" and 414 ":startup" capabilities. 416 o YANG Patch: a PATCH operation where the media type is 417 "application/vnd.yang.patch+xml" or "application/ 418 vnd.yang.patch+json". 420 o YANG terminal node: a YANG node representing a leaf, leaf-list, or 421 anyxml definition. 423 1.4. Overview 425 This document defines the RESTCONF protocol, a RESTful API for 426 accessing conceptual datastores containing data defined with YANG 427 language. RESTCONF provides an application framework and meta-model, 428 using HTTP methods. 430 The RESTCONF resources are accessed via a set of URIs defined in this 431 document. The set of YANG modules supported by the server will 432 determine the additional data model specific operations and top-level 433 data node resources available on the server. 435 1.4.1. Resource URI Map 437 The URI hierarchy for the RESTCONF resources consists of an entry 438 point container, 3 top-level resources, and 1 field. Refer to 439 Section 5 for details on each URI. 441 /restconf 442 /datastore 443 / (config=true or false) 444 /modules 445 /module 446 /name 447 /revision 448 /namespace 449 /feature 450 /deviation 451 /operations 452 / 453 /version (field) 455 1.4.2. RESTCONF Message Examples 457 The examples within this document use the normative YANG module 458 defined in Section 8 and the non-normative example YANG module 459 defined in Section 14. 461 This section shows some typical RESTCONF message exchanges. 463 1.4.2.1. Retrieve the Top-level API Resource 465 By default, when a resource is retrieved, any nested resources are 466 also returned, using the default encoding, which is XML. 468 The client may start by retrieving the top-level API resource, using 469 the entry point URI "/restconf". 471 GET /restconf?format=json HTTP/1.1 472 Host: example.com 473 Accept: application/vnd.yang.api+json 475 The server might respond as follows: 477 HTTP/1.1 200 OK 478 Date: Mon, 23 Apr 2012 17:01:00 GMT 479 Server: example-server 480 Content-Type: application/vnd.yang.api+json 482 { 483 "restconf": { 484 "datastore" : [ null ], 485 "modules": { 486 "module": [ 487 { 488 "name" : "example-jukebox", 489 "revision" : "2013-09-04", 490 "namespace" : "example.com" 491 } 492 ] 493 }, 494 "operations" : { 495 "play" : [ null ] 496 }, 497 "version": "1.0" 498 } 499 } 501 To request that the response content to be encoded in XML, the 502 "Accept" header can be used, as in this example request: 504 GET /restconf HTTP/1.1 505 Host: example.com 506 Accept: application/vnd.yang.api+xml 508 An alternate approach is provided using the "format" query parameter, 509 as in this example request: 511 GET /restconf?format=xml HTTP/1.1 512 Host: example.com 514 The server will return the same response either way, which might be 515 as follows : 517 HTTP/1.1 200 OK 518 Date: Mon, 23 Apr 2012 17:01:00 GMT 519 Server: example-server 520 Cache-Control: no-cache 521 Pragma: no-cache 522 Content-Type: application/vnd.yang.api+xml 523 524 525 526 527 example-jukebox 528 2013-09-04 529 example.com 530 531 532 533 534 535 1.0 536 538 Refer to Section 3.3 for details on the GET method. 540 1.4.2.2. Create New Data Resources 542 To create a new "jukebox" resource, the client might send: 544 POST /restconf/datastore HTTP/1.1 545 Host: example.com 546 Content-Type: application/vnd.yang.data+json 548 { "example-jukebox:jukebox" : [null] } 550 If the resource is created, the server might respond: 552 HTTP/1.1 201 Created 553 Date: Mon, 23 Apr 2012 17:01:00 GMT 554 Server: example-server 555 Location: http://example.com/restconf/datastore/ 556 example-jukebox:jukebox 557 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 558 ETag: b3a3e673be2 560 To create a new "artist" resource within the "library" resource, the 561 client might send the following request. 563 POST /restconf/datastore/example-jukebox:jukebox/library HTTP/1.1 564 Host: example.com 565 Content-Type: application/vnd.yang.data+json 567 { "artist" : { 568 "name" : "Foo Fighters" 569 } 570 } 572 If the resource is created, the server might respond as follows. 573 Note that the "Location" header line is wrapped for display purposes 574 only: 576 HTTP/1.1 201 Created 577 Date: Mon, 23 Apr 2012 17:02:00 GMT 578 Server: example-server 579 Location: http://example.com/restconf/datastore/ 580 example-jukebox:jukebox/library/artist/Foo%20Fighters 581 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 582 ETag: b3830f23a4c 584 To create a new "album" resource for this artist within the "jukebox" 585 resource, the client might send the following request. Note that the 586 request URI header line is wrapped for display purposes only: 588 POST /restconf/datastore/example-jukebox:jukebox/ 589 library/artist/Foo%20Fighters HTTP/1.1 590 Host: example.com 591 Content-Type: application/vnd.yang.data+json 593 { 594 "album" : { 595 "name" : "Wasting Light", 596 "genre" : "example-jukebox:alternative", 597 "year" : 2012 // note this is the wrong date 598 } 599 } 601 If the resource is created, the server might respond as follows. 602 Note that the "Location" header line is wrapped for display purposes 603 only: 605 HTTP/1.1 201 Created 606 Date: Mon, 23 Apr 2012 17:03:00 GMT 607 Server: example-server 608 Location: http://example.com/restconf/datastore/ 609 example-jukebox:jukebox/library/artist/Foo%20Fighters/ 610 album/Wasting%20Light 611 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 612 ETag: b8389233a4c 614 Refer to Section 3.4 for details on the POST method. 616 1.4.2.3. Replace an Existing Data Resource 618 Note: replacing a resource is a fairly drastic operation. The PATCH 619 method is often more appropriate. 621 The album sub-resource is replaced here for example purposes only. 622 To replace the "album" resource contents, the client might send as 623 follows. Note that the request URI header line is wrapped for 624 display purposes only: 626 PUT /restconf/datastore/example-jukebox:jukebox/ 627 library/artist/Foo%20Fighters/album/Wasting%20Light HTTP/1.1 628 Host: example.com 629 If-Match: b3830f23a4c 630 Content-Type: application/vnd.yang.data+json 632 { 633 "album" : { 634 "name" : "Wasting Light", 635 "genre" : "example-jukebox:alternative", 636 "year" : 2011 637 } 638 } 640 If the resource is updated, the server might respond: 642 HTTP/1.1 204 No Content 643 Date: Mon, 23 Apr 2012 17:04:00 GMT 644 Server: example-server 645 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 646 ETag: b27480aeda4c 648 Refer to Section 3.5 for details on the PUT method. 650 1.4.2.4. Patch an Existing Data Resource 652 To replace just the "year" field in the "album" resource (instead of 653 replacing the entire resource), the client might send a plain patch 654 as follows. Note that the request URI header line is wrapped for 655 display purposes only: 657 PATCH /restconf/datastore/example-jukebox:jukebox/ 658 library/artist/Foo%20Fighters/album/Wasting%20Light HTTP/1.1 659 Host: example.com 660 If-Match: b8389233a4c 661 Content-Type: application/vnd.yang.data+json 663 { "year" : 2011 } 665 If the field is updated, the server might respond: 667 HTTP/1.1 204 No Content 668 Date: Mon, 23 Apr 2012 17:49:30 GMT 669 Server: example-server 670 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 671 ETag: b2788923da4c 673 The XML encoding for the same request might be: 675 PATCH /restconf/datastore/example-jukebox:jukebox/ 676 library/artist/Foo%20Fighters/album/Wasting%20Light HTTP/1.1 677 Host: example.com 678 If-Match: b8389233a4c 679 Content-Type: application/vnd.yang.data+xml 681 2011 683 Refer to Section 3.6 for details on the PATCH method. 685 1.4.2.5. Delete an Existing Data Resource 687 To delete a resource such as the "album" resource, the client might 688 send: 690 DELETE /restconf/datastore/example-jukebox:jukebox/ 691 library/artist/Foo%20Fighters/album/Wasting%20Light HTTP/1.1 692 Host: example.com 694 If the resource is deleted, the server might respond: 696 HTTP/1.1 204 No Content 697 Date: Mon, 23 Apr 2012 17:49:40 GMT 698 Server: example-server 700 Refer to Section 3.7 for details on the DELETE method. 702 1.4.2.6. Delete an Optional Field Within a Data Resource 704 The DELETE method cannot be used to delete an optional field within a 705 resource. This can only be done using the PATCH method with the YANG 706 Patch media type. 708 Refer to Section 7 for details on the YANG Patch method. 710 1.4.2.7. Invoke a Data Model Specific Operation 712 To invoke a data-model specific operation via an operation resource, 713 the POST method is used. A client might send a "backup-datastore" 714 request as follows: 716 POST /restconf/operations/example-ops:backup-datastore HTTP/1.1 717 Host: example.com 719 The server might respond: 721 HTTP/1.1 204 No Content 722 Date: Mon, 23 Apr 2012 17:50:00 GMT 723 Server: example-server 725 Refer to Section 3.9 for details on using the POST method with 726 operation resources. 728 2. Framework 730 The RESTCONF protocol defines a framework that can be used to 731 implement a common API for configuration management. This section 732 describes the components of the RESTCONF framework. 734 2.1. Message Model 736 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 737 message corresponds to a single protocol method. Most messages can 738 perform a single task on a single resource, such as retrieving a 739 resource or editing a resource. The exception is the PATCH method 740 using the YANG Patch format. This allows multiple datastore edits 741 within a single message. 743 2.2. Notification Model 745 [TBD] 747 2.3. Resource Model 749 The RESTCONF protocol operates on a hierarchy of resources, starting 750 with the top-level API resource itself. Each resource represents a 751 manageable component within the device. 753 A resource can be considered a collection of conceptual data and the 754 set of allowed methods on that data. It can contain child nodes that 755 are nested resources or fields. The child resource types and methods 756 allowed on them are data-model specific. 758 A resource has its own media type identifier, represented by the 759 "Content-Type" header in the HTTP response message. A resource can 760 contain zero or more nested resources. A resource can be created and 761 deleted independently of its parent resource, as long as the parent 762 resource exists. 764 All RESTCONF resources are defined in this document except datastore 765 contents, protocol operations, and notification events. The syntax 766 and semantics for these resource types are defined with YANG 767 statements. 769 2.3.1. RESTCONF Resource Types 771 The RESTCONF protocol defines some application specific media types 772 to identify each of the available resource types. The following 773 table summarizes the purpose of each resource. 775 +-----------+--------------------------------+ 776 | Resource | Media Type | 777 +-----------+--------------------------------+ 778 | API | application/vnd.yang.api | 779 | Datastore | application/vnd.yang.datastore | 780 | Data | application/vnd.yang.data | 781 | Event | application/vnd.yang.event | 782 | Operation | application/vnd.yang.operation | 783 | Patch | application/vnd.yang.patch | 784 +-----------+--------------------------------+ 786 RESTCONF Media Types 788 These resources are described in Section 5. 790 2.3.2. Resource Discovery 792 A client SHOULD start by retrieving the top-level API resource, using 793 the entry point URI "/restconf". 795 The RESTCONF protocol does not include a resource discovery 796 mechanism. Instead, the definitions within the YANG modules 797 advertised by the server are used to construct a predictable 798 operation or data resource identifier. 800 The "depth" query parameter can be used to control how many 801 descendant levels should be included when retrieving sub-resources. 802 This parameter can be used with the GET method to discover sub- 803 resources within a particular resource. 805 Refer to Section 3.8.2 for more details on the "depth" parameter. 807 2.4. Datastore Model 809 A conceptual "unified datastore" is used to simplify resource 810 management for the client. The RESTCONF datastore is a combination 811 of the running configuration and any non-configuration data supported 812 by the device. By default only configuration data is returned by a 813 GET method on the datastore contents. 815 The underlying NETCONF datastores can be used to implement the 816 unified datastore, but the server design is not limited to the exact 817 datastore procedures defined in NETCONF. 819 The "candidate" and "startup" datastores are not visible in the 820 RESTCONF protocol. Transaction management and configuration 821 persistence are handled by the server and not controlled by the 822 client. 824 2.4.1. Content Model 826 The RESTCONF protocol operates on a conceptual datastore defined with 827 the YANG data modeling language. The server lists each YANG module 828 it supports in the "/restconf/modules/module" resource in the top- 829 level API resource type, using a structure based on the YANG module 830 capability URI format defined in RFC 6020. 832 The conceptual datastore contents, data-model-specific operations and 833 notification events are identified by this set of YANG module 834 resources. All RESTCONF content identified as either a data 835 resource, operation resource, or event resource is defined with the 836 YANG language. 838 The classification of data as configuration or non-configuration is 839 derived from the YANG "config" statement. Data retrieval with the 840 GET method can be filtered in several ways, including the "config" 841 parameter to retrieve configuration or non-configuration data. 843 Data ordering behavior is derived from the YANG "ordered-by" 844 statement. The YANG Patch operation is provided to allow list or 845 leaf-list fields to be inserted or moved in the same manner as 846 NETCONF. 848 The server is not required to maintain system ordered data in any 849 particular persistent order. The server SHOULD maintain the same 850 data ordering for system ordered data until the next reboot or 851 termination of the server. The server MUST maintain the same data 852 ordering for user ordered data until the next reboot or termination 853 of the server. 855 2.4.2. Editing Model 857 The RESTCONF datastore editing model is simple and direct, similar to 858 the behavior of the ":writable-running" capability in NETCONF. 860 Each RESTCONF edit of a datastore resource is activated upon 861 successful completion of the transaction. It is an implementation- 862 specific matter how the server accomplishes a RESTCONF edit request. 863 For example, a server which only accepts edits through a candidate 864 datastore may internally edit this datastore and perform the "commit" 865 operation automatically. 867 Applications which need more control over the editing model might 868 consider using NETCONF instead of RESTCONF. 870 2.4.2.1. Edit Operation Discovery 872 Sometimes a server does not implement every operation for every 873 resource. Sometimes data model requirements cause a node to 874 implement a subset of the edit operations. For example, a server may 875 not allow modification of a particular configuration data node after 876 the parent resource has been created. 878 The OPTIONS method can be used to identify which HTTP methods are 879 supported by the server for a particular resource. For example, if 880 the server will allow a data resource node to be created then the 881 POST method will be returned in the response. 883 2.4.2.2. Edit Collision Detection 885 Two "edit collision detection" mechanisms are provided in RESTCONF, 886 for datastore and data resources. 888 o timestamp: the last change time is maintained and the 889 "Last-Modified" and "Date" headers are returned in the response 890 for a retrieval request. The "If-Unmodified-Since" header can be 891 used in edit operation requests to cause the server to reject the 892 request if the resource has been modified since the specified 893 timestamp. 895 o entity tag: a unique opaque string is maintained and the "ETag" 896 header is returned in the response for a retrieval request. The 897 "If-Match" header can be used in edit operation requests to cause 898 the server to reject the request if the resource entity tag does 899 not match the specified value. 901 Note that the server is only required to maintain these properties 902 for a datastore resource, not for individual data resources. 904 Example: 906 In this example, the server just supports the mandatory datastore 907 last-changed timestamp. The client has previously retrieved the 908 "Last-Modified" header and has some value cached to provide in the 909 following request to replace a list entry with key value "11": 911 PATCH /restconf/datastore/example-jukebox:jukebox/ 912 library/artist/Foo%20Fighters/album/Wasting%20Light/year HTTP/1.1 913 Host: example.com 914 Accept: application/vnd.yang.data+json 915 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 916 Content-Type: application/vnd.yang.data+json 917 { "year" : "2011" } 919 In this example the datastore resource has changed since the time 920 specified in the "If-Unmodified-Since" header. The server might 921 respond: 923 HTTP/1.1 304 Not Modified 924 Date: Mon, 23 Apr 2012 19:01:00 GMT 925 Server: example-server 926 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 927 ETag: b34aed893a4c 929 2.4.3. Locking Model 931 Datastore locking is not provided by RESTCONF. An application that 932 needs to make several changes to the running configuration datastore 933 contents in sequence, without disturbance from other clients might 934 consider using the NETCONF protocol instead of RESTCONF. 936 2.4.4. Persistence Model 938 Each RESTCONF edit of a datastore resource is saved to non-volatile 939 storage in an implementation-specific matter by the server. There is 940 no guarantee that configuration changes are saved immediately, or 941 that the saved configuration is always a mirror of the running 942 configuration. 944 Applications which need more control over the persistence model might 945 consider using NETCONF instead of RESTCONF. 947 2.4.5. Defaults Model 949 NETCONF has a rather complex defaults handling model for leafs. 950 RESTCONF attempts to avoid this complexity by restricting the 951 operations that can be applied to a resource. 953 If the target of a GET method (plus "select" value) is a data node 954 that represents a leaf that has a default value, and the leaf has not 955 been given a value yet, the server MUST return the default value that 956 is in use by the server. 958 The GET method returns only descendant nodes that exist, which will 959 be determined by the server. There is no mechanism for the client to 960 ask the server for the default values of nested resources that would 961 be used for any nodes not present, but some default value is in use 962 by the server. (There is no retrieval mode like 963 "with-defaults=report-all" in NETCONF.) 964 Applications which need more control over the defaults model might 965 consider using NETCONF instead of RESTCONF. 967 2.5. Transaction Model 969 The RESTCONF protocol provides an extensible transaction framework 970 that allows a simplified transaction model that uses plain REST 971 operations to edit one resource (and sub-resources) at a time. It 972 also provides YANG Patch, which is a standard variant of the PATCH 973 method. This allows a richer set of edit operations that can be 974 applied to multiple resources at once. 976 RESTCONF does not provide a more complex transaction model that 977 allows for multiple edits to be stored in a temporary scratchpad and 978 committed all at once. 980 Applications which need more control over the transaction model might 981 consider using NETCONF instead of RESTCONF. 983 2.6. Extensibility Model 985 The RESTCONF protocol is designed to be extensible for datastore 986 content and data-model specific protocol operations. New protocol 987 operations can be added without changing the entry point if they are 988 optional and do not alter any existing operations. 990 Separate namespaces for each YANG module are used. Content encoded 991 in XML will indicate the module using the "namespace" URI value in 992 the YANG module. Content encoded in JSON will indicate the module 993 using the module name specified in the YANG module, but this is not 994 required unless multiple sibling nodes have the same YANG identifier 995 name. JSON encoding rules for module names are specified in 996 [I-D.lhotka-netmod-json]. 998 2.7. Versioning Model 1000 The version of a resource instance is identified with an entity tag, 1001 as defined by HTTP. The version identifiers in this section apply to 1002 the version of the schema definition of a resource. There are two 1003 types of schema versioning information used in the RESTCONF protocol: 1005 o the RESTCONF protocol version 1007 o data and operation resource definition versions 1009 The protocol version is identified by the string used for the well- 1010 known URI entry point "/restconf". This would be changed (e.g., 1011 "/restconf2") if non-backward compatible changes are ever needed. 1013 Minor version changes that do not break backward-compatibility will 1014 not cause the entry point to change. 1016 The API "restconf/version" resource can be used by the client to 1017 identify the exact version of the RESTCONF protocol implemented by 1018 the server. This value will include the complete RESTCONF protocol 1019 version. The "/restconf/version" resource MUST be updated every time 1020 the protocol specification is republished. 1022 The resource definition version for a data or operation resource is a 1023 date string, which is the revision date of the YANG module that 1024 defines the resource. The resource version for all other resource 1025 types is a numeric string, defined by the "/restconf/version" field. 1027 2.8. Retrieval Filtering Model 1029 There are three types of filtering for retrieval of data resources in 1030 the RESTCONF protocol. 1032 o conditional all-or-nothing: use some conditional test mechanism in 1033 the request headers and retrieve either a complete "200 OK" 1034 response if the condition is met, or a "304 Not Modified" Status- 1035 Line if the condition is not met. 1037 o data classification: request configuration or non-configuration 1038 data. 1040 o filter: request a subset of all possible descendant nodes within 1041 the target resource. The "select" query parameter can be used for 1042 this purpose. 1044 Refer to Section 5.3.2 for details on data retrieval filtering. 1046 2.9. Access Control Model 1048 The RESTCONF protocol provides no granular access control for any 1049 content except for operation and data resources. The NETCONF Access 1050 Control Model (NACM) is defined in [RFC6536]. There is a specific 1051 mapping between RESTCONF operations and NETCONF edit operations, 1052 defined in Table 1. The resource path also needs to be converted 1053 internally by the server to the corresponding YANG instance- 1054 identifier. Using this information, the server can apply the NACM 1055 access control rules to RESTCONF messages. 1057 The server MUST NOT allow any operation to any resources that the 1058 client is not authorized to access. 1060 3. Operations 1062 The RESTCONF protocol uses HTTP methods to identify the CRUD 1063 operation requested for a particular resource. The following table 1064 shows how the RESTCONF operations relate to NETCONF protocol 1065 operations: 1067 +----------+-------------------------------------+ 1068 | RESTCONF | NETCONF | 1069 +----------+-------------------------------------+ 1070 | OPTIONS | none | 1071 | HEAD | none | 1072 | GET | , | 1073 | POST | (operation="create") | 1074 | PUT | (operation="replace") | 1075 | PATCH | (operation="merge") | 1076 | DELETE | (operation="delete") | 1077 +----------+-------------------------------------+ 1079 Table 1: CRUD Methods in RESTCONF 1081 The NETCONF "remove" operation attribute is not supported by the HTTP 1082 DELETE method. The resource must exist or the DELETE method will 1083 fail. 1085 This section defines the RESTCONF protocol usage for each HTTP 1086 method. 1088 3.1. OPTIONS 1090 The OPTIONS method is sent by the client to discover which methods 1091 are supported by the server for a specific resource. It is supported 1092 for all media types. Note that implementation of this method is part 1093 of HTTP, and this section does not introduce any additional 1094 requirements. 1096 The request MUST contain a request URI that contains at least the 1097 entry point component. 1099 The server will return a "Status-Line" header containing "204 No 1100 Content". and include the "Allow" header in the response. This 1101 header will be filled in, based on the target resource media type. 1102 Other headers MAY also be included in the response. 1104 Example 1: 1106 A client might request the methods supported for a data resource 1107 called "library": 1109 OPTIONS /restconf/datastore/example-jukebox:jukebox/ 1110 library/artist HTTP/1.1 1111 Host: example.com 1113 The server might respond (for a config=true list): 1115 HTTP/1.1 204 No Content 1116 Date: Mon, 23 Apr 2012 17:01:00 GMT 1117 Server: example-server 1118 Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH,DELETE 1120 Example 2: 1122 A client might request the methods supported for a non-configuration 1123 "counters" resource within a "system" resource: 1125 OPTIONS /restconf/datastore/example-system:system/ 1126 counters HTTP/1.1 1127 Host: example.com 1129 The server might respond: 1131 HTTP/1.1 204 No Content 1132 Date: Mon, 23 Apr 2012 17:02:00 GMT 1133 Server: example-server 1134 Allow: OPTIONS,HEAD,GET 1136 Example 3: 1138 A client might request the methods supported for an operation 1139 resource called "play": 1141 OPTIONS /restconf/operations/example-jukebox:play HTTP/1.1 1142 Host: example.com 1144 The server might respond: 1146 HTTP/1.1 204 No Content 1147 Date: Mon, 23 Apr 2012 17:02:00 GMT 1148 Server: example-server 1149 Allow: POST 1151 3.2. HEAD 1153 The HEAD method is sent by the client to retrieve just the headers 1154 that would be returned for the comparable GET method, without the 1155 response body. It is supported for all resource types, except 1156 operation resources. 1158 The request MUST contain a request URI that contains at least the 1159 entry point component. 1161 The same query parameters supported by the GET method are supported 1162 by the HEAD method. For example, the "select" query parameter can be 1163 used to specify a nested resource within the target resource. 1165 The access control behavior is enforced as if the method was GET 1166 instead of HEAD. The server MUST respond the same as if the method 1167 was GET instead of HEAD, except that no response body is included. 1169 Example: 1171 The client might request the response headers for JSON representation 1172 of the "library" resource: 1174 HEAD /restconf/datastore/example-jukebox:jukebox/ 1175 library HTTP/1.1 1176 Host: example.com 1177 Accept: application/vnd.yang.data+json 1179 The server might respond: 1181 HTTP/1.1 200 OK 1182 Date: Mon, 23 Apr 2012 17:02:40 GMT 1183 Server: example-server 1184 Content-Type: application/vnd.yang.data+json 1185 Cache-Control: no-cache 1186 Pragma: no-cache 1187 ETag: a74eefc993a2b 1188 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1190 3.3. GET 1192 The GET method is sent by the client to retrieve data and meta-data 1193 for a resource. It is supported for all resource types, except 1194 operation resources. The request MUST contain a request URI that 1195 contains at least the entry point component. 1197 The following query parameters are supported by the GET method: 1199 +--------+---------+------------------------------------------------+ 1200 | Name | Section | Description | 1201 +--------+---------+------------------------------------------------+ 1202 | config | 3.8.1 | Request either configuration or | 1203 | | | non-configuration data | 1204 | depth | 3.8.2 | Control the depth of a retrieval request | 1205 | format | 3.8.3 | Request either JSON or XML content in the | 1206 | | | response | 1207 | select | 3.8.6 | Specify a nested resource within the target | 1208 | | | resource | 1209 +--------+---------+------------------------------------------------+ 1211 GET Query Parameters 1213 The server MUST NOT return any data resources for which the user does 1214 not have read privileges. 1216 If the user is not authorized to read any portion of the target 1217 resource, an error response containing a "403 Forbidden" Status-Line 1218 is returned to the client. 1220 If the user is authorized to read some but not all of the target 1221 resource, the unauthorized content is omitted from the response 1222 message body, and the authorized content is returned to the client. 1224 Example: 1226 The client might request the response headers for a JSON 1227 representation of the "library" resource: 1229 GET /restconf/datastore/example-jukebox:jukebox/ 1230 library/artist/Foo%20Fighters/album?format=json HTTP/1.1 1231 Host: example.com 1232 Accept: application/vnd.yang.api+json 1234 The server might respond: 1236 HTTP/1.1 200 OK 1237 Date: Mon, 23 Apr 2012 17:02:40 GMT 1238 Server: example-server 1239 Content-Type: application/vnd.yang.data+json 1240 Cache-Control: no-cache 1241 Pragma: no-cache 1242 ETag: a74eefc993a2b 1243 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1245 { 1246 "album" : { 1247 "name" : "Wasting Light", 1248 "genre" : "example-jukebox:alternative", 1249 "year" : 2011 1250 } 1251 } 1253 3.4. POST 1255 The POST method is sent by the client for various reasons. The 1256 server uses the target resource media type to determine how to 1257 process the request. 1259 The request MUST contain a request URI that contains a target 1260 resource which identifies one of the following resource types: 1262 +-----------+------------------------------------------------+ 1263 | Type | Description | 1264 +-----------+------------------------------------------------+ 1265 | Datastore | Create a top-level configuration data resource | 1266 | Data | Create a configuration data sub-resource | 1267 | Operation | Invoke protocol operation | 1268 +-----------+------------------------------------------------+ 1270 Resource Types that Support POST 1272 3.4.1. Create Resource Mode 1274 If the target resource type is a Datastore or Data resource, then the 1275 POST is treated as a request to create a resource or sub-resource. 1277 The following query parameters are supported by the POST method for 1278 Datastore and Data resource types. They can only be used for YANG 1279 list data nodes which are ordered by the user. 1281 +--------+---------+-----------------------------------------+ 1282 | Name | Section | Description | 1283 +--------+---------+-----------------------------------------+ 1284 | insert | 3.8.4 | Specify where to insert a resource | 1285 | point | 3.8.5 | Specify the insert point for a resource | 1286 +--------+---------+-----------------------------------------+ 1288 POST Query Parameters 1290 If the POST method succeeds, a "204 No Content" Status-Line is 1291 returned and there is no response message body. 1293 If the user is not authorized to create the target resource, an error 1294 response containing a "403 Forbidden" Status-Line is returned to the 1295 client. All other error responses are handled according to the 1296 procedures defined in Section 6. 1298 3.4.2. Invoke Operation Mode 1300 If the target resource type is an Operation resource, then the POST 1301 method is treated as a request to invoke that operation. The message 1302 body (if any) is processed as the operation input parameters. Refer 1303 to Section 5.4 for details on Operation resources. 1305 If the POST method succeeds, a "200 OK" Status-Line is returned if 1306 there is a response message body, and a "204 No Content" Status-Line 1307 is returned if there is no response message body. 1309 If the user is not authorized to invoke the target operation, an 1310 error response containing a "403 Forbidden" Status-Line is returned 1311 to the client. All other error responses are handled according to 1312 the procedures defined in Section 6. 1314 3.5. PUT 1316 The PUT method is sent by the client to replace the target resource. 1318 The request MUST contain a request URI that contains a target 1319 resource that identifies the data resource to replace. 1321 If the PUT method succeeds, a "200 OK" Status-Line is returned, and 1322 there is no response message body. 1324 If the user is not authorized to replace the target resource an error 1325 response containing a "403 Forbidden" Status-Line is returned to the 1326 client. All other error responses are handled according to the 1327 procedures defined in Section 6. 1329 3.6. PATCH 1331 The PATCH method uses the HTTP PATCH method defined in [RFC5789] to 1332 provide an extensible framework for resource patching mechanisms. 1333 Each patch type needs a unique media type. Any number of patch types 1334 can be supported by the server. There are two mandatory patch types 1335 that MUST be implemented by the server: 1337 o plain patch type: If the specified media type is "application/ 1338 vnd.yang.data", then the PATCH method is a simple merge operation 1339 on the target resource. The message body contains the XML or JSON 1340 encoded resource content that will be merged with the target 1341 resource. 1343 o YANG Patch type: If the specified media type is "application/ 1344 vnd.yang.patch", then the PATCH method is a YANG Patch formatted 1345 list of edits (see Section 7). The message body contains the XML 1346 or JSON encoded instance of the 'patch' container specified in the 1347 'ietf-restconf' YANG module (see Section 8). 1349 The PATCH method MUST be used to create or delete an optional field 1350 within an existing resource or sub-resource. 1352 If the PATCH method succeeds, a "200 OK" Status-Line is returned, and 1353 there is no response message body. 1355 If the user is not authorized to alter the target resource an error 1356 response containing a "403 Forbidden" Status-Line is returned to the 1357 client. All other error responses are handled according to the 1358 procedures defined in Section 6. 1360 3.7. DELETE 1362 The DELETE method is used to delete the target resource. 1364 If the DELETE method succeeds, a "200 OK" Status-Line is returned, 1365 and there is no response message body. 1367 If the user is not authorized to delete the target resource then an 1368 error response containing a "403 Forbidden" Status-Line is returned 1369 to the client. All other error responses are handled according to 1370 the procedures defined in Section 6. 1372 3.8. Query Parameters 1374 Each RESTCONF operation allows zero or more query parameters to be 1375 present in the request URI. Refer to Section 3 for details on the 1376 query parameters used in the definition of each operation. 1378 Query parameters can be given in any order. Each parameter can 1379 appear zero or one time. A default value may apply if the parameter 1380 is missing. 1382 This section defines all the RESTCONF query parameters. 1384 3.8.1. "config" Parameter 1386 The "config" parameter is used to specify whether configuration or 1387 non-configuration data is requested. 1389 This parameter is only supported for the GET and HEAD methods. It is 1390 also only supported if the target resource is a data resource. 1392 syntax: config= true | false 1393 default: true 1395 Example: 1397 This example request by the client would retrieve only the non- 1398 configuration data nodes that exist within the "library" resource. 1400 GET /restconf/datastore/example-jukebox:jukebox/ 1401 library?config=false HTTP/1.1 1402 Host: example.com 1403 Accept: application/vnd.yang.data+json 1405 The server might respond: 1407 HTTP/1.1 200 OK 1408 Date: Mon, 23 Apr 2012 17:01:30 GMT 1409 Server: example-server 1410 Cache-Control: no-cache 1411 Pragma: no-cache 1412 Content-Type: application/vnd.yang.data+json 1414 { 1415 "library" : { 1416 "artist-count" : 42, 1417 "album-count" : 59, 1418 "song-count" : 374 1419 } 1420 } 1422 3.8.2. "depth" Parameter 1424 The "depth" parameter is used to specify the number of nest levels 1425 returned in a response for a GET method. A nest-level consists of 1426 the target resource and any child nodes which are contained within 1427 the target resource node. 1429 The start level is determined by the target resource for the 1430 operation. 1432 syntax: depth= | unbounded 1433 default: unbounded 1435 Example: 1437 This example operation would retrieve 2 levels of configuration data 1438 nodes that exist within the top-level "jukebox" resource. 1440 GET /restconf/datastore/example-jukebox:jukebox 1441 ?depth=2 HTTP/1.1 1442 Host: example.com 1443 Accept: application/vnd.yang.data+json 1445 The server might respond: 1447 HTTP/1.1 200 OK 1448 Date: Mon, 23 Apr 2012 17:11:30 GMT 1449 Server: example-server 1450 Cache-Control: no-cache 1451 Pragma: no-cache 1452 Content-Type: application/vnd.yang.data+json 1454 { 1455 "jukebox" : { 1456 "library" : { 1457 "artist" : { 1458 "name" : "Foo Fighters" 1459 } 1460 }, 1461 "player" : { 1462 "gap" : 0.5 1463 } 1464 } 1465 } 1467 By default, the server will include all sub-trees within a retrieved 1468 resource, which is the same resource type. Only only level of sub- 1469 resources with a different media type than the target resource will 1470 be returned. 1472 For example, if the client retrieves the "application/vnd.yang.api" 1473 resource type, then the node for the datastore resource is returned 1474 as an empty node, because all its child nodes are data resources. 1475 The entire contents of the datastore are not returned in this case. 1476 The operation resources also are returned as empty nodes (e.g. "play" 1477 operation). 1479 Request URL: 1481 GET /restconf HTTP/1.1 1483 Response: 1485 { 1486 "restconf": { 1487 "datastore" : [ null ], 1488 "modules": { 1489 "module": [ 1490 { 1491 "name" : "example-jukebox", 1492 "revision" : "2013-09-04", 1493 "namespace" : "example.com" 1494 } 1495 ] 1496 }, 1497 "operations" : { 1498 "play" : [ null ] 1499 }, 1500 "version": "1.0" 1501 } 1502 } 1504 3.8.3. "format" Parameter 1506 The "format" parameter is used to specify the format of any content 1507 returned in the response. Note that this parameter MAY be used 1508 instead of the "Accept" header to identify the format desired in the 1509 response. 1511 The "format" parameter is only supported for the GET and HEAD 1512 methods. It is supported for all RESTCONF media types. 1514 syntax: format= xml | json 1515 default: Accept header, then xml 1517 If the "format" parameter is present, then it overrides the Accept 1518 header, if present. If neither the Accept header or the "format" 1519 parameter are present, then the default is XML. 1521 Examples: 1523 GET /restconf/datastore/example-routing:routing HTTP/1.1 1524 Host: example.com 1525 Accept: application/vnd.yang.data+json 1527 This example request would retrieve only the configuration data nodes 1528 that exist within the top-level "routing" resource, and retrieve them 1529 in JSON encoding. 1531 GET /restconf/datastore/example-routing:routing 1532 ?format=json HTTP/1.1 1534 Host: example.com 1536 This example request would retrieve only the configuration data nodes 1537 that exist within the top-level "routing" resource, and retrieve them 1538 in JSON encoding. 1540 3.8.4. "insert" Parameter 1542 The "insert" parameter is used to specify how a resource should be 1543 inserted within a user-ordered list. 1545 This parameter is only supported for the POST method. It is also 1546 only supported if the target resource is a data resource, and that 1547 data represents a YANG list that is ordered by the user, not the 1548 system. 1550 If the values "before" or "after" are used, then a "point" parameter 1551 for the insertion parameter MUST also be present. 1553 syntax: insert= first | last | before | after 1554 default: last 1556 Example: 1558 Request from client: 1560 PATCH /restconf/datastore/example-jukebox:jukebox/ 1561 playlist/Foo-One?insert=first HTTP/1.1 1562 Host: example.com 1563 Content-Type: application/vnd.yang.data+json 1565 { 1566 "song" : { 1567 "index" : 1, 1568 "id" : "/example-jukebox:jukebox/library/artist/ 1569 Foo%20Fighters/album/Wasting%20Light/song/Rope" 1570 } 1571 } 1573 Response from server: 1575 HTTP/1.1 201 Created 1576 Date: Mon, 23 Apr 2012 13:01:20 GMT 1577 Server: example-server 1578 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1579 Location: http://example.com/restconf/datastore/ 1580 example-jukebox:jukebox/playlist/Foo-One/song/1 1581 ETag: eeeada438af 1583 3.8.5. "point" Parameter 1585 The "point" parameter is used to specify the insertion point for a 1586 data resource that is being created or moved within a user ordered 1587 list. It is ignored unless the "insert" query parameter is also 1588 present, and has the value "before" or "after". 1590 This parameter contains the instance identifier of the resource to be 1591 used as the insertion point for a POST method. It is encoded 1592 according to the rules defined in Section 5.3.1. There is no default 1593 for this parameter. 1595 syntax: point= 1597 Example: 1599 In this example, the client is inserting a new "song" resource within 1600 an "album" resource after another song. The request URI is split for 1601 display purposes only. 1603 Request from client: 1605 POST /restconf/datastore/example-jukebox:jukebox/ 1606 library/artist/Foo%20Fighters/album/Wasting%20Light?insert=after 1607 &point=/restconf/datastore/example-jukebox:jukebox/ 1608 library/artist/Foo%20Fighters/album/Wasting%20Light/song/ 1609 Bridge%20Burning HTTP/1.1 1610 Host: example.com 1611 Content-Type: application/vnd.yang.data+json 1613 { 1614 "song" : { 1615 "name" : "Rope", 1616 "location" : "/media/rope.mp3", 1617 "format" : "MP3", 1618 "length" : 259 1619 } 1620 } 1622 Response from server: 1624 HTTP/1.1 204 No Content 1625 Date: Mon, 23 Apr 2012 13:01:20 GMT 1626 Server: example-server 1627 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1628 ETag: abcada438af 1630 3.8.6. "select" Parameter 1632 The "select" query parameter is used to specify an expression which 1633 can represent a subset of all data nodes within the target resource. 1634 It contains a relative path expression, using the target resource as 1635 the context node. 1637 It is supported for all resource types except operation resources. 1638 The contents are encoded according to the "api-select" rule defined 1639 in Section 5.3.1. This parameter is only allowed for GET and HEAD 1640 methods. 1642 [FIXME: the syntax of the select string is still TBD; XPath, schema- 1643 identifier, regular expressions, something else; Perhaps add 1644 parameter "xselect" for XPath and this param is limited to a path- 1645 expr.] 1647 In this example the client is retrieving the API version field from 1648 the server in JSON format: 1650 GET /restconf?select=version&format=json HTTP/1.1 1651 Host: example.com 1652 Accept: application/vnd.yang.api+json 1654 The server might respond as follows. 1656 HTTP/1.1 200 OK 1657 Date: Mon, 23 Apr 2012 17:01:00 GMT 1658 Server: example-server 1659 Cache-Control: no-cache 1660 Pragma: no-cache 1661 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 1662 Content-Type: application/vnd.yang.api+json 1664 { "version": "1.0" } 1666 3.9. Protocol Operations 1668 The RESTCONF protocol allows data-model specific protocol operations 1669 to be invoked using the POST method. The media type "application/ 1670 vnd.yang.operation+xml" or "application/vnd.yang.operation+json" MUST 1671 be used in the "Content-Type" line in the message header. 1673 Data model specific operations are supported. The syntax and 1674 semantics of these operations exactly correspond to the YANG "rpc" 1675 statement definition for the operation. 1677 Refer to Section 5.4 for details on operation resources. 1679 4. Messages 1681 This section describes the messages that are used in the RESTCONF 1682 protocol. 1684 4.1. Request URI Structure 1686 Resources are represented with URIs following the structure for 1687 generic URIs in [RFC3986]. 1689 A RESTCONF operation is derived from the HTTP method and the request 1690 URI, using the following conceptual fields: 1692 /restconf/?# 1694 ^ ^ ^ ^ ^ 1695 | | | | | 1696 method entry resource query fragment 1698 M M O O I 1700 M=mandatory, O=optional, I=ignored 1702 replaced by client with real values 1704 o method: the HTTP method identifying the RESTCONF operation 1705 requested by the client, to act upon the target resource specified 1706 in the request URI. RESTCONF operation details are described in 1707 Section 3. 1709 o entry: the well-known RESTCONF entry point ("/restconf"). 1711 o resource: the path expression identifying the resource that is 1712 being accessed by the operation. If this field is not present, 1713 then the target resource is the API itself, represented by the 1714 media type "application/vnd.yang.api". 1716 o query: the set of parameters associated with the RESTCONF message. 1717 These have the familiar form of "name=value" pairs. There is a 1718 specific set of parameters defined, although the server MAY choose 1719 to support additional parameters not defined in this document. 1721 o fragment: This field is not used by the RESTCONF protocol. 1723 The client SHOULD NOT assume the final structure of a URI path for a 1724 resource. Instead, existing resources can be discovered with the GET 1725 method. When new resources are created by the client, a "Location" 1726 header is returned, which identifies the path of the newly created 1727 resource. The client MUST use this exact path identifier to access 1728 the resource once it has been created. 1730 The "target" of an operation is a resource. The "path" field in the 1731 request URI represents the target resource for the operation. 1733 4.2. Message Headers 1735 There are several HTTP header lines utilized in RESTCONF messages. 1736 Messages are not limited to the HTTP headers listed in this section. 1738 HTTP defines which header lines are required for particular 1739 circumstances. Refer to each operation definition section in 1740 Section 3 for examples on how particular headers are used. 1742 There are some request headers that are used within RESTCONF, usually 1743 applied to data resources. The following tables summarize the 1744 headers most relevant in RESTCONF message requests: 1746 +---------------------+---------------------------------------------+ 1747 | Name | Description | 1748 +---------------------+---------------------------------------------+ 1749 | Accept | Response Content-Types that are acceptable | 1750 | Content-Type | The media type of the request body | 1751 | Host | The host address of the server | 1752 | If-Match | Only perform the action if the entity | 1753 | | matches ETag | 1754 | If-Modified-Since | Only perform the action if modified since | 1755 | | time | 1756 | If-Unmodified-Since | Only perform the action if un-modified | 1757 | | since time | 1758 +---------------------+---------------------------------------------+ 1760 RESTCONF Request Headers 1762 The following tables summarize the headers most relevant in RESTCONF 1763 message responses: 1765 +---------------+---------------------------------------------------+ 1766 | Name | Description | 1767 +---------------+---------------------------------------------------+ 1768 | Allow | Valid actions when 405 error returned | 1769 | Content-Type | The media type of the response body | 1770 | Date | The date and time the message was sent | 1771 | ETag | An identifier for a specific version of a | 1772 | | resource | 1773 | Last-Modified | The last modified date and time of a resource | 1774 | Location | The resource identifier for a newly created | 1775 | | resource | 1776 +---------------+---------------------------------------------------+ 1778 RESTCONF Response Headers 1780 4.3. Message Encoding 1782 RESTCONF messages are encoded in HTTP according to RFC 2616. The 1783 "utf-8" character set is used for all messages. RESTCONF message 1784 content is sent in the HTTP message body. 1786 Content is encoded in either JSON or XML format. 1788 XML encoding rules for data nodes are defined in [RFC6020]. The same 1789 encoding rules are used for all XML content. 1791 JSON encoding rules are defined in [I-D.lhotka-netmod-json]. Plain 1792 JSON cannot be used because special encoding rules are needed to 1793 handle multiple module namespaces and provide consistent data type 1794 processing. 1796 Request input content encoding format is identified with the Content- 1797 Type header. This field MUST be present if a message body is sent by 1798 the client. 1800 Response output content encoding format is identified with the Accept 1801 header, the "format" query parameter, or if neither is specified, the 1802 request input encoding format is used. If there was no request 1803 input, then the default output encoding is XML. File extensions 1804 encoded in the request are not used to identify format encoding. 1806 4.4. RESTCONF Meta-Data 1808 The RESTCONF protocol needs to retrieve the same meta-data that is 1809 used in the NETCONF protocol. Information about default leafs, last- 1810 modified timestamps, etc. are commonly used to annotate 1811 representations of the datastore contents. This meta-data is not 1812 defined in the YANG schema because it applies to the datastore, and 1813 is common across all data nodes. 1815 This information is encoded as attributes in XML, but JSON does not 1816 have a standard way of attaching non-schema defined meta-data to a 1817 resource or field. 1819 4.4.1. JSON Encoding of RESTCONF Meta-Data 1821 The YANG to JSON mapping [I-D.lhotka-netmod-json] does not support 1822 attributes because YANG does not support meta-data in data node 1823 definitions. This section specifies how RESTCONF meta-data is 1824 encoded in JSON. 1826 Only simple meta-data is supported: 1828 o A meta-data instance can appear 0 or 1 times for a particular data 1829 node 1831 o A meta-data instance associated with a resource is encoded as if 1832 it were a YANG leaf of type "string", according to the encoding 1833 rules in [I-D.lhotka-netmod-json], except the identifier is 1834 prepended with a "@" (%40) character. 1836 o A meta-data instance associated with a field within a resource is 1837 encoded as if it were a container for the meta-data values and the 1838 field value in its native encoding. It is encoded according to 1839 the rules in [I-D.lhotka-netmod-json], except the meta-data 1840 identifiers are prepended with a "@" (%40) character. The field 1841 name/value pair is repeated inside this container, which contains 1842 the actual value of the field. 1844 Examples: 1846 Meta-data: 1848 enabled= 1849 owner= 1851 YANG example: 1853 container top { 1854 leaf A { 1855 type int32; 1856 } 1857 leaf B { 1858 type boolean; 1859 } 1860 } 1862 The client is retrieving the "top" data resource, and the server is 1863 including datastore meta-data. Note that a query parameter to 1864 request or suppress specific meta-data is not provided in RESTCONF. 1866 GET /restconf/datastore/example:top HTTP/1.1 1867 Host: example.com 1868 Accept: application/vnd.yang.api+json 1870 The server might respond as follows: 1872 HTTP/1.1 200 OK 1873 Date: Mon, 23 Apr 2012 17:01:00 GMT 1874 Server: example-server 1875 Content-Type: application/vnd.yang.api+json 1877 { 1878 "top": { 1879 "@enabled" : "true", 1880 "@owner" : "fred", 1881 "A" : { 1882 "@enabled" : "true", 1883 "A" : 42 1884 }, 1885 "B" : { 1886 "@enabled" : "false", 1887 "B" : true 1888 } 1889 } 1890 } 1892 4.5. Return Status 1894 Each message represents some sort of resource access. An HTTP 1895 "Status-Line" header line is returned for each request. If a 4xx or 1896 5xx range status code is returned in the Status-Line, then the error 1897 information will be returned in the response, according to the format 1898 defined in Section 6.1. 1900 4.6. Message Caching 1902 Since the datastore contents change at unpredictable times, responses 1903 from a RESTCONF server generally SHOULD NOT be cached. 1905 The server SHOULD include a "Cache-Control" header in every response 1906 that specifies whether the response should be cached. A "Pragma" 1907 header specifying "no-cache" MAY also be sent in case the 1908 "Cache-Control" header is not supported. 1910 Instead of using HTTP caching, the client SHOULD track the "ETag" 1911 and/or "Last-Modified" headers returned by the server for the 1912 datastore resource (or data resource if the server supports it). A 1913 retrieval request for a resource can include headers such as 1914 "If-None-Match" or "If-Modified-Since" which will cause the server to 1915 return a "304 Not Modified" Status-Line if the resource has not 1916 changed. The client MAY use the HEAD method to retrieve just the 1917 message headers, which SHOULD include the "ETag" and "Last-Modified" 1918 headers, if this meta-data is maintained for the target resource. 1920 5. Resources 1922 The resources used in the RESTCONF protocol are identified by the 1923 "path" component in the request URI. Each operation is performed on 1924 a target resource. 1926 5.1. API Resource (/restconf) 1928 The API resource contains the state and access points for the 1929 RESTCONF features. It is the top-level resource and has the media 1930 type "application/vnd.yang.api+xml" or "application/ 1931 vnd.yang.api+json". It is accessible through the well-known relative 1932 URI "/restconf". 1934 The "restconf" container definition in the "ietf-restconf" module 1935 defined in Section 8 is used to specify the structure and syntax of 1936 the conceptual fields and sub-resources within the API resource. 1938 The "restconf" entry point container, and all fields and sub- 1939 resources with the same resource type, are defined in the namespace 1940 of the "ietf-restconf" module. 1942 There is one mandatory field "version" that identifies the specific 1943 version of the RESTCONF protocol implemented by the server: 1945 o The same server-wide response MUST be returned each time this 1946 field is retrieved. 1948 o It is assigned by the server when the server is started. 1950 o The server MUST return the value "1.0" for this version of the 1951 RESTCONF protocol. 1953 o This field is encoded with the rules for an "enumeration" data 1954 type, using the "version" leaf definition in Section 8. 1956 This resource has the following child resources: 1958 +----------------+--------------------------------+ 1959 | Child Resource | Description | 1960 +----------------+--------------------------------+ 1961 | datastore | Link to "datastore" resource | 1962 | modules | YANG module capability URIs | 1963 | operations | Data-model specific operations | 1964 +----------------+--------------------------------+ 1966 RESTCONF Resources 1968 5.1.1. /restconf/datastore 1970 This mandatory resource represents the running configuration 1971 datastore and any non-configuration data available. It may be 1972 retrieved and edited directly. It cannot be created or deleted by 1973 the client. This resource type is defined in Section 5.2. 1975 5.1.2. /restconf/modules 1977 This mandatory resource contains the identifiers for the YANG data 1978 model modules supported by the server. 1980 The server MUST maintain a last-modified timestamp for this resource, 1981 and return the "Last-Modified" header when this resource is retrieved 1982 with the GET or HEAD methods. 1984 The server SHOULD maintain an entity-tag for this resource, and 1985 return the "ETag" header when this resource is retrieved with the GET 1986 or HEAD methods. 1988 5.1.2.1. /restconf/modules/module 1990 This mandatory resource contains one URI string for each YANG data 1991 model module supported by the server. There MUST be an instance of 1992 this resource for every YANG module that is accessible via an 1993 operation resource or a data resource. 1995 The contents of the "module" resource are defined in the "module" 1996 YANG list statement in Section 8. 1998 The server MAY maintain a last-modified timestamp for each instance 1999 of this resource, and return the "Last-Modified" header when this 2000 resource is retrieved with the GET or HEAD methods. If not supported 2001 then the timestamp for the parent "modules" resource MAY be used 2002 instead. 2004 The server MAY maintain an entity-tag for each instance of this 2005 resource, and return the "ETag" header when this resource is 2006 retrieved with the GET or HEAD methods. If not supported then the 2007 timestamp for the parent "modules" resource MAY be used instead. 2009 There are additional encoding requirements for this resource. The 2010 URI MUST follow the YANG module capability URI formatting defined in 2011 section 5.6.4 of [RFC6020]. 2013 5.1.2.2. Retrieval Example 2015 In this example the client is retrieving the modules resource from 2016 the server in JSON format: 2018 GET /restconf/modules&format=json HTTP/1.1 2019 Host: example.com 2020 Accept: application/vnd.yang.api+json 2022 The server might respond as follows. 2024 HTTP/1.1 200 OK 2025 Date: Mon, 23 Apr 2012 17:01:00 GMT 2026 Server: example-server 2027 Cache-Control: no-cache 2028 Pragma: no-cache 2029 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 2030 Content-Type: application/vnd.yang.api+json 2032 { 2033 "modules": { 2034 "module": [ 2035 { 2036 "name" : "foo", 2037 "revision" : "2012-01-02", 2038 "namespace" : "http://example.com/ns/foo", 2039 "feature" : [ "feature1", "feature2" ] 2040 }, 2041 { 2042 "name" : "foo-types", 2043 "revision" : "2012-01-05", 2044 "namespace" : "http://example.com/ns/foo-types" 2045 }, 2046 { 2047 "name" : "bar", 2048 "revision" : "2012-11-05", 2049 "namespace" : "http://example.com/ns/bar", 2050 "feature" : [ "bar-ext" ] 2051 } 2052 ] 2053 } 2054 } 2056 5.1.3. /restconf/operations 2058 This optional resource provides access to the data-model specific 2059 protocol operations supported by the server. The server MAY omit 2060 this resource if no data-model specific operations are advertised. 2062 Any data-model specific operations defined in the YANG modules 2063 advertised by the server MAY be available as child nodes of this 2064 resource. 2066 5.2. Datastore Resource 2068 A datastore resource represents the conceptual root of a tree of data 2069 resources. 2071 The server MUST maintain a last-modified timestamp for this resource, 2072 and return the "Last-Modified" header when this resource is retrieved 2073 with the GET or HEAD methods. Only changes to configuration data 2074 resources within the datastore affect this timestamp. 2076 The server SHOULD maintain a resource entity tag for this resource, 2077 and return the "ETag" header when this resource is retrieved with the 2078 GET or HEAD methods. The resource entity tag SHOULD be changed to a 2079 new previously unused value if changes to any configuration data 2080 resources within the datastore are made. 2082 A datastore resource can be retrieved with the GET method, to 2083 retrieve either configuration data resources or non-configuration 2084 data resources within the datastore. The "config" query parameter is 2085 used to choose between them. Refer to Section 3.8.1 for more 2086 details. 2088 The depth of the subtrees returned in retrieval operations can be 2089 controlled with the "depth" query parameter. The number of nest 2090 levels, starting at the target resource, can be specified, or an 2091 unlimited number can be returned. Refer to Section 3.8.2 for more 2092 details. 2094 [FIXME: not clear if top-level YANG data nodes MUST be containers or 2095 lists. 2097 A datastore resource can only be written directly with the PATCH 2098 method. Only the configuration data resources within the datastore 2099 resource can be edited directly with all methods.] 2101 5.3. Data Resource 2103 A data resource represents a YANG data node that is a descendant node 2104 of a datastore resource. Only YANG container and list data node 2105 types are considered to represent data resources. Other YANG data 2106 nodes are considered to be fields within their parent resource. 2108 For configuration data resources, the server MAY maintain a last- 2109 modified timestamp for the resource, and return the "Last-Modified" 2110 header when it is retrieved with the GET or HEAD methods. 2112 For configuration data resources, the server MAY maintain a resource 2113 entity tag for the resource, and return the "ETag" header when it is 2114 retrieved as the target resource with the GET or HEAD methods. The 2115 resource entity tag SHOULD be changed to a new previously unused 2116 value if changes to the resource or any configuration resource within 2117 the resource is altered. 2119 A data resource can be retrieved with the GET method, to retrieve 2120 either configuration data resources or non-configuration data 2121 resources within the target resource. The "config" query parameter 2122 is used to choose between them. Refer to Section 3.8.1 for more 2123 details. 2125 The depth of the subtrees returned in retrieval operations can be 2126 controlled with the "depth" query parameter. The number of nest 2127 levels, starting at the target resource, can be specified, or an 2128 unlimited number can be returned. Refer to Section 3.8.2 for more 2129 details. 2131 A configuration data resource can be altered by the client with some 2132 of all of the edit operations, depending on the target resource and 2133 the specific operation. Refer to Section 3 for more details on edit 2134 operations. 2136 5.3.1. Encoding YANG Instance Identifiers in the Request URI 2138 In YANG, data nodes are named with an absolute XPath expression, from 2139 the document root to the target resource. In RESTCONF, URL friendly 2140 path expressions are used instead. 2142 The YANG "instance-identifier" (i-i) data type is represented in 2143 RESTCONF with the path expression format defined in this section. 2145 +-------+-------------------------------------------+ 2146 | Name | Comments | 2147 +-------+-------------------------------------------+ 2148 | point | Insertion point is always a full i-i | 2149 | path | Request URI path is a full or partial i-i | 2150 +-------+-------------------------------------------+ 2152 RESTCONF instance-identifier Type Conversion 2154 The "path" component of the request URI contains the absolute path 2155 expression that identifies the target resource. The "select" query 2156 parameter is used to optionally identify the requested data nodes 2157 within the target resource to be retrieved in a GET method. 2159 A predictable location for a data resource is important, since 2160 applications will code to the YANG data model module, which uses 2161 static naming and defines an absolute path location for all data 2162 nodes. 2164 A RESTCONF data resource identifier is not an XPath expression. It 2165 is encoded from left to right, starting with the top-level data node, 2166 according to the "api-path" rule in Section 5.3.1.1. The node name 2167 of each ancestor of the target resource node is encoded in order, 2168 ending with the node name for the target resource. 2170 If the "select" is present, it is encoded, starting with a child node 2171 of the target resource, according to the "api-select" rule defined in 2172 Section 5.3.1.1. 2174 If a data node in the path expression is a YANG list node, then the 2175 key values for the list (if any) are encoded according to the 2176 "key-value" rule. If the list node is the target resource, then the 2177 key values MAY be omitted, according to the operation. For example, 2178 the POST method to create a new data resource for a list node does 2179 not allow the key values to be present in the request URI. 2181 The key leaf values for a data resource representing a YANG list MUST 2182 be encoded as follows: 2184 o The value of each leaf identified in the "key" statement is 2185 encoded in order. 2187 o All the components in the "key" statement MUST be encoded. 2188 Partial instance identifiers are not supported. 2190 o Each value is encoded using the "key-value" rule in 2191 Section 5.3.1.1, according to the encoding rules for the data type 2192 of the key leaf. 2194 o An empty string can be a valid key value (e.g., "/top/list/key1// 2195 key3"). 2197 o The "/" character MUST be URL-encoded (i.e., "%2F"). 2199 o All whitespace MUST be URL-encoded. 2201 o A "null" value is not allowed since the "empty" data type is not 2202 allowed for key leafs. 2204 o The XML encoding is defined in [RFC6020]. 2206 o The JSON encoding is defined in [I-D.lhotka-netmod-json]. 2208 o The entire "key-value" MUST be properly URL-encoded, according to 2209 the rules defined in [RFC3986]. 2211 o resource URI values returned in Location headers for data 2212 resources SHOULD identify the module name, even if there are no 2213 conflicting local names when the resource is created. This 2214 insures the correct resource will be identified even if the server 2215 loads a new module that the old client does not know about. 2217 Examples: 2219 [ lines wrapped for display purposes only ] 2221 /restconf/datastore/example-jukebox:jukebox/library/ 2222 artist/Beatles&select=album 2224 /restconf/datastore/example-list:newlist/ 2225 17&select=nextlist/22/44/acme-list-ext:ext-leaf 2227 /restconf/datastore/example-list:somelist/ 2228 fred%20and%20wilma 2230 /restconf/datastore/example-list:somelist/ 2231 fred%20and%20wilma/address 2233 5.3.1.1. ABNF For Data Resource Identifiers 2235 The following ABNF syntax is used to construct RESTCONF path 2236 identifiers: 2238 api-path = "/" api-identifier 2239 0*("/" (api-identifier | key-value )) 2241 [FIXME: the syntax for the select string is still TBD] 2242 api-select = api-identifier 2243 0*("/" (api-identifier | key-value )) 2245 api-identifier = [module-name ":"] identifier 2247 module-name = identifier 2249 key-value = string 2251 ;; An identifier MUST NOT start with 2252 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 2253 identifier = (ALPHA / "_") 2254 *(ALPHA / DIGIT / "_" / "-" / ".") 2256 string = 2258 5.3.2. Data Resource Retrieval 2260 There are three types of filtering for retrieval of data resources. 2261 This section defines each mode. 2263 5.3.2.1. Conditional Retrieval 2265 The HTTP headers (such as "If-Modified-Since" and "If-Match") can by 2266 used in for a request message for a GET method to check a condition 2267 within the server state, such as the last time the datastore resource 2268 was modified, or the resource entity tag of the target resource. 2270 If the condition is met according to the header definition, a "200 2271 OK" Status-Line and the data requested is returned in the response 2272 message. If the condition is not met, a "304 Not Modified" Status- 2273 Line is returned in response message instead. 2275 5.3.2.2. Data Classification Retrieval 2277 The "config" query parameter can be used with the GET method to 2278 specify whether configuration or non-configuration data is requested. 2279 Refer to Section 3.8.1 for more details on the "config" query 2280 parameter. 2282 5.3.2.3. Filtered Retrieval 2284 The "select" query parameter is used to specify a filter that should 2285 be applied to the target resource to request a subset of all possible 2286 descendant nodes within the target resource. 2288 The format of the "select" parameter string is defined in 2289 Section 3.8.6. The set of nodes selected by the filter expression is 2290 applied to each context node identified by the target resource. 2292 5.4. Operation Resource 2294 An operation resource represents an protocol operation defined with 2295 the YANG "rpc" statement. 2297 All operation resources share the same module namespace as any top- 2298 level data resources, so the name of an operation resource cannot 2299 conflict with the name of a top-level data resource defined within 2300 the same module. 2302 If 2 different YANG modules define the same "rpc" identifier, then 2303 the module name MUST be used in the request URI. For example, if 2304 "module-A" and "module-B" both defined a "reset" operation, then 2305 invoking the operation from "module-A" would be requested as follows: 2307 POST /restconf/operations/module-A:reset HTTP/1.1 2308 Server example.com 2310 Any usage of an operation resource from the same module, with the 2311 same name, refers to the same "rpc" statement definition. This 2312 behavior can be used to design protocol operations that perform the 2313 same general function on different resource types. 2315 If the "rpc" statement has an "input" section, then a message body 2316 MAY be sent by the client in the request, otherwise the request 2317 message MUST NOT include a message body. If the "rpc" statement has 2318 an "output" section, then a message body MAY be sent by the server in 2319 the response. Otherwise the server MUST NOT include a message body 2320 in the response message, and MUST send a "204 No Content" Status-Line 2321 instead. 2323 5.4.1. Encoding Operation Input Parameters 2325 If the "rpc" statement has an "input" section, then the "input" node 2326 is provided in the message body, corresponding to the YANG data 2327 definition statements within the "input" section. 2329 Example: 2331 The following YANG definition is used for the examples in this 2332 section. 2334 rpc reboot { 2335 input { 2336 leaf delay { 2337 units seconds; 2338 type uint32; 2339 default 0; 2340 } 2341 leaf message { type string; } 2342 leaf language { type string; } 2343 } 2344 } 2346 The client might send the following POST request message: 2348 POST /restconf/datastore/operations/ 2349 example-ops:reboot HTTP/1.1 2350 Host: example.com 2351 Content-Type: application/vnd.yang.data+json 2353 { 2354 "input" : { 2355 "delay" : 600, 2356 "message" : "Going down for system maintenance", 2357 "language" : "en-US" 2358 } 2359 } 2361 The server might respond: 2363 HTTP/1.1 204 No Content 2364 Date: Mon, 25 Apr 2012 11:01:00 GMT 2365 Server: example-server 2367 5.4.2. Encoding Operation Output Parameters 2369 If the "rpc" statement has an "output" section, then the "output" 2370 node is provided in the message body, corresponding to the YANG data 2371 definition statements within the "output" section. 2373 Example: 2375 The following YANG definition is used for the examples in this 2376 section. 2378 rpc get-reboot-info { 2379 output { 2380 leaf reboot-time { 2381 units seconds; 2382 type uint32; 2383 } 2384 leaf message { type string; } 2385 leaf language { type string; } 2386 } 2387 } 2389 The client might send the following POST request message: 2391 POST /restconf/datastore/operations/example-ops:get-reboot-info 2392 HTTP/1.1 2393 Host: example.com 2394 Content-Type: application/vnd.yang.data+json 2396 The server might respond: 2398 HTTP/1.1 200 OK 2399 Date: Mon, 25 Apr 2012 11:10:30 GMT 2400 Server: example-server 2402 { 2403 "output" : { 2404 "reboot-time" : 30, 2405 "message" : "Going down for system maintenance", 2406 "language" : "en-US" 2407 } 2408 } 2410 5.5. Event Resource 2412 [TBD] 2414 6. Error Reporting 2416 HTTP Status-Lines are used to report success or failure for RESTCONF 2417 operations. The element returned in NETCONF error 2418 responses contains some useful information. This error information 2419 is adapted for use in RESTCONF, and error information is returned for 2420 "4xx" class of status codes. 2422 The following table summarizes the return status codes used 2423 specifically by RESTCONF operations: 2425 +---------------------------+---------------------------------------+ 2426 | Status-Line | Description | 2427 +---------------------------+---------------------------------------+ 2428 | 100 Continue | POST accepted, 201 should follow | 2429 | 200 OK | Success with response body | 2430 | 201 Created | POST to create a resource success | 2431 | 202 Accepted | POST to create a resource accepted | 2432 | 204 No Content | Success without response body | 2433 | 304 Not Modified | Conditional operation not done | 2434 | 400 Bad Request | Invalid request message | 2435 | 403 Forbidden | Access to resource denied | 2436 | 404 Not Found | Resource target or resource node not | 2437 | | found | 2438 | 405 Method Not Allowed | Method not allowed for target | 2439 | | resource | 2440 | 409 Conflict | Resource or lock in use | 2441 | 413 Request Entity Too | too-big error | 2442 | Large | | 2443 | 414 Request-URI Too Large | too-big error | 2444 | 415 Unsupported Media | non RESTCONF media type | 2445 | Type | | 2446 | 500 Internal Server Error | operation-failed | 2447 | 501 Not Implemented | unknown-operation | 2448 | 503 Service Unavailable | Recoverable server error | 2449 +---------------------------+---------------------------------------+ 2451 HTTP Status Codes used in RESTCONF 2453 Since an operation resource is defined with a YANG "rpc" statement, a 2454 mapping between the NETCONF value and the HTTP status 2455 code is needed. The specific error condition and response code to 2456 use are data-model specific and might be contained in the YANG 2457 "description" statement for the "rpc" statement. 2459 +-------------------------+-------------+ 2460 | | status code | 2461 +-------------------------+-------------+ 2462 | in-use | 409 | 2463 | invalid-value | 400 | 2464 | too-big | 413 | 2465 | missing-attribute | 400 | 2466 | bad-attribute | 400 | 2467 | unknown-attribute | 400 | 2468 | bad-element | 400 | 2469 | unknown-element | 400 | 2470 | unknown-namespace | 400 | 2471 | access-denied | 403 | 2472 | lock-denied | 409 | 2473 | resource-denied | 409 | 2474 | rollback-failed | 500 | 2475 | data-exists | 409 | 2476 | data-missing | 409 | 2477 | operation-not-supported | 501 | 2478 | operation-failed | 500 | 2479 | partial-operation | 500 | 2480 | malformed-message | 400 | 2481 +-------------------------+-------------+ 2483 Mapping from error-tag to status code 2485 6.1. Error Response Message 2487 When an error occurs for a request message on a data resource or an 2488 operation resource, and a "4xx" class of status codes (except for 2489 status code "403"), then the server SHOULD send a response body 2490 containing the information described by the "errors" container 2491 definition within the YANG module Section 8. 2493 Example: 2495 The following example shows an error returned for an "lock-denied" 2496 error on a datastore resource. 2498 POST /restconf/operations/example-ops:lock-datastore HTTP/1.1 2499 Host: example.com 2501 The server might respond: 2503 HTTP/1.1 409 Conflict 2504 Date: Mon, 23 Apr 2012 17:11:00 GMT 2505 Server: example-server 2506 Content-Type: application/vnd.yang.api+json 2508 { 2509 "errors": { 2510 "error": { 2511 "error-type": "protocol", 2512 "error-tag": "lock-denied", 2513 "error-message": "Lock failed, lock is already held", 2514 } 2515 } 2516 } 2518 7. YANG Patch 2520 The YANG Patch operation is provided so complex editing operations 2521 can be performed within RESTCONF. The "plain patch" operation only 2522 provides a simple merge edit operation on the target datastore. 2524 A "YANG Patch" is an ordered list of edits that are applied to the 2525 target datastore by the server. The specific fields are defined with 2526 the 'yang-patch' container definition in the YANG module Section 8. 2528 Each patch is identified by a client provided string, called the 2529 "patch-id". 2531 The client can control the type of error handling that should be 2532 applied to the list of supplied edits. 2534 7.1. Why not use JSON Patch? 2536 The RESTCONF PATCH method requires that the media type of the patch 2537 content be specified, so it should be possible to use any patch 2538 mechanism, including JSON Patch [RFC6902]. 2540 The RESTCONF protocol is designed to utilize the YANG data modelling 2541 language to specify content schemas. The JSON Patch mechanism is 2542 incompatible with RESTCONF for the following reasons: 2544 o A patch mechanism that works with either XML or JSON encoding is 2545 needed. 2547 o YANG configuration nodes can be named with complex keys, using one 2548 or more key leafs. JSON arrays are packed and all the YANG keys 2549 would be collapsed down to a single integer index. 2551 o YANG configuration nodes are named with stable, persistent 2552 identifiers, using key leafs. JSON arrays are packed, and if 2553 entry I is added or deleted, then all entries I+1 .. Imax are 2554 renumbered. 2556 o The edit operation set needs to align with the NETCONF protocol, 2557 and JSON Patch does not provide an aligned set of edit operations. 2559 o The datastore validation procedures need to be specific and 2560 aligned with YANG validation procedures. 2562 o The error reporting needs to align with the NETCONF protocol, and 2563 JSON Patch does not provide an aligned error reporting mechanism. 2565 7.2. YANG Patch Target Data Node 2567 The target data node for each edit operation is determined by the 2568 value of the target resource in the request and the "target" leaf 2569 within each "edit" entry. 2571 If the target resource specified in the request URI identifies a 2572 datastore resource, then the path string in the "target" leaf is an 2573 absolute path expression. The first node specified in the "target" 2574 leaf is a top-level data node defined within a YANG module. 2576 If the target resource specified in the request URI identifies a data 2577 resource, then the path string in the "target" leaf is a relative 2578 path expression. The first node specified in the "target" leaf is a 2579 child node of the data node associated with the target resource. 2581 7.3. YANG Patch Edit Operations 2583 Each YANG patch edit specifies one edit operation on the target data 2584 node. The set of operations is aligned with the NETCONF edit 2585 operations, but also includes some new operations. 2587 +-----------+-------------------------------------------------------+ 2588 | Operation | Description | 2589 +-----------+-------------------------------------------------------+ 2590 | create | create a new data resource if it does not already | 2591 | | exist or error | 2592 | delete | delete a data resource if it already exists or error | 2593 | insert | insert a new user-ordered data resource | 2594 | merge | merge the edit value with the target data resource; | 2595 | | create if it does not already exist | 2596 | move | re-order the target data resource | 2597 | replace | replace the target data resource with the edit value | 2598 | remove | remove a data resource if it already exists or no | 2599 | | error | 2600 +-----------+-------------------------------------------------------+ 2602 YANG Patch Edit Operations 2604 7.4. YANG Patch Error Handling 2606 There are three error handling modes available that the server MUST 2607 support. These modes specify how the server will behave when errors 2608 occur in the processing of each edit operation. Note that the server 2609 MUST ensure that a well-formed message is received and that the 2610 supplied message body conforms to the YANG schema definition for the 2611 "patch" container, defined in the YANG module Section 8. 2613 If a well-formed, schema-valid YANG Patch message is received, then 2614 then the server will process the supplied edits in ascending order. 2615 The following error modes apply to the processing of this edit list: 2617 o all-or-none: All the specified edits MUST be applied or the target 2618 datastore contents SHOULD be returned to its original state before 2619 the PATCH method started. The server MAY fail to restore the 2620 contents of the target datastore completely and with certainty. 2621 It is possible for a rollback to fail or and "undo" operation to 2622 fail. 2624 o stop-on-error: Each edit will be attempted in order and if an 2625 error occurs, the the server will stop processing the edit list 2626 and return an error report identifying the edit list entry that 2627 caused the error. 2629 o continue-on-error: Each edit will be attempted in order and if an 2630 error occurs, the the server will record an error identifying the 2631 edit list entry that caused the error, and continue to the next 2632 edit entry. 2634 The server will save the running datastore to non-volatile storage if 2635 it has changed, after the edits have been attempted. 2637 7.5. YANG Patch Response 2639 A special response is returned for YANG Patch operations, in order to 2640 report status information for each individual edit. It is possible 2641 to report general errors as well. The YANG conceptual container 2642 definition "yang-patch-status" defined in Section 8 is used to define 2643 the syntax. 2645 7.6. YANG Patch Examples 2647 7.6.1. Continue-on-error Example 2649 The following example shows several songs being added to an existing 2650 album. 2652 o Each edit contains one song. 2654 o The first song already exists, so an error will be reported for 2655 that edit. 2657 o The error-action is continue-on-error, so the rest of the songs 2658 will be added without error. 2660 Request from client: 2662 PATCH /restconf/datastore/example-jukebox:jukebox/ 2663 library/artist/Foo%20Fighters/album/Wasting%20Light HTTP/1.1 2664 Host: example.com 2665 Content-Type: application/vnd.yang.patch+json 2667 { 2668 "yang-patch" : { 2669 "patch-id" : "add-songs-patch", 2670 "error-action" : "continue-on-error", 2671 "edit" : [ 2672 { 2673 "edit-id" : 1, 2674 "operation" : "create", 2675 "target" : "/song", 2676 "value" : { 2677 "song" : { 2678 "name" : "Bridge Burning", 2679 "location" : "/media/bridge_burning.mp3", 2680 "format" : "MP3", 2681 "length" : 288 2682 } 2683 } 2684 }, 2685 { 2686 "edit-id" : 2, 2687 "operation" : "create", 2688 "target" : "/song", 2689 "value" : { 2690 "song" : { 2691 "name" : "Rope", 2692 "location" : "/media/rope.mp3", 2693 "format" : "MP3", 2694 "length" : 259 2695 } 2696 } 2697 }, 2698 { 2699 "edit-id" : 3, 2700 "operation" : "create", 2701 "target" : "/song", 2702 "value" : { 2703 "song" : { 2704 "name" : "Dear Rosemary", 2705 "location" : "/media/dear_rosemary.mp3", 2706 "format" : "MP3", 2707 "length" : 269 2709 } 2710 } 2711 } 2712 ] 2713 } 2714 } 2716 Response from server: 2718 HTTP/1.1 409 Conflict 2719 Date: Mon, 23 Apr 2012 13:01:20 GMT 2720 Server: example-server 2721 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 2722 Content-Type: application/vnd.yang.api+json 2724 { 2725 "yang-patch-status" : { 2726 "patch-id" : "add-songs-patch", 2727 "edit-status" : { 2728 "edit" : [ 2729 { 2730 "edit-id" : 1, 2731 "errors" : { 2732 "error" : { 2733 "error-type": "application", 2734 "error-tag": "data-exists", 2735 "error-path": "/example-jukebox:jukebox/library/artist/ 2736 Foo%20Fighters/album/Wasting%20Light/song/ 2737 Burning%20Light", 2738 "error-message": "Data already exists, cannot be 2739 created" 2740 } 2741 }, 2742 { 2743 "edit-id" : 2, 2744 "location" : "http://example.com/restconf/ 2745 datastore/example-jukebox:jukebox/library/artist/ 2746 Foo%20Fighters/album/Wasting%20Light/song/Rope" 2747 }, 2748 { 2749 "edit-id" : 3, 2750 "location" : "http://example.com/restconf/ 2751 datastore/example-jukebox:jukebox/library/artist/ 2752 Foo%20Fighters/album/Wasting%20Light/song/ 2753 Dear%20Rosemary" 2754 } 2755 } 2756 ] 2758 } 2759 } 2760 } 2762 7.6.2. Move list entry example 2764 The following example shows a song being moved within an existing 2765 playlist. Song "1" in playlist "Foo-One" is being moved after song 2766 "3" in the playlist. The operation succeeds, so a non-error reply 2767 example can be shown. 2769 Request from client: 2771 PATCH /restconf/datastore/example-jukebox:jukebox/ 2772 playlist/Foo-One HTTP/1.1 2773 Host: example.com 2774 Content-Type: application/vnd.yang.patch+json 2776 { 2777 "yang-patch" : { 2778 "patch-id" : "move-song-patch", 2779 "error-action" : "all-or-none", 2780 "edit" : [ 2781 { 2782 "edit-id" : 1, 2783 "operation" : "move", 2784 "target" : "/song/1", 2785 "point" : "/song3", 2786 "where" : "after" 2787 } 2788 ] 2789 } 2790 } 2792 Response from server: 2794 HTTP/1.1 400 OK 2795 Date: Mon, 23 Apr 2012 13:01:20 GMT 2796 Server: example-server 2797 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 2798 Content-Type: application/vnd.yang.api+json 2800 { 2801 "yang-patch-status" : { 2802 "patch-id" : "move-song-patch", 2803 "edit-status" : { 2804 "edit" : [ 2805 { 2806 "edit-id" : 1, 2807 "ok" : [ null ] 2808 } 2809 } 2810 ] 2811 } 2812 } 2813 } 2815 8. RESTCONF module 2817 The "ietf-restconf" module defines conceptual definitions within 2818 groupings, which are not meant to be implemented as datastore 2819 contents by a server. 2821 The "ietf-yang-types" and "ietf-inet_types" modules from [RFC6991] 2822 are used by this module for some type definitions. 2824 RFC Ed.: update the date below with the date of RFC publication and 2825 remove this note. 2827 file "ietf-restconf@2013-09-09.yang" 2829 module ietf-restconf { 2830 // RFC Ed.: replace XXXX with 'ietf' and remove this note 2831 namespace "urn:XXXX:params:xml:ns:yang:ietf-restconf"; 2832 prefix "restconf"; 2834 import ietf-yang-types { prefix yang; } 2835 import ietf-inet-types { prefix inet; } 2837 organization 2838 "IETF NETCONF (Network Configuration) Working Group"; 2840 contact 2841 "Editor: Andy Bierman 2842 2844 Editor: Martin Bjorklund 2845 2847 Editor: Kent Watsen 2848 2850 Editor: Rex Fernando 2851 "; 2853 description 2854 "This module contains conceptual YANG specifications 2855 for the YANG Patch and error content that is used in 2856 RESTCONF protocol messages. A conceptual container 2857 representing the RESTCONF API nodes (type vnd.yang.api). 2859 Note that the YANG definitions within this module do not 2860 represent configuration data of any kind. 2861 The YANG grouping statements provide a normative syntax 2862 for XML and JSON message encoding purposes. 2864 Copyright (c) 2013 IETF Trust and the persons identified as 2865 authors of the code. All rights reserved. 2867 Redistribution and use in source and binary forms, with or 2868 without modification, is permitted pursuant to, and subject 2869 to the license terms contained in, the Simplified BSD License 2870 set forth in Section 4.c of the IETF Trust's Legal Provisions 2871 Relating to IETF Documents 2872 (http://trustee.ietf.org/license-info). 2874 This version of this YANG module is part of RFC XXXX; see 2875 the RFC itself for full legal notices."; 2877 // RFC Ed.: replace XXXX with actual RFC number and remove this 2878 // note. 2880 // RFC Ed.: remove this note 2881 // Note: extracted from draft-bierman-netconf-restconf-01.txt 2883 // RFC Ed.: update the date below with the date of RFC publication 2884 // and remove this note. 2885 revision 2013-09-09 { 2886 description 2887 "Initial revision."; 2888 reference 2889 "RFC XXXX: RESTCONF Protocol."; 2890 } 2892 typedef data-resource-identifier { 2893 type string { 2894 length "1 .. max"; 2895 } 2896 description 2897 "Contains a Data Resource Identifier formatted string 2898 to identify a specific data node."; 2899 reference 2900 "RFC XXXX: [sec. 5.3.1.1 ABNF For Data Resource Identifiers]"; 2901 } 2903 // this typedef is TBD; not currently used 2904 typedef datastore-identifier { 2905 type union { 2906 type enumeration { 2907 enum candidate { 2908 description 2909 "Identifies the NETCONF shared candidate datastore."; 2910 reference 2911 "RFC 6241, section 8.3"; 2913 } 2914 enum running { 2915 description 2916 "Identifies the NETCONF running datastore."; 2917 reference 2918 "RFC 6241, section 5.1"; 2919 } 2920 enum startup { 2921 description 2922 "Identifies the NETCONF startup datastore."; 2923 reference 2924 "RFC 6241, section 8.7"; 2925 } 2926 } 2927 type string; 2928 } 2929 description 2930 "Contains a string to identify a specific datastore. 2931 The enumerated datastore identifier values are 2932 reserved for standard datastore names."; 2933 } 2935 typedef revision-identifier { 2936 type string { 2937 pattern '\d{4}-\d{2}-\d{2}'; 2938 } 2939 description 2940 "Represents a specific date in YYYY-MM-DD format. 2941 TBD: make pattern more precise to exclude leading zeros."; 2942 } 2944 grouping yang-patch { 2946 description 2947 "A grouping that contains a YANG container 2948 representing the syntax and semantics of a 2949 YANG Patch edit request message."; 2951 container yang-patch { 2952 description 2953 "Represents a conceptual sequence of datastore edits, 2954 called a patch. Each patch is given a client-assigned 2955 patch identifier. A patch is applied with client-specified 2956 error handling to control how the ordered list of edits 2957 is applied if an error is encountered. 2959 A patch MUST be validated by the server to be a 2960 well-formed message before any of the patch edits 2961 are validated or attempted. 2963 The validation model for patches closely follows 2964 the constraint enforcement model in YANG, except it 2965 is conceptually enforced on an ordered list of edits. 2967 The server MUST conceptually perform field validation 2968 for each edit in ascending order, as defined in RFC 6020, 2969 section 8.3.1 and 8.3.2. This is most relevant if the edit 2970 error-action is 'stop-on-error', since the identification 2971 of the first error determines where edit processing is 2972 terminated. 2974 If YANG datastore validation (defined in RFC 6020, section 2975 8.3.3) is required, then it performed after all edits have 2976 been individually validated. 2978 It is possible for a datastore constraint violation to occur 2979 due to any node in the datastore, including nodes not 2980 included in the edit list. Any validation errors SHOULD 2981 be reported in the reply message. 2983 If datastore validation is required and fails, the server 2984 SHOULD NOT allow the datastore to remain invalid. It is an 2985 implementation-specific matter how the server fixes the 2986 invalid datastore. For example, the server might prune 2987 invalid nodes causing the datastore validation error, 2988 or undo the entire patch."; 2990 reference 2991 "RFC 6020, section 8.3."; 2993 leaf patch-id { 2994 type string; 2995 description 2996 "An arbitrary string provided by the client to identify 2997 the entire patch. This value SHOULD be present in any 2998 audit logging records generated by the server for the 2999 patch. Error messages returned by the server pertaining 3000 to this patch will be identified by this patch-id value."; 3001 } 3003 leaf error-action { 3004 type enumeration { 3005 enum all-or-none { 3006 description 3007 "The server will apply all edits in the patch only 3008 if no errors occur. If any errors occur then 3009 none of the edits will be applied and the 3010 contents of the target datastore MUST be unchanged."; 3011 } 3012 enum stop-on-error { 3013 description 3014 "The server will apply edits in the specified order 3015 and will stop processing edits if any error occurs. 3016 Any previous edits which were successfully applied 3017 will remain applied. No further edits will be 3018 attempted after the first error is encountered."; 3019 } 3020 enum continue-on-error { 3021 description 3022 "The server will apply edits in the specified order 3023 and will continue processing edits if any error 3024 occurs."; 3025 } 3026 } 3027 default all-or-none; 3028 description 3029 "The error handling behavior for the ordered list of 3030 edits."; 3031 } 3033 list edit { 3034 key edit-id; 3036 description 3037 "Represents one edit within the YANG Patch 3038 request message."; 3040 leaf edit-id { 3041 type uint32; 3042 description 3043 "Arbitrary integer index for the edit. 3044 The server MUST process edits in ascending order. 3045 Error messages returned by the server pertaining 3046 to a specific edit will be identified by this 3047 identifier value."; 3048 } 3050 leaf operation { 3051 type enumeration { 3052 enum create { 3053 description 3054 "The target data node is created using the 3055 supplied value, only if it does not already 3056 exist."; 3058 } 3059 enum delete { 3060 description 3061 "Delete the target node, only if the data resource 3062 currently exists, otherwise return an error."; 3063 } 3064 enum insert { 3065 description 3066 "Insert the supplied value into a user-ordered 3067 list or leaf-list entry. The target node must 3068 represent a new data resource."; 3069 } 3070 enum merge { 3071 description 3072 "The supplied value is merged with the target data 3073 node."; 3074 } 3075 enum move { 3076 description 3077 "Move the target node. Reorder a user-ordered 3078 list or leaf-list. The target node must represent 3079 an existing data resource."; 3080 } 3081 enum replace { 3082 description 3083 "The supplied value is used to replace the target 3084 data node."; 3085 } 3086 enum remove { 3087 description 3088 "Delete the target node if it currently exists."; 3089 } 3090 } 3091 mandatory true; 3092 description 3093 "The datastore operation requested for the associated 3094 edit entry"; 3095 } 3097 leaf target { 3098 type data-resource-identifier; 3099 mandatory true; 3100 description 3101 "Identifies the target data resource for the edit 3102 operation."; 3103 } 3105 leaf point { 3106 when "(../operation = 'insert' or " + 3107 "../operation = 'move') and " + 3108 "(../where = 'before' or ../where = 'after')" { 3109 description 3110 "Point leaf only applies for insert or move 3111 operations, before or after an existing entry."; 3112 } 3113 type data-resource-identifier; 3114 description 3115 "The absolute URL path for the data node that is being 3116 used as the insertion point or move point for the 3117 target of this edit entry."; 3118 } 3120 leaf where { 3121 when "../operation = 'insert' or ../operation = 'move'" { 3122 description 3123 "Where leaf only applies for insert or move 3124 operations."; 3125 } 3126 type enumeration { 3127 enum before { 3128 description 3129 "Insert or move a data node before the data resource 3130 identified by the 'point' parameter."; 3131 } 3132 enum after { 3133 description 3134 "Insert or move a data node after the data resource 3135 identified by the 'point' parameter."; 3136 } 3137 enum first { 3138 description 3139 "Insert or move a data node so it becomes ordered 3140 as the first entry."; 3141 } 3142 enum last { 3143 description 3144 "Insert or move a data node so it becomes ordered 3145 as the last entry."; 3146 } 3148 } 3149 default last; 3150 description 3151 "Identifies where a data resource will be inserted or 3152 moved. YANG only allows these operations for 3153 list and leaf-list data nodes that are ordered-by 3154 user."; 3155 } 3157 anyxml value { 3158 when "(../operation = 'create' or " + 3159 "../operation = 'merge' " + 3160 "or ../operation = 'replace' or " + 3161 "../operation = 'insert')" { 3162 description 3163 "Value node only used for create, merge, 3164 replace, and insert operations"; 3165 } 3166 description 3167 "Value used for this edit operation."; 3168 } 3169 } 3170 } 3172 } // grouping yang-patch 3174 grouping yang-patch-status { 3176 description 3177 "A grouping that contains a YANG container 3178 representing the syntax and semantics of 3179 YANG Patch status response message."; 3181 container yang-patch-status { 3182 description 3183 "A container representing the response message 3184 sent by the server after a YANG Patch edit 3185 request message has been processed."; 3187 leaf patch-id { 3188 type string; 3189 description 3190 "The patch-id value used in the request"; 3191 } 3193 container global-errors { 3194 uses errors; 3195 description 3196 "This container will be present if global 3197 errors unrelated to a specific edit occurred."; 3198 } 3200 container edit-status { 3201 description 3202 "This container will be present if there are 3203 edit-specific status responses to report."; 3205 list edit { 3206 key edit-id; 3208 description 3209 "Represents a list of status responses, 3210 corresponding to edits in the YANG Patch 3211 request message."; 3213 leaf edit-id { 3214 type uint32; 3215 description 3216 "Response status is for the edit list entry 3217 with this edit-id value."; 3218 } 3219 choice edit-status-choice { 3220 description 3221 "A choice between different types of status 3222 responses for each edit entry."; 3224 leaf ok { 3225 type empty; 3226 description 3227 "This edit entry was invoked without any 3228 errors detected by the server associated 3229 with this edit."; 3230 } 3231 leaf location { 3232 type inet:uri; 3233 description 3234 "Contains the Location header value that would be 3235 returned if this edit causes a new resource to be 3236 created. If the edit identified by the same edit-id 3237 value was successfully invoked and a new resource 3238 was created, then this field will be returned 3239 instead of 'ok'."; 3240 } 3241 leaf skipped { 3242 type empty; 3243 description 3244 "This edit entry was skipped or not reached 3245 by the server."; 3246 } 3247 case errors { 3248 uses errors; 3249 description 3250 "The server detected errors associated with the 3251 edit identified by the same edit-id value."; 3252 } 3253 } 3254 } 3255 } 3256 } 3257 } // grouping yang-patch-status 3259 grouping errors { 3261 description 3262 "A grouping that contains a YANG container 3263 representing the syntax and semantics of a 3264 YANG Patch errors report within a response message."; 3266 container errors { 3267 config false; // needed so list error does not need a key 3268 description 3269 "Represents an error report returned by the server if 3270 a request results in an error."; 3272 list error { 3273 description 3274 "An entry containing information about one 3275 specific error that occurred while processing 3276 a RESTCONF request."; 3277 reference "RFC 6241, Section 4.3"; 3279 leaf error-type { 3280 type enumeration { 3281 enum transport { 3282 description "The transport layer"; 3283 } 3284 enum rpc { 3285 description "The rpc or notification layer"; 3286 } 3287 enum protocol { 3288 description "The protocol operation layer"; 3289 } 3290 enum application { 3291 description "The server application layer"; 3292 } 3293 } 3294 mandatory true; 3295 description 3296 "The protocol layer where the error occurred."; 3298 } 3300 leaf error-tag { 3301 type string; 3302 mandatory true; 3303 description 3304 "The enumerated error tag."; 3305 } 3307 leaf error-app-tag { 3308 type string; 3309 description 3310 "The application-specific error tag."; 3311 } 3313 leaf error-path { 3314 type data-resource-identifier; 3315 description 3316 "The target data resource identifier associated 3317 with the error, if any."; 3318 } 3320 leaf error-message { 3321 type string; 3322 description 3323 "A message describing the error."; 3324 } 3326 container error-info { 3327 description 3328 "A container allowing additional information 3329 to be included in the error report."; 3330 // arbitrary anyxml content here 3331 } 3332 } 3333 } 3334 } // grouping errors 3336 grouping restconf { 3338 description 3339 "A grouping that contains a YANG container 3340 representing the syntax and semantics of 3341 the RESTCONF API resource."; 3343 container restconf { 3344 description 3345 "Conceptual container representing the vnd.yang.api 3346 resource type."; 3348 container datastore { 3349 description 3350 "Container representing the vnd.yang.datastore resource 3351 type. Represents the conceptual root of the unified 3352 datastore containing YANG data nodes. The child nodes 3353 of this container can be data resources (vnd.yang.data) 3354 defined as top-level YANG data nodes from the modules 3355 advertised by the server in /restconf/modules."; 3356 } 3357 container modules { 3358 description 3359 "Contains a list of module description entries. 3360 These modules are currently loaded into the server."; 3362 list module { 3363 key "name revision"; 3364 description 3365 "Each entry represents one module currently 3366 supported by the server."; 3368 leaf name { 3369 type yang:yang-identifier; 3370 description "The YANG module name."; 3371 } 3372 leaf revision { 3373 type union { 3374 type revision-identifier; 3375 type string { length 0; } 3376 } 3377 description 3378 "The YANG module revision date. An empty string is 3379 used if no revision statement is present in the 3380 YANG module."; 3381 } 3382 leaf namespace { 3383 type inet:uri; 3384 mandatory true; 3385 description 3386 "The XML namespace identifier for this module."; 3387 } 3388 leaf-list feature { 3389 type yang:yang-identifier; 3390 description 3391 "List of YANG feature names from this module that are 3392 supported by the server."; 3394 } 3395 leaf-list deviation { 3396 type yang:yang-identifier; 3397 description 3398 "List of YANG deviation module names used by this 3399 server to modify the conformance of the module 3400 associated with this entry."; 3401 } 3402 } 3403 } 3404 container operations { 3405 description 3406 "Container for all operation resources 3407 (vnd.yang.operation), 3409 Each resource is represented as an empty leaf with the 3410 name of the RPC operation from the YANG rpc statement. 3412 E.g.; 3414 POST /restconf/operations/show-log-errors 3416 leaf show-log-errors { 3417 type empty; 3418 } 3419 "; 3420 } 3421 leaf version { 3422 type enumeration { 3423 enum "1.0" { 3424 description 3425 "Version 1.0 of the RESTCONF protocol."; 3426 } 3427 } 3428 config false; 3429 description 3430 "Contains the RESTCONF protocol version."; 3431 } 3432 } 3433 } // grouping restconf 3435 } 3437 3439 9. IANA Considerations 3441 9.1. YANG Module Registry 3443 This document registers one URI in the IETF XML registry [RFC3688]. 3444 Following the format in RFC 3688, the following registration is 3445 requested to be made. 3447 // RFC Ed.: replace XXXX with 'ietf' and remove this note 3448 URI: urn:XXXX:params:xml:ns:yang:ietf-restconf 3449 Registrant Contact: The NETMOD WG of the IETF. 3450 XML: N/A, the requested URI is an XML namespace. 3452 This document registers one YANG module in the YANG Module Names 3453 registry [RFC6020]. 3455 name: ietf-restconf 3456 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3457 prefix: restconf 3458 // RFC Ed.: replace XXXX with RFC number and remove this note 3459 reference: RFC XXXX 3461 10. Security Considerations 3463 TBD 3465 11. Change Log 3467 -- RFC Ed.: remove this section before publication. 3469 11.1. 00 to 01 3471 o Removed incorrect /.well-known URI prefix. 3473 o remove incorrect IANA request for well-known URI. 3475 o Clarified that API resource type nodes are defined in the ietf- 3476 restconf namespace. 3478 o changed CamelCase names in example-jukebox.yang to lowercase, and 3479 updated examples. 3481 o updated and corrected YANG types in ietf-restconf module. 3483 11.2. YANG-API-01 to RESTCONF-00 3485 o Protocol renamed from YANG-API to RESTCONF 3487 o Fields are clarified. Containers and lists are sub-resources. 3488 All other YANG data node types are fields within a parent 3489 resource. 3491 o The 'optional-key' YANG extension has been removed. 3493 o The default value is returned by the server if the target resource 3494 represents a missing data node but the server is using a default 3495 value for the leaf. 3497 o The default for the 'depth' parameter has been changed from '1' to 3498 'unbounded'. The depth is only limited if an integer value for 3499 this parameter is specified by the client. 3501 o The default for the 'format' parameter has been changed from 3502 'json' to 'xml'. 3504 o expanded introduction 3506 o removed transactions 3508 o removed capabilities 3510 o removed usage of Range and IfRange headers 3511 o simplified editing model 3513 o removed global protocol operations from ietf-restconf.yang 3515 o changed RPC operation terminology to protocol operation 3517 o updated JSON draft reference 3519 o updated IANA section 3521 o added YANG Patch 3523 o added YANG definitions to ietf-restconf.yang 3525 o added Kent Watsen and Rex Fernando as co-authors 3527 o updated YANG modules so they pass pyang --ietf checking 3529 o changed examples so resource URIs use the module name variant to 3530 identify data resources 3532 o changed depth behavior so the entire server contents are not 3533 returned for "GET /restconf"; Server will stop at new resource 3534 type; e.g. yang.api --> yang.datastore returns the datastore as an 3535 empty node; yang.api --> yang.operation returns the operation name 3536 as an empty node; 3538 12. Closed Issues 3540 o Which WG should do this work? NETCONF? NETMOD? It is not clear 3541 since RESTCONF builds on concepts and standards from documents 3542 owned by both working groups. 3544 A: The NETCONF WG would do this work. 3546 o Should sessions be used or not? Should "reusable sessions" be 3547 used? Better for auditing? How does locking of the /restconf/ 3548 datastore resource work for multiple edits if a session is 1 3549 operation? When does the server release the lock and decide it 3550 has been abandoned or client was disconnected? 3552 A: RESTCONF is a session-less protocol. It could be implemented to 3553 utilize persistent HTTP connections, but this is not required or 3554 designed into the protocol. 3556 o Should the "/restconf/modules" resource within the API resource be 3557 a separate resource, with its own timestamp? Currently the API 3558 timestamp is coupled to any changes to the list of loaded modules. 3559 Should the API resource be static and cacheable? 3561 A: all child containers are considered sub-resources. The server MAY 3562 support timestamps and entity IDs for data nodes. 3564 o What to do about no REMOVE operation, just DELETE? The effect is 3565 local to the request; in a NETCONF edit-config it is worse, since 3566 the netconf request might create/delete/modify many nodes 3568 A: The YANG Patch operation allows remove or delete semantics. 3570 o Should every YANG data node be a data resource and every YANG RPC 3571 statement an operation resource? Is a YANG extension needed to 3572 allow data modeler control of resource boundaries? 3574 A: Nested containers and lists are considered sub-resources. 3575 Terminal nodes (leaf, leaf-list, anyxml) are considered properties of 3576 the parent resource. 3578 o Resource creation order and other dependencies between resources 3579 are not well identified in YANG. YANG has leafrefs and instance- 3580 identifiers, which can be used to identify some order 3581 dependencies. Are any new mechanisms needed in RESTCONF needed to 3582 identify resource creation order and other dependency 3583 requirements? 3585 A: YANG Patch allows the client to control creation order when 3586 multiple resources need to be edited at once. The edit operations 3587 allow the server to order all the descendant resources provided by 3588 the client, for a single datastore edit target node. 3590 o Encoding of leafrefs? Is there some additional meta-data needed? 3591 Do leafref nodes need to be identified in responses (RFC 5988) or 3592 is the YANG module definition sufficient to provide this meta- 3593 data? 3595 A: no special message encoding of leaf-refs is needed. The server 3596 must understand the YANG schema no matter what protocol or encoding 3597 is used. 3599 o What should the default algorithm be for defining data resources? 3600 Should the default for an augment from another namespace be to 3601 start a new resource? Top-level data node defaults as a resource 3602 OK? 3604 A: Augmented nodes do not follow different rules than other nested 3605 YANG structures. Containers and lists start new sub-resources. 3607 13. Open Issues 3609 o There is no "message-id" field in a RESTCONF message. Is a 3610 message identifier needed? If so, should either the "Message-ID" 3611 or "Content-ID" header from RFC 2392 be used for this purpose? 3613 o What syntax should be used for the "select" query parameter? The 3614 current choices are "xpath" and "path-expr". Perhaps an 3615 additional parameter to identify the select string format is 3616 needed to allow extensibility? 3618 o Are all header lines used by RESTCONF supported by common 3619 application frameworks, such as FastCGI and WSGI? If not, then 3620 should query parameters be used instead, since the QUERY_STRING is 3621 widely available to WEB applications? 3623 o Should the element returned in error responses be a 3624 separate media type? 3626 o How should additional datastores be supported, which may be added 3627 to the NETCONF/NETMOD framework in the future? 3629 o How does a client know which PATCH media types are supported by 3630 the server in addition to application/vnd.yang.data and 3631 application/vnd.yang.patch? 3633 o Is the /restconf/version field considered meta-data? Should it be 3634 returned as XRD (Extensible Resource Descriptor)? In addition or 3635 instead of the version field? Should this be the ietf-restconf 3636 YANG module revision date, instead of the string 1.0? 3638 o Notification message delivery is TBD 3640 o Alignment between NETCONF and RESTCONF notification is expected to 3641 be very close to RFC 5277 design. Additional Sub/pub features 3642 still TBD. 3644 o Some sections may need to be rewritten to support notifications 3645 and event resources 3647 o Since data resources can only be YANG containers or lists, what 3648 should be done about top-level YANG data nodes that are not 3649 containers or lists? Are they allowed in RESTCONF? 3651 o Can a choice be a resource? YANG choices are invisible to 3652 RESTCONF at this time. 3654 o Does RESTCONF need to Use a .well-known link relation to to re-map 3655 API entry point? 3657 The client first discovers the server's root for the RESTCONF API. 3658 In this example, it is "/api/restconf": 3660 Request 3661 ------- 3662 GET /.well-known/host-meta users HTTP/1.1 3663 Host: example.com 3664 Accept: application/xrd+xml 3666 Response 3667 -------- 3668 HTTP/1.1 200 OK 3669 Content-Type: application/xrd+xml 3670 Content-Length: nnn 3672 3673 3674 3676 Once discovering the RESTCONF API root, the client MUST prepend it to 3677 any access to a RESTCONF resource: 3679 Request 3680 ------- 3681 GET /api/restconf?select=version&format=json HTTP/1.1 3682 Host: example.com 3683 Accept: application/vnd.yang.api+json 3685 Response 3686 -------- 3687 HTTP/1.1 200 OK 3688 Date: Mon, 23 Apr 2012 17:01:00 GMT 3689 Server: example-server 3690 Cache-Control: no-cache 3691 Pragma: no-cache 3692 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 3693 Content-Type: application/vnd.yang.api+json 3695 { "version": "1.0" } 3697 14. Example YANG Module 3699 module example-jukebox { 3701 namespace "http://example.com/ns/example-jukebox"; 3702 prefix "jbox"; 3704 organization "Example, Inc."; 3705 contact "support at example.com"; 3706 description "Example Jukebox Data Model Module"; 3707 revision "2013-09-09" { 3708 description "Initial version."; 3709 reference "example.com document 1-4673"; 3710 } 3712 identity genre { 3713 description "Base for all genre types"; 3714 } 3716 // abbreviated list of genre classifications 3717 identity alternative { 3718 base genre; 3719 description "Alternative music"; 3720 } 3721 identity blues { 3722 base genre; 3723 description "Blues music"; 3724 } 3725 identity country { 3726 base genre; 3727 description "Country music"; 3728 } 3729 identity jazz { 3730 base genre; 3731 description "Jazz music"; 3732 } 3733 identity pop { 3734 base genre; 3735 description "Pop music"; 3736 } 3737 identity rock { 3738 base genre; 3739 description "Rock music"; 3740 } 3742 container jukebox { 3743 presence 3744 "An empty container indicates that the jukebox 3745 service is available"; 3747 description 3748 "Represents a jukebox resource, with a library, playlists, 3749 and a play operation."; 3751 container library { 3753 description "Represents the jukebox library resource."; 3755 list artist { 3756 key name; 3758 description 3759 "Represents one artist resource within the 3760 jukebox library resource."; 3762 leaf name { 3763 type string { 3764 length "1 .. max"; 3765 } 3766 description "The name of the artist."; 3767 } 3769 list album { 3770 key name; 3772 description 3773 "Represents one album resource within one 3774 artist resource, within the jukebox library."; 3776 leaf name { 3777 type string { 3778 length "1 .. max"; 3779 } 3780 description "The name of the album."; 3781 } 3783 leaf genre { 3784 type identityref { base genre; } 3785 description 3786 "The genre identifying the type of music on 3787 the album."; 3788 } 3790 leaf year { 3791 type uint16 { 3792 range "1900 .. max"; 3794 } 3795 description "The year the album was released"; 3796 } 3798 list song { 3799 key name; 3801 description 3802 "Represents one song resource within one 3803 album resource, within the jukebox library."; 3805 leaf name { 3806 type string { 3807 length "1 .. max"; 3808 } 3809 description "The name of the song"; 3810 } 3811 leaf location { 3812 type string; 3813 mandatory true; 3814 description 3815 "The file location string of the 3816 media file for the song"; 3817 } 3818 leaf format { 3819 type string; 3820 description 3821 "An identifier string for the media type 3822 for the file associated with the 3823 'location' leaf for this entry."; 3824 } 3825 leaf length { 3826 type uint32; 3827 units "seconds"; 3828 description 3829 "The duration of this song in seconds."; 3830 } 3831 } // end list 'song' 3832 } // end list 'album' 3833 } // end list 'artist' 3835 leaf artist-count { 3836 type uint32; 3837 units "songs"; 3838 config false; 3839 description "Number of artists in the library"; 3840 } 3841 leaf album-count { 3842 type uint32; 3843 units "albums"; 3844 config false; 3845 description "Number of albums in the library"; 3846 } 3847 leaf song-count { 3848 type uint32; 3849 units "songs"; 3850 description "Number of songs in the library"; 3851 } 3852 } // end library 3854 list playlist { 3855 key name; 3857 description 3858 "Example configuration data resource"; 3860 leaf name { 3861 type string; 3862 description 3863 "The name of the playlist."; 3864 } 3865 leaf description { 3866 type string; 3867 description 3868 "A comment describing the playlist."; 3869 } 3870 list song { 3871 key index; 3872 ordered-by user; 3874 description 3875 "Example nested configuration data resource"; 3877 leaf index { // not really needed 3878 type uint32; 3879 description 3880 "An arbitrary integer index for this 3881 playlist song."; 3882 } 3883 leaf id { 3884 type instance-identifier; 3885 mandatory true; 3886 description 3887 "Song identifier. Must identify an instance of 3888 /jukebox/library/artist/album/song/name."; 3889 } 3891 } 3892 } 3894 container player { 3895 description 3896 "Represents the jukebox player resource."; 3898 leaf gap { 3899 type decimal64 { 3900 fraction-digits 1; 3901 range "0.0 .. 2.0"; 3902 } 3903 units "tenths of seconds"; 3904 description "Time gap between each song"; 3905 } 3906 } 3907 } 3909 rpc play { 3910 description "Control function for the jukebox player"; 3911 input { 3912 leaf playlist { 3913 type string; 3914 mandatory true; 3915 description "playlist name"; 3916 } 3917 leaf song-number { 3918 type uint32; 3919 mandatory true; 3920 description "Song number in playlist to play"; 3921 } 3922 } 3923 } 3924 } 3926 15. References 3928 15.1. Normative References 3930 [I-D.lhotka-netmod-json] 3931 Lhotka, L., "Modeling JSON Text with YANG", 3932 draft-lhotka-netmod-yang-json-01 (work in progress), 3933 April 2013. 3935 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3936 Requirement Levels", BCP 14, RFC 2119, March 1997. 3938 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3939 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3940 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3942 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3943 January 2004. 3945 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3946 Resource Identifier (URI): Generic Syntax", STD 66, 3947 RFC 3986, January 2005. 3949 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 3950 RFC 5789, March 2010. 3952 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 3953 Network Configuration Protocol (NETCONF)", RFC 6020, 3954 October 2010. 3956 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3957 and A. Bierman, Ed., "Network Configuration Protocol 3958 (NETCONF)", RFC 6241, June 2011. 3960 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 3961 Protocol (NETCONF) Access Control Model", RFC 6536, 3962 March 2012. 3964 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 3965 July 2013. 3967 15.2. Informative References 3969 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 3970 (JSON) Patch", RFC 6902, April 2013. 3972 Authors' Addresses 3974 Andy Bierman 3975 YumaWorks 3977 Email: andy@yumaworks.com 3979 Martin Bjorklund 3980 Tail-f Systems 3982 Email: mbj@tail-f.com 3984 Kent Watsen 3985 Juniper Networks 3987 Email: kwatsen@juniper.net 3989 Rex Fernando 3990 Cisco 3992 Email: rex@cisco.com