idnits 2.17.1 draft-ietf-netconf-restconf-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 889 has weird spacing: '... method entry...' == Line 1174 has weird spacing: '...mespace ine...' == Line 1179 has weird spacing: '...evision uni...' == Line 3063 has weird spacing: '...ocation str...' == Line 3073 has weird spacing: '...w index uin...' == (1 more instance...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 3, 2014) is 3584 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 6 errors (**), 0 flaws (~~), 9 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track M. Bjorklund 5 Expires: January 4, 2015 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 R. Fernando 9 Cisco 10 July 3, 2014 12 RESTCONF Protocol 13 draft-ietf-netconf-restconf-01 15 Abstract 17 This document describes an HTTP-based protocol that provides a 18 programmatic interface for accessing data defined in YANG, using the 19 datastores defined in NETCONF. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 4, 2015. 38 Copyright Notice 40 Copyright (c) 2014 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.1. Secure Transport . . . . . . . . . . . . . . . . . . . . . 5 57 1.2. Simple Subset of NETCONF Functionality . . . . . . . . . . 5 58 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 6 59 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 60 1.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 8 61 1.4.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 1.4.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 9 63 1.4.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 10 64 1.4.5. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 11 65 2. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 12 66 2.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 12 67 2.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 69 2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 70 2.4.1. Create Resource Mode . . . . . . . . . . . . . . . . . 14 71 2.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 15 72 2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 73 2.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 17 74 2.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 18 75 2.8. Query Parameters . . . . . . . . . . . . . . . . . . . . . 19 76 3. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 77 3.1. Request URI Structure . . . . . . . . . . . . . . . . . . 21 78 3.2. RESTCONF Path Resolution . . . . . . . . . . . . . . . . . 22 79 3.3. Message Headers . . . . . . . . . . . . . . . . . . . . . 23 80 3.4. Message Encoding . . . . . . . . . . . . . . . . . . . . . 24 81 3.5. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . . 25 82 3.6. Return Status . . . . . . . . . . . . . . . . . . . . . . 25 83 3.7. Message Caching . . . . . . . . . . . . . . . . . . . . . 25 84 4. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 26 85 4.1. RESTCONF Resource Types . . . . . . . . . . . . . . . . . 26 86 4.2. Resource Discovery . . . . . . . . . . . . . . . . . . . . 27 87 4.3. API Resource . . . . . . . . . . . . . . . . . . . . . . . 27 88 4.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . . 28 89 4.3.2. {+restconf}/modules . . . . . . . . . . . . . . . . . 29 90 4.3.3. {+restconf}/operations . . . . . . . . . . . . . . . . 30 91 4.3.4. {+restconf}/streams . . . . . . . . . . . . . . . . . 30 92 4.4. Datastore Resource . . . . . . . . . . . . . . . . . . . . 30 93 4.4.1. Edit Collision Detection . . . . . . . . . . . . . . . 31 94 4.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 31 95 4.5.1. Encoding YANG Instance Identifiers in the Request 96 URI . . . . . . . . . . . . . . . . . . . . . . . . . 32 97 4.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 34 98 4.6. Operation Resource . . . . . . . . . . . . . . . . . . . . 35 99 4.6.1. Encoding Operation Input Parameters . . . . . . . . . 35 100 4.6.2. Encoding Operation Output Parameters . . . . . . . . . 36 101 4.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 37 102 4.8. Stream Resource . . . . . . . . . . . . . . . . . . . . . 38 103 4.9. Errors Resource . . . . . . . . . . . . . . . . . . . . . 38 104 5. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 39 105 5.1. Server Support . . . . . . . . . . . . . . . . . . . . . . 39 106 5.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 39 107 5.3. Subscribing to Receive Notifications . . . . . . . . . . . 40 108 5.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . . 41 109 5.4. Receiving Event Notifications . . . . . . . . . . . . . . 41 110 6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 43 111 6.1. Error Response Message . . . . . . . . . . . . . . . . . . 44 112 7. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 47 113 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 61 114 8.1. The "restconf" Relation Type . . . . . . . . . . . . . . . 61 115 8.2. YANG Module Registry . . . . . . . . . . . . . . . . . . . 61 116 8.3. application/yang Media Sub Types . . . . . . . . . . . . . 61 117 9. Security Considerations . . . . . . . . . . . . . . . . . . . 63 118 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 64 119 10.1. Normative References . . . . . . . . . . . . . . . . . . . 64 120 10.2. Informative References . . . . . . . . . . . . . . . . . . 65 121 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 66 122 A.1. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 66 123 A.2. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 67 124 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 68 125 B.1. select parameter . . . . . . . . . . . . . . . . . . . . . 68 126 B.2. netconf-state monitoring support . . . . . . . . . . . . . 68 127 B.3. secure transport . . . . . . . . . . . . . . . . . . . . . 68 128 B.4. Encoding of key leafs in resource URIs . . . . . . . . . . 68 129 B.5. get-bulk query parameters . . . . . . . . . . . . . . . . 69 130 B.6. defaults handling . . . . . . . . . . . . . . . . . . . . 69 131 B.7. protocol capability URIs . . . . . . . . . . . . . . . . . 69 132 B.8. target resource list keys required for GET . . . . . . . . 70 133 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . . 71 134 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 71 135 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . . 77 136 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 77 137 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 77 138 D.1.2. Retrieve The Server Module Information . . . . . . . . 79 139 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . . 81 140 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 81 141 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 82 142 D.3. Query String Parameter Examples . . . . . . . . . . . . . 82 143 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 82 144 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 85 145 D.3.3. "filter" Parameter . . . . . . . . . . . . . . . . . . 88 146 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . . 89 147 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 90 148 D.3.6. "select" Parameter . . . . . . . . . . . . . . . . . . 90 149 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . . 91 150 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 91 151 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 92 153 1. Introduction 155 There is a need for standard mechanisms to allow WEB applications to 156 access the configuration data, operational data, data-model specific 157 protocol operations, and notification events within a networking 158 device, in a modular and extensible manner. 160 This document describes an HTTP [RFC2616] based protocol called 161 RESTCONF, for accessing data defined in YANG [RFC6020], using 162 datastores defined in NETCONF [RFC6241]. 164 The NETCONF protocol defines configuration datastores and a set of 165 Create, Retrieve, Update, Delete (CRUD) operations that can be used 166 to access these datastores. The YANG language defines the syntax and 167 semantics of datastore content, operational data, protocol 168 operations, and notification events. RESTCONF uses HTTP operations 169 to provide CRUD operations on a NETCONF datastore containing YANG- 170 defined data. Since NETCONF protocol operations are not relevant, 171 the user should not need any prior knowledge of NETCONF in order to 172 use RESTCONF. 174 Configuration data and state data are exposed as resources that can 175 be retrieved with the GET method. Resources representing 176 configuration data can be modified with the DELETE, PATCH, POST, and 177 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 178 or JSON [JSON]. 180 Data-model specific protocol operations defined with the YANG "rpc" 181 statement can be invoked with the POST method. Data-model specific 182 notification events defined with the YANG "notification" statement 183 can be accessed. 185 1.1. Secure Transport 187 RESTCONF relies on TLS [RFC2246] to provide privacy and data 188 integrity for its HTTP operations. More specifically, RESTCONF 189 requires HTTP over TLS (HTTPS) [RFC2818]. To ensure security, 190 RESTCONF clients MUST verify the RESTCONF server's X.509 certificate 191 using the path validation algorithm defined in section 6 of 192 [RFC5280]. Devices that do not support TLS will be unable to 193 implement RESTCONF. 195 1.2. Simple Subset of NETCONF Functionality 197 The framework and meta-model used for an HTTP-based API does not need 198 to mirror those used by the NETCONF protocol, but it needs to be 199 compatible with NETCONF. A simplified framework and protocol is 200 needed that utilizes the three NETCONF datastores (candidate, 201 running, startup), but hides the complexity of multiple datastores 202 from the client. 204 A simplified transaction model is needed that allows basic CRUD 205 operations on a hierarchy of conceptual resources. This represents a 206 limited subset of the transaction capabilities of the NETCONF 207 protocol. 209 Applications that require more complex transaction capabilities might 210 consider NETCONF instead of RESTCONF. The following transaction 211 features are not directly provided in RESTCONF: 213 o datastore locking (full or partial) 215 o candidate datastore 217 o startup datastore 219 o validate operation 221 o confirmed-commit procedure 223 RESTCONF is not intended to replace NETCONF, but rather provide an 224 additional simplified interface that follows REST principles and is 225 compatible with a resource-oriented device abstraction. 227 The following figure shows the system components: 229 +-----------+ +-----------------+ 230 | WEB app | <-------> | | 231 +-----------+ HTTP | network device | 232 | | 233 +-----------+ | +-----------+ | 234 | NMS app | <-------> | | datastore | | 235 +-----------+ NETCONF | +-----------+ | 236 +-----------------+ 238 1.3. Data Model Driven API 240 RESTCONF combines the simplicity of the HTTP protocol with the 241 predictability and automation potential of a schema-driven API. 242 Using YANG, a client can predict all resource endpoints, much like 243 using URI Templates [RFC6570], but in a more holistic manner. This 244 strategy obviates the need for responses provided by the server to 245 contain HATEOAS links, originally described in Roy Fielding's 246 doctoral dissertation [rest-dissertation]. 248 A REST client using HATEOAS principles would not use any data 249 modeling language to define the application-specific content of the 250 API. The client would discover each new child resource as it 251 traverses the URIs returned as Location IDs to discover the server 252 capabilities. This approach has 3 significant weaknesses with 253 regards to control of complex networking devices: 255 o inefficient performance: configuration APIs will be quite complex 256 and may require thousands of protocol messages to discover all the 257 schema information. Typically the data type information has to be 258 passed in the protocol messages, which is also wasteful overhead. 260 o no data model richness: without a data model, the schema-level 261 semantics and validation constraints are not available to the 262 application. 264 o no tool automation: API automation tools need some sort of content 265 schema to function. Such tools can automate various programming 266 and documentation tasks related to specific data models. 268 Data model modules such as YANG modules serve as an "API contract" 269 that will be honored by the server. An application designer can code 270 to the data model, knowing in advance important details about the 271 exact protocol operations and datastore content a conforming server 272 implementation will support. 274 RESTCONF provides the YANG module capability information supported by 275 the server, in case the client wants to use it. The URIs for custom 276 protocol operations and datastore content are predictable, based on 277 the YANG module definitions. 279 Operational experience with CLI and SNMP indicates that operators 280 learn the 'location' of specific service or device related data and 281 do not expect such information to be arbitrary and discovered each 282 time the client opens a management session to a server. 284 The RESTCONF protocol operates on a conceptual datastore defined with 285 the YANG data modeling language. The server lists each YANG module 286 it supports under "{+restconf}/modules" in the top-level API resource 287 type, using a structure based on the YANG module capability URI 288 format defined in [RFC6020]. 290 The conceptual datastore contents, data-model-specific operations and 291 notification events are identified by this set of YANG module 292 resources. All RESTCONF content identified as either a data 293 resource, operation resource, or event stream resource is defined 294 with the YANG language. 296 The classification of data as configuration or non-configuration is 297 derived from the YANG "config" statement. Data ordering behavior is 298 derived from the YANG "ordered-by" statement. 300 The RESTCONF datastore editing model is simple and direct, similar to 301 the behavior of the ":writable-running" capability in NETCONF. Each 302 RESTCONF edit of a datastore resource is activated upon successful 303 completion of the transaction. 305 1.4. Terminology 307 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 308 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 309 "OPTIONAL" in this document are to be interpreted as described in BCP 310 14, [RFC2119]. 312 1.4.1. NETCONF 314 The following terms are defined in [RFC6241]: 316 o candidate configuration datastore 318 o client 320 o configuration data 322 o datastore 324 o configuration datastore 326 o protocol operation 328 o running configuration datastore 330 o server 332 o startup configuration datastore 334 o state data 336 o user 338 1.4.2. HTTP 340 The following terms are defined in [RFC2616]: 342 o entity tag 343 o fragment 345 o header line 347 o message body 349 o method 351 o path 353 o query 355 o request 357 o request URI 359 o response body 361 o resource 363 1.4.3. YANG 365 The following terms are defined in [RFC6020]: 367 o container 369 o data node 371 o key leaf 373 o leaf 375 o leaf-list 377 o list 379 o presence container (or P-container) 381 o RPC operation (now called protocol operation) 383 o non-presence container (or NP-container) 385 o ordered-by system 387 o ordered-by user 389 1.4.4. Terms 391 The following terms are used within this document: 393 o API resource: a resource with the media type "application/ 394 yang.api+xml" or "application/yang.api+json". API resources can 395 only be edited by the server. 397 o data resource: a resource with the media type "application/ 398 yang.data+xml" or "application/yang.data+json". Data resources 399 can be edited by clients or the server. All YANG data node types 400 can be data resources. YANG terminal nodes cannot contain child 401 resources. 403 o datastore resource: a resource with the media type "application/ 404 yang.datastore+xml" or "application/yang.datastore+json". 405 Represents a configuration datastore. 407 o edit operation: a RESTCONF operation on a data resource using the 408 POST, PUT, PATCH, or DELETE method. 410 o event stream resource: a resource with the media type 411 "application/yang.stream+xml" or "application/yang.stream+json". 412 This resource represents an SSE (Server-Sent Events) event stream. 413 The content consists of text using the media type "text/ 414 event-stream", as defined by the HTML5 specification. Each event 415 represents one message generated by the server. It 416 contains a conceptual system or data-model specific event that is 417 delivered within a notification event stream. 419 o operation: the conceptual RESTCONF operation for a message, 420 derived from the HTTP method, request URI, headers, and message 421 body. 423 o operation resource: a resource with the media type "application/ 424 yang.operation+xml" or "application/yang.operation+json". 426 o patch: a generic PATCH request on the target datastore or data 427 resource. The media type of the message body content will 428 identify the patch type in use. 430 o plain patch: a PATCH request where the media type is "application/ 431 yang.data+xml" or "application/yang.data+json". 433 o query parameter: a parameter (and its value if any), encoded 434 within the query component of the request URI. 436 o retrieval request: a request using the GET or HEAD methods. 438 o target resource: the resource that is associated with a particular 439 message, identified by the "path" component of the request URI. 441 o unified datastore: A conceptual representation of the device 442 running configuration. The server will hide all NETCONF datastore 443 details for edit operations, such as the ":candidate" and 444 ":startup" capabilities. 446 o schema resource: a resource with the media type "application/ 447 yang". The YANG representation of the schema can be retrieved by 448 the client with the GET method. 450 o YANG terminal node: a YANG node representing a leaf, leaf-list, or 451 anyxml definition. 453 1.4.5. Tree Diagrams 455 A simplified graphical representation of the data model is used in 456 this document. The meaning of the symbols in these diagrams is as 457 follows: 459 o Brackets "[" and "]" enclose list keys. 461 o Abbreviations before data node names: "rw" means configuration 462 data (read-write) and "ro" state data (read-only). 464 o Symbols after data node names: "?" means an optional node, "!" 465 means a presence container, and "*" denotes a list and leaf-list. 467 o Parentheses enclose choice and case nodes, and case nodes are also 468 marked with a colon (":"). 470 o Ellipsis ("...") stands for contents of subtrees that are not 471 shown. 473 2. Operations 475 The RESTCONF protocol uses HTTP methods to identify the CRUD 476 operation requested for a particular resource. 478 The following table shows how the RESTCONF operations relate to 479 NETCONF protocol operations: 481 +----------+-------------------------------------+ 482 | RESTCONF | NETCONF | 483 +----------+-------------------------------------+ 484 | OPTIONS | none | 485 | HEAD | none | 486 | GET | , | 487 | POST | (operation="create") | 488 | PUT | (operation="replace") | 489 | PATCH | (operation="merge") | 490 | DELETE | (operation="delete") | 491 +----------+-------------------------------------+ 493 Table 1: CRUD Methods in RESTCONF 495 The NETCONF "remove" operation attribute is not supported by the HTTP 496 DELETE method. The resource must exist or the DELETE method will 497 fail. The PATCH method is equivalent to a "merge" operation for a 498 plain patch. 500 Access control mechanisms may be used to limit what operations can be 501 used. In particular, RESTCONF is compatible with the NETCONF Access 502 Control Model (NACM) [RFC6536], as there is a specific mapping 503 between RESTCONF and NETCONF operations, defined in Table 1. The 504 resource path needs to be converted internally by the server to the 505 corresponding YANG instance-identifier. Using this information, the 506 server can apply the NACM access control rules to RESTCONF messages. 508 The server MUST NOT allow any operation to any resources that the 509 client is not authorized to access. 511 Implementation of all methods (except PATCH) are defined in 512 [RFC2616]. This section defines the RESTCONF protocol usage for each 513 HTTP method. 515 2.1. OPTIONS 517 The OPTIONS method is sent by the client to discover which methods 518 are supported by the server for a specific resource. If supported, 519 it SHOULD be implemented for all media types. 521 The server SHOULD implement this method, however the same information 522 could be extracted from the YANG modules and the RESTCONF protocol 523 specification. 525 If the PATCH method is supported, then the "Accept-Patch" header MUST 526 be supported, as defined in [RFC5789]. 528 2.2. HEAD 530 The HEAD method is sent by the client to retrieve just the headers 531 that would be returned for the comparable GET method, without the 532 response body. It is supported for all resource types, except 533 operation resources. 535 The request MUST contain a request URI that contains at least the 536 entry point component. The same query parameters supported by the 537 GET method are supported by the HEAD method. 539 The access control behavior is enforced as if the method was GET 540 instead of HEAD. The server MUST respond the same as if the method 541 was GET instead of HEAD, except that no response body is included. 543 2.3. GET 545 The GET method is sent by the client to retrieve data and meta-data 546 for a resource. It is supported for all resource types, except 547 operation resources. The request MUST contain a request URI that 548 contains at least the entry point component. 550 The server MUST NOT return any data resources for which the user does 551 not have read privileges. If the user is not authorized to read the 552 target resource, an error response containing a "403 Forbidden" or 553 "404 Not Found" Status-Line is returned to the client. 555 If the user is authorized to read some but not all of the target 556 resource, the unauthorized content is omitted from the response 557 message body, and the authorized content is returned to the client. 559 Example: 561 The client might request the response headers for a JSON 562 representation of the "library" resource: 564 GET /restconf/data/example-jukebox:jukebox/ 565 library/artist=Foo%20Fighters/album HTTP/1.1 566 Host: example.com 567 Accept: application/yang.data+json, 568 application/yang.errors+json 570 The server might respond: 572 HTTP/1.1 200 OK 573 Date: Mon, 23 Apr 2012 17:02:40 GMT 574 Server: example-server 575 Content-Type: application/yang.data+json 576 Cache-Control: no-cache 577 Pragma: no-cache 578 ETag: a74eefc993a2b 579 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 581 { 582 "album" : [ 583 { 584 "name" : "Wasting Light", 585 "genre" : "example-jukebox:alternative", 586 "year" : 2011 587 } 588 ] 589 } 591 2.4. POST 593 The POST method is sent by the client to create a data resource or 594 invoke an operation resource. The server uses the target resource 595 media type to determine how to process the request. 597 +-----------+------------------------------------------------+ 598 | Type | Description | 599 +-----------+------------------------------------------------+ 600 | Datastore | Create a top-level configuration data resource | 601 | Data | Create a configuration data child resource | 602 | Operation | Invoke a protocol operation | 603 +-----------+------------------------------------------------+ 605 Resource Types that Support POST 607 2.4.1. Create Resource Mode 609 If the target resource type is a datastore or data resource, then the 610 POST is treated as a request to create a resource or child resource. 611 The message body is expected to contain the content of a child 612 resource to create within the parent (target resource). 614 The "insert" and "point" query parameters are supported by the POST 615 method for datastore and data resource types, as specified in the 616 YANG definition in Section 7. 618 If the POST method succeeds, a "201 Created" Status-Line is returned 619 and there is no response message body. A "Location" header 620 identifying the child resource that was created MUST be present in 621 the response in this case. 623 If the user is not authorized to create the target resource, an error 624 response containing a "403 Forbidden" or "404 Not Found" Status-Line 625 is returned to the client. All other error responses are handled 626 according to the procedures defined in Section 6. 628 Example: 630 To create a new "jukebox" resource, the client might send: 632 POST /restconf/data HTTP/1.1 633 Host: example.com 634 Content-Type: application/yang.data+json 636 { "example-jukebox:jukebox" : [null] } 638 If the resource is created, the server might respond as follows: 640 HTTP/1.1 201 Created 641 Date: Mon, 23 Apr 2012 17:01:00 GMT 642 Server: example-server 643 Location: http://example.com/restconf/data/example-jukebox:jukebox 644 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 645 ETag: b3a3e673be2 647 Refer to Appendix D.2.1 for more resource creation examples. 649 2.4.2. Invoke Operation Mode 651 If the target resource type is an operation resource, then the POST 652 method is treated as a request to invoke that operation. The message 653 body (if any) is processed as the operation input parameters. Refer 654 to Section 4.6 for details on operation resources. 656 If the POST request succeeds, a "200 OK" Status-Line is returned if 657 there is a response message body, and a "204 No Content" Status-Line 658 is returned if there is no response message body. 660 If the user is not authorized to invoke the target operation, an 661 error response containing a "403 Forbidden" or "404 Not Found" 662 Status-Line is returned to the client. All other error responses are 663 handled according to the procedures defined in Section 6. 665 Example: 667 In this example, the client is invoking the "play" operation defined 668 in the "example-jukebox" YANG module. 670 A client might send a "play" request as follows: 672 POST /restconf/operations/example-jukebox:play HTTP/1.1 673 Host: example.com 674 Content-Type: application/yang.operation+json 676 { 677 "example-jukebox:input" : { 678 "playlist" : "Foo-One", 679 "song-number" : 2 680 } 681 } 683 The server might respond: 685 HTTP/1.1 204 No Content 686 Date: Mon, 23 Apr 2012 17:50:00 GMT 687 Server: example-server 689 2.5. PUT 691 The PUT method is sent by the client to create or replace the target 692 resource. 694 The only target resource media type that supports PUT is the data 695 resource. The message body is expected to contain the content used 696 to create or replace the target resource. 698 The "insert" and "point" query parameters are supported by the PUT 699 method for data resources, as specified in the YANG definition in 700 Section 7. 702 Consistent with [RFC2616], if the PUT request creates a new resource, 703 a "201 Created" Status-Line is returned. If an existing resource is 704 modified, either "200 OK" or "204 No Content" are returned. 706 If the user is not authorized to create or replace the target 707 resource an error response containing a "403 Forbidden" or "404 Not 708 Found" Status-Line is returned to the client. All other error 709 responses are handled according to the procedures defined in 710 Section 6. 712 Example: 714 An "album" child resource defined in the "example-jukebox" YANG 715 module is replaced or created if it does not already exist. 717 To replace the "album" resource contents, the client might send as 718 follows. Note that the request URI header line is wrapped for 719 display purposes only: 721 PUT /restconf/data/example-jukebox:jukebox/ 722 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 723 Host: example.com 724 Content-Type: application/yang.data+json 726 { 727 "example-jukebox:album" : { 728 "name" : "Wasting Light", 729 "genre" : "example-jukebox:alternative", 730 "year" : 2011 731 } 732 } 734 If the resource is updated, the server might respond: 736 HTTP/1.1 204 No Content 737 Date: Mon, 23 Apr 2012 17:04:00 GMT 738 Server: example-server 739 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 740 ETag: b27480aeda4c 742 2.6. PATCH 744 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 745 an extensible framework for resource patching mechanisms. It is 746 optional to implement by the server. Each patch type needs a unique 747 media type. Zero or more PATCH media types MAY be supported by the 748 server. 750 A plain patch is used to create or update a child resource within the 751 target resource. If the target resource instance does not exist, the 752 server MUST NOT create it. 754 If the PATCH request succeeds, a "200 OK" Status-Line is returned if 755 there is a message body, and "204 No Content" is returned if no 756 response message body is sent. 758 If the user is not authorized to alter the target resource an error 759 response containing a "403 Forbidden" or "404 Not Found" Status-Line 760 is returned to the client. All other error responses are handled 761 according to the procedures defined in Section 6. 763 Example: 765 To replace just the "year" field in the "album" resource (instead of 766 replacing the entire resource with the PUT method), the client might 767 send a plain patch as follows. Note that the request URI header line 768 is wrapped for display purposes only: 770 PATCH /restconf/data/example-jukebox:jukebox/ 771 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 772 Host: example.com 773 Content-Type: application/yang.data+json 775 { 776 "example-jukebox:album" : { 777 "genre" : "example-jukebox:rock", 778 "year" : 2011 779 } 780 } 782 If the field is updated, the server might respond: 784 HTTP/1.1 204 No Content 785 Date: Mon, 23 Apr 2012 17:49:30 GMT 786 Server: example-server 787 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 788 ETag: b2788923da4c 790 The XML encoding for the same request might be: 792 PATCH /restconf/data/example-jukebox:jukebox/ 793 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 794 Host: example.com 795 If-Match: b8389233a4c 796 Content-Type: application/yang.data+xml 798 799 example-jukebox:rock 800 2011 801 803 2.7. DELETE 805 The DELETE method is used to delete the target resource. If the 806 DELETE request succeeds, a "204 No Content" Status-Line is returned, 807 and there is no response message body. 809 If the user is not authorized to delete the target resource then an 810 error response containing a "403 Forbidden" or "404 Not Found" 811 Status-Line is returned to the client. All other error responses are 812 handled according to the procedures defined in Section 6. 814 Example: 816 To delete a resource such as the "album" resource, the client might 817 send: 819 DELETE /restconf/data/example-jukebox:jukebox/ 820 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 821 Host: example.com 823 If the resource is deleted, the server might respond: 825 HTTP/1.1 204 No Content 826 Date: Mon, 23 Apr 2012 17:49:40 GMT 827 Server: example-server 829 2.8. Query Parameters 831 Each RESTCONF operation allows zero or more query parameters to be 832 present in the request URI. The specific parameters that are allowed 833 depends on the resource type, and sometimes the specific target 834 resource used, in the request. 836 +------------+----------+-------------------------------------------+ 837 | Name | Methods | Description | 838 +------------+----------+-------------------------------------------+ 839 | content | GET | Select config and/or non-config data | 840 | | | resources | 841 | depth | GET | Request limited sub-tree depth in the | 842 | | | reply content | 843 | filter | GET | Boolean notification filter for | 844 | | | event-stream resources | 845 | insert | POST, | Insertion mode for user-ordered data | 846 | | PUT | resources | 847 | point | POST, | Insertion point for user-ordered data | 848 | | PUT | resources | 849 | select | GET | Request a subset of the target resource | 850 | | | contents | 851 | start-time | GET | Replay buffer start time for event-stream | 852 | | | resources | 853 | stop-time | GET | Replay buffer stop time for event-stream | 854 | | | resources | 855 +------------+----------+-------------------------------------------+ 857 RESTCONF Query Parameters 859 Query parameters can be given in any order. Each parameter can 860 appear at most once in a request URI. A default value may apply if 861 the parameter is missing. 863 The semantics and syntax for all query parameters are defined in the 864 "query-parameters" YANG grouping in Section 7. The YANG encoding 865 MUST be converted to URL-encoded string for use in the request URI. 867 Refer to Appendix D.3 for examples of query parameter usage. 869 3. Messages 871 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 872 message corresponds to a single protocol method. Most messages can 873 perform a single task on a single resource, such as retrieving a 874 resource or editing a resource. The exception is the PATCH method, 875 which allows multiple datastore edits within a single message. 877 3.1. Request URI Structure 879 Resources are represented with URIs following the structure for 880 generic URIs in [RFC3986]. 882 A RESTCONF operation is derived from the HTTP method and the request 883 URI, using the following conceptual fields: 885 //?# 887 ^ ^ ^ ^ ^ 888 | | | | | 889 method entry resource query fragment 891 M M O O I 893 M=mandatory, O=optional, I=ignored 895 replaced by client with real values 897 o method: the HTTP method identifying the RESTCONF operation 898 requested by the client, to act upon the target resource specified 899 in the request URI. RESTCONF operation details are described in 900 Section 2. 902 o entry: the root of the RESTCONF API configured on this HTTP 903 server, discovered by getting the ".well-known/host-meta" 904 resource, as described in Section 3.2. All of the examples in 905 this document assume "/restconf" as the discovered RESTCONF API 906 root path. The URI template [RFC6570] syntax "{+restconf}" is 907 used to refer to the entry point outside of an example. 909 o resource: the path expression identifying the resource that is 910 being accessed by the operation. If this field is not present, 911 then the target resource is the API itself, represented by the 912 media type "application/yang.api". 914 o query: the set of parameters associated with the RESTCONF message. 915 These have the familiar form of "name=value" pairs. There is a 916 specific set of parameters defined, although the server MAY choose 917 to support additional parameters not defined in this document. 918 The contents of the any query parameter value MUST be encoded 919 according to [RFC2396], section 3.4. Any reserved characters MUST 920 be encoded with escape sequences, according to [RFC2396], section 921 2.4. 923 o fragment: This field is not used by the RESTCONF protocol. 925 When new resources are created by the client, a "Location" header is 926 returned, which identifies the path of the newly created resource. 927 The client MUST use this exact path identifier to access the resource 928 once it has been created. 930 The "target" of an operation is a resource. The "path" field in the 931 request URI represents the target resource for the operation. 933 3.2. RESTCONF Path Resolution 935 In line the best practices defined by [get-off-my-lawn], RESTCONF 936 enables deployments to specify where the RESTCONF API is located. 937 When first connecting to a RESTCONF server, a RESTCONF client MUST 938 determine the root of the RESTCONF API. The client discovers this by 939 getting the "/.well-known/host-meta" resource ([RFC6415]) and using 940 the element containing the "restconf" attribute : 942 Request 943 ------- 944 GET /.well-known/host-meta users HTTP/1.1 945 Host: example.com 946 Accept: application/xrd+xml 948 Response 949 -------- 950 HTTP/1.1 200 OK 951 Content-Type: application/xrd+xml 952 Content-Length: nnn 954 955 956 958 Once discovering the RESTCONF API root, the client MUST prepend it to 959 any subsequent request to a RESTCONF resource. For instance, using 960 the "/restconf" path discovered above, the client can now determine 961 the operations supported by the the server: 963 Request 964 ------- 965 GET /restconf/operations HTTP/1.1 966 Host: example.com 967 Accept: application/yang.api+json, 968 application/yang.errors+json 970 Response 971 -------- 972 HTTP/1.1 200 OK 973 Date: Mon, 23 Apr 2012 17:01:00 GMT 974 Server: example-server 975 Cache-Control: no-cache 976 Pragma: no-cache 977 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 978 Content-Type: application/yang.api+json 980 { "operations" : { "play" : [ null ] } } 982 3.3. Message Headers 984 There are several HTTP header lines utilized in RESTCONF messages. 985 Messages are not limited to the HTTP headers listed in this section. 987 HTTP defines which header lines are required for particular 988 circumstances. Refer to each operation definition section in 989 Section 2 for examples on how particular headers are used. 991 There are some request headers that are used within RESTCONF, usually 992 applied to data resources. The following tables summarize the 993 headers most relevant in RESTCONF message requests: 995 +---------------------+---------------------------------------------+ 996 | Name | Description | 997 +---------------------+---------------------------------------------+ 998 | Accept | Response Content-Types that are acceptable | 999 | Content-Type | The media type of the request body | 1000 | Host | The host address of the server | 1001 | If-Match | Only perform the action if the entity | 1002 | | matches ETag | 1003 | If-Modified-Since | Only perform the action if modified since | 1004 | | time | 1005 | If-Unmodified-Since | Only perform the action if un-modified | 1006 | | since time | 1007 +---------------------+---------------------------------------------+ 1008 RESTCONF Request Headers 1010 The following tables summarize the headers most relevant in RESTCONF 1011 message responses: 1013 +---------------+---------------------------------------------------+ 1014 | Name | Description | 1015 +---------------+---------------------------------------------------+ 1016 | Allow | Valid actions when 405 error returned | 1017 | Cache-Control | The cache control parameters for the response | 1018 | Content-Type | The media type of the response body | 1019 | Date | The date and time the message was sent | 1020 | ETag | An identifier for a specific version of a | 1021 | | resource | 1022 | Last-Modified | The last modified date and time of a resource | 1023 | Location | The resource identifier for a newly created | 1024 | | resource | 1025 +---------------+---------------------------------------------------+ 1027 RESTCONF Response Headers 1029 3.4. Message Encoding 1031 RESTCONF messages are encoded in HTTP according to RFC 2616. The 1032 "utf-8" character set is used for all messages. RESTCONF message 1033 content is sent in the HTTP message body. 1035 Content is encoded in either JSON or XML format. 1037 XML encoding rules for data nodes are defined in [RFC6020]. The same 1038 encoding rules are used for all XML content. 1040 JSON encoding rules are defined in [I-D.lhotka-netmod-json]. This 1041 encoding is valid JSON, but also has special encoding rules to 1042 identify module namespaces and provide consistent type processing of 1043 YANG data. 1045 Request input content encoding format is identified with the Content- 1046 Type header. This field MUST be present if a message body is sent by 1047 the client. 1049 Response output content encoding format is identified with the Accept 1050 header in the request, or if is not specified, the request input 1051 encoding format is used. If there was no request input, then the 1052 default output encoding is XML. File extensions encoded in the 1053 request are not used to identify format encoding. 1055 3.5. RESTCONF Meta-Data 1057 The RESTCONF protocol needs to retrieve the same meta-data that is 1058 used in the NETCONF protocol. Information about default leafs, last- 1059 modified timestamps, etc. are commonly used to annotate 1060 representations of the datastore contents. This meta-data is not 1061 defined in the YANG schema because it applies to the datastore, and 1062 is common across all data nodes. 1064 This information is encoded as attributes in XML. JSON encoding of 1065 meta-data is defined in [I-D.lhotka-netmod-json]. 1067 3.6. Return Status 1069 Each message represents some sort of resource access. An HTTP 1070 "Status-Line" header line is returned for each request. If a 4xx or 1071 5xx range status code is returned in the Status-Line, then the error 1072 information will be returned in the response, according to the format 1073 defined in Section 6.1. 1075 3.7. Message Caching 1077 Since the datastore contents change at unpredictable times, responses 1078 from a RESTCONF server generally SHOULD NOT be cached. 1080 The server SHOULD include a "Cache-Control" header in every response 1081 that specifies whether the response should be cached. A "Pragma" 1082 header specifying "no-cache" MAY also be sent in case the 1083 "Cache-Control" header is not supported. 1085 Instead of using HTTP caching, the client SHOULD track the "ETag" 1086 and/or "Last-Modified" headers returned by the server for the 1087 datastore resource (or data resource if the server supports it). A 1088 retrieval request for a resource can include the "If-None-Match" 1089 and/or "If-Modified-Since" headers, which will cause the server to 1090 return a "304 Not Modified" Status-Line if the resource has not 1091 changed. The client MAY use the HEAD method to retrieve just the 1092 message headers, which SHOULD include the "ETag" and "Last-Modified" 1093 headers, if this meta-data is maintained for the target resource. 1095 4. Resources 1097 The RESTCONF protocol operates on a hierarchy of resources, starting 1098 with the top-level API resource itself. Each resource represents a 1099 manageable component within the device. 1101 A resource can be considered a collection of conceptual data and the 1102 set of allowed methods on that data. It can contain nested child 1103 resources. The child resource types and methods allowed on them are 1104 data-model specific. 1106 A resource has its own media type identifier, represented by the 1107 "Content-Type" header in the HTTP response message. A resource can 1108 contain zero or more nested resources. A resource can be created and 1109 deleted independently of its parent resource, as long as the parent 1110 resource exists. 1112 All RESTCONF resources are defined in this document except datastore 1113 contents, protocol operations, and notification events. The syntax 1114 and semantics for these resource types are defined in YANG modules. 1116 The RESTCONF resources are accessed via a set of URIs defined in this 1117 document. The set of YANG modules supported by the server will 1118 determine the data model specific operations, top-level data node 1119 resources, and notification event messages supported by the server. 1121 The resources used in the RESTCONF protocol are identified by the 1122 "path" component in the request URI. Each operation is performed on 1123 a target resource. 1125 4.1. RESTCONF Resource Types 1127 The RESTCONF protocol defines a set of application specific media 1128 types to identify each of the available resource types. The 1129 following resource types are defined in RESTCONF: 1131 +-----------+----------------------------+ 1132 | Resource | Media Type | 1133 +-----------+----------------------------+ 1134 | API | application/yang.api | 1135 | Datastore | application/yang.datastore | 1136 | Data | application/yang.data | 1137 | Errors | application/yang.errors | 1138 | Operation | application/yang.operation | 1139 | Schema | application/yang | 1140 | Stream | application/yang.stream | 1141 +-----------+----------------------------+ 1142 RESTCONF Media Types 1144 4.2. Resource Discovery 1146 A client SHOULD start by retrieving the top-level API resource, using 1147 the entry point URI defined in Section 3.2. 1149 The RESTCONF protocol does not include a resource discovery 1150 mechanism. Instead, the definitions within the YANG modules 1151 advertised by the server are used to construct a predictable 1152 operation or data resource identifier. 1154 The "depth" query parameter can be used to control how many 1155 descendant levels should be included when retrieving child resources. 1156 This parameter can be used with the GET method to discover child 1157 resources within a particular resource. 1159 4.3. API Resource 1161 The API resource contains the state and access points for the 1162 RESTCONF features. It is the top-level resource and has the media 1163 type "application/yang.api+xml" or "application/yang.api+json". 1165 YANG Tree Diagram for "application/yang.api" Resource Type: 1167 +--rw restconf 1168 +--rw data 1169 +--rw modules 1170 | +--rw module* [name revision] 1171 | +--rw name yang:yang-identifier 1172 | +--rw revision union 1173 | +--rw schema? empty 1174 | +--rw namespace inet:uri 1175 | +--rw feature* yang:yang-identifier 1176 | +--rw deviation* yang:yang-identifier 1177 | +--rw submodule* [name revision] 1178 | +--rw name yang:yang-identifier 1179 | +--rw revision union 1180 | +--rw schema? empty 1181 +--rw operations 1182 +--rw streams 1183 +--rw stream* [name] 1184 +--rw name string 1185 +--rw description? string 1186 +--rw replay-support? boolean 1187 +--rw replay-log-creation-time? yang:date-and-time 1188 +--rw events? empty 1190 The "restconf" container definition in the "ietf-restconf" module 1191 defined in Section 7 is used to specify the structure and syntax of 1192 the conceptual child resources within the API resource. 1194 This resource has the following child resources: 1196 +----------------+--------------------------------+ 1197 | Child Resource | Description | 1198 +----------------+--------------------------------+ 1199 | data | Contains all data resources | 1200 | modules | YANG module information | 1201 | operations | Data-model specific operations | 1202 | streams | Notification event streams | 1203 +----------------+--------------------------------+ 1205 RESTCONF Resources 1207 4.3.1. {+restconf}/data 1209 This mandatory resource represents the combined configuration and 1210 operational data resources that can be accessed by a client. It 1211 cannot be created or deleted by the client. The datastore resource 1212 type is defined in Section 4.4. 1214 Example: 1216 This example request by the client would retrieve only the non- 1217 configuration data nodes that exist within the "library" resource, 1218 using the "content" query parameter. 1220 GET /restconf/data/example-jukebox:jukebox/library 1221 ?content=nonconfig HTTP/1.1 1222 Host: example.com 1223 Accept: application/yang.data+json, 1224 application/yang.errors+json 1226 The server might respond: 1228 HTTP/1.1 200 OK 1229 Date: Mon, 23 Apr 2012 17:01:30 GMT 1230 Server: example-server 1231 Cache-Control: no-cache 1232 Pragma: no-cache 1233 Content-Type: application/yang.data+json 1235 { 1236 "example-jukebox:library" : { 1237 "artist-count" : 42, 1238 "album-count" : 59, 1239 "song-count" : 374 1240 } 1241 } 1243 4.3.2. {+restconf}/modules 1245 This mandatory resource contains the identifiers for the YANG data 1246 model modules supported by the server. 1248 The server MUST maintain a last-modified timestamp for this resource, 1249 and return the "Last-Modified" header when this resource is retrieved 1250 with the GET or HEAD methods. 1252 The server SHOULD maintain an entity-tag for this resource, and 1253 return the "ETag" header when this resource is retrieved with the GET 1254 or HEAD methods. 1256 4.3.2.1. {+restconf}/modules/module 1258 This mandatory resource contains one list entry for each YANG data 1259 model module supported by the server. There MUST be an instance of 1260 this resource for every YANG module that is accessible via an 1261 operation resource or a data resource. 1263 The contents of the "module" resource are defined in the "module" 1264 YANG list statement in Section 7. 1266 The server MAY maintain a last-modified timestamp for each instance 1267 of this resource, and return the "Last-Modified" header when this 1268 resource is retrieved with the GET or HEAD methods. If not supported 1269 then the timestamp for the parent "modules" resource MAY be used 1270 instead. 1272 The server MAY maintain an entity-tag for each instance of this 1273 resource, and return the "ETag" header when this resource is 1274 retrieved with the GET or HEAD methods. If not supported then the 1275 timestamp for the parent "modules" resource MAY be used instead. 1277 4.3.3. {+restconf}/operations 1279 This optional resource is a container that provides access to the 1280 data-model specific protocol operations supported by the server. The 1281 server MAY omit this resource if no data-model specific operations 1282 are advertised. 1284 Any data-model specific operations defined in the YANG modules 1285 advertised by the server MAY be available as child nodes of this 1286 resource. 1288 Operation resources are defined in Section 4.6. 1290 4.3.4. {+restconf}/streams 1292 This optional resource is a container that provides access to the 1293 notification event streams supported by the server. The server MAY 1294 omit this resource if no notification event streams are supported. 1295 The media type for this resource is "application/yang.api". 1297 The server will populate this container with a stream list entry for 1298 each stream type it supports. Each stream contains a leaf called 1299 "events" which represents an event stream resource. The media type 1300 for this resource is "application/yang.stream". 1302 Stream resources are defined in Section 4.8. Notifications are 1303 defined in Section 5. 1305 4.4. Datastore Resource 1307 The "{+restconf}/data" subtree represents the datastore resource 1308 type, which is a collection of configuration and operational data 1309 nodes. 1311 A "unified datastore" interface is used to simplify resource editing 1312 for the client. The RESTCONF unified datastore is a conceptual 1313 interface to the native configuration datastores that are present on 1314 the device. 1316 The underlying NETCONF datastores (i.e., candidate, running, startup) 1317 can be used to implement the unified datastore, but the server design 1318 is not limited to the exact datastore procedures defined in NETCONF. 1320 The "candidate" and "startup" datastores are not visible in the 1321 RESTCONF protocol. Transaction management and configuration 1322 persistence are handled by the server and not controlled by the 1323 client. 1325 A datastore resource can only be written directly with the PATCH 1326 method. Only the configuration data resources within the datastore 1327 resource can be edited directly with all methods. 1329 Each RESTCONF edit of a datastore resource is saved to non-volatile 1330 storage in an implementation-specific matter by the server. There is 1331 no guarantee that configuration changes are saved immediately, or 1332 that the saved configuration is always a mirror of the running 1333 configuration. 1335 4.4.1. Edit Collision Detection 1337 Two "edit collision detection" mechanisms are provided in RESTCONF, 1338 for datastore and data resources. 1340 4.4.1.1. Timestamp 1342 The last change time is maintained and the "Last-Modified" and "Date" 1343 headers are returned in the response for a retrieval request. The 1344 "If-Unmodified-Since" header can be used in edit operation requests 1345 to cause the server to reject the request if the resource has been 1346 modified since the specified timestamp. 1348 The server MUST maintain a last-modified timestamp for this resource, 1349 and return the "Last-Modified" header when this resource is retrieved 1350 with the GET or HEAD methods. Only changes to configuration data 1351 resources within the datastore affect this timestamp. 1353 4.4.1.2. Entity tag 1355 A unique opaque string is maintained and the "ETag" header is 1356 returned in the response for a retrieval request. The "If-Match" 1357 header can be used in edit operation requests to cause the server to 1358 reject the request if the resource entity tag does not match the 1359 specified value. 1361 The server MUST maintain a resource entity tag for this resource, and 1362 return the "ETag" header when this resource is retrieved with the GET 1363 or HEAD methods. The resource entity tag MUST be changed to a new 1364 previously unused value if changes to any configuration data 1365 resources within the datastore are made. 1367 4.5. Data Resource 1369 A data resource represents a YANG data node that is a descendant node 1370 of a datastore resource. 1372 For configuration data resources, the server MAY maintain a last- 1373 modified timestamp for the resource, and return the "Last-Modified" 1374 header when it is retrieved with the GET or HEAD methods. If 1375 maintained, the resource timestamp MUST be set to the current time 1376 whenever the resource or any configuration resource within the 1377 resource is altered. 1379 For configuration data resources, the server MAY maintain a resource 1380 entity tag for the resource, and return the "ETag" header when it is 1381 retrieved as the target resource with the GET or HEAD methods. If 1382 maintained, the resource entity tag MUST be updated whenever the 1383 resource or any configuration resource within the resource is 1384 altered. 1386 A data resource can be retrieved with the GET method. Data resources 1387 are accessed via the "{+restconf}/data" entry point. This sub-tree 1388 is used to retrieve and edit data resources. 1390 A configuration data resource can be altered by the client with some 1391 or all of the edit operations, depending on the target resource and 1392 the specific operation. Refer to Section 2 for more details on edit 1393 operations. 1395 The resource definition version for a data resource is identified by 1396 the revision date of the YANG module containing the YANG definition 1397 for the data resource, specified in the "{+restconf}/modules" sub- 1398 tree. 1400 4.5.1. Encoding YANG Instance Identifiers in the Request URI 1402 In YANG, data nodes are named with an absolute XPath expression, 1403 defined in [XPath] , starting from the document root to the target 1404 resource. In RESTCONF, URL encoded Location header expressions are 1405 used instead. 1407 The YANG "instance-identifier" (i-i) data type is represented in 1408 RESTCONF with the path expression format defined in this section. 1410 +-------+-------------------------------------------+ 1411 | Name | Comments | 1412 +-------+-------------------------------------------+ 1413 | point | Insertion point is always a full i-i | 1414 | path | Request URI path is a full or partial i-i | 1415 +-------+-------------------------------------------+ 1417 RESTCONF instance-identifier Type Conversion 1419 The "path" component of the request URI contains the absolute path 1420 expression that identifies the target resource. 1422 A predictable location for a data resource is important, since 1423 applications will code to the YANG data model module, which uses 1424 static naming and defines an absolute path location for all data 1425 nodes. 1427 A RESTCONF data resource identifier is not an XPath expression. It 1428 is encoded from left to right, starting with the top-level data node, 1429 according to the "api-path" rule in Section 4.5.1.1. The node name 1430 of each ancestor of the target resource node is encoded in order, 1431 ending with the node name for the target resource. 1433 If a data node in the path expression is a YANG list node, then the 1434 key values for the list (if any) MUST be encoded according to the 1435 following rules. 1437 o The key leaf values for a data resource representing a YANG list 1438 MUST be encoded using one path segment [RFC3986]. 1440 o If there is only one key leaf value, the path segment is 1441 constructed by having the list name followed by an "=" followed by 1442 the single key leaf value. 1444 o If there are multiple key leaf values, the value of each leaf 1445 identified in the "key" statement is encoded in the order 1446 specified in the YANG "key" statement, with a comma separating 1447 them. 1449 o All the components in the "key" statement MUST be encoded. 1450 Partial instance identifiers are not supported. 1452 o Quoted strings are supported in the key leaf values. Quoted 1453 strings MUST be used to express empty strings. (example: 1454 list=foo,'',baz). 1456 o The "list-instance" ABNF rule defined in Section 4.5.1.1 1457 represents the syntax of a list instance identifier. 1459 o Resource URI values returned in Location headers for data 1460 resources MUST identify the module name, even if there are no 1461 conflicting local names when the resource is created. This 1462 ensures the correct resource will be identified even if the server 1463 loads a new module that the old client does not know about. 1465 Examples: 1467 container top { 1468 list list1 { 1469 key "key1 key2 key3"; 1470 ... 1471 list list2 { 1472 key "key4 key5"; 1473 ... 1474 leaf X { type string; } 1475 } 1476 } 1478 For the above YANG definition, URI with key leaf values will be 1479 encoded as follows (line wrapped for display purposes only): 1481 /restconf/data/top/list1=key1val,key2val,key3val3/ 1482 list2=key4val,key5val/X 1484 4.5.1.1. ABNF For Data Resource Identifiers 1486 The "api-path" ABNF syntax is used to construct RESTCONF path 1487 identifiers: 1489 api-path = "/" | 1490 ("/" api-identifier 1491 0*("/" (api-identifier | list-instance ))) 1493 api-identifier = [module-name ":"] identifier 1495 module-name = identifier 1497 list-instance = api-identifier "=" key-value ["," key-value]* 1499 key-value = string 1501 string = 1503 ;; An identifier MUST NOT start with 1504 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 1505 identifier = (ALPHA / "_") 1506 *(ALPHA / DIGIT / "_" / "-" / ".") 1508 4.5.2. Defaults Handling 1510 NETCONF has a rather complex model for handling default values for 1511 leafs. RESTCONF attempts to avoid this complexity by restricting the 1512 operations that can be applied to a resource. Applications that 1513 require full control of defaults might consider NETCONF instead of 1514 RESTCONF. 1516 If the target of a GET method is a data node that represents a leaf 1517 that has a default value, and the leaf has not been given a value 1518 yet, the server MUST return the default value that is in use by the 1519 server. 1521 If the target of a GET method is a data node that represents a 1522 container or list that has any child resources with default values, 1523 for the child resources that have not been given value yet, the 1524 server MAY return the default values that are in use by the server. 1526 4.6. Operation Resource 1528 An operation resource represents an protocol operation defined with 1529 the YANG "rpc" statement. 1531 All operation resources share the same module namespace as any top- 1532 level data resources, so the name of an operation resource cannot 1533 conflict with the name of a top-level data resource defined within 1534 the same module. 1536 If 2 different YANG modules define the same "rpc" identifier, then 1537 the module name MUST be used in the request URI. For example, if 1538 "module-A" and "module-B" both defined a "reset" operation, then 1539 invoking the operation from "module-A" would be requested as follows: 1541 POST /restconf/operations/module-A:reset HTTP/1.1 1542 Server example.com 1544 Any usage of an operation resource from the same module, with the 1545 same name, refers to the same "rpc" statement definition. This 1546 behavior can be used to design protocol operations that perform the 1547 same general function on different resource types. 1549 If the "rpc" statement has an "input" section, then a message body 1550 MAY be sent by the client in the request, otherwise the request 1551 message MUST NOT include a message body. If the "rpc" statement has 1552 an "output" section, then a message body MAY be sent by the server in 1553 the response. Otherwise the server MUST NOT include a message body 1554 in the response message, and MUST send a "204 No Content" Status-Line 1555 instead. 1557 4.6.1. Encoding Operation Input Parameters 1559 If the "rpc" statement has an "input" section, then the "input" node 1560 is provided in the message body, corresponding to the YANG data 1561 definition statements within the "input" section. 1563 Example: 1565 The following YANG definition is used for the examples in this 1566 section. 1568 rpc reboot { 1569 input { 1570 leaf delay { 1571 units seconds; 1572 type uint32; 1573 default 0; 1574 } 1575 leaf message { type string; } 1576 leaf language { type string; } 1577 } 1578 } 1580 The client might send the following POST request message: 1582 POST /restconf/operations/example-ops:reboot HTTP/1.1 1583 Host: example.com 1584 Content-Type: application/yang.operation+json 1586 { 1587 "example-ops:input" : { 1588 "delay" : 600, 1589 "message" : "Going down for system maintenance", 1590 "language" : "en-US" 1591 } 1592 } 1594 The server might respond: 1596 HTTP/1.1 204 No Content 1597 Date: Mon, 25 Apr 2012 11:01:00 GMT 1598 Server: example-server 1600 4.6.2. Encoding Operation Output Parameters 1602 If the "rpc" statement has an "output" section, then the "output" 1603 node is provided in the message body, corresponding to the YANG data 1604 definition statements within the "output" section. 1606 Example: 1608 The following YANG definition is used for the examples in this 1609 section. 1611 rpc get-reboot-info { 1612 output { 1613 leaf reboot-time { 1614 units seconds; 1615 type uint32; 1616 } 1617 leaf message { type string; } 1618 leaf language { type string; } 1619 } 1620 } 1622 The client might send the following POST request message: 1624 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 1625 Host: example.com 1626 Accept: application/yang.operation+json, 1627 application/yang.errors+json 1629 The server might respond: 1631 HTTP/1.1 200 OK 1632 Date: Mon, 25 Apr 2012 11:10:30 GMT 1633 Server: example-server 1634 Content-Type: application/yang.operation+json 1636 { 1637 "example-ops:output" : { 1638 "reboot-time" : 30, 1639 "message" : "Going down for system maintenance", 1640 "language" : "en-US" 1641 } 1642 } 1644 4.7. Schema Resource 1646 If the server supports the "schema" leaf within the API then the 1647 client can retrieve the YANG schema text for the associated YANG 1648 module or submodule, using the GET method. 1650 The client might send the following GET request message: 1652 GET /restconf/modules/module=example-jukebox,2014-07-03/schema 1653 HTTP/1.1 1654 Host: example.com 1655 Accept: application/yang, 1656 application/yang.errors+json 1658 The server might respond: 1660 HTTP/1.1 200 OK 1661 Date: Mon, 25 Apr 2012 11:10:30 GMT 1662 Server: example-server 1663 Content-Type: application/yang 1665 module example-jukebox { 1667 namespace "http://example.com/ns/example-jukebox"; 1668 prefix "jbox"; 1670 // rest of YANG module content deleted... 1671 } 1673 4.8. Stream Resource 1675 A "stream" resource represents a source for system generated event 1676 notifications. Each stream is created and modified by the server 1677 only. A client can retrieve a stream resource or initiate a long- 1678 poll server sent event stream, using the procedure specified in 1679 Section 5.3. 1681 A notification stream functions according to the NETCONF 1682 Notifications specification [RFC5277]. The "ietf-restconf" YANG 1683 module contains the "stream" list ("{+restconf}/streams/stream") 1684 which specifies the syntax and semantics of a stream resource. 1686 4.9. Errors Resource 1688 An "errors" resource is a collection of error information that is 1689 sent as the message body in a server response message, if an error 1690 occurs while processing a request message. 1692 The "ietf-restconf" YANG module contains the "errors" grouping which 1693 specifies the syntax and semantics of an errors resource. RESTCONF 1694 error handling behavior is defined in Section 6. 1696 5. Notifications 1698 The RESTCONF protocol supports YANG-defined event notifications. The 1699 solution preserves aspects of NETCONF Event Notifications [RFC5277] 1700 while utilizing the Server-Sent Events [wd-eventsource] transport 1701 strategy. 1703 5.1. Server Support 1705 A RESTCONF server is not required to support RESTCONF notifications. 1706 Clients may determine if a server supports RESTCONF notifications by 1707 using the HTTP operation OPTIONS, HEAD, or GET on the "{+restconf}/ 1708 streams" resource described below. The server does not support 1709 RESTCONF notifications if an HTTP error code is returned (e.g., 404 1710 Not Found). 1712 5.2. Event Streams 1714 A RESTCONF server that supports notifications will populate a stream 1715 resource for each notification delivery service access point. A 1716 RESTCONF client can retrieve the list of supported event streams from 1717 a RESTCONF server using the GET operation on the "{+restconf}/ 1718 streams" resource. 1720 The "{+restconf}/streams" container definition in the "ietf-restconf" 1721 module defined in Section 7 is used to specify the structure and 1722 syntax of the conceptual child resources within the "streams" 1723 resource. 1725 For example: 1727 The client might send the following request: 1729 GET /restconf/streams HTTP/1.1 1730 Host: example.com 1731 Accept: application/yang.api+xml, 1732 application/yang.errors+xml 1734 The server might send the following response: 1736 HTTP/1.1 200 OK 1737 Content-Type: application/yang.api+xml 1738 1739 1740 NETCONF 1741 default NETCONF event stream 1742 1743 true 1744 1745 2007-07-08T00:00:00Z 1746 1747 1748 1749 1750 SNMP 1751 SNMP notifications 1752 false 1753 1754 1755 1756 syslog-critical 1757 Critical and higher severity 1758 1759 true 1760 1761 2007-07-01T00:00:00Z 1762 1763 1764 1765 1767 5.3. Subscribing to Receive Notifications 1769 RESTCONF clients can subscribe to receive notifications by sending an 1770 HTTP GET request for the "{+restconf}/streams/stream/" 1771 resource, with the "Accept" type "text/event-stream". The server 1772 will treat the connection as an event stream, using the Server Sent 1773 Events [wd-eventsource] transport strategy. 1775 The server MAY support query parameters for a GET method on this 1776 resource. These parameters are specific to each notification stream. 1778 For example: 1780 GET /restconf/streams/stream=NETCONF/events HTTP/1.1 1781 Host: example.com 1782 Accept: text/event-stream 1783 Cache-Control: no-cache 1784 Connection: keep-alive 1786 A RESTCONF client MAY request the server compress the events using 1787 the HTTP header field "Accept-Encoding". For instance: 1789 GET /restconf/streams/stream=NETCONF/events HTTP/1.1 1790 Host: example.com 1791 Accept: text/event-stream 1792 Cache-Control: no-cache 1793 Connection: keep-alive 1794 Accept-Encoding: gzip, deflate 1796 5.3.1. NETCONF Event Stream 1798 The server SHOULD support the "NETCONF" notification stream defined 1799 in [RFC5277]. For this stream, RESTCONF notification subscription 1800 requests MAY specify parameters indicating the events it wishes to 1801 receive. 1803 +------------+-------------------------+ 1804 | Name | Description | 1805 +------------+-------------------------+ 1806 | start-time | replay event start time | 1807 | stop-time | replay event stop time | 1808 | filter | boolean content filter | 1809 +------------+-------------------------+ 1811 NETCONF Stream Query Parameters 1813 The semantics and syntax for these query parameters are defined in 1814 the "query-parameters" YANG grouping in Section 7. The YANG encoding 1815 MUST be converted to URL-encoded string for use in the request URI. 1817 Refer to Appendix D.3.3 for filter parameter examples. 1819 5.4. Receiving Event Notifications 1821 RESTCONF notifications are encoded according to the definition of the 1822 event stream. The NETCONF stream defined in [RFC5277] is encoded in 1823 XML format. 1825 The structure of the event data is based on the "notification" 1826 element definition in section 4 of [RFC5277]. It MUST conform to the 1827 "notification" YANG container definition in Section 7. 1829 An example SSE notification encoded using XML: 1831 data: 1833 data: 2013-12-21T00:01:00Z 1834 data: 1835 data: fault 1836 data: 1837 data: Ethernet0 1838 data: 1839 data: major 1840 data: 1841 data: 1843 Since XML is not whitespace sensitive, the above message can be 1844 encoded onto a single line. 1846 For example: ('\' line wrapping added for formatting only) 1848 data: 2013-12-21T00:01:00ZfaultEthernet0maj\ 1852 or 1854 The SSE specifications supports the following additional fields: 1855 event, id and retry. A RESTCONF server MAY send the "retry" field 1856 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 1857 SHOULD NOT send the "event" or "id" fields, as there are no 1858 meaningful values that could be used for them that would not be 1859 redundant to the contents of the notification itself. RESTCONF 1860 servers that do not send the "id" field also do not need to support 1861 the HTTP header "Last-Event-Id". RESTCONF servers that do send the 1862 "id" field MUST still support the "startTime" query parameter as the 1863 preferred means for a client to specify where to restart the event 1864 stream. 1866 6. Error Reporting 1868 HTTP Status-Lines are used to report success or failure for RESTCONF 1869 operations. The element returned in NETCONF error 1870 responses contains some useful information. This error information 1871 is adapted for use in RESTCONF, and error information is returned for 1872 "4xx" class of status codes. 1874 The following table summarizes the return status codes used 1875 specifically by RESTCONF operations: 1877 +---------------------------+---------------------------------------+ 1878 | Status-Line | Description | 1879 +---------------------------+---------------------------------------+ 1880 | 100 Continue | POST accepted, 201 should follow | 1881 | 200 OK | Success with response body | 1882 | 201 Created | POST to create a resource success | 1883 | 202 Accepted | POST to create a resource accepted | 1884 | 204 No Content | Success without response body | 1885 | 304 Not Modified | Conditional operation not done | 1886 | 400 Bad Request | Invalid request message | 1887 | 403 Forbidden | Access to resource denied | 1888 | 404 Not Found | Resource target or resource node not | 1889 | | found | 1890 | 405 Method Not Allowed | Method not allowed for target | 1891 | | resource | 1892 | 409 Conflict | Resource or lock in use | 1893 | 412 Precondition Failed | Conditional method is false | 1894 | 413 Request Entity Too | too-big error | 1895 | Large | | 1896 | 414 Request-URI Too Large | too-big error | 1897 | 415 Unsupported Media | non RESTCONF media type | 1898 | Type | | 1899 | 500 Internal Server Error | operation-failed | 1900 | 501 Not Implemented | unknown-operation | 1901 | 503 Service Unavailable | Recoverable server error | 1902 +---------------------------+---------------------------------------+ 1904 HTTP Status Codes used in RESTCONF 1906 Since an operation resource is defined with a YANG "rpc" statement, a 1907 mapping between the NETCONF value and the HTTP status 1908 code is needed. The specific error condition and response code to 1909 use are data-model specific and might be contained in the YANG 1910 "description" statement for the "rpc" statement. 1912 +-------------------------+-------------+ 1913 | | status code | 1914 +-------------------------+-------------+ 1915 | in-use | 409 | 1916 | invalid-value | 400 | 1917 | too-big | 413 | 1918 | missing-attribute | 400 | 1919 | bad-attribute | 400 | 1920 | unknown-attribute | 400 | 1921 | bad-element | 400 | 1922 | unknown-element | 400 | 1923 | unknown-namespace | 400 | 1924 | access-denied | 403 | 1925 | lock-denied | 409 | 1926 | resource-denied | 409 | 1927 | rollback-failed | 500 | 1928 | data-exists | 409 | 1929 | data-missing | 409 | 1930 | operation-not-supported | 501 | 1931 | operation-failed | 500 | 1932 | partial-operation | 500 | 1933 | malformed-message | 400 | 1934 +-------------------------+-------------+ 1936 Mapping from error-tag to status code 1938 6.1. Error Response Message 1940 When an error occurs for a request message on a data resource or an 1941 operation resource, and a "4xx" class of status codes (except for 1942 status code "403 Forbidden"), then the server SHOULD send a response 1943 body containing the information described by the "errors" container 1944 definition within the YANG module Section 7. The Content-Type of 1945 this response message MUST be application/yang.errors. 1947 YANG Tree Diagram for Data: 1949 +--ro errors 1950 +--ro error 1951 +--ro error-type enumeration 1952 +--ro error-tag string 1953 +--ro error-app-tag? string 1954 +--ro (error-node)? 1955 | +--:(error-path) 1956 | | +--ro error-path? instance-identifier 1957 | +--:(error-urlpath) 1958 | +--ro error-urlpath? data-resource-identifier 1959 +--ro error-message? string 1960 +--ro error-info 1962 The semantics and syntax for RESTCONF error messages are defined in 1963 the "errors" YANG grouping in Section 7. 1965 Examples: 1967 The following example shows an error returned for an "lock-denied" 1968 error on a datastore resource. 1970 POST /restconf/operations/example-ops:lock-datastore HTTP/1.1 1971 Host: example.com 1973 The server might respond: 1975 HTTP/1.1 409 Conflict 1976 Date: Mon, 23 Apr 2012 17:11:00 GMT 1977 Server: example-server 1978 Content-Type: application/yang.errors+json 1980 { 1981 "ietf-restconf:errors": { 1982 "error": { 1983 "error-type": "protocol", 1984 "error-tag": "lock-denied", 1985 "error-message": "Lock failed, lock already held" 1986 } 1987 } 1988 } 1990 The following example shows an error returned for a "data-exists" 1991 error on a data resource. The "jukebox" resource already exists so 1992 it cannot be created. 1994 The client might send: 1996 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 1997 Host: example.com 1999 The server might respond: 2001 HTTP/1.1 409 Conflict 2002 Date: Mon, 23 Apr 2012 17:11:00 GMT 2003 Server: example-server 2004 Content-Type: application/yang.errors+json 2006 { 2007 "ietf-restconf:errors": { 2008 "error": { 2009 "error-type": "protocol", 2010 "error-tag": "data-exists", 2011 "error-urlpath": "http://example.com/restconf/data/ 2012 example-jukebox:jukebox", 2013 "error-message": 2014 "Data already exists, cannot create new resource" 2015 } 2016 } 2017 } 2019 7. RESTCONF module 2021 The "ietf-restconf" module defines conceptual definitions within 2022 groupings, which are not meant to be implemented as datastore 2023 contents by a server. 2025 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 2026 are used by this module for some type definitions. 2028 RFC Ed.: update the date below with the date of RFC publication and 2029 remove this note. 2031 file "ietf-restconf@2014-07-03.yang" 2033 module ietf-restconf { 2034 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 2035 prefix "rc"; 2037 import ietf-yang-types { prefix yang; } 2038 import ietf-inet-types { prefix inet; } 2040 organization 2041 "IETF NETCONF (Network Configuration) Working Group"; 2043 contact 2044 "WG Web: 2045 WG List: 2047 WG Chair: Bert Wijnen 2048 2050 WG Chair: Mehmet Ersue 2051 2053 Editor: Andy Bierman 2054 2056 Editor: Martin Bjorklund 2057 2059 Editor: Kent Watsen 2060 2062 Editor: Rex Fernando 2063 "; 2065 description 2066 "This module contains conceptual YANG specifications 2067 for the message and error content that is used in 2068 RESTCONF protocol messages. A conceptual container 2069 representing the RESTCONF API nodes is also defined 2070 for the media type application/yang.api. 2072 Note that the YANG definitions within this module do not 2073 represent configuration data of any kind. 2074 The YANG grouping statements provide a normative syntax 2075 for XML and JSON message encoding purposes. 2077 Copyright (c) 2014 IETF Trust and the persons identified as 2078 authors of the code. All rights reserved. 2080 Redistribution and use in source and binary forms, with or 2081 without modification, is permitted pursuant to, and subject 2082 to the license terms contained in, the Simplified BSD License 2083 set forth in Section 4.c of the IETF Trust's Legal Provisions 2084 Relating to IETF Documents 2085 (http://trustee.ietf.org/license-info). 2087 This version of this YANG module is part of RFC XXXX; see 2088 the RFC itself for full legal notices."; 2090 // RFC Ed.: replace XXXX with actual RFC number and remove this 2091 // note. 2093 // RFC Ed.: remove this note 2094 // Note: extracted from draft-ietf-netconf-restconf-01.txt 2096 // RFC Ed.: update the date below with the date of RFC publication 2097 // and remove this note. 2098 revision 2014-07-03 { 2099 description 2100 "Initial revision."; 2101 reference 2102 "RFC XXXX: RESTCONF Protocol."; 2103 } 2105 typedef data-resource-identifier { 2106 type string { 2107 length "1 .. max"; 2108 } 2109 description 2110 "Contains a Data Resource Identifier formatted string 2111 to identify a specific data resource instance. 2112 The document root for all data resources is a 2113 datastore resource container. Each top-level YANG 2114 data nodes supported by the server will be represented 2115 as a child node of the document root. 2117 The canonical representation of a data resource identifier 2118 includes the full server specification that is returned 2119 in the Location header when a new data resource is created 2120 with the POST method. 2122 The abbreviated representation does not contain any server 2123 location identification. Instead the identifier will start 2124 with the '/' character to represent the datastore document 2125 root for the data resource instance. 2127 The server MUST accept either representation and SHOULD 2128 return the canonical representation in any response message."; 2129 reference 2130 "RFC XXXX: [sec. 5.3.1.1 ABNF For Data Resource Identifiers]"; 2131 } 2133 typedef revision-identifier { 2134 type string { 2135 pattern '\d{4}-\d{2}-\d{2}'; 2136 } 2137 description 2138 "Represents a specific date in YYYY-MM-DD format. 2139 TBD: make pattern more precise to exclude leading zeros."; 2140 } 2142 grouping errors { 2144 description 2145 "A grouping that contains a YANG container 2146 representing the syntax and semantics of a 2147 YANG Patch errors report within a response message."; 2149 container errors { 2150 description 2151 "Represents an error report returned by the server if 2152 a request results in an error."; 2154 list error { 2155 description 2156 "An entry containing information about one 2157 specific error that occurred while processing 2158 a RESTCONF request."; 2159 reference "RFC 6241, Section 4.3"; 2161 leaf error-type { 2162 type enumeration { 2163 enum transport { 2164 description "The transport layer"; 2165 } 2166 enum rpc { 2167 description "The rpc or notification layer"; 2168 } 2169 enum protocol { 2170 description "The protocol operation layer"; 2171 } 2172 enum application { 2173 description "The server application layer"; 2174 } 2175 } 2176 mandatory true; 2177 description 2178 "The protocol layer where the error occurred."; 2179 } 2181 leaf error-tag { 2182 type string; 2183 mandatory true; 2184 description 2185 "The enumerated error tag."; 2186 } 2188 leaf error-app-tag { 2189 type string; 2190 description 2191 "The application-specific error tag."; 2192 } 2194 choice error-node { 2195 description 2196 "The server will return the location of the error node 2197 in a format that is appropriate for the protocol. 2198 If no specific node within the request message body 2199 caused the error then this choice will not be present."; 2201 leaf error-path { 2202 type instance-identifier; 2203 description 2204 "The YANG instance identifier associated 2205 with the error node. This leaf will only be 2206 present if the error node is not a data resource, 2207 e.g., the error node is an input parameter 2208 for an operation resource."; 2209 } 2210 leaf error-urlpath { 2211 type data-resource-identifier; 2212 description 2213 "The target data resource identifier associated 2214 with the error node. This leaf will only be 2215 present if the error node is associated with 2216 a data resource (either within the server or 2217 in the request message)."; 2218 } 2219 } 2221 leaf error-message { 2222 type string; 2223 description 2224 "A message describing the error."; 2225 } 2227 anyxml error-info { 2228 description 2229 "Arbitrary XML that represents a container 2230 of additional information for the error report."; 2231 } 2232 } 2233 } 2234 } // grouping errors 2236 grouping restconf { 2237 description 2238 "A grouping that contains a YANG container 2239 representing the syntax and semantics of 2240 the RESTCONF API resource."; 2242 container restconf { 2243 description 2244 "Conceptual container representing the 2245 application/yang.api resource type."; 2247 container data { 2248 description 2249 "Container representing the application/yang.datastore 2250 resource type. Represents the conceptual root of all 2251 operational data and configuration data supported by 2252 the server. The child nodes of this container can be 2253 any data resource (application/yang.data), which are 2254 defined as top-level data nodes from the YANG modules 2255 advertised by the server in /restconf/modules."; 2256 } 2257 container modules { 2258 description 2259 "Contains a list of module description entries. 2260 These modules are currently loaded into the server."; 2262 grouping common-leafs { 2263 description 2264 "Common parameters for YANG modules and submodules."; 2266 leaf name { 2267 type yang:yang-identifier; 2268 description "The YANG module or submodule name."; 2269 } 2270 leaf revision { 2271 type union { 2272 type revision-identifier; 2273 type string { length 0; } 2274 } 2275 description 2276 "The YANG module or submodule revision date. 2277 An empty string is used if no revision statement 2278 is present in the YANG module or submodule."; 2279 } 2281 leaf schema { 2282 type empty; 2283 description 2284 "Represents the YANG schema resource for this module 2285 or submodule if it is available on the server. 2286 This leaf will only be present if the server has 2287 the schema available for retrieval. A GET 2288 request with a target resource URI that identifies 2289 this leaf will cause the server to return the YANG 2290 schema text for the associated module or submodule."; 2291 } 2292 } 2294 list module { 2295 key "name revision"; 2296 description 2297 "Each entry represents one module currently 2298 supported by the server."; 2300 uses common-leafs; 2302 leaf namespace { 2303 type inet:uri; 2304 mandatory true; 2305 description 2306 "The XML namespace identifier for this module."; 2307 } 2308 leaf-list feature { 2309 type yang:yang-identifier; 2310 description 2311 "List of YANG feature names from this module that are 2312 supported by the server."; 2313 } 2314 leaf-list deviation { 2315 type yang:yang-identifier; 2316 description 2317 "List of YANG deviation module names used by this 2318 server to modify the conformance of the module 2319 associated with this entry."; 2320 } 2322 list submodule { 2323 key "name revision"; 2324 description 2325 "Each entry represents one submodule within the 2326 parent module."; 2328 uses common-leafs; 2329 } 2330 } 2331 } 2333 container operations { 2334 description 2335 "Container for all operation resources 2336 (application/yang.operation), 2338 Each resource is represented as an empty leaf with the 2339 name of the RPC operation from the YANG rpc statement. 2341 E.g.; 2343 POST /restconf/operations/show-log-errors 2345 leaf show-log-errors { 2346 type empty; 2347 } 2348 "; 2349 } 2351 container streams { 2352 description 2353 "Container representing the notification event streams 2354 supported by the server."; 2355 reference 2356 "RFC 5277, Section 3.4, element."; 2358 list stream { 2359 key name; 2360 description 2361 "Each entry describes an event stream supported by 2362 the server."; 2364 leaf name { 2365 type string; 2366 description "The stream name"; 2367 reference "RFC 5277, Section 3.4, element."; 2368 } 2370 leaf description { 2371 type string; 2372 description "Description of stream content"; 2373 reference 2374 "RFC 5277, Section 3.4, element."; 2375 } 2377 leaf replay-support { 2378 type boolean; 2379 description 2380 "Indicates if replay buffer supported for this stream"; 2381 reference 2382 "RFC 5277, Section 3.4, element."; 2383 } 2385 leaf replay-log-creation-time { 2386 type yang:date-and-time; 2387 description 2388 "Indicates the time the replay log for this stream 2389 was created."; 2390 reference 2391 "RFC 5277, Section 3.4, 2392 element."; 2393 } 2395 leaf events { 2396 type empty; 2397 description 2398 "Represents the entry point for establishing 2399 notification delivery via server sent events."; 2401 } 2402 } 2403 } 2405 } 2406 } // grouping restconf 2408 grouping query-parameters { 2409 description 2410 "Contains conceptual definitions for the query string 2411 parameters used in the RESTCONF protocol."; 2413 leaf content { 2414 type enumeration { 2415 enum config { 2416 description 2417 "Return only configuration descendant data nodes"; 2418 } 2419 enum nonconfig { 2420 description 2421 "Return only non-configuration descendant data nodes"; 2422 } 2423 enum all { 2424 description 2425 "Return all descendant data nodes"; 2426 } 2427 } 2428 description 2429 "The content parameter controls how descendant nodes of 2430 the requested data nodes will be processed in the reply. 2432 This parameter is only allowed for GET methods on 2433 datastore and data resources. A 400 Bad Request error 2434 is returned if used for other methods or resource types. 2436 The default value is determined by the config-stmt 2437 value of the requested data nodes. If 'false', then 2438 the default is 'nonconfig'. If 'true' then the 2439 default is 'config'."; 2440 } 2442 leaf depth { 2443 type union { 2444 type enumeration { 2445 enum unbounded { 2446 description "All sub-resources will be returned."; 2447 } 2449 } 2450 type uint32 { 2451 range "1..max"; 2452 } 2453 } 2454 default unbounded; 2455 description 2456 "The 'depth' parameter is used to specify the number 2457 of nest levels returned in a response for a GET method. 2458 The first nest-level consists of the requested data node 2459 itself. Any child nodes which are contained within 2460 a parent node have a depth value that is 1 greater than 2461 its parent. 2463 This parameter is only allowed for GET methods on api, 2464 datastore, and data resources. A 400 Bad Request error 2465 is returned if used for other methods or resource types. 2467 By default, the server will include all sub-resources 2468 within a retrieved resource, which have the same resource 2469 type as the requested resource. Only one level of 2470 sub-resources with a different media type than the target 2471 resource will be returned."; 2472 } 2474 leaf filter { 2475 type yang:xpath1.0; 2476 description 2477 "The 'filter' parameter is used to indicate which subset of 2478 all possible events are of interest. If not present, all 2479 events not precluded by other parameters will be sent. 2481 This parameter is only allowed for GET methods on a 2482 text/event-stream data resource. A 400 Bad Request error 2483 is returned if used for other methods or resource types. 2485 The format of this parameter is an XPath expression, and 2486 is evaluated in the following context: 2488 o The set of namespace declarations is the set of 2489 prefix and namespace pairs for all supported YANG 2490 modules, where the prefix is the YANG module name, and 2491 the namespace is as defined by the 'namespace' statement 2492 in the YANG module. 2493 o The function library is the core function library defined 2494 in XPATH. 2496 o The set of variable bindings is empty. 2498 o The context node is the root node 2500 The filter is used as defined in [RFC5277], section 3.6. 2501 If the boolean result of the expression is true when applied 2502 to the conceptual 'notification' document root, then the 2503 notification event is delivered to the client."; 2504 } 2506 leaf insert { 2507 type enumeration { 2508 enum first { 2509 description "Insert the new data as the new first entry."; 2510 } 2511 enum last { 2512 description "Insert the new data as the new last entry."; 2513 } 2514 enum before { 2515 description 2516 "Insert the new data before the insertion point, 2517 specified by the value of the 'point' parameter."; 2518 } 2519 enum after { 2520 description 2521 "Insert the new data after the insertion point, 2522 specified by the value of the 'point' parameter."; 2523 } 2524 } 2525 default last; 2526 description 2527 "The 'insert' parameter is used to specify how a 2528 resource should be inserted within a user-ordered list. 2530 This parameter is only supported for the POST and PUT 2531 methods. It is also only supported if the target 2532 resource is a data resource, and that data represents 2533 a YANG list or leaf-list that is ordered by the user. 2535 If the values 'before' or 'after' are used, 2536 then a 'point' query parameter for the insertion 2537 parameter MUST also be present, or a 400 Bad Request 2538 error is returned."; 2539 } 2541 leaf point { 2542 type data-resource-identifier; 2543 description 2544 "The 'point' parameter is used to specify the 2545 insertion point for a data resource that is being 2546 created or moved within a user ordered list or leaf-list. 2548 This parameter is only supported for the POST and PUT 2549 methods. It is also only supported if the target 2550 resource is a data resource, and that data represents 2551 a YANG list or leaf-list that is ordered by the user. 2553 If the 'insert' query parameter is not present, or has 2554 a value other than 'before' or 'after', then a 400 2555 Bad Request error is returned. 2557 This parameter contains the instance identifier of the 2558 resource to be used as the insertion point for a 2559 POST or PUT method."; 2560 } 2562 leaf select { 2563 type string { 2564 length "1 .. max"; 2565 } 2566 description 2567 "The 'select' query parameter is used to optionally identify 2568 data nodes within the target resource to be retrieved in a 2569 GET method. The client can use this parameter to retrieve 2570 a subset of all nodes in a resource. 2572 A value of the 'select' query parameter matches the 2573 following rule: 2575 select-expr = path '(' select-expr / '*' ')' / 2576 path ';' select-expr / 2577 path 2578 path = api-identifier [ '/' path ] 2580 'api-identifier' is defined in section 5.3.1.1. 2582 ';' is used to select multiple nodes. For example, to 2583 retreive only the 'genre' and 'year' of an album, use: 2584 'select=genre;year'. 2586 Parentheses are used to specify sub-selectors of a node. 2587 For example, to retreive only the 'label' and 2588 'catalogue-number' of an album, use: 2589 'select=admin(label;catalogue-number)'. 2591 '/' is used in a path to retreive a child node of a node. 2592 For example, to retreive only the 'label' of an album, use: 2593 'select=admin/label'. 2595 This parameter is only allowed for GET methods on api, 2596 datastore, and data resources. A 400 Bad Request error 2597 is returned if used for other methods or resource types."; 2598 reference 2599 "RFC XXXX: [sec. 5.3.1.1 ABNF For Data Resource Identifiers]"; 2600 } 2602 leaf start-time { 2603 type yang:date-and-time; 2604 description 2605 "The 'start-time' parameter is used to trigger 2606 the notification replay feature and indicate 2607 that the replay should start at the time specified. 2608 If the stream does not support replay, per the 2609 'replay-support' attribute returned by 2610 the /restconf/streams resource, then the server MUST 2611 return the HTTP error code 400 Bad Request. 2613 This parameter is only allowed for GET methods on a 2614 text/event-stream data resource. A 400 Bad Request error 2615 is returned if used for other methods or resource types. 2617 If this parameter is not present, then a replay subscription 2618 is not begin requested. It is not valid to specify start 2619 times that are later than the current time. If the value 2620 specified is earlier than the log can support, the replay 2621 will begin with the earliest available notification"; 2622 } 2624 leaf stop-time { 2625 type yang:date-and-time; 2626 description 2627 "The 'stop-time' parameter is used with the 2628 replay feature to indicate the newest notifications of 2629 interest. This parameter MUST be used with and have a 2630 value later than the 'start-time' parameter. 2632 This parameter is only allowed for GET methods on a 2633 text/event-stream data resource. A 400 Bad Request error 2634 is returned if used for other methods or resource types. 2636 If this parameter is not present, the notifications will 2637 continue until the subscription is terminated. 2638 Values in the future are valid."; 2639 } 2641 } // grouping query-parameters 2642 grouping notification { 2643 description 2644 "Contains the notification message wrapper definition."; 2646 container notification { 2647 description 2648 "RESTCONF notification message wrapper."; 2650 leaf event-time { 2651 type yang:date-and-time; 2652 mandatory true; 2653 description 2654 "The time the event was generated by the 2655 event source."; 2656 reference 2657 "RFC 5277, section 4, element."; 2658 } 2660 /* The YANG-specific notification container is encoded 2661 * after the 'event-time' element. The format 2662 * corresponds to the notificationContent element 2663 * in RFC 5277, section 4. For example: 2664 * 2665 * module example-one { 2666 * ... 2667 * notification event1 { ... } 2668 * 2669 * } 2670 * 2671 * Encoded as element 'event1' in the namespace 2672 * for module 'example-one'. 2673 */ 2674 } 2675 } // grouping notification 2677 } 2679 2681 8. IANA Considerations 2683 8.1. The "restconf" Relation Type 2685 This specification registers the "restconf" relation type in the Link 2686 Relation Type Registry defined by [RFC5988]: 2688 Relation Name: restconf 2690 Description: Identifies the root of RESTCONF API as configured 2691 on this HTTP server. The "restconf" relation 2692 defines the root of the API defined in RFCXXXX. 2693 Subsequent revisions of RESTCONF will use alternate 2694 relation values to support protocol versioning. 2696 Reference: RFC XXXX 2698 ` 2700 8.2. YANG Module Registry 2702 This document registers one URI in the IETF XML registry [RFC3688]. 2703 Following the format in RFC 3688, the following registration is 2704 requested to be made. 2706 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 2707 Registrant Contact: The NETMOD WG of the IETF. 2708 XML: N/A, the requested URI is an XML namespace. 2710 This document registers one YANG module in the YANG Module Names 2711 registry [RFC6020]. 2713 name: ietf-restconf 2714 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 2715 prefix: rc 2716 // RFC Ed.: replace XXXX with RFC number and remove this note 2717 reference: RFC XXXX 2719 8.3. application/yang Media Sub Types 2721 The parent MIME media type for RESTCONF resources is application/ 2722 yang, which is defined in [RFC6020]. This document defines the 2723 following sub-types for this media type. 2725 - api 2726 - data 2727 - datastore 2728 - errors 2729 - operation 2730 - stream 2732 Type name: application 2734 Subtype name: yang.xxx 2736 Required parameters: TBD 2738 Optional parameters: TBD 2740 Encoding considerations: TBD 2742 Security considerations: TBD 2744 Interoperability considerations: TBD 2746 // RFC Ed.: replace XXXX with RFC number and remove this note 2747 Published specification: RFC XXXX 2749 9. Security Considerations 2751 This section provides security considerations for the resources 2752 defined by the RESTCONF protocol. Security considerations for HTTPS 2753 are defined in [RFC2818]. Security considerations for the content 2754 manipulated by RESTCONF can be found in the documents defining data 2755 models. 2757 This document does not specify an authentication scheme, but it does 2758 require that an authenticated NETCONF username be associated with 2759 each HTTP request. The authentication scheme MAY be implemented in 2760 the underlying transport layer (e.g., client certificates) or within 2761 the HTTP layer (e.g., Basic Auth, OAuth, etc.). RESTCONF does not 2762 itself define an authentication mechanism, authentication MUST occur 2763 in a lower layer. Implementors SHOULD provide a comprehensive 2764 authorization scheme with RESTCONF and ensure that the resulting 2765 NETCONF username is made available to the RESTCONF server. 2767 Authorization of individual user access to operations and data MAY be 2768 configured via NETCONF Access Control Model (NACM) [RFC6536], as 2769 specified in Section 2. Other authorization models MAY be used, but 2770 are outside of the scope of this document. 2772 Configuration information is by its very nature sensitive. Its 2773 transmission in the clear and without integrity checking leaves 2774 devices open to classic eavesdropping and false data injection 2775 attacks. Configuration information often contains passwords, user 2776 names, service descriptions, and topological information, all of 2777 which are sensitive. Because of this, this protocol SHOULD be 2778 implemented carefully with adequate attention to all manner of attack 2779 one might expect to experience with other management interfaces. 2781 Different environments may well allow different rights prior to and 2782 then after authentication. When an operation is not properly 2783 authorized, the RESTCONF server MUST return HTTP error status code 2784 401 Unauthorized. Note that authorization information can be 2785 exchanged in the form of configuration information, which is all the 2786 more reason to ensure the security of the connection. 2788 10. References 2790 10.1. Normative References 2792 [I-D.lhotka-netmod-json] 2793 Lhotka, L., "Modeling JSON Text with YANG", 2794 draft-lhotka-netmod-yang-json-02 (work in progress), 2795 September 2013. 2797 [JSON] Bray, T., Ed., "The JSON Data Interchange Format", 2798 draft-ietf-json-rfc4627bis-10 (work in progress), 2799 December 2013. 2801 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2802 Requirement Levels", BCP 14, RFC 2119, March 1997. 2804 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol, Version 1.0", 2805 RFC 2246, January 1999. 2807 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2808 Resource Identifiers (URI): Generic Syntax", RFC 2396, 2809 August 1998. 2811 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2812 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2813 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2815 [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. 2817 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2818 January 2004. 2820 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2821 Resource Identifier (URI): Generic Syntax", STD 66, 2822 RFC 3986, January 2005. 2824 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2825 Notifications", RFC 5277, July 2008. 2827 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2828 Housley, R., and T. Polk, "Internet X.509 Public Key 2829 Infrastructure Certificate and Certificate Revocation List 2830 (CRL) Profile", RFC 5280, May 2008. 2832 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 2833 RFC 5789, March 2010. 2835 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 2837 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 2838 Network Configuration Protocol (NETCONF)", RFC 6020, 2839 October 2010. 2841 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2842 and A. Bierman, Ed., "Network Configuration Protocol 2843 (NETCONF)", RFC 6241, June 2011. 2845 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", 2846 RFC 6415, October 2011. 2848 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2849 Protocol (NETCONF) Access Control Model", RFC 6536, 2850 March 2012. 2852 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 2853 and D. Orchard, "URI Template", RFC 6570, March 2012. 2855 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 2856 July 2013. 2858 [W3C.REC-xml-20081126] 2859 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 2860 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 2861 Edition)", World Wide Web Consortium Recommendation REC- 2862 xml-20081126, November 2008, 2863 . 2865 [get-off-my-lawn] 2866 Nottingham, M., "URI Design and Ownership", Best Current 2867 Practice draft-ietf-appsawg-uri-get-off-my-lawn-05, 2868 May 2014. 2870 [rest-dissertation] 2871 Fielding, R., "Architectural Styles and the Design of 2872 Network-based Software Architectures", 2000. 2874 [wd-eventsource] 2875 Hickson, I., "Server-Sent Events", December 2012. 2877 10.2. Informative References 2879 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 2880 Version 1.0", World Wide Web Consortium 2881 Recommendation REC-xpath-19991116, November 1999, 2882 . 2884 Appendix A. Change Log 2886 -- RFC Ed.: remove this section before publication. 2888 A.1. 00 - 01 2890 o fixed content=nonconfig example (non-config was incorrect) 2892 o closed open issue 'message-id'. There is no need for a message-id 2893 field, and RFC 2392 does not apply. 2895 o closed open issue 'server support verification'. The headers used 2896 by RESTCONF are widely supported. 2898 o removed encoding rules from section on RESTCONF Meta-Data. This 2899 is now defined in [I-D.lhotka-netmod-json]. 2901 o added media type application/yang.errors to map to errors YANG 2902 grouping. Updated error examples to use new media type. 2904 o closed open issue 'additional datastores'. Support may be added 2905 in the future to identify new datastores. 2907 o closed open issue 'PATCH media type discovery'. The section on 2908 PATCH has an added sentence on the Accept-Patch header. 2910 o closed open issue 'YANG to resource mapping'. Current mapping of 2911 all data nodes to resources will be used in order to allow 2912 mandatory DELETE support. The PATCH operation is optional, as 2913 well as the YANG Patch media type. 2915 o closed open issue '_self links for HATEOAS support'. It was 2916 decided that they are redundant because they can be derived from 2917 the YANG module for the specific data. 2919 o added explanatory text for the 'select' parameter. 2921 o added RESTCONF Path Resolution section for discovering the root of 2922 the RESTCONF API using the /.well-known/host-meta. 2924 o added an "error" media type to for structured error messages 2926 o added Secure Transport section requiring TLS 2928 o added Security Considerations section 2930 o removed all references to "REST-like" 2932 A.2. bierman:restconf-04 to ietf:restconf-00 2934 o updated open issues section 2936 Appendix B. Open Issues 2938 -- RFC Ed.: remove this section before publication. 2940 B.1. select parameter 2942 o What syntax should be used for the "select" query parameter? The 2943 current choices are "XPath" and "path-expr". Perhaps an 2944 additional parameter to identify the select string format is 2945 needed to allow extensibility? 2947 Status: solution proposal added by Martin. 2949 B.2. netconf-state monitoring support 2951 o Should long-term RESTCONF operations (i.e. SSE long-poll) be 2952 considered sessions with regards to NETCONF monitoring "session" 2953 list? If so, what text is needed in RESTCONF draft to standardize 2954 the RESTCONF session entries? 2956 Status: closed-update-pending 2958 Resolution: 2960 A new data structure to monitor streams can be added to the netconf- 2961 state sub-tree. The session-id in this new data structure is not 2962 restricted to the NETCONF-only rules for the sessions sub-tree. 2964 B.3. secure transport 2966 o Details to support secure operation over TLS are needed 2968 Status: closed 2970 o Security considerations need to be written 2972 Status: closed 2974 o Can call-home for RESTCONF be supported 2976 Status: open 2978 B.4. Encoding of key leafs in resource URIs 2980 o The use of a forward slash '/' as the delimiter between key values 2981 in a target resource URI is not not desirable. Only 1 segment per 2982 YANG data node layer should be used. 2984 Status: open 2986 Proposals: 2988 Example: list foo, int8 keys X and Y 2990 Old: 2992 /restconf/data/foo/19/22/foo-leaf 2994 New: 2996 /restconf/data/foo=19,22/foo-leaf 2998 Or: 3000 /restconf/data/foo/19,22/foo-leaf 3002 B.5. get-bulk query parameters 3004 o New query parameters (e.g., offset, limit) are needed to retrieve 3005 a limited number of list instances. 3007 Status: solution proposal pending 3009 Resolution: This bulk retrieval mechanism will be added. 3011 B.6. defaults handling 3013 o The client does not really know what sort of defaults the server 3014 will return in GET replies. Should the with-defaults query 3015 parameter be added to RESTCONF? If so, should it be mandatory-to- 3016 implement? 3018 Status: open 3020 B.7. protocol capability URIs 3022 o The client does not know what vendor extensions (if any) are 3023 implemented by the server. Should the server provide a read-only 3024 container of capability URIs to identify protocol extensions? The 3025 NETMOD WG may also want to extend the protocol in the future 3026 without updating the core RESTCONF RFC. 3028 Status: open 3030 B.8. target resource list keys required for GET 3032 o Should the client be able to GET all or a subset of all list 3033 instances by issuing a GET without any list keys for the target 3034 resource list? 3036 GET /restconf/data/interfaces/interface 3038 o Should a "collection" resource be required in order for such a 3039 request to be considered valid by the server. 3041 Status: open 3043 Appendix C. Example YANG Module 3045 The example YANG module used in this document represents a simple 3046 media jukebox interface. 3048 YANG Tree Diagram for "example-jukebox" Module 3050 +--rw jukebox? 3051 +--rw library 3052 | +--rw artist [name] 3053 | | +--rw name string 3054 | | +--rw album [name] 3055 | | +--rw name string 3056 | | +--rw genre? identityref 3057 | | +--rw year? uint16 3058 | | +--rw admin 3059 | | | +--rw label? string 3060 | | | +--rw catalogue-number? string 3061 | | +--rw song [name] 3062 | | +--rw name string 3063 | | +--rw location string 3064 | | +--rw format? string 3065 | | +--rw length? uint32 3066 | +--ro artist-count? uint32 3067 | +--ro album-count? uint32 3068 | +--ro song-count? uint32 3069 +--rw playlist [name] 3070 | +--rw name string 3071 | +--rw description? string 3072 | +--rw song [index] 3073 | +--rw index uint32 3074 | +--rw id instance-identifier 3075 +--rw player 3076 +--rw gap? decimal64 3078 rpcs: 3080 +---x play 3081 +--ro input 3082 +--ro playlist string 3083 +--ro song-number uint32 3085 C.1. example-jukebox YANG Module 3087 module example-jukebox { 3088 namespace "http://example.com/ns/example-jukebox"; 3089 prefix "jbox"; 3090 import ietf-restconf { prefix rc; } 3092 organization "Example, Inc."; 3093 contact "support at example.com"; 3094 description "Example Jukebox Data Model Module"; 3095 revision "2014-07-03" { 3096 description "Initial version."; 3097 reference "example.com document 1-4673"; 3098 } 3100 identity genre { 3101 description "Base for all genre types"; 3102 } 3104 // abbreviated list of genre classifications 3105 identity alternative { 3106 base genre; 3107 description "Alternative music"; 3108 } 3109 identity blues { 3110 base genre; 3111 description "Blues music"; 3112 } 3113 identity country { 3114 base genre; 3115 description "Country music"; 3116 } 3117 identity jazz { 3118 base genre; 3119 description "Jazz music"; 3120 } 3121 identity pop { 3122 base genre; 3123 description "Pop music"; 3124 } 3125 identity rock { 3126 base genre; 3127 description "Rock music"; 3128 } 3130 container jukebox { 3131 presence 3132 "An empty container indicates that the jukebox 3133 service is available"; 3135 description 3136 "Represents a jukebox resource, with a library, playlists, 3137 and a play operation."; 3139 container library { 3141 description "Represents the jukebox library resource."; 3143 list artist { 3144 key name; 3146 description 3147 "Represents one artist resource within the 3148 jukebox library resource."; 3150 leaf name { 3151 type string { 3152 length "1 .. max"; 3153 } 3154 description "The name of the artist."; 3155 } 3157 list album { 3158 key name; 3160 description 3161 "Represents one album resource within one 3162 artist resource, within the jukebox library."; 3164 leaf name { 3165 type string { 3166 length "1 .. max"; 3167 } 3168 description "The name of the album."; 3169 } 3171 leaf genre { 3172 type identityref { base genre; } 3173 description 3174 "The genre identifying the type of music on 3175 the album."; 3176 } 3178 leaf year { 3179 type uint16 { 3180 range "1900 .. max"; 3181 } 3182 description "The year the album was released"; 3183 } 3184 container admin { 3185 description 3186 "Administrative information for the album."; 3188 leaf label { 3189 type string; 3190 description "The label that released the album."; 3191 } 3192 leaf catalogue-number { 3193 type string; 3194 description "The album's catalogue number."; 3195 } 3196 } 3198 list song { 3199 key name; 3201 description 3202 "Represents one song resource within one 3203 album resource, within the jukebox library."; 3205 leaf name { 3206 type string { 3207 length "1 .. max"; 3208 } 3209 description "The name of the song"; 3210 } 3211 leaf location { 3212 type string; 3213 mandatory true; 3214 description 3215 "The file location string of the 3216 media file for the song"; 3217 } 3218 leaf format { 3219 type string; 3220 description 3221 "An identifier string for the media type 3222 for the file associated with the 3223 'location' leaf for this entry."; 3224 } 3225 leaf length { 3226 type uint32; 3227 units "seconds"; 3228 description 3229 "The duration of this song in seconds."; 3230 } 3231 } // end list 'song' 3233 } // end list 'album' 3234 } // end list 'artist' 3236 leaf artist-count { 3237 type uint32; 3238 units "songs"; 3239 config false; 3240 description "Number of artists in the library"; 3241 } 3242 leaf album-count { 3243 type uint32; 3244 units "albums"; 3245 config false; 3246 description "Number of albums in the library"; 3247 } 3248 leaf song-count { 3249 type uint32; 3250 units "songs"; 3251 config false; 3252 description "Number of songs in the library"; 3253 } 3254 } // end library 3256 list playlist { 3257 key name; 3259 description 3260 "Example configuration data resource"; 3262 leaf name { 3263 type string; 3264 description 3265 "The name of the playlist."; 3266 } 3267 leaf description { 3268 type string; 3269 description 3270 "A comment describing the playlist."; 3271 } 3272 list song { 3273 key index; 3274 ordered-by user; 3276 description 3277 "Example nested configuration data resource"; 3279 leaf index { // not really needed 3280 type uint32; 3281 description 3282 "An arbitrary integer index for this 3283 playlist song."; 3284 } 3285 leaf id { 3286 type rc:data-resource-identifier; 3287 mandatory true; 3288 description 3289 "Song identifier. Must identify an instance of 3290 /jukebox/library/artist/album/song/name."; 3291 } 3292 } 3293 } 3295 container player { 3296 description 3297 "Represents the jukebox player resource."; 3299 leaf gap { 3300 type decimal64 { 3301 fraction-digits 1; 3302 range "0.0 .. 2.0"; 3303 } 3304 units "tenths of seconds"; 3305 description "Time gap between each song"; 3306 } 3307 } 3308 } 3310 rpc play { 3311 description "Control function for the jukebox player"; 3312 input { 3313 leaf playlist { 3314 type string; 3315 mandatory true; 3316 description "playlist name"; 3317 } 3318 leaf song-number { 3319 type uint32; 3320 mandatory true; 3321 description "Song number in playlist to play"; 3322 } 3323 } 3324 } 3325 } 3327 Appendix D. RESTCONF Message Examples 3329 The examples within this document use the normative YANG module 3330 defined in Section 7 and the non-normative example YANG module 3331 defined in Appendix C.1. 3333 This section shows some typical RESTCONF message exchanges. 3335 D.1. Resource Retrieval Examples 3337 D.1.1. Retrieve the Top-level API Resource 3339 The client may start by retrieving the top-level API resource, using 3340 the entry point URI "{+restconf}". 3342 GET /restconf HTTP/1.1 3343 Host: example.com 3344 Accept: application/yang.api+json, 3345 application/yang.errors+json 3347 The server might respond as follows: 3349 HTTP/1.1 200 OK 3350 Date: Mon, 23 Apr 2012 17:01:00 GMT 3351 Server: example-server 3352 Content-Type: application/yang.api+json 3354 { 3355 "ietf-restconf:restconf": { 3356 "data" : [ null ], 3357 "modules": { 3358 "module": [ 3359 { 3360 "name" : "example-jukebox", 3361 "revision" : "2014-07-03", 3362 "namespace" : "http://example.com/ns/example-jukebox", 3363 "schema" : [ null ] 3364 } 3365 ] 3366 }, 3367 "operations" : { 3368 "play" : [ null ] 3369 }, 3370 "streams" : { 3371 "stream" : [ 3372 { 3373 "name" : "NETCONF", 3374 "description" : "default NETCONF event stream", 3375 "replay-support" : true, 3376 "replay-log-creation-time:" : "2007-07-08T00:00:00Z", 3377 "events" : [ null ] 3378 } 3379 ] 3380 } 3381 } 3382 } 3384 To request that the response content to be encoded in XML, the 3385 "Accept" header can be used, as in this example request: 3387 GET /restconf HTTP/1.1 3388 Host: example.com 3389 Accept: application/yang.api+xml, 3390 application/yang.errors+xml 3392 The server will return the same response either way, which might be 3393 as follows : 3395 HTTP/1.1 200 OK 3396 Date: Mon, 23 Apr 2012 17:01:00 GMT 3397 Server: example-server 3398 Cache-Control: no-cache 3399 Pragma: no-cache 3400 Content-Type: application/yang.api+xml 3402 3403 3404 3405 3406 example-jukebox 3407 2014-07-03 3408 3409 http://example.com/ns/example-jukebox 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 NETCONF 3420 default NETCONF event stream 3421 3422 true 3423 3424 2007-07-08T00:00:00Z 3425 3426 3427 3428 3429 3431 D.1.2. Retrieve The Server Module Information 3433 In this example the client is retrieving the modules resource from 3434 the server in JSON format: 3436 GET /restconf/modules HTTP/1.1 3437 Host: example.com 3438 Accept: application/yang.api+json, 3439 application/yang.errors+json 3441 The server might respond as follows. 3443 HTTP/1.1 200 OK 3444 Date: Mon, 23 Apr 2012 17:01:00 GMT 3445 Server: example-server 3446 Cache-Control: no-cache 3447 Pragma: no-cache 3448 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 3449 Content-Type: application/yang.api+json 3451 { 3452 "ietf-restconf:modules": { 3453 "module": [ 3454 { 3455 "name" : "foo", 3456 "revision" : "2012-01-02", 3457 "schema" : [null], 3458 "namespace" : "http://example.com/ns/foo", 3459 "feature" : [ "feature1", "feature2" ] 3460 }, 3461 { 3462 "name" : "foo-types", 3463 "revision" : "2012-01-05", 3464 "schema" : [null], 3465 "namespace" : "http://example.com/ns/foo-types" 3466 }, 3467 { 3468 "name" : "bar", 3469 "revision" : "2012-11-05", 3470 "schema" : [null], 3471 "namespace" : "http://example.com/ns/bar", 3472 "feature" : [ "bar-ext" ], 3473 "submodule" : [ 3474 { 3475 "name" : "bar-submod1", 3476 "revision" : "2012-11-05", 3477 "schema" : [null] 3478 }, 3479 { 3480 "name" : "bar-submod2", 3481 "revision" : "2012-11-05", 3482 "schema" : [null] 3483 } 3484 ] 3485 } 3486 ] 3487 } 3488 } 3490 D.2. Edit Resource Examples 3492 D.2.1. Create New Data Resources 3494 To create a new "artist" resource within the "library" resource, the 3495 client might send the following request. 3497 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 3498 Host: example.com 3499 Content-Type: application/yang.data+json 3501 { "example-jukebox:artist" : { 3502 "name" : "Foo Fighters" 3503 } 3504 } 3506 If the resource is created, the server might respond as follows. 3507 Note that the "Location" header line is wrapped for display purposes 3508 only: 3510 HTTP/1.1 201 Created 3511 Date: Mon, 23 Apr 2012 17:02:00 GMT 3512 Server: example-server 3513 Location: http://example.com/restconf/data/ 3514 example-jukebox:jukebox/library/artist=Foo%20Fighters 3515 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 3516 ETag: b3830f23a4c 3518 To create a new "album" resource for this artist within the "jukebox" 3519 resource, the client might send the following request. Note that the 3520 request URI header line is wrapped for display purposes only: 3522 POST /restconf/data/example-jukebox:jukebox/ 3523 library/artist=Foo%20Fighters HTTP/1.1 3524 Host: example.com 3525 Content-Type: application/yang.data+json 3527 { 3528 "example-jukebox:album" : { 3529 "name" : "Wasting Light", 3530 "genre" : "example-jukebox:alternative", 3531 "year" : 2012 # note this is the wrong date 3532 } 3533 } 3535 If the resource is created, the server might respond as follows. 3536 Note that the "Location" header line is wrapped for display purposes 3537 only: 3539 HTTP/1.1 201 Created 3540 Date: Mon, 23 Apr 2012 17:03:00 GMT 3541 Server: example-server 3542 Location: http://example.com/restconf/data/ 3543 example-jukebox:jukebox/library/artist=Foo%20Fighters/ 3544 album=Wasting%20Light 3545 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 3546 ETag: b8389233a4c 3548 D.2.2. Detect Resource Entity Tag Change 3550 In this example, the server just supports the mandatory datastore 3551 last-changed timestamp. The client has previously retrieved the 3552 "Last-Modified" header and has some value cached to provide in the 3553 following request to patch an "album" list entry with key value 3554 "Wasting Light". Only the "year" field is being updated. 3556 PATCH /restconf/data/example-jukebox:jukebox/ 3557 library/artist=Foo%20Fighters/album=Wasting%20Light/year 3558 HTTP/1.1 3559 Host: example.com 3560 Accept: application/yang.data+json, 3561 application/yang.errors+json 3562 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 3563 Content-Type: application/yang.data+json 3565 { "example-jukebox:year" : "2011" } 3567 In this example the datastore resource has changed since the time 3568 specified in the "If-Unmodified-Since" header. The server might 3569 respond: 3571 HTTP/1.1 412 Precondition Failed 3572 Date: Mon, 23 Apr 2012 19:01:00 GMT 3573 Server: example-server 3574 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 3575 ETag: b34aed893a4c 3577 D.3. Query String Parameter Examples 3579 D.3.1. "content" Parameter 3581 The "content" parameter is used to select the type of data child 3582 resources (configuration and/or not configuration) that are returned 3583 by the server for a GET method request. 3585 In this example, a simple YANG list that has configuration and non- 3586 configuration child resources. 3588 container events 3589 list event { 3590 key name; 3591 leaf name { type string; } 3592 leaf description { type string; } 3593 leaf event-count { 3594 type uint32; 3595 config false; 3596 } 3597 } 3598 } 3600 Example 1: content=all 3602 To retrieve all the child resources, the "content" parameter is set 3603 to "all". The client might send: 3605 GET /restconf/data/example-events:events?content=all 3606 HTTP/1.1 3607 Host: example.com 3608 Accept: application/yang.data+json, 3609 application/yang.errors+json 3611 The server might respond: 3613 HTTP/1.1 200 OK 3614 Date: Mon, 23 Apr 2012 17:11:30 GMT 3615 Server: example-server 3616 Cache-Control: no-cache 3617 Pragma: no-cache 3618 Content-Type: application/yang.data+json 3620 { 3621 "example-events:events" : { 3622 "event" : [ 3623 { 3624 "name" : "interface-up", 3625 "description" : "Interface up notification count", 3626 "event-count" : 42 3627 }, 3628 { 3629 "name" : "interface-down", 3630 "description" : "Interface down notification count", 3631 "event-count" : 4 3632 } 3633 ] 3634 } 3635 } 3637 Example 2: content=config 3639 To retrieve only the configuration child resources, the "content" 3640 parameter is set to "config" or omitted since this is the default 3641 value. Note that the "ETag" and "Last-Modified" headers are only 3642 returned if the content parameter value is "config". 3644 GET /restconf/data/example-events:events?content=config 3645 HTTP/1.1 3646 Host: example.com 3647 Accept: application/yang.data+json, 3648 application/yang.errors+json 3650 The server might respond: 3652 HTTP/1.1 200 OK 3653 Date: Mon, 23 Apr 2012 17:11:30 GMT 3654 Server: example-server 3655 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 3656 ETag: eeeada438af 3657 Cache-Control: no-cache 3658 Pragma: no-cache 3659 Content-Type: application/yang.data+json 3661 { 3662 "example-events:events" : { 3663 "event" : [ 3664 { 3665 "name" : "interface-up", 3666 "description" : "Interface up notification count" 3667 }, 3668 { 3669 "name" : "interface-down", 3670 "description" : "Interface down notification count" 3671 } 3672 ] 3673 } 3674 } 3676 Example 3: content=nonconfig 3678 To retrieve only the non-configuration child resources, the "content" 3679 parameter is set to "nonconfig". Note that configuration ancestors 3680 (if any) and list key leafs (if any) are also returned. The client 3681 might send: 3683 GET /restconf/data/example-events:events?content=nonconfig 3684 HTTP/1.1 3685 Host: example.com 3686 Accept: application/yang.data+json, 3687 application/yang.errors+json 3689 The server might respond: 3691 HTTP/1.1 200 OK 3692 Date: Mon, 23 Apr 2012 17:11:30 GMT 3693 Server: example-server 3694 Cache-Control: no-cache 3695 Pragma: no-cache 3696 Content-Type: application/yang.data+json 3698 { 3699 "example-events:events" : { 3700 "event" : [ 3701 { 3702 "name" : "interface-up", 3703 "event-count" : 42 3704 }, 3705 { 3706 "name" : "interface-down", 3707 "event-count" : 4 3708 } 3709 ] 3710 } 3711 } 3713 D.3.2. "depth" Parameter 3715 The "depth" parameter is used to limit the number of levels of child 3716 resources that are returned by the server for a GET method request. 3718 This example shows how different values of the "depth" parameter 3719 would affect the reply content for retrieval of the top-level 3720 "jukebox" data resource. 3722 Example 1: depth=unbounded 3724 To retrieve all the child resources, the "depth" parameter is not 3725 present or set to the default value "unbounded". Note that some 3726 strings are wrapped for display purposes only. 3728 GET /restconf/data/example-jukebox:jukebox?depth=unbounded 3729 HTTP/1.1 3730 Host: example.com 3731 Accept: application/yang.data+json, 3732 application/yang.errors+json 3734 The server might respond: 3736 HTTP/1.1 200 OK 3737 Date: Mon, 23 Apr 2012 17:11:30 GMT 3738 Server: example-server 3739 Cache-Control: no-cache 3740 Pragma: no-cache 3741 Content-Type: application/yang.data+json 3743 { 3744 "example-jukebox:jukebox" : { 3745 "library" : { 3746 "artist" : [ 3747 { 3748 "name" : "Foo Fighters", 3749 "album" : [ 3750 { 3751 "name" : "Wasting Light", 3752 "genre" : "example-jukebox:alternative", 3753 "year" : 2011, 3754 "song" : [ 3755 { 3756 "name" : "Wasting Light", 3757 "location" : 3758 "/media/foo/a7/wasting-light.mp3", 3759 "format" : "MP3", 3760 "length" " 286 3761 }, 3762 { 3763 "name" : "Rope", 3764 "location" : "/media/foo/a7/rope.mp3", 3765 "format" : "MP3", 3766 "length" " 259 3767 } 3768 ] 3769 } 3770 ] 3771 } 3772 ] 3773 }, 3774 "playlist" : [ 3775 { 3776 "name" : "Foo-One", 3777 "description" : "example playlist 1", 3778 "song" : [ 3779 { 3780 "index" : 1, 3781 "id" : "http://example.com/restconf/data/ 3782 example-jukebox:jukebox/library/artist/ 3783 Foo%20Fighters/album/Wasting%20Light/ 3784 song/Rope" 3785 }, 3786 { 3787 "index" : 2, 3788 "id" : "http://example.com/restconf/data/ 3789 example-jukebox:jukebox/library/artist/ 3790 Foo%20Fighters/album/Wasting%20Light/song/ 3791 Bridge%20Burning" 3792 } 3793 ] 3794 } 3795 ], 3796 "player" : { 3797 "gap" : 0.5 3798 } 3799 } 3800 } 3802 Example 2: depth=1 3804 To determine if 1 or more resource instances exist for a given target 3805 resource, the value "1" is used. 3807 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 3808 Host: example.com 3809 Accept: application/yang.data+json, 3810 application/yang.errors+json 3812 The server might respond: 3814 HTTP/1.1 200 OK 3815 Date: Mon, 23 Apr 2012 17:11:30 GMT 3816 Server: example-server 3817 Cache-Control: no-cache 3818 Pragma: no-cache 3819 Content-Type: application/yang.data+json 3821 { 3822 "example-jukebox:jukebox" : [null] 3823 } 3825 Example 3: depth=3 3827 To limit the depth level to the target resource plus 2 child resource 3828 layers the value "3" is used. 3830 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 3831 Host: example.com 3832 Accept: application/yang.data+json, 3833 application/yang.errors+json 3835 The server might respond: 3837 HTTP/1.1 200 OK 3838 Date: Mon, 23 Apr 2012 17:11:30 GMT 3839 Server: example-server 3840 Cache-Control: no-cache 3841 Pragma: no-cache 3842 Content-Type: application/yang.data+json 3844 { 3845 "example-jukebox:jukebox" : { 3846 "library" : { 3847 "artist" : [ null ] 3848 }, 3849 "playlist" : [ 3850 { 3851 "name" : "Foo-One", 3852 "description" : "example playlist 1", 3853 "song" : [ null ] 3854 } 3855 ], 3856 "player" : { 3857 "gap" : 0.5 3858 } 3859 } 3860 } 3862 D.3.3. "filter" Parameter 3864 The following URIs show some examples of notification filter 3865 specifications (lines wrapped for display purposes only): 3867 // filter = /event/eventClass='fault' 3868 GET /restconf/streams/stream=NETCONF/events? 3869 filter=%2Fevent%2FeventClass%3D'fault' 3871 // filter = /event/severityCode<=4 3872 GET /restconf/streams/stream=NETCONF/events? 3873 filter=%2Fevent%2FseverityCode%3C%3D4 3875 // filter = /linkUp|/linkDown 3876 GET /restconf/streams/stream=SNMP/events? 3877 filter=%2FlinkUp%7C%2FlinkDown 3879 // filter = /*/reportingEntity/card!='Ethernet0' 3880 GET /restconf/streams/stream=NETCONF/events? 3881 filter=%2F*%2FreportingEntity%2Fcard%21%3D'Ethernet0' 3883 // filter = /*/email-addr[contains(.,'company.com')] 3884 GET /restconf/streams/stream=critical-syslog/events? 3885 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 3887 // Note: the module name is used as prefix. 3888 // filter = (/example-mod:event1/name='joe' and 3889 // /example-mod:event1/status='online') 3890 GET /restconf/streams/stream=NETCONF/events? 3891 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and 3892 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 3894 D.3.4. "insert" Parameter 3896 In this example, a new first entry in the "Foo-One" playlist is being 3897 created. 3899 Request from client: 3901 POST /restconf/data/example-jukebox:jukebox/ 3902 playlist=Foo-One?insert=first HTTP/1.1 3903 Host: example.com 3904 Content-Type: application/yang.data+json 3906 { 3907 "example-jukebox:song" : { 3908 "index" : 1, 3909 "id" : "/example-jukebox:jukebox/library/artist/ 3910 Foo%20Fighters/album/Wasting%20Light/song/Rope" 3911 } 3912 } 3914 Response from server: 3916 HTTP/1.1 201 Created 3917 Date: Mon, 23 Apr 2012 13:01:20 GMT 3918 Server: example-server 3919 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 3920 Location: http://example.com/restconf/data/ 3921 example-jukebox:jukebox/playlist=Foo-One/song=1 3922 ETag: eeeada438af 3924 D.3.5. "point" Parameter 3926 Example: 3928 In this example, the client is inserting a new "song" resource within 3929 an "album" resource after another song. The request URI is split for 3930 display purposes only. 3932 Request from client: 3934 POST /restconf/data/example-jukebox:jukebox/ 3935 library/artist/Foo%20Fighters/album/Wasting%20Light? 3936 insert=after&point=%2Fexample-jukebox%3Ajukebox%2F 3937 library%2Fartist%2FFoo%20Fighters%2Falbum%2F 3938 Wasting%20Light%2Fsong%2FBridge%20Burning HTTP/1.1 3939 Host: example.com 3940 Content-Type: application/yang.data+json 3942 { 3943 "example-jukebox:song" : { 3944 "name" : "Rope", 3945 "location" : "/media/foo/a7/rope.mp3", 3946 "format" : "MP3", 3947 "length" : 259 3948 } 3949 } 3951 Response from server: 3953 HTTP/1.1 204 No Content 3954 Date: Mon, 23 Apr 2012 13:01:20 GMT 3955 Server: example-server 3956 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 3957 ETag: abcada438af 3959 D.3.6. "select" Parameter 3961 In this example the client is retrieving the API resource, but 3962 selecting only the "name" and "revision" nodes from each module, in 3963 JSON format: 3965 GET /restconf?select=modules/module(name;revision) HTTP/1.1 3966 Host: example.com 3967 Accept: application/yang.api+json, 3968 application/yang.errors+json 3970 The server might respond as follows. 3972 HTTP/1.1 200 OK 3973 Date: Mon, 23 Apr 2012 17:01:00 GMT 3974 Server: example-server 3975 Content-Type: application/yang.api+json 3977 { 3978 "ietf-restconf:restconf": { 3979 "modules": { 3980 "module": [ 3981 { 3982 "name" : "example-jukebox", 3983 "revision" : "2014-07-03" 3984 } 3985 ] 3986 } 3987 } 3988 } 3990 D.3.7. "start-time" Parameter 3992 TBD 3994 D.3.8. "stop-time" Parameter 3996 TBD 3998 Authors' Addresses 4000 Andy Bierman 4001 YumaWorks 4003 Email: andy@yumaworks.com 4005 Martin Bjorklund 4006 Tail-f Systems 4008 Email: mbj@tail-f.com 4010 Kent Watsen 4011 Juniper Networks 4013 Email: kwatsen@juniper.net 4015 Rex Fernando 4016 Cisco 4018 Email: rex@cisco.com