idnits 2.17.1 draft-ietf-netconf-restconf-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1698 has weird spacing: '... method entry...' == Line 2760 has weird spacing: '...ormance boo...' == Line 2764 has weird spacing: '...evision uni...' == Line 3367 has weird spacing: '...ocation str...' == Line 3377 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 (October 8, 2014) is 3481 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: April 11, 2015 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 October 8, 2014 10 RESTCONF Protocol 11 draft-ietf-netconf-restconf-02 13 Abstract 15 This document describes an HTTP-based protocol that provides a 16 programmatic interface for accessing data defined in YANG, using the 17 datastores defined in NETCONF. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on April 11, 2015. 36 Copyright Notice 38 Copyright (c) 2014 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.1. Secure Transport . . . . . . . . . . . . . . . . . . . . 5 55 1.2. Simple Subset of NETCONF Functionality . . . . . . . . . 5 56 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 6 57 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 58 1.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 7 59 1.4.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 8 60 1.4.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 8 61 1.4.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 9 62 1.4.5. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10 63 2. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 11 64 2.1. RESTCONF Resource Types . . . . . . . . . . . . . . . . . 11 65 2.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 12 66 2.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 12 67 2.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 13 68 2.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 14 69 2.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 14 70 2.4.1. Edit Collision Detection . . . . . . . . . . . . . . 14 71 2.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 15 72 2.5.1. Encoding YANG Instance Identifiers in the Request URI 16 73 2.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 18 74 2.6. Operation Resource . . . . . . . . . . . . . . . . . . . 19 75 2.6.1. Encoding Operation Input Parameters . . . . . . . . . 19 76 2.6.2. Encoding Operation Output Parameters . . . . . . . . 20 77 2.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 21 78 2.8. Stream Resource . . . . . . . . . . . . . . . . . . . . . 22 79 2.9. Errors Resource . . . . . . . . . . . . . . . . . . . . . 23 80 3. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 23 81 3.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 24 82 3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 24 83 3.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 84 3.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 25 85 3.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 26 86 3.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 26 87 3.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 88 3.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 28 89 3.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 30 90 3.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 30 91 3.8.1. Query Parameter URIs . . . . . . . . . . . . . . . . 31 92 3.8.2. The "content" Query Parameter . . . . . . . . . . . . 32 93 3.8.3. The "depth" Query Parameter . . . . . . . . . . . . . 32 94 3.8.4. The "select" Query Parameter . . . . . . . . . . . . 33 95 3.8.5. The "insert" Query Parameter . . . . . . . . . . . . 34 96 3.8.6. The "point" Query Parameter . . . . . . . . . . . . . 34 97 3.8.7. The "filter" Query Parameter . . . . . . . . . . . . 35 98 3.8.8. The "start-time" Query Parameter . . . . . . . . . . 36 99 3.8.9. The "stop-time" Query Parameter . . . . . . . . . . . 36 100 4. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 37 101 4.1. Request URI Structure . . . . . . . . . . . . . . . . . . 37 102 4.2. RESTCONF Path Resolution . . . . . . . . . . . . . . . . 38 103 4.3. Message Headers . . . . . . . . . . . . . . . . . . . . . 39 104 4.4. Message Encoding . . . . . . . . . . . . . . . . . . . . 40 105 4.5. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 41 106 4.6. Return Status . . . . . . . . . . . . . . . . . . . . . . 41 107 4.7. Message Caching . . . . . . . . . . . . . . . . . . . . . 41 108 5. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 42 109 5.1. Server Support . . . . . . . . . . . . . . . . . . . . . 42 110 5.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 42 111 5.3. Subscribing to Receive Notifications . . . . . . . . . . 43 112 5.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 44 113 5.4. Receiving Event Notifications . . . . . . . . . . . . . . 45 114 6. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 46 115 6.1. Error Response Message . . . . . . . . . . . . . . . . . 48 116 7. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 50 117 8. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 56 118 8.1. restconf-state/capabilities . . . . . . . . . . . . . . . 56 119 8.2. restconf-state/streams . . . . . . . . . . . . . . . . . 57 120 8.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 57 121 9. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 60 122 9.1. modules . . . . . . . . . . . . . . . . . . . . . . . . . 61 123 9.1.1. modules/module . . . . . . . . . . . . . . . . . . . 61 124 9.2. YANG Library Module . . . . . . . . . . . . . . . . . . . 62 125 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 66 126 10.1. The "restconf" Relation Type . . . . . . . . . . . . . . 66 127 10.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 66 128 10.3. application/yang Media Sub Types . . . . . . . . . . . . 67 129 10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . 68 130 11. Security Considerations . . . . . . . . . . . . . . . . . . . 68 131 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 69 132 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 69 133 13.1. Normative References . . . . . . . . . . . . . . . . . . 69 134 13.2. Informative References . . . . . . . . . . . . . . . . . 71 135 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 71 136 A.1. 01 - 02 . . . . . . . . . . . . . . . . . . . . . . . . . 71 137 A.2. 00 - 01 . . . . . . . . . . . . . . . . . . . . . . . . . 72 138 A.3. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 73 139 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 73 140 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 73 141 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 74 142 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 79 143 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 80 144 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 80 145 D.1.2. Retrieve The Server Module Information . . . . . . . 81 146 D.1.3. Retrieve The Server Capability Information . . . . . 82 147 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 83 148 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 83 149 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 84 150 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 85 151 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 85 152 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 88 153 D.3.3. "select" Parameter . . . . . . . . . . . . . . . . . 91 154 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 92 155 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 93 156 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 93 157 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 94 158 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 94 159 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 94 161 1. Introduction 163 There is a need for standard mechanisms to allow WEB applications to 164 access the configuration data, operational data, data-model specific 165 protocol operations, and notification events within a networking 166 device, in a modular and extensible manner. 168 This document describes an HTTP [RFC2616] based protocol called 169 RESTCONF, for accessing data defined in YANG [RFC6020], using 170 datastores defined in NETCONF [RFC6241]. 172 The NETCONF protocol defines configuration datastores and a set of 173 Create, Retrieve, Update, Delete (CRUD) operations that can be used 174 to access these datastores. The YANG language defines the syntax and 175 semantics of datastore content, operational data, protocol 176 operations, and notification events. RESTCONF uses HTTP operations 177 to provide CRUD operations on a NETCONF datastore containing YANG- 178 defined data. Since NETCONF protocol operations are not relevant, 179 the user should not need any prior knowledge of NETCONF in order to 180 use RESTCONF. 182 Configuration data and state data are exposed as resources that can 183 be retrieved with the GET method. Resources representing 184 configuration data can be modified with the DELETE, PATCH, POST, and 185 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 186 or JSON [JSON]. 188 Data-model specific protocol operations defined with the YANG "rpc" 189 statement can be invoked with the POST method. Data-model specific 190 notification events defined with the YANG "notification" statement 191 can be accessed. 193 1.1. Secure Transport 195 RESTCONF relies on TLS [RFC2246] to provide privacy and data 196 integrity for its HTTP operations. More specifically, RESTCONF 197 requires HTTP over TLS (HTTPS) [RFC2818]. To ensure security, 198 RESTCONF clients MUST verify the RESTCONF server's X.509 certificate 199 using the path validation algorithm defined in section 6 of 200 [RFC5280]. Devices that do not support TLS will be unable to 201 implement RESTCONF. 203 1.2. Simple Subset of NETCONF Functionality 205 The framework and meta-model used for an HTTP-based API does not need 206 to mirror those used by the NETCONF protocol, but it needs to be 207 compatible with NETCONF. A simplified framework and protocol is 208 needed that utilizes the three NETCONF datastores (candidate, 209 running, startup), but hides the complexity of multiple datastores 210 from the client. 212 A simplified transaction model is needed that allows basic CRUD 213 operations on a hierarchy of conceptual resources. This represents a 214 limited subset of the transaction capabilities of the NETCONF 215 protocol. 217 Applications that require more complex transaction capabilities might 218 consider NETCONF instead of RESTCONF. The following transaction 219 features are not directly provided in RESTCONF: 221 o datastore locking (full or partial) 223 o candidate datastore 225 o startup datastore 227 o validate operation 229 o confirmed-commit procedure 231 RESTCONF is not intended to replace NETCONF, but rather provide an 232 additional simplified interface that follows REST principles and is 233 compatible with a resource-oriented device abstraction. 235 The following figure shows the system components: 237 +-----------+ +-----------------+ 238 | WEB app | <-------> | | 239 +-----------+ HTTP | network device | 240 | | 241 +-----------+ | +-----------+ | 242 | NMS app | <-------> | | datastore | | 243 +-----------+ NETCONF | +-----------+ | 244 +-----------------+ 246 1.3. Data Model Driven API 248 RESTCONF combines the simplicity of the HTTP protocol with the 249 predictability and automation potential of a schema-driven API. 250 Using YANG, a client can predict all resource endpoints, much like 251 using URI Templates [RFC6570], but in a more holistic manner. This 252 strategy obviates the need for responses provided by the server to 253 contain HATEOAS links, originally described in Roy Fielding's 254 doctoral dissertation [rest-dissertation]. 256 A REST client using HATEOAS principles would not use any data 257 modeling language to define the application-specific content of the 258 API. The client would discover each new child resource as it 259 traverses the URIs returned as Location IDs to discover the server 260 capabilities. This approach has 3 significant weaknesses with 261 regards to control of complex networking devices: 263 o inefficient performance: configuration APIs will be quite complex 264 and may require thousands of protocol messages to discover all the 265 schema information. Typically the data type information has to be 266 passed in the protocol messages, which is also wasteful overhead. 268 o no data model richness: without a data model, the schema-level 269 semantics and validation constraints are not available to the 270 application. 272 o no tool automation: API automation tools need some sort of content 273 schema to function. Such tools can automate various programming 274 and documentation tasks related to specific data models. 276 Data model modules such as YANG modules serve as an "API contract" 277 that will be honored by the server. An application designer can code 278 to the data model, knowing in advance important details about the 279 exact protocol operations and datastore content a conforming server 280 implementation will support. 282 RESTCONF provides the YANG module capability information supported by 283 the server, in case the client wants to use it. The URIs for custom 284 protocol operations and datastore content are predictable, based on 285 the YANG module definitions. 287 Operational experience with CLI and SNMP indicates that operators 288 learn the 'location' of specific service or device related data and 289 do not expect such information to be arbitrary and discovered each 290 time the client opens a management session to a server. 292 The RESTCONF protocol operates on a conceptual datastore defined with 293 the YANG data modeling language. The server lists each YANG module 294 it supports under "{+restconf}/modules" in the top-level API resource 295 type, using a structure based on the YANG module capability URI 296 format defined in [RFC6020]. 298 The conceptual datastore contents, data-model-specific operations and 299 notification events are identified by this set of YANG module 300 resources. All RESTCONF content identified as either a data 301 resource, operation resource, or event stream resource is defined 302 with the YANG language. 304 The classification of data as configuration or non-configuration is 305 derived from the YANG "config" statement. Data ordering behavior is 306 derived from the YANG "ordered-by" statement. 308 The RESTCONF datastore editing model is simple and direct, similar to 309 the behavior of the ":writable-running" capability in NETCONF. Each 310 RESTCONF edit of a datastore resource is activated upon successful 311 completion of the transaction. 313 1.4. Terminology 315 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 316 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 317 "OPTIONAL" in this document are to be interpreted as described in BCP 318 14, [RFC2119]. 320 1.4.1. NETCONF 322 The following terms are defined in [RFC6241]: 324 o candidate configuration datastore 326 o client 328 o configuration data 330 o datastore 331 o configuration datastore 333 o protocol operation 335 o running configuration datastore 337 o server 339 o startup configuration datastore 341 o state data 343 o user 345 1.4.2. HTTP 347 The following terms are defined in [RFC2616]: 349 o entity tag 351 o fragment 353 o header line 355 o message body 357 o method 359 o path 361 o query 363 o request 365 o request URI 367 o response body 369 o resource 371 1.4.3. YANG 373 The following terms are defined in [RFC6020]: 375 o container 377 o data node 378 o key leaf 380 o leaf 382 o leaf-list 384 o list 386 o presence container (or P-container) 388 o RPC operation (now called protocol operation) 390 o non-presence container (or NP-container) 392 o ordered-by system 394 o ordered-by user 396 1.4.4. Terms 398 The following terms are used within this document: 400 o API resource: a resource with the media type "application/ 401 yang.api+xml" or "application/yang.api+json". API resources can 402 only be edited by the server. 404 o data resource: a resource with the media type "application/ 405 yang.data+xml" or "application/yang.data+json". Data resources 406 can be edited by clients or the server. All YANG data node types 407 can be data resources. YANG terminal nodes cannot contain child 408 resources. 410 o datastore resource: a resource with the media type "application/ 411 yang.datastore+xml" or "application/yang.datastore+json". 412 Represents a configuration datastore. 414 o edit operation: a RESTCONF operation on a data resource using the 415 POST, PUT, PATCH, or DELETE method. 417 o event stream resource: This resource represents an SSE (Server- 418 Sent Events) event stream. The content consists of text using the 419 media type "text/event-stream", as defined by the HTML5 420 specification. Each event represents one message 421 generated by the server. It contains a conceptual system or data- 422 model specific event that is delivered within a notification event 423 stream. 425 o operation: the conceptual RESTCONF operation for a message, 426 derived from the HTTP method, request URI, headers, and message 427 body. 429 o operation resource: a resource with the media type "application/ 430 yang.operation+xml" or "application/yang.operation+json". 432 o patch: a generic PATCH request on the target datastore or data 433 resource. The media type of the message body content will 434 identify the patch type in use. 436 o plain patch: a PATCH request where the media type is "application/ 437 yang.data+xml" or "application/yang.data+json". 439 o query parameter: a parameter (and its value if any), encoded 440 within the query component of the request URI. 442 o retrieval request: a request using the GET or HEAD methods. 444 o target resource: the resource that is associated with a particular 445 message, identified by the "path" component of the request URI. 447 o unified datastore: A conceptual representation of the device 448 running configuration. The server will hide all NETCONF datastore 449 details for edit operations, such as the ":candidate" and 450 ":startup" capabilities. 452 o schema resource: a resource with the media type "application/ 453 yang". The YANG representation of the schema can be retrieved by 454 the client with the GET method. 456 o YANG terminal node: a YANG node representing a leaf, leaf-list, or 457 anyxml definition. 459 1.4.5. Tree Diagrams 461 A simplified graphical representation of the data model is used in 462 this document. The meaning of the symbols in these diagrams is as 463 follows: 465 o Brackets "[" and "]" enclose list keys. 467 o Abbreviations before data node names: "rw" means configuration 468 data (read-write) and "ro" state data (read-only). 470 o Symbols after data node names: "?" means an optional node, "!" 471 means a presence container, and "*" denotes a list and leaf-list. 473 o Parentheses enclose choice and case nodes, and case nodes are also 474 marked with a colon (":"). 476 o Ellipsis ("...") stands for contents of subtrees that are not 477 shown. 479 2. Resources 481 The RESTCONF protocol operates on a hierarchy of resources, starting 482 with the top-level API resource itself. Each resource represents a 483 manageable component within the device. 485 A resource can be considered a collection of conceptual data and the 486 set of allowed methods on that data. It can contain nested child 487 resources. The child resource types and methods allowed on them are 488 data-model specific. 490 A resource has its own media type identifier, represented by the 491 "Content-Type" header in the HTTP response message. A resource can 492 contain zero or more nested resources. A resource can be created and 493 deleted independently of its parent resource, as long as the parent 494 resource exists. 496 All RESTCONF resources are defined in this document except datastore 497 contents, protocol operations, and notification events. The syntax 498 and semantics for these resource types are defined in YANG modules. 500 The RESTCONF resources are accessed via a set of URIs defined in this 501 document. The set of YANG modules supported by the server will 502 determine the data model specific operations, top-level data node 503 resources, and notification event messages supported by the server. 505 The resources used in the RESTCONF protocol are identified by the 506 "path" component in the request URI. Each operation is performed on 507 a target resource. 509 2.1. RESTCONF Resource Types 511 The RESTCONF protocol defines a set of application specific media 512 types to identify each of the available resource types. The 513 following resource types are defined in RESTCONF: 515 +-----------+----------------------------+ 516 | Resource | Media Type | 517 +-----------+----------------------------+ 518 | API | application/yang.api | 519 | Datastore | application/yang.datastore | 520 | Data | application/yang.data | 521 | Errors | application/yang.errors | 522 | Operation | application/yang.operation | 523 | Schema | application/yang | 524 +-----------+----------------------------+ 526 RESTCONF Media Types 528 2.2. Resource Discovery 530 A client SHOULD start by retrieving the top-level API resource, using 531 the entry point URI defined in Section 4.2. 533 The RESTCONF protocol does not include a resource discovery 534 mechanism. Instead, the definitions within the YANG modules 535 advertised by the server are used to construct a predictable 536 operation or data resource identifier. 538 The "depth" query parameter (see Section 3.8.3) can be used to 539 control how many descendant levels should be included when retrieving 540 child resources. This parameter can be used with the GET method to 541 discover child resources within a particular resource. 543 2.3. API Resource 545 The API resource contains the state and access points for the 546 RESTCONF features. It is the top-level resource and has the media 547 type "application/yang.api+xml" or "application/yang.api+json". 549 YANG Tree Diagram for "application/yang.api" Resource Type: 551 +--rw restconf 552 +--rw data 553 +--rw operations 555 The "restconf" grouping definition in the "ietf-restconf" module 556 defined in Section 7 is used to specify the structure and syntax of 557 the conceptual child resources within the API resource. 559 This resource has the following child resources: 561 +----------------+--------------------------------+ 562 | Child Resource | Description | 563 +----------------+--------------------------------+ 564 | data | Contains all data resources | 565 | operations | Data-model specific operations | 566 +----------------+--------------------------------+ 568 RESTCONF API Resource 570 2.3.1. {+restconf}/data 572 This mandatory resource represents the combined configuration and 573 operational data resources that can be accessed by a client. It 574 cannot be created or deleted by the client. The datastore resource 575 type is defined in Section 2.4. 577 Example: 579 This example request by the client would retrieve only the non- 580 configuration data nodes that exist within the "library" resource, 581 using the "content" query parameter (see Section 3.8.2). 583 GET /restconf/data/example-jukebox:jukebox/library 584 ?content=nonconfig HTTP/1.1 585 Host: example.com 586 Accept: application/yang.data+json, 587 application/yang.errors+json 589 The server might respond: 591 HTTP/1.1 200 OK 592 Date: Mon, 23 Apr 2012 17:01:30 GMT 593 Server: example-server 594 Cache-Control: no-cache 595 Pragma: no-cache 596 Content-Type: application/yang.data+json 598 { 599 "example-jukebox:library" : { 600 "artist-count" : 42, 601 "album-count" : 59, 602 "song-count" : 374 603 } 604 } 606 2.3.2. {+restconf}/operations 608 This optional resource is a container that provides access to the 609 data-model specific protocol operations supported by the server. The 610 server MAY omit this resource if no data-model specific operations 611 are advertised. 613 Any data-model specific operations defined in the YANG modules 614 advertised by the server MAY be available as child nodes of this 615 resource. 617 Operation resources are defined in Section 2.6. 619 2.4. Datastore Resource 621 The "{+restconf}/data" subtree represents the datastore resource 622 type, which is a collection of configuration and operational data 623 nodes. 625 A "unified datastore" interface is used to simplify resource editing 626 for the client. The RESTCONF unified datastore is a conceptual 627 interface to the native configuration datastores that are present on 628 the device. 630 The underlying NETCONF datastores (i.e., candidate, running, startup) 631 can be used to implement the unified datastore, but the server design 632 is not limited to the exact datastore procedures defined in NETCONF. 634 The "candidate" and "startup" datastores are not visible in the 635 RESTCONF protocol. Transaction management and configuration 636 persistence are handled by the server and not controlled by the 637 client. 639 A datastore resource can only be written directly with the PATCH 640 method. Only the configuration data resources within the datastore 641 resource can be edited directly with all methods. 643 Each RESTCONF edit of a datastore resource is saved to non-volatile 644 storage in an implementation-specific matter by the server. There is 645 no guarantee that configuration changes are saved immediately, or 646 that the saved configuration is always a mirror of the running 647 configuration. 649 2.4.1. Edit Collision Detection 651 Two "edit collision detection" mechanisms are provided in RESTCONF, 652 for datastore and data resources. 654 2.4.1.1. Timestamp 656 The last change time is maintained and the "Last-Modified" and "Date" 657 headers are returned in the response for a retrieval request. The 658 "If-Unmodified-Since" header can be used in edit operation requests 659 to cause the server to reject the request if the resource has been 660 modified since the specified timestamp. 662 The server MUST maintain a last-modified timestamp for this resource, 663 and return the "Last-Modified" header when this resource is retrieved 664 with the GET or HEAD methods. Only changes to configuration data 665 resources within the datastore affect this timestamp. 667 2.4.1.2. Entity tag 669 A unique opaque string is maintained and the "ETag" header is 670 returned in the response for a retrieval request. The "If-Match" 671 header can be used in edit operation requests to cause the server to 672 reject the request if the resource entity tag does not match the 673 specified value. 675 The server MUST maintain a resource entity tag for this resource, and 676 return the "ETag" header when this resource is retrieved with the GET 677 or HEAD methods. The resource entity tag MUST be changed to a new 678 previously unused value if changes to any configuration data 679 resources within the datastore are made. 681 2.5. Data Resource 683 A data resource represents a YANG data node that is a descendant node 684 of a datastore resource. 686 For configuration data resources, the server MAY maintain a last- 687 modified timestamp for the resource, and return the "Last-Modified" 688 header when it is retrieved with the GET or HEAD methods. If 689 maintained, the resource timestamp MUST be set to the current time 690 whenever the resource or any configuration resource within the 691 resource is altered. 693 For configuration data resources, the server MAY maintain a resource 694 entity tag for the resource, and return the "ETag" header when it is 695 retrieved as the target resource with the GET or HEAD methods. If 696 maintained, the resource entity tag MUST be updated whenever the 697 resource or any configuration resource within the resource is 698 altered. 700 A data resource can be retrieved with the GET method. Data resources 701 are accessed via the "{+restconf}/data" entry point. This sub-tree 702 is used to retrieve and edit data resources. 704 A configuration data resource can be altered by the client with some 705 or all of the edit operations, depending on the target resource and 706 the specific operation. Refer to Section 3 for more details on edit 707 operations. 709 The resource definition version for a data resource is identified by 710 the revision date of the YANG module containing the YANG definition 711 for the data resource, specified in the "{+restconf}/modules" sub- 712 tree. 714 2.5.1. Encoding YANG Instance Identifiers in the Request URI 716 In YANG, data nodes are named with an absolute XPath expression, 717 defined in [XPath] , starting from the document root to the target 718 resource. In RESTCONF, URL encoded Location header expressions are 719 used instead. 721 The YANG "instance-identifier" (i-i) data type is represented in 722 RESTCONF with the path expression format defined in this section. 724 +-------+-------------------------------------------+ 725 | Name | Comments | 726 +-------+-------------------------------------------+ 727 | point | Insertion point is always a full i-i | 728 | path | Request URI path is a full or partial i-i | 729 +-------+-------------------------------------------+ 731 RESTCONF instance-identifier Type Conversion 733 The "path" component of the request URI contains the absolute path 734 expression that identifies the target resource. 736 A predictable location for a data resource is important, since 737 applications will code to the YANG data model module, which uses 738 static naming and defines an absolute path location for all data 739 nodes. 741 A RESTCONF data resource identifier is not an XPath expression. It 742 is encoded from left to right, starting with the top-level data node, 743 according to the "api-path" rule in Section 2.5.1.1. The node name 744 of each ancestor of the target resource node is encoded in order, 745 ending with the node name for the target resource. 747 If a data node in the path expression is a YANG list node, then the 748 key values for the list (if any) MUST be encoded according to the 749 following rules. 751 o The key leaf values for a data resource representing a YANG list 752 MUST be encoded using one path segment [RFC3986]. 754 o If there is only one key leaf value, the path segment is 755 constructed by having the list name followed by an "=" followed by 756 the single key leaf value. 758 o If there are multiple key leaf values, the value of each leaf 759 identified in the "key" statement is encoded in the order 760 specified in the YANG "key" statement, with a comma separating 761 them. 763 o All the components in the "key" statement MUST be encoded. 764 Partial instance identifiers are not supported. 766 o Quoted strings are supported in the key leaf values. Quoted 767 strings MUST be used to express empty strings. (example: 768 list=foo,'',baz). 770 o The "list-instance" ABNF rule defined in Section 2.5.1.1 771 represents the syntax of a list instance identifier. 773 o Resource URI values returned in Location headers for data 774 resources MUST identify the module name, even if there are no 775 conflicting local names when the resource is created. This 776 ensures the correct resource will be identified even if the server 777 loads a new module that the old client does not know about. 779 Examples: 781 container top { 782 list list1 { 783 key "key1 key2 key3"; 784 ... 785 list list2 { 786 key "key4 key5"; 787 ... 788 leaf X { type string; } 789 } 790 } 792 For the above YANG definition, URI with key leaf values will be 793 encoded as follows (line wrapped for display purposes only): 795 /restconf/data/top/list1=key1val,key2val,key3val3/ 796 list2=key4val,key5val/X 798 2.5.1.1. ABNF For Data Resource Identifiers 800 The "api-path" ABNF syntax is used to construct RESTCONF path 801 identifiers: 803 api-path = "/" | 804 ("/" api-identifier 805 0*("/" (api-identifier | list-instance ))) 807 api-identifier = [module-name ":"] identifier 809 module-name = identifier 811 list-instance = api-identifier "=" key-value ["," key-value]* 813 key-value = string 815 string = 817 ;; An identifier MUST NOT start with 818 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 819 identifier = (ALPHA / "_") 820 *(ALPHA / DIGIT / "_" / "-" / ".") 822 2.5.2. Defaults Handling 824 NETCONF has a rather complex model for handling default values for 825 leafs. RESTCONF attempts to avoid this complexity by restricting the 826 operations that can be applied to a resource. Applications that 827 require full control of defaults might consider NETCONF instead of 828 RESTCONF. 830 If the target of a GET method is a data node that represents a leaf 831 that has a default value, and the leaf has not been given a value 832 yet, the server MUST return the default value that is in use by the 833 server. 835 If the target of a GET method is a data node that represents a 836 container or list that has any child resources with default values, 837 for the child resources that have not been given value yet, the 838 server MAY return the default values that are in use by the server. 840 2.6. Operation Resource 842 An operation resource represents an protocol operation defined with 843 the YANG "rpc" statement. 845 All operation resources share the same module namespace as any top- 846 level data resources, so the name of an operation resource cannot 847 conflict with the name of a top-level data resource defined within 848 the same module. 850 If 2 different YANG modules define the same "rpc" identifier, then 851 the module name MUST be used in the request URI. For example, if 852 "module-A" and "module-B" both defined a "reset" operation, then 853 invoking the operation from "module-A" would be requested as follows: 855 POST /restconf/operations/module-A:reset HTTP/1.1 856 Server example.com 858 Any usage of an operation resource from the same module, with the 859 same name, refers to the same "rpc" statement definition. This 860 behavior can be used to design protocol operations that perform the 861 same general function on different resource types. 863 If the "rpc" statement has an "input" section, then a message body 864 MAY be sent by the client in the request, otherwise the request 865 message MUST NOT include a message body. If the "rpc" statement has 866 an "output" section, then a message body MAY be sent by the server in 867 the response. Otherwise the server MUST NOT include a message body 868 in the response message, and MUST send a "204 No Content" Status-Line 869 instead. 871 2.6.1. Encoding Operation Input Parameters 873 If the "rpc" statement has an "input" section, then the "input" node 874 is provided in the message body, corresponding to the YANG data 875 definition statements within the "input" section. 877 Example: 879 The following YANG definition is used for the examples in this 880 section. 882 rpc reboot { 883 input { 884 leaf delay { 885 units seconds; 886 type uint32; 887 default 0; 888 } 889 leaf message { type string; } 890 leaf language { type string; } 891 } 892 } 894 The client might send the following POST request message: 896 POST /restconf/operations/example-ops:reboot HTTP/1.1 897 Host: example.com 898 Content-Type: application/yang.operation+json 900 { 901 "example-ops:input" : { 902 "delay" : 600, 903 "message" : "Going down for system maintenance", 904 "language" : "en-US" 905 } 906 } 908 The server might respond: 910 HTTP/1.1 204 No Content 911 Date: Mon, 25 Apr 2012 11:01:00 GMT 912 Server: example-server 914 2.6.2. Encoding Operation Output Parameters 916 If the "rpc" statement has an "output" section, then the "output" 917 node is provided in the message body, corresponding to the YANG data 918 definition statements within the "output" section. 920 Example: 922 The following YANG definition is used for the examples in this 923 section. 925 rpc get-reboot-info { 926 output { 927 leaf reboot-time { 928 units seconds; 929 type uint32; 930 } 931 leaf message { type string; } 932 leaf language { type string; } 933 } 934 } 936 The client might send the following POST request message: 938 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 939 Host: example.com 940 Accept: application/yang.operation+json, 941 application/yang.errors+json 943 The server might respond: 945 HTTP/1.1 200 OK 946 Date: Mon, 25 Apr 2012 11:10:30 GMT 947 Server: example-server 948 Content-Type: application/yang.operation+json 950 { 951 "example-ops:output" : { 952 "reboot-time" : 30, 953 "message" : "Going down for system maintenance", 954 "language" : "en-US" 955 } 956 } 958 2.7. Schema Resource 960 If the server supports the "schema" leaf within the API then the 961 client can retrieve the YANG schema text for the associated YANG 962 module or submodule, using the GET method. First the client needs to 963 retrieve the URL for retrieving the schema. 965 The client might send the following GET request message: 967 GET /restconf/data/modules/module= 968 example-jukebox,2014-07-03/schema HTTP/1.1 969 Host: example.com 970 Accept: application/yang.data+json, 971 application/yang.errors+json 973 The server might respond: 975 HTTP/1.1 200 OK 976 Date: Mon, 25 Apr 2012 11:10:30 GMT 977 Server: example-server 978 Content-Type: application/yang.data+json 980 { 981 "schema": 982 "http://example.com/mymodules/example-jukebox/2014-07-03" 983 } 985 Next the client needs to retrieve the actual YANG schema. 987 The client might send the following GET request message: 989 GET http://example.com/mymodules/example-jukebox/2014-07-03 990 HTTP/1.1 991 Host: example.com 992 Accept: application/yang.data+json, 993 application/yang.errors+json 995 The server might respond: 997 module example-jukebox { 999 namespace "http://example.com/ns/example-jukebox"; 1000 prefix "jbox"; 1002 // rest of YANG module content deleted... 1003 } 1005 2.8. Stream Resource 1007 A "stream" resource represents a source for system generated event 1008 notifications. Each stream is created and modified by the server 1009 only. A client can retrieve a stream resource or initiate a long- 1010 poll server sent event stream, using the procedure specified in 1011 Section 5.3. 1013 A notification stream functions according to the NETCONF 1014 Notifications specification [RFC5277]. The "ietf-restconf" YANG 1015 module contains the "stream" list ("{+restconf}/streams/stream") 1016 which specifies the syntax and semantics of a stream resource. 1018 2.9. Errors Resource 1020 An "errors" resource is a collection of error information that is 1021 sent as the message body in a server response message, if an error 1022 occurs while processing a request message. 1024 The "ietf-restconf" YANG module contains the "errors" grouping which 1025 specifies the syntax and semantics of an errors resource. RESTCONF 1026 error handling behavior is defined in Section 6. 1028 3. Operations 1030 The RESTCONF protocol uses HTTP methods to identify the CRUD 1031 operation requested for a particular resource. 1033 The following table shows how the RESTCONF operations relate to 1034 NETCONF protocol operations: 1036 +----------+-------------------------------------+ 1037 | RESTCONF | NETCONF | 1038 +----------+-------------------------------------+ 1039 | OPTIONS | none | 1040 | HEAD | none | 1041 | GET | , | 1042 | POST | (operation="create") | 1043 | PUT | (operation="replace") | 1044 | PATCH | (operation="merge") | 1045 | DELETE | (operation="delete") | 1046 +----------+-------------------------------------+ 1048 Table 1: CRUD Methods in RESTCONF 1050 The NETCONF "remove" operation attribute is not supported by the HTTP 1051 DELETE method. The resource must exist or the DELETE method will 1052 fail. The PATCH method is equivalent to a "merge" operation for a 1053 plain patch. 1055 Access control mechanisms may be used to limit what operations can be 1056 used. In particular, RESTCONF is compatible with the NETCONF Access 1057 Control Model (NACM) [RFC6536], as there is a specific mapping 1058 between RESTCONF and NETCONF operations, defined in Table 1. The 1059 resource path needs to be converted internally by the server to the 1060 corresponding YANG instance-identifier. Using this information, the 1061 server can apply the NACM access control rules to RESTCONF messages. 1063 The server MUST NOT allow any operation to any resources that the 1064 client is not authorized to access. 1066 Implementation of all methods (except PATCH) are defined in 1067 [RFC2616]. This section defines the RESTCONF protocol usage for each 1068 HTTP method. 1070 3.1. OPTIONS 1072 The OPTIONS method is sent by the client to discover which methods 1073 are supported by the server for a specific resource. If supported, 1074 it SHOULD be implemented for all media types. 1076 The server SHOULD implement this method, however the same information 1077 could be extracted from the YANG modules and the RESTCONF protocol 1078 specification. 1080 If the PATCH method is supported, then the "Accept-Patch" header MUST 1081 be supported, as defined in [RFC5789]. 1083 3.2. HEAD 1085 The HEAD method is sent by the client to retrieve just the headers 1086 that would be returned for the comparable GET method, without the 1087 response body. It is supported for all resource types, except 1088 operation resources. 1090 The request MUST contain a request URI that contains at least the 1091 entry point component. The same query parameters supported by the 1092 GET method are supported by the HEAD method. 1094 The access control behavior is enforced as if the method was GET 1095 instead of HEAD. The server MUST respond the same as if the method 1096 was GET instead of HEAD, except that no response body is included. 1098 3.3. GET 1100 The GET method is sent by the client to retrieve data and meta-data 1101 for a resource. It is supported for all resource types, except 1102 operation resources. The request MUST contain a request URI that 1103 contains at least the entry point component. 1105 The server MUST NOT return any data resources for which the user does 1106 not have read privileges. If the user is not authorized to read the 1107 target resource, an error response containing a "403 Forbidden" or 1108 "404 Not Found" Status-Line is returned to the client. 1110 If the user is authorized to read some but not all of the target 1111 resource, the unauthorized content is omitted from the response 1112 message body, and the authorized content is returned to the client. 1114 Example: 1116 The client might request the response headers for a JSON 1117 representation of the "library" resource: 1119 GET /restconf/data/example-jukebox:jukebox/ 1120 library/artist=Foo%20Fighters/album HTTP/1.1 1121 Host: example.com 1122 Accept: application/yang.data+json, 1123 application/yang.errors+json 1125 The server might respond: 1127 HTTP/1.1 200 OK 1128 Date: Mon, 23 Apr 2012 17:02:40 GMT 1129 Server: example-server 1130 Content-Type: application/yang.data+json 1131 Cache-Control: no-cache 1132 Pragma: no-cache 1133 ETag: a74eefc993a2b 1134 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1136 { 1137 "album" : [ 1138 { 1139 "name" : "Wasting Light", 1140 "genre" : "example-jukebox:alternative", 1141 "year" : 2011 1142 } 1143 ] 1144 } 1146 3.4. POST 1148 The POST method is sent by the client to create a data resource or 1149 invoke an operation resource. The server uses the target resource 1150 media type to determine how to process the request. 1152 +-----------+------------------------------------------------+ 1153 | Type | Description | 1154 +-----------+------------------------------------------------+ 1155 | Datastore | Create a top-level configuration data resource | 1156 | Data | Create a configuration data child resource | 1157 | Operation | Invoke a protocol operation | 1158 +-----------+------------------------------------------------+ 1160 Resource Types that Support POST 1162 3.4.1. Create Resource Mode 1164 If the target resource type is a datastore or data resource, then the 1165 POST is treated as a request to create a resource or child resource. 1166 The message body is expected to contain the content of a child 1167 resource to create within the parent (target resource). 1169 The "insert" and "point" query parameters are supported by the POST 1170 method for datastore and data resource types, as specified in the 1171 YANG definition in Section 7. 1173 If the POST method succeeds, a "201 Created" Status-Line is returned 1174 and there is no response message body. A "Location" header 1175 identifying the child resource that was created MUST be present in 1176 the response in this case. 1178 If the user is not authorized to create the target resource, an error 1179 response containing a "403 Forbidden" or "404 Not Found" Status-Line 1180 is returned to the client. All other error responses are handled 1181 according to the procedures defined in Section 6. 1183 Example: 1185 To create a new "jukebox" resource, the client might send: 1187 POST /restconf/data HTTP/1.1 1188 Host: example.com 1189 Content-Type: application/yang.data+json 1191 { "example-jukebox:jukebox" : [null] } 1193 If the resource is created, the server might respond as follows: 1195 HTTP/1.1 201 Created 1196 Date: Mon, 23 Apr 2012 17:01:00 GMT 1197 Server: example-server 1198 Location: http://example.com/restconf/data/example-jukebox:jukebox 1199 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 1200 ETag: b3a3e673be2 1202 Refer to Appendix D.2.1 for more resource creation examples. 1204 3.4.2. Invoke Operation Mode 1206 If the target resource type is an operation resource, then the POST 1207 method is treated as a request to invoke that operation. The message 1208 body (if any) is processed as the operation input parameters. Refer 1209 to Section 2.6 for details on operation resources. 1211 If the POST request succeeds, a "200 OK" Status-Line is returned if 1212 there is a response message body, and a "204 No Content" Status-Line 1213 is returned if there is no response message body. 1215 If the user is not authorized to invoke the target operation, an 1216 error response containing a "403 Forbidden" or "404 Not Found" 1217 Status-Line is returned to the client. All other error responses are 1218 handled according to the procedures defined in Section 6. 1220 Example: 1222 In this example, the client is invoking the "play" operation defined 1223 in the "example-jukebox" YANG module. 1225 A client might send a "play" request as follows: 1227 POST /restconf/operations/example-jukebox:play HTTP/1.1 1228 Host: example.com 1229 Content-Type: application/yang.operation+json 1231 { 1232 "example-jukebox:input" : { 1233 "playlist" : "Foo-One", 1234 "song-number" : 2 1235 } 1236 } 1238 The server might respond: 1240 HTTP/1.1 204 No Content 1241 Date: Mon, 23 Apr 2012 17:50:00 GMT 1242 Server: example-server 1244 3.5. PUT 1246 The PUT method is sent by the client to create or replace the target 1247 resource. 1249 The only target resource media type that supports PUT is the data 1250 resource. The message body is expected to contain the content used 1251 to create or replace the target resource. 1253 The "insert" (Section 3.8.5) and "point" (Section 3.8.6) query 1254 parameters are supported by the PUT method for data resources. 1256 Consistent with [RFC2616], if the PUT request creates a new resource, 1257 a "201 Created" Status-Line is returned. If an existing resource is 1258 modified, either "200 OK" or "204 No Content" are returned. 1260 If the user is not authorized to create or replace the target 1261 resource an error response containing a "403 Forbidden" or "404 Not 1262 Found" Status-Line is returned to the client. All other error 1263 responses are handled according to the procedures defined in 1264 Section 6. 1266 Example: 1268 An "album" child resource defined in the "example-jukebox" YANG 1269 module is replaced or created if it does not already exist. 1271 To replace the "album" resource contents, the client might send as 1272 follows. Note that the request URI header line is wrapped for 1273 display purposes only: 1275 PUT /restconf/data/example-jukebox:jukebox/ 1276 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1277 Host: example.com 1278 Content-Type: application/yang.data+json 1280 { 1281 "example-jukebox:album" : { 1282 "name" : "Wasting Light", 1283 "genre" : "example-jukebox:alternative", 1284 "year" : 2011 1285 } 1286 } 1288 If the resource is updated, the server might respond: 1290 HTTP/1.1 204 No Content 1291 Date: Mon, 23 Apr 2012 17:04:00 GMT 1292 Server: example-server 1293 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 1294 ETag: b27480aeda4c 1296 3.6. PATCH 1298 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 1299 an extensible framework for resource patching mechanisms. It is 1300 optional to implement by the server. Each patch type needs a unique 1301 media type. Zero or more PATCH media types MAY be supported by the 1302 server. 1304 A plain patch is used to create or update a child resource within the 1305 target resource. If the target resource instance does not exist, the 1306 server MUST NOT create it. 1308 If the PATCH request succeeds, a "200 OK" Status-Line is returned if 1309 there is a message body, and "204 No Content" is returned if no 1310 response message body is sent. 1312 If the user is not authorized to alter the target resource an error 1313 response containing a "403 Forbidden" or "404 Not Found" Status-Line 1314 is returned to the client. All other error responses are handled 1315 according to the procedures defined in Section 6. 1317 Example: 1319 To replace just the "year" field in the "album" resource (instead of 1320 replacing the entire resource with the PUT method), the client might 1321 send a plain patch as follows. Note that the request URI header line 1322 is wrapped for display purposes only: 1324 PATCH /restconf/data/example-jukebox:jukebox/ 1325 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1326 Host: example.com 1327 Content-Type: application/yang.data+json 1329 { 1330 "example-jukebox:album" : { 1331 "genre" : "example-jukebox:rock", 1332 "year" : 2011 1333 } 1334 } 1336 If the field is updated, the server might respond: 1338 HTTP/1.1 204 No Content 1339 Date: Mon, 23 Apr 2012 17:49:30 GMT 1340 Server: example-server 1341 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 1342 ETag: b2788923da4c 1344 The XML encoding for the same request might be: 1346 PATCH /restconf/data/example-jukebox:jukebox/ 1347 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1348 Host: example.com 1349 If-Match: b8389233a4c 1350 Content-Type: application/yang.data+xml 1352 1353 example-jukebox:rock 1354 2011 1355 1357 3.7. DELETE 1359 The DELETE method is used to delete the target resource. If the 1360 DELETE request succeeds, a "204 No Content" Status-Line is returned, 1361 and there is no response message body. 1363 If the user is not authorized to delete the target resource then an 1364 error response containing a "403 Forbidden" or "404 Not Found" 1365 Status-Line is returned to the client. All other error responses are 1366 handled according to the procedures defined in Section 6. 1368 Example: 1370 To delete a resource such as the "album" resource, the client might 1371 send: 1373 DELETE /restconf/data/example-jukebox:jukebox/ 1374 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1375 Host: example.com 1377 If the resource is deleted, the server might respond: 1379 HTTP/1.1 204 No Content 1380 Date: Mon, 23 Apr 2012 17:49:40 GMT 1381 Server: example-server 1383 3.8. Query Parameters 1385 Each RESTCONF operation allows zero or more query parameters to be 1386 present in the request URI. The specific parameters that are allowed 1387 depends on the resource type, and sometimes the specific target 1388 resource used, in the request. 1390 +------------+----------+-------------------------------------------+ 1391 | Name | Methods | Description | 1392 +------------+----------+-------------------------------------------+ 1393 | content | GET | Select config and/or non-config data | 1394 | | | resources | 1395 | depth | GET | Request limited sub-tree depth in the | 1396 | | | reply content | 1397 | filter | GET | Boolean notification filter for event- | 1398 | | | stream resources | 1399 | insert | POST, | Insertion mode for user-ordered data | 1400 | | PUT | resources | 1401 | point | POST, | Insertion point for user-ordered data | 1402 | | PUT | resources | 1403 | select | GET | Request a subset of the target resource | 1404 | | | contents | 1405 | start-time | GET | Replay buffer start time for event-stream | 1406 | | | resources | 1407 | stop-time | GET | Replay buffer stop time for event-stream | 1408 | | | resources | 1409 +------------+----------+-------------------------------------------+ 1411 RESTCONF Query Parameters 1413 Query parameters can be given in any order. Each parameter can 1414 appear at most once in a request URI. A default value may apply if 1415 the parameter is missing. 1417 Refer to Appendix D.3 for examples of query parameter usage. 1419 If vendors define additional query parameters, they SHOULD use a 1420 prefix (such as the enterprise or organization name) for query 1421 parameter names in order to avoid collisions with other parameters. 1423 3.8.1. Query Parameter URIs 1425 A new set of NETCONF Capability URNs are defined to identify the 1426 specific query parameters supported by the server. 1428 +---------+-------------------------------------------------+ 1429 | Name | URI | 1430 +---------+-------------------------------------------------+ 1431 | content | urn:ietf:params:restconf:capability:content:1.0 | 1432 | depth | urn:ietf:params:restconf:capability:depth:1.0 | 1433 | filter | urn:ietf:params:restconf:capability:filter:1.0 | 1434 | insert | urn:ietf:params:restconf:capability:insert:1.0 | 1435 | select | urn:ietf:params:restconf:capability:select:1.0 | 1436 | replay | urn:ietf:params:restconf:capability:replay:1.0 | 1437 +---------+-------------------------------------------------+ 1439 RESTCONF Query Parameter URIs 1441 3.8.2. The "content" Query Parameter 1443 The "content" parameter controls how descendant nodes of the 1444 requested data nodes will be processed in the reply. 1446 The allowed values are: 1448 +-----------+-----------------------------------------------------+ 1449 | Value | Description | 1450 +-----------+-----------------------------------------------------+ 1451 | config | Return only configuration descendant data nodes | 1452 | nonconfig | Return only non-configuration descendant data nodes | 1453 | all | Return all descendant data nodes | 1454 +-----------+-----------------------------------------------------+ 1456 This parameter is only allowed for GET methods on datastore and data 1457 resources. A 400 Bad Request error is returned if used for other 1458 methods or resource types. 1460 The default value is determined by the "config" statement value of 1461 the requested data nodes. If the "config" value is "false", then the 1462 default for the "content" parameter is "nonconfig". If "config" is 1463 "true" then the default for the "content" parameter is "config". 1465 If this query parameter is supported by the server, then the 1466 "content" query parameter URI MUST be listed in the "capability" 1467 leaf-list in Section 8.3. 1469 3.8.3. The "depth" Query Parameter 1471 The "depth" parameter is used to specify the number of nest levels 1472 returned in a response for a GET method. The first nest-level 1473 consists of the requested data node itself. Any child nodes which 1474 are contained within a parent node have a depth value that is 1 1475 greater than its parent. 1477 The value of the "depth" parameter is either an integer between 1 and 1478 65535, or the string "unbounded". "unbounded" is the default. 1480 This parameter is only allowed for GET methods on API, datastore, and 1481 data resources. A 400 Bad Request error is returned if it used for 1482 other methods or resource types. 1484 By default, the server will include all sub-resources within a 1485 retrieved resource, which have the same resource type as the 1486 requested resource. Only one level of sub-resources with a different 1487 media type than the target resource will be returned. 1489 If this query parameter is supported by the server, then the "depth" 1490 query parameter URI MUST be listed in the "capability" leaf-list in 1491 Section 8.3. 1493 3.8.4. The "select" Query Parameter 1495 The "select" query parameter is used to optionally identify data 1496 nodes within the target resource to be retrieved in a GET method. 1497 The client can use this parameter to retrieve a subset of all nodes 1498 in a resource. 1500 A value of the "select" query parameter matches the following rule: 1502 select-expr = path '(' select-expr / '*' ')' / 1503 path ';' select-expr / 1504 path 1505 path = api-identifier [ '/' path ] 1507 "api-identifier" is defined in Section 2.5.1.1. 1509 ";" is used to select multiple nodes. For example, to retrieve only 1510 the "genre" and "year" of an album, use: "select=genre;year". 1512 Parentheses are used to specify sub-selectors of a node. For 1513 example, to retrieve only the "label" and "catalogue-number" of an 1514 album, use: "select=admin(label;catalogue-number)". 1516 "/" is used in a path to retrieve a child node of a node. For 1517 example, to retrieve only the "label" of an album, use: 1518 "select=admin/label". 1520 This parameter is only allowed for GET methods on api, datastore, and 1521 data resources. A 400 Bad Request error is returned if used for 1522 other methods or resource types. 1524 If this query parameter is supported by the server, then the "select" 1525 query parameter URI MUST be listed in the "capability" leaf-list in 1526 Section 8.3. 1528 3.8.5. The "insert" Query Parameter 1530 The "insert" parameter is used to specify how a resource should be 1531 inserted within a user-ordered list. 1533 The allowed values are: 1535 +--------+----------------------------------------------------------+ 1536 | Value | Description | 1537 +--------+----------------------------------------------------------+ 1538 | first | Insert the new data as the new first entry. | 1539 | last | Insert the new data as the new last entry. | 1540 | before | Insert the new data before the insertion point, as | 1541 | | specified by the value of the "point" parameter. | 1542 | after | Insert the new data after the insertion point, as | 1543 | | specified by the value of the "point" parameter. | 1544 +--------+----------------------------------------------------------+ 1546 The default value is "last". 1548 This parameter is only supported for the POST and PUT methods. It is 1549 also only supported if the target resource is a data resource, and 1550 that data represents a YANG list or leaf-list that is ordered by the 1551 user. 1553 If the values "before" or "after" are used, then a "point" query 1554 parameter for the insertion parameter MUST also be present, or a 400 1555 Bad Request error is returned. 1557 If this query parameter is supported by the server, then the "insert" 1558 query parameter URI MUST be listed in the "capability" leaf-list in 1559 Section 8.3. The "point" query parameter MUST also be supported by 1560 the server. 1562 3.8.6. The "point" Query Parameter 1564 The "point" parameter is used to specify the insertion point for a 1565 data resource that is being created or moved within a user ordered 1566 list or leaf-list. 1568 The value of the "point" parameter is of type 1569 "data-resource-identifier", defined in the "ietf-restconf" YANG 1570 module Section 7. 1572 This parameter is only supported for the POST and PUT methods. It is 1573 also only supported if the target resource is a data resource, and 1574 that data represents a YANG list or leaf-list that is ordered by the 1575 user. 1577 If the "insert" query parameter is not present, or has a value other 1578 than "before" or "after", then a 400 Bad Request error is returned. 1580 This parameter contains the instance identifier of the resource to be 1581 used as the insertion point for a POST or PUT method. 1583 If the server includes the "insert" query parameter URI in the 1584 "capability" leaf-list in Section 8.3, then the "point" query 1585 parameter MUST be supported. 1587 3.8.7. The "filter" Query Parameter 1589 The "filter" parameter is used to indicate which subset of all 1590 possible events are of interest. If not present, all events not 1591 precluded by other parameters will be sent. 1593 This parameter is only allowed for GET methods on a text/event-stream 1594 data resource. A 400 Bad Request error is returned if used for other 1595 methods or resource types. 1597 The format of this parameter is an XPath 1.0 expression, and is 1598 evaluated in the following context: 1600 o The set of namespace declarations is the set of prefix and 1601 namespace pairs for all supported YANG modules, where the prefix 1602 is the YANG module name, and the namespace is as defined by the 1603 "namespace" statement in the YANG module. 1605 o The function library is the core function library defined in XPath 1606 1.0. 1608 o The set of variable bindings is empty. 1610 o The context node is the root node. 1612 The filter is used as defined in [RFC5277], section 3.6. If the 1613 boolean result of the expression is true when applied to the 1614 conceptual "notification" document root, then the notification event 1615 is delivered to the client. 1617 If this query parameter is supported by the server, then the "filter" 1618 query parameter URI MUST be listed in the "capability" leaf-list in 1619 Section 8.3. 1621 3.8.8. The "start-time" Query Parameter 1623 The "start-time" parameter is used to trigger the notification replay 1624 feature and indicate that the replay should start at the time 1625 specified. If the stream does not support replay, per the 1626 "replay-support" attribute returned by the /restconf/streams 1627 resource, then the server MUST return the HTTP error code 400 Bad 1628 Request. 1630 The value of the "start-time" parameter is of type "date-and-time", 1631 defined in the "ietf-yang" YANG module [RFC6991]. 1633 This parameter is only allowed for GET methods on a text/event-stream 1634 data resource. A 400 Bad Request error is returned if used for other 1635 methods or resource types. 1637 If this parameter is not present, then a replay subscription is not 1638 being requested. It is not valid to specify start times that are 1639 later than the current time. If the value specified is earlier than 1640 the log can support, the replay will begin with the earliest 1641 available notification. 1643 If this query parameter is supported by the server, then the "replay" 1644 query parameter URI MUST be listed in the "capability" leaf-list in 1645 Section 8.3. The "stop-time" query parameter MUST also be supported 1646 by the server. 1648 If the "replay-support" leaf is present in the "stream" entry 1649 (defined in Section 8.3) then the server MUST support the 1650 "start-time" and "stop-time" query parameters for that stream. 1652 3.8.9. The "stop-time" Query Parameter 1654 The "stop-time" parameter is used with the replay feature to indicate 1655 the newest notifications of interest. This parameter MUST be used 1656 with and have a value later than the "start-time" parameter. 1658 The value of the "stop-time" parameter is of type "date-and-time", 1659 defined in the "ietf-yang" YANG module [RFC6991]. 1661 This parameter is only allowed for GET methods on a text/event-stream 1662 data resource. A 400 Bad Request error is returned if used for other 1663 methods or resource types. 1665 If this parameter is not present, the notifications will continue 1666 until the subscription is terminated. Values in the future are 1667 valid. 1669 If this query parameter is supported by the server, then the "replay" 1670 query parameter URI MUST be listed in the "capability" leaf-list in 1671 Section 8.3. The "start-time" query parameter MUST also be supported 1672 by the server. 1674 If the "replay-support" leaf is present in the "stream" entry 1675 (defined in Section 8.3) then the server MUST support the 1676 "start-time" and "stop-time" query parameters for that stream. 1678 4. Messages 1680 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 1681 message corresponds to a single protocol method. Most messages can 1682 perform a single task on a single resource, such as retrieving a 1683 resource or editing a resource. The exception is the PATCH method, 1684 which allows multiple datastore edits within a single message. 1686 4.1. Request URI Structure 1688 Resources are represented with URIs following the structure for 1689 generic URIs in [RFC3986]. 1691 A RESTCONF operation is derived from the HTTP method and the request 1692 URI, using the following conceptual fields: 1694 //?# 1696 ^ ^ ^ ^ ^ 1697 | | | | | 1698 method entry resource query fragment 1700 M M O O I 1702 M=mandatory, O=optional, I=ignored 1704 replaced by client with real values 1706 o method: the HTTP method identifying the RESTCONF operation 1707 requested by the client, to act upon the target resource specified 1708 in the request URI. RESTCONF operation details are described in 1709 Section 3. 1711 o entry: the root of the RESTCONF API configured on this HTTP 1712 server, discovered by getting the ".well-known/host-meta" 1713 resource, as described in Section 4.2. All of the examples in 1714 this document assume "/restconf" as the discovered RESTCONF API 1715 root path. The URI template [RFC6570] syntax "{+restconf}" is 1716 used to refer to the entry point outside of an example. 1718 o resource: the path expression identifying the resource that is 1719 being accessed by the operation. If this field is not present, 1720 then the target resource is the API itself, represented by the 1721 media type "application/yang.api". 1723 o query: the set of parameters associated with the RESTCONF message. 1724 These have the familiar form of "name=value" pairs. All query 1725 parameters are optional to implement by the server and optional to 1726 use by the client. Each query parameter is identified by a URI. 1727 The server MUST list the query parameter URIs it supports in the 1728 "capabilities" list defined in Section 8.3. 1730 There is a specific set of parameters defined, although the server 1731 MAY choose to support query parameters not defined in this document. 1732 The contents of the any query parameter value MUST be encoded 1733 according to [RFC2396], section 3.4. Any reserved characters MUST be 1734 encoded with escape sequences, according to [RFC2396], section 2.4. 1736 o fragment: This field is not used by the RESTCONF protocol. 1738 When new resources are created by the client, a "Location" header is 1739 returned, which identifies the path of the newly created resource. 1740 The client MUST use this exact path identifier to access the resource 1741 once it has been created. 1743 The "target" of an operation is a resource. The "path" field in the 1744 request URI represents the target resource for the operation. 1746 4.2. RESTCONF Path Resolution 1748 In line the best practices defined by [get-off-my-lawn], RESTCONF 1749 enables deployments to specify where the RESTCONF API is located. 1750 When first connecting to a RESTCONF server, a RESTCONF client MUST 1751 determine the root of the RESTCONF API. The client discovers this by 1752 getting the "/.well-known/host-meta" resource ([RFC6415]) and using 1753 the element containing the "restconf" attribute : 1755 Request 1756 ------- 1757 GET /.well-known/host-meta users HTTP/1.1 1758 Host: example.com 1759 Accept: application/xrd+xml 1761 Response 1762 -------- 1763 HTTP/1.1 200 OK 1764 Content-Type: application/xrd+xml 1765 Content-Length: nnn 1766 1767 1768 1770 Once discovering the RESTCONF API root, the client MUST prepend it to 1771 any subsequent request to a RESTCONF resource. For instance, using 1772 the "/restconf" path discovered above, the client can now determine 1773 the operations supported by the the server: 1775 Request 1776 ------- 1777 GET /restconf/operations HTTP/1.1 1778 Host: example.com 1779 Accept: application/yang.api+json, 1780 application/yang.errors+json 1782 Response 1783 -------- 1784 HTTP/1.1 200 OK 1785 Date: Mon, 23 Apr 2012 17:01:00 GMT 1786 Server: example-server 1787 Cache-Control: no-cache 1788 Pragma: no-cache 1789 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 1790 Content-Type: application/yang.api+json 1792 { "operations" : { "play" : [ null ] } } 1794 4.3. Message Headers 1796 There are several HTTP header lines utilized in RESTCONF messages. 1797 Messages are not limited to the HTTP headers listed in this section. 1799 HTTP defines which header lines are required for particular 1800 circumstances. Refer to each operation definition section in 1801 Section 3 for examples on how particular headers are used. 1803 There are some request headers that are used within RESTCONF, usually 1804 applied to data resources. The following tables summarize the 1805 headers most relevant in RESTCONF message requests: 1807 +---------------------+---------------------------------------------+ 1808 | Name | Description | 1809 +---------------------+---------------------------------------------+ 1810 | Accept | Response Content-Types that are acceptable | 1811 | Content-Type | The media type of the request body | 1812 | Host | The host address of the server | 1813 | If-Match | Only perform the action if the entity | 1814 | | matches ETag | 1815 | If-Modified-Since | Only perform the action if modified since | 1816 | | time | 1817 | If-Unmodified-Since | Only perform the action if un-modified | 1818 | | since time | 1819 +---------------------+---------------------------------------------+ 1821 RESTCONF Request Headers 1823 The following tables summarize the headers most relevant in RESTCONF 1824 message responses: 1826 +---------------+---------------------------------------------------+ 1827 | Name | Description | 1828 +---------------+---------------------------------------------------+ 1829 | Allow | Valid actions when 405 error returned | 1830 | Cache-Control | The cache control parameters for the response | 1831 | Content-Type | The media type of the response body | 1832 | Date | The date and time the message was sent | 1833 | ETag | An identifier for a specific version of a | 1834 | | resource | 1835 | Last-Modified | The last modified date and time of a resource | 1836 | Location | The resource identifier for a newly created | 1837 | | resource | 1838 +---------------+---------------------------------------------------+ 1840 RESTCONF Response Headers 1842 4.4. Message Encoding 1844 RESTCONF messages are encoded in HTTP according to RFC 2616. The 1845 "utf-8" character set is used for all messages. RESTCONF message 1846 content is sent in the HTTP message body. 1848 Content is encoded in either JSON or XML format. 1850 XML encoding rules for data nodes are defined in [RFC6020]. The same 1851 encoding rules are used for all XML content. 1853 JSON encoding rules are defined in [I-D.lhotka-netmod-json]. This 1854 encoding is valid JSON, but also has special encoding rules to 1855 identify module namespaces and provide consistent type processing of 1856 YANG data. 1858 Request input content encoding format is identified with the Content- 1859 Type header. This field MUST be present if a message body is sent by 1860 the client. 1862 Response output content encoding format is identified with the Accept 1863 header in the request, or if is not specified, the request input 1864 encoding format is used. If there was no request input, then the 1865 default output encoding is XML. File extensions encoded in the 1866 request are not used to identify format encoding. 1868 4.5. RESTCONF Meta-Data 1870 The RESTCONF protocol needs to retrieve the same meta-data that is 1871 used in the NETCONF protocol. Information about default leafs, last- 1872 modified timestamps, etc. are commonly used to annotate 1873 representations of the datastore contents. This meta-data is not 1874 defined in the YANG schema because it applies to the datastore, and 1875 is common across all data nodes. 1877 This information is encoded as attributes in XML. JSON encoding of 1878 meta-data is defined in [I-D.lhotka-netmod-json]. 1880 4.6. Return Status 1882 Each message represents some sort of resource access. An HTTP 1883 "Status-Line" header line is returned for each request. If a 4xx or 1884 5xx range status code is returned in the Status-Line, then the error 1885 information will be returned in the response, according to the format 1886 defined in Section 6.1. 1888 4.7. Message Caching 1890 Since the datastore contents change at unpredictable times, responses 1891 from a RESTCONF server generally SHOULD NOT be cached. 1893 The server SHOULD include a "Cache-Control" header in every response 1894 that specifies whether the response should be cached. A "Pragma" 1895 header specifying "no-cache" MAY also be sent in case the 1896 "Cache-Control" header is not supported. 1898 Instead of using HTTP caching, the client SHOULD track the "ETag" 1899 and/or "Last-Modified" headers returned by the server for the 1900 datastore resource (or data resource if the server supports it). A 1901 retrieval request for a resource can include the "If-None-Match" and/ 1902 or "If-Modified-Since" headers, which will cause the server to return 1903 a "304 Not Modified" Status-Line if the resource has not changed. 1904 The client MAY use the HEAD method to retrieve just the message 1905 headers, which SHOULD include the "ETag" and "Last-Modified" headers, 1906 if this meta-data is maintained for the target resource. 1908 5. Notifications 1910 The RESTCONF protocol supports YANG-defined event notifications. The 1911 solution preserves aspects of NETCONF Event Notifications [RFC5277] 1912 while utilizing the Server-Sent Events [wd-eventsource] transport 1913 strategy. 1915 5.1. Server Support 1917 A RESTCONF server is not required to support RESTCONF notifications. 1918 Clients may determine if a server supports RESTCONF notifications by 1919 using the HTTP operation OPTIONS, HEAD, or GET on the 1920 "{+restconf}/streams" resource described below. The server does not 1921 support RESTCONF notifications if an HTTP error code is returned 1922 (e.g., 404 Not Found). 1924 5.2. Event Streams 1926 A RESTCONF server that supports notifications will populate a stream 1927 resource for each notification delivery service access point. A 1928 RESTCONF client can retrieve the list of supported event streams from 1929 a RESTCONF server using the GET operation on the "restconf-state/ 1930 streams" data resource defined in Section 8.3. 1932 The "restconf-state/streams" container definition in the 1933 "ietf-restconf-monitoring" module (defined in Section 8.3) is used to 1934 specify the structure and syntax of the conceptual child resources 1935 within the "streams" resource. 1937 For example: 1939 The client might send the following request: 1941 GET /restconf/data/restconf-state/streams HTTP/1.1 1942 Host: example.com 1943 Accept: application/yang.data+xml, 1944 application/yang.errors+xml 1946 The server might send the following response: 1948 HTTP/1.1 200 OK 1949 Content-Type: application/yang.api+xml 1950 1952 1953 NETCONF 1954 default NETCONF event stream 1955 1956 true 1957 1958 2007-07-08T00:00:00Z 1959 1960 http://example.com/streams/NETCONF 1961 1962 1963 SNMP 1964 SNMP notifications 1965 false 1966 http://example.com/streams/SNMP 1967 1968 1969 syslog-critical 1970 Critical and higher severity 1971 1972 true 1973 1974 2007-07-01T00:00:00Z 1975 1976 http://example.com/streams/syslog-critical 1977 1978 1980 5.3. Subscribing to Receive Notifications 1982 RESTCONF clients can determine the URL for the subscription resource 1983 (to receive notifications) by sending an HTTP GET request for the 1984 "{+restconf}/streams/stream//events" data resource. 1986 The value returned by the server can be used for the actual 1987 notification subscription. 1989 The client will send an HTTP GET request for the URL returned by the 1990 server with the "Accept" type "text/event-stream". 1992 The server will treat the connection as an event stream, using the 1993 Server Sent Events [wd-eventsource] transport strategy. 1995 The server MAY support query parameters for a GET method on this 1996 resource. These parameters are specific to each notification stream. 1998 For example: 2000 The client might send the following request: 2002 GET /restconf/data/restconf-state/streams/stream=NETCONF/events 2003 HTTP/1.1 2004 Host: example.com 2005 Accept: application/yang.data+xml, 2006 application/yang.errors+xml 2008 The server might send the following response: 2010 HTTP/1.1 200 OK 2011 Content-Type: application/yang.api+xml 2013 2015 http://example.com/streams/NETCONF 2016 2018 The RESTCONF client can then use this URL value to start monitoring 2019 the event stream: 2021 GET /streams/NETCONF HTTP/1.1 2022 Host: example.com 2023 Accept: text/event-stream 2024 Cache-Control: no-cache 2025 Connection: keep-alive 2027 A RESTCONF client MAY request the server compress the events using 2028 the HTTP header field "Accept-Encoding". For instance: 2030 GET /streams/NETCONF HTTP/1.1 2031 Host: example.com 2032 Accept: text/event-stream 2033 Cache-Control: no-cache 2034 Connection: keep-alive 2035 Accept-Encoding: gzip, deflate 2037 5.3.1. NETCONF Event Stream 2039 The server SHOULD support the "NETCONF" notification stream defined 2040 in [RFC5277]. For this stream, RESTCONF notification subscription 2041 requests MAY specify parameters indicating the events it wishes to 2042 receive. These query parameters are optional to implement, and only 2043 available if the server supports them. 2045 +------------+-------------------------+ 2046 | Name | Description | 2047 +------------+-------------------------+ 2048 | start-time | replay event start time | 2049 | stop-time | replay event stop time | 2050 | filter | boolean content filter | 2051 +------------+-------------------------+ 2053 NETCONF Stream Query Parameters 2055 The semantics and syntax for these query parameters are defined in 2056 the "query-parameters" YANG grouping in Section 7. The YANG encoding 2057 MUST be converted to URL-encoded string for use in the request URI. 2059 Refer to Appendix D.3.6 for filter parameter examples. 2061 5.4. Receiving Event Notifications 2063 RESTCONF notifications are encoded according to the definition of the 2064 event stream. The NETCONF stream defined in [RFC5277] is encoded in 2065 XML format. 2067 The structure of the event data is based on the "notification" 2068 element definition in section 4 of [RFC5277]. It MUST conform to the 2069 "notification" YANG container definition in Section 7. 2071 An example SSE notification encoded using XML: 2073 data: 2075 data: 2013-12-21T00:01:00Z 2076 data: 2077 data: fault 2078 data: 2079 data: Ethernet0 2080 data: 2081 data: major 2082 data: 2083 data: 2085 Since XML is not whitespace sensitive, the above message can be 2086 encoded onto a single line. 2088 For example: ('\' line wrapping added for formatting only) 2089 data: 2013-12-21T00:01:00ZfaultEthernet0maj\ 2093 or 2095 The SSE specifications supports the following additional fields: 2096 event, id and retry. A RESTCONF server MAY send the "retry" field 2097 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 2098 SHOULD NOT send the "event" or "id" fields, as there are no 2099 meaningful values that could be used for them that would not be 2100 redundant to the contents of the notification itself. RESTCONF 2101 servers that do not send the "id" field also do not need to support 2102 the HTTP header "Last-Event-Id". RESTCONF servers that do send the 2103 "id" field MUST still support the "startTime" query parameter as the 2104 preferred means for a client to specify where to restart the event 2105 stream. 2107 6. Error Reporting 2109 HTTP Status-Lines are used to report success or failure for RESTCONF 2110 operations. The element returned in NETCONF error 2111 responses contains some useful information. This error information 2112 is adapted for use in RESTCONF, and error information is returned for 2113 "4xx" class of status codes. 2115 The following table summarizes the return status codes used 2116 specifically by RESTCONF operations: 2118 +---------------------------+---------------------------------------+ 2119 | Status-Line | Description | 2120 +---------------------------+---------------------------------------+ 2121 | 100 Continue | POST accepted, 201 should follow | 2122 | 200 OK | Success with response body | 2123 | 201 Created | POST to create a resource success | 2124 | 202 Accepted | POST to create a resource accepted | 2125 | 204 No Content | Success without response body | 2126 | 304 Not Modified | Conditional operation not done | 2127 | 400 Bad Request | Invalid request message | 2128 | 403 Forbidden | Access to resource denied | 2129 | 404 Not Found | Resource target or resource node not | 2130 | | found | 2131 | 405 Method Not Allowed | Method not allowed for target | 2132 | | resource | 2133 | 409 Conflict | Resource or lock in use | 2134 | 412 Precondition Failed | Conditional method is false | 2135 | 413 Request Entity Too | too-big error | 2136 | Large | | 2137 | 414 Request-URI Too Large | too-big error | 2138 | 415 Unsupported Media | non RESTCONF media type | 2139 | Type | | 2140 | 500 Internal Server Error | operation-failed | 2141 | 501 Not Implemented | unknown-operation | 2142 | 503 Service Unavailable | Recoverable server error | 2143 +---------------------------+---------------------------------------+ 2145 HTTP Status Codes used in RESTCONF 2147 Since an operation resource is defined with a YANG "rpc" statement, a 2148 mapping between the NETCONF value and the HTTP status 2149 code is needed. The specific error condition and response code to 2150 use are data-model specific and might be contained in the YANG 2151 "description" statement for the "rpc" statement. 2153 +-------------------------+-------------+ 2154 | | status code | 2155 +-------------------------+-------------+ 2156 | in-use | 409 | 2157 | invalid-value | 400 | 2158 | too-big | 413 | 2159 | missing-attribute | 400 | 2160 | bad-attribute | 400 | 2161 | unknown-attribute | 400 | 2162 | bad-element | 400 | 2163 | unknown-element | 400 | 2164 | unknown-namespace | 400 | 2165 | access-denied | 403 | 2166 | lock-denied | 409 | 2167 | resource-denied | 409 | 2168 | rollback-failed | 500 | 2169 | data-exists | 409 | 2170 | data-missing | 409 | 2171 | operation-not-supported | 501 | 2172 | operation-failed | 500 | 2173 | partial-operation | 500 | 2174 | malformed-message | 400 | 2175 +-------------------------+-------------+ 2177 Mapping from error-tag to status code 2179 6.1. Error Response Message 2181 When an error occurs for a request message on a data resource or an 2182 operation resource, and a "4xx" class of status codes (except for 2183 status code "403 Forbidden"), then the server SHOULD send a response 2184 body containing the information described by the "errors" container 2185 definition within the YANG module Section 7. The Content-Type of 2186 this response message MUST be application/yang.errors. 2188 YANG Tree Diagram for Data: 2190 +--ro errors 2191 +--ro error 2192 +--ro error-type enumeration 2193 +--ro error-tag string 2194 +--ro error-app-tag? string 2195 +--ro (error-node)? 2196 | +--:(error-path) 2197 | | +--ro error-path? instance-identifier 2198 | +--:(error-urlpath) 2199 | +--ro error-urlpath? data-resource-identifier 2200 +--ro error-message? string 2201 +--ro error-info 2203 The semantics and syntax for RESTCONF error messages are defined in 2204 the "errors" YANG grouping in Section 7. 2206 Examples: 2208 The following example shows an error returned for an "lock-denied" 2209 error on a datastore resource. 2211 POST /restconf/operations/example-ops:lock-datastore HTTP/1.1 2212 Host: example.com 2214 The server might respond: 2216 HTTP/1.1 409 Conflict 2217 Date: Mon, 23 Apr 2012 17:11:00 GMT 2218 Server: example-server 2219 Content-Type: application/yang.errors+json 2221 { 2222 "ietf-restconf:errors": { 2223 "error": { 2224 "error-type": "protocol", 2225 "error-tag": "lock-denied", 2226 "error-message": "Lock failed, lock already held" 2227 } 2228 } 2229 } 2231 The following example shows an error returned for a "data-exists" 2232 error on a data resource. The "jukebox" resource already exists so 2233 it cannot be created. 2235 The client might send: 2237 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 2238 Host: example.com 2240 The server might respond: 2242 HTTP/1.1 409 Conflict 2243 Date: Mon, 23 Apr 2012 17:11:00 GMT 2244 Server: example-server 2245 Content-Type: application/yang.errors+json 2247 { 2248 "ietf-restconf:errors": { 2249 "error": { 2250 "error-type": "protocol", 2251 "error-tag": "data-exists", 2252 "error-urlpath": "http://example.com/restconf/data/ 2253 example-jukebox:jukebox", 2254 "error-message": 2255 "Data already exists, cannot create new resource" 2256 } 2257 } 2258 } 2260 7. RESTCONF module 2262 The "ietf-restconf" module defines conceptual definitions within 2263 groupings, which are not meant to be implemented as datastore 2264 contents by a server. The "restconf" container is not intended to be 2265 implemented as a top-level data node (under the "/restconf/data" 2266 entry point). 2268 The "ietf-yang-types" module from [RFC6991] is used by this module 2269 for some type definitions. 2271 RFC Ed.: update the date below with the date of RFC publication and 2272 remove this note. 2274 file "ietf-restconf@2014-10-07.yang" 2276 module ietf-restconf { 2277 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 2278 prefix "rc"; 2280 import ietf-yang-types { prefix yang; } 2282 organization 2283 "IETF NETCONF (Network Configuration) Working Group"; 2285 contact 2286 "WG Web: 2287 WG List: 2289 WG Chair: Bert Wijnen 2290 2292 WG Chair: Mehmet Ersue 2293 2295 Editor: Andy Bierman 2296 2298 Editor: Martin Bjorklund 2299 2301 Editor: Kent Watsen 2302 "; 2304 description 2305 "This module contains conceptual YANG specifications 2306 for the message and error content that is used in 2307 RESTCONF protocol messages. A conceptual container 2308 representing the RESTCONF API nodes is also defined 2309 for the media type application/yang.api. 2311 Note that the YANG definitions within this module do not 2312 represent configuration data of any kind. 2313 The YANG grouping statements provide a normative syntax 2314 for XML and JSON message encoding purposes. 2316 Copyright (c) 2014 IETF Trust and the persons identified as 2317 authors of the code. All rights reserved. 2319 Redistribution and use in source and binary forms, with or 2320 without modification, is permitted pursuant to, and subject 2321 to the license terms contained in, the Simplified BSD License 2322 set forth in Section 4.c of the IETF Trust's Legal Provisions 2323 Relating to IETF Documents 2324 (http://trustee.ietf.org/license-info). 2326 This version of this YANG module is part of RFC XXXX; see 2327 the RFC itself for full legal notices."; 2329 // RFC Ed.: replace XXXX with actual RFC number and remove this 2330 // note. 2332 // RFC Ed.: remove this note 2333 // Note: extracted from draft-ietf-netconf-restconf-02.txt 2335 // RFC Ed.: update the date below with the date of RFC publication 2336 // and remove this note. 2337 revision 2014-10-07 { 2338 description 2339 "Initial revision."; 2340 reference 2341 "RFC XXXX: RESTCONF Protocol."; 2342 } 2344 typedef data-resource-identifier { 2345 type string { 2346 length "1 .. max"; 2347 } 2348 description 2349 "Contains a Data Resource Identifier formatted string 2350 to identify a specific data resource instance. 2351 The document root for all data resources is a 2352 datastore resource container. Each top-level YANG 2353 data nodes supported by the server will be represented 2354 as a child node of the document root. 2356 The canonical representation of a data resource identifier 2357 includes the full server specification that is returned 2358 in the Location header when a new data resource is created 2359 with the POST method. 2361 The abbreviated representation does not contain any server 2362 location identification. Instead the identifier will start 2363 with the '/' character to represent the datastore document 2364 root for the data resource instance. 2366 The server MUST accept either representation and SHOULD 2367 return the canonical representation in any response message."; 2368 reference 2369 "RFC XXXX: [sec. 5.3.1.1 ABNF For Data Resource Identifiers]"; 2370 } 2372 grouping errors { 2373 description 2374 "A grouping that contains a YANG container 2375 representing the syntax and semantics of a 2376 YANG Patch errors report within a response message."; 2378 container errors { 2379 description 2380 "Represents an error report returned by the server if 2381 a request results in an error."; 2383 list error { 2384 description 2385 "An entry containing information about one 2386 specific error that occurred while processing 2387 a RESTCONF request."; 2388 reference "RFC 6241, Section 4.3"; 2390 leaf error-type { 2391 type enumeration { 2392 enum transport { 2393 description "The transport layer"; 2394 } 2395 enum rpc { 2396 description "The rpc or notification layer"; 2397 } 2398 enum protocol { 2399 description "The protocol operation layer"; 2400 } 2401 enum application { 2402 description "The server application layer"; 2403 } 2404 } 2405 mandatory true; 2406 description 2407 "The protocol layer where the error occurred."; 2408 } 2410 leaf error-tag { 2411 type string; 2412 mandatory true; 2413 description 2414 "The enumerated error tag."; 2415 } 2417 leaf error-app-tag { 2418 type string; 2419 description 2420 "The application-specific error tag."; 2421 } 2423 choice error-node { 2424 description 2425 "The server will return the location of the error node 2426 in a format that is appropriate for the protocol. 2428 If no specific node within the request message body 2429 caused the error then this choice will not be present."; 2431 leaf error-path { 2432 type instance-identifier; 2433 description 2434 "The YANG instance identifier associated 2435 with the error node. This leaf will only be 2436 present if the error node is not a data resource, 2437 e.g., the error node is an input parameter 2438 for an operation resource."; 2439 } 2440 leaf error-urlpath { 2441 type data-resource-identifier; 2442 description 2443 "The target data resource identifier associated 2444 with the error node. This leaf will only be 2445 present if the error node is associated with 2446 a data resource (either within the server or 2447 in the request message)."; 2448 } 2449 } 2451 leaf error-message { 2452 type string; 2453 description 2454 "A message describing the error."; 2455 } 2457 anyxml error-info { 2458 description 2459 "Arbitrary XML that represents a container 2460 of additional information for the error report."; 2461 } 2462 } 2463 } 2464 } // grouping errors 2466 grouping restconf { 2467 container restconf { 2468 description 2469 "Conceptual container representing the 2470 application/yang.api resource type."; 2472 container data { 2473 description 2474 "Container representing the application/yang.datastore 2475 resource type. Represents the conceptual root of all 2476 operational data and configuration data supported by 2477 the server. The child nodes of this container can be 2478 any data resource (application/yang.data), which are 2479 defined as top-level data nodes from the YANG modules 2480 advertised by the server in the ietf-restconf-monitoring 2481 module."; 2482 } 2484 container operations { 2485 description 2486 "Container for all operation resources 2487 (application/yang.operation), 2489 Each resource is represented as an empty leaf with the 2490 name of the RPC operation from the YANG rpc statement. 2492 E.g.; 2494 POST /restconf/operations/show-log-errors 2496 leaf show-log-errors { 2497 type empty; 2498 } 2499 "; 2500 } 2501 } // container restconf 2502 } // grouping restconf 2504 grouping notification { 2505 description 2506 "Contains the notification message wrapper definition."; 2508 container notification { 2509 description 2510 "RESTCONF notification message wrapper."; 2512 leaf event-time { 2513 type yang:date-and-time; 2514 mandatory true; 2515 description 2516 "The time the event was generated by the 2517 event source."; 2518 reference 2519 "RFC 5277, section 4, element."; 2520 } 2521 /* The YANG-specific notification container is encoded 2522 * after the 'event-time' element. The format 2523 * corresponds to the notificationContent element 2524 * in RFC 5277, section 4. For example: 2525 * 2526 * module example-one { 2527 * ... 2528 * notification event1 { ... } 2529 * 2530 * } 2531 * 2532 * Encoded as element 'event1' in the namespace 2533 * for module 'example-one'. 2534 */ 2535 } 2536 } // grouping notification 2538 } 2540 2542 8. RESTCONF Monitoring 2544 The "ietf-restconf-monitoring" module provides information about the 2545 RESTCONF protocol capabilities and notification event streams 2546 available from the server. Implementation is mandatory for RESTCONF 2547 servers, if any protocol capabilities or notification event streams 2548 are supported. 2550 YANG Tree Diagram for "ietf-restconf-monitoring" module: 2552 +--ro restconf-state 2553 +--ro capabilities 2554 | +--ro capability* inet:uri 2555 +--ro streams 2556 +--ro stream* [name] 2557 +--ro name string 2558 +--ro description? string 2559 +--ro replay-support? boolean 2560 +--ro replay-log-creation-time? yang:date-and-time 2561 +--ro events inet:uri 2563 8.1. restconf-state/capabilities 2565 This mandatory container holds the RESTCONF protocol capability URIs 2566 supported by the server. 2568 The server MUST maintain a last-modified timestamp for this 2569 container, and return the "Last-Modified" header when this data node 2570 is retrieved with the GET or HEAD methods. 2572 The server SHOULD maintain an entity-tag for this container, and 2573 return the "ETag" header when this data node is retrieved with the 2574 GET or HEAD methods. 2576 8.2. restconf-state/streams 2578 This optional container provides access to the notification event 2579 streams supported by the server. The server MAY omit this container 2580 if no notification event streams are supported. 2582 The server will populate this container with a stream list entry for 2583 each stream type it supports. Each stream contains a leaf called 2584 "events" which contains a URI that represents an event stream 2585 resource. 2587 Stream resources are defined in Section 2.8. Notifications are 2588 defined in Section 5. 2590 8.3. RESTCONF Monitoring Module 2592 The "ietf-restconf-monitoring" module defines monitoring information 2593 for the RESTCONF protocol. 2595 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 2596 are used by this module for some type definitions. 2598 RFC Ed.: update the date below with the date of RFC publication and 2599 remove this note. 2601 file "ietf-restconf-monitoring@2014-10-07.yang" 2603 module ietf-restconf-monitoring { 2604 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; 2605 prefix "rcmon"; 2607 import ietf-yang-types { prefix yang; } 2608 import ietf-inet-types { prefix inet; } 2610 organization 2611 "IETF NETCONF (Network Configuration) Working Group"; 2613 contact 2614 "WG Web: 2615 WG List: 2616 WG Chair: Bert Wijnen 2617 2619 WG Chair: Mehmet Ersue 2620 2622 Editor: Andy Bierman 2623 2625 Editor: Martin Bjorklund 2626 2628 Editor: Kent Watsen 2629 "; 2631 description 2632 "This module contains monitoring information for the 2633 RESTCONF protocol. 2635 Copyright (c) 2014 IETF Trust and the persons identified as 2636 authors of the code. All rights reserved. 2638 Redistribution and use in source and binary forms, with or 2639 without modification, is permitted pursuant to, and subject 2640 to the license terms contained in, the Simplified BSD License 2641 set forth in Section 4.c of the IETF Trust's Legal Provisions 2642 Relating to IETF Documents 2643 (http://trustee.ietf.org/license-info). 2645 This version of this YANG module is part of RFC XXXX; see 2646 the RFC itself for full legal notices."; 2648 // RFC Ed.: replace XXXX with actual RFC number and remove this 2649 // note. 2651 // RFC Ed.: remove this note 2652 // Note: extracted from draft-ietf-netconf-restconf-02.txt 2654 // RFC Ed.: update the date below with the date of RFC publication 2655 // and remove this note. 2656 revision 2014-10-07 { 2657 description 2658 "Initial revision."; 2659 reference 2660 "RFC XXXX: RESTCONF Protocol."; 2661 } 2663 container restconf-state { 2664 config false; 2665 description 2666 "Contains RESTCONF protocol monitoring information."; 2668 container capabilities { 2669 description 2670 "Contains a list of protocol capability URIs"; 2672 leaf-list capability { 2673 type inet:uri; 2674 description "A RESTCONF protocol capability URI."; 2675 } 2676 } 2678 container streams { 2679 description 2680 "Container representing the notification event streams 2681 supported by the server."; 2682 reference 2683 "RFC 5277, Section 3.4, element."; 2685 list stream { 2686 key name; 2687 description 2688 "Each entry describes an event stream supported by 2689 the server."; 2691 leaf name { 2692 type string; 2693 description "The stream name"; 2694 reference "RFC 5277, Section 3.4, element."; 2695 } 2697 leaf description { 2698 type string; 2699 description "Description of stream content"; 2700 reference 2701 "RFC 5277, Section 3.4, element."; 2702 } 2704 leaf replay-support { 2705 type boolean; 2706 description 2707 "Indicates if replay buffer supported for this stream. 2708 If 'true', then the server MUST support the 'start-time' 2709 and 'stop-time' query parameters for this stream."; 2710 reference 2711 "RFC 5277, Section 3.4, element."; 2713 } 2715 leaf replay-log-creation-time { 2716 when "../replay-support"; 2717 type yang:date-and-time; 2718 description 2719 "Indicates the time the replay log for this stream 2720 was created."; 2721 reference 2722 "RFC 5277, Section 3.4, 2723 element."; 2724 } 2726 leaf events { 2727 type inet:uri; 2728 mandatory true; 2729 description 2730 "Contains a URL that represents the entry point 2731 for establishing notification delivery via server 2732 sent events."; 2733 } 2734 } 2735 } 2736 } 2738 } 2740 2742 9. YANG Module Library 2744 The "ietf-yang-library" module provides information about the YANG 2745 modules and submodules used by the RESTCONF server. Implementation 2746 is mandatory for RESTCONF servers. All YANG modules and submodules 2747 used by the server MUST be identified in the YANG module library. 2749 YANG Tree Diagram for "ietf-yang-library" module: 2751 +--ro modules 2752 +--ro module-set-id? string 2753 +--ro module* [name revision] 2754 +--ro name yang:yang-identifier 2755 +--ro revision union 2756 +--ro schema? inet:uri 2757 +--ro namespace inet:uri 2758 +--ro feature* yang:yang-identifier 2759 +--ro deviation* yang:yang-identifier 2760 +--ro conformance boolean 2761 +--ro submodules 2762 +--ro submodule* [name revision] 2763 +--ro name yang:yang-identifier 2764 +--ro revision union 2765 +--ro schema? inet:uri 2767 9.1. modules 2769 This mandatory container holds the identifiers for the YANG data 2770 model modules supported by the server. 2772 The server MUST maintain a last-modified timestamp for this 2773 container, and return the "Last-Modified" header when this data node 2774 is retrieved with the GET or HEAD methods. 2776 The server SHOULD maintain an entity-tag for this container, and 2777 return the "ETag" header when this data node is retrieved with the 2778 GET or HEAD methods. 2780 9.1.1. modules/module 2782 This mandatory list contains one entry for each YANG data model 2783 module supported by the server. There MUST be an instance of this 2784 list for every YANG module that is used by the server. 2786 The contents of the "module" list are defined in the "module" YANG 2787 list statement in Section 9.2. 2789 The server MAY maintain a last-modified timestamp for each instance 2790 of this list entry, and return the "Last-Modified" header when this 2791 data node is retrieved with the GET or HEAD methods. If not 2792 supported then the timestamp for the parent "modules" container MAY 2793 be used instead. 2795 The server MAY maintain an entity-tag for each instance of this list 2796 entry, and return the "ETag" header when this data node is retrieved 2797 with the GET or HEAD methods. If not supported then the timestamp 2798 for the parent "modules" container MAY be used instead. 2800 9.2. YANG Library Module 2802 The "ietf-yang-library" module defines monitoring information for the 2803 YANG modules used by a RESTCONF server. 2805 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 2806 are used by this module for some type definitions. 2808 RFC Ed.: update the date below with the date of RFC publication and 2809 remove this note. 2811 file "ietf-yang-library@2014-10-07.yang" 2813 module ietf-yang-library { 2814 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library"; 2815 prefix "yanglib"; 2817 import ietf-yang-types { prefix yang; } 2818 import ietf-inet-types { prefix inet; } 2820 organization 2821 "IETF NETCONF (Network Configuration) Working Group"; 2823 contact 2824 "WG Web: 2825 WG List: 2827 WG Chair: Bert Wijnen 2828 2830 WG Chair: Mehmet Ersue 2831 2833 Editor: Andy Bierman 2834 2836 Editor: Martin Bjorklund 2837 2839 Editor: Kent Watsen 2840 "; 2842 description 2843 "This module contains monitoring information about the YANG 2844 modules and submodules that are used within a RESTCONF 2845 server. 2847 Copyright (c) 2014 IETF Trust and the persons identified as 2848 authors of the code. All rights reserved. 2850 Redistribution and use in source and binary forms, with or 2851 without modification, is permitted pursuant to, and subject 2852 to the license terms contained in, the Simplified BSD License 2853 set forth in Section 4.c of the IETF Trust's Legal Provisions 2854 Relating to IETF Documents 2855 (http://trustee.ietf.org/license-info). 2857 This version of this YANG module is part of RFC XXXX; see 2858 the RFC itself for full legal notices."; 2860 // RFC Ed.: replace XXXX with actual RFC number and remove this 2861 // note. 2863 // RFC Ed.: remove this note 2864 // Note: extracted from draft-ietf-netconf-restconf-02.txt 2866 // RFC Ed.: update the date below with the date of RFC publication 2867 // and remove this note. 2868 revision 2014-09-26 { 2869 description 2870 "Initial revision."; 2871 reference 2872 "RFC XXXX: RESTCONF Protocol."; 2873 } 2875 typedef revision-identifier { 2876 type string { 2877 pattern '\d{4}-\d{2}-\d{2}'; 2878 } 2879 description 2880 "Represents a specific date in YYYY-MM-DD format. 2881 TBD: make pattern more precise to exclude leading zeros."; 2882 } 2884 grouping module { 2885 description 2886 "The module data structure is represented as a grouping 2887 so it can be reused in configuration or another monitoring 2888 data structure."; 2890 grouping common-leafs { 2891 description 2892 "Common parameters for YANG modules and submodules."; 2894 leaf name { 2895 type yang:yang-identifier; 2896 description "The YANG module or submodule name."; 2897 } 2898 leaf revision { 2899 type union { 2900 type revision-identifier; 2901 type string { length 0; } 2902 } 2903 description 2904 "The YANG module or submodule revision date. 2905 An empty string is used if no revision statement 2906 is present in the YANG module or submodule."; 2907 } 2908 leaf schema { 2909 type inet:uri; 2910 description 2911 "Contains a URL that represents the YANG schema 2912 resource for this module or submodule. 2914 This leaf will only be present if there is a URL 2915 available for retrieval of the schema for this entry."; 2916 } 2917 } 2919 list module { 2920 key "name revision"; 2921 description 2922 "Each entry represents one module currently 2923 supported by the server."; 2925 uses common-leafs; 2927 leaf namespace { 2928 type inet:uri; 2929 mandatory true; 2930 description 2931 "The XML namespace identifier for this module."; 2932 } 2933 leaf-list feature { 2934 type yang:yang-identifier; 2935 description 2936 "List of YANG feature names from this module that are 2937 supported by the server."; 2938 } 2939 leaf-list deviation { 2940 type yang:yang-identifier; 2941 description 2942 "List of YANG deviation module names used by this 2943 server to modify the conformance of the module 2944 associated with this entry."; 2945 } 2946 leaf conformance { 2947 type boolean; 2948 mandatory true; 2949 description 2950 "If 'true', then the server is claiming conformance to 2951 the YANG module identified in this entry. 2953 If 'false', then the server is not claiming any 2954 conformance for the YANG module identified by this 2955 entry. The module may be needed for reusable definitions 2956 such as extensions, features, identifies, typedefs, 2957 or groupings."; 2958 } 2959 container submodules { 2960 description 2961 "Contains information about all the submodules used 2962 by the parent module entry"; 2964 list submodule { 2965 key "name revision"; 2966 description 2967 "Each entry represents one submodule within the 2968 parent module."; 2969 uses common-leafs; 2970 } 2971 } 2972 } // list module 2973 } // grouping module 2975 container modules { 2976 config false; 2977 description 2978 "Contains YANG module monitoring information."; 2980 leaf module-set-id { 2981 type string; 2982 description 2983 "Contains a server-specific identifier representing 2984 the current set of modules and submodules. The 2985 server MUST change the value of this leaf if the 2986 information represented by the 'module' list instances 2987 has changed."; 2988 } 2990 uses module; 2992 } 2994 } 2996 2998 10. IANA Considerations 3000 10.1. The "restconf" Relation Type 3002 This specification registers the "restconf" relation type in the Link 3003 Relation Type Registry defined by [RFC5988]: 3005 Relation Name: restconf 3007 Description: Identifies the root of RESTCONF API as configured 3008 on this HTTP server. The "restconf" relation 3009 defines the root of the API defined in RFCXXXX. 3010 Subsequent revisions of RESTCONF will use alternate 3011 relation values to support protocol versioning. 3013 Reference: RFC XXXX 3015 ` 3017 10.2. YANG Module Registry 3019 This document registers three URIs in the IETF XML registry 3020 [RFC3688]. Following the format in RFC 3688, the following 3021 registration is requested to be made. 3023 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 3024 Registrant Contact: The NETMOD WG of the IETF. 3025 XML: N/A, the requested URI is an XML namespace. 3027 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3028 Registrant Contact: The NETMOD WG of the IETF. 3029 XML: N/A, the requested URI is an XML namespace. 3031 URI: urn:ietf:params:xml:ns:yang:ietf-yang-library 3032 Registrant Contact: The NETMOD WG of the IETF. 3033 XML: N/A, the requested URI is an XML namespace. 3035 This document registers three YANG modules in the YANG Module Names 3036 registry [RFC6020]. 3038 name: ietf-restconf 3039 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3040 prefix: rc 3041 // RFC Ed.: replace XXXX with RFC number and remove this note 3042 reference: RFC XXXX 3044 name: ietf-restconf-monitoring 3045 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3046 prefix: rcmon 3047 // RFC Ed.: replace XXXX with RFC number and remove this note 3048 reference: RFC XXXX 3050 name: ietf-yang-library 3051 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library 3052 prefix: yanglib 3053 // RFC Ed.: replace XXXX with RFC number and remove this note 3054 reference: RFC XXXX 3056 10.3. application/yang Media Sub Types 3058 The parent MIME media type for RESTCONF resources is application/ 3059 yang, which is defined in [RFC6020]. This document defines the 3060 following sub-types for this media type. 3062 - api 3063 - data 3064 - datastore 3065 - errors 3066 - operation 3067 - stream 3069 Type name: application 3071 Subtype name: yang.xxx 3073 Required parameters: TBD 3075 Optional parameters: TBD 3077 Encoding considerations: TBD 3079 Security considerations: TBD 3081 Interoperability considerations: TBD 3083 // RFC Ed.: replace XXXX with RFC number and remove this note 3084 Published specification: RFC XXXX 3086 10.4. NETCONF Capability URNs 3088 This document registers several capability identifiers in "Network 3089 Configuration Protocol (NETCONF) Capability URNs" registry 3091 Index 3092 Capability Identifier 3093 ------------------------ 3095 :content 3096 urn:ietf:params:restconf:capability:content:1.0 3098 :depth 3099 urn:ietf:params:restconf:capability:depth:1.0 3101 :filter 3102 urn:ietf:params:restconf:capability:filter:1.0 3104 :insert 3105 urn:ietf:params:restconf:capability:insert:1.0 3107 :select 3108 urn:ietf:params:restconf:capability:select:1.0 3110 :replay 3111 urn:ietf:params:restconf:capability:replay:1.0 3113 11. Security Considerations 3115 This section provides security considerations for the resources 3116 defined by the RESTCONF protocol. Security considerations for HTTPS 3117 are defined in [RFC2818]. Security considerations for the content 3118 manipulated by RESTCONF can be found in the documents defining data 3119 models. 3121 This document does not specify an authentication scheme, but it does 3122 require that an authenticated NETCONF username be associated with 3123 each HTTP request. The authentication scheme MAY be implemented in 3124 the underlying transport layer (e.g., client certificates) or within 3125 the HTTP layer (e.g., Basic Auth, OAuth, etc.). RESTCONF does not 3126 itself define an authentication mechanism, authentication MUST occur 3127 in a lower layer. Implementors SHOULD provide a comprehensive 3128 authorization scheme with RESTCONF and ensure that the resulting 3129 NETCONF username is made available to the RESTCONF server. 3131 Authorization of individual user access to operations and data MAY be 3132 configured via NETCONF Access Control Model (NACM) [RFC6536], as 3133 specified in Section 3. Other authorization models MAY be used, but 3134 are outside of the scope of this document. 3136 Configuration information is by its very nature sensitive. Its 3137 transmission in the clear and without integrity checking leaves 3138 devices open to classic eavesdropping and false data injection 3139 attacks. Configuration information often contains passwords, user 3140 names, service descriptions, and topological information, all of 3141 which are sensitive. Because of this, this protocol SHOULD be 3142 implemented carefully with adequate attention to all manner of attack 3143 one might expect to experience with other management interfaces. 3145 Different environments may well allow different rights prior to and 3146 then after authentication. When an operation is not properly 3147 authorized, the RESTCONF server MUST return HTTP error status code 3148 401 Unauthorized. Note that authorization information can be 3149 exchanged in the form of configuration information, which is all the 3150 more reason to ensure the security of the connection. 3152 12. Acknowledgements 3154 The authors would like to thank for following for lively discussions 3155 on list and in the halls (ordered by last name): Rex Fernando 3157 13. References 3159 13.1. Normative References 3161 [I-D.lhotka-netmod-json] 3162 Lhotka, L., "Modeling JSON Text with YANG", draft-lhotka- 3163 netmod-yang-json-02 (work in progress), September 2013. 3165 [JSON] Bray, T., Ed., "The JSON Data Interchange Format", draft- 3166 ietf-json-rfc4627bis-10 (work in progress), December 2013. 3168 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3169 Requirement Levels", BCP 14, RFC 2119, March 1997. 3171 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol, Version 1.0", 3172 RFC 2246, January 1999. 3174 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3175 Resource Identifiers (URI): Generic Syntax", RFC 2396, 3176 August 1998. 3178 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3179 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3180 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3182 [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. 3184 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3185 January 2004. 3187 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3188 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3189 3986, January 2005. 3191 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3192 Notifications", RFC 5277, July 2008. 3194 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3195 Housley, R., and T. Polk, "Internet X.509 Public Key 3196 Infrastructure Certificate and Certificate Revocation List 3197 (CRL) Profile", RFC 5280, May 2008. 3199 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3200 5789, March 2010. 3202 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3204 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 3205 Network Configuration Protocol (NETCONF)", RFC 6020, 3206 October 2010. 3208 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3209 and A. Bierman, Ed., "Network Configuration Protocol 3210 (NETCONF)", RFC 6241, June 2011. 3212 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 3213 6415, October 2011. 3215 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 3216 Protocol (NETCONF) Access Control Model", RFC 6536, March 3217 2012. 3219 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3220 and D. Orchard, "URI Template", RFC 6570, March 2012. 3222 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 3223 July 2013. 3225 [W3C.REC-xml-20081126] 3226 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 3227 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 3228 Edition)", World Wide Web Consortium Recommendation REC- 3229 xml-20081126, November 2008, 3230 . 3232 [get-off-my-lawn] 3233 Nottingham, M., "URI Design and Ownership", Best Current 3234 Practice draft-ietf-appsawg-uri-get-off-my-lawn-05, May 3235 2014. 3237 [rest-dissertation] 3238 Fielding, R., "Architectural Styles and the Design of 3239 Network-based Software Architectures", 2000. 3241 [wd-eventsource] 3242 Hickson, I., "Server-Sent Events", December 2012. 3244 13.2. Informative References 3246 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 3247 Version 1.0", World Wide Web Consortium Recommendation 3248 REC-xpath-19991116, November 1999, 3249 . 3251 Appendix A. Change Log 3253 -- RFC Ed.: remove this section before publication. 3255 A.1. 01 - 02 3257 o moved query parameter definitions from the YANG module back to the 3258 plain text sections 3260 o made all query parameters optional to implement 3262 o defined query parameter capability URI 3264 o moved 'streams' to new YANG module (ietf-restconf-monitoring) 3266 o added 'capabilities' container to new YANG module (ietf-restconf- 3267 monitoring) 3269 o moved 'modules' container to new YANG module (ietf-yang-library) 3271 o added new leaf 'module-set-id' (ietf-yang-library) 3272 o added new leaf 'conformance' (ietf-yang-library) 3274 o changed 'schema' leaf to type inet:uri that returns the location 3275 of the YANG schema (instead of returning the schema directly) 3277 o changed 'events' leaf to type inet:uri that returns the location 3278 of the event stream resource (instead of returning events 3279 directly) 3281 o changed examples for yang.api resource since the monitoring 3282 information is no longer in this resource 3284 o closed issue #1 'select parameter' since no objections to the 3285 proposed syntax 3287 o closed "encoding of list keys" issue since no objection to new 3288 encoding of list keys in a target resource URI. 3290 o moved open issues list to the issue tracker on github 3292 A.2. 00 - 01 3294 o fixed content=nonconfig example (non-config was incorrect) 3296 o closed open issue 'message-id'. There is no need for a message-id 3297 field, and RFC 2392 does not apply. 3299 o closed open issue 'server support verification'. The headers used 3300 by RESTCONF are widely supported. 3302 o removed encoding rules from section on RESTCONF Meta-Data. This 3303 is now defined in [I-D.lhotka-netmod-json]. 3305 o added media type application/yang.errors to map to errors YANG 3306 grouping. Updated error examples to use new media type. 3308 o closed open issue 'additional datastores'. Support may be added 3309 in the future to identify new datastores. 3311 o closed open issue 'PATCH media type discovery'. The section on 3312 PATCH has an added sentence on the Accept-Patch header. 3314 o closed open issue 'YANG to resource mapping'. Current mapping of 3315 all data nodes to resources will be used in order to allow 3316 mandatory DELETE support. The PATCH operation is optional, as 3317 well as the YANG Patch media type. 3319 o closed open issue '_self links for HATEOAS support'. It was 3320 decided that they are redundant because they can be derived from 3321 the YANG module for the specific data. 3323 o added explanatory text for the 'select' parameter. 3325 o added RESTCONF Path Resolution section for discovering the root of 3326 the RESTCONF API using the /.well-known/host-meta. 3328 o added an "error" media type to for structured error messages 3330 o added Secure Transport section requiring TLS 3332 o added Security Considerations section 3334 o removed all references to "REST-like" 3336 A.3. bierman:restconf-04 to ietf:restconf-00 3338 o updated open issues section 3340 Appendix B. Open Issues 3342 -- RFC Ed.: remove this section before publication. 3344 The RESTCONF issues are tracked on github.com: 3346 https://github.com/netconf-wg/restconf/issues 3348 Appendix C. Example YANG Module 3350 The example YANG module used in this document represents a simple 3351 media jukebox interface. 3353 YANG Tree Diagram for "example-jukebox" Module 3354 +--rw jukebox? 3355 +--rw library 3356 | +--rw artist [name] 3357 | | +--rw name string 3358 | | +--rw album [name] 3359 | | +--rw name string 3360 | | +--rw genre? identityref 3361 | | +--rw year? uint16 3362 | | +--rw admin 3363 | | | +--rw label? string 3364 | | | +--rw catalogue-number? string 3365 | | +--rw song [name] 3366 | | +--rw name string 3367 | | +--rw location string 3368 | | +--rw format? string 3369 | | +--rw length? uint32 3370 | +--ro artist-count? uint32 3371 | +--ro album-count? uint32 3372 | +--ro song-count? uint32 3373 +--rw playlist [name] 3374 | +--rw name string 3375 | +--rw description? string 3376 | +--rw song [index] 3377 | +--rw index uint32 3378 | +--rw id instance-identifier 3379 +--rw player 3380 +--rw gap? decimal64 3382 rpcs: 3384 +---x play 3385 +--ro input 3386 +--ro playlist string 3387 +--ro song-number uint32 3389 C.1. example-jukebox YANG Module 3391 module example-jukebox { 3393 namespace "http://example.com/ns/example-jukebox"; 3394 prefix "jbox"; 3395 import ietf-restconf { prefix rc; } 3397 organization "Example, Inc."; 3398 contact "support at example.com"; 3399 description "Example Jukebox Data Model Module"; 3400 revision "2014-07-03" { 3401 description "Initial version."; 3402 reference "example.com document 1-4673"; 3403 } 3405 identity genre { 3406 description "Base for all genre types"; 3407 } 3409 // abbreviated list of genre classifications 3410 identity alternative { 3411 base genre; 3412 description "Alternative music"; 3413 } 3414 identity blues { 3415 base genre; 3416 description "Blues music"; 3417 } 3418 identity country { 3419 base genre; 3420 description "Country music"; 3421 } 3422 identity jazz { 3423 base genre; 3424 description "Jazz music"; 3425 } 3426 identity pop { 3427 base genre; 3428 description "Pop music"; 3429 } 3430 identity rock { 3431 base genre; 3432 description "Rock music"; 3433 } 3435 container jukebox { 3436 presence 3437 "An empty container indicates that the jukebox 3438 service is available"; 3440 description 3441 "Represents a jukebox resource, with a library, playlists, 3442 and a play operation."; 3444 container library { 3446 description "Represents the jukebox library resource."; 3448 list artist { 3449 key name; 3450 description 3451 "Represents one artist resource within the 3452 jukebox library resource."; 3454 leaf name { 3455 type string { 3456 length "1 .. max"; 3457 } 3458 description "The name of the artist."; 3459 } 3461 list album { 3462 key name; 3464 description 3465 "Represents one album resource within one 3466 artist resource, within the jukebox library."; 3468 leaf name { 3469 type string { 3470 length "1 .. max"; 3471 } 3472 description "The name of the album."; 3473 } 3475 leaf genre { 3476 type identityref { base genre; } 3477 description 3478 "The genre identifying the type of music on 3479 the album."; 3480 } 3482 leaf year { 3483 type uint16 { 3484 range "1900 .. max"; 3485 } 3486 description "The year the album was released"; 3487 } 3489 container admin { 3490 description 3491 "Administrative information for the album."; 3493 leaf label { 3494 type string; 3495 description "The label that released the album."; 3496 } 3497 leaf catalogue-number { 3498 type string; 3499 description "The album's catalogue number."; 3500 } 3501 } 3503 list song { 3504 key name; 3506 description 3507 "Represents one song resource within one 3508 album resource, within the jukebox library."; 3510 leaf name { 3511 type string { 3512 length "1 .. max"; 3513 } 3514 description "The name of the song"; 3515 } 3516 leaf location { 3517 type string; 3518 mandatory true; 3519 description 3520 "The file location string of the 3521 media file for the song"; 3522 } 3523 leaf format { 3524 type string; 3525 description 3526 "An identifier string for the media type 3527 for the file associated with the 3528 'location' leaf for this entry."; 3529 } 3530 leaf length { 3531 type uint32; 3532 units "seconds"; 3533 description 3534 "The duration of this song in seconds."; 3535 } 3536 } // end list 'song' 3537 } // end list 'album' 3538 } // end list 'artist' 3540 leaf artist-count { 3541 type uint32; 3542 units "songs"; 3543 config false; 3544 description "Number of artists in the library"; 3545 } 3546 leaf album-count { 3547 type uint32; 3548 units "albums"; 3549 config false; 3550 description "Number of albums in the library"; 3551 } 3552 leaf song-count { 3553 type uint32; 3554 units "songs"; 3555 config false; 3556 description "Number of songs in the library"; 3557 } 3558 } // end library 3560 list playlist { 3561 key name; 3563 description 3564 "Example configuration data resource"; 3566 leaf name { 3567 type string; 3568 description 3569 "The name of the playlist."; 3570 } 3571 leaf description { 3572 type string; 3573 description 3574 "A comment describing the playlist."; 3575 } 3576 list song { 3577 key index; 3578 ordered-by user; 3580 description 3581 "Example nested configuration data resource"; 3583 leaf index { // not really needed 3584 type uint32; 3585 description 3586 "An arbitrary integer index for this 3587 playlist song."; 3588 } 3589 leaf id { 3590 type rc:data-resource-identifier; 3591 mandatory true; 3592 description 3593 "Song identifier. Must identify an instance of 3594 /jukebox/library/artist/album/song/name."; 3595 } 3596 } 3597 } 3599 container player { 3600 description 3601 "Represents the jukebox player resource."; 3603 leaf gap { 3604 type decimal64 { 3605 fraction-digits 1; 3606 range "0.0 .. 2.0"; 3607 } 3608 units "tenths of seconds"; 3609 description "Time gap between each song"; 3610 } 3611 } 3612 } 3614 rpc play { 3615 description "Control function for the jukebox player"; 3616 input { 3617 leaf playlist { 3618 type string; 3619 mandatory true; 3620 description "playlist name"; 3621 } 3622 leaf song-number { 3623 type uint32; 3624 mandatory true; 3625 description "Song number in playlist to play"; 3626 } 3627 } 3628 } 3629 } 3631 Appendix D. RESTCONF Message Examples 3633 The examples within this document use the normative YANG module 3634 defined in Section 7 and the non-normative example YANG module 3635 defined in Appendix C.1. 3637 This section shows some typical RESTCONF message exchanges. 3639 D.1. Resource Retrieval Examples 3641 D.1.1. Retrieve the Top-level API Resource 3643 The client may start by retrieving the top-level API resource, using 3644 the entry point URI "{+restconf}". 3646 GET /restconf HTTP/1.1 3647 Host: example.com 3648 Accept: application/yang.api+json, 3649 application/yang.errors+json 3651 The server might respond as follows: 3653 HTTP/1.1 200 OK 3654 Date: Mon, 23 Apr 2012 17:01:00 GMT 3655 Server: example-server 3656 Content-Type: application/yang.api+json 3658 { 3659 "ietf-restconf:restconf": { 3660 "data" : [ null ], 3661 "operations" : { 3662 "play" : [ null ] 3663 } 3664 } 3665 } 3667 To request that the response content to be encoded in XML, the 3668 "Accept" header can be used, as in this example request: 3670 GET /restconf HTTP/1.1 3671 Host: example.com 3672 Accept: application/yang.api+xml, 3673 application/yang.errors+xml 3675 The server will return the same response either way, which might be 3676 as follows : 3678 HTTP/1.1 200 OK 3679 Date: Mon, 23 Apr 2012 17:01:00 GMT 3680 Server: example-server 3681 Cache-Control: no-cache 3682 Pragma: no-cache 3683 Content-Type: application/yang.api+xml 3684 3685 3686 3687 3688 3689 3691 D.1.2. Retrieve The Server Module Information 3693 In this example the client is retrieving the modules information from 3694 the server in JSON format: 3696 GET /restconf/data/modules HTTP/1.1 3697 Host: example.com 3698 Accept: application/yang.data+json, 3699 application/yang.errors+json 3701 The server might respond as follows. 3703 HTTP/1.1 200 OK 3704 Date: Mon, 23 Apr 2012 17:01:00 GMT 3705 Server: example-server 3706 Cache-Control: no-cache 3707 Pragma: no-cache 3708 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 3709 Content-Type: application/yang.data+json 3711 { 3712 "ietf-yang-library:modules": { 3713 "module": [ 3714 { 3715 "name" : "foo", 3716 "revision" : "2012-01-02", 3717 "schema" : "http://example.com/mymodules/foo/2012-01-02", 3718 "namespace" : "http://example.com/ns/foo", 3719 "feature" : [ "feature1", "feature2" ], 3720 "conformance" : true 3721 }, 3722 { 3723 "name" : "foo-types", 3724 "revision" : "2012-01-05", 3725 "schema" : 3726 "http://example.com/mymodules/foo-types/2012-01-05", 3727 "schema" : [null], 3728 "namespace" : "http://example.com/ns/foo-types", 3729 "conformance" : false 3730 }, 3731 { 3732 "name" : "bar", 3733 "revision" : "2012-11-05", 3734 "schema" : "http://example.com/mymodules/bar/2012-11-05", 3735 "namespace" : "http://example.com/ns/bar", 3736 "feature" : [ "bar-ext" ], 3737 "conformance" : true, 3738 "submodule" : [ 3739 { 3740 "name" : "bar-submod1", 3741 "revision" : "2012-11-05", 3742 "schema" : 3743 "http://example.com/mymodules/bar-submod1/2012-11-05" 3744 }, 3745 { 3746 "name" : "bar-submod2", 3747 "revision" : "2012-11-05", 3748 "schema" : 3749 "http://example.com/mymodules/bar-submod2/2012-11-05" 3750 } 3751 ] 3752 } 3753 ] 3754 } 3755 } 3757 D.1.3. Retrieve The Server Capability Information 3759 In this example the client is retrieving the capability information 3760 from the server in JSON format, and the server supports all the 3761 RESTCONF query parameters, plus one vendor parameter: 3763 GET /restconf/data/restconf-state/capabilities HTTP/1.1 3764 Host: example.com 3765 Accept: application/yang.data+json, 3766 application/yang.errors+json 3768 The server might respond as follows. 3770 HTTP/1.1 200 OK 3771 Date: Mon, 23 Apr 2012 17:02:00 GMT 3772 Server: example-server 3773 Cache-Control: no-cache 3774 Pragma: no-cache 3775 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 3776 Content-Type: application/yang.data+json 3778 { 3779 "ietf-restconf-monitoring:capabilities": { 3780 "capability": [ 3781 "urn:ietf:params:restconf:capability:content:1.0", 3782 "urn:ietf:params:restconf:capability:depth:1.0", 3783 "urn:ietf:params:restconf:capability:filter:1.0", 3784 "urn:ietf:params:restconf:capability:insert:1.0", 3785 "urn:ietf:params:restconf:capability:point:1.0", 3786 "urn:ietf:params:restconf:capability:select:1.0", 3787 "urn:ietf:params:restconf:capability:start-time:1.0", 3788 "urn:ietf:params:restconf:capability:stop-time:1.0", 3789 "http://example.com/capabilities/myparam" 3790 ] 3791 } 3792 } 3794 D.2. Edit Resource Examples 3796 D.2.1. Create New Data Resources 3798 To create a new "artist" resource within the "library" resource, the 3799 client might send the following request. 3801 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 3802 Host: example.com 3803 Content-Type: application/yang.data+json 3805 { "example-jukebox:artist" : { 3806 "name" : "Foo Fighters" 3807 } 3808 } 3810 If the resource is created, the server might respond as follows. 3811 Note that the "Location" header line is wrapped for display purposes 3812 only: 3814 HTTP/1.1 201 Created 3815 Date: Mon, 23 Apr 2012 17:02:00 GMT 3816 Server: example-server 3817 Location: http://example.com/restconf/data/ 3818 example-jukebox:jukebox/library/artist=Foo%20Fighters 3819 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 3820 ETag: b3830f23a4c 3822 To create a new "album" resource for this artist within the "jukebox" 3823 resource, the client might send the following request. Note that the 3824 request URI header line is wrapped for display purposes only: 3826 POST /restconf/data/example-jukebox:jukebox/ 3827 library/artist=Foo%20Fighters HTTP/1.1 3828 Host: example.com 3829 Content-Type: application/yang.data+json 3831 { 3832 "example-jukebox:album" : { 3833 "name" : "Wasting Light", 3834 "genre" : "example-jukebox:alternative", 3835 "year" : 2012 # note this is the wrong date 3836 } 3837 } 3839 If the resource is created, the server might respond as follows. 3840 Note that the "Location" header line is wrapped for display purposes 3841 only: 3843 HTTP/1.1 201 Created 3844 Date: Mon, 23 Apr 2012 17:03:00 GMT 3845 Server: example-server 3846 Location: http://example.com/restconf/data/ 3847 example-jukebox:jukebox/library/artist=Foo%20Fighters/ 3848 album=Wasting%20Light 3849 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 3850 ETag: b8389233a4c 3852 D.2.2. Detect Resource Entity Tag Change 3854 In this example, the server just supports the mandatory datastore 3855 last-changed timestamp. The client has previously retrieved the 3856 "Last-Modified" header and has some value cached to provide in the 3857 following request to patch an "album" list entry with key value 3858 "Wasting Light". Only the "year" field is being updated. 3860 PATCH /restconf/data/example-jukebox:jukebox/ 3861 library/artist=Foo%20Fighters/album=Wasting%20Light/year 3862 HTTP/1.1 3863 Host: example.com 3864 Accept: application/yang.data+json, 3865 application/yang.errors+json 3866 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 3867 Content-Type: application/yang.data+json 3869 { "example-jukebox:year" : "2011" } 3871 In this example the datastore resource has changed since the time 3872 specified in the "If-Unmodified-Since" header. The server might 3873 respond: 3875 HTTP/1.1 412 Precondition Failed 3876 Date: Mon, 23 Apr 2012 19:01:00 GMT 3877 Server: example-server 3878 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 3879 ETag: b34aed893a4c 3881 D.3. Query Parameter Examples 3883 D.3.1. "content" Parameter 3885 The "content" parameter is used to select the type of data child 3886 resources (configuration and/or not configuration) that are returned 3887 by the server for a GET method request. 3889 In this example, a simple YANG list that has configuration and non- 3890 configuration child resources. 3892 container events 3893 list event { 3894 key name; 3895 leaf name { type string; } 3896 leaf description { type string; } 3897 leaf event-count { 3898 type uint32; 3899 config false; 3900 } 3901 } 3902 } 3904 Example 1: content=all 3906 To retrieve all the child resources, the "content" parameter is set 3907 to "all". The client might send: 3909 GET /restconf/data/example-events:events?content=all 3910 HTTP/1.1 3911 Host: example.com 3912 Accept: application/yang.data+json, 3913 application/yang.errors+json 3915 The server might respond: 3917 HTTP/1.1 200 OK 3918 Date: Mon, 23 Apr 2012 17:11:30 GMT 3919 Server: example-server 3920 Cache-Control: no-cache 3921 Pragma: no-cache 3922 Content-Type: application/yang.data+json 3924 { 3925 "example-events:events" : { 3926 "event" : [ 3927 { 3928 "name" : "interface-up", 3929 "description" : "Interface up notification count", 3930 "event-count" : 42 3931 }, 3932 { 3933 "name" : "interface-down", 3934 "description" : "Interface down notification count", 3935 "event-count" : 4 3936 } 3937 ] 3938 } 3939 } 3941 Example 2: content=config 3943 To retrieve only the configuration child resources, the "content" 3944 parameter is set to "config" or omitted since this is the default 3945 value. Note that the "ETag" and "Last-Modified" headers are only 3946 returned if the content parameter value is "config". 3948 GET /restconf/data/example-events:events?content=config 3949 HTTP/1.1 3950 Host: example.com 3951 Accept: application/yang.data+json, 3952 application/yang.errors+json 3954 The server might respond: 3956 HTTP/1.1 200 OK 3957 Date: Mon, 23 Apr 2012 17:11:30 GMT 3958 Server: example-server 3959 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 3960 ETag: eeeada438af 3961 Cache-Control: no-cache 3962 Pragma: no-cache 3963 Content-Type: application/yang.data+json 3965 { 3966 "example-events:events" : { 3967 "event" : [ 3968 { 3969 "name" : "interface-up", 3970 "description" : "Interface up notification count" 3971 }, 3972 { 3973 "name" : "interface-down", 3974 "description" : "Interface down notification count" 3975 } 3976 ] 3977 } 3978 } 3980 Example 3: content=nonconfig 3982 To retrieve only the non-configuration child resources, the "content" 3983 parameter is set to "nonconfig". Note that configuration ancestors 3984 (if any) and list key leafs (if any) are also returned. The client 3985 might send: 3987 GET /restconf/data/example-events:events?content=nonconfig 3988 HTTP/1.1 3989 Host: example.com 3990 Accept: application/yang.data+json, 3991 application/yang.errors+json 3993 The server might respond: 3995 HTTP/1.1 200 OK 3996 Date: Mon, 23 Apr 2012 17:11:30 GMT 3997 Server: example-server 3998 Cache-Control: no-cache 3999 Pragma: no-cache 4000 Content-Type: application/yang.data+json 4002 { 4003 "example-events:events" : { 4004 "event" : [ 4005 { 4006 "name" : "interface-up", 4007 "event-count" : 42 4008 }, 4009 { 4010 "name" : "interface-down", 4011 "event-count" : 4 4012 } 4013 ] 4014 } 4015 } 4017 D.3.2. "depth" Parameter 4019 The "depth" parameter is used to limit the number of levels of child 4020 resources that are returned by the server for a GET method request. 4022 This example shows how different values of the "depth" parameter 4023 would affect the reply content for retrieval of the top-level 4024 "jukebox" data resource. 4026 Example 1: depth=unbounded 4028 To retrieve all the child resources, the "depth" parameter is not 4029 present or set to the default value "unbounded". Note that some 4030 strings are wrapped for display purposes only. 4032 GET /restconf/data/example-jukebox:jukebox?depth=unbounded 4033 HTTP/1.1 4034 Host: example.com 4035 Accept: application/yang.data+json, 4036 application/yang.errors+json 4038 The server might respond: 4040 HTTP/1.1 200 OK 4041 Date: Mon, 23 Apr 2012 17:11:30 GMT 4042 Server: example-server 4043 Cache-Control: no-cache 4044 Pragma: no-cache 4045 Content-Type: application/yang.data+json 4047 { 4048 "example-jukebox:jukebox" : { 4049 "library" : { 4050 "artist" : [ 4051 { 4052 "name" : "Foo Fighters", 4053 "album" : [ 4054 { 4055 "name" : "Wasting Light", 4056 "genre" : "example-jukebox:alternative", 4057 "year" : 2011, 4058 "song" : [ 4059 { 4060 "name" : "Wasting Light", 4061 "location" : 4062 "/media/foo/a7/wasting-light.mp3", 4063 "format" : "MP3", 4064 "length" " 286 4065 }, 4066 { 4067 "name" : "Rope", 4068 "location" : "/media/foo/a7/rope.mp3", 4069 "format" : "MP3", 4070 "length" " 259 4071 } 4072 ] 4073 } 4074 ] 4075 } 4076 ] 4077 }, 4078 "playlist" : [ 4079 { 4080 "name" : "Foo-One", 4081 "description" : "example playlist 1", 4082 "song" : [ 4083 { 4084 "index" : 1, 4085 "id" : "http://example.com/restconf/data/ 4086 example-jukebox:jukebox/library/artist/ 4087 Foo%20Fighters/album/Wasting%20Light/ 4088 song/Rope" 4089 }, 4090 { 4091 "index" : 2, 4092 "id" : "http://example.com/restconf/data/ 4093 example-jukebox:jukebox/library/artist/ 4094 Foo%20Fighters/album/Wasting%20Light/song/ 4095 Bridge%20Burning" 4096 } 4097 ] 4098 } 4099 ], 4100 "player" : { 4101 "gap" : 0.5 4102 } 4103 } 4104 } 4106 Example 2: depth=1 4108 To determine if 1 or more resource instances exist for a given target 4109 resource, the value "1" is used. 4111 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 4112 Host: example.com 4113 Accept: application/yang.data+json, 4114 application/yang.errors+json 4116 The server might respond: 4118 HTTP/1.1 200 OK 4119 Date: Mon, 23 Apr 2012 17:11:30 GMT 4120 Server: example-server 4121 Cache-Control: no-cache 4122 Pragma: no-cache 4123 Content-Type: application/yang.data+json 4125 { 4126 "example-jukebox:jukebox" : [null] 4127 } 4129 Example 3: depth=3 4131 To limit the depth level to the target resource plus 2 child resource 4132 layers the value "3" is used. 4134 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 4135 Host: example.com 4136 Accept: application/yang.data+json, 4137 application/yang.errors+json 4139 The server might respond: 4141 HTTP/1.1 200 OK 4142 Date: Mon, 23 Apr 2012 17:11:30 GMT 4143 Server: example-server 4144 Cache-Control: no-cache 4145 Pragma: no-cache 4146 Content-Type: application/yang.data+json 4148 { 4149 "example-jukebox:jukebox" : { 4150 "library" : { 4151 "artist" : [ null ] 4152 }, 4153 "playlist" : [ 4154 { 4155 "name" : "Foo-One", 4156 "description" : "example playlist 1", 4157 "song" : [ null ] 4158 } 4159 ], 4160 "player" : { 4161 "gap" : 0.5 4162 } 4163 } 4164 } 4166 D.3.3. "select" Parameter 4168 In this example the client is retrieving the API resource, but 4169 selecting only the "name" and "revision" nodes from each module, in 4170 JSON format: 4172 GET /restconf/data?select=modules/module(name;revision) HTTP/1.1 4173 Host: example.com 4174 Accept: application/yang.data+json, 4175 application/yang.errors+json 4177 The server might respond as follows. 4179 HTTP/1.1 200 OK 4180 Date: Mon, 23 Apr 2012 17:01:00 GMT 4181 Server: example-server 4182 Content-Type: application/yang.data+json 4184 { 4185 "ietf-yang-library:modules": { 4186 "module": [ 4187 { 4188 "name" : "example-jukebox", 4189 "revision" : "2014-07-03" 4190 }, 4191 { 4192 "name" : "ietf-restconf-monitoring", 4193 "revision" : "2014-10-07" 4194 }, 4195 { 4196 "name" : "ietf-yang-library", 4197 "revision" : "2014-10-07" 4198 } 4199 ] 4200 } 4201 } 4203 D.3.4. "insert" Parameter 4205 In this example, a new first entry in the "Foo-One" playlist is being 4206 created. 4208 Request from client: 4210 POST /restconf/data/example-jukebox:jukebox/ 4211 playlist=Foo-One?insert=first HTTP/1.1 4212 Host: example.com 4213 Content-Type: application/yang.data+json 4215 { 4216 "example-jukebox:song" : { 4217 "index" : 1, 4218 "id" : "/example-jukebox:jukebox/library/artist/ 4219 Foo%20Fighters/album/Wasting%20Light/song/Rope" 4220 } 4221 } 4223 Response from server: 4225 HTTP/1.1 201 Created 4226 Date: Mon, 23 Apr 2012 13:01:20 GMT 4227 Server: example-server 4228 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4229 Location: http://example.com/restconf/data/ 4230 example-jukebox:jukebox/playlist=Foo-One/song=1 4231 ETag: eeeada438af 4233 D.3.5. "point" Parameter 4235 Example: 4237 In this example, the client is inserting a new "song" resource within 4238 an "album" resource after another song. The request URI is split for 4239 display purposes only. 4241 Request from client: 4243 POST /restconf/data/example-jukebox:jukebox/ 4244 library/artist/Foo%20Fighters/album/Wasting%20Light? 4245 insert=after&point=%2Fexample-jukebox%3Ajukebox%2F 4246 library%2Fartist%2FFoo%20Fighters%2Falbum%2F 4247 Wasting%20Light%2Fsong%2FBridge%20Burning HTTP/1.1 4248 Host: example.com 4249 Content-Type: application/yang.data+json 4251 { 4252 "example-jukebox:song" : { 4253 "name" : "Rope", 4254 "location" : "/media/foo/a7/rope.mp3", 4255 "format" : "MP3", 4256 "length" : 259 4257 } 4258 } 4260 Response from server: 4262 HTTP/1.1 204 No Content 4263 Date: Mon, 23 Apr 2012 13:01:20 GMT 4264 Server: example-server 4265 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4266 ETag: abcada438af 4268 D.3.6. "filter" Parameter 4270 The following URIs show some examples of notification filter 4271 specifications (lines wrapped for display purposes only): 4273 // filter = /event/eventClass='fault' 4274 GET /mystreams/stream=NETCONF/events? 4275 filter=%2Fevent%2FeventClass%3D'fault' 4277 // filter = /event/severityCode<=4 4278 GET /mystreams/stream=NETCONF/events? 4279 filter=%2Fevent%2FseverityCode%3C%3D4 4281 // filter = /linkUp|/linkDown 4282 GET /mystreams/stream=SNMP/events? 4283 filter=%2FlinkUp%7C%2FlinkDown 4285 // filter = /*/reportingEntity/card!='Ethernet0' 4286 GET /mystreams/stream=NETCONF/events? 4287 filter=%2F*%2FreportingEntity%2Fcard%21%3D'Ethernet0' 4289 // filter = /*/email-addr[contains(.,'company.com')] 4290 GET /mystreams/stream=critical-syslog/events? 4291 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 4293 // Note: the module name is used as prefix. 4294 // filter = (/example-mod:event1/name='joe' and 4295 // /example-mod:event1/status='online') 4296 GET /mystreams/stream=NETCONF/events? 4297 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and 4298 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 4300 D.3.7. "start-time" Parameter 4302 TBD 4304 D.3.8. "stop-time" Parameter 4306 TBD 4308 Authors' Addresses 4310 Andy Bierman 4311 YumaWorks 4313 Email: andy@yumaworks.com 4315 Martin Bjorklund 4316 Tail-f Systems 4318 Email: mbj@tail-f.com 4319 Kent Watsen 4320 Juniper Networks 4322 Email: kwatsen@juniper.net