idnits 2.17.1 draft-bierman-netconf-yang-api-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 4 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 1508 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 (November 30, 2012) is 4164 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 (-02) exists of draft-lhotka-netmod-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: June 3, 2013 Tail-f Systems 6 November 30, 2012 8 YANG-API Protocol 9 draft-bierman-netconf-yang-api-01 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 June 3, 2013. 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. Simple Subset of NETCONF Functionality . . . . . . . . . . 4 53 1.2. Data Model Driven API . . . . . . . . . . . . . . . . . . 5 54 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 55 1.3.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 6 56 1.3.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . 7 57 1.3.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 1.3.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 8 59 1.4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 8 60 1.4.1. Resource URI Map . . . . . . . . . . . . . . . . . . . 9 61 1.4.2. YANG-API Message Examples . . . . . . . . . . . . . . 9 62 2. Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 15 63 2.1. Message Model . . . . . . . . . . . . . . . . . . . . . . 15 64 2.2. Resource Model . . . . . . . . . . . . . . . . . . . . . . 15 65 2.2.1. YANG-API Resource Types . . . . . . . . . . . . . . . 15 66 2.2.2. Resource Discovery . . . . . . . . . . . . . . . . . . 16 67 2.3. Datastore Model . . . . . . . . . . . . . . . . . . . . . 16 68 2.3.1. Content Model . . . . . . . . . . . . . . . . . . . . 17 69 2.3.2. Editing Model . . . . . . . . . . . . . . . . . . . . 17 70 2.3.3. Locking Model . . . . . . . . . . . . . . . . . . . . 19 71 2.3.4. Persistence Model . . . . . . . . . . . . . . . . . . 19 72 2.3.5. Defaults Model . . . . . . . . . . . . . . . . . . . . 19 73 2.4. Transaction Model . . . . . . . . . . . . . . . . . . . . 20 74 2.5. Extensibility Model . . . . . . . . . . . . . . . . . . . 20 75 2.6. Versioning Model . . . . . . . . . . . . . . . . . . . . . 20 76 2.7. Retrieval Filtering Model . . . . . . . . . . . . . . . . 21 77 2.8. Access Control Model . . . . . . . . . . . . . . . . . . . 21 78 3. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 22 79 3.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 22 80 3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 81 3.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 82 3.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 83 3.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 84 3.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 27 85 3.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 27 86 3.8. Query Parameters . . . . . . . . . . . . . . . . . . . . . 28 87 3.8.1. "config" Parameter . . . . . . . . . . . . . . . . . . 28 88 3.8.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 29 89 3.8.3. "format" Parameter . . . . . . . . . . . . . . . . . . 30 90 3.8.4. "insert" Parameter . . . . . . . . . . . . . . . . . . 30 91 3.8.5. "point" Parameter . . . . . . . . . . . . . . . . . . 31 92 3.8.6. "select" Parameter . . . . . . . . . . . . . . . . . . 32 93 3.9. Protocol Operations . . . . . . . . . . . . . . . . . . . 32 94 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 95 4.1. Request URI Structure . . . . . . . . . . . . . . . . . . 34 96 4.2. Message Headers . . . . . . . . . . . . . . . . . . . . . 35 97 4.3. Message Encoding . . . . . . . . . . . . . . . . . . . . . 36 98 4.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 36 99 4.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 37 100 5. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 38 101 5.1. API Resource (/yang-api) . . . . . . . . . . . . . . . . . 38 102 5.1.1. /yang-api/datastore . . . . . . . . . . . . . . . . . 38 103 5.1.2. /yang-api/modules . . . . . . . . . . . . . . . . . . 38 104 5.1.3. /yang-api/operations . . . . . . . . . . . . . . . . . 38 105 5.1.4. /yang-api/version . . . . . . . . . . . . . . . . . . 40 106 5.2. Datastore Resource . . . . . . . . . . . . . . . . . . . . 41 107 5.3. Data Resource . . . . . . . . . . . . . . . . . . . . . . 41 108 5.3.1. Encoding YANG Instance Identifiers in the Request 109 URI . . . . . . . . . . . . . . . . . . . . . . . . . 42 110 5.3.2. Identifying YANG-defined Data Resources . . . . . . . 44 111 5.3.3. Identifying Optional Keys . . . . . . . . . . . . . . 45 112 5.3.4. Data Resource Retrieval . . . . . . . . . . . . . . . 45 113 5.4. Operation Resource . . . . . . . . . . . . . . . . . . . . 47 114 5.4.1. Encoding Operation Input Parameters . . . . . . . . . 48 115 5.4.2. Encoding Operation Output Parameters . . . . . . . . . 49 116 5.4.3. Identifying YANG-defined Operation Resources . . . . . 50 117 6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 51 118 6.1. Error Response Message . . . . . . . . . . . . . . . . . . 52 119 7. RelaxNG Grammar . . . . . . . . . . . . . . . . . . . . . . . 55 120 8. YANG-API module . . . . . . . . . . . . . . . . . . . . . . . 56 121 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 58 122 10. Security Considerations . . . . . . . . . . . . . . . . . . . 59 123 11. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 60 124 11.1. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 60 125 12. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 61 126 13. Example YANG Module . . . . . . . . . . . . . . . . . . . . . 63 127 14. Normative References . . . . . . . . . . . . . . . . . . . . . 67 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 68 130 1. Introduction 132 There is a need for standard mechanisms to allow WEB applications to 133 access the configuration data, operational data, and data-model 134 specific protocol operations within a networking device, in a modular 135 and extensible manner. 137 This document describes a RESTful protocol called YANG-API, running 138 over HTTP [RFC2616], for accessing data defined in YANG [RFC6020], 139 using datastores defined in NETCONF [RFC6241]. 141 The NETCONF protocol defines configuration datastores and a set of 142 Create, Retrieve, Update, Delete (CRUD) operations that can be used 143 to access these datastores. The YANG language defines the syntax and 144 semantics of datastore content and operational data. RESTful 145 operations are used to access the hierarchical data within a 146 datastore. 148 A RESTful API can be created that provides CRUD operations on a 149 NETCONF datastore containing YANG-defined data. This can be done in 150 a simplified manner, compatible with HTTP and RESTful design 151 principles. Since NETCONF protocol operations are not relevant, the 152 user should not need any prior knowledge of NETCONF in order to use 153 the RESTful API. 155 Configuration data and state data are exposed as resources that can 156 be retrieved with the GET method. Resources representing 157 configuration data can be modified with the DELETE, PATCH, POST, and 158 PUT methods. Data-model specific protocol operations defined with 159 the YANG "rpc" statement can be invoked with the POST method. 161 1.1. Simple Subset of NETCONF Functionality 163 The framework and meta-model used for a RESTful API does not need to 164 mirror those used by the NETCONF protocol. It just needs to be 165 compatible with NETCONF. A simplified framework and protocol is 166 needed that utilizes the three NETCONF datastores (candidate, 167 running, startup), but hides the complexity of multiple datastores 168 from the client. 170 A simplified transaction model is needed that allows basic CRUD 171 operations on a hierarchy of conceptual resources. This represents a 172 limited subset of the transaction capabilities of the NETCONF 173 protocol. 175 Applications that require more complex transaction capabilities might 176 consider NETCONF instead of YANG-API. The following transaction 177 features are not provided in YANG-API: 179 o datastore locking (full or partial) 181 o candidate datastore 183 o validate operation 185 o confirmed-commit procedure 187 The RESTful API is not intended to replace NETCONF, but rather 188 provide an additional simplified interface that follows RESTful 189 principles and is compatible with a resource-oriented device 190 abstraction. It is expected that applications that need the full 191 feature set of NETCONF such as notifications will continue to use 192 NETCONF. 194 The following figure shows the system components: 196 +-----------+ +-----------------+ 197 | WEB app | <-------> | | 198 +-----------+ HTTP | network device | 199 | | 200 +-----------+ | +-----------+ | 201 | NMS app | <-------> | | datastore | | 202 +-----------+ NETCONF | +-----------+ | 203 +-----------------+ 205 1.2. Data Model Driven API 207 YANG-API combines the simplicity of a RESTful API over HTTP with the 208 predictability and automation potential of a schema-driven API. 210 A RESTful client using YANG-API will not use any data modelling 211 language to define the application-specific content of the API. The 212 client would discover each new child resource as it traverses the 213 URIs return as Location IDs to discover the server capabilities. 215 This approach has 3 significant weaknesses wrt/ control of complex 216 networking devices: 218 o inefficient performance: configuration APIs will be quite complex 219 and may require thousands of protocol messages to discover all the 220 schema information. Typically the data type information has to be 221 passed in the protocol messages, which is also wasteful overhead. 223 o no data model richness: without a data model, the schema-level 224 semantics and validation constraints are not available to the 225 application. Data model modules such as YANG modules serve as an 226 "API contract" that will be honored by the server. An application 227 designer can code to the data model, knowing in advance important 228 details about the exact protocol operations and datastore content 229 a conforming server implementation will support. 231 o no tool automation: API automation tools need some sort of content 232 schema to function. Such tools can automate various programming 233 and documentation tasks related to specific data models. 235 YANG-API provides the YANG module capability information supported by 236 the server, in case the client wants to use it. The URIs for custom 237 protocol operations and datastore content are predictable, based on 238 the YANG module definitions. Note that the YANG modules and 239 predictable URIs are optional to use by the client. They can be 240 completely ignored without any loss of protocol functionality. 242 Operational experience with CLI and SNMP indicates that operators 243 learn the 'location' of specific service or device related data and 244 do not expect such information to be arbitrary and discovered each 245 time the client opens a management session to a server. 247 1.3. Terminology 249 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 250 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 251 "OPTIONAL" in this document are to be interpreted as described in BCP 252 14, [RFC2119]. 254 1.3.1. NETCONF 256 The following terms are defined in [RFC6241]: 258 o candidate configuration datastore 260 o client 262 o configuration data 264 o datastore 266 o configuration datastore 268 o protocol operation 270 o running configuration datastore 272 o server 273 o startup configuration datastore 275 o state data 277 o user 279 1.3.2. HTTP 281 The following terms are defined in [RFC2616]: 283 o entity tag 285 o fragment 287 o header line 289 o message body 291 o method 293 o path 295 o query 297 o request URI 299 o response body 301 1.3.3. YANG 303 The following terms are defined in [RFC6020]: 305 o container 307 o data node 309 o key leaf 311 o leaf 313 o leaf-list 315 o list 317 o presence container (or P-container) 319 o RPC operation (now called protocol operation) 320 o non-presence container (or NP-container) 322 o ordered-by system 324 o ordered-by user 326 1.3.4. Terms 328 The following terms are used within this document: 330 o API resource: a resource with the media type "application/ 331 vnd.yang.api+xml" or ""application/vnd.yang.api+json". 333 o data resource: a resource with the media type "application/ 334 vnd.yang.data+xml" or "application/vnd.yang.data+json". 336 o datastore resource: a resource with the media type "application/ 337 vnd.yang.datastore+xml" or "application/vnd.yang.datastore+json" 339 o edit operation: a YANG-API operation on a data resource using the 340 POST, PUT, PATCH, or DELETE method. 342 o operation: the conceptual YANG-API operation for a message, 343 derived from the method, request URI, headers, and message body. 345 o operation resource: a resource with the media type 346 "vnd.yang.operation+xml" or "vnd.yang.operation+json" 348 o optional key: a key leaf for a YANG list data node, which MAY be 349 omitted by the client when an instance of the list is created. 351 o query parameter: a parameter (and its value if any), encoded 352 within the query portion of the request URI. 354 o resource: a conceptual object representing a manageable component 355 within a device. 357 o retrieval request: an operation using the GET or HEAD methods. 359 o target resource: the resource that is associated with a particular 360 message, identified by the "path" component of the request URI. 362 1.4. Overview 364 This document defines the YANG-API protocol, a RESTful API for 365 accessing conceptual datastores containing data defined with YANG 366 language. YANG-API provides an application framework and meta-model, 367 using HTTP operations. 369 The YANG-API resources are accessed via a set of URIs defined in this 370 document. The set of YANG modules supported by the server will 371 determine the additional data model specific operations and top-level 372 data node resources available on the server. 374 1.4.1. Resource URI Map 376 The URI hierarchy for the YANG-API resources consists of an entry 377 point and up to 4 top-level resources and/or fields. Refer to 378 Section 5 for details on each URI. 380 /yang-api 381 /datastore 382 / (config=true or false) 383 /modules 384 /module 385 /operations 386 / 387 /version 389 1.4.2. YANG-API Message Examples 391 The examples within this document use the non-normative example YANG 392 module defined in Section 13. 394 This section shows some typical YANG-API message exchanges. 396 1.4.2.1. Retrieve the Top-level API Resource 398 By default, when a resource is retrieved, all of its fields are 399 returned, but none (if any) of the nested resources are returned. 400 Also, the default encoding is JSON. Data resources are encoded 401 according to the encoding rules in [I-D.lhotka-netmod-json]. 403 The client starts by retrieving the top-level API resource, using the 404 entry point URI "/yang-api". 406 GET /yang-api HTTP/1.1 407 Host: example.com 409 The server might respond as follows. The "module" lines below are 410 split for display purposes only: 412 HTTP/1.1 200 OK 413 Date: Mon, 23 Apr 2012 17:01:00 GMT 414 Server: example-server 415 Content-Type: application/vnd.yang.api+json 417 { 418 "yang-api": { 419 "modules": { 420 "module": [ 421 "urn:ietf:params:xml:ns:yang:ietf-yang-api 422 ?module=ietf-yang-api&revision=2012-05-27", 423 "example.com?module=example-jukebox 424 &revision=2012-05-30" 425 ] 426 }, 427 "version": "1.0" 428 } 429 } 431 To request that the response content to be encoded in XML, the 432 "Accept" header can be used, as in this example request: 434 GET /yang-api HTTP/1.1 435 Host: example.com 436 Accept: application/vnd.yang.api+xml 438 An alternate approach is provided using the "format" query parameter, 439 as in this example request: 441 GET /yang-api?format=xml HTTP/1.1 442 Host: example.com 444 The server will return the same response either way, which might be 445 as follows : 447 HTTP/1.1 200 OK 448 Date: Mon, 23 Apr 2012 17:01:00 GMT 449 Server: example-server 450 Cache-Control: no-cache 451 Pragma: no-cache 452 Content-Type: application/vnd.yang.api+xml 453 454 455 urn:ietf:params:xml:ns:yang:ietf-yang-api 456 ?module=ietf-yang-api 457 &revision=2012-05-27 458 example.com?module=example-jukebox 459 &revision=2012-05-30 460 461 1.0 462 464 Refer to Section 3.3 for details on the GET operation. 466 1.4.2.2. Create New Data Resources 468 To create a new "jukebox" resource, the client might send: 470 POST /yang-api/datastore/jukebox HTTP/1.1 471 Host: example.com 473 If the resource is created, the server might respond: 475 HTTP/1.1 201 Created 476 Date: Mon, 23 Apr 2012 17:01:00 GMT 477 Server: example-server 478 Location: http://example.com/yang-api/datastore/jukebox 479 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 480 ETag: b3a3e673be2 482 To create a new "artist" resource within the "jukebox" resource, the 483 client might send the following request, Note that the arbitrary 484 integer "index" is not provided, since it is an optional key: 486 POST /yang-api/datastore/jukebox/artist HTTP/1.1 487 Host: example.com 488 Content-Type: application/vnd.yang.data+json 490 { 491 "artist" : { 492 "name" : "The Foo Fighters" 493 } 494 } 496 If the resource is created, the server might respond: 498 HTTP/1.1 201 Created 499 Date: Mon, 23 Apr 2012 17:02:00 GMT 500 Server: example-server 501 Location: http://example.com/yang-api/datastore/jukebox/artist/1 502 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 503 ETag: b3830f23a4c 505 To create a new "album" resource for this artist within the "jukebox" 506 resource, the client might send the following request, 508 POST /yang-api/datastore/jukebox/artist/1/album HTTP/1.1 509 Host: example.com 510 Content-Type: application/vnd.yang.data+json 512 { 513 "album" : { 514 "name" : "Wasting Light", 515 "genre" : "example-jukebox:Alternative", 516 "year" : 2012 517 } 518 } 520 If the resource is created, the server might respond as follows. 521 Note that the "Location" header line is wrapped for display purposes 522 only: 524 HTTP/1.1 201 Created 525 Date: Mon, 23 Apr 2012 17:03:00 GMT 526 Server: example-server 527 Location: http://example.com/yang-api/datastore/ 528 jukebox/artist/1/album/Wasting%20Light 529 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 530 ETag: b8389233a4c 532 Refer to Section 3.4 for details on the POST operation. 534 1.4.2.3. Replace an Existing Data Resource 536 Note: replacing a resource is a fairly drastic operation. The PATCH 537 operation is often more appropriate. 539 The album sub-resource is re-added here for example purposes only. 540 To replace the "artist" resource contents, the client might send: 542 PUT /yang-api/datastore/jukebox/artist/1 HTTP/1.1 543 Host: example.com 544 If-Match: b3830f23a4c 545 Content-Type: application/vnd.yang.data+json 547 { 548 "artist" : { 549 "name" : "Foo Fighters", 550 "album" : { 551 "name" : "Wasting Light", 552 "genre" : "example-jukebox:Alternative", 553 "year" : 2012 554 } 555 } 556 } 558 If the resource is updated, the server might respond: 560 HTTP/1.1 204 No Content 561 Date: Mon, 23 Apr 2012 17:04:00 GMT 562 Server: example-server 563 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 564 ETag: b27480aeda4c 566 Refer to Section 3.5 for details on the PUT operation. 568 1.4.2.4. Patch an Existing Data Resource 570 To replace just the "year" field in the "album" resource, the client 571 might send: 573 PATCH /yang-api/datastore/jukebox/artist/1/album/ 574 Wasting%20Light/year HTTP/1.1 575 Host: example.com 576 If-Match: b8389233a4c 577 Content-Type: application/vnd.yang.data+json 579 { "year" : 2011 } 581 If the resource is updated, the server might respond: 583 HTTP/1.1 204 No Content 584 Date: Mon, 23 Apr 2012 17:49:30 GMT 585 Server: example-server 586 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 587 ETag: b2788923da4c 589 Refer to Section 3.6 for details on the PATCH operation. 591 1.4.2.5. Delete an Existing Data Resource 593 To delete a resource such as the "album" resource, the client might 594 send: 596 DELETE /yang-api/datastore/jukebox/artist/1/album/ 597 Wasting%20Light HTTP/1.1 598 Host: example.com 600 If the resource is deleted, the server might respond: 602 HTTP/1.1 204 No Content 603 Date: Mon, 23 Apr 2012 17:49:40 GMT 604 Server: example-server 606 Refer to Section 3.7 for details on the DELETE operation. 608 1.4.2.6. Invoke a Data Model Specific Operation 610 To invoke a data-model specific operation via an operation resource, 611 the POST operation is used. A client might send a "backup-datastore" 612 request as follows: 614 POST /yang-api/operations/backup-datastore HTTP/1.1 615 Host: example.com 617 The server might respond: 619 HTTP/1.1 204 No Content 620 Date: Mon, 23 Apr 2012 17:50:00 GMT 621 Server: example-server 623 Refer to Section 3.9 for details on using the POST operation with 624 operation resources. 626 2. Framework 628 The YANG-API protocol defines a framework that can be used to 629 implement a common API for configuration management. This section 630 describes the components of the YANG-API framework. 632 2.1. Message Model 634 The YANG-API protocol uses HTTP entities for messages. A single HTTP 635 message corresponds to a single protocol operation. A message can 636 perform a single task on a single resource, such as retrieving a 637 resource or editing a resource. It cannot be used to combine 638 multiple tasks. The client cannot provide multiple (possibly 639 unrelated) edit operations within a single request, like the NETCONF 640 protocol operation. 642 2.2. Resource Model 644 The YANG-API protocol operates on a hierarchy of resources, starting 645 with the top-level API resource itself. Each resource represents a 646 manageable component within the device. 648 A resource can be considered a collection of conceptual data and the 649 set of allowed operations on that data. It can contain child nodes 650 that are either "fields" or other resources. The child resource 651 types and operations allowed on them are data-model specific. 653 A resource has its own media type identifier, represented by the 654 "Content-Type" header in the HTTP response message. A resource can 655 contain zero or more fields and zero or more resources. A resource 656 can be created and deleted independently of its parent resource, as 657 long as the parent resource exist. 659 A field is a child node defined within a resource. A field can 660 contain zero or more fields and zero or more resources. A field 661 cannot be created and deleted independently of its parent resource. 663 All YANG-API resources and fields are defined in this document except 664 datastore contents and protocol operations. These resource types are 665 defined with YANG data definition statements and the "rpc" statement. 666 A default mapping is defined to differentiate sub-resources from 667 fields within data resources. 669 2.2.1. YANG-API Resource Types 671 The YANG-API protocol defines some application specific media types 672 to identify each of the available resource types. The following 673 table summarizes the purpose of each resource. 675 +-----------+--------------------------------+ 676 | Resource | Media Type | 677 +-----------+--------------------------------+ 678 | API | application/vnd.yang.api | 679 | Datastore | application/vnd.yang.datastore | 680 | Data | application/vnd.yang.data | 681 | Operation | application/vnd.yang.operation | 682 +-----------+--------------------------------+ 684 YANG-API Media Types 686 These resources are described in Section 5. 688 2.2.2. Resource Discovery 690 A client SHOULD start by retrieving the top-level API resource, using 691 the entry point URI "/yang-api". 693 The YANG-API protocol does not include a resource discovery 694 mechanism. Instead, the definitions within the YANG modules 695 advertised by the server are used to construct a predictable 696 operation or data resource identifier. 698 The "depth" query parameter can be used to control how many 699 descendant levels should be included when retrieving sub-resources. 700 This parameter can be used with the GET operation to discover sub- 701 resources within a particular resource. 703 Refer to Section 3.8.2 for more details on the "depth" parameter. 705 2.3. Datastore Model 707 A conceptual "unified datastore" is used to simplify resource 708 management for the client. The YANG-API datastore is a combination 709 of the running configuration and any non-configuration data supported 710 by the device. By default only configuration data is returned by a 711 GET operation on the datastore contents. 713 The underlying NETCONF datastores can be used to implement the 714 unified datastore, but the server design is not limited to the exact 715 datastore procedures defined in NETCONF. 717 The "candidate" and "startup" datastores are not visible in the YANG- 718 API protocol. Transaction management and configuration persistence 719 are handled by the server and not controlled by the client. 721 2.3.1. Content Model 723 The YANG-API protocol operates on a conceptual datastore defined with 724 the YANG data modeling language. The server lists each YANG module 725 it supports in the "/yang-api/modules/module" field in the top-level 726 API resource type, using the YANG module capability URI format 727 defined in RFC 6020. 729 The conceptual datastore contents and data-model-specific operations 730 are identified by the set of YANG module capability URIs. All YANG- 731 API content identified as either a data resource or an operation 732 resource is defined with the YANG language. 734 The classification of data as configuration or non-configuration is 735 derived from the YANG "config" statement. Data retrieval with the 736 GET operation can be filtered in several ways, including the "config" 737 parameter to retrieve configuration or non-configuration data. 739 The classification of data as a resource or field within a resource 740 is derived from the rules specified in Section 5.3.2. 742 Data ordering behavior is derived from the YANG "ordered-by" 743 statement. Editing mechanisms are provided to allow list or leaf- 744 list resources to be inserted or moved in the same manner as NETCONF, 745 and defined in YANG. 747 The server is not required to maintain system ordered data in any 748 particular persistent order. The server SHOULD maintain the same 749 data ordering for system ordered data until the next reboot or 750 termination of the server. 752 2.3.2. Editing Model 754 The YANG-API datastore editing model is simple and direct, similar to 755 the behavior of the ":writable-running" capability in NETCONF. 757 Each YANG-API edit of a datastore resource is activated upon 758 successful completion of the transaction. It is an implementation- 759 specific matter how the server accomplishes a YANG-API edit request. 760 For example, a server which only accepts edits through a candidate 761 datastore may internally edit this datastore and perform the "commit" 762 operation automatically. 764 Applications which need more control over the editing model might 765 consider using NETCONF instead of YANG-API. 767 2.3.2.1. Edit Operation Discovery 769 Sometimes a server does not implement every operation for every 770 resource. Sometimes data model requirements cause a node to 771 implement a subset of the edit operations. For example, a server may 772 not allow modification of a particular configuration data node after 773 the parent resource has been created. 775 The OPTIONS operation can be used to identify which operations are 776 supported by the server for a particular resource. For example, if 777 the server will allow a data resource node to be created then the 778 POST operation will be returned in the response. 780 2.3.2.2. Edit Collision Detection 782 Two "edit collision detection" mechanisms are provided in YANG-API, 783 for datastore and data resources. 785 o timestamp: the last change time is maintained and the 786 "Last-Modified" and "Date" headers are returned in the response 787 for a retrieval request. The "If-Unmodified-Since" header can be 788 used in edit operation requests to cause the server to reject the 789 request if the resource has been modified since the specified 790 timestamp. 792 o entity tag: a unique opaque string is maintained and the "ETag" 793 header is returned in the response for a retrieval request. The 794 "If-Match" header can be used in edit operation requests to cause 795 the server to reject the request if the resource entity tag does 796 not match the specified value. 798 Note that the server is only required to maintain these fields for a 799 datastore resource, not for individual data resources. 801 Example: 803 In this example, the server just supports the mandatory datastore 804 last-changed timestamp. The client has previously retrieved the 805 "Last-Modified" header and has some value cached to provide in the 806 following request to replace a list entry with key value "11": 808 PATCH /yang-api/datastore/jukebox/artist/1/album/ 809 Wasting%20Light/year HTTP/1.1 810 Host: example.com 811 Accept: application/vnd.yang.data+json 812 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 813 Content-Type: application/vnd.yang.data+json 814 { "year" : "2011" } 816 In this example the datastore resource has changed since the time 817 specified in the "If-Unmodified-Since" header. The server might 818 respond: 820 HTTP/1.1 304 Not Modified 821 Date: Mon, 23 Apr 2012 19:01:00 GMT 822 Server: example-server 823 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 824 ETag: b34aed893a4c 826 2.3.3. Locking Model 828 Datastore locking is not provided by YANG-API. An application that 829 needs to make several changes to the running configuration datastore 830 contents in sequence, without disturbance from other clients might 831 consider using the NETCONF protocol instead of YANG-API. 833 2.3.4. Persistence Model 835 Each YANG-API edit of a datastore resource is saved to non-volatile 836 storage in an implementation-specific matter by the server. There is 837 no guarantee that configuration changes are saved immediately, or 838 that the saved configuration is always a mirror of the running 839 configuration. 841 Applications which need more control over the persistence model might 842 consider using NETCONF instead of YANG-API. 844 2.3.5. Defaults Model 846 NETCONF has a rather complex defaults handling model for leafs. 847 YANG-API attempts to avoid this complexity by restricting the 848 operations that can be applied to a resource and fields within that 849 resource. 851 The GET method returns only nodes that exist, which will be 852 determined by the server. There is no mechanism for the client to 853 ask the server for the default values that would be used for any 854 nodes not present, but some default value is in use by the server. 855 (There is no 857 retrieval mode like "with-defaults=report-all" in NETCONF.) 859 If a leaf definition has a default value, and the leaf has not been 860 given a value yet, the server SHOULD NOT return any value for the 861 leaf in the response for a GET operation. 863 Applications which need more control over the defaults model might 864 consider using NETCONF instead of YANG-API. 866 2.4. Transaction Model 868 The YANG-API protocol does not provide a complex transaction model 869 that allows for multiple protocol operations, or even operations on 870 multiple resources in one protocol operation. A very simple "one 871 operation one one resource" per transaction model is used instead. 873 Applications which need more control over the transaction model might 874 consider using NETCONF instead of YANG-API. 876 2.5. Extensibility Model 878 The YANG-API protocol is designed to be extensible for datastore 879 content and data-model specific protocol operations. New protocol 880 operations can be added without changing the entry point if they are 881 optional and do not alter any existing operations. 883 Separate namespaces for each YANG module are used. Content encoded 884 in XML will indicate the module using the "namespace" URI value in 885 the YANG module. Content encoded in JSON will indicate the module 886 using the module name specified in the YANG module. JSON encoding 887 rules for module namespaces are specified in 888 [I-D.lhotka-netmod-json]. 890 2.6. Versioning Model 892 The version of a resource instance is identified with an entity tag, 893 as defined by HTTP. The version identifiers in this section apply to 894 the version of the schema definition of a resource. There are two 895 types of schema versioning information used in the YANG-API protocol: 897 o the YANG-API protocol version 899 o data and operation resource definition versions 901 The protocol version is identified by the string used for the well- 902 known URI entry point "/yang-api". This would be changed (e.g., 903 "/yang-api2") if non-backward compatible changes are ever needed. 904 Minor version changes that do not break backward-compatibility will 905 not cause the entry point to change. 907 The API "yang-api/version" field can be used by the client to 908 identify the exact version of the YANG-API protocol implemented by 909 the server. This value will include the complete YANG-API protocol 910 version. The "/yang-api" entry point will only change (e.g., 911 "/yang-api2") if non-backward compatible changes are made to the 912 protocol. The "/yang-api/version" field MUST be updated every time 913 the protocol specification is republished. 915 The resource definition version for a data or operation resource is a 916 date string, which is the revision date of the YANG module that 917 defines the resource. The resource version for all other resource 918 types is a numeric string, defined by the "/yang-api/version" field. 920 2.7. Retrieval Filtering Model 922 There are four types of filtering for retrieval of data resources in 923 the YANG-API protocol. 925 o conditional all-or-nothing: use some conditional test mechanism in 926 the request headers and retrieve either a complete "200 OK" 927 response if the condition is met, or a "304 Not Modified" Status- 928 Line if the condition is not met. 930 o data classification: request configuration or non-configuration 931 data. 933 o subset: request a subset of all possible instances of a list or 934 leaf-list data resource. 936 o filter: request a subset of all possible descendant nodes within 937 the target resource. The "select" query parameter can be used for 938 this purpose. 940 Refer to Section 5.3.4 for details on data retrieval filtering. 942 2.8. Access Control Model 944 The YANG-API protocol provides no granular access control for any 945 content except for operation and data resources. The NETCONF Access 946 Control Model (NACM) is defined in [RFC6536]. There is a specific 947 mapping between YANG-API operations and NETCONF edit operations, 948 defined in Table 1. The resource path also needs to be converted 949 internally by the server to the corresponding YANG instance- 950 identifier. Using this information, the server can apply the NACM 951 access control rules to YANG-API messages. 953 The server MUST NOT allow any operation to any resources that the 954 client is not authorized to access. 956 3. Operations 958 The YANG-API protocol uses HTTP methods to identify the CRUD 959 operation requested for a particular resource or field within a 960 resource. The following table shows how the YANG-API operations 961 relate to NETCONF protocol operations: 963 +----------+-------------------------------------+ 964 | YANG-API | NETCONF | 965 +----------+-------------------------------------+ 966 | OPTIONS | none | 967 | HEAD | none | 968 | GET | , | 969 | POST | (operation="create") | 970 | PUT | (operation="replace") | 971 | PATCH | (operation="merge") | 972 | DELETE | (operation="delete") | 973 +----------+-------------------------------------+ 975 Table 1: CRUD Operations in YANG-API 977 The NETCONF "remove" operation attribute is not supported by the HTTP 978 DELETE method. The resource must exist or the DELETE operation will 979 fail. 981 This section defines the YANG-API protocol usage for each HTTP 982 method. 984 3.1. OPTIONS 986 The OPTIONS method is sent by the client to discover which methods 987 are supported by the server for a specific resource, or field within 988 a resource. It is supported for all media types. Note that 989 implementation of this operation is part of HTTP, and this section 990 does not introduce any additional requirements. 992 The request MUST contain a request URI that contains at least the 993 entry point component. 995 The server will return a "Status-Line" header containing "204 No 996 Content". and include the "Allow" header in the response. This 997 header will be filled in, based on the target resource media type. 998 Other headers MAY also be included in the response. 1000 Example 1: 1002 A client might request the methods supported for a data resource 1003 called "library" 1004 OPTIONS /yang-api/datastore/jukebox/library HTTP/1.1 1005 Host: example.com 1007 The server might respond (for a config=true list): 1009 HTTP/1.1 204 No Content 1010 Date: Mon, 23 Apr 2012 17:01:00 GMT 1011 Server: example-server 1012 Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH,DELETE 1014 Example 2: 1016 A client might request the methods supported for a non-configuration 1017 leaf within a data resource: 1019 OPTIONS /yang-api/datastore/jukebox/library/ 1020 song-count HTTP/1.1 1021 Host: example.com 1023 The server might respond: 1025 HTTP/1.1 204 No Content 1026 Date: Mon, 23 Apr 2012 17:02:00 GMT 1027 Server: example-server 1028 Allow: OPTIONS,HEAD,GET 1030 Example 3: 1032 A client might request the methods supported for an operation 1033 resource called "play": 1035 OPTIONS /yang-api/operations/play HTTP/1.1 1036 Host: example.com 1038 The server might respond: 1040 HTTP/1.1 204 No Content 1041 Date: Mon, 23 Apr 2012 17:02:00 GMT 1042 Server: example-server 1043 Allow: POST 1045 3.2. HEAD 1047 The HEAD operation is sent by the client to retrieve just the headers 1048 that would be returned for the comparable GET operation, without the 1049 response body. The HTTP HEAD method is used for this operation. It 1050 is supported for all resource types, except operation resources. 1052 The request MUST contain a request URI that contains at least the 1053 entry point component. 1055 The same query parameters supported by the GET operation are 1056 supported by the HEAD operation. For example, the "select" query 1057 parameter can be used to specify a field within the target resource. 1059 The access control behavior is enforced as if the method was GET 1060 instead of HEAD. The server MUST respond the same as if the method 1061 was GET instead of HEAD, except that no response body is included. 1063 Example: 1065 The client might request the response headers for the default (JSON) 1066 representation of the "library" resource: 1068 HEAD /yang-api/datastore/jukebox/library HTTP/1.1 1069 Host: example.com 1071 The server might respond: 1073 HTTP/1.1 200 OK 1074 Date: Mon, 23 Apr 2012 17:02:40 GMT 1075 Server: example-server 1076 Content-Type: application/vnd.yang.data+json 1077 Cache-Control: no-cache 1078 Pragma: no-cache 1079 ETag: a74eefc993a2b 1080 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1082 3.3. GET 1084 The GET operation is sent by the client to retrieve data and meta- 1085 data for a resource or field within a resource. The HTTP GET method 1086 is used for this operation. It is supported for all resource types, 1087 except operation resources. The request MUST contain a request URI 1088 that contains at least the entry point component. 1090 The following query parameters are supported by the GET operation: 1092 +--------+---------+------------------------------------------------+ 1093 | Name | Section | Description | 1094 +--------+---------+------------------------------------------------+ 1095 | config | 3.8.1 | Request either configuration or | 1096 | | | non-configuration data | 1097 | depth | 3.8.2 | Control the depth of a retrieval request | 1098 | format | 3.8.3 | Request either JSON or XML content in the | 1099 | | | response | 1100 | select | 3.8.6 | Specify a field within the target resource | 1101 +--------+---------+------------------------------------------------+ 1103 GET Query Parameters 1105 The server MUST NOT return any data resources or fields within any 1106 data resources for which the user does not have read privileges. 1108 If the user is not authorized to read any portion of the target 1109 resource, an error response containing a "403 Forbidden" Status-Line 1110 is returned to the client. 1112 If the user is authorized to read some but not all of the target 1113 resource, the unauthorized content is omitted from the response 1114 message body, and the authorized content is returned to the client. 1116 Example: 1118 The client might request the response headers for a JSON 1119 representation of the "library" resource: 1121 GET /yang-api/datastore/jukebox/library/artist/ 1122 1/album HTTP/1.1 1123 Host: example.com 1125 The server might respond: 1127 HTTP/1.1 200 OK 1128 Date: Mon, 23 Apr 2012 17:02:40 GMT 1129 Server: example-server 1130 Content-Type: application/vnd.yang.data+json 1131 Cache-Control: no-cache 1132 Pragma: no-cache 1133 ETag: a74eefc993a2b 1134 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1136 { 1137 "album" : { 1138 "name" : "Wasting Light", 1139 "genre" : "example-jukebox:Alternative", 1140 "year" : 2011 1141 } 1142 } 1144 3.4. POST 1146 The POST operation is sent by the client for various reasons. The 1147 HTTP POST method is used for this purpose. The request MUST contain 1148 a request URI that contains a target resource that identifies one of 1149 the following resource types: 1151 +-------------+--------------------------------------+ 1152 | Type | Description | 1153 +-------------+--------------------------------------+ 1154 | Data | Create a configuration data resource | 1155 | Operation | Invoke protocol operation | 1156 | Transaction | Create a new transaction | 1157 +-------------+--------------------------------------+ 1159 Resource Types that Support POST 1161 The following query parameters are supported by the POST operation: 1163 +--------+---------+-----------------------------------------+ 1164 | Name | Section | Description | 1165 +--------+---------+-----------------------------------------+ 1166 | insert | 3.8.4 | Specify where to insert a resource | 1167 | point | 3.8.5 | Specify the insert point for a resource | 1168 +--------+---------+-----------------------------------------+ 1170 POST Query Parameters 1172 If the POST operation succeeds, a "200 OK" Status-Line is returned if 1173 there is no response message body, and a "204 No Content" Status-Line 1174 is returned if there is a response message body. 1176 If the user is not authorized to invoke the target (operation) 1177 resource, or create the target resource, an error response containing 1178 a "403 Forbidden" Status-Line is returned to the client. All other 1179 error responses are handled according to the procedures defined in 1180 Section 6. 1182 3.5. PUT 1184 The PUT operation is sent by the client to replace the target 1185 resource. 1187 The HTTP PUT method is used for this purpose. The request MUST 1188 contain a request URI that contains a target resource that identifies 1189 the data resource to replace. 1191 The following query parameters are supported by the PUT operation: 1193 +--------+---------+---------------------------------------+ 1194 | Name | Section | Description | 1195 +--------+---------+---------------------------------------+ 1196 | insert | 3.8.4 | Specify where to move a resource | 1197 | point | 3.8.5 | Specify the move point for a resource | 1198 +--------+---------+---------------------------------------+ 1200 PUT Query Parameters 1202 If the PUT operation succeeds, a "200 OK" Status-Line is returned, 1203 and there is no response message body. 1205 If the user is not authorized to replace the target resource an error 1206 response containing a "403 Forbidden" Status-Line is returned to the 1207 client. All other error responses are handled according to the 1208 procedures defined in Section 6. 1210 3.6. PATCH 1212 The PATCH operation uses the HTTP PATCH method defined in [RFC5789] 1213 to provide a "merge" editing mode for data resources. Instead of 1214 replacing all or part of the target resource, the supplied values are 1215 merged into the target resource. 1217 If the PATCH operation succeeds, a "200 OK" Status-Line is returned, 1218 and there is no response message body. 1220 If the user is not authorized to alter the target resource an error 1221 response containing a "403 Forbidden" Status-Line is returned to the 1222 client. All other error responses are handled according to the 1223 procedures defined in Section 6. 1225 3.7. DELETE 1227 The DELETE operation uses the HTTP DELETE method to delete the target 1228 resource. 1230 If the DELETE operation succeeds, a "200 OK" Status-Line is returned, 1231 and there is no response message body. 1233 If the user is not authorized to delete the target resource then an 1234 error response containing a "403 Forbidden" Status-Line is returned 1235 to the client. All other error responses are handled according to 1236 the procedures defined in Section 6. 1238 3.8. Query Parameters 1240 Each YANG-API operation allows zero or more query parameters to be 1241 present in the request URI. Refer to Section 3 for details on the 1242 query parameters used in the definition of each operation. 1244 Query parameters can be given in any order. Each parameter can 1245 appear zero or one time. A default value may apply if the parameter 1246 is missing. 1248 This section defines all the YANG-API query parameters. 1250 3.8.1. "config" Parameter 1252 The "config" parameter is used to specify whether configuration or 1253 non-configuration data is requested. 1255 This parameter is only supported for the GET and HEAD methods. It is 1256 also only supported if the target resource is a data resource. 1258 syntax: config= true | false 1259 default: true 1261 Example: 1263 This example request by the client would retrieve only the non- 1264 configuration data nodes that exist within the second-level "library" 1265 resource. 1267 GET /yang-api/datastore/jukebox/library?config=false HTTP/1.1 1268 Host: example.com 1269 Accept: application/vnd.yang.data+xml 1271 The server might respond: 1273 HTTP/1.1 200 OK 1274 Date: Mon, 23 Apr 2012 17:01:30 GMT 1275 Server: example-server 1276 Cache-Control: no-cache 1277 Pragma: no-cache 1278 Content-Type: application/vnd.yang.data+json 1280 { 1281 "library" : { 1282 "artist-count" : 42, 1283 "album-count" : 59, 1284 "song-count" : 374 1285 } 1287 } 1289 3.8.2. "depth" Parameter 1291 The "depth" parameter is used to specify the number of nest levels 1292 returned in a response for a GET operation. A nest-level consists of 1293 the target resource and any child nodes which are optional data nodes 1294 (anyxml, leaf, or leaf-list). A non-presence container is 1295 transparent when determining the nest level. A child node (which is 1296 not a non-presence container) within a non-presence container is used 1297 to determine the nest-level. 1299 The start level is determined by the target resource for the 1300 operation. 1302 syntax: depth= | unbounded 1303 default: 1 1305 Example: 1307 This example operation would retrieve 2 levels of configuration data 1308 nodes that exist within the top-level "jukebox" resource. 1310 GET /yang-api/datastore/jukebox?depth=2 HTTP/1.1 1311 Host: example.com 1312 Accept: application/vnd.yang.data+json 1314 The server might respond: 1316 HTTP/1.1 200 OK 1317 Date: Mon, 23 Apr 2012 17:11:30 GMT 1318 Server: example-server 1319 Cache-Control: no-cache 1320 Pragma: no-cache 1321 Content-Type: application/vnd.yang.data+json 1323 { 1324 "jukebox" : { 1325 "library" : { 1326 "artist" : { 1327 "index" : 1, 1328 "name" : "Foo Fighters" 1329 } 1330 }, 1331 "player" : { 1332 "gap" : 0.5 1333 } 1334 } 1336 } 1338 3.8.3. "format" Parameter 1340 The "format" parameter is used to specify the format of any content 1341 returned in the response. Note that the "Accept" header MAY be used 1342 instead of this parameter to identify the format desired in the 1343 response. For example: 1345 GET /yang-api/datastore/routing HTTP/1.1 1346 Host: example.com 1347 Accept: application/vnd.yang.data+xml 1349 This example request would retrieve only the configuration data nodes 1350 that exist within the top-level "routing" resource, and retrieve them 1351 in XML encoding instead of JSON encoding. 1353 The "format" parameter is only supported for the GET and HEAD 1354 methods. It is supported for all YANG-API media types. 1356 syntax: format= xml | json 1357 default: json 1359 Example: 1361 GET /yang-api/datastore/routing?format=xml HTTP/1.1 1362 Host: example.com 1364 This example URI would retrieve only the configuration data nodes 1365 that exist within the top-level "routing" resource, and retrieve them 1366 in XML encoding instead of JSON encoding. 1368 3.8.4. "insert" Parameter 1370 The "insert" parameter is used to specify how a resource should be 1371 inserted (or moved) within the user-ordered list or leaf-list data 1372 resource. 1374 This parameter is only supported for the POST and PUT methods. It is 1375 also only supported if the target resource is a data resource, and 1376 that data represents a YANG list or leaf-list that is ordered by the 1377 user, not the system. 1379 If the values "before" or "after" are used, then a "point" parameter 1380 for the insertion parameter MUST also be present. 1382 syntax: insert= first | last | before | after 1383 default: last 1385 Example: 1387 Request from client: 1389 POST /yang-api/datastore/jukebox/library/artist/1/album 1390 /Wasting%20Light/song?insert=first HTTP/1.1 1391 Host: example.com 1392 Content-Type: application/vnd.yang.data+json 1394 { 1395 "song" : { 1396 "name" : "Bridge Burning", 1397 "location" : "/media/bridge_burning.mp3", 1398 "format" : "MP3", 1399 "length" : 286 1400 } 1401 } 1403 Response from server: 201 status 1405 HTTP/1.1 201 Created 1406 Date: Mon, 23 Apr 2012 13:01:20 GMT 1407 Server: example-server 1408 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1410 Location: http://example.com/yang-api/datastore/jukebox 1411 /library/artist/1/album?Wasting%20Light/song/1 1412 ETag: eeeada438af 1414 3.8.5. "point" Parameter 1416 The "point" parameter is used to specify the insertion point for a 1417 data resource that is being created or moved within a user ordered 1418 list or leaf-list. It is ignored unless the "insert" query parameter 1419 is also present, and has the value "before" or "after". 1421 This parameter contains the instance identifier of the resource, or 1422 field within a resource, to be used as the insertion point for a POST 1423 or PUT operation. It is encoded according to the rules defined in 1424 Section 5.3.1. There is no default for this parameter. 1426 syntax: point= 1428 Example: 1430 In this example, the client is moving an existing "song" resource 1431 within an "album" resource after another song. The request URI is 1432 split for display purposes only. 1434 Request from client: 1436 PUT /yang-api/datastore/jukebox/library/artist/1/album/ 1437 Wasting%20Light/song/2?insert=after 1438 &point=/yang-api/datastore/jukebox/library/artist/1/ 1439 album/Wasting%20Light/song/4 HTTP/1.1 1440 Host: example.com 1442 Response from server: 1444 HTTP/1.1 204 No Content 1445 Date: Mon, 23 Apr 2012 13:01:20 GMT 1446 Server: example-server 1447 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1448 ETag: abcada438af 1450 3.8.6. "select" Parameter 1452 The "select" query parameter is used to specify an expression which 1453 can represent a subset of all data nodes within the target resource. 1454 It contains a relative path expression, using the target resource as 1455 the context node. 1457 It is supported for all resource types except operation resources. 1458 The contents are encoded according to the "api-select" rule defined 1459 in Section 5.3.1. This parameter is only allowed for GET and HEAD 1460 operations. 1462 [FIXME: the syntax of the select string is still TBD; XPath, schema- 1463 identifier, regular expressions, something else] 1465 Refer to Section 1.4.2 for example request messages using the 1466 "select" parameter. 1468 3.9. Protocol Operations 1470 The YANG-API also allows data-model specific protocol operations to 1471 be invoked using the POST method. The media type 1472 "vnd.yang.operation+xml" or "vnd.yang.operation+json" MUST be used in 1473 the "Content-Type" field in the message header. 1475 Data model specific operations are supported. The syntax and 1476 semantics of these operations exactly correspond to the YANG "rpc" 1477 statement definition for the operation. 1479 Any input for a protocol operation is encoded in an element called 1480 "input", which corresponds to the element in a NETCONF 1481 message. The child nodes of the "input" element are encoded 1482 according to the data definition statements in the input section of 1483 the "rpc" statement. 1485 Any output for a protocol operation is encoded in an element called 1486 "output", which corresponds to the element in a NETCONF 1487 message. The child nodes of the "output" element are encoded 1488 according to the data definition statements in the output section of 1489 the "rpc" statement. 1491 4. Messages 1493 This section describes the messages that are used in the YANG-API 1494 protocol. 1496 4.1. Request URI Structure 1498 Resources are represented with URIs following the structure for 1499 generic URIs in [RFC3986]. 1501 A YANG-API operation is derived from the HTTP method and the request 1502 URI, using the following conceptual fields: 1504 /yang-api/?# 1506 ^ ^ ^ ^ ^ 1507 | | | | | 1508 method entry resource query fragment 1510 M M O O I 1512 M=mandatory, O=optional, I=ignored 1514 replaced by client with real values 1516 o method: the HTTP method identifying the YANG-API operation 1517 requested by the client, to act upon the target resource specified 1518 in the request URI. YANG-API operation details are described in 1519 Section 3. 1521 o entry: the well-known YANG-API entry point ("/yang-api"). 1523 o resource: the path expression identifying the resource that is 1524 being accessed by the operation. If this field is not present, 1525 then the target resource is the API itself, represented by the 1526 media type "vnd.yang.api". 1528 o query: the set of parameters associated with the YANG-API message. 1529 These have the familiar form of "name=value" pairs. There is a 1530 specific set of parameters defined, although the server MAY choose 1531 to support additional parameters not defined in this document. 1533 o fragment: This field is not used by the YANG-API protocol. 1535 The client SHOULD NOT assume the final structure of a URI path for a 1536 resource. Instead, existing resources can be discovered with the GET 1537 operation. When new resources are created by the client, a 1538 "Location" header is returned, which identifies the path of the newly 1539 created resource. The client MUST use this exact path identifier to 1540 access the resource once it has been created. 1542 The "target" of an operation is a resource. The "path" field in the 1543 request URI represents the target resource for the operation. 1545 4.2. Message Headers 1547 There are several HTTP header lines utilized in YANG-API messages. 1548 Messages are not limited to the HTTP headers listed in this section. 1550 HTTP defines which header lines are required for particular 1551 circumstances. Refer to each operation definition section in 1552 Section 3 for examples on how particular headers are used. 1554 There are some request headers that are used within YANG-API, usually 1555 applied to data resources. The following tables summarize the 1556 headers most relevant in YANG-API message requests: 1558 +---------------------+---------------------------------------------+ 1559 | Name | Description | 1560 +---------------------+---------------------------------------------+ 1561 | Accept | Response Content-Types that are acceptable | 1562 | Content-Type | The media type of the request body | 1563 | Host | The host address of the server | 1564 | If-Match | Only perform the action if the entity | 1565 | | matches ETag | 1566 | If-Modified-Since | Only perform the action if modified since | 1567 | | time | 1568 | If-Range | Only retrieve range if resource unchanged | 1569 | If-Unmodified-Since | Only perform the action if un-modified | 1570 | | since time | 1571 | Range | Specify a range of data resource entries | 1572 +---------------------+---------------------------------------------+ 1574 YANG-API Request Headers 1576 The following tables summarize the headers most relevant in YANG-API 1577 message responses: 1579 +---------------+---------------------------------------------------+ 1580 | Name | Description | 1581 +---------------+---------------------------------------------------+ 1582 | Allow | Valid actions when 405 error returned | 1583 | Content-Type | The media type of the response body | 1584 | Date | The date and time the message was sent | 1585 | ETag | An identifier for a specific version of a | 1586 | | resource | 1587 | Last-Modified | The last modified date and time of a resource | 1588 | Location | The resource identifier for a newly created | 1589 | | resource | 1590 +---------------+---------------------------------------------------+ 1592 YANG-API Response Headers 1594 4.3. Message Encoding 1596 YANG-API messages are encoded in HTTP according to RFC 2616. The 1597 "utf-8" character set is used for all messages. YANG-API message 1598 content is sent in the HTTP message body. 1600 Content is encoded in either JSON or XML format. 1602 XML encoding rules for data nodes are defined in [RFC6020]. The same 1603 encoding rules are used for all XML content. XML attributes are not 1604 used and will be ignored if present in an XML-encoded message. 1606 JSON encoding rules are defined in [I-D.lhotka-netmod-json]. Special 1607 encoding rules are needed to handle multiple module namespaces and 1608 provide consistent data type processing. 1610 Request input content encoding format is identified with the Content- 1611 Type header. This field MUST be present if message input is sent by 1612 the client. 1614 Response output content encoding format is identified with the Accept 1615 header, the "format" query parameter, or if neither is specified, the 1616 request input encoding format is used. If there was no request 1617 input, then the default output encoding is JSON. File extensions 1618 encoded in the request are not used to identify format encoding. 1620 4.4. Return Status 1622 Each message represents some sort of resource access. An HTTP 1623 "Status-Line" header line is returned for each request. If a 4xx or 1624 5xx range status code is returned in the Status-Line, then the error 1625 information will be returned in the response, according to the format 1626 defined in Section 6.1. 1628 4.5. Message Caching 1630 Since the datastore contents change at unpredictable times, responses 1631 from a YANG-API server generally SHOULD NOT be cached. 1633 The server SHOULD include a "Cache-Control" header in every response 1634 that specifies whether the response should be cached. A "Pragma" 1635 header specifying "no-cache" MAY also be sent in case the 1636 "Cache-Control" header is not supported. 1638 Instead of using HTTP caching, the client SHOULD track the "ETag" 1639 and/or "Last-Modified" headers returned by the server for the 1640 datastore resource (or data resource if the server supports it). 1642 A retrieval request for a resource can include headers such as 1643 "If-None-Match" or "If-Modified-Since" which will cause the server to 1644 return a "304 Not Modified" Status-Line if the resource has not 1645 changed. 1647 The client MAY use the HEAD operation to retrieve just the message 1648 headers, which SHOULD include the "ETag" and "Last-Modified" headers, 1649 if this meta-data is maintained for the target resource. 1651 5. Resources 1653 The resources used in the YANG-API protocol are identified by the 1654 "path" component in the request URI. Each operation is performed on 1655 a target resource. 1657 5.1. API Resource (/yang-api) 1659 The API resource contains the state and access points for the YANG- 1660 API features. 1662 It is the top-level resource and has the media type "application/ 1663 vnd.yang.api+xml" or "application/vnd.yang.api+json". It is 1664 accessible through the well-known URI "/yang-api". 1666 This resource has the following fields: 1668 +------------+--------------------------------+ 1669 | Field Name | Description | 1670 +------------+--------------------------------+ 1671 | datastore | Link to "datastore" resource | 1672 | modules | YANG module capability URIs | 1673 | operations | Data-model specific operations | 1674 +------------+--------------------------------+ 1676 YANG-API Resource Fields 1678 5.1.1. /yang-api/datastore 1680 This mandatory resource represents the running configuration 1681 datastore and any non-configuration data available. It may be 1682 retrieved and edited directly. It cannot be created or deleted by 1683 the client. This resource type is defined in Section 5.2. 1685 5.1.2. /yang-api/modules 1687 This mandatory field contains the identifiers for the YANG data model 1688 modules supported by the server. There MUST be exactly one instance 1689 of this field. 1691 The server MUST maintain a last-modified timestamp for this field, 1692 and return the "Last-Modified" header when this field is retrieved 1693 with the GET or HEAD methods. 1695 5.1.3. /yang-api/operations 1697 This optional field provides access to the data-model specific 1698 protocol operations supported by the server. The server MAY omit 1699 this field if no data-model specific operations are advertised. 1701 Any data-model specific operations defined in the YANG modules 1702 advertised by the server SHOULD be available as child nodes of this 1703 field. 1705 5.1.3.1. /yang-api/modules/module 1707 This mandatory field contains one URI string for each YANG data model 1708 module supported by the server. There MUST be an instance of this 1709 field for every YANG module that is accessible via an operation 1710 resource or a data resource. 1712 The server MAY maintain a last-modified timestamp for each instance 1713 of this resource, and return the "Last-Modified" header when this 1714 resource is retrieved with the GET or HEAD methods. If not supported 1715 then the timestamp for the parent "modules" field MUST NOT be used 1716 instead. 1718 The contents of this field are encoded with the "uri" derived type 1719 from the "ietf-iana-types" modules in [RFC6021]. 1721 There are additional encoding requirements for this field. The URI 1722 MUST follow the YANG module capability URI formatting defined in 1723 section 5.6.4 of [RFC6020]. 1725 5.1.3.2. Retrieval Example 1727 In this example the client is retrieving the modules field from the 1728 server in the default JSON format: 1730 GET /yang-api?select=modules HTTP/1.1 1731 Host: example.com 1732 Accept: application/vnd.yang.api+json 1734 The server might respond as follows. Note that the content below is 1735 split across multiple lines for display purposes only: 1737 HTTP/1.1 200 OK 1738 Date: Mon, 23 Apr 2012 17:01:00 GMT 1739 Server: example-server 1740 Cache-Control: no-cache 1741 Pragma: no-cache 1742 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 1743 Content-Type: application/vnd.yang.api+json 1745 { 1746 "yang-api": { 1747 "modules": { 1748 "module": [ 1749 "example.com?module=foo&revision=2012-01-02", 1750 "example.com?module=bar&revision=2011-10-10" 1751 "example.com?module=itf&revision=2011-10-10 1752 &feature=restore" 1753 ] 1754 } 1755 } 1756 } 1758 5.1.4. /yang-api/version 1760 This mandatory field identifies the specific version of the YANG-API 1761 protocol implemented by the server. 1763 The same server-wide response MUST be returned each time this field 1764 is retrieved. It is assigned by the server when the server is 1765 started. The server MUST return the value "1.0" for this version of 1766 the YANG-API protocol. 1768 This field is encoded with the rules for an "enumeration" data type, 1769 using the following leaf definition: 1771 leaf version { 1772 config false; 1773 type enum { 1774 enum "1.0" { 1775 description 1776 "Version 1.0 of the YANG-API protocol."; 1777 } 1778 } 1779 } 1781 5.2. Datastore Resource 1783 A datastore resource represents the conceptual root of a tree of data 1784 resources. 1786 The server MUST maintain a last-modified timestamp for this resource, 1787 and return the "Last-Modified" header when this resource is retrieved 1788 with the GET or HEAD methods. Only changes to configuration data 1789 resources within the datastore affect this timestamp. 1791 The server SHOULD maintain a resource entity tag for this resource, 1792 and return the "ETag" header when this resource is retrieved with the 1793 GET or HEAD methods. The resource entity tag SHOULD be changed to a 1794 new previously unused value if changes to any configuration data 1795 resources within the datastore are made. 1797 A datastore resource can be retrieved with the GET operation, to 1798 retrieve either configuration data resources or non-configuration 1799 data resources within the datastore. The "config" query parameter is 1800 used to choose between them. Refer to Section 3.8.1 for more 1801 details. 1803 The depth of the subtrees returned in retrieval operations can be 1804 controlled with the "depth" query parameter. The number of nest 1805 levels, starting at the target resource, can be specified, or an 1806 unlimited number can be returned. Refer to Section 3.8.2 for more 1807 details. 1809 A datastore resource cannot be written directly with any edit 1810 operation. Only the configuration data resources within the 1811 datastore resource can be edited. 1813 5.3. Data Resource 1815 A data resource represents a YANG data node that is a descendant node 1816 of a datastore resource. 1818 For configuration data resources, the server MAY maintain a last- 1819 modified timestamp for the resource, and return the "Last-Modified" 1820 header when it is retrieved with the GET or HEAD methods. 1822 For configuration data resources, the server MAY maintain a resource 1823 entity tag for the resource, and return the "ETag" header when it is 1824 retrieved as the target resource with the GET or HEAD methods. The 1825 resource entity tag SHOULD be changed to a new previously unused 1826 value if changes to the resource or any configuration field within 1827 the resource is altered. 1829 A data resource can be retrieved with the GET operation, to retrieve 1830 either configuration data resources or non-configuration data 1831 resources within the target resource. The "config" query parameter 1832 is used to choose between them. Refer to Section 3.8.1 for more 1833 details. 1835 The depth of the subtrees returned in retrieval operations can be 1836 controlled with the "depth" query parameter. The number of nest 1837 levels, starting at the target resource, can be specified, or an 1838 unlimited number can be returned. Refer to Section 3.8.2 for more 1839 details. 1841 A configuration data resource can be altered by the client with some 1842 of all of the edit operations, depending on the target resource and 1843 the specific operation. Refer to Section 3 for more details on edit 1844 operations. 1846 5.3.1. Encoding YANG Instance Identifiers in the Request URI 1848 In YANG, data nodes are named with an absolute XPath expression, from 1849 the document root to the target resource. In YANG-API, URL friendly 1850 path expressions are used instead. 1852 The YANG "instance-identifier" (i-i) data type is represented in 1853 YANG-API with the path expression format defined in this section. 1855 +-------+-------------------------------------------+ 1856 | Name | Comments | 1857 +-------+-------------------------------------------+ 1858 | point | Insertion point is always a full i-i | 1859 | path | Request URI path is a full or partial i-i | 1860 +-------+-------------------------------------------+ 1862 YANG-API instance-identifier Type Conversion 1864 The "path" component of the request URI contains the absolute path 1865 expression that identifies the target resource. The "select" query 1866 parameter is used to optionally identify the requested data nodes 1867 within the target resource to be retrieved in a GET operation. 1869 A predictable location for a data resource is important, since 1870 applications will code to the YANG data model module, which uses 1871 static naming and defines an absolute path location for all data 1872 nodes. 1874 A YANG-API data resource identifier is not an XPath expression. It 1875 is encoded from left to right, starting with the top-level data node, 1876 according to the "api-path" rule in Section 5.3.1.1. The node name 1877 of each ancestor of the target resource node is encoded in order, 1878 ending with the node name for the target resource. 1880 If the "select" is present, it is encoded, starting with a child node 1881 of the target resource, according to the "api-select" rule defined in 1882 Section 5.3.1.1. 1884 If a data node in the path expression is a YANG list node, then the 1885 key values for the list (if any) are encoded according to the 1886 "key-value" rule. If the list node is the target resource, then the 1887 key values MAY be omitted, according to the operation. For example, 1888 the POST operation to create a new data resource for a list node does 1889 not allow the key values to be present in the request URI. 1891 The key leaf values for a data resource representing a YANG list MUST 1892 be encoded as follows: 1894 o The value of each leaf identified in the "key" statement is 1895 encoded in order. 1897 o All the components in the "key" statement MUST be encoded. 1898 Partial instance identifiers are not supported. 1900 o Each value is encoded using the "key-value" rule in 1901 Section 5.3.1.1, according to the encoding rules for the data type 1902 of the key leaf. 1904 o An empty string can be a valid key value (e.g., "/top/list/key1// 1905 key3"). 1907 o The "/" character MUST be URL-encoded (i.e., "%2F"). 1909 o All whitespace MUST be URL-encoded. 1911 o A "null" value is not allowed since the "empty" data type is not 1912 allowed for key leafs. 1914 o The XML encoding is defined in [RFC6020]. 1916 o The JSON encoding is defined in [I-D.lhotka-netmod-json]. 1918 o The entire "key-value" MUST be properly URL-encoded, according to 1919 the rules defined in [RFC3986]. 1921 Notifications are not supported by YANG-API because they are not 1922 supported by HTTP. YANG notification statements are ignored by a 1923 YANG-API server. 1925 Examples: 1927 /yang-api/datastore/jukebox/library/artist/17&select=name 1929 /yang-api/datastore/newlist/17&select=nextlist/22/44/myleaf 1931 /yang-api/datastore/somelist/fred%20and%20wilma 1933 /yang-api/datastore/somelist/fred%20and%20wilma/address 1935 5.3.1.1. ABNF For Data Resource Identifiers 1937 The following ABNF syntax is used to construct YANG-API path 1938 identifiers: 1940 api-path = "/" api-identifier 1941 0*("/" (api-identifier | key-value )) 1943 [FIXME: the syntax for the select string is still TBD] 1944 api-select = api-identifier 1945 0*("/" (api-identifier | key-value )) 1947 api-identifier = [module-name ":"] identifier 1949 module-name = identifier 1951 key-value = string 1953 ;; An identifier MUST NOT start with 1954 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 1955 identifier = (ALPHA / "_") 1956 *(ALPHA / DIGIT / "_" / "-" / ".") 1958 string = 1960 5.3.2. Identifying YANG-defined Data Resources 1962 The data resources used in YANG-API are defined with YANG data 1963 definition statements. 1965 Not every data node defined in a YANG module should be treated as a 1966 resource. The YANG-API needs to know which YANG data nodes are 1967 resources, and which are fields within a resource. 1969 For data resources, YANG-API uses a simple algorithm for defining 1970 resource boundaries, within the conceptual sub-trees described by 1971 YANG data definition statements. 1973 All top-level data nodes are considered to be resources. For nodes 1974 within a top-level resource: 1976 o a presence container starts a new resource 1978 o a list starts a new resource 1980 o an optional terminal node (anyxml, leaf, or leaf-list) starts a 1981 new resource 1983 o a data node of type "anyxml" cannot have any sub-resources 1985 A non-configuration data node cannot be a separate resource from its 1986 parent. Only top-level data nodes are considered to be resources 1987 (which only support retrieval methods). 1989 5.3.3. Identifying Optional Keys 1991 It is sometimes useful to have the server assign the key(s) for a new 1992 resource. The "Location" header will indicate the key value(s) that 1993 the server selected, so the client does not need to provide all the 1994 key leaf values. 1996 It is useful to identify in the YANG data model module which key 1997 leafs are optional to provide, and which are not. The YANG extension 1998 statement "optional-key" is provided to indicate that the leaf 1999 definition represents an optional key. 2001 The client MAY provide a value for a key leaf in a POST operation. 2002 Refer to Section 8 for details on the "optional-key" extension. 2003 Refer to Section 13 for usage examples of this YANG extension 2004 statement. 2006 5.3.4. Data Resource Retrieval 2008 There are four types of filtering for retrieval of data resources. 2009 This section defines each mode. 2011 5.3.4.1. Conditional Retrieval 2013 The HTTP headers (such as "If-Modified-Since" and "If-Match") can by 2014 used in for a request message for a GET operation to check a 2015 condition within the server state, such as the last time the 2016 datastore resource was modified, or the resource entity tag of the 2017 target resource. 2019 If the condition is met according to the header definition, a "200 2020 OK" Status-Line and the data requested is returned in the response 2021 message. If the condition is not met, a "304 Not Modified" Status- 2022 Line is returned in response message instead. 2024 5.3.4.2. Data Classification Retrieval 2026 The "config" query parameter can be used with the GET operation to 2027 specify whether configuration or non-configuration data is requested. 2028 Refer to Section 3.8.1 for more details on the "config" query 2029 parameter. 2031 5.3.4.3. Subset Retrieval 2033 The "Range" header is used to request a specific subset of the 2034 instances of a list or leaf-list data resource that are returned by 2035 the server for a retrieval operation. Normally, if the target 2036 resource in a request message does not specify an instance, then all 2037 instances are returned. 2039 The YANG-API protocol uses the token "entries" instead of "bytes" as 2040 the range units. 2042 The entries are numbered starting from "0". A list or leaf-list can 2043 change order between requests so the client needs to be aware of the 2044 data model semantics, and whether the list contents are stable enough 2045 to use the subset retrieval mechanism. 2047 If the requested range cannot be returned because the range 2048 specification includes index values for entries that do not exist, 2049 then an error occurs, and the server MUST return a "416 Requested 2050 range not satisfiable" Status-Line. 2052 If the range request can be satisfied, then a "200 OK" Status-Line is 2053 returned, and the response MUST include a "Content-Range" header 2054 indicating which entries are returned. The response message body 2055 contains the data for the requested range of entries. 2057 Example: 2059 In this example, the client is requesting 5 "artist" resource 2060 entries, starting with the 10th entry: 2062 Request from client: 2064 GET /yang-api/datastore/jukebox/library/artist HTTP/1.1 2065 Host: example.com 2066 Accept: application/vnd.yang.data+json 2067 Range: entries 10-14 2069 Response from server: 2071 HTTP/1.1 200 OK 2072 Date: Mon, 23 Apr 2012 13:01:20 GMT 2073 Cache-Control: no-cache 2074 Pragma: no-cache 2075 Content-Type: application/vnd.yang.data+json 2076 Content-Range: entries 10-14 2077 Server: example-server 2078 Last-Modified: Mon, 23 Apr 2012 02:12:20 GMT 2079 ETag: abcada438af 2081 { 2082 "artist" : { 2083 // content removed for brevity 2084 } 2085 } 2087 5.3.4.4. Filtered Retrieval 2089 The "select" query parameter is used to specify a filter that should 2090 be applied to the target resource to request a subset of all possible 2091 descendant nodes within the target resource. 2093 The format of the "select" parameter string is defined in 2094 Section 3.8.6. The set of nodes selected by the filter expression is 2095 applied to each context node identified by the target resource. 2097 5.4. Operation Resource 2099 An operation resource represents an protocol operation defined with 2100 the YANG "rpc" statement. 2102 All operation resources share the same module namespace as any top- 2103 level data resources, so the name of an operation resource cannot 2104 conflict with the name of a top-level data resource defined within 2105 the same module. 2107 If 2 different YANG modules define the same "rpc" identifier, then 2108 the module name MUST be used in the request URI. For example, if 2109 "module-A" and "module-B" both defined a "reset" operation, then 2110 invoking the operation from "module-A" would be requested as follows: 2112 POST /yang-api/operations/module-A:reset HTTP/1.1 2113 Server example.com 2115 Any usage of an operation resource from the same module, with the 2116 same name, refers to the same "rpc" statement definition. This 2117 behavior can be used to design protocol operations that perform the 2118 same general function on different resource types. 2120 If the "rpc" statement has an "input" section, then a message body 2121 MAY be sent by the client in the request, otherwise the request 2122 message MUST NOT include a message body. If the "rpc" statement has 2123 an "output" section, then a message body MAY be sent by the server in 2124 the response. Otherwise the server MUST NOT include a message body 2125 in the response message, and MUST send a "204 No Content" Status-Line 2126 instead. 2128 5.4.1. Encoding Operation Input Parameters 2130 If the "rpc" statement has an "input" section, then the "input" node 2131 is provided in the message body, corresponding to the YANG data 2132 definition statements within the "input" section. 2134 Example: 2136 The following YANG definition is used for the examples in this 2137 section. 2139 rpc reboot { 2140 input { 2141 leaf delay { 2142 units seconds; 2143 type uint32; 2144 default 0; 2145 } 2146 leaf message { type string; } 2147 leaf language { type string; } 2148 } 2149 } 2151 The client might send the following POST request message: 2153 POST /yang-api/datastore/operations/reboot HTTP/1.1 2154 Host: example.com 2155 Content-Type: application/vnd.yang.data+json 2157 { 2158 "input" : { 2159 "delay" : 600, 2160 "message" : "Going down for system maintenance", 2161 "language" : "en-US" 2162 } 2163 } 2165 The server might respond: 2167 HTTP/1.1 204 No Content 2168 Date: Mon, 25 Apr 2012 11:01:00 GMT 2169 Server: example-server 2171 5.4.2. Encoding Operation Output Parameters 2173 If the "rpc" statement has an "output" section, then the "output" 2174 node is provided in the message body, corresponding to the YANG data 2175 definition statements within the "output" section. 2177 Example: 2179 The following YANG definition is used for the examples in this 2180 section. 2182 rpc get-reboot-info { 2183 input { 2184 leaf reboot-time { 2185 units seconds; 2186 type uint32; 2187 } 2188 leaf message { type string; } 2189 leaf language { type string; } 2190 } 2191 } 2193 The client might send the following POST request message: 2195 POST /yang-api/datastore/operations/get-reboot-info HTTP/1.1 2196 Host: example.com 2198 The server might respond: 2200 HTTP/1.1 200 OK 2201 Date: Mon, 25 Apr 2012 11:10:30 GMT 2202 Server: example-server 2203 Content-Type: application/vnd.yang.data+json 2205 { 2206 "output" : { 2207 "reboot-time" : 30, 2208 "message" : "Going down for system maintenance", 2209 "language" : "en-US" 2210 } 2211 } 2213 5.4.3. Identifying YANG-defined Operation Resources 2215 The operation resources used in YANG-API are defined with YANG "rpc" 2216 statements. All "rpc" statements within a YANG module that are 2217 supported by the server are available as operation resources. 2219 6. Error Reporting 2221 HTTP Status-Lines are used to report success or failure for YANG-API 2222 operations. The element returned in NETCONF error 2223 responses contains some useful information. This error information 2224 is adapted for use in YANG-API, and error information is returned for 2225 "4xx" class of status codes. 2227 The following table summarizes the return status codes used 2228 specifically by YANG-API operations: 2230 +-------------------------------+-----------------------------------+ 2231 | Status-Line | Description | 2232 +-------------------------------+-----------------------------------+ 2233 | 100 Continue | POST accepted, 201 should follow | 2234 | 200 OK | Success with response body | 2235 | 201 Created | POST to create a resource success | 2236 | 202 Accepted | POST to create a resource | 2237 | | accepted | 2238 | 204 No Content | Success without response body | 2239 | 304 Not Modified | Conditional operation not done | 2240 | 400 Bad Request | Invalid request message | 2241 | 403 Forbidden | Access to resource denied | 2242 | 404 Not Found | Resource target or resource node | 2243 | | not found | 2244 | 405 Method Not Allowed | Method not allowed for target | 2245 | | resource | 2246 | 409 Conflict | Resource or lock in use | 2247 | 413 Request Entity Too Large | too-big error | 2248 | 414 Request-URI Too Large | too-big error | 2249 | 415 Unsupported Media Type | non YANG-API media type | 2250 | 416 Requested range not | If-Range error | 2251 | satisfiable | | 2252 | 500 Internal Server Error | operation-failed | 2253 | 501 Not Implemented | unknown-operation | 2254 | 503 Service Unavailable | Recoverable server error | 2255 +-------------------------------+-----------------------------------+ 2257 HTTP Status Codes used in YANG-API 2259 Since an operation resource is defined with a YANG "rpc" statement, a 2260 mapping between the NETCONF value and the HTTP status 2261 code is needed. The specific error condition and response code to 2262 use are data-model specific and might be contained in the YANG 2263 "description" statement for the "rpc" statement. 2265 +-------------------------+-------------+ 2266 | | status code | 2267 +-------------------------+-------------+ 2268 | in-use | 409 | 2269 | invalid-value | 400 | 2270 | too-big | 413 | 2271 | missing-attribute | 400 | 2272 | bad-attribute | 400 | 2273 | unknown-attribute | 400 | 2274 | bad-element | 400 | 2275 | unknown-element | 400 | 2276 | unknown-namespace | 400 | 2277 | access-denied | 403 | 2278 | lock-denied | 409 | 2279 | resource-denied | 409 | 2280 | rollback-failed | 500 | 2281 | data-exists | 409 | 2282 | data-missing | 409 | 2283 | operation-not-supported | 501 | 2284 | operation-failed | 500 | 2285 | partial-operation | 500 | 2286 | malformed-message | 400 | 2287 +-------------------------+-------------+ 2289 Mapping from error-tag to status code 2291 6.1. Error Response Message 2293 When an error occurs for a request message on a data resource or an 2294 operation resource, and a "4xx" class of status codes (except for 2295 status code "403"), then the server SHOULD send a response body 2296 containing the information described by the following YANG data 2297 definition statement: 2299 container errors { 2300 config false; 2302 list error { 2303 reference "RFC 6241, Section 4.3"; 2304 leaf error-type { 2305 mandatory true; 2306 type enumeration { 2307 enum transport; 2308 enum rpc; 2309 enum protocol; 2310 enum application; 2311 } 2312 } 2313 leaf error-tag { 2314 mandatory true; 2315 type string; 2316 } 2317 leaf error-app-tag { 2318 type string; 2319 } 2320 leaf error-path { 2321 type string; // YANG-API encoded instance-identifier 2322 } 2323 leaf error-message { 2324 type string; 2325 } 2326 container error-info { 2327 // anyxml content here 2328 } 2329 } 2330 } 2332 Example: 2334 The following example shows an error returned for an "lock-denied" 2335 error on a datastore resource. 2337 POST /yang-api/operations/lock-datastore HTTP/1.1 2338 Host: example.com 2340 The server might respond: 2342 HTTP/1.1 409 Conflict 2343 Date: Mon, 23 Apr 2012 17:11:00 GMT 2344 Server: example-server 2345 Content-Type: application/vnd.yang.api+json 2347 { 2348 "errors": { 2349 "error": { 2350 "error-type": "protocol", 2351 "error-tag": "lock-denied", 2352 "error-message": "Lock failed, lock is already held", 2353 } 2354 } 2355 } 2357 7. RelaxNG Grammar 2359 TBD 2361 8. YANG-API module 2363 RFC Ed.: update the date below with the date of RFC publication and 2364 remove this note. 2366 file "ietf-yang-api@2012-11-30.yang" 2368 module ietf-yang-api { 2369 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-api"; 2370 prefix "api"; 2372 organization 2373 "IETF NETCONF (Network Configuration) Working Group"; 2375 contact 2376 "Editor: Andy Bierman 2377 2379 Editor: Martin Bjorklund 2380 "; 2382 description 2383 "This module contains a collection of YANG language extensions 2384 to describe REST API Resources using YANG data definition 2385 statements. 2387 Copyright (c) 2012 IETF Trust and the persons identified as 2388 authors of the code. All rights reserved. 2390 Redistribution and use in source and binary forms, with or 2391 without modification, is permitted pursuant to, and subject 2392 to the license terms contained in, the Simplified BSD License 2393 set forth in Section 4.c of the IETF Trust's Legal Provisions 2394 Relating to IETF Documents 2395 (http://trustee.ietf.org/license-info). 2397 This version of this YANG module is part of RFC XXXX; see 2398 the RFC itself for full legal notices."; 2400 // RFC Ed.: replace XXXX with actual RFC number and remove this 2401 // note. 2403 // RFC Ed.: remove this note 2404 // Note: extracted from draft-bierman-netconf-yang-api-01.txt 2406 // RFC Ed.: update the date below with the date of RFC publication 2407 // and remove this note. 2408 revision 2012-11-30 { 2409 description 2410 "Initial revision."; 2411 reference 2412 "RFC XXXX: YANG-API Protocol."; 2413 } 2415 /* 2416 * Extensions 2417 */ 2419 extension optional-key { 2420 description 2421 "This extension is used to allow the client to create 2422 a new instance of a resource without providing a 2423 value for the key leaf containing this statement. 2424 This extension is ignored for NETCONF, and only 2425 applies to YANG-API resources and fields. 2426 This extension is ignored unless it appears 2427 directly within a 'leaf' data definition statement."; 2428 } 2430 } 2432 2434 9. IANA Considerations 2436 This document registers one URI in the IETF XML registry [RFC3688]. 2437 Following the format in RFC 3688, the following registration is 2438 requested to be made. 2440 URI: urn:ietf:params:xml:ns:yang:ietf-yang-api 2441 Registrant Contact: The NETMOD WG of the IETF. 2442 XML: N/A, the requested URI is an XML namespace. 2444 This document registers one YANG module in the YANG Module Names 2445 registry [RFC6020]. 2447 name: ietf-yang-api 2448 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-api 2449 prefix: api 2450 reference: RFC XXXX 2452 10. Security Considerations 2454 TBD 2456 11. Change Log 2458 -- RFC Ed.: remove this section before publication. 2460 11.1. 00-01 2462 o expanded introduction 2464 o removed transactions 2466 o removed capabilities 2468 o simplified editing model 2470 o removed global protocol operations from ietf-yang-api.yang 2472 o changed RPC operation terminology to protocol operation 2474 o updated JSON draft reference 2476 o updated open issues section 2478 o updated IANA section 2480 12. Open Issues 2482 o Which WG should do this work? NETCONF? NETMOD? It is not clear 2483 since YANG-API builds on concepts and standards from documents 2484 owned by both working groups. 2486 o Resource creation order and other dependencies between resources 2487 are not well identified in YANG. YANG has leafrefs and instance- 2488 identifiers, which can be used to identify some order 2489 dependencies. Are any new mechanisms needed in YANG-API needed to 2490 identify resource creation order and other dependency 2491 requirements? 2493 o There is no "message-id" field in a YANG-API message. Is a 2494 message identifier needed? If so, should either the "Message-ID" 2495 or "Content-ID" header from RFC 2392 be used for this purpose? 2497 o Should sessions be used or not? Should "reusable sessions" be 2498 used? Better for auditing? How does locking of the /yang-api/ 2499 datastore resource work for multiple edits if a session is 1 2500 operation? When does the server release the lock and decide it 2501 has been abandoned or client was disconnected? 2503 o What syntax should be used for the "select" query parameter? 2505 o Should the "/yang-api/modules" field within the API resource be a 2506 separate resource, with its own timestamp? Currently the API 2507 timestamp is coupled to any changes to the list of loaded modules. 2508 Should the API resource be static and cacheable? 2510 o What to do about no REMOVE operation, just DELETE? The effect is 2511 local to the request; in a NETCONF edit-config it is worse, since 2512 the netconf request might create/delete/modify many nodes 2514 o Should every YANG data node be a data resource and every YANG RPC 2515 statement an operation resource? Is a YANG extension needed to 2516 allow data modeler control of resource boundaries? 2518 o Encoding of leafrefs? Is there some additional meta-data needed? 2519 Do leafref nodes need to be identified in responses (RFC 5988) or 2520 is the YANG module definition sufficient to provide this meta- 2521 data? 2523 o What should the default algorithm be for defining data resources? 2524 Should the default for an augment from another namespace be to 2525 start a new resource? Top-level data node defaults as a resource 2526 OK? 2528 o Is the token "entries" legal in the YANG-API usage of Range? What 2529 units should be used? "bytes" is the only token defined by HTTP. 2531 o Are all header lines used by YANG-API supported by common 2532 application frameworks, such as FastCGI and WSGI? If not, then 2533 should query parameters be used instead, since the QUERY_STRING is 2534 widely available to WEB applications? 2536 o Should the element returned in error responses be a 2537 separate media type? 2539 o How should additional datastores be supported, which may be added 2540 to the NETCONF/NETMOD framework in the future? 2542 13. Example YANG Module 2544 module example-jukebox { 2546 namespace "http://example.com/ns/example-jukebox"; 2547 prefix "jbox"; 2549 import ietf-yang-api { prefix api; } 2551 organization "Example, Inc."; 2552 description "Example Jukebox Data Model Module"; 2553 revision "2012-05-30"; 2555 identity genre { 2556 description "Base for all genre types"; 2557 } 2559 // abbreviated list of genre classifications 2560 identity Alternative { 2561 base genre; 2562 } 2563 identity Blues { 2564 base genre; 2565 } 2566 identity Country { 2567 base genre; 2568 } 2569 identity Jazz { 2570 base genre; 2571 } 2572 identity Pop { 2573 base genre; 2574 } 2575 identity Rock { 2576 base genre; 2577 } 2579 container jukebox { 2580 presence 2581 "An empty container indicates that the jukebox 2582 service is available"; 2584 container library { 2585 list artist { 2586 key index; 2587 unique name; 2588 leaf index { 2589 api:optional-key; 2590 type uint32; 2591 description 2592 "Optional key used instead of natural key for 2593 example. Also rare but possible artists with 2594 the same name are really different entities."; 2595 } 2596 leaf name { 2597 type string; 2598 } 2600 list album { 2601 key name; 2602 leaf name { 2603 type string { 2604 length "1 .. max"; 2605 } 2606 } 2607 leaf genre { 2608 type identityref { base genre; } 2609 } 2610 leaf year { 2611 type uint16 { 2612 range "1900 .. max"; 2613 } 2614 } 2615 list song { 2616 api:optional-key; 2617 key index; 2618 ordered-by user; 2619 leaf index { 2620 type uint32; 2621 } 2622 leaf name { 2623 mandatory true; 2624 type string; 2625 } 2626 leaf location { 2627 mandatory true; 2628 type string; 2629 } 2630 leaf format { 2631 type string; 2632 } 2633 leaf length { 2634 units "seconds"; 2635 type uint32; 2637 } 2638 } 2639 } 2640 } 2641 leaf artist-count { 2642 config false; 2643 type uint32; 2644 units "songs"; 2645 description "Number of artists in the library"; 2646 } 2647 leaf album-count { 2648 config false; 2649 type uint32; 2650 units "albums"; 2651 description "Number of albums in the library"; 2652 } 2653 leaf song-count { 2654 type uint32; 2655 units "songs"; 2656 description "Number of songs in the library"; 2657 } 2658 } 2660 list playlist { 2661 description 2662 "Example configuration data resource"; 2663 key name; 2664 leaf name { 2665 type string; 2666 } 2667 leaf description { 2668 type string; 2669 } 2670 list song { 2671 description 2672 "Example nested configuration data resource"; 2673 ordered-by user; 2674 key index; 2675 leaf index { 2676 api:optional-key; 2677 type uint32; 2678 } 2679 leaf id { 2680 mandatory true; 2681 type instance-identifier; 2682 description 2683 "Song identifier. Must identify an instance of 2684 /jukebox/library/artist/album/song. 2686 The id is not the key to allow duplicates 2687 in a playlist"; 2688 } 2689 } 2690 } 2692 container player { 2693 leaf gap { 2694 description "Time gap between each song"; 2695 units "tenths of seconds"; 2696 type decimal64 { 2697 fraction-digits 1; 2698 range "0.0 .. 2.0"; 2699 } 2700 } 2701 } 2702 } 2704 rpc play { 2705 description "Control function for the jukebox player"; 2706 input { 2707 leaf playlist { 2708 type string; 2709 mandatory true; 2710 description "playlist name"; 2711 } 2712 leaf song-number { 2713 type uint32; 2714 mandatory true; 2715 description "Song number in playlist to play"; 2716 } 2717 } 2718 } 2719 } 2721 14. Normative References 2723 [I-D.lhotka-netmod-json] 2724 Lhotka, L., "Modeling JSON Text with YANG", 2725 draft-lhotka-netmod-yang-json-00 (work in progress), 2726 October 2012. 2728 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2729 Requirement Levels", BCP 14, RFC 2119, March 1997. 2731 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2732 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2733 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2735 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2736 January 2004. 2738 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2739 Resource Identifier (URI): Generic Syntax", STD 66, 2740 RFC 3986, January 2005. 2742 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 2743 RFC 5789, March 2010. 2745 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2746 Network Configuration Protocol (NETCONF)", RFC 6020, 2747 October 2010. 2749 [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, 2750 October 2010. 2752 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2753 and A. Bierman, Ed., "Network Configuration Protocol 2754 (NETCONF)", RFC 6241, June 2011. 2756 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2757 Protocol (NETCONF) Access Control Model", RFC 6536, 2758 March 2012. 2760 Authors' Addresses 2762 Andy Bierman 2763 YumaWorks 2765 Email: andy@yumaworks.com 2767 Martin Bjorklund 2768 Tail-f Systems 2770 Email: mbj@tail-f.com