idnits 2.17.1 draft-bierman-netconf-yang-api-00.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 5 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1593 has weird spacing: '...d entry resou...' == 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 (May 30, 2012) is 4339 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) == Outdated reference: A later version (-01) exists of draft-lhotka-yang-json-00 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 6021 (Obsoleted by RFC 6991) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 3 errors (**), 0 flaws (~~), 5 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: December 1, 2012 Tail-f Systems 6 May 30, 2012 8 YANG-API Protocol 9 draft-bierman-netconf-yang-api-00 11 Abstract 13 This document describes a RESTful protocol that provides a 14 programmatic interface over HTTP for accessing data defined in YANG, 15 using the datastores defined in NETCONF. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on December 1, 2012. 34 Copyright Notice 36 Copyright (c) 2012 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 52 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 53 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 5 54 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 6 56 1.1.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 57 1.2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 1.2.1. Resource URI Map . . . . . . . . . . . . . . . . . . . 8 59 1.2.2. YANG-API Message Examples . . . . . . . . . . . . . . 8 60 2. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 15 61 2.1. Message Model . . . . . . . . . . . . . . . . . . . . . . 15 62 2.2. Resource Model . . . . . . . . . . . . . . . . . . . . . . 15 63 2.2.1. YANG-API Resource Types . . . . . . . . . . . . . . . 15 64 2.2.2. Resource Discovery . . . . . . . . . . . . . . . . . . 16 65 2.3. Datastore Model . . . . . . . . . . . . . . . . . . . . . 16 66 2.3.1. Content Model . . . . . . . . . . . . . . . . . . . . 17 67 2.3.2. Editing Model . . . . . . . . . . . . . . . . . . . . 17 68 2.3.3. Locking Model . . . . . . . . . . . . . . . . . . . . 19 69 2.3.4. Persistence Model . . . . . . . . . . . . . . . . . . 20 70 2.3.5. Defaults Model . . . . . . . . . . . . . . . . . . . . 20 71 2.4. Transaction Model . . . . . . . . . . . . . . . . . . . . 20 72 2.5. Extensibility Model . . . . . . . . . . . . . . . . . . . 21 73 2.6. Versioning Model . . . . . . . . . . . . . . . . . . . . . 21 74 2.7. Retrieval Filtering Model . . . . . . . . . . . . . . . . 22 75 2.8. Access Control Model . . . . . . . . . . . . . . . . . . . 22 76 3. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 24 77 3.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 24 78 3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 79 3.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 80 3.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 81 3.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 82 3.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 29 83 3.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 29 84 3.8. Query Parameters . . . . . . . . . . . . . . . . . . . . . 30 85 3.8.1. "config" Parameter . . . . . . . . . . . . . . . . . . 30 86 3.8.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 31 87 3.8.3. "format" Parameter . . . . . . . . . . . . . . . . . . 32 88 3.8.4. "insert" Parameter . . . . . . . . . . . . . . . . . . 32 89 3.8.5. "point" Parameter . . . . . . . . . . . . . . . . . . 33 90 3.8.6. "select" Parameter . . . . . . . . . . . . . . . . . . 34 91 3.9. RPC Operations . . . . . . . . . . . . . . . . . . . . . . 34 92 3.9.1. Data Model Specific Operations . . . . . . . . . . . . 35 93 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 94 4.1. Request URI Structure . . . . . . . . . . . . . . . . . . 36 95 4.2. Message Headers . . . . . . . . . . . . . . . . . . . . . 37 96 4.3. Message Encoding . . . . . . . . . . . . . . . . . . . . . 38 97 4.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 38 98 4.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 39 99 5. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 40 100 5.1. API Resource (/yang-api) . . . . . . . . . . . . . . . . . 40 101 5.1.1. /yang-api/capabilities . . . . . . . . . . . . . . . . 40 102 5.1.2. /yang-api/datastore . . . . . . . . . . . . . . . . . 43 103 5.1.3. /yang-api/operations . . . . . . . . . . . . . . . . . 44 104 5.1.4. /yang-api/modules . . . . . . . . . . . . . . . . . . 46 105 5.1.5. /yang-api/transaction . . . . . . . . . . . . . . . . 48 106 5.1.6. /yang-api/version . . . . . . . . . . . . . . . . . . 48 107 5.2. Datastore Resource . . . . . . . . . . . . . . . . . . . . 49 108 5.3. Data Resource . . . . . . . . . . . . . . . . . . . . . . 49 109 5.3.1. Encoding YANG Instance Identifiers in the Request 110 URI . . . . . . . . . . . . . . . . . . . . . . . . . 50 111 5.3.2. Identifying YANG-defined Data Resources . . . . . . . 52 112 5.3.3. Identifying Optional Keys . . . . . . . . . . . . . . 53 113 5.3.4. Data Resource Retrieval . . . . . . . . . . . . . . . 53 114 5.4. Operation Resource . . . . . . . . . . . . . . . . . . . . 55 115 5.4.1. Encoding Operation Input Parameters . . . . . . . . . 56 116 5.4.2. Encoding Operation Output Parameters . . . . . . . . . 57 117 5.4.3. Identifying YANG-defined Operation Resources . . . . . 58 118 5.5. Transaction Resource . . . . . . . . . . . . . . . . . . . 58 119 5.5.1. Creating a Transaction Resource . . . . . . . . . . . 59 120 5.5.2. Editing a Transaction Datastore . . . . . . . . . . . 60 121 5.5.3. Deleting a Transaction Resource . . . . . . . . . . . 61 122 5.5.4. Transaction Operations . . . . . . . . . . . . . . . . 62 123 6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 65 124 6.1. Error Response Message . . . . . . . . . . . . . . . . . . 66 125 7. RelaxNG Grammar . . . . . . . . . . . . . . . . . . . . . . . 69 126 8. YANG-API module . . . . . . . . . . . . . . . . . . . . . . . 70 127 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 73 128 10. Security Considerations . . . . . . . . . . . . . . . . . . . 74 129 11. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 75 130 12. Example YANG Module . . . . . . . . . . . . . . . . . . . . . 78 131 13. Normative References . . . . . . . . . . . . . . . . . . . . . 82 132 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 83 134 1. Introduction 136 There is a need for standard mechanisms to allow WEB applications to 137 access the configuration data, operational data, and data-model 138 specific RPC operations within a networking device, in a modular and 139 extensible manner. 141 This document describes a RESTful protocol called YANG-API, running 142 over HTTP [RFC2616], for accessing data defined in YANG [RFC6020], 143 using datastores defined in NETCONF [RFC6241]. 145 The NETCONF protocol defines configuration datastores and a set of 146 Create, Retrieve, Update, Delete (CRUD) operations that can be used 147 to access these datastores. The YANG language defines the syntax and 148 semantics of datastore content and operational data. RESTful 149 operations are used to access the hierarchical data within a 150 datastore. 152 A RESTful API can be created that provides CRUD operations on a 153 NETCONF datastore containing YANG-defined data. This can be done in 154 a simplified manner, compatible with HTTP and RESTful design 155 principles. Since NETCONF protocol operations are not relevant, the 156 user should not need any prior knowledge of NETCONF in order to use 157 the RESTful API. 159 Configuration data and state data are exposed as resources that can 160 be retrieved with the GET method. Resources representing 161 configuration data can be modified with the DELETE, PATCH, POST, and 162 PUT methods. Data-model specific RPC operations defined with the 163 YANG "rpc" statement can be invoked with the POST method. 165 The framework and meta-model used for a RESTful API does not need to 166 mirror those used by the NETCONF protocol. It just needs to be 167 compatible with NETCONF. A simplified framework and protocol is 168 needed that aligns with the three NETCONF datastores (candidate, 169 running, startup). A simplified yet more powerful transaction model 170 is needed that exposes the proper functionality without over- 171 restricting server design. 173 The RESTful API is not intended to replace NETCONF, but rather 174 provide an additional simplified interface that follows RESTful 175 principles and is compatible with a resource-oriented device 176 abstraction. It is expected that applications that need the full 177 feature set of NETCONF such as notifications will continue to use 178 NETCONF. 180 The following figure shows the system components: 182 +-----------+ +-----------------+ 183 | WEB app | <-------> | | 184 +-----------+ HTTP | network device | 185 | | 186 +-----------+ | +-----------+ | 187 | NMS app | <-------> | | datastore | | 188 +-----------+ NETCONF | +-----------+ | 189 +-----------------+ 191 1.1. Terminology 193 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 194 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 195 "OPTIONAL" in this document are to be interpreted as described in BCP 196 14, [RFC2119]. 198 1.1.1. NETCONF 200 The following terms are defined in [RFC6241]: 202 o candidate configuration datastore 204 o client 206 o configuration data 208 o datastore 210 o configuration datastore 212 o protocol operation 214 o running configuration datastore 216 o server 218 o startup configuration datastore 220 o state data 222 o user 224 1.1.2. HTTP 226 The following terms are defined in [RFC2616]: 228 o entity tag 230 o fragment 232 o header line 234 o message body 236 o method 238 o path 240 o query 242 o request URI 244 o response body 246 1.1.3. YANG 248 The following terms are defined in [RFC6020]: 250 o container 252 o data node 254 o key leaf 256 o leaf 258 o leaf-list 260 o list 262 o presence container (or P-container) 264 o RPC operation 266 o non-presence container (or NP-container) 268 o ordered-by system 270 o ordered-by user 272 1.1.4. Terms 274 The following terms are used within this document: 276 o API resource: a resource with the media type "application/ 277 vnd.yang.api+xml" or ""application/vnd.yang.api+json". 279 o data resource: a resource with the media type "application/ 280 vnd.yang.data+xml" or "application/vnd.yang.data+json". 282 o datastore resource: a resource with the media type "application/ 283 vnd.yang.datastore+xml" or "application/vnd.yang.datastore+json" 285 o edit operation: a YANG-API operation on a data resource using the 286 POST, PUT, PATCH, or DELETE method. 288 o operation: the conceptual YANG-API operation for a message, 289 derived from the method, request URI, headers, and message body. 291 o operation resource: a resource with the media type 292 "vnd.yang.operation+xml" or "vnd.yang.operation+json" 294 o optional key: a key leaf for a YANG list data node, which MAY be 295 omitted by the client when an instance of the list is created. 297 o query parameter: a parameter (and its value if any), encoded 298 within the query portion of the request URI. 300 o resource: a conceptual object representing a manageable component 301 within a device. 303 o retrieval request: an operation using the GET or HEAD methods. 305 o target resource: the resource that is associated with a particular 306 message, identified by the "path" component of the request URI. 308 o transaction resource: a resource with the media type 309 "vnd.yang.transaction+xml" or "vnd.yang.transaction+json" 311 1.2. Overview 313 This document defines the YANG-API protocol, a RESTful API for 314 accessing conceptual datastores containing data defined with YANG 315 language. YANG-API provides an application framework and meta-model, 316 using HTTP operations. 318 The YANG-API resources are accessed via a set of URIs defined in this 319 document. The set of YANG modules supported by the server will 320 determine the additional data model specific operations and top-level 321 data node resources available on the server. 323 Not all YANG-API defined resources are mandatory-to-implement. The 324 server implementor may choose the specific editing model and 325 persistence model that is supported. The specific subset is 326 identified and accessible via 3 capability fields. Refer to 327 Section 5.1.1 for more details. 329 1.2.1. Resource URI Map 331 The URI hierarchy for the YANG-API resources consists of an entry 332 point and up to 6 top-level resources and/or fields. Refer to 333 Section 5 for details on each URI. 335 /yang-api 336 /capabilities 337 /edit-model 338 /persist-model 339 /transaction-model 340 /datastore 341 / (config=true or false) 342 /modules 343 /module 344 /operations 345 /lock-datastore 346 /save-datastore 347 /unlock-datastore 348 / 349 /transaction 350 / 351 /commit 352 /datastore 353 / (config=true) 354 /discard-changes 355 /exclusive-mode 356 /update 357 /validate 358 /version 360 1.2.2. YANG-API Message Examples 362 The examples within this document use the non-normative example YANG 363 module defined in Section 12. 365 This section shows some typical YANG-API message exchanges. 367 In these examples, the server capabilities are as follows: 369 o the edit-model is "direct" 371 o the persist-model is "manual" 373 o the transaction-model is "none" 375 1.2.2.1. Retrieve the Top-level API Resource 377 By default, when a resource is retrieved, all of its fields are 378 returned, but none (if any) of the nested resources are returned. 379 Also, the default encoding is JSON. Data resources are encoded 380 according to the encoding rules in [I-D.lhotka-yang-json]. 382 The client starts by retrieving the top-level API resource, using the 383 entry point URI "/yang-api". 385 GET /yang-api HTTP/1.1 386 Host: example.com 388 The server might respond as follows. The "module" lines below are 389 split for display purposes only: 391 HTTP/1.1 200 OK 392 Date: Mon, 23 Apr 2012 17:01:00 GMT 393 Server: example-server 394 Content-Type: application/vnd.yang.api+json 396 { 397 "yang-api": { 398 "capabilities": { 399 "edit-model": "direct", 400 "persist-model": "automatic", 401 "transaction-model": "none" 402 }, 403 "modules": { 404 "module": [ 405 "urn:ietf:params:xml:ns:yang:ietf-yang-api 406 ?module=ietf-yang-api&revision=2012-05-27", 407 "example.com?module=example-jukebox 408 &revision=2012-05-30" 409 ] 410 }, 411 "version": "1.0" 412 } 413 } 415 To request that the response content to be encoded in XML, the 416 "Accept" header can be used, as in this example request: 418 GET /yang-api HTTP/1.1 419 Host: example.com 420 Accept: application/vnd.yang.api+xml 422 An alternate approach is provided using the "format" query parameter, 423 as in this example request: 425 GET /yang-api?format=xml HTTP/1.1 426 Host: example.com 428 The server will return the same response either way, which might be 429 as follows : 431 HTTP/1.1 200 OK 432 Date: Mon, 23 Apr 2012 17:01:00 GMT 433 Server: example-server 434 Cache-Control: no-cache 435 Pragma: no-cache 436 Content-Type: application/vnd.yang.api+xml 438 439 440 direct 441 automatic 442 none 443 444 445 urn:ietf:params:xml:ns:yang:ietf-yang-api 446 ?module=ietf-yang-api 447 &revision=2012-05-27 448 example.com?module=example-jukebox 449 &revision=2012-05-30 450 451 1.0 452 454 Refer to Section 3.3 for details on the GET operation. 456 1.2.2.2. Create New Data Resources 458 To create a new "jukebox" resource, the client might send: 460 POST /yang-api/datastore/jukebox HTTP/1.1 461 Host: example.com 463 If the resource is created, the server might respond: 465 HTTP/1.1 201 Created 466 Date: Mon, 23 Apr 2012 17:01:00 GMT 467 Server: example-server 468 Location: http://example.com/yang-api/datastore/jukebox 469 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 470 ETag: b3a3e673be2 472 To create a new "artist" resource within the "jukebox" resource, the 473 client might send the following request, Note that the arbitrary 474 integer "index" is not provided, since it is an optional key: 476 POST /yang-api/datastore/jukebox/artist HTTP/1.1 477 Host: example.com 478 Content-Type: application/vnd.yang.data+json 480 { 481 "artist" : { 482 "name" : "The Foo Fighters" 483 } 484 } 486 If the resource is created, the server might respond: 488 HTTP/1.1 201 Created 489 Date: Mon, 23 Apr 2012 17:02:00 GMT 490 Server: example-server 491 Location: http://example.com/yang-api/datastore/jukebox/artist/1 492 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 493 ETag: b3830f23a4c 495 To create a new "album" resource for this artist within the "jukebox" 496 resource, the client might send the following request, 498 POST /yang-api/datastore/jukebox/artist/1/album HTTP/1.1 499 Host: example.com 500 Content-Type: application/vnd.yang.data+json 502 { 503 "album" : { 504 "name" : "Wasting Light", 505 "genre" : "example-jukebox:Alternative", 506 "year" : 2012 507 } 508 } 510 If the resource is created, the server might respond as follows. 511 Note that the "Location" header line is wrapped for display purposes 512 only: 514 HTTP/1.1 201 Created 515 Date: Mon, 23 Apr 2012 17:03:00 GMT 516 Server: example-server 517 Location: http://example.com/yang-api/datastore/ 518 jukebox/artist/1/album/Wasting%20Light 519 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 520 ETag: b8389233a4c 522 Refer to Section 3.4 for details on the POST operation. 524 1.2.2.3. Replace an Existing Data Resource 526 Note: replacing a resource is a fairly drastic operation. The PATCH 527 operation is often more appropriate. 529 The album sub-resource is re-added here for example purposes only. 530 To replace the "artist" resource contents, the client might send: 532 PUT /yang-api/datastore/jukebox/artist/1 HTTP/1.1 533 Host: example.com 534 If-Match: b3830f23a4c 535 Content-Type: application/vnd.yang.data+json 537 { 538 "artist" : { 539 "name" : "Foo Fighters", 540 "album" : { 541 "name" : "Wasting Light", 542 "genre" : "example-jukebox:Alternative", 543 "year" : 2012 544 } 545 } 546 } 548 If the resource is updated, the server might respond: 550 HTTP/1.1 204 No Content 551 Date: Mon, 23 Apr 2012 17:04:00 GMT 552 Server: example-server 553 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 554 ETag: b27480aeda4c 556 Refer to Section 3.5 for details on the PUT operation. 558 1.2.2.4. Patch an Existing Data Resource 560 To replace just the "year" field in the "album" resource, the client 561 might send: 563 PATCH /yang-api/datastore/jukebox/artist/1/album/ 564 Wasting%20Light/year HTTP/1.1 565 Host: example.com 566 If-Match: b8389233a4c 567 Content-Type: application/vnd.yang.data+json 569 { "year" : 2011 } 571 If the resource is updated, the server might respond: 573 HTTP/1.1 204 No Content 574 Date: Mon, 23 Apr 2012 17:49:30 GMT 575 Server: example-server 576 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 577 ETag: b2788923da4c 579 Refer to Section 3.6 for details on the PATCH operation. 581 1.2.2.5. Delete an Existing Data Resource 583 To delete a resource such as the "album" resource, the client might 584 send: 586 DELETE /yang-api/datastore/jukebox/artist/1/album/ 587 Wasting%20Light HTTP/1.1 588 Host: example.com 590 If the resource is deleted, the server might respond: 592 HTTP/1.1 204 No Content 593 Date: Mon, 23 Apr 2012 17:49:40 GMT 594 Server: example-server 596 Refer to Section 3.7 for details on the DELETE operation. 598 1.2.2.6. Invoke a Data Model Specific Operation 600 To invoke a global operation, such as the "save-datastore" operation 601 resource, the POST operation is used. A client might send a 602 "save-datastore" request as follows: 604 POST /yang-api/operations/save-datastore HTTP/1.1 605 Host: example.com 607 The server might respond: 609 HTTP/1.1 204 No Content 610 Date: Mon, 23 Apr 2012 17:50:00 GMT 611 Server: example-server 613 Refer to Section 3.9 for details on using the POST operation with 614 operation resources. 616 2. Framework 618 The YANG-API protocol defines a framework that can be used to 619 implement a common API for configuration management. This section 620 describes the components of the YANG-API framework. 622 2.1. Message Model 624 The YANG-API protocol uses HTTP entities for messages. A single HTTP 625 message corresponds to a single protocol operation in NETCONF. A 626 message can perform a single task on a single resource, such as 627 retrieving a resource or editing a resource. It cannot be used to 628 combine multiple tasks. The client cannot provide multiple (possibly 629 unrelated) edit operations within a single request, like the NETCONF 630 protocol operation. 632 2.2. Resource Model 634 The YANG-API protocol operates on a hierarchy of resources, starting 635 with the top-level API resource itself. Each resource represents a 636 manageable component within the device. 638 A resource can be considered a collection of conceptual data and the 639 set of allowed operations on that data. It can contain child nodes 640 that are either "fields" or other resources. The child resource 641 types and operations allowed on them are data-model specific. 643 A resource has its own media type identifier, represented by the 644 "Content-Type" header in the HTTP response message. A resource can 645 contain zero or more fields and zero or more resources. A resource 646 can be created and deleted independently of its parent resource, as 647 long as the parent resource exist. 649 A field is a child node defined within a resource. A field can 650 contain zero or more fields and zero or more resources. A field 651 cannot be created and deleted independently of its parent resource. 653 All YANG-API resources and fields are defined in this document except 654 datastore contents and RPC operations. These resource types are 655 defined with YANG data definition statements and the "rpc" statement. 656 A default mapping is defined to differentiate sub-resources from 657 fields within data resources. 659 2.2.1. YANG-API Resource Types 661 The YANG-API protocol defines some application specific media types 662 to identify each of the available resource types. The following 663 table summarizes the purpose of each resource. 665 +-------------+----------------------------------+ 666 | Resource | Media Type | 667 +-------------+----------------------------------+ 668 | API | application/vnd.yang.api | 669 | Datastore | application/vnd.yang.datastore | 670 | Data | application/vnd.yang.data | 671 | Operation | application/vnd.yang.operation | 672 | Transaction | application/vnd.yang.transaction | 673 +-------------+----------------------------------+ 675 YANG-API Media Types 677 These resources are described in Section 5. 679 2.2.2. Resource Discovery 681 A client SHOULD start by retrieving the top-level API resource, using 682 the entry point URI "/yang-api". 684 The YANG-API protocol does not include a resource discovery 685 mechanism. Instead, the definitions within the YANG modules 686 advertised by the server are used to construct a predictable 687 operation or data resource identifier. 689 The "depth" query parameter can be used to control how many 690 descendant levels should be included when retrieving sub-resources. 691 This parameter can be used with the GET operation to discover sub- 692 resources within a particular resource. 694 Refer to Section 3.8.2 for more details on the "depth" parameter. 696 2.3. Datastore Model 698 A conceptual "unified datastore" is used to simplify resource 699 management for the client. The YANG-API datastore is a combination 700 of the running configuration and any non-configuration data supported 701 by the device. By default only configuration data is returned by a 702 GET operation on the datastore contents. 704 The underlying NETCONF datastores can be used to implement the 705 unified datastore, but the server design is not limited to the exact 706 datastore procedures defined in NETCONF. 708 Instead of a separate candidate configuration datastore to use as a 709 globally shared scratchpad to collect edits, an optional transaction 710 mechanism is provided (see Section 2.4). 712 Instead of a separate startup configuration datastore, a simplified 713 persistence model is used (see Section 2.3.4). 715 2.3.1. Content Model 717 The YANG-API protocol operates on a conceptual datastore defined with 718 the YANG data modeling language. The server lists each YANG module 719 it supports in the "/yang-api/modules/module" field in the top-level 720 API resource type, using the YANG module capability URI format 721 defined in RFC 6020. 723 The conceptual datastore contents and data-model-specific operations 724 are identified by the set of YANG module capability URIs. All YANG- 725 API content identified as either a data resource or an operation 726 resource is defined with the YANG language. 728 The classification of data as configuration or non-configuration is 729 derived from the YANG "config" statement. Data retrieval with the 730 GET operation can be filtered in several ways, including the "config" 731 parameter to retrieve configuration or non-configuration data. 733 The classification of data as a resource or field within a resource 734 is derived from the rules specified in Section 5.3.2. 736 Data ordering behavior is derived from the YANG "ordered-by" 737 statement. Editing mechanisms are provided to allow list or leaf- 738 list resources to be inserted or moved in the same manner as NETCONF, 739 and defined in YANG. 741 The server is not required to maintain system ordered data in any 742 particular persistent order. The server SHOULD maintain the same 743 data ordering for system ordered data until the next reboot or 744 termination of the server. 746 2.3.2. Editing Model 748 The YANG-API datastore editing model is compatible with the NETCONF 749 protocol but not exactly the same. 751 If the running configuration datastore is written directly, then each 752 change takes place right away. This can have a negative impact on 753 network behavior if multiple inter-related resources need to be 754 edited at once, in order to achieve the new desired network state. 756 To address this problem, an optional transaction mechanism is defined 757 (similar to the NETCONF :candidate capability) to allow multiple 758 edits to be collected and validated, before being applied all-or- 759 nothing to the running configuration datastore. 761 Private and shared transactions are supported. If the server uses a 762 single shared datastore resource, or if multiple clients use the same 763 private transaction, then it is often useful to know if the data 764 resources being edited have changed (relative to the resource 765 versions the client thinks are on the server). 767 This can be achieved in YANG-API using the edit collision detection 768 mechanisms described in Section 2.3.2.2. If a collision is detected, 769 then the client can retrieve the resource before proceeding with the 770 edit. 772 2.3.2.1. Edit Operation Discovery 774 Sometimes a server does not implement every operation for every 775 resource. Sometimes data model requirements cause a node to 776 implement a subset of the edit operations. For example, a server may 777 not allow modification of a particular configuration data node after 778 the parent resource has been created. 780 The OPTIONS operation can be used to identify which operations are 781 supported by the server for a particular resource. For example, if 782 the server will allow a data resource node to be created then the 783 POST operation will be returned in the response. 785 2.3.2.2. Edit Collision Detection 787 Two "edit collision detection" mechanisms are provided in YANG-API, 788 for datastore and data resources. 790 o timestamp: the last change time is maintained and the 791 "Last-Modified" and "Date" headers are returned in the response 792 for a retrieval request. The "If-Unmodified-Since" header can be 793 used in edit operation requests to cause the server to reject the 794 request if the resource has been modified since the specified 795 timestamp. 797 o entity tag: a unique opaque string is maintained and the "ETag" 798 header is returned in the response for a retrieval request. The 799 "If-Match" header can be used in edit operation requests to cause 800 the server to reject the request if the resource entity tag does 801 not match the specified value. 803 Note that the server is only required to maintain these fields for a 804 datastore resource, not for individual data resources. 806 Example: 808 In this example, the server just supports the mandatory datastore 809 last-changed timestamp. The client has previously retrieved the 810 "Last-Modified" header and has some value cached to provide in the 811 following request to replace a list entry with key value "11": 813 PATCH /yang-api/datastore/jukebox/artist/1/album/ 814 Wasting%20Light/year HTTP/1.1 815 Host: example.com 816 Accept: application/vnd.yang.data+json 817 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 818 Content-Type: application/vnd.yang.data+json 820 { "year" : "2011" } 822 In this example the datastore resource has changed since the time 823 specified in the "If-Unmodified-Since" header. The server might 824 respond: 826 HTTP/1.1 304 Not Modified 827 Date: Mon, 23 Apr 2012 19:01:00 GMT 828 Server: example-server 829 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 830 ETag: b34aed893a4c 832 2.3.3. Locking Model 834 Datastore locking is needed in order to allow a client to make 835 several changes to the running configuration datastore contents in 836 sequence, without disturbance from other clients. 838 The "lock-datastore" and "unlock-datastore" operations MUST be 839 supported by the server. These correspond to the global locks 840 defined in NETCONF. Only the running configuration datastore can be 841 locked and unlocked in this manner. If the datastore is locked, then 842 direct edits and transaction commits by other clients will fail. 844 The editing model allows for concurrent transactions to occur without 845 locking, using the transaction "update" operation. This is similar 846 to the "discard-changes" operation, except that the running 847 configuration datastore is merged into the current transaction 848 datastore (instead of replacing the contents). If the "update" 849 cannot be done, a conflict error report is generated so the client 850 can manually resolve the differences. 852 A client can request exclusive write access when a transaction 853 resource is created. This is comparable to a global lock on the 854 candidate configuration datastore if the server "transaction-model" 855 capability field is set to "shared". In this case, the creation of 856 the new transaction resource will fail if another exclusive 857 transaction already exists. 859 There is no partial datastore locking (i.e., per-resource or per YANG 860 data node) at this time. Explicit partial locks are difficult to use 861 and easy to misuse. Transactions are easier for a client to use, and 862 allow more server design freedom as well. 864 2.3.4. Persistence Model 866 A client must be aware of how the server saves configuration data to 867 non-volatile storage, so the server advertises its persistence model 868 (either "automatic" or "manual"). 870 If manual persistence of the running configuration datastore is 871 required, then the "persist" operation MUST be supported by the 872 server and MUST be used by the client to save the running 873 configuration datastore contents to non-volatile storage. 875 If automatic persistence of the running configuration datastore is 876 supported by the server, then the non-volatile storage of 877 configuration changes is handled automatically by the server, and the 878 "persist" operation MUST NOT be supported by the server. 880 2.3.5. Defaults Model 882 NETCONF has a rather complex defaults handling model for leafs. 883 YANG-API attempts to avoid this complexity by restricting the 884 operations that can be applied to a resource and fields within that 885 resource. 887 The GET method returns only nodes that exist, which will be 888 determined by the server. There is no mechanism for the client to 889 ask the server for the default values that would be used for any 890 nodes not present, but some default value is in use by the server. 891 If a leaf definition has a default value, and the leaf has not been 892 given a value yet, the server SHOULD NOT return any value for the 893 leaf in the response for a GET operation. 895 2.4. Transaction Model 897 The "/yang-api/transaction" resource will be present if the server 898 supports transactions. If so, the server MUST support at least one 899 transaction at a time and MAY support multiple concurrent 900 transactions, either by one client or multiple clients. 902 The "/yang-api/capabilities/transaction-model" field in the top-level 903 API resource identifies which type of transactions the server 904 supports, either "none", "shared", or "private". If shared, then all 905 clients are sharing the same "/yang-api/transaction//datastore" 906 resource. If "private" then each instance of a "/yang-api/ 907 transaction//datastore" resource is independent of each another. 909 There are a small number of operations supported for a transaction 910 resource. 912 o commit: attempt to commit the transaction. 914 o discard-changes: replace the contents of the transaction datastore 915 to the contents of the running configuration datastore. 917 o update: merge the contents of the running configuration datastore 918 into the transaction datastore. 920 o validate: Run commit validation tests against the running 921 configuration datastore contents, according to section 8.3.3 of 922 [RFC6020]. 924 Refer to Section 5.5.4 for more details on these operations. 926 2.5. Extensibility Model 928 The YANG-API protocol is designed to be extensible for datastore 929 content and data-model specific RPC operations. New RPC operations 930 can be added without changing the entry point if they are optional 931 and do not alter any existing operations. 933 Separate namespaces for each YANG module are used. Content encoded 934 in XML will indicate the module using the "namespace" URI value in 935 the YANG module. Content encoded in JSON will indicate the module 936 using the module name specified in the YANG module. JSON encoding 937 rules for module namespaces are specified in [I-D.lhotka-yang-json]. 939 2.6. Versioning Model 941 The version of a resource instance is identified with an entity tag, 942 as defined by HTTP. The version identifiers in this section apply to 943 the version of the schema definition of a resource. There are two 944 types of schema versioning information used in the YANG-API protocol: 946 o the YANG-API protocol version 948 o data and operation resource definition versions 950 The protocol version is identified by the string used for the well- 951 known URI entry point "/yang-api". This would be changed (e.g., 952 "/yang-api2") if non-backward compatible changes are ever needed. 954 Minor version changes that do not break backward-compatibility will 955 not cause the entry point to change. 957 The API "yang-api/version" field can be used by the client to 958 identify the exact version of the YANG-API protocol implemented by 959 the server. This value will include the complete YANG-API protocol 960 version. The "/yang-api" entry point will only change (e.g., 961 "/yang-api2") if non-backward compatible changes are made to the 962 protocol. The "/yang-api/version" field MUST be updated every time 963 the protocol specification is republished. 965 The resource definition version for a data or operation resource is a 966 date string, which is the revision date of the YANG module that 967 defines the resource. The resource version for all other resource 968 types is a numeric string, defined by the "/yang-api/version" field. 970 2.7. Retrieval Filtering Model 972 There are four types of filtering for retrieval of data resources in 973 the YANG-API protocol. 975 o conditional all-or-nothing: use some conditional test mechanism in 976 the request headers and retrieve either a complete "200 OK" 977 response if the condition is met, or a "304 Not Modified" Status- 978 Line if the condition is not met. 980 o data classification: request configuration or non-configuration 981 data. 983 o subset: request a subset of all possible instances of a list or 984 leaf-list data resource. 986 o filter: request a subset of all possible descendant nodes within 987 the target resource. The "select" query parameter can be used for 988 this purpose. 990 Refer to Section 5.3.4 for details on data retrieval filtering. 992 2.8. Access Control Model 994 The YANG-API protocol provides no granular access control for any 995 content except for operation and data resources. The NETCONF Access 996 Control Model (NACM) is defined in [RFC6536]. There is a specific 997 mapping between YANG-API operations and NETCONF edit operations, 998 defined in Table 1. The resource path also needs to be converted 999 internally by the server to the corresponding YANG instance- 1000 identifier. Using this information, the server can apply the NACM 1001 access control rules to YANG-API messages. 1003 The server MUST NOT allow any operation to any resources that the 1004 client is not authorized to access. 1006 3. Operations 1008 The YANG-API protocol uses HTTP methods to identify the CRUD 1009 operation requested for a particular resource or field within a 1010 resource. The following table shows how the YANG-API operations 1011 relate to NETCONF protocol operations: 1013 +----------+-------------------------------------+ 1014 | YANG-API | NETCONF | 1015 +----------+-------------------------------------+ 1016 | OPTIONS | none | 1017 | HEAD | none | 1018 | GET | , | 1019 | POST | (operation="create") | 1020 | PUT | (operation="replace") | 1021 | PATCH | (operation="merge") | 1022 | DELETE | (operation="delete") | 1023 +----------+-------------------------------------+ 1025 Table 1: CRUD Operations in YANG-API 1027 The NETCONF "remove" operation attribute is not supported by the HTTP 1028 DELETE method. The resource must exist or the DELETE operation will 1029 fail. 1031 This section defines the YANG-API protocol usage for each HTTP 1032 method. 1034 3.1. OPTIONS 1036 The OPTIONS method is sent by the client to discover which methods 1037 are supported by the server for a specific resource, or field within 1038 a resource. It is supported for all media types. Note that 1039 implementation of this operation is part of HTTP, and this section 1040 does not introduce any additional requirements. 1042 The request MUST contain a request URI that contains at least the 1043 entry point component. 1045 The server will return a "Status-Line" header containing "204 No 1046 Content". and include the "Allow" header in the response. This 1047 header will be filled in, based on the target resource media type. 1048 Other headers MAY also be included in the response. 1050 Example 1: 1052 A client might request the methods supported for a data resource 1053 called "library" 1054 OPTIONS /yang-api/datastore/jukebox/library HTTP/1.1 1055 Host: example.com 1057 The server might respond (for a config=true list): 1059 HTTP/1.1 204 No Content 1060 Date: Mon, 23 Apr 2012 17:01:00 GMT 1061 Server: example-server 1062 Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH,DELETE 1064 Example 2: 1066 A client might request the methods supported for a non-configuration 1067 leaf within a data resource: 1069 OPTIONS /yang-api/datastore/jukebox/library/ 1070 song-count HTTP/1.1 1071 Host: example.com 1073 The server might respond: 1075 HTTP/1.1 204 No Content 1076 Date: Mon, 23 Apr 2012 17:02:00 GMT 1077 Server: example-server 1078 Allow: OPTIONS,HEAD,GET 1080 Example 3: 1082 A client might request the methods supported for an operation 1083 resource called "play": 1085 OPTIONS /yang-api/operations/play HTTP/1.1 1086 Host: example.com 1088 The server might respond: 1090 HTTP/1.1 204 No Content 1091 Date: Mon, 23 Apr 2012 17:02:00 GMT 1092 Server: example-server 1093 Allow: POST 1095 3.2. HEAD 1097 The HEAD operation is sent by the client to retrieve just the headers 1098 that would be returned for the comparable GET operation, without the 1099 response body. The HTTP HEAD method is used for this operation. It 1100 is supported for all resource types, except operation resources. 1102 The request MUST contain a request URI that contains at least the 1103 entry point component. 1105 The same query parameters supported by the GET operation are 1106 supported by the HEAD operation. For example, the "select" query 1107 parameter can be used to specify a field within the target resource. 1109 The access control behavior is enforced as if the method was GET 1110 instead of HEAD. The server MUST respond the same as if the method 1111 was GET instead of HEAD, except that no response body is included. 1113 Example: 1115 The client might request the response headers for the default (JSON) 1116 representation of the "library" resource: 1118 HEAD /yang-api/datastore/jukebox/library HTTP/1.1 1119 Host: example.com 1121 The server might respond: 1123 HTTP/1.1 200 OK 1124 Date: Mon, 23 Apr 2012 17:02:40 GMT 1125 Server: example-server 1126 Content-Type: application/vnd.yang.data+json 1127 Cache-Control: no-cache 1128 Pragma: no-cache 1129 ETag: a74eefc993a2b 1130 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1132 3.3. GET 1134 The GET operation is sent by the client to retrieve data and meta- 1135 data for a resource or field within a resource. The HTTP GET method 1136 is used for this operation. It is supported for all resource types, 1137 except operation resources. The request MUST contain a request URI 1138 that contains at least the entry point component. 1140 The following query parameters are supported by the GET operation: 1142 +--------+---------+------------------------------------------------+ 1143 | Name | Section | Description | 1144 +--------+---------+------------------------------------------------+ 1145 | config | 3.8.1 | Request either configuration or | 1146 | | | non-configuration data | 1147 | depth | 3.8.2 | Control the depth of a retrieval request | 1148 | format | 3.8.3 | Request either JSON or XML content in the | 1149 | | | response | 1150 | select | 3.8.6 | Specify a field within the target resource | 1151 +--------+---------+------------------------------------------------+ 1153 GET Query Parameters 1155 The server MUST NOT return any data resources or fields within any 1156 data resources for which the user does not have read privileges. 1158 If the user is not authorized to read any portion of the target 1159 resource, an error response containing a "403 Forbidden" Status-Line 1160 is returned to the client. 1162 If the user is authorized to read some but not all of the target 1163 resource, the unauthorized content is omitted from the response 1164 message body, and the authorized content is returned to the client. 1166 Example: 1168 The client might request the response headers for a JSON 1169 representation of the "library" resource: 1171 GET /yang-api/datastore/jukebox/library/artist/ 1172 1/album HTTP/1.1 1173 Host: example.com 1175 The server might respond: 1177 HTTP/1.1 200 OK 1178 Date: Mon, 23 Apr 2012 17:02:40 GMT 1179 Server: example-server 1180 Content-Type: application/vnd.yang.data+json 1181 Cache-Control: no-cache 1182 Pragma: no-cache 1183 ETag: a74eefc993a2b 1184 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1186 { 1187 "album" : { 1188 "name" : "Wasting Light", 1189 "genre" : "example-jukebox:Alternative", 1190 "year" : 2011 1191 } 1192 } 1194 3.4. POST 1196 The POST operation is sent by the client for various reasons. The 1197 HTTP POST method is used for this purpose. The request MUST contain 1198 a request URI that contains a target resource that identifies one of 1199 the following resource types: 1201 +-------------+--------------------------------------+ 1202 | Type | Description | 1203 +-------------+--------------------------------------+ 1204 | Data | Create a configuration data resource | 1205 | Operation | Invoke RPC operation | 1206 | Transaction | Create a new transaction | 1207 +-------------+--------------------------------------+ 1209 Resource Types that Support POST 1211 The following query parameters are supported by the POST operation: 1213 +--------+---------+-----------------------------------------+ 1214 | Name | Section | Description | 1215 +--------+---------+-----------------------------------------+ 1216 | insert | 3.8.4 | Specify where to insert a resource | 1217 | point | 3.8.5 | Specify the insert point for a resource | 1218 +--------+---------+-----------------------------------------+ 1220 POST Query Parameters 1222 If the POST operation succeeds, a "200 OK" Status-Line is returned if 1223 there is no response message body, and a "204 No Content" Status-Line 1224 is returned if there is a response message body. 1226 If the user is not authorized to invoke the target (operation) 1227 resource, or create the target resource, an error response containing 1228 a "403 Forbidden" Status-Line is returned to the client. All other 1229 error responses are handled according to the procedures defined in 1230 Section 6. 1232 3.5. PUT 1234 The PUT operation is sent by the client to replace the target 1235 resource. 1237 The HTTP PUT method is used for this purpose. The request MUST 1238 contain a request URI that contains a target resource that identifies 1239 the data resource to replace. 1241 The following query parameters are supported by the PUT operation: 1243 +--------+---------+---------------------------------------+ 1244 | Name | Section | Description | 1245 +--------+---------+---------------------------------------+ 1246 | insert | 3.8.4 | Specify where to move a resource | 1247 | point | 3.8.5 | Specify the move point for a resource | 1248 +--------+---------+---------------------------------------+ 1250 PUT Query Parameters 1252 If the PUT operation succeeds, a "200 OK" Status-Line is returned, 1253 and there is no response message body. 1255 If the user is not authorized to replace the target resource an error 1256 response containing a "403 Forbidden" Status-Line is returned to the 1257 client. All other error responses are handled according to the 1258 procedures defined in Section 6. 1260 3.6. PATCH 1262 The PATCH operation uses the HTTP PATCH method defined in [RFC5789] 1263 to provide a "merge" editing mode for data resources. Instead of 1264 replacing all or part of the target resource, the supplied values are 1265 merged into the target resource. 1267 If the PATCH operation succeeds, a "200 OK" Status-Line is returned, 1268 and there is no response message body. 1270 If the user is not authorized to alter the target resource an error 1271 response containing a "403 Forbidden" Status-Line is returned to the 1272 client. All other error responses are handled according to the 1273 procedures defined in Section 6. 1275 3.7. DELETE 1277 The DELETE operation uses the HTTP DELETE method to delete the target 1278 resource. 1280 If the DELETE operation succeeds, a "200 OK" Status-Line is returned, 1281 and there is no response message body. 1283 If the user is not authorized to delete the target resource then an 1284 error response containing a "403 Forbidden" Status-Line is returned 1285 to the client. All other error responses are handled according to 1286 the procedures defined in Section 6. 1288 3.8. Query Parameters 1290 Each YANG-API operation allows zero or more query parameters to be 1291 present in the request URI. Refer to Section 3 for details on the 1292 query parameters used in the definition of each operation. 1294 Query parameters can be given in any order. Each parameter can 1295 appear zero or one time. A default value may apply if the parameter 1296 is missing. 1298 This section defines all the YANG-API query parameters. 1300 3.8.1. "config" Parameter 1302 The "config" parameter is used to specify whether configuration or 1303 non-configuration data is requested. 1305 This parameter is only supported for the GET and HEAD methods. It is 1306 also only supported if the target resource is a data resource. 1308 syntax: config= true | false 1309 default: true 1311 Example: 1313 This example request by the client would retrieve only the non- 1314 configuration data nodes that exist within the second-level "library" 1315 resource. 1317 GET /yang-api/datastore/jukebox/library?config=false HTTP/1.1 1318 Host: example.com 1319 Accept: application/vnd.yang.data+xml 1321 The server might respond: 1323 HTTP/1.1 200 OK 1324 Date: Mon, 23 Apr 2012 17:01:30 GMT 1325 Server: example-server 1326 Cache-Control: no-cache 1327 Pragma: no-cache 1328 Content-Type: application/vnd.yang.data+json 1330 { 1331 "library" : { 1332 "artist-count" : 42, 1333 "album-count" : 59, 1334 "song-count" : 374 1335 } 1337 } 1339 3.8.2. "depth" Parameter 1341 The "depth" parameter is used to specify the number of nest levels 1342 returned in a response for a GET operation. A nest-level consists of 1343 the target resource and any child nodes which are optional data nodes 1344 (anyxml, leaf, or leaf-list). A non-presence container is 1345 transparent when determining the nest level. A child node (which is 1346 not a non-presence container) within a non-presence container is used 1347 to determine the nest-level. 1349 The start level is determined by the target resource for the 1350 operation. 1352 syntax: depth= | unbounded 1353 default: 1 1355 Example: 1357 This example operation would retrieve 2 levels of configuration data 1358 nodes that exist within the top-level "jukebox" resource. 1360 GET /yang-api/datastore/jukebox?depth=2 HTTP/1.1 1361 Host: example.com 1362 Accept: application/vnd.yang.data+json 1364 The server might respond: 1366 HTTP/1.1 200 OK 1367 Date: Mon, 23 Apr 2012 17:11:30 GMT 1368 Server: example-server 1369 Cache-Control: no-cache 1370 Pragma: no-cache 1371 Content-Type: application/vnd.yang.data+json 1373 { 1374 "jukebox" : { 1375 "library" : { 1376 "artist" : { 1377 "index" : 1, 1378 "name" : "Foo Fighters" 1379 } 1380 }, 1381 "player" : { 1382 "gap" : 0.5 1383 } 1384 } 1386 } 1388 3.8.3. "format" Parameter 1390 The "format" parameter is used to specify the format of any content 1391 returned in the response. Note that the "Accept" header MAY be used 1392 instead of this parameter to identify the format desired in the 1393 response. For example: 1395 GET /yang-api/datastore/routing HTTP/1.1 1396 Host: example.com 1397 Accept: application/vnd.yang.data+xml 1399 This example request would retrieve only the configuration data nodes 1400 that exist within the top-level "routing" resource, and retrieve them 1401 in XML encoding instead of JSON encoding. 1403 The "format" parameter is only supported for the GET and HEAD 1404 methods. It is supported for all YANG-API media types. 1406 syntax: format= xml | json 1407 default: json 1409 Example: 1411 GET /yang-api/datastore/routing?format=xml HTTP/1.1 1412 Host: example.com 1414 This example URI would retrieve only the configuration data nodes 1415 that exist within the top-level "routing" resource, and retrieve them 1416 in XML encoding instead of JSON encoding. 1418 3.8.4. "insert" Parameter 1420 The "insert" parameter is used to specify how a resource should be 1421 inserted (or moved) within the user-ordered list or leaf-list data 1422 resource. 1424 This parameter is only supported for the POST and PUT methods. It is 1425 also only supported if the target resource is a data resource, and 1426 that data represents a YANG list or leaf-list that is ordered by the 1427 user, not the system. 1429 If the values "before" or "after" are used, then a "point" parameter 1430 for the insertion parameter MUST also be present. 1432 syntax: insert= first | last | before | after 1433 default: last 1435 Example: 1437 Request from client: 1439 POST /yang-api/datastore/jukebox/library/artist/1/album 1440 /Wasting%20Light/song?insert=first HTTP/1.1 1441 Host: example.com 1442 Content-Type: application/vnd.yang.data+json 1444 { 1445 "song" : { 1446 "name" : "Bridge Burning", 1447 "location" : "/media/bridge_burning.mp3", 1448 "format" : "MP3", 1449 "length" : 286 1450 } 1451 } 1453 Response from server: 201 status 1455 HTTP/1.1 201 Created 1456 Date: Mon, 23 Apr 2012 13:01:20 GMT 1457 Server: example-server 1458 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1460 Location: http://example.com/yang-api/datastore/jukebox 1461 /library/artist/1/album?Wasting%20Light/song/1 1462 ETag: eeeada438af 1464 3.8.5. "point" Parameter 1466 The "point" parameter is used to specify the insertion point for a 1467 data resource that is being created or moved within a user ordered 1468 list or leaf-list. It is ignored unless the "insert" query parameter 1469 is also present, and has the value "before" or "after". 1471 This parameter contains the instance identifier of the resource, or 1472 field within a resource, to be used as the insertion point for a POST 1473 or PUT operation. It is encoded according to the rules defined in 1474 Section 5.3.1. There is no default for this parameter. 1476 syntax: point= 1478 Example: 1480 In this example, the client is moving an existing "song" resource 1481 within an "album" resource after another song. The request URI is 1482 split for display purposes only. 1484 Request from client: 1486 PUT /yang-api/datastore/jukebox/library/artist/1/album/ 1487 Wasting%20Light/song/2?insert=after 1488 &point=/yang-api/datastore/jukebox/library/artist/1/ 1489 album/Wasting%20Light/song/4 HTTP/1.1 1490 Host: example.com 1492 Response from server: 1494 HTTP/1.1 204 No Content 1495 Date: Mon, 23 Apr 2012 13:01:20 GMT 1496 Server: example-server 1497 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1498 ETag: abcada438af 1500 3.8.6. "select" Parameter 1502 The "select" query parameter is used to specify an expression which 1503 can represent a subset of all data nodes within the target resource. 1504 It contains a relative path expression, using the target resource as 1505 the context node. 1507 It is supported for all resource types except operation resources. 1508 The contents are encoded according to the "api-select" rule defined 1509 in Section 5.3.1. This parameter is only allowed for GET and HEAD 1510 operations. 1512 [FIXME: the syntax of the select string is still TBD; XPath, schema- 1513 identifier, regular expressions, something else] 1515 Refer to Section 1.2.2 for example request messages using the 1516 "select" parameter. 1518 3.9. RPC Operations 1520 The YANG-API also allows RPC operations to be invoked using the POST 1521 method. The media type "vnd.yang.operation+xml" or 1522 "vnd.yang.operation+json" MUST be used in the "Content-Type" field in 1523 the message header. 1525 The following datastore specific operations are defined: 1527 +------------------+------------------------------------------------+ 1528 | Operation | Description | 1529 +------------------+------------------------------------------------+ 1530 | lock-datastore | Lock the /yang-api/datastore resource for | 1531 | | writing | 1532 | save-datastore | Save the /yang-api/datastore resource to | 1533 | | NV-storage | 1534 | unlock-datastore | Unlock the /yang-api/datastore resource | 1535 +------------------+------------------------------------------------+ 1537 YANG-API Datastore Operations 1539 Refer to Section 5.2 for details on these operations. 1541 The following transaction specific operations are defined: 1543 +-----------------+-------------------------------------------------+ 1544 | Operation | Description | 1545 +-----------------+-------------------------------------------------+ 1546 | commit | Commit the transaction to the running config | 1547 | discard-changes | replace transaction data with current running | 1548 | | config | 1549 | update | merge current running config into transaction | 1550 | | data | 1551 | validate | validate transaction datastore | 1552 +-----------------+-------------------------------------------------+ 1554 YANG-API Transaction Operations 1556 Refer to Section 5.5 for details on these operations. 1558 3.9.1. Data Model Specific Operations 1560 Data model specific operations are supported. The syntax and 1561 semantics of these operations exactly correspond to the YANG rpc 1562 statement definition for the operation. 1564 Any input for a RPC operation is encoded in an element called 1565 "input", which corresponds to the element in a NETCONF 1566 message. The child nodes of the "input" element are encoded 1567 according to the data definition statements in the input section of 1568 the rpc statement. 1570 Any output for a RPC operation is encoded in an element called 1571 "output", which corresponds to the element in a NETCONF 1572 message. The child nodes of the "output" element are encoded 1573 according to the data definition statements in the output section of 1574 the rpc statement. 1576 4. Messages 1578 This section describes the messages that are used in the YANG-API 1579 protocol. 1581 4.1. Request URI Structure 1583 Resources are represented with URIs following the structure for 1584 generic URIs in [RFC3986]. 1586 A YANG-API operation is derived from the HTTP method and the request 1587 URI, using the following conceptual fields: 1589 /yang-api/?# 1591 ^ ^ ^ ^ ^ 1592 | | | | | 1593 method entry resource query fragment 1595 M M O O I 1597 M=mandatory, O=optional, I=ignored 1599 replaced by client with real values 1601 o method: the HTTP method identifying the YANG-API operation 1602 requested by the client, to act upon the target resource specified 1603 in the request URI. YANG-API operation details are described in 1604 Section 3. 1606 o entry: the well-known YANG-API entry point ("/yang-api"). 1608 o resource: the path expression identifying the resource that is 1609 being accessed by the operation. If this field is not present, 1610 then the target resource is the API itself, represented by the 1611 media type "vnd.yang.api". 1613 o query: the set of parameters associated with the YANG-API message. 1614 These have the familiar form of "name=value" pairs. There is a 1615 specific set of parameters defined, although the server MAY choose 1616 to support additional parameters not defined in this document. 1618 o fragment: This field is not used by the YANG-API protocol. 1620 The client SHOULD NOT assume the final structure of a URI path for a 1621 resource. Instead, existing resources can be discovered with the GET 1622 operation. When new resources are created by the client, a 1623 "Location" header is returned, which identifies the path of the newly 1624 created resource. The client MUST use this exact path identifier to 1625 access the resource once it has been created. 1627 The "target" of an operation is a resource. The "path" field in the 1628 request URI represents the target resource for the operation. 1630 4.2. Message Headers 1632 There are several HTTP header lines utilized in YANG-API messages. 1633 Messages are not limited to the HTTP headers listed in this section. 1635 HTTP defines which header lines are required for particular 1636 circumstances. Refer to each operation definition section in 1637 Section 3 for examples on how particular headers are used. 1639 There are some request headers that are used within YANG-API, usually 1640 applied to data resources. The following tables summarize the 1641 headers most relevant in YANG-API message requests: 1643 +---------------------+---------------------------------------------+ 1644 | Name | Description | 1645 +---------------------+---------------------------------------------+ 1646 | Accept | Response Content-Types that are acceptable | 1647 | Content-Type | The media type of the request body | 1648 | Host | The host address of the server | 1649 | If-Match | Only perform the action if the entity | 1650 | | matches ETag | 1651 | If-Modified-Since | Only perform the action if modified since | 1652 | | time | 1653 | If-Range | Only retrieve range if resource unchanged | 1654 | If-Unmodified-Since | Only perform the action if un-modified | 1655 | | since time | 1656 | Range | Specify a range of data resource entries | 1657 +---------------------+---------------------------------------------+ 1659 YANG-API Request Headers 1661 The following tables summarize the headers most relevant in YANG-API 1662 message responses: 1664 +---------------+---------------------------------------------------+ 1665 | Name | Description | 1666 +---------------+---------------------------------------------------+ 1667 | Allow | Valid actions when 405 error returned | 1668 | Content-Type | The media type of the response body | 1669 | Date | The date and time the message was sent | 1670 | ETag | An identifier for a specific version of a | 1671 | | resource | 1672 | Last-Modified | The last modified date and time of a resource | 1673 | Location | The resource identifier for a newly created | 1674 | | resource | 1675 +---------------+---------------------------------------------------+ 1677 YANG-API Response Headers 1679 4.3. Message Encoding 1681 YANG-API messages are encoded in HTTP according to RFC 2616. The 1682 "utf-8" character set is used for all messages. YANG-API message 1683 content is sent in the HTTP message body. 1685 Content is encoded in either JSON or XML format. 1687 XML encoding rules for data nodes are defined in [RFC6020]. The same 1688 encoding rules are used for all XML content. XML attributes are not 1689 used and will be ignored if present in an XML-encoded message. 1691 JSON encoding rules are defined in [I-D.lhotka-yang-json]. Special 1692 encoding rules are needed to handle multiple module namespaces and 1693 provide consistent data type processing. 1695 Request input content encoding format is identified with the Content- 1696 Type header. This field MUST be present if message input is sent by 1697 the client. 1699 Response output content encoding format is identified with the Accept 1700 header, the "format" query parameter, or if neither is specified, the 1701 request input encoding format is used. If there was no request 1702 input, then the default output encoding is JSON. File extensions 1703 encoded in the request are not used to identify format encoding. 1705 4.4. Return Status 1707 Each message represents some sort of resource access. An HTTP 1708 "Status-Line" header line is returned for each request. If a 4xx or 1709 5xx range status code is returned in the Status-Line, then the error 1710 information will be returned in the response, according to the format 1711 defined in Section 6.1. 1713 4.5. Message Caching 1715 Since the datastore contents change at unpredictable times, responses 1716 from a YANG-API server generally SHOULD NOT be cached. 1718 The server SHOULD include a "Cache-Control" header in every response 1719 that specifies whether the response should be cached. A "Pragma" 1720 header specifying "no-cache" MAY also be sent in case the 1721 "Cache-Control" header is not supported. 1723 Instead of using HTTP caching, the client SHOULD track the "ETag" 1724 and/or "Last-Modified" headers returned by the server for the 1725 datastore resource (or data resource if the server supports it). 1727 A retrieval request for a resource can include headers such as 1728 "If-None-Match" or "If-Modified-Since" which will cause the server to 1729 return a "304 Not Modified" Status-Line if the resource has not 1730 changed. 1732 The client MAY use the HEAD operation to retrieve just the message 1733 headers, which SHOULD include the "ETag" and "Last-Modified" headers, 1734 if this meta-data is maintained for the target resource. 1736 5. Resources 1738 The resources used in the YANG-API protocol are identified by the 1739 "path" component in the request URI. Each operation is performed on 1740 a target resource. 1742 5.1. API Resource (/yang-api) 1744 The API resource contains the state and access points for the YANG- 1745 API features. 1747 It is the top-level resource and has the media type "application/ 1748 vnd.yang.api+xml" or "application/vnd.yang.api+json". It is 1749 accessible through the well-known URI "/yang-api". 1751 This resource has the following fields: 1753 +--------------+--------------------------------+ 1754 | Field Name | Description | 1755 +--------------+--------------------------------+ 1756 | capabilities | Server capabilities | 1757 | datastore | Link to "datastore" resource | 1758 | operations | Global operations | 1759 | modules | YANG modules | 1760 | transaction | Link to "transaction" resource | 1761 +--------------+--------------------------------+ 1763 YANG-API Resource Fields 1765 5.1.1. /yang-api/capabilities 1767 This mandatory field represents the YANG-API server capabilities. 1768 The child nodes are read-only fields that MUST NOT change while the 1769 server is running, but MAY change after a reboot. 1771 Example: 1773 To retrieve just the YANG-API capabilities, the client might send the 1774 following request: 1776 GET /yang-api?select=capabilities HTTP/1.1 1777 Host: example.com 1779 The server might respond: 1781 HTTP/1.1 200 OK 1782 Date: Mon, 23 Apr 2012 17:10:00 GMT 1783 Server: example-server 1784 Cache-Control: no-cache 1785 Pragma: no-cache 1786 Content-Type: application/vnd.yang.api+json 1788 { 1789 "yang-api": { 1790 "capabilities": { 1791 "edit-model": "transaction", 1792 "persist-model": "manual", 1793 "transaction-model": "private" 1794 } 1795 } 1796 } 1798 5.1.1.1. /yang-api/capabilities/edit-model 1800 The "edit-model" capability field is used to identify the editing 1801 model used by the server. There are 4 supported models: 1803 o none: A server within a constrained device MAY choose to provide a 1804 read-only implementation, in which case no editing model is 1805 supported. 1807 o direct: A device MAY allow the running configuration datastore to 1808 only be modified directly, and therefore will not support 1809 transactions. 1811 o transaction: A device SHOULD support the transaction mechanism 1812 defined in this document. Datastore edits are collected in the 1813 transaction datastore and applied to the running configuration 1814 datastore with the "commit" operation. 1816 o both: A device MAY support both the direct and transaction editing 1817 models, by allowing direct editing operations on the datastore and 1818 supporting the transaction mechanism. 1820 The server SHOULD support 1 of the 2 datastore editing models, and 1821 MAY support both datastore editing models. If both are supported, 1822 then the client can decide which editing model it prefers. 1824 This field is encoded with the rules for a "bits" data type, using 1825 the following leaf definition: 1827 leaf edit-model { 1828 config false; 1829 type bits { 1830 bit direct { 1831 description 1832 "Direct writing to the datastore resource is allowed."; 1833 } 1834 bit transaction { 1835 description 1836 "Writing to the datastore via transactions is allowed."; 1837 } 1838 } 1839 } 1841 There is no default. The server MUST set zero, one, or both of these 1842 bits in the "edit-model" capability field. 1844 5.1.1.2. /yang-api/capabilities/persist-model 1846 The "persist-model" capability field is used to identify the 1847 persistence model used by the server. There are two supported 1848 models: 1850 o automatic: The server will automatically save the running 1851 configuration datastore contents to non-volatile storage. 1853 o manual: The client must manually save the running configuration 1854 datastore contents to non-volatile storage. 1856 This field is encoded with the rules for an "enumeration" data type, 1857 using the following leaf definition: 1859 leaf persist-model { 1860 config false; 1861 type enumeration { 1862 enum automatic { 1863 description 1864 "The server will automatically save the 1865 running configuration"; 1866 } 1867 enum manual { 1868 description 1869 "The client must manually save the running 1870 configuration"; 1871 } 1872 } 1873 } 1875 There is no default. The server MUST set one enumeration value in 1876 the "persist-model" capability field. 1878 5.1.1.3. /yang-api/capabilities/transaction-model 1880 The "transaction-model" capability field is used to identify the 1881 transaction model used by the server. There are 3 supported models: 1883 o none: The server does not support transactions. 1885 o shared: All clients are sharing the same conceptual transaction 1886 datastore (similar to NETCONF :candidate capability). 1888 o private: Each transaction datastore resource is independent of one 1889 another. 1891 This field is encoded with the rules for an "enumeration" data type, 1892 using the following leaf definition: 1894 leaf transaction-model { 1895 config false; 1896 type enumeration { 1897 enum none { 1898 description 1899 "The server does not support transactions."; 1900 } 1901 enum shared { 1902 description 1903 "The server supports a shared transaction datastore 1904 resource."; 1905 } 1906 enum private { 1907 description 1908 "The server supports a private transaction datastore 1909 resource."; 1910 } 1911 } 1912 } 1914 There is no default. The server MUST set one enumeration value in 1915 the "transaction-model" capability field. 1917 5.1.2. /yang-api/datastore 1919 This mandatory resource represents the running configuration 1920 datastore and any non-configuration data available. It may be 1921 retrieved and edited directly or indirectly (via transactions). It 1922 cannot be created or deleted by the client. This resource type is 1923 defined in Section 5.2. 1925 5.1.3. /yang-api/operations 1927 This optional field provides access to the global datastore and data- 1928 model specific RPC operations supported by the server. The datastore 1929 operation resources will be available depending on the server 1930 capabilities. If the server does not support any global operations, 1931 then this field SHOULD NOT not be present. 1933 There are 3 global operations defined by YANG-API. 1935 o lock-datastore 1937 o save-datastore 1939 o unlock-datastore 1941 Any data-model specific global operations derived from YANG modules 1942 supported by the server will also be available through child node 1943 resources within the "operations" field. The YANG-API defined global 1944 operations are described in this section. 1946 5.1.3.1. /yang-api/operations/lock-datastore 1948 The "lock-datastore" operation resource is used to lock the datastore 1949 resource represented by the URI "/yang-api/datastore". It behaves 1950 exactly the same as the NETCONF operation on the running 1951 configuration datastore. 1953 If the operation succeeds, a "204 No Content" value in the 1954 "Status-Line" is sent in the response. If the operation fails, the 1955 appropriate error code is set according to the rules in Section 6, 1956 and the error report is sent in the response, according to the format 1957 defined in Section 6.1. 1959 The "lock-datastore" operation does not take any parameters. The 1960 YANG "rpc" statement definition for this operation is defined in 1961 Section 8. 1963 Example: 1965 The client might request a lock on the running configuration 1966 datastore as follows: 1968 POST /yang-api/operations/lock-datastore HTTP/1.1 1969 Host: example.com 1971 If the operation succeeds the server might respond: 1973 HTTP/1.1 204 No Content 1974 Date: Mon, 23 Apr 2012 17:03:00 GMT 1975 Server: example-server 1977 If the operation fails the server might respond: 1979 HTTP/1.1 204 No Content 1980 Date: Mon, 23 Apr 2012 17:03:00 GMT 1981 Server: example-server 1983 5.1.3.2. /yang-api/operations/save-datastore 1985 The "save-datastore" operation resource is used to save the datastore 1986 resource represented by the URI "/yang-api/datastore" to non-volatile 1987 storage. It behaves exactly the same as the NETCONF 1988 operation when used to copy the running configuration datastore to 1989 the startup configuration datastore. 1991 If the operation succeeds, a "204 No Content" value in the 1992 "Status-Line" is sent in the response. If the operation fails, the 1993 appropriate error code is set according to the rules in Section 6, 1994 and the error report is sent in the response, according to the format 1995 defined in Section 6.1. 1997 The "save-datastore" operation does not take any parameters. The 1998 YANG "rpc" statement definition for this operation is defined in 1999 Section 8. 2001 Example: 2003 The client might request that the running configuration datastore be 2004 saved in non-volatile storage as follows: 2006 POST /yang-api/operations/save-datastore HTTP/1.1 2007 Host: example.com 2009 If the operation succeeds the server might respond: 2011 HTTP/1.1 204 No Content 2012 Date: Mon, 23 Apr 2012 17:03:00 GMT 2013 Server: example-server 2015 If the operation fails the server might respond: 2017 HTTP/1.1 204 No Content 2018 Date: Mon, 23 Apr 2012 17:03:00 GMT 2019 Server: example-server 2021 5.1.3.3. /yang-api/operations/unlock-datastore 2023 The "unlock-datastore" operation resource is used to unlock the 2024 datastore resource represented by the URI "/yang-api/datastore". It 2025 behaves exactly the same as the NETCONF operation on the 2026 running configuration datastore. 2028 If the operation succeeds, a "204 No Content" value in the 2029 "Status-Line" is sent in the response. If the operation fails, the 2030 appropriate error code is set according to the rules in Section 6, 2031 and the error report is sent in the response, according to the format 2032 defined in Section 6.1. 2034 The "unlock-datastore" operation does not take any parameters. The 2035 YANG "rpc" statement definition for this operation is defined in 2036 Section 8. 2038 Example: 2040 The client might release a lock on the running configuration 2041 datastore as follows: 2043 POST /yang-api/operations/unlock-datastore HTTP/1.1 2044 Host: example.com 2046 If the operation succeeds the server might respond: 2048 HTTP/1.1 204 No Content 2049 Date: Mon, 23 Apr 2012 17:03:00 GMT 2050 Server: example-server 2052 If the operation fails the server might respond: 2054 HTTP/1.1 204 No Content 2055 Date: Mon, 23 Apr 2012 17:03:00 GMT 2056 Server: example-server 2058 5.1.4. /yang-api/modules 2060 This mandatory field contains the identifiers for the YANG data model 2061 modules supported by the server. There MUST be exactly one instance 2062 of this field. 2064 The server MUST maintain a last-modified timestamp for this field, 2065 and return the "Last-Modified" header when this field is retrieved 2066 with the GET or HEAD methods. 2068 5.1.4.1. /yang-api/modules/module 2070 This mandatory field contains one URI string for each YANG data model 2071 module supported by the server. There MUST be an instance of this 2072 field for every YANG module that is accessible via an operation 2073 resource or a data resource. 2075 The server MAY maintain a last-modified timestamp for each instance 2076 of this resource, and return the "Last-Modified" header when this 2077 resource is retrieved with the GET or HEAD methods. If not supported 2078 then the timestamp for the parent "modules" field MUST NOT be used 2079 instead. 2081 The contents of this field are encoded with the "uri" derived type 2082 from the "ietf-iana-types" modules in [RFC6021]. 2084 There are additional encoding requirements for this field. The URI 2085 MUST follow the YANG module capability URI formatting defined in 2086 section 5.6.4 of [RFC6020]. 2088 5.1.4.2. Retrieval Example 2090 In this example the client is retrieving the modules field from the 2091 server in the default JSON format: 2093 GET /yang-api?select=modules HTTP/1.1 2094 Host: example.com 2095 Accept: application/vnd.yang.api+json 2097 The server might respond as follows. Note that the content below is 2098 split across multiple lines for display purposes only: 2100 HTTP/1.1 200 OK 2101 Date: Mon, 23 Apr 2012 17:01:00 GMT 2102 Server: example-server 2103 Cache-Control: no-cache 2104 Pragma: no-cache 2105 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 2106 Content-Type: application/vnd.yang.api+json 2108 { 2109 "yang-api": { 2110 "modules": { 2111 "module": [ 2112 "example.com?module=foo&revision=2012-01-02", 2113 "example.com?module=bar&revision=2011-10-10" 2114 "example.com?module=itf&revision=2011-10-10 2115 &feature=restore" 2116 ] 2117 } 2118 } 2119 } 2121 5.1.5. /yang-api/transaction 2123 This optional resource will be supported if the server implements 2124 transactions, identified by the "/yang-api/capabilities/edit-model" 2125 field in the API resource. It is used to allow one or more 2126 individual edits to be applied (all-or-nothing) to the running 2127 configuration datastore, and to facilitate concurrent editing 2128 transactions with a mechanism to update the transaction datastore 2129 contents with the latest running configuration datastore contents. 2131 This resource is defined in Section 5.5. 2133 5.1.6. /yang-api/version 2135 This mandatory field identifies the specific version of the YANG-API 2136 protocol implemented by the server. 2138 The same server-wide response MUST be returned each time this field 2139 is retrieved. It is assigned by the server when the server is 2140 started. The server MUST return the value "1.0" for this version of 2141 the YANG-API protocol. 2143 This field is encoded with the rules for an "enumeration" data type, 2144 using the following leaf definition: 2146 leaf version { 2147 config false; 2148 type enum { 2149 enum "1.0" { 2150 description 2151 "Version 1.0 of the YANG-API protocol."; 2152 } 2153 } 2154 } 2156 5.2. Datastore Resource 2158 A datastore resource represents the conceptual root of a tree of data 2159 resources. 2161 The server MUST maintain a last-modified timestamp for this resource, 2162 and return the "Last-Modified" header when this resource is retrieved 2163 with the GET or HEAD methods. Only changes to configuration data 2164 resources within the datastore affect this timestamp. 2166 The server SHOULD maintain a resource entity tag for this resource, 2167 and return the "ETag" header when this resource is retrieved with the 2168 GET or HEAD methods. The resource entity tag SHOULD be changed to a 2169 new previously unused value if changes to any configuration data 2170 resources within the datastore are made. 2172 A datastore resource can be retrieved with the GET operation, to 2173 retrieve either configuration data resources or non-configuration 2174 data resources within the datastore. The "config" query parameter is 2175 used to choose between them. Refer to Section 3.8.1 for more 2176 details. 2178 The depth of the subtrees returned in retrieval operations can be 2179 controlled with the "depth" query parameter. The number of nest 2180 levels, starting at the target resource, can be specified, or an 2181 unlimited number can be returned. Refer to Section 3.8.2 for more 2182 details. 2184 A datastore resource cannot be written directly with any edit 2185 operation. Only the configuration data resources within the 2186 datastore resource can be edited. 2188 5.3. Data Resource 2190 A data resource represents a YANG data node that is a descendant node 2191 of a datastore resource. 2193 For configuration data resources, the server MAY maintain a last- 2194 modified timestamp for the resource, and return the "Last-Modified" 2195 header when it is retrieved with the GET or HEAD methods. 2197 For configuration data resources, the server MAY maintain a resource 2198 entity tag for the resource, and return the "ETag" header when it is 2199 retrieved as the target resource with the GET or HEAD methods. The 2200 resource entity tag SHOULD be changed to a new previously unused 2201 value if changes to the resource or any configuration field within 2202 the resource is altered. 2204 A data resource can be retrieved with the GET operation, to retrieve 2205 either configuration data resources or non-configuration data 2206 resources within the target resource. The "config" query parameter 2207 is used to choose between them. Refer to Section 3.8.1 for more 2208 details. 2210 The depth of the subtrees returned in retrieval operations can be 2211 controlled with the "depth" query parameter. The number of nest 2212 levels, starting at the target resource, can be specified, or an 2213 unlimited number can be returned. Refer to Section 3.8.2 for more 2214 details. 2216 A configuration data resource can be altered by the client with some 2217 of all of the edit operations, depending on the target resource and 2218 the specific operation. Refer to Section 3 for more details on edit 2219 operations. 2221 5.3.1. Encoding YANG Instance Identifiers in the Request URI 2223 In YANG, data nodes are named with an absolute XPath expression, from 2224 the document root to the target resource. In YANG-API, URL friendly 2225 path expressions are used instead. 2227 The YANG "instance-identifier" (i-i) data type is represented in 2228 YANG-API with the path expression format defined in this section. 2230 +-------+-------------------------------------------+ 2231 | Name | Comments | 2232 +-------+-------------------------------------------+ 2233 | point | Insertion point is always a full i-i | 2234 | path | Request URI path is a full or partial i-i | 2235 +-------+-------------------------------------------+ 2237 YANG-API instance-identifier Type Conversion 2239 The "path" component of the request URI contains the absolute path 2240 expression that identifies the target resource. The "select" query 2241 parameter is used to optionally identify the requested data nodes 2242 within the target resource to be retrieved in a GET operation. 2244 A predictable location for a data resource is important, since 2245 applications will code to the YANG data model module, which uses 2246 static naming and defines an absolute path location for all data 2247 nodes. 2249 A YANG-API data resource identifier is not an XPath expression. It 2250 is encoded from left to right, starting with the top-level data node, 2251 according to the "api-path" rule in Section 5.3.1.1. The node name 2252 of each ancestor of the target resource node is encoded in order, 2253 ending with the node name for the target resource. 2255 If the "select" is present, it is encoded, starting with a child node 2256 of the target resource, according to the "api-select" rule defined in 2257 Section 5.3.1.1. 2259 If a data node in the path expression is a YANG list node, then the 2260 key values for the list (if any) are encoded according to the 2261 "key-value" rule. If the list node is the target resource, then the 2262 key values MAY be omitted, according to the operation. For example, 2263 the POST operation to create a new data resource for a list node does 2264 not allow the key values to be present in the request URI. 2266 The key leaf values for a data resource representing a YANG list MUST 2267 be encoded as follows: 2269 o The value of each leaf identified in the "key" statement is 2270 encoded in order. 2272 o All the components in the "key" statement MUST be encoded. 2273 Partial instance identifiers are not supported. 2275 o Each value is encoded using the "key-value" rule in 2276 Section 5.3.1.1, according to the encoding rules for the data type 2277 of the key leaf. 2279 o An empty string can be a valid key value (e.g., "/top/list/key1// 2280 key3"). 2282 o The "/" character MUST be URL-encoded (i.e., "%2F"). 2284 o All whitespace MUST be URL-encoded. 2286 o A "null" value is not allowed since the "empty" data type is not 2287 allowed for key leafs. 2289 o The XML encoding is defined in [RFC6020]. 2291 o The JSON encoding is defined in [I-D.lhotka-yang-json]. 2293 o The entire "key-value" MUST be properly URL-encoded, according to 2294 the rules defined in [RFC3986]. 2296 Examples: 2298 /yang-api/datastore/jukebox/library/artist/17&select=name 2300 /yang-api/datastore/newlist/17&select=nextlist/22/44/myleaf 2302 /yang-api/datastore/somelist/fred%20and%20wilma 2304 /yang-api/datastore/somelist/fred%20and%20wilma/address 2306 5.3.1.1. ABNF For Data Resource Identifiers 2308 The following ABNF syntax is used to construct YANG-API path 2309 identifiers: 2311 api-path = "/" api-identifier 2312 0*("/" (api-identifier | key-value )) 2314 [FIXME: the syntax for the select string is still TBD] 2315 api-select = api-identifier 2316 0*("/" (api-identifier | key-value )) 2318 api-identifier = [module-name ":"] identifier 2320 module-name = identifier 2322 key-value = string 2324 ;; An identifier MUST NOT start with 2325 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 2326 identifier = (ALPHA / "_") 2327 *(ALPHA / DIGIT / "_" / "-" / ".") 2329 string = 2331 5.3.2. Identifying YANG-defined Data Resources 2333 The data resources used in YANG-API are defined with YANG data 2334 definition statements. 2336 Not every data node defined in a YANG module should be treated as a 2337 resource. The YANG-API needs to know which YANG data nodes are 2338 resources, and which are fields within a resource. 2340 For data resources, YANG-API uses a simple algorithm for defining 2341 resource boundaries, within the conceptual sub-trees described by 2342 YANG data definition statements. 2344 All top-level data nodes are considered to be resources. For nodes 2345 within a top-level resource: 2347 o a presence container starts a new resource 2349 o a list starts a new resource 2351 o an optional terminal node (anyxml, leaf, or leaf-list) starts a 2352 new resource 2354 o a data node of type "anyxml" cannot have any sub-resources 2356 A non-configuration data node cannot be a separate resource from its 2357 parent. Only top-level data nodes are considered to be resources 2358 (which only support retrieval methods). 2360 5.3.3. Identifying Optional Keys 2362 It is sometimes useful to have the server assign the key(s) for a new 2363 resource. The "Location" header will indicate the key value(s) that 2364 the server selected, so the client does not need to provide all the 2365 key leaf values. 2367 It is useful to identify in the YANG data model module which key 2368 leafs are optional to provide, and which are not. The YANG extension 2369 statement "optional-key" is provided to indicate that the leaf 2370 definition represents an optional key. 2372 The client MAY provide a value for a key leaf in a POST operation. 2373 Refer to Section 8 for details on the "optional-key" extension. 2374 Refer to Section 12 for usage examples of this YANG extension 2375 statement. 2377 5.3.4. Data Resource Retrieval 2379 There are four types of filtering for retrieval of data resources. 2380 This section defines each mode. 2382 5.3.4.1. Conditional Retrieval 2384 The HTTP headers (such as "If-Modified-Since" and "If-Match") can by 2385 used in for a request message for a GET operation to check a 2386 condition within the server state, such as the last time the 2387 datastore resource was modified, or the resource entity tag of the 2388 target resource. 2390 If the condition is met according to the header definition, a "200 2391 OK" Status-Line and the data requested is returned in the response 2392 message. If the condition is not met, a "304 Not Modified" Status- 2393 Line is returned in response message instead. 2395 5.3.4.2. Data Classification Retrieval 2397 The "config" query parameter can be used with the GET operation to 2398 specify whether configuration or non-configuration data is requested. 2399 Refer to Section 3.8.1 for more details on the "config" query 2400 parameter. 2402 5.3.4.3. Subset Retrieval 2404 The "Range" header is used to request a specific subset of the 2405 instances of a list or leaf-list data resource that are returned by 2406 the server for a retrieval operation. Normally, if the target 2407 resource in a request message does not specify an instance, then all 2408 instances are returned. 2410 The YANG-API protocol uses the token "entries" instead of "bytes" as 2411 the range units. 2413 The entries are numbered starting from "0". A list or leaf-list can 2414 change order between requests so the client needs to be aware of the 2415 data model semantics, and whether the list contents are stable enough 2416 to use the subset retrieval mechanism. 2418 If the requested range cannot be returned because the range 2419 specification includes index values for entries that do not exist, 2420 then an error occurs, and the server MUST return a "416 Requested 2421 range not satisfiable" Status-Line. 2423 If the range request can be satisfied, then a "200 OK" Status-Line is 2424 returned, and the response MUST include a "Content-Range" header 2425 indicating which entries are returned. The response message body 2426 contains the data for the requested range of entries. 2428 Example: 2430 In this example, the client is requesting 5 "artist" resource 2431 entries, starting with the 10th entry: 2433 Request from client: 2435 GET /yang-api/datastore/jukebox/library/artist HTTP/1.1 2436 Host: example.com 2437 Accept: application/vnd.yang.data+json 2438 Range: entries 10-14 2440 Response from server: 2442 HTTP/1.1 200 OK 2443 Date: Mon, 23 Apr 2012 13:01:20 GMT 2444 Cache-Control: no-cache 2445 Pragma: no-cache 2446 Content-Type: application/vnd.yang.data+json 2447 Content-Range: entries 10-14 2448 Server: example-server 2449 Last-Modified: Mon, 23 Apr 2012 02:12:20 GMT 2450 ETag: abcada438af 2452 { 2453 "artist" : { 2454 // content removed for brevity 2455 } 2456 } 2458 5.3.4.4. Filtered Retrieval 2460 The "select" query parameter is used to specify a filter that should 2461 be applied to the target resource to request a subset of all possible 2462 descendant nodes within the target resource. 2464 The format of the "select" parameter string is defined in 2465 Section 3.8.6. The set of nodes selected by the filter expression is 2466 applied to each context node identified by the target resource. 2468 5.4. Operation Resource 2470 An operation resource represents an RPC operation defined with the 2471 YANG "rpc" statement. 2473 All operation resources share the same module namespace as any top- 2474 level data resources, so the name of an operation resource cannot 2475 conflict with the name of a top-level data resource defined within 2476 the same module. 2478 If 2 different YANG modules define the same "rpc" identifier, then 2479 the module name MUST be used in the request URI. For example, if 2480 "module-A" and "module-B" both defined a "reset" operation, then 2481 invoking the operation from "module-A" would be requested as follows: 2483 POST /yang-api/operations/module-A:reset HTTP/1.1 2484 Server example.com 2486 Any usage of an operation resource from the same module, with the 2487 same name, refers to the same "rpc" statement definition. This 2488 behavior can be used to design RPC operations that perform the same 2489 general function on different resource types. 2491 If the "rpc" statement has an "input" section, then a message body 2492 MAY be sent by the client in the request, otherwise the request 2493 message MUST NOT include a message body. If the "rpc" statement has 2494 an "output" section, then a message body MAY be sent by the server in 2495 the response. Otherwise the server MUST NOT include a message body 2496 in the response message, and MUST send a "204 No Content" Status-Line 2497 instead. 2499 5.4.1. Encoding Operation Input Parameters 2501 If the "rpc" statement has an "input" section, then the "input" node 2502 is provided in the message body, corresponding to the YANG data 2503 definition statements within the "input" section. 2505 Example: 2507 The following YANG definition is used for the examples in this 2508 section. 2510 rpc reboot { 2511 input { 2512 leaf delay { 2513 units seconds; 2514 type uint32; 2515 default 0; 2516 } 2517 leaf message { type string; } 2518 leaf language { type string; } 2519 } 2520 } 2522 The client might send the following POST request message: 2524 POST /yang-api/datastore/operations/reboot HTTP/1.1 2525 Host: example.com 2526 Content-Type: application/vnd.yang.data+json 2528 { 2529 "input" : { 2530 "delay" : 600, 2531 "message" : "Going down for system maintenance", 2532 "language" : "en-US" 2533 } 2534 } 2536 The server might respond: 2538 HTTP/1.1 204 No Content 2539 Date: Mon, 25 Apr 2012 11:01:00 GMT 2540 Server: example-server 2542 5.4.2. Encoding Operation Output Parameters 2544 If the "rpc" statement has an "output" section, then the "output" 2545 node is provided in the message body, corresponding to the YANG data 2546 definition statements within the "output" section. 2548 Example: 2550 The following YANG definition is used for the examples in this 2551 section. 2553 rpc get-reboot-info { 2554 input { 2555 leaf reboot-time { 2556 units seconds; 2557 type uint32; 2558 } 2559 leaf message { type string; } 2560 leaf language { type string; } 2561 } 2562 } 2564 The client might send the following POST request message: 2566 POST /yang-api/datastore/operations/get-reboot-info HTTP/1.1 2567 Host: example.com 2569 The server might respond: 2571 HTTP/1.1 200 OK 2572 Date: Mon, 25 Apr 2012 11:10:30 GMT 2573 Server: example-server 2574 Content-Type: application/vnd.yang.data+json 2576 { 2577 "output" : { 2578 "reboot-time" : 30, 2579 "message" : "Going down for system maintenance", 2580 "language" : "en-US" 2581 } 2582 } 2584 5.4.3. Identifying YANG-defined Operation Resources 2586 The operation resources used in YANG-API are defined with YANG "rpc" 2587 statements. All "rpc" statements within a YANG module that are 2588 supported by the server are available as operation resources. 2590 5.5. Transaction Resource 2592 The "transaction" resource type is used to construct a set of one or 2593 more edit operations on data resources within a "scratchpad" 2594 datastore resource. The transaction can be committed when the client 2595 decides the data resource edits are complete. The transaction can 2596 also be reverted and updated, as described later in this section. 2598 This resource type will only be supported if the "edit-model" 2599 capabilities field in the API resource includes the value 2600 "transaction". If transactions are supported, then the server will 2601 allow the client to create, use, and delete transaction resources. 2603 The POST operation is used to create a new transaction resource. The 2604 DELETE operation is used to cleanup and delete an existing 2605 transaction resource. The PUT and PATCH operations are not supported 2606 for this resource type. 2608 The media type for the transaction resource type is either 2609 "application/vnd.yang.transaction+xml" or "application/ 2610 vnd.yang.transaction+json". 2612 The procedures for editing the transaction datastore contents are the 2613 same as those for editing the running configuration datastore except 2614 the changes do not take effect right away and the datastore integrity 2615 validation tests are not done until the transaction is committed to 2616 running configuration datastore. 2618 The following steps are typically followed to use transaction 2619 resources: 2621 o create a transaction resource using the URI "/yang-api/ 2622 transaction". 2624 o the server will allocate a new transaction and return its resource 2625 ID. 2627 o add/alter/delete data resources within the scratchpad datastore 2629 o commit the transaction to the running configuration datastore. 2631 o delete the transaction resource 2633 5.5.1. Creating a Transaction Resource 2635 In order to reduce the complexity of query parameters and allow 2636 easier extensibility of transaction resource creation, the 2637 configuration parameters for the transaction are sent in the request 2638 message for the POST operation. 2640 The only parameter at this time is the "exclusive-mode" parameter, 2641 which is used by the client to request that no other transactions or 2642 direct edits are allowed to alter the running configuration datastore 2643 while the exclusive mode transaction resource exists. An exclusive 2644 mode transaction if the server transaction-model is "shared" is 2645 conceptually equivalent in NETCONF to global locks on both the 2646 "candidate" and "running" datastores. 2648 The following YANG leaf definition is used for the "exclusive-mode" 2649 parameter, for encoding purposes: 2651 leaf exclusive-mode { 2652 type boolean; 2653 default false; 2654 description "Exclusive transaction mode"; 2655 } 2657 When a transaction resource is created by the client, the server will 2658 generate an opaque string to identify the transaction. This 2659 transaction ID will be used by the server in the resource ID for the 2660 new transaction. 2662 If the server uses a shared transaction model, then the transaction 2663 ID MAY be the same for multiple transaction resources. Otherwise the 2664 server SHOULD use a unique identifier for each transaction resource. 2666 The server does not ensure exclusive access to a particular 2667 transaction. The access control mechanisms for sharing transactions 2668 is out of scope for this document. 2670 After a transaction has been successfully created, it can be accessed 2671 via the "Location" header returned in the response message. 2673 Example: 2675 The following message shows an exclusive transaction resource 2676 request. The client might send: 2678 POST /yang-api/transaction HTTP/1.1 2679 Host: example.com 2680 Content-Type: application/vnd.yang.transaction+json 2682 { 2683 "transaction" : { 2684 "exclusive-mode" : true 2685 } 2686 } 2688 The server might reply: 2690 HTTP/1.1 201 Created 2691 Date: Mon, 23 Apr 2012 17:01:00 GMT 2692 Server: example-server 2693 Location: http://example.com/yang-api/transaction/12345 2694 Last-Modified: Mon, 23 Apr 2012 19:48:00 GMT 2695 ETag: b38830de24c 2697 5.5.2. Editing a Transaction Datastore 2699 When a transaction resource is created, the server will create a 2700 child datastore resource, which is a conceptual scratchpad for 2701 collecting edits to later be applied all at once to the running 2702 configuration datastore. The initial contents of this datastore are 2703 the contents of the running configuration datastore at the time the 2704 transaction is created. 2706 After a transaction has been successfully created, it can be accessed 2707 by using the previously retrieved "Location" header value in the 2708 request URI of new request messages. This datastore resource is a 2709 child node of the resource ID node, identified by a URI. 2711 For example, the "path" component of a request URI for a datastore 2712 resource (for transaction ID "12345") would be: 2714 "/yang-api/transaction/12345/datastore" 2716 The client can add, edit, or delete the data resources within the 2717 transaction datastore. Refer to Section 5.3 for details on editing 2718 data resources. 2720 Example: 2722 The following message shows the creation of a new "artist" resource 2723 within the "jukebox" resource. The request URI is split across lines 2724 for display purposes only. 2726 The client might send: 2728 POST /yang-api/transaction/12345/datastore/jukebox/ 2729 library/artist HTTP/1.1 2730 Host: example.com 2731 Content-Type: application/vnd.yang.data+json 2733 { 2734 "artist" : { 2735 "name" : "Miles Davis" 2736 } 2737 } 2739 The server might reply as follows. The "Location" header is split 2740 across lines for display purposes only. 2742 HTTP/1.1 201 Created 2743 Date: Mon, 24 Apr 2012 11:01:00 GMT 2744 Server: example-server 2745 Location: http://example.com/yang-api/transaction/ 2746 12345/datastore/jukebox/library/artist/2 2747 Last-Modified: Mon, 24 Apr 2012 11:01:00 GMT 2748 ETag: b38830de24c 2750 5.5.3. Deleting a Transaction Resource 2752 Once a client is finished with a transaction resource, it SHOULD be 2753 deleted by the client. A transaction resource is not deleted when a 2754 commit is completed. The DELETE operation is used to terminate the 2755 transaction, and discard the transaction database and all its data 2756 resource contents. 2758 Example: 2760 The following message shows the deletion of an existing transaction 2761 resource. 2763 The client might send: 2765 DELETE /yang-api/transaction/12345 2766 Host: example.com 2768 The server might reply as follows. 2770 HTTP/1.1 204 No Content 2771 Date: Mon, 24 Apr 2012 12:01:00 GMT 2772 Server: example-server 2774 5.5.4. Transaction Operations 2776 There are a small number of operation resources available for 2777 transaction resources. These are protocol operations beyond the 2778 basic CRUD operations allowed for the data resources within the 2779 transaction datastore. 2781 5.5.4.1. commit 2783 The "commit" operation is used to apply the contents of the 2784 transaction datastore to the running configuration datastore. 2786 If this operation succeeds then a "204 No Content" Status-Line is 2787 sent in the response message. If the operation fails, the 2788 appropriate error code is set according to the rules in Section 6, 2789 and the error report is sent in the response, according to the format 2790 defined in Section 6.1. 2792 Example: 2794 The following message exchange shows a commit operation. The client 2795 might send: 2797 POST /yang-api/transaction/12345/commit 2798 Host: example.com 2800 The server might reply as follows: 2802 HTTP/1.1 204 No Content 2803 Date: Mon, 25 Apr 2012 01:21:00 GMT 2804 Server: example-server 2805 Last-Modified: Mon, 25 Apr 2012 01:21:00 GMT 2806 ETag: ab34530de24c 2808 5.5.4.2. discard-changes 2810 The "discard-changes" operation is used to replace the contents of 2811 the transaction datastore with the contents of the running 2812 configuration datastore. 2814 If this operation succeeds then a "204 No Content" Status-Line is 2815 sent in the response message. If the operation fails, the 2816 appropriate error code is set according to the rules in Section 6, 2817 and the error report is sent in the response, according to the format 2818 defined in Section 6.1. 2820 Example: 2822 The following message exchange shows a discard-changes operation. 2823 The client might send: 2825 POST /yang-api/transaction/12345/discard-changes 2826 Host: example.com 2828 The server might reply as follows. 2830 HTTP/1.1 204 No Content 2831 Date: Mon, 25 Apr 2012 01:22:00 GMT 2832 Server: example-server 2833 Last-Modified: Mon, 25 Apr 2012 01:22:00 GMT 2834 ETag: ee3498de24c 2836 5.5.4.3. update 2838 The "update" operation is used to merge the contents of the running 2839 configuration datastore into the transaction datastore. If any 2840 editing conflicts are detected that cannot be resolved by the server, 2841 then the update operation MUST fail, and the transaction datastore 2842 contents MUST remain unchanged after the operation is completed. 2844 If this operation succeeds then a "204 No Content" Status-Line is 2845 sent in the response message. If the operation fails, the 2846 appropriate error code is set according to the rules in Section 6, 2847 and the error report is sent in the response, according to the format 2848 defined in Section 6.1. 2850 Example: 2852 The following message exchange shows an update operation. The client 2853 might send: 2855 POST /yang-api/transaction/12345/update 2856 Host: example.com 2858 The server might reply as follows. 2860 HTTP/1.1 204 No Content 2861 Date: Mon, 25 Apr 2012 01:32:00 GMT 2862 Server: example-server 2863 Last-Modified: Mon, 25 Apr 2012 01:32:00 GMT 2864 ETag: ab23984de125 2866 5.5.4.4. validate 2868 The "validate" operation is used to validate the contents of the 2869 transaction datastore. The server will verify that the transaction 2870 datastore can be committed to the running configuration datastore. 2871 If any editing conflicts are detected which cannot be resolved by the 2872 server, then the update operation MUST fail. 2874 If this operation succeeds then a "204 No Content" Status-Line is 2875 sent in the response message. If the operation fails, the 2876 appropriate error code is set according to the rules in Section 6, 2877 and the error report is sent in the response, according to the format 2878 defined in Section 6.1. 2880 Example: 2882 The following message exchange shows a validate operation. The 2883 client might send: 2885 POST /yang-api/transaction/12345/validate 2886 Host: example.com 2888 The server might reply as follows. 2890 HTTP/1.1 204 No Content 2891 Date: Mon, 25 Apr 2012 01:42:00 GMT 2892 Server: example-server 2893 Last-Modified: Mon, 25 Apr 2012 01:32:00 GMT 2894 ETag: ab23984de125 2896 6. Error Reporting 2898 HTTP Status-Lines are used to report success or failure for YANG-API 2899 operations. The element returned in NETCONF error 2900 responses contains some useful information. This error information 2901 is adapted for use in YANG-API, and error information is returned for 2902 "4xx" class of status codes. 2904 The following table summarizes the return status codes used 2905 specifically by YANG-API operations: 2907 +-------------------------------+-----------------------------------+ 2908 | Status-Line | Description | 2909 +-------------------------------+-----------------------------------+ 2910 | 100 Continue | POST accepted, 201 should follow | 2911 | 200 OK | Success with response body | 2912 | 201 Created | POST to create a resource success | 2913 | 202 Accepted | POST to create a resource | 2914 | | accepted | 2915 | 204 No Content | Success without response body | 2916 | 304 Not Modified | Conditional operation not done | 2917 | 400 Bad Request | Invalid request message | 2918 | 403 Forbidden | Access to resource denied | 2919 | 404 Not Found | Resource target or resource node | 2920 | | not found | 2921 | 405 Method Not Allowed | Method not allowed for target | 2922 | | resource | 2923 | 409 Conflict | Resource or lock in use | 2924 | 413 Request Entity Too Large | too-big error | 2925 | 414 Request-URI Too Large | too-big error | 2926 | 415 Unsupported Media Type | non YANG-API media type | 2927 | 416 Requested range not | If-Range error | 2928 | satisfiable | | 2929 | 500 Internal Server Error | operation-failed | 2930 | 501 Not Implemented | unknown-operation | 2931 | 503 Service Unavailable | Recoverable server error | 2932 +-------------------------------+-----------------------------------+ 2934 HTTP Status Codes used in YANG-API 2936 Since an operation resource is defined with a YANG "rpc" statement, a 2937 mapping between the NETCONF value and the HTTP status 2938 code is needed. The specific error condition and response code to 2939 use are data-model specific and might be contained in the YANG 2940 "description" statement for the "rpc" statement. 2942 +-------------------------+-------------+ 2943 | | status code | 2944 +-------------------------+-------------+ 2945 | in-use | 409 | 2946 | invalid-value | 400 | 2947 | too-big | 413 | 2948 | missing-attribute | 400 | 2949 | bad-attribute | 400 | 2950 | unknown-attribute | 400 | 2951 | bad-element | 400 | 2952 | unknown-element | 400 | 2953 | unknown-namespace | 400 | 2954 | access-denied | 403 | 2955 | lock-denied | 409 | 2956 | resource-denied | 409 | 2957 | rollback-failed | 500 | 2958 | data-exists | 409 | 2959 | data-missing | 409 | 2960 | operation-not-supported | 501 | 2961 | operation-failed | 500 | 2962 | partial-operation | 500 | 2963 | malformed-message | 400 | 2964 +-------------------------+-------------+ 2966 Mapping from error-tag to status code 2968 6.1. Error Response Message 2970 When an error occurs for a request message on a data resource or an 2971 operation resource, and a "4xx" class of status codes (except for 2972 status code "403"), then the server SHOULD send a response body 2973 containing the information described by the following YANG data 2974 definition statement: 2976 container errors { 2977 config false; 2979 list error { 2980 reference "RFC 6241, Section 4.3"; 2981 leaf error-type { 2982 mandatory true; 2983 type enumeration { 2984 enum transport; 2985 enum rpc; 2986 enum protocol; 2987 enum application; 2988 } 2989 } 2990 leaf error-tag { 2991 mandatory true; 2992 type string; 2993 } 2994 leaf error-app-tag { 2995 type string; 2996 } 2997 leaf error-path { 2998 type string; // YANG-API encoded instance-identifier 2999 } 3000 leaf error-message { 3001 type string; 3002 } 3003 container error-info { 3004 // anyxml content here 3005 } 3006 } 3007 } 3009 Example: 3011 The following example shows an error returned for an "lock-denied" 3012 error on a datastore resource. 3014 POST /yang-api/operations/lock-datastore HTTP/1.1 3015 Host: example.com 3017 The server might respond: 3019 HTTP/1.1 409 Conflict 3020 Date: Mon, 23 Apr 2012 17:11:00 GMT 3021 Server: example-server 3022 Content-Type: application/vnd.yang.api+json 3024 { 3025 "errors": { 3026 "error": { 3027 "error-type": "protocol", 3028 "error-tag": "lock-denied", 3029 "error-message": "Lock failed, lock is already held", 3030 } 3031 } 3032 } 3034 7. RelaxNG Grammar 3036 TBD 3038 8. YANG-API module 3040 RFC Ed.: update the date below with the date of RFC publication and 3041 remove this note. 3043 file "ietf-yang-api@2012-05-27.yang" 3045 module ietf-yang-api { 3046 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-api"; 3047 prefix "api"; 3049 organization 3050 "IETF NETCONF (Network Configuration) Working Group"; 3052 contact 3053 "Editor: Andy Bierman 3054 3056 Editor: Martin Bjorklund 3057 "; 3059 description 3060 "This module contains a collection of YANG language extensions 3061 to describe REST API Resources using YANG data definition 3062 statements. 3064 Copyright (c) 2012 IETF Trust and the persons identified as 3065 authors of the code. All rights reserved. 3067 Redistribution and use in source and binary forms, with or 3068 without modification, is permitted pursuant to, and subject 3069 to the license terms contained in, the Simplified BSD License 3070 set forth in Section 4.c of the IETF Trust's Legal Provisions 3071 Relating to IETF Documents 3072 (http://trustee.ietf.org/license-info). 3074 This version of this YANG module is part of RFC XXXX; see 3075 the RFC itself for full legal notices."; 3077 // RFC Ed.: replace XXXX with actual RFC number and remove this 3078 // note. 3080 // RFC Ed.: remove this note 3081 // Note: extracted from draft-bierman-netconf-yang-api-00.txt 3083 // RFC Ed.: update the date below with the date of RFC publication 3084 // and remove this note. 3085 revision 2012-05-27 { 3086 description 3087 "Initial revision."; 3088 reference 3089 "RFC XXXX: YANG-API Protocol."; 3090 } 3092 /* 3093 * Extensions 3094 */ 3096 extension optional-key { 3097 description 3098 "This extension is used to allow the client to create 3099 a new instance of a resource without providing a 3100 value for the key leaf containing this statement. 3101 This extension is ignored for NETCONF, and only 3102 applies to YANG-API resources and fields. 3103 This extension is ignored unless it appears 3104 directly within a 'leaf' data definition statement."; 3105 } 3107 /* 3108 * Operations 3109 */ 3111 rpc lock-datastore { 3112 description 3113 "Lock the running configuration datastore for writing."; 3114 } 3116 rpc save-datastore { 3117 description 3118 "Save the running configuration datastore to non-volatile 3119 storage."; 3120 } 3122 rpc unlock-datastore { 3123 description 3124 "Unlock the running configuration datastore."; 3125 } 3127 rpc commit { 3128 description 3129 "Commit the transaction datastore contents to 3130 the running configuration datastore."; 3131 } 3132 rpc discard-changes { 3133 description 3134 "Replace the transaction datastore contents with 3135 the running configuration datastore contents."; 3136 } 3138 rpc update { 3139 description 3140 "Attempt to merge the running configuration datastore 3141 contents into the transaction datastore contents."; 3142 } 3144 rpc validate { 3145 description 3146 "Validate the transaction datastore contents."; 3147 } 3149 } 3151 3153 9. IANA Considerations 3155 TBD 3157 10. Security Considerations 3159 TBD 3161 11. Open Issues 3163 o Resource creation order and other dependencies between resources 3164 are not well identified in YANG. YANG has leafrefs and instance- 3165 identifiers, which can be used to identify some order 3166 dependencies. Are any new mechanisms needed in YANG-API needed to 3167 identify resource creation order and other dependency 3168 requirements? 3170 o There is no "message-id" field in a YANG-API message. Is a 3171 message identifier needed? If so, should either the "Message-ID" 3172 or "Content-ID" header from RFC 2392 be used for this purpose? 3174 o The non-configuration data resources are combined with the 3175 configuration data resources within the YANG-API datastore. The 3176 "config" query parameter is used to pick 1 or the other for GET 3177 operations. Is this the best way to deal with YANG config-stmt? 3178 Should YANG-API follow the same data classifications as YANG (i.e. 3179 config=true|false), or create something new? Note that 3180 transactions are config=true only, like the candidate datastore in 3181 NETCONF. 3183 o Should confirmed commit be added? If so, how? Should NETCONF 3184 "confirmed-commit" procedure be used exactly for the transaction 3185 commit operation, or should a new procedure be defined? 3187 o Should datastore operations be added for "backup" and "restore" 3188 functionality? 3190 o Should sessions be used or not? Should "reusable sessions" be 3191 used? Better for auditing? How does locking of the /yang-api/ 3192 datastore resource work for multiple edits if a session is 1 3193 operation? When does the server release the lock and decide it 3194 has been abandoned or client was disconnected? 3196 o What syntax should be used for the "select" query parameter? 3198 o Should the "/yang-api/modules" field within the API resource be a 3199 separate resource, with its own timestamp? Currently the API 3200 timestamp is coupled to any changes to the list of loaded modules. 3201 Should the API resource be static and cacheable? 3203 o How should resource discovery be done? 3205 o What to do about no REMOVE operation, just DELETE? The effect is 3206 local to the request; in a NETCONF edit-config it is worse, since 3207 the netconf request might create/delete/modify many nodes 3209 o Should every YANG data node be a data resource and every YANG RPC 3210 statement an operation resource? Is a YANG extension needed to 3211 allow data modeler control of resource boundaries? 3213 o Encoding of leafrefs? Is there some additional meta-data needed? 3214 Do leafref nodes need to be identified in responses (RFC 5988) or 3215 is the YANG module definition sufficient to provide this meta- 3216 data? 3218 o What should the default algorithm be for defining data resources? 3219 Should the default for an augment from another namespace be to 3220 start a new resource? Top-level data node defaults as a resource 3221 OK? 3223 o Is the token "entries" legal in the YANG-API usage of Range? What 3224 units should be used? "bytes" is the only token defined by HTTP. 3226 o How should private transaction conflicts be handled? Currently up 3227 to the server to decide how to handle conflicts. What happens if 3228 there are transactions A and B. A commits. Next, B commits w/o 3229 updating. Will A's changes be lost? Maybe. Detecting conflicts 3230 may require a very resource-intensive implementation on the server 3231 - may force the server to create a copy of the entire datastore 3232 for each transaction. Want to allow a transaction to be just a 3233 diff-set towards the datastore, so transactions are cheap. 3235 o Does the shared transaction work like the candidate wrt to locks? 3236 I.e. will an exclusive transaction start fail if there are 3237 uncommitted changes? 3239 o Need to specify the update/commit procedure in more detail so that 3240 there is some server flexibility and client can tell what the 3241 server will do? E.g., what causes a conflict? When is update 3242 required before commit? 3244 o Are all header lines used by YANG-API supported by common 3245 application frameworks, such as FastCGI and WSGI? If not, then 3246 should query parameters be used instead, since the QUERY_STRING is 3247 widely available to WEB applications? 3249 o Should the element returned in error responses be a 3250 separate media type? 3252 o Locks tied to sessions, but if don't have sessions, then how do 3253 locks work? 3255 o Should locks be modeled as resources as operations. I.e., remove 3256 lock-datastore and unlock-datastore operations. and transactions 3257 will be required (exclusive mode) to write more than one operation 3258 at a time with exclusive access. 3260 o Should the writable-running (direct mode) be removed and just have 3261 transaction resources, which will hide writes to running config? 3263 o Should POST to create a new transaction for a shared candidate be 3264 needed? Could get the same transaction ID back each ime? 3265 Predictable resource needed instead? 3267 o Do changes to the shared transaction show up in all copies when 3268 the change is made? 3270 o How can private transactions be shared securely? Are any new 3271 access control mechanisms needed? 3273 12. Example YANG Module 3275 module example-jukebox { 3277 namespace "http://example.com/ns/example-jukebox"; 3278 prefix "jbox"; 3280 import ietf-yang-api { prefix api; } 3282 organization "Example, Inc."; 3283 description "Example Jukebox Data Model Module"; 3284 revision "2012-05-30"; 3286 identity genre { 3287 description "Base for all genre types"; 3288 } 3290 // abbreviated list of genre classifications 3291 identity Alternative { 3292 base genre; 3293 } 3294 identity Blues { 3295 base genre; 3296 } 3297 identity Country { 3298 base genre; 3299 } 3300 identity Jazz { 3301 base genre; 3302 } 3303 identity Pop { 3304 base genre; 3305 } 3306 identity Rock { 3307 base genre; 3308 } 3310 container jukebox { 3311 presence 3312 "An empty container indicates that the jukebox 3313 service is available"; 3315 container library { 3316 list artist { 3317 key index; 3318 unique name; 3319 leaf index { 3320 api:optional-key; 3321 type uint32; 3322 description 3323 "Optional key used instead of natural key for 3324 example. Also rare but possible artists with 3325 the same name are really different entities."; 3326 } 3327 leaf name { 3328 type string; 3329 } 3331 list album { 3332 key name; 3333 leaf name { 3334 type string { 3335 length "1 .. max"; 3336 } 3337 } 3338 leaf genre { 3339 type identityref { base genre; } 3340 } 3341 leaf year { 3342 type uint16 { 3343 range "1900 .. max"; 3344 } 3345 } 3346 list song { 3347 api:optional-key; 3348 key index; 3349 ordered-by user; 3350 leaf index { 3351 type uint32; 3352 } 3353 leaf name { 3354 mandatory true; 3355 type string; 3356 } 3357 leaf location { 3358 mandatory true; 3359 type string; 3360 } 3361 leaf format { 3362 type string; 3363 } 3364 leaf length { 3365 units "seconds"; 3366 type uint32; 3368 } 3369 } 3370 } 3371 } 3372 leaf artist-count { 3373 config false; 3374 type uint32; 3375 units "songs"; 3376 description "Number of artists in the library"; 3377 } 3378 leaf album-count { 3379 config false; 3380 type uint32; 3381 units "albums"; 3382 description "Number of albums in the library"; 3383 } 3384 leaf song-count { 3385 type uint32; 3386 units "songs"; 3387 description "Number of songs in the library"; 3388 } 3389 } 3391 list playlist { 3392 description 3393 "Example configuration data resource"; 3394 key name; 3395 leaf name { 3396 type string; 3397 } 3398 leaf description { 3399 type string; 3400 } 3401 list song { 3402 description 3403 "Example nested configuration data resource"; 3404 ordered-by user; 3405 key index; 3406 leaf index { 3407 api:optional-key; 3408 type uint32; 3409 } 3410 leaf id { 3411 mandatory true; 3412 type instance-identifier; 3413 description 3414 "Song identifier. Must identify an instance of 3415 /jukebox/library/artist/album/song. 3417 The id is not the key to allow duplicates 3418 in a playlist"; 3419 } 3420 } 3421 } 3423 container player { 3424 leaf gap { 3425 description "Time gap between each song"; 3426 units "tenths of seconds"; 3427 type decimal64 { 3428 fraction-digits 1; 3429 range "0.0 .. 2.0"; 3430 } 3431 } 3432 } 3433 } 3435 rpc play { 3436 description "Control function for the jukebox player"; 3437 input { 3438 leaf playlist { 3439 type string; 3440 mandatory true; 3441 description "playlist name"; 3442 } 3443 leaf song-number { 3444 type uint32; 3445 mandatory true; 3446 description "Song number in playlist to play"; 3447 } 3448 } 3449 } 3450 } 3452 13. Normative References 3454 [I-D.lhotka-yang-json] 3455 Lhotka, L., "Modeling JSON Text with YANG", 3456 draft-lhotka-yang-json-00 (work in progress), April 2012. 3458 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3459 Requirement Levels", BCP 14, RFC 2119, March 1997. 3461 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3462 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3463 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3465 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3466 Resource Identifier (URI): Generic Syntax", STD 66, 3467 RFC 3986, January 2005. 3469 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 3470 RFC 5789, March 2010. 3472 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 3473 Network Configuration Protocol (NETCONF)", RFC 6020, 3474 October 2010. 3476 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 3477 October 2010. 3479 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3480 and A. Bierman, Ed., "Network Configuration Protocol 3481 (NETCONF)", RFC 6241, June 2011. 3483 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 3484 Protocol (NETCONF) Access Control Model", RFC 6536, 3485 March 2012. 3487 Authors' Addresses 3489 Andy Bierman 3490 YumaWorks 3492 Email: andy@yumaworks.com 3494 Martin Bjorklund 3495 Tail-f Systems 3497 Email: mbj@tail-f.com