idnits 2.17.1 draft-ietf-netconf-restconf-12.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 2394 has weird spacing: '... method entry...' == Line 3315 has weird spacing: '...ncoding strin...' == Line 3316 has weird spacing: '...ocation inet:...' == Line 4373 has weird spacing: '...ocation str...' == Line 4383 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). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If the target resource represents a YANG leaf-list, then the PATCH method MUST not change the value of the leaf-list instance. -- The document date (April 12, 2016) is 2934 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) == Outdated reference: A later version (-06) exists of draft-ietf-netconf-yang-library-05 == Outdated reference: A later version (-14) exists of draft-ietf-netmod-rfc6020bis-11 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-yang-json-06 == Outdated reference: A later version (-07) exists of draft-ietf-netmod-yang-metadata-02 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7320 (Obsoleted by RFC 8820) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPath' == Outdated reference: A later version (-14) exists of draft-ietf-netconf-yang-patch-06 Summary: 11 errors (**), 0 flaws (~~), 14 warnings (==), 3 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: October 14, 2016 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 April 12, 2016 10 RESTCONF Protocol 11 draft-ietf-netconf-restconf-12 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 October 14, 2016. 36 Copyright Notice 38 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . . . . . 5 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 55 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6 57 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7 58 1.1.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 59 1.1.5. URI Template . . . . . . . . . . . . . . . . . . . . 9 60 1.1.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 9 61 1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 9 62 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 10 63 1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 11 64 1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 12 65 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 13 66 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 13 67 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 13 68 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 13 69 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 14 70 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 14 71 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 14 72 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 15 73 3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 17 74 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 17 75 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18 76 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 18 77 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19 78 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 19 79 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20 80 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21 81 3.5.1. Encoding Data Resource Identifiers in the Request URI 22 82 3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 25 83 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 25 84 3.6.1. Encoding Operation Resource Input Parameters . . . . 26 85 3.6.2. Encoding Operation Resource Output Parameters . . . . 29 86 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 31 87 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 32 88 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 33 89 3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 34 90 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 34 91 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 35 92 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 35 93 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 94 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 37 95 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 37 96 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 38 97 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 98 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 41 99 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 41 100 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 42 101 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 43 102 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 44 103 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 45 104 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 45 105 4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 46 106 4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 47 107 4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 48 108 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 48 109 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 49 110 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 50 111 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 51 112 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 51 113 5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 52 114 5.3. RESTCONF Meta-Data . . . . . . . . . . . . . . . . . . . 53 115 5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 53 116 5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 54 117 5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 54 118 5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 54 119 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 55 120 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 55 121 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 55 122 6.3. Subscribing to Receive Notifications . . . . . . . . . . 57 123 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 58 124 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 58 125 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 60 126 7.1. Error Response Message . . . . . . . . . . . . . . . . . 62 127 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 64 128 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 70 129 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 70 130 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 71 131 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 71 132 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 72 133 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 72 134 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 76 135 10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 76 136 10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 77 138 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77 139 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 77 140 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 77 141 11.3. application/yang Media Sub Types . . . . . . . . . . . . 78 142 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 79 143 12. Security Considerations . . . . . . . . . . . . . . . . . . . 79 144 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 80 145 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 81 146 14.1. Normative References . . . . . . . . . . . . . . . . . . 81 147 14.2. Informative References . . . . . . . . . . . . . . . . . 83 148 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 84 149 A.1. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 84 150 A.2. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 84 151 A.3. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 85 152 A.4. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 87 153 A.5. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 87 154 A.6. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 88 155 A.7. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 88 156 A.8. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 88 157 A.9. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 89 158 A.10. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 90 159 A.11. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 90 160 A.12. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 91 161 A.13. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 92 162 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 92 163 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 92 164 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 93 165 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 98 166 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 98 167 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 98 168 D.1.2. Retrieve The Server Module Information . . . . . . . 99 169 D.1.3. Retrieve The Server Capability Information . . . . . 101 170 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 102 171 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 102 172 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 103 173 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 103 174 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 104 175 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 104 176 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 107 177 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 110 178 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 111 179 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 111 180 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 112 181 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 113 182 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 113 183 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 113 184 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 115 186 1. Introduction 188 There is a need for standard mechanisms to allow Web applications to 189 access the configuration data, state data, data-model specific 190 protocol operations, and event notifications within a networking 191 device, in a modular and extensible manner. 193 This document defines an HTTP [RFC7230] based protocol called 194 RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or 195 YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using datastores 196 defined in NETCONF [RFC6241]. 198 NETCONF defines configuration datastores and a set of Create, 199 Retrieve, Update, Delete (CRUD) operations that can be used to access 200 these datastores. The YANG language defines the syntax and semantics 201 of datastore content, state data, protocol operations, and event 202 notifications. 204 RESTCONF uses HTTP operations to provide CRUD operations on a 205 conceptual datastore containing YANG-defined data, which is 206 compatible with a server which implements NETCONF datastores. 208 If a RESTCONF server is co-located with a NETCONF server, then there 209 are protocol interactions to be considered, as described in 210 Section 1.4. The server MAY provide access to specific datastores 211 using operation resources, as described in Section 3.6. 213 Configuration data and state data are exposed as resources that can 214 be retrieved with the GET method. Resources representing 215 configuration data can be modified with the DELETE, PATCH, POST, and 216 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 217 or JSON [RFC7159]. 219 Data-model specific operations defined with the YANG "rpc" or 220 "action" statements can be invoked with the POST method. Data-model 221 specific event notifications defined with the YANG "notification" 222 statement can be accessed. 224 1.1. Terminology 226 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 227 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 228 "OPTIONAL" in this document are to be interpreted as described in BCP 229 14, [RFC2119]. 231 1.1.1. NETCONF 233 The following terms are defined in [RFC6241]: 235 o candidate configuration datastore 237 o client 239 o configuration data 241 o datastore 243 o configuration datastore 245 o protocol operation 247 o running configuration datastore 249 o server 251 o startup configuration datastore 253 o state data 255 o user 257 1.1.2. HTTP 259 The following terms are defined in [RFC3986]: 261 o fragment 263 o path 265 o query 267 The following terms are defined in [RFC7230]: 269 o header 271 o message-body 273 o request-line 275 o request URI 277 o status-line 279 The following terms are defined in [RFC7231]: 281 o method 282 o request 284 o resource 286 The following terms are defined in [RFC7232]: 288 o entity tag 290 1.1.3. YANG 292 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 294 o action 296 o container 298 o data node 300 o key leaf 302 o leaf 304 o leaf-list 306 o list 308 o non-presence container (or NP-container) 310 o ordered-by user 312 o presence container (or P-container) 314 o RPC operation 316 o top-level data node 318 1.1.4. Terms 320 The following terms are used within this document: 322 o API resource: a resource with the media type "application/ 323 yang.api+xml" or "application/yang.api+json". 325 o data resource: a resource with the media type "application/ 326 yang.data+xml" or "application/yang.data+json". Containers, 327 leafs, list entries, anydata and anyxml nodes can be data 328 resources. 330 o datastore resource: a resource with the media type "application/ 331 yang.datastore+xml" or "application/yang.datastore+json". 332 Represents a datastore. 334 o edit operation: a RESTCONF operation on a data resource using 335 either a POST, PUT, PATCH, or DELETE method. 337 o event stream resource: This resource represents an SSE (Server- 338 Sent Events) event stream. The content consists of text using the 339 media type "text/event-stream", as defined by the HTML5 340 [W3C.REC-html5-20141028] specification. Each event represents one 341 message generated by the server. It contains a 342 conceptual system or data-model specific event that is delivered 343 within an event notification stream. Also called a "stream 344 resource". 346 o media-type: HTTP uses Internet media types [RFC2046] in the 347 Content-Type and Accept header fields in order to provide open and 348 extensible data typing and type negotiation. 350 o operation: the conceptual RESTCONF operation for a message, 351 derived from the HTTP method, request URI, headers, and message- 352 body. 354 o operation resource: a resource with the media type "application/ 355 yang.operation+xml" or "application/yang.operation+json". 357 o patch: a generic PATCH request on the target datastore or data 358 resource. The media type of the message-body content will 359 identify the patch type in use. 361 o plain patch: a specific PATCH request type that can be used for 362 simple merge operations. 364 o query parameter: a parameter (and its value if any), encoded 365 within the query component of the request URI. 367 o RESTCONF capability: An optional RESTCONF protocol feature 368 supported by the server, which is identified by an IANA registered 369 NETCONF Capability URI, and advertised with an entry in the 370 "capability" leaf-list in Section 9.3. 372 o retrieval request: a request using the GET or HEAD methods. 374 o target resource: the resource that is associated with a particular 375 message, identified by the "path" component of the request URI. 377 o schema resource: a resource with the media type "application/ 378 yang". The YANG representation of the schema can be retrieved by 379 the client with the GET method. 381 o stream list: the set of data resource instances that describe the 382 event stream resources available from the server. This 383 information is defined in the "ietf-restconf-monitoring" module as 384 the "stream" list. It can be retrieved using the target resource 385 "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/ 386 stream". The stream list contains information about each stream, 387 such as the URL to retrieve the event stream data. 389 1.1.5. URI Template 391 Throughout this document, the URI template [RFC6570] syntax 392 "{+restconf}" is used to refer to the RESTCONF API entry point 393 outside of an example. See Section 3.1 for details. 395 For simplicity, all of the examples in this document assume "/ 396 restconf" as the discovered RESTCONF API root path. 398 1.1.6. Tree Diagrams 400 A simplified graphical representation of the data model is used in 401 this document. The meaning of the symbols in these diagrams is as 402 follows: 404 o Brackets "[" and "]" enclose list keys. 406 o Abbreviations before data node names: "rw" means configuration 407 data (read-write) and "ro" state data (read-only). 409 o Symbols after data node names: "?" means an optional node, "!" 410 means a presence container, and "*" denotes a list and leaf-list. 412 o Parentheses enclose choice and case nodes, and case nodes are also 413 marked with a colon (":"). 415 o Ellipsis ("...") stands for contents of subtrees that are not 416 shown. 418 1.2. Subset of NETCONF Functionality 420 RESTCONF does not need to mirror the full functionality of the 421 NETCONF protocol, but it does need to be compatible with NETCONF. 422 RESTCONF achieves this by implementing a subset of the interaction 423 capabilities provided by the NETCONF protocol, for instance, by 424 eliminating datastores and explicit locking. 426 RESTCONF uses HTTP methods to implement the equivalent of NETCONF 427 operations, enabling basic CRUD operations on a hierarchy of 428 conceptual resources. 430 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 431 resources represented by YANG data models. These basic edit 432 operations allow the running configuration to be altered in an all- 433 or-none fashion. 435 RESTCONF is not intended to replace NETCONF, but rather provide an 436 additional interface that follows Representational State Transfer 437 (REST) principles [rest-dissertation], and is compatible with a 438 resource-oriented device abstraction. 440 The following figure shows the system components if a RESTCONF server 441 is co-located with a NETCONF server: 443 +-----------+ +-----------------+ 444 | Web app | <-------> | | 445 +-----------+ HTTP | network device | 446 | | 447 +-----------+ | +-----------+ | 448 | NMS app | <-------> | | datastore | | 449 +-----------+ NETCONF | +-----------+ | 450 +-----------------+ 452 The following figure shows the system components if a RESTCONF server 453 is implemented in a device that does not have a NETCONF server: 455 +-----------+ +-----------------+ 456 | Web app | <-------> | | 457 +-----------+ HTTP | network device | 458 | | 459 +-----------------+ 461 1.3. Data Model Driven API 463 RESTCONF combines the simplicity of the HTTP protocol with the 464 predictability and automation potential of a schema-driven API. 465 Using YANG, a client can predict all management resources, much like 466 using URI Templates [RFC6570], but in a more holistic manner. This 467 strategy obviates the need for responses provided by the server to 468 contain Hypermedia as the Engine of Application State (HATEOAS) 469 links, originally described in Roy Fielding's doctoral dissertation 470 [rest-dissertation]. 472 RESTCONF provides the YANG module capability information supported by 473 the server, in case the client wants to use it. The URIs for custom 474 protocol operations and datastore content are predictable, based on 475 the YANG module definitions. 477 The RESTCONF protocol operates on a conceptual datastore defined with 478 the YANG data modeling language. The server lists each YANG module 479 it supports using the "ietf-yang-library" YANG module, defined in 480 [I-D.ietf-netconf-yang-library]. The server MUST implement the 481 "ietf-yang-library" module, which MUST identify all the YANG modules 482 used by the server. 484 The conceptual datastore contents, data-model-specific operations and 485 event notifications are identified by this set of YANG modules. 487 The classification of data as configuration or non-configuration is 488 derived from the YANG "config" statement. Data ordering behavior is 489 derived from the YANG "ordered-by" statement. 491 The RESTCONF datastore editing model is simple and direct, similar to 492 the behavior of the :writable-running capability in NETCONF. Each 493 RESTCONF edit of a datastore resource is activated upon successful 494 completion of the transaction. 496 1.4. Coexistence with NETCONF 498 RESTCONF can be implemented on a device that supports NETCONF. 500 If the device supports :writable-running, all edits to configuration 501 nodes in {+restconf}/data are performed in the running configuration 502 datastore. The URI template "{+restconf}" is defined in 503 Section 1.1.5. 505 Otherwise, if the device supports :candidate, all edits to 506 configuration nodes in {+restconf}/data are performed in the 507 candidate configuration datastore. The candidate MUST be 508 automatically committed to running immediately after each successful 509 edit. Any edits from other sources that are in the candidate 510 datastore will also be committed. If a confirmed-commit procedure is 511 in progress, then this commit will act as the confirming commit. If 512 the server is expecting a "persist-id" parameter to complete the 513 confirmed commit procedure then the RESTCONF edit operation MUST fail 514 with a "409 Conflict" status-line. 516 If the device supports :startup, the device MUST automatically update 517 the non-volatile "startup datastore", after the running datastore has 518 been updated as a consequence of a RESTCONF edit operation. 520 If a datastore that would be modified by a RESTCONF operation has an 521 active lock, the RESTCONF edit operation MUST fail with a "409 522 Conflict" status-line. 524 1.5. RESTCONF Extensibility 526 There are two extensibility mechanisms built into RESTCONF: 528 o protocol version 530 o optional capabilities 532 This document defines version 1 of the RESTCONF protocol. If a 533 future version of this protocol is defined, then that document will 534 specify how the new version of RESTCONF is identified. It is 535 expected that a different entry point {+restconf2} would be defined. 536 The server will advertise all protocol versions that it supports in 537 its host-meta data. 539 In this example, the server supports both RESTCONF version 1 and a 540 fictitious version 2. 542 Request 543 ------- 544 GET /.well-known/host-meta HTTP/1.1 545 Host: example.com 546 Accept: application/xrd+xml 548 Response 549 -------- 550 HTTP/1.1 200 OK 551 Content-Type: application/xrd+xml 552 Content-Length: nnn 554 555 556 557 559 RESTCONF also supports a server-defined list of optional 560 capabilities, which are listed by a server using the 561 "ietf-restconf-monitoring" module defined in Section 9.3. For 562 example, this document defines several query parameters in 563 Section 4.8. Each optional parameter has a corresponding capability 564 URI defined in Section 9.1.1 that is advertised by the server if 565 supported. 567 The "capabilities" list can identify any sort of server extension. 568 Typically this extension mechanism is used to identify optional query 569 parameters but it is not limited to that purpose. For example, the 570 "defaults" URI defined in Section 9.1.2 specifies a mandatory URI 571 identifying server defaults handling behavior. 573 A new sub-resource type could be identified with a capability if it 574 is optional to implement. Mandatory protocol features and new 575 resource types require a new revision of the RESTCONF protocol. 577 2. Transport Protocol Requirements 579 2.1. Integrity and Confidentiality 581 HTTP [RFC7230] is an application layer protocol that may be layered 582 on any reliable transport-layer protocol. RESTCONF is defined on top 583 of HTTP, but due to the sensitive nature of the information conveyed, 584 RESTCONF requires that the transport-layer protocol provides both 585 data integrity and confidentiality. A RESTCONF server MUST support 586 the TLS protocol [RFC5246]. The RESTCONF protocol MUST NOT be used 587 over HTTP without using the TLS protocol. 589 HTTP/1.1 pipelining MUST be supported by the server. Responses MUST 590 be sent in the same order that requests are received. No other 591 versions of HTTP are supported for use with RESTCONF. 593 2.2. HTTPS with X.509v3 Certificates 595 Given the nearly ubiquitous support for HTTP over TLS [RFC7230], 596 RESTCONF implementations MUST support the "https" URI scheme, which 597 has the IANA assigned default port 443. 599 RESTCONF servers MUST present an X.509v3 based certificate when 600 establishing a TLS connection with a RESTCONF client. The use the 601 X.509v3 based certificates is consistent with NETCONF over TLS 602 [RFC7589]. 604 2.3. Certificate Validation 606 The RESTCONF client MUST either use X.509 certificate path validation 607 [RFC5280] to verify the integrity of the RESTCONF server's TLS 608 certificate, or match the presented X.509 certificate with locally 609 configured certificate fingerprints. 611 The presented X.509 certificate MUST also be considered valid if it 612 matches a locally configured certificate fingerprint. If X.509 613 certificate path validation fails and the presented X.509 certificate 614 does not match a locally configured certificate fingerprint, the 615 connection MUST be terminated as defined in [RFC5246]. 617 2.4. Authenticated Server Identity 619 The RESTCONF client MUST check the identity of the server according 620 to Section 6 of [RFC6125], including processing the outcome as 621 described in Section 6.6 of [RFC6125]. 623 2.5. Authenticated Client Identity 625 The RESTCONF server MUST authenticate client access to any protected 626 resource. If the RESTCONF client is not authorized to access a 627 resource, the server MUST send an HTTP response with "401 628 Unauthorized" status-line, as defined in Section 3.1 of [RFC7235]. 630 To authenticate a client, a RESTCONF server MUST use TLS based client 631 certificates (Section 7.4.6 of [RFC5246]), or MUST use any HTTP 632 authentication scheme defined in the HTTP Authentication Scheme 633 Registry (Section 5.1 in [RFC7235]). A server MAY also support the 634 combination of both client certificates and an HTTP client 635 authentication scheme, with the determination of how to process this 636 combination left as an implementation decision. 638 The RESTCONF client identity derived from the authentication 639 mechanism used is hereafter known as the "RESTCONF username" and 640 subject to the NETCONF Access Control Module (NACM) [RFC6536]. When 641 a client certificate is presented, the RESTCONF username MUST be 642 derived using the algorithm defined in Section 7 of [RFC7589]. For 643 all other cases, when HTTP authentication is used, the RESTCONF 644 username MUST be provided by the HTTP authentication scheme used. 646 3. Resources 648 The RESTCONF protocol operates on a hierarchy of resources, starting 649 with the top-level API resource itself (Section 3.1). Each resource 650 represents a manageable component within the device. 652 A resource can be considered a collection of data and the set of 653 allowed methods on that data. It can contain nested child resources. 654 The child resource types and methods allowed on them are data-model 655 specific. 657 A resource has a media type identifier, represented by the 658 "Content-Type" header in the HTTP response message. A resource can 659 contain zero or more nested resources. A resource can be created and 660 deleted independently of its parent resource, as long as the parent 661 resource exists. 663 All RESTCONF resource types are defined in this document except 664 specific datastore contents, protocol operations, and event 665 notifications. The syntax and semantics for these resource types are 666 defined in YANG modules. 668 The RESTCONF resources are accessed via a set of URIs defined in this 669 document. The set of YANG modules supported by the server will 670 determine the data model specific operations, top-level data nodes, 671 and event notification messages supported by the server. 673 The RESTCONF protocol does not include a data resource discovery 674 mechanism. Instead, the definitions within the YANG modules 675 advertised by the server are used to construct a predictable 676 operation or data resource identifier. 678 3.1. Root Resource Discovery 680 In line with the best practices defined by [RFC7320], RESTCONF 681 enables deployments to specify where the RESTCONF API is located. 682 When first connecting to a RESTCONF server, a RESTCONF client MUST 683 determine the root of the RESTCONF API. There MUST be exactly one 684 "restconf" link relation returned by the device. 686 The client discovers this by getting the "/.well-known/host-meta" 687 resource ([RFC6415]) and using the element containing the 688 "restconf" attribute : 690 Example returning /restconf: 692 Request 693 ------- 694 GET /.well-known/host-meta HTTP/1.1 695 Host: example.com 696 Accept: application/xrd+xml 698 Response 699 -------- 700 HTTP/1.1 200 OK 701 Content-Type: application/xrd+xml 702 Content-Length: nnn 704 705 706 707 After discovering the RESTCONF API root, the client MUST prepend it 708 to any subsequent request to a RESTCONF resource. In this example, 709 the client would use the path "/restconf" as the RESTCONF entry 710 point. 712 Example returning /top/restconf: 714 Request 715 ------- 716 GET /.well-known/host-meta HTTP/1.1 717 Host: example.com 718 Accept: application/xrd+xml 720 Response 721 -------- 722 HTTP/1.1 200 OK 723 Content-Type: application/xrd+xml 724 Content-Length: nnn 726 727 728 730 In this example, the client would use the path "/top/restconf" as the 731 RESTCONF entry point. 733 The client can now determine the operation resources supported by the 734 the server. In this example a custom "play" operation is supported: 736 Request 737 ------- 738 GET /top/restconf/operations HTTP/1.1 739 Host: example.com 740 Accept: application/yang.api+json 742 Response 743 -------- 744 HTTP/1.1 200 OK 745 Date: Mon, 23 Apr 2012 17:01:00 GMT 746 Server: example-server 747 Cache-Control: no-cache 748 Pragma: no-cache 749 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 750 Content-Type: application/yang.api+json 752 { "operations" : { "example-jukebox:play" : {} } } 754 If the XRD contains more than one link relation, then only the 755 relation named "restconf" is relevant to this specification. 757 3.2. RESTCONF Media Types 759 The RESTCONF protocol defines a set of application specific media 760 types to identify each of the available resource types. The 761 following resource types are defined in RESTCONF: 763 +-----------+---------------------------------+ 764 | Resource | Media Type | 765 +-----------+---------------------------------+ 766 | API | application/yang.api+xml | 767 | | application/yang.api+json | 768 | Datastore | application/yang.datastore+xml | 769 | | application/yang.datastore+json | 770 | Data | application/yang.data+xml | 771 | | application/yang.data+json | 772 | [none] | application/yang.errors+xml | 773 | | application/yang.errors+json | 774 | Operation | application/yang.operation+xml | 775 | | application/yang.operation+json | 776 | Schema | application/yang | 777 +-----------+---------------------------------+ 779 RESTCONF Media Types 781 3.3. API Resource 783 The API resource contains the entry points for the RESTCONF datastore 784 and operation resources. It is the top-level resource located at 785 {+restconf} and has the media type "application/yang.api+xml" or 786 "application/yang.api+json". 788 YANG Tree Diagram for an API Resource: 790 +--rw restconf 791 +--rw data 792 +--rw operations 793 +--ro yang-library-version 795 The "application/yang.api" restconf-media-type extension in the 796 "ietf-restconf" module defined in Section 8 is used to specify the 797 structure and syntax of the conceptual child resources within the API 798 resource. 800 The API resource can be retrieved with the GET method. 802 This resource has the following child resources: 804 +----------------------+--------------------------------+ 805 | Child Resource | Description | 806 +----------------------+--------------------------------+ 807 | data | Contains all data resources | 808 | operations | Data-model specific operations | 809 | yang-library-version | ietf-yang-library module date | 810 +----------------------+--------------------------------+ 812 RESTCONF API Resource 814 3.3.1. {+restconf}/data 816 This mandatory resource represents the combined configuration and 817 state data resources that can be accessed by a client. It cannot be 818 created or deleted by the client. The datastore resource type is 819 defined in Section 3.4. 821 Example: 823 This example request by the client would retrieve only the non- 824 configuration data nodes that exist within the "library" resource, 825 using the "content" query parameter (see Section 4.8.1). 827 GET /restconf/data/example-jukebox:jukebox/library 828 ?content=nonconfig HTTP/1.1 829 Host: example.com 830 Accept: application/yang.data+xml 832 The server might respond: 834 HTTP/1.1 200 OK 835 Date: Mon, 23 Apr 2012 17:01:30 GMT 836 Server: example-server 837 Cache-Control: no-cache 838 Pragma: no-cache 839 Content-Type: application/yang.data+xml 841 842 42 843 59 844 374 845 847 3.3.2. {+restconf}/operations 848 This optional resource is a container that provides access to the 849 data-model specific protocol operations supported by the server. The 850 server MAY omit this resource if no data-model specific operations 851 are advertised. 853 Any data-model specific protocol operations defined in the YANG 854 modules advertised by the server MUST be available as child nodes of 855 this resource. 857 Operation resources are defined in Section 3.6. 859 3.3.3. {+restconf}/yang-library-version 861 This mandatory leaf identifies the revision date of the 862 "ietf-yang-library" YANG module that is implemented by this server. 864 Example: 866 GET /restconf/yang-library-version HTTP/1.1 867 Host: example.com 868 Accept: application/yang.data+xml 870 The server might respond (response wrapped for display purposes): 872 HTTP/1.1 200 OK 873 Date: Mon, 23 Apr 2012 17:01:30 GMT 874 Server: example-server 875 Cache-Control: no-cache 876 Pragma: no-cache 877 Content-Type: application/yang.data+xml 879 881 2016-04-09 882 884 3.4. Datastore Resource 886 The "{+restconf}/data" subtree represents the datastore resource 887 type, which is a collection of configuration data and state data 888 nodes. 890 This resource type is an abstraction of the system's underlying 891 datastore implementation. It is used to simplify resource editing 892 for the client. The RESTCONF datastore resource is a conceptual 893 collection of all configuration and state data that is present on the 894 device. 896 Configuration edit transaction management and configuration 897 persistence are handled by the server and not controlled by the 898 client. A datastore resource can be written directly with the POST 899 and PATCH methods. Each RESTCONF edit of a datastore resource is 900 saved to non-volatile storage by the server, if the server supports 901 non-volatile storage of configuration data. 903 3.4.1. Edit Collision Detection 905 Two "edit collision detection" mechanisms are provided in RESTCONF, 906 for datastore and data resources. 908 3.4.1.1. Timestamp 910 The last change time is maintained and the "Last-Modified" 911 ([RFC7232], Section 2.2) header is returned in the response for a 912 retrieval request. The "If-Unmodified-Since" header can be used in 913 edit operation requests to cause the server to reject the request if 914 the resource has been modified since the specified timestamp. 916 The server SHOULD maintain a last-modified timestamp for the top- 917 level {+restconf}/data resource. This timestamp is only affected by 918 configuration data resources, and MUST NOT be updated for changes to 919 non-configuration data. 921 3.4.1.2. Entity tag 923 A unique opaque string is maintained and the "ETag" ([RFC7232], 924 Section 2.3) header is returned in the response for a retrieval 925 request. The "If-Match" header can be used in edit operation 926 requests to cause the server to reject the request if the resource 927 entity tag does not match the specified value. 929 The server MUST maintain an entity tag for the top-level {+restconf}/ 930 data resource. This entity tag is only affected by configuration 931 data resources, and MUST NOT be updated for changes to non- 932 configuration data. 934 3.4.1.3. Update Procedure 936 Changes to configuration data resources affect the timestamp and 937 entity tag to that resource, any ancestor data resources, and the 938 datastore resource. 940 For example, an edit to disable an interface might be done by setting 941 the leaf "/interfaces/interface/enabled" to "false". The "enabled" 942 data node and its ancestors (one "interface" list instance, and the 943 "interfaces" container) are considered to be changed. The datastore 944 is considered to be changed when any top-level configuration data 945 node is changed (e.g., "interfaces"). 947 3.5. Data Resource 949 A data resource represents a YANG data node that is a descendant node 950 of a datastore resource. Each YANG-defined data node can be uniquely 951 targeted by the request-line of an HTTP operation. Containers, 952 leafs, leaf-list entries, list entries, anydata and anyxml nodes are 953 data resources. 955 The representation maintained for each data resource is the YANG 956 defined subtree for that node. HTTP operations on a data resource 957 affect both the targeted data node and all its descendants, if any. 959 For configuration data resources, the server MAY maintain a last- 960 modified timestamp for the resource, and return the "Last-Modified" 961 header when it is retrieved with the GET or HEAD methods. 963 The "Last-Modified" header information can be used by a RESTCONF 964 client in subsequent requests, within the "If-Modified-Since" and 965 "If-Unmodified-Since" headers. 967 If maintained, the resource timestamp MUST be set to the current time 968 whenever the resource or any configuration resource within the 969 resource is altered. If not maintained, then the resource timestamp 970 for the datastore MUST be used instead. 972 This timestamp is only affected by configuration data resources, and 973 MUST NOT be updated for changes to non-configuration data. 975 For configuration data resources, the server SHOULD maintain a 976 resource entity tag for the resource, and return the "ETag" header 977 when it is retrieved as the target resource with the GET or HEAD 978 methods. If maintained, the resource entity tag MUST be updated 979 whenever the resource or any configuration resource within the 980 resource is altered. If not maintained, then the resource entity tag 981 for the datastore MUST be used instead. 983 The "ETag" header information can be used by a RESTCONF client in 984 subsequent requests, within the "If-Match" and "If-None-Match" 985 headers. 987 This entity tag is only affected by configuration data resources, and 988 MUST NOT be updated for changes to non-configuration data. 990 A data resource can be retrieved with the GET method. Data resources 991 are accessed via the "{+restconf}/data" entry point. This sub-tree 992 is used to retrieve and edit data resources. 994 A configuration data resource can be altered by the client with some 995 or all of the edit operations, depending on the target resource and 996 the specific operation. Refer to Section 4 for more details on edit 997 operations. 999 3.5.1. Encoding Data Resource Identifiers in the Request URI 1001 In YANG, data nodes are identified with an absolute XPath expression, 1002 defined in [XPath], starting from the document root to the target 1003 resource. In RESTCONF, URI-encoded path expressions are used 1004 instead. 1006 A predictable location for a data resource is important, since 1007 applications will code to the YANG data model module, which uses 1008 static naming and defines an absolute path location for all data 1009 nodes. 1011 A RESTCONF data resource identifier is not an XPath expression. It 1012 is encoded from left to right, starting with the top-level data node, 1013 according to the "api-path" rule in Section 3.5.1.1. The node name 1014 of each ancestor of the target resource node is encoded in order, 1015 ending with the node name for the target resource. If a node in the 1016 path is defined in another module than its parent node, then module 1017 name followed by a colon character (":") is prepended to the node 1018 name in the resource identifier. See Section 3.5.1.1 for details. 1020 If a data node in the path expression is a YANG leaf-list node, then 1021 the leaf-list value MUST be encoded according to the following rules: 1023 o The instance-identifier for the leaf-list MUST be encoded using 1024 one path segment [RFC3986]. 1026 o The path segment is constructed by having the leaf-list name, 1027 followed by an "=" character, followed by the leaf-list value. 1028 (e.g., /restconf/data/top-leaflist=fred). 1030 If a data node in the path expression is a YANG list node, then the 1031 key values for the list (if any) MUST be encoded according to the 1032 following rules: 1034 o The key leaf values for a data resource representing a YANG list 1035 MUST be encoded using one path segment [RFC3986]. 1037 o If there is only one key leaf value, the path segment is 1038 constructed by having the list name, followed by an "=" character, 1039 followed by the single key leaf value. 1041 o If there are multiple key leaf values, the path segment is 1042 constructed by having the list name, followed by the value of each 1043 leaf identified in the "key" statement, encoded in the order 1044 specified in the YANG "key" statement. Each key leaf value except 1045 the last one is followed by a comma character. 1047 o The key value is specified as a string, using the canonical 1048 representation for the YANG data type. Any reserved characters 1049 MUST be percent-encoded, according to [RFC3986], section 2.1. 1051 o All the components in the "key" statement MUST be encoded. 1052 Partial instance identifiers are not supported. 1054 o Since missing key values are not allowed, two consecutive commas 1055 are interpreted as a zero-length string. (example: 1056 list=foo,,baz). 1058 o The "list-instance" ABNF rule defined in Section 3.5.1.1 1059 represents the syntax of a list instance identifier. 1061 o Resource URI values returned in Location headers for data 1062 resources MUST identify the module name, even if there are no 1063 conflicting local names when the resource is created. This 1064 ensures the correct resource will be identified even if the server 1065 loads a new module that the old client does not know about. 1067 Examples: 1069 container top { 1070 list list1 { 1071 key "key1 key2 key3"; 1072 ... 1073 list list2 { 1074 key "key4 key5"; 1075 ... 1076 leaf X { type string; } 1077 } 1078 } 1079 leaf-list Y { 1080 type uint32; 1081 } 1082 } 1084 For the above YANG definition, a target resource URI for leaf "X" 1085 would be encoded as follows (line wrapped for display purposes only): 1087 /restconf/data/example-top:top/list1=key1,key2,key3/ 1088 list2=key4,key5/X 1090 For the above YANG definition, a target resource URI for leaf-list 1091 "Y" would be encoded as follows: 1093 /restconf/data/example-top:top/Y=instance-value 1095 The following example shows how reserved characters are percent- 1096 encoded within a key value. The value of "key1" contains a comma, 1097 single-quote, double-quote, colon, double-quote, space, and forward 1098 slash. (,'":" /). Note that double-quote is not a reserved 1099 characters and does not need to be percent-encoded. The value of 1100 "key2" is the empty string, and the value of "key3" is the string 1101 "foo". 1103 Example URL: 1105 /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo 1107 3.5.1.1. ABNF For Data Resource Identifiers 1109 The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to 1110 construct RESTCONF path identifiers: 1112 api-path = "/" | 1113 ("/" api-identifier 1114 0*("/" (api-identifier | list-instance ))) 1116 api-identifier = [module-name ":"] identifier ;; note 1 1118 module-name = identifier 1120 list-instance = api-identifier "=" key-value ["," key-value]* 1122 key-value = string ;; note 1 1124 string = 1126 ;; An identifier MUST NOT start with 1127 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 1128 identifier = (ALPHA / "_") 1129 *(ALPHA / DIGIT / "_" / "-" / ".") 1131 Note 1: The syntax for "api-identifier" and "key-value" MUST conform 1132 to the JSON identifier encoding rules in Section 4 of 1133 [I-D.ietf-netmod-yang-json]. 1135 3.5.2. Defaults Handling 1137 RESTCONF requires that a server report its default handling mode (see 1138 Section 9.1.2 for details). If the optional "with-defaults" query 1139 parameter is supported by the server, a client may use it to control 1140 retrieval of default values (see Section 4.8.9 for details). 1142 If a leaf or leaf-list is missing from the configuration and there is 1143 a YANG-defined default for that data resource, then the server MUST 1144 use the YANG-defined default as the configured value. 1146 If the target of a GET method is a data node that represents a leaf 1147 that has a default value, and the leaf has not been configured yet, 1148 the server MUST return the default value that is in use by the 1149 server. 1151 If the target of a GET method is a data node that represents a 1152 container or list that has any child resources with default values, 1153 for the child resources that have not been given value yet, the 1154 server MAY return the default values that are in use by the server, 1155 in accordance with its reported default handing mode and query 1156 parameters passed by the client. 1158 3.6. Operation Resource 1160 An operation resource represents a protocol operation defined with 1161 the YANG "rpc" statement or a data-model specific action defined with 1162 a YANG "action" statement. It is invoked using a POST method on the 1163 operation resource. 1165 An RPC operation is invoked as: 1167 POST {+restconf}/operations/ 1169 The field identifies the module name and rpc identifier 1170 string for the desired operation. 1172 For example, if "module-A" defined a "reset" rpc operation, then 1173 invoking the operation from "module-A" would be requested as follows: 1175 POST /restconf/operations/module-A:reset HTTP/1.1 1176 Server example.com 1178 An action is invoked as: 1180 POST {+restconf}/data// 1182 where contains the path to the data node 1183 where the action is defined, and is the name of the action. 1185 For example, if "module-A" defined a "reset-all" action in the 1186 container "interfaces", then invoking this action would be requested 1187 as follows: 1189 POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 1190 Server example.com 1192 If the "rpc" or "action" statement has an "input" section, then a 1193 message-body MAY be sent by the client in the request, otherwise the 1194 request message MUST NOT include a message-body. If the "input" 1195 objcet tree contains mandatory parameters, then a message-body MUST 1196 be sent by the client. A mandatory parameter is a leaf or choice 1197 with a "mandatory" statement set to "true", or a list or leaf-list 1198 than have a "min-elements" statement value greater than zero. 1200 If the operation is invoked without errors, and if the "rpc" or 1201 "action" statement has an "output" section, then a message-body MAY 1202 be sent by the server in the response, otherwise the response message 1203 MUST NOT include a message-body in the response message, and MUST 1204 send a "204 No Content" status-line instead. 1206 If the operation input is not valid, or the operation is invoked but 1207 errors occur, then a message-body MUST be sent by the server, 1208 containing an "errors" resource, as defined in Section 3.9. A 1209 detailed example of an operation resource error response can be found 1210 in Section 3.6.3. 1212 All operation resources representing RPC operations supported by the 1213 server MUST be identified in the {+restconf}/operations subtree 1214 defined in Section 3.3.2. Operation resources representing YANG 1215 actions are not identified in this subtree since they are invoked 1216 using a URI within the {+restconf}/data subtree. 1218 3.6.1. Encoding Operation Resource Input Parameters 1220 If the "rpc" or "action" statement has an "input" section, then the 1221 "input" node is provided in the message-body, corresponding to the 1222 YANG data definition statements within the "input" section. 1224 Examples: 1226 The following YANG module is used for the RPC operation examples in 1227 this section. 1229 module example-ops { 1230 namespace "https://example.com/ns/example-ops"; 1231 prefix "ops"; 1232 revision "2016-03-10"; 1234 rpc reboot { 1235 input { 1236 leaf delay { 1237 units seconds; 1238 type uint32; 1239 default 0; 1240 } 1241 leaf message { type string; } 1242 leaf language { type string; } 1243 } 1244 } 1246 rpc get-reboot-info { 1247 output { 1248 leaf reboot-time { 1249 units seconds; 1250 type uint32; 1251 } 1252 leaf message { type string; } 1253 leaf language { type string; } 1254 } 1255 } 1256 } 1258 The following YANG module is used for the YANG action examples in 1259 this section. 1261 module example-actions { 1262 yang-version 1.1; 1263 namespace "https://example.com/ns/example-actions"; 1264 prefix "act"; 1265 import ietf-yang-types { prefix yang; } 1266 revision "2016-03-10"; 1268 container interfaces { 1269 list interface { 1270 key name; 1271 leaf name { type string; } 1273 action reset { 1274 input { 1275 leaf delay { 1276 units seconds; 1277 type uint32; 1278 default 0; 1279 } 1280 } 1281 } 1283 action get-last-reset-time { 1284 output { 1285 leaf last-reset { 1286 type yang:date-and-time; 1287 mandatory true; 1288 } 1289 } 1290 } 1291 } 1292 } 1294 } 1296 RPC Input Example: 1298 The client might send the following POST request message to invoke 1299 the "reboot" RPC operation: 1301 POST /restconf/operations/example-ops:reboot HTTP/1.1 1302 Host: example.com 1303 Content-Type: application/yang.operation+xml 1305 1306 600 1307 Going down for system maintenance 1308 en-US 1309 1311 The server might respond: 1313 HTTP/1.1 204 No Content 1314 Date: Mon, 25 Apr 2012 11:01:00 GMT 1315 Server: example-server 1317 The same example request message is shown here using JSON encoding: 1319 POST /restconf/operations/example-ops:reboot HTTP/1.1 1320 Host: example.com 1321 Content-Type: application/yang.operation+json 1322 { 1323 "example-ops:input" : { 1324 "delay" : 600, 1325 "message" : "Going down for system maintenance", 1326 "language" : "en-US" 1327 } 1328 } 1330 Action Input Example: 1332 The client might send the following POST request message to invoke 1333 the "reset" action (text wrap for display purposes): 1335 POST /restconf/data/example-actions:interfaces/interface=eth0 1336 /reset HTTP/1.1 1337 Host: example.com 1338 Content-Type: application/yang.operation+xml 1340 1341 600 1342 1344 The server might respond: 1346 HTTP/1.1 204 No Content 1347 Date: Mon, 25 Apr 2012 11:01:00 GMT 1348 Server: example-server 1350 The same example request message is shown here using JSON encoding 1351 (text wrap for display purposes): 1353 POST /restconf/data/example-actions:interfaces/interface=eth0 1354 /reset HTTP/1.1 1355 Host: example.com 1356 Content-Type: application/yang.operation+json 1358 { "example-actions:input" : { 1359 "delay" : 600 1360 } 1361 } 1363 3.6.2. Encoding Operation Resource Output Parameters 1365 If the "rpc" or "action" statement has an "output" section, then the 1366 "output" node is provided in the message-body, corresponding to the 1367 YANG data definition statements within the "output" section. 1369 The request URI is not returned in the response. This URI might have 1370 context information required to associate the output to the specific 1371 "rpc" or "action" statement used in the request. 1373 Examples: 1375 RPC Output Example: 1377 The "example-ops" YANG module defined in Section 3.6.1 is used for 1378 this example. 1380 The client might send the following POST request message to invoke 1381 the "get-reboot-info" operation: 1383 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 1384 Host: example.com 1385 Accept: application/yang.operation+json 1387 The server might respond: 1389 HTTP/1.1 200 OK 1390 Date: Mon, 25 Apr 2012 11:10:30 GMT 1391 Server: example-server 1392 Content-Type: application/yang.operation+json 1394 { 1395 "example-ops:output" : { 1396 "reboot-time" : 30, 1397 "message" : "Going down for system maintenance", 1398 "language" : "en-US" 1399 } 1400 } 1402 The same response is shown here using XML encoding: 1404 HTTP/1.1 200 OK 1405 Date: Mon, 25 Apr 2012 11:10:30 GMT 1406 Server: example-server 1407 Content-Type: application/yang.operation+xml 1409 1410 30 1411 Going down for system maintenance 1412 en-US 1413 1415 Action Output Example: 1417 The "example-actions" YANG module defined in Section 3.6.1 is used 1418 for this example. 1420 The client might send the following POST request message to invoke 1421 the "get-last-reset-time" action: 1423 POST /restconf/data/example-actions:interfaces/interface=eth0 1424 /get-last-reset-time HTTP/1.1 1425 Host: example.com 1426 Accept: application/yang.operation+json 1428 The server might respond: 1430 HTTP/1.1 200 OK 1431 Date: Mon, 25 Apr 2012 11:10:30 GMT 1432 Server: example-server 1433 Content-Type: application/yang.operation+json 1435 { 1436 "example-actions:output" : { 1437 "last-reset" : "2015-10-10T02:14:11Z" 1438 } 1439 } 1441 3.6.3. Encoding Operation Resource Errors 1443 If any errors occur while attempting to invoke the operation or 1444 action, then an "errors" media type is returned with the appropriate 1445 error status. 1447 Using the "reboot" operation from the example in Section 3.6.1, the 1448 client might send the following POST request message: 1450 POST /restconf/operations/example-ops:reboot HTTP/1.1 1451 Host: example.com 1452 Content-Type: application/yang.operation+xml 1454 1455 -33 1456 Going down for system maintenance 1457 en-US 1458 1460 The server might respond with an "invalid-value" error: 1462 HTTP/1.1 400 Bad Request 1463 Date: Mon, 25 Apr 2012 11:10:30 GMT 1464 Server: example-server 1465 Content-Type: application/yang.errors+xml 1467 1468 1469 protocol 1470 invalid-value 1471 1472 /ops:input/ops:delay 1473 1474 Invalid input parameter 1475 1476 1478 The same response is shown here in JSON encoding: 1480 HTTP/1.1 400 Bad Request 1481 Date: Mon, 25 Apr 2012 11:10:30 GMT 1482 Server: example-server 1483 Content-Type: application/yang.errors+json 1485 { "ietf-restconf:errors" : { 1486 "error" : [ 1487 { 1488 "error-type" : "protocol", 1489 "error-tag" : "invalid-value", 1490 "error-path" : "/example-ops:input/delay", 1491 "error-message" : "Invalid input parameter", 1492 } 1493 ] 1494 } 1495 } 1497 3.7. Schema Resource 1499 The server can optionally support retrieval of the YANG modules it 1500 supports. If retrieval is supported, then the "schema" leaf MUST be 1501 present in the associated "module" list entry, defined in 1502 [I-D.ietf-netconf-yang-library]. 1504 To retrieve a YANG module, a client first needs to get the URL for 1505 retrieving the schema, which is stored in the "schema" leaf. Note 1506 that there is no required structure for this URL. The URL value 1507 shown below is just an example. 1509 The client might send the following GET request message: 1511 GET /restconf/data/ietf-yang-library:modules/module= 1512 example-jukebox,2015-04-04/schema HTTP/1.1 1513 Host: example.com 1514 Accept: application/yang.data+json 1516 The server might respond: 1518 HTTP/1.1 200 OK 1519 Date: Thu, 11 Feb 2016 11:10:30 GMT 1520 Server: example-server 1521 Content-Type: application/yang.data+json 1523 { 1524 "ietf-yang-library:schema": 1525 "https://example.com/mymodules/example-jukebox/2015-04-04" 1526 } 1528 Next the client needs to retrieve the actual YANG schema. 1530 The client might send the following GET request message: 1532 GET https://example.com/mymodules/example-jukebox/2015-04-04 1533 HTTP/1.1 1534 Host: example.com 1535 Accept: application/yang 1537 The server might respond: 1539 HTTP/1.1 200 OK 1540 Date: Thu, 11 Feb 2016 11:10:31 GMT 1541 Server: example-server 1542 Content-Type: application/yang 1544 module example-jukebox { 1546 // contents of YANG module deleted for this example... 1548 } 1550 3.8. Event Stream Resource 1552 An "event stream" resource represents a source for system generated 1553 event notifications. Each stream is created and modified by the 1554 server only. A client can retrieve a stream resource or initiate a 1555 long-poll server sent event stream, using the procedure specified in 1556 Section 6.3. 1558 A notification stream functions according to the NETCONF 1559 Notifications specification [RFC5277]. The available streams can be 1560 retrieved from the stream list, which specifies the syntax and 1561 semantics of a stream resource. 1563 3.9. Errors Media Type 1565 An "errors" media type is a collection of error information that is 1566 sent as the message-body in a server response message, if an error 1567 occurs while processing a request message. It is not considered a 1568 resource type because no instances can be retrieved with a GET 1569 request. 1571 The "ietf-restconf" YANG module contains the "application/ 1572 yang.errors" restconf-media-type extension which specifies the syntax 1573 and semantics of an "errors" media type. RESTCONF error handling 1574 behavior is defined in Section 7. 1576 4. Operations 1578 The RESTCONF protocol uses HTTP methods to identify the CRUD 1579 operation requested for a particular resource. 1581 The following table shows how the RESTCONF operations relate to 1582 NETCONF protocol operations: 1584 +----------+--------------------------------------------+ 1585 | RESTCONF | NETCONF | 1586 +----------+--------------------------------------------+ 1587 | OPTIONS | none | 1588 | HEAD | none | 1589 | GET | , | 1590 | POST | (operation="create") | 1591 | POST | invoke any operation | 1592 | PUT | (operation="create/replace") | 1593 | PATCH | (operation="merge") | 1594 | DELETE | (operation="delete") | 1595 +----------+--------------------------------------------+ 1597 CRUD Methods in RESTCONF 1599 The NETCONF "remove" operation attribute is not supported by the HTTP 1600 DELETE method. The resource must exist or the DELETE method will 1601 fail. The PATCH method is equivalent to a "merge" operation when 1602 using a plain patch (see Section 4.6.1); other media-types may 1603 provide more granular control. 1605 Access control mechanisms MUST be used to limit what operations can 1606 be used. In particular, RESTCONF is compatible with the NETCONF 1607 Access Control Model (NACM) [RFC6536], as there is a specific mapping 1608 between RESTCONF and NETCONF operations, defined in Section 4. The 1609 resource path needs to be converted internally by the server to the 1610 corresponding YANG instance-identifier. Using this information, the 1611 server can apply the NACM access control rules to RESTCONF messages. 1613 The server MUST NOT allow any operation to any resources that the 1614 client is not authorized to access. 1616 Operations are applied to a single data resource instance at once. 1617 The server MUST NOT allow any operation to be applied to multiple 1618 instances of a YANG list or leaf-list. 1620 Implementation of all methods (except PATCH) are defined in 1621 [RFC7231]. This section defines the RESTCONF protocol usage for each 1622 HTTP method. 1624 4.1. OPTIONS 1626 The OPTIONS method is sent by the client to discover which methods 1627 are supported by the server for a specific resource (e.g., GET, POST, 1628 DELETE, etc.). The server MUST implement this method. 1630 If the PATCH method is supported, then the "Accept-Patch" header MUST 1631 be supported and returned in the response to the OPTIONS request, as 1632 defined in [RFC5789]. 1634 4.2. HEAD 1636 The HEAD method is sent by the client to retrieve just the headers 1637 that would be returned for the comparable GET method, without the 1638 response message-body. It is supported for all resource types, 1639 except operation resources. 1641 The request MUST contain a request URI that contains at least the 1642 entry point. The same query parameters supported by the GET method 1643 are supported by the HEAD method. 1645 The access control behavior is enforced as if the method was GET 1646 instead of HEAD. The server MUST respond the same as if the method 1647 was GET instead of HEAD, except that no response message-body is 1648 included. 1650 4.3. GET 1651 The GET method is sent by the client to retrieve data and meta-data 1652 for a resource. It is supported for all resource types, except 1653 operation resources. The request MUST contain a request URI that 1654 contains at least the entry point. 1656 The server MUST NOT return any data resources for which the user does 1657 not have read privileges. If the user is not authorized to read the 1658 target resource, an error response containing a "401 Unauthorized" 1659 status-line SHOULD be returned. A server MAY return a "404 Not 1660 Found" status-line, as described in section 6.5.3 in [RFC7231]. 1662 If the user is authorized to read some but not all of the target 1663 resource, the unauthorized content is omitted from the response 1664 message-body, and the authorized content is returned to the client. 1666 If any content is returned to the client, then the server MUST send a 1667 valid response message-body. More than one element MUST NOT be 1668 returned for XML encoding. 1670 If a retrieval request for a data resource representing a YANG leaf- 1671 list or list object identifies more than one instance, and XML 1672 encoding is used in the response, then an error response containing a 1673 "400 Bad Request" status-line MUST be returned by the server. 1675 If the target resource of a retrieval request is for an operation 1676 resource then a "405 Method Not Allowed" status-line MUST be returned 1677 by the server. 1679 Note that the way that access control is applied to data resources is 1680 completely incompatible with HTTP caching. The Last-Modified and 1681 ETag headers maintained for a data resource are not affected by 1682 changes to the access control rules for that data resource. It is 1683 possible for the representation of a data resource that is visible to 1684 a particular client to be changed without detection via the Last- 1685 Modified or ETag values. 1687 Example: 1689 The client might request the response headers for an XML 1690 representation of the a specific "album" resource: 1692 GET /restconf/data/example-jukebox:jukebox/ 1693 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1694 Host: example.com 1695 Accept: application/yang.data+xml 1697 The server might respond: 1699 HTTP/1.1 200 OK 1700 Date: Mon, 23 Apr 2012 17:02:40 GMT 1701 Server: example-server 1702 Content-Type: application/yang.data+xml 1703 Cache-Control: no-cache 1704 Pragma: no-cache 1705 ETag: a74eefc993a2b 1706 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1708 1710 Wasting Light 1711 jbox:alternative 1712 2011 1713 1715 4.4. POST 1717 The POST method is sent by the client to create a data resource or 1718 invoke an operation resource. The server uses the target resource 1719 media type to determine how to process the request. 1721 +-----------+------------------------------------------------+ 1722 | Type | Description | 1723 +-----------+------------------------------------------------+ 1724 | Datastore | Create a top-level configuration data resource | 1725 | Data | Create a configuration data child resource | 1726 | Operation | Invoke a protocol operation | 1727 +-----------+------------------------------------------------+ 1729 Resource Types that Support POST 1731 4.4.1. Create Resource Mode 1733 If the target resource type is a datastore or data resource, then the 1734 POST is treated as a request to create a top-level resource or child 1735 resource, respectively. The message-body is expected to contain the 1736 content of a child resource to create within the parent (target 1737 resource). The message-body MUST NOT contain more than one instance 1738 of the expected data resource. The data-model for the child tree is 1739 the subtree as defined by YANG for the child resource. 1741 The "insert" and "point" query parameters MUST be supported by the 1742 POST method for datastore and data resources. These parameters are 1743 only allowed if the list or leaf-list is ordered-by user. 1745 If the POST method succeeds, a "201 Created" status-line is returned 1746 and there is no response message-body. A "Location" header 1747 identifying the child resource that was created MUST be present in 1748 the response in this case. 1750 If the data resource already exists, then the POST request MUST fail 1751 and a "409 Conflict" status-line MUST be returned. 1753 If the user is not authorized to create the target resource, an error 1754 response containing a "403 Forbidden" status-line SHOULD be returned. 1755 A server MAY return a "404 Not Found" status-line, as described in 1756 section 6.5.3 in [RFC7231]. All other error responses are handled 1757 according to the procedures defined in Section 7. 1759 Example: 1761 To create a new "jukebox" resource, the client might send: 1763 POST /restconf/data HTTP/1.1 1764 Host: example.com 1765 Content-Type: application/yang.data+json 1767 { "example-jukebox:jukebox" : {} } 1769 If the resource is created, the server might respond as follows. 1770 Note that the "Location" header line is wrapped for display purposes 1771 only: 1773 HTTP/1.1 201 Created 1774 Date: Mon, 23 Apr 2012 17:01:00 GMT 1775 Server: example-server 1776 Location: https://example.com/restconf/data/ 1777 example-jukebox:jukebox 1778 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 1779 ETag: b3a3e673be2 1781 Refer to Appendix D.2.1 for more resource creation examples. 1783 4.4.2. Invoke Operation Mode 1785 If the target resource type is an operation resource, then the POST 1786 method is treated as a request to invoke that operation. The 1787 message-body (if any) is processed as the operation input parameters. 1788 Refer to Section 3.6 for details on operation resources. 1790 If the POST request succeeds, a "200 OK" status-line is returned if 1791 there is a response message-body, and a "204 No Content" status-line 1792 is returned if there is no response message-body. 1794 If the user is not authorized to invoke the target operation, an 1795 error response containing a "403 Forbidden" status-line is returned 1796 to the client. All other error responses are handled according to 1797 the procedures defined in Section 7. 1799 Example: 1801 In this example, the client is invoking the "play" operation defined 1802 in the "example-jukebox" YANG module. 1804 A client might send a "play" request as follows: 1806 POST /restconf/operations/example-jukebox:play HTTP/1.1 1807 Host: example.com 1808 Content-Type: application/yang.operation+json 1810 { 1811 "example-jukebox:input" : { 1812 "playlist" : "Foo-One", 1813 "song-number" : 2 1814 } 1815 } 1817 The server might respond: 1819 HTTP/1.1 204 No Content 1820 Date: Mon, 23 Apr 2012 17:50:00 GMT 1821 Server: example-server 1823 4.5. PUT 1825 The PUT method is sent by the client to create or replace the target 1826 data resource. A request message-body MUST be present, representing 1827 the new data resource, or the server MUST return "400 Bad Request" 1828 status-line. 1830 The only target resource media type that supports PUT is the data 1831 resource. The message-body is expected to contain the content used 1832 to create or replace the target resource. 1834 The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query 1835 parameters MUST be supported by the PUT method for data resources. 1836 These parameters are only allowed if the list or leaf-list is 1837 ordered-by user. 1839 Consistent with [RFC7231], if the PUT request creates a new resource, 1840 a "201 Created" status-line is returned. If an existing resource is 1841 modified, a "204 No Content" status-line is returned. 1843 If the user is not authorized to create or replace the target 1844 resource an error response containing a "403 Forbidden" status-line 1845 SHOULD be returned. A server MAY return a "404 Not Found" status- 1846 line, as described in section 6.5.3 in [RFC7231]. All other error 1847 responses are handled according to the procedures defined in 1848 Section 7. 1850 If the target resource represents a YANG leaf-list, then the PUT 1851 method MUST NOT change the value of the leaf-list instance. 1853 If the target resource represents a YANG list instance, then the PUT 1854 method MUST NOT change any key leaf values in the message-body 1855 representation. 1857 Example: 1859 An "album" child resource defined in the "example-jukebox" YANG 1860 module is replaced or created if it does not already exist. 1862 To replace the "album" resource contents, the client might send as 1863 follows. Note that the request-line is wrapped for display purposes 1864 only: 1866 PUT /restconf/data/example-jukebox:jukebox/ 1867 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1868 Host: example.com 1869 Content-Type: application/yang.data+json 1871 { 1872 "example-jukebox:album" : { 1873 "name" : "Wasting Light", 1874 "genre" : "example-jukebox:alternative", 1875 "year" : 2011 1876 } 1877 } 1879 If the resource is updated, the server might respond: 1881 HTTP/1.1 204 No Content 1882 Date: Mon, 23 Apr 2012 17:04:00 GMT 1883 Server: example-server 1884 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 1885 ETag: b27480aeda4c 1887 The same request is shown here using XML encoding: 1889 PUT /restconf/data/example-jukebox:jukebox/ 1890 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1892 Host: example.com 1893 Content-Type: application/yang.data+xml 1895 1897 Wasting Light 1898 jbox:alternative 1899 2011 1900 1902 4.6. PATCH 1904 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 1905 an extensible framework for resource patching mechanisms. It is 1906 optional to implement by the server. Each patch mechanism needs a 1907 unique media type. Zero or more patch media types MAY be supported 1908 by the server. The media types supported by a server can be 1909 discovered by the client by sending an OPTIONS request (see 1910 Section 4.1). 1912 This document defines one patch mechanism (Section 4.6.1). The YANG 1913 PATCH mechanism is defined in [I-D.ietf-netconf-yang-patch]. Other 1914 patch mechanisms may be defined by future specifications. 1916 If the target resource instance does not exist, the server MUST NOT 1917 create it. 1919 If the PATCH request succeeds, a "200 OK" status-line is returned if 1920 there is a message-body, and "204 No Content" is returned if no 1921 response message-body is sent. 1923 If the user is not authorized to alter the target resource an error 1924 response containing a "403 Forbidden" status-line SHOULD be returned. 1925 A server MAY return a "404 Not Found" status-line, as described in 1926 section 6.5.3 in [RFC7231]. All other error responses are handled 1927 according to the procedures defined in Section 7. 1929 4.6.1. Plain Patch 1931 The plain patch mechanism merges the contents of the message body 1932 with the target resource. If the target resource is a datastore 1933 resource (see Section 3.4), the message body MUST be either 1934 application/yang.datastore+xml or application/yang.datastore+json. 1935 If then the target resource is a data resource (see Section 3.5), 1936 then the message body MUST be either application/yang.data+xml or 1937 application/yang.data+json. 1939 Plain patch can be used to create or update, but not delete, a child 1940 resource within the target resource. Please see 1941 [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting 1942 more granular control. The YANG Patch Media Type allows multiple 1943 sub-operations (e.g., merge, delete) within a single PATCH operation. 1945 If the target resource represents a YANG leaf-list, then the PATCH 1946 method MUST not change the value of the leaf-list instance. 1948 If the target resource represents a YANG list instance, then the 1949 PATCH method MUST NOT change any key leaf values in the message-body 1950 representation. 1952 Example: 1954 To replace just the "year" field in the "album" resource (instead of 1955 replacing the entire resource with the PUT method), the client might 1956 send a plain patch as follows. Note that the request-line is wrapped 1957 for display purposes only: 1959 PATCH /restconf/data/example-jukebox:jukebox/ 1960 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1961 Host: example.com 1962 If-Match: b8389233a4c 1963 Content-Type: application/yang.data+xml 1965 1966 2011 1967 1969 If the field is updated, the server might respond: 1971 HTTP/1.1 204 No Content 1972 Date: Mon, 23 Apr 2012 17:49:30 GMT 1973 Server: example-server 1974 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 1975 ETag: b2788923da4c 1977 4.7. DELETE 1979 The DELETE method is used to delete the target resource. If the 1980 DELETE request succeeds, a "204 No Content" status-line is returned, 1981 and there is no response message-body. 1983 If the user is not authorized to delete the target resource then an 1984 error response containing a "403 Forbidden" status-line SHOULD be 1985 returned. A server MAY return a "404 Not Found" status-line, as 1986 described in section 6.5.3 in [RFC7231]. All other error responses 1987 are handled according to the procedures defined in Section 7. 1989 If the target resource represents a YANG leaf-list or list, then the 1990 PATCH method SHOULD NOT delete more than one such instance. The 1991 server MAY delete more than one instance if a query parameter is used 1992 requesting this behavior. (Definition of this query parameter is 1993 outside the scope of this document.) 1995 Example: 1997 To delete a resource such as the "album" resource, the client might 1998 send: 2000 DELETE /restconf/data/example-jukebox:jukebox/ 2001 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2002 Host: example.com 2004 If the resource is deleted, the server might respond: 2006 HTTP/1.1 204 No Content 2007 Date: Mon, 23 Apr 2012 17:49:40 GMT 2008 Server: example-server 2010 4.8. Query Parameters 2012 Each RESTCONF operation allows zero or more query parameters to be 2013 present in the request URI. The specific parameters that are allowed 2014 depends on the resource type, and sometimes the specific target 2015 resource used, in the request. 2017 o Query parameters can be given in any order. 2019 o Each parameter can appear at most once in a request URI. 2021 o A default value may apply if the parameter is missing. 2023 o Query parameter names and values are case-sensitive 2025 o A server MUST return an error with a '400 Bad Request' status-line 2026 if a query parameter is unexpected. 2028 +-------------------+-------------+---------------------------------+ 2029 | Name | Methods | Description | 2030 +-------------------+-------------+---------------------------------+ 2031 | content | GET | Select config and/or non-config | 2032 | | | data resources | 2033 | depth | GET | Request limited sub-tree depth | 2034 | | | in the reply content | 2035 | fields | GET | Request a subset of the target | 2036 | | | resource contents | 2037 | filter | GET | Boolean notification filter for | 2038 | | | event stream resources | 2039 | insert | POST, PUT | Insertion mode for ordered-by | 2040 | | | user data resources | 2041 | point | POST, PUT | Insertion point for ordered-yb | 2042 | | | user data resources | 2043 | start-time | GET | Replay buffer start time for | 2044 | | | event stream resources | 2045 | stop-time | GET | Replay buffer stop time for | 2046 | | | event stream resources | 2047 | with-defaults | GET | Control retrieval of default | 2048 | | | values | 2049 +-------------------+-------------+---------------------------------+ 2051 RESTCONF Query Parameters 2053 Refer to Appendix D.3 for examples of query parameter usage. 2055 If vendors define additional query parameters, they SHOULD use a 2056 prefix (such as the enterprise or organization name) for query 2057 parameter names in order to avoid collisions with other parameters. 2059 4.8.1. The "content" Query Parameter 2061 The "content" parameter controls how descendant nodes of the 2062 requested data nodes will be processed in the reply. 2064 The allowed values are: 2066 +-----------+-----------------------------------------------------+ 2067 | Value | Description | 2068 +-----------+-----------------------------------------------------+ 2069 | config | Return only configuration descendant data nodes | 2070 | nonconfig | Return only non-configuration descendant data nodes | 2071 | all | Return all descendant data nodes | 2072 +-----------+-----------------------------------------------------+ 2074 This parameter is only allowed for GET methods on datastore and data 2075 resources. A "400 Bad Request" status-line is returned if used for 2076 other methods or resource types. 2078 If this query parameter is not present, the default value is "all". 2079 This query parameter MUST be supported by the server. 2081 4.8.2. The "depth" Query Parameter 2083 The "depth" parameter is used to specify the number of nest levels 2084 returned in a response for a GET method. The first nest-level 2085 consists of the requested data node itself. If the "fields" 2086 parameter (Section 4.8.3) is used to select descendant data nodes, 2087 these nodes all have a depth value of 1. This has the effect of 2088 including the nodes specified by the fields, even if the "depth" 2089 value is less than the actual depth level of the specified fields. 2090 Any child nodes which are contained within a parent node have a depth 2091 value that is 1 greater than its parent. 2093 The value of the "depth" parameter is either an integer between 1 and 2094 65535, or the string "unbounded". "unbounded" is the default. 2096 This parameter is only allowed for GET methods on API, datastore, and 2097 data resources. A "400 Bad Request" status-line is returned if it 2098 used for other methods or resource types. 2100 More than one "depth" query parameter MUST NOT appear in a request. 2101 If more than one instance is present, then a "400 Bad Request" 2102 status-line MUST be returned by the server. 2104 By default, the server will include all sub-resources within a 2105 retrieved resource, which have the same resource type as the 2106 requested resource. Only one level of sub-resources with a different 2107 media type than the target resource will be returned. The exception 2108 is the datastore resource. If this resource type is retrieved then 2109 by default the datastore and all child data resources are returned. 2111 If the "depth" query parameter URI is listed in the "capability" 2112 leaf-list in Section 9.3, then the server supports the "depth" query 2113 parameter. 2115 4.8.3. The "fields" Query Parameter 2117 The "fields" query parameter is used to optionally identify data 2118 nodes within the target resource to be retrieved in a GET method. 2119 The client can use this parameter to retrieve a subset of all nodes 2120 in a resource. 2122 A value of the "fields" query parameter matches the following rule: 2124 fields-expr = path '(' fields-expr ')' / 2125 path ';' fields-expr / 2126 path 2127 path = api-identifier [ '/' path ] 2129 "api-identifier" is defined in Section 3.5.1.1. 2131 ";" is used to select multiple nodes. For example, to retrieve only 2132 the "genre" and "year" of an album, use: "fields=genre;year". 2134 Parentheses are used to specify sub-selectors of a node. 2136 For example, assume the target resource is the "album" list. To 2137 retrieve only the "label" and "catalogue-number" of the "admin" 2138 container within an album, use: 2139 "fields=admin(label;catalogue-number)". 2141 "/" is used in a path to retrieve a child node of a node. For 2142 example, to retrieve only the "label" of an album, use: "fields=admin 2143 /label". 2145 This parameter is only allowed for GET methods on api, datastore, and 2146 data resources. A "400 Bad Request" status-line is returned if used 2147 for other methods or resource types. 2149 More than one "fields" query parameter MUST NOT appear in a request. 2150 If more than one instance is present, then a "400 Bad Request" 2151 status-line MUST be returned by the server. 2153 If the "fields" query parameter URI is listed in the "capability" 2154 leaf-list in Section 9.3, then the server supports the "fields" 2155 parameter. 2157 4.8.4. The "filter" Query Parameter 2159 The "filter" parameter is used to indicate which subset of all 2160 possible events are of interest. If not present, all events not 2161 precluded by other parameters will be sent. 2163 This parameter is only allowed for GET methods on a text/event-stream 2164 data resource. A "400 Bad Request" status-line is returned if used 2165 for other methods or resource types. 2167 The format of this parameter is an XPath 1.0 expression, and is 2168 evaluated in the following context: 2170 o The set of namespace declarations is the set of prefix and 2171 namespace pairs for all supported YANG modules, where the prefix 2172 is the YANG module name, and the namespace is as defined by the 2173 "namespace" statement in the YANG module. 2175 o The function library is the core function library defined in XPath 2176 1.0. 2178 o The set of variable bindings is empty. 2180 o The context node is the root node. 2182 More than one "filter" query parameter MUST NOT appear in a request. 2183 If more than one instance is present, then a "400 Bad Request" 2184 status-line MUST be returned by the server. 2186 The filter is used as defined in [RFC5277], Section 3.6. If the 2187 boolean result of the expression is true when applied to the 2188 conceptual "notification" document root, then the event notification 2189 is delivered to the client. 2191 If the "filter" query parameter URI is listed in the "capability" 2192 leaf-list in Section 9.3, then the server supports the "filter" query 2193 parameter. 2195 4.8.5. The "insert" Query Parameter 2197 The "insert" parameter is used to specify how a resource should be 2198 inserted within a ordered-by user list. 2200 The allowed values are: 2202 +-----------+-------------------------------------------------------+ 2203 | Value | Description | 2204 +-----------+-------------------------------------------------------+ 2205 | first | Insert the new data as the new first entry. | 2206 | last | Insert the new data as the new last entry. | 2207 | before | Insert the new data before the insertion point, as | 2208 | | specified by the value of the "point" parameter. | 2209 | after | Insert the new data after the insertion point, as | 2210 | | specified by the value of the "point" parameter. | 2211 +-----------+-------------------------------------------------------+ 2213 The default value is "last". 2215 This parameter is only supported for the POST and PUT methods. It is 2216 also only supported if the target resource is a data resource, and 2217 that data represents a YANG list or leaf-list that is ordered-by 2218 user. 2220 More than one "insert" query parameter MUST NOT appear in a request. 2221 If more than one instance is present, then a "400 Bad Request" 2222 status-line MUST be returned by the server. 2224 If the values "before" or "after" are used, then a "point" query 2225 parameter for the insertion parameter MUST also be present, or a "400 2226 Bad Request" status-line is returned. 2228 The "insert" query parameter MUST be supported by the server. 2230 4.8.6. The "point" Query Parameter 2232 The "point" parameter is used to specify the insertion point for a 2233 data resource that is being created or moved within an ordered-by 2234 user list or leaf-list. 2236 The value of the "point" parameter is a string that identifies the 2237 path to the insertion point object. The format is the same as a 2238 target resource URI string. 2240 This parameter is only supported for the POST and PUT methods. It is 2241 also only supported if the target resource is a data resource, and 2242 that data represents a YANG list or leaf-list that is ordered-by 2243 user. 2245 If the "insert" query parameter is not present, or has a value other 2246 than "before" or "after", then a "400 Bad Request" status-line is 2247 returned. 2249 More than one "point" query parameter MUST NOT appear in a request. 2250 If more than one instance is present, then a "400 Bad Request" 2251 status-line MUST be returned by the server. 2253 This parameter contains the instance identifier of the resource to be 2254 used as the insertion point for a POST or PUT method. 2256 The "point" query parameter MUST be supported by the server. 2258 4.8.7. The "start-time" Query Parameter 2260 The "start-time" parameter is used to trigger the notification replay 2261 feature and indicate that the replay should start at the time 2262 specified. If the stream does not support replay, per the 2263 "replay-support" attribute returned by stream list entry for the 2264 stream resource, then the server MUST return a "400 Bad Request" 2265 status-line. 2267 The value of the "start-time" parameter is of type "date-and-time", 2268 defined in the "ietf-yang" YANG module [RFC6991]. 2270 This parameter is only allowed for GET methods on a text/event-stream 2271 data resource. A "400 Bad Request" status-line is returned if used 2272 for other methods or resource types. 2274 More than one "start-time" query parameter MUST NOT appear in a 2275 request. If more than one instance is present, then a "400 Bad 2276 Request" status-line MUST be returned by the server. 2278 If this parameter is not present, then a replay subscription is not 2279 being requested. It is not valid to specify start times that are 2280 later than the current time. If the value specified is earlier than 2281 the log can support, the replay will begin with the earliest 2282 available notification. 2284 If this query parameter is supported by the server, then the "replay" 2285 query parameter URI MUST be listed in the "capability" leaf-list in 2286 Section 9.3. The "stop-time" query parameter MUST also be supported 2287 by the server. 2289 If the "replay-support" leaf has the value 'true' in the "stream" 2290 entry (defined in Section 9.3) then the server MUST support the 2291 "start-time" and "stop-time" query parameters for that stream. 2293 4.8.8. The "stop-time" Query Parameter 2295 The "stop-time" parameter is used with the replay feature to indicate 2296 the newest notifications of interest. This parameter MUST be used 2297 with and have a value later than the "start-time" parameter. 2299 The value of the "stop-time" parameter is of type "date-and-time", 2300 defined in the "ietf-yang" YANG module [RFC6991]. 2302 This parameter is only allowed for GET methods on a text/event-stream 2303 data resource. A "400 Bad Request" status-line is returned if used 2304 for other methods or resource types. 2306 More than one "stop-time" query parameter MUST NOT appear in a 2307 request. If more than one instance is present, then a "400 Bad 2308 Request" status-line MUST be returned by the server. 2310 If this parameter is not present, the notifications will continue 2311 until the subscription is terminated. Values in the future are 2312 valid. 2314 If this query parameter is supported by the server, then the "replay" 2315 query parameter URI MUST be listed in the "capability" leaf-list in 2316 Section 9.3. The "start-time" query parameter MUST also be supported 2317 by the server. 2319 If the "replay-support" leaf is present in the "stream" entry 2320 (defined in Section 9.3) then the server MUST support the 2321 "start-time" and "stop-time" query parameters for that stream. 2323 4.8.9. The "with-defaults" Query Parameter 2325 The "with-defaults" parameter is used to specify how information 2326 about default data nodes should be returned in response to GET 2327 requests on data resources. 2329 If the server supports this capability, then it MUST implement the 2330 behavior in Section 4.5.1 of [RFC6243], except applied to the 2331 RESTCONF GET operation, instead of the NETCONF operations. 2333 +---------------------------+---------------------------------------+ 2334 | Value | Description | 2335 +---------------------------+---------------------------------------+ 2336 | report-all | All data nodes are reported | 2337 | trim | Data nodes set to the YANG default | 2338 | | are not reported | 2339 | explicit | Data nodes set to the YANG default by | 2340 | | the client are reported | 2341 | report-all-tagged | All data nodes are reported and | 2342 | | defaults are tagged | 2343 +---------------------------+---------------------------------------+ 2345 If the "with-defaults" parameter is set to "report-all" then the 2346 server MUST adhere to the defaults reporting behavior defined in 2347 Section 3.1 of [RFC6243]. 2349 If the "with-defaults" parameter is set to "trim" then the server 2350 MUST adhere to the defaults reporting behavior defined in Section 3.2 2351 of [RFC6243]. 2353 If the "with-defaults" parameter is set to "explicit" then the server 2354 MUST adhere to the defaults reporting behavior defined in Section 3.3 2355 of [RFC6243]. 2357 If the "with-defaults" parameter is set to "report-all-tagged" then 2358 the server MUST adhere to the defaults reporting behavior defined in 2359 Section 3.4 of [RFC6243]. 2361 More than one "with-defaults" query parameter MUST NOT appear in a 2362 request. If more than one instance is present, then a "400 Bad 2363 Request" status-line MUST be returned by the server. 2365 If the "with-defaults" parameter is not present then the server MUST 2366 adhere to the defaults reporting behavior defined in its "basic-mode" 2367 parameter for the "defaults" protocol capability URI, defined in 2368 Section 9.1.2. 2370 If the server includes the "with-defaults" query parameter URI in the 2371 "capability" leaf-list in Section 9.3, then the "with-defaults" query 2372 parameter MUST be supported. 2374 5. Messages 2376 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 2377 message corresponds to a single protocol method. Most messages can 2378 perform a single task on a single resource, such as retrieving a 2379 resource or editing a resource. The exception is the PATCH method, 2380 which allows multiple datastore edits within a single message. 2382 5.1. Request URI Structure 2384 Resources are represented with URIs following the structure for 2385 generic URIs in [RFC3986]. 2387 A RESTCONF operation is derived from the HTTP method and the request 2388 URI, using the following conceptual fields: 2390 //?# 2392 ^ ^ ^ ^ ^ 2393 | | | | | 2394 method entry resource query fragment 2396 M M O O I 2398 M=mandatory, O=optional, I=ignored 2400 where: 2402 is the HTTP method 2403 is the RESTCONF entry point 2404 is the Target Resource URI 2405 is the query parameter list 2406 is not used in RESTCONF 2408 o method: the HTTP method identifying the RESTCONF operation 2409 requested by the client, to act upon the target resource specified 2410 in the request URI. RESTCONF operation details are described in 2411 Section 4. 2413 o entry: the root of the RESTCONF API configured on this HTTP 2414 server, discovered by getting the "/.well-known/host-meta" 2415 resource, as described in Section 3.1. 2417 o resource: the path expression identifying the resource that is 2418 being accessed by the operation. If this field is not present, 2419 then the target resource is the API itself, represented by the 2420 media type "application/yang.api". 2422 o query: the set of parameters associated with the RESTCONF message. 2423 These have the familiar form of "name=value" pairs. Most query 2424 parameters are optional to implement by the server and optional to 2425 use by the client. Each optional query parameter is identified by 2426 a URI. The server MUST list the optional query parameter URIs it 2427 supports in the "capabilities" list defined in Section 9.3. 2429 There is a specific set of parameters defined, although the server 2430 MAY choose to support query parameters not defined in this document. 2431 The contents of the any query parameter value MUST be encoded 2432 according to [RFC3986], Section 3.4. Any reserved characters MUST be 2433 percent-encoded, according to [RFC3986], section 2.1. 2435 o fragment: This field is not used by the RESTCONF protocol. 2437 When new resources are created by the client, a "Location" header is 2438 returned, which identifies the path of the newly created resource. 2439 The client uses this exact path identifier to access the resource 2440 once it has been created. 2442 The "target" of an operation is a resource. The "path" field in the 2443 request URI represents the target resource for the operation. 2445 Refer to Appendix D for examples of RESTCONF Request URIs. 2447 5.2. Message Encoding 2449 RESTCONF messages are encoded in HTTP according to [RFC7230]. The 2450 "utf-8" character set is used for all messages. RESTCONF message 2451 content is sent in the HTTP message-body. 2453 Content is encoded in either JSON or XML format. A server MUST 2454 support XML or JSON encoding. XML encoding rules for data nodes are 2455 defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are 2456 used for all XML content. JSON encoding rules are defined in 2457 [I-D.ietf-netmod-yang-json]. JSON encoding of meta-data is defined 2458 in [I-D.ietf-netmod-yang-metadata]. This encoding is valid JSON, but 2459 also has special encoding rules to identify module namespaces and 2460 provide consistent type processing of YANG data. 2462 Request input content encoding format is identified with the Content- 2463 Type header. This field MUST be present if a message-body is sent by 2464 the client. 2466 The server MUST support the "Accept" header and "406 Not Acceptable" 2467 status-line, as defined in [RFC7231]. Response output content 2468 encoding format is identified with the Accept header in the request. 2469 If it is not specified, the request input encoding format SHOULD be 2470 used, or the server MAY choose any supported content encoding format. 2472 If there was no request input, then the default output encoding is 2473 XML or JSON, depending on server preference. File extensions encoded 2474 in the request are not used to identify format encoding. 2476 5.3. RESTCONF Meta-Data 2478 The RESTCONF protocol needs to retrieve the same meta-data that is 2479 used in the NETCONF protocol. Information about default leafs, last- 2480 modified timestamps, etc. are commonly used to annotate 2481 representations of the datastore contents. This meta-data is not 2482 defined in the YANG schema because it applies to the datastore, and 2483 is common across all data nodes. 2485 This information is encoded as attributes in XML. JSON encoding of 2486 meta-data is defined in [I-D.ietf-netmod-yang-metadata]. 2488 The following examples are based on the example in Appendix D.3.9. 2489 The "report-all-tagged" mode for the "with-defaults" query parameter 2490 requires that a "default" attribute be returned for default nodes. 2491 This example shows that attribute for the "mtu" leaf . 2493 5.3.1. XML MetaData Encoding Example 2495 GET /restconf/data/interfaces/interface=eth1 2496 ?with-defaults=report-all-tagged HTTP/1.1 2497 Host: example.com 2498 Accept: application/yang.data+xml 2500 The server might respond as follows. 2502 HTTP/1.1 200 OK 2503 Date: Mon, 23 Apr 2012 17:01:00 GMT 2504 Server: example-server 2505 Content-Type: application/yang.data+xml 2507 2509 eth1 2510 1500 2512 up 2513 2515 5.3.2. JSON MetaData Encoding Example 2517 Note that RFC 6243 defines the "default" attribute with XSD, not 2518 YANG, so the YANG module name has to be assigned manually. The value 2519 "ietf-netconf-with-defaults" is assigned for JSON meta-data encoding. 2521 GET /restconf/data/interfaces/interface=eth1 2522 ?with-defaults=report-all-tagged HTTP/1.1 2523 Host: example.com 2524 Accept: application/yang.data+json 2526 The server might respond as follows. 2528 HTTP/1.1 200 OK 2529 Date: Mon, 23 Apr 2012 17:01:00 GMT 2530 Server: example-server 2531 Content-Type: application/yang.data+json 2533 { 2534 "example:interface": [ 2535 { 2536 "name" : "eth1", 2537 "mtu" : 1500, 2538 "@mtu": { 2539 "ietf-netconf-with-defaults:default" : true 2540 }, 2541 "status" : "up" 2542 } 2543 ] 2544 } 2546 5.4. Return Status 2548 Each message represents some sort of resource access. An HTTP 2549 "status-line" header line is returned for each request. If a 4xx or 2550 5xx range status code is returned in the status-line, then the error 2551 information will be returned in the response, according to the format 2552 defined in Section 7.1. 2554 5.5. Message Caching 2556 Since the datastore contents change at unpredictable times, responses 2557 from a RESTCONF server generally SHOULD NOT be cached. 2559 The server SHOULD include a "Cache-Control" header in every response 2560 that specifies whether the response should be cached. A "Pragma" 2561 header specifying "no-cache" MAY also be sent in case the 2562 "Cache-Control" header is not supported. 2564 Instead of relying on HTTP caching, the client SHOULD track the 2565 "ETag" and/or "Last-Modified" headers returned by the server for the 2566 datastore resource (or data resource if the server supports it). A 2567 retrieval request for a resource can include the "If-None-Match" and/ 2568 or "If-Modified-Since" headers, which will cause the server to return 2569 a "304 Not Modified" status-line if the resource has not changed. 2570 The client MAY use the HEAD method to retrieve just the message 2571 headers, which SHOULD include the "ETag" and "Last-Modified" headers, 2572 if this meta-data is maintained for the target resource. 2574 6. Notifications 2576 The RESTCONF protocol supports YANG-defined event notifications. The 2577 solution preserves aspects of NETCONF Event Notifications [RFC5277] 2578 while utilizing the Server-Sent Events [W3C.CR-eventsource-20121211] 2579 transport strategy. 2581 6.1. Server Support 2583 A RESTCONF server MAY support RESTCONF notifications. Clients may 2584 determine if a server supports RESTCONF notifications by using the 2585 HTTP operation OPTIONS, HEAD, or GET on the stream list. The server 2586 does not support RESTCONF notifications if an HTTP error code is 2587 returned (e.g., "404 Not Found" status-line). 2589 6.2. Event Streams 2591 A RESTCONF server that supports notifications will populate a stream 2592 resource for each notification delivery service access point. A 2593 RESTCONF client can retrieve the list of supported event streams from 2594 a RESTCONF server using the GET operation on the stream list. 2596 The "restconf-state/streams" container definition in the 2597 "ietf-restconf-monitoring" module (defined in Section 9.3) is used to 2598 specify the structure and syntax of the conceptual child resources 2599 within the "streams" resource. 2601 For example: 2603 The client might send the following request: 2605 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2606 streams HTTP/1.1 2608 Host: example.com 2609 Accept: application/yang.data+xml 2611 The server might send the following response: 2613 HTTP/1.1 200 OK 2614 Content-Type: application/yang.api+xml 2616 2618 2619 NETCONF 2620 default NETCONF event stream 2621 2622 true 2623 2624 2007-07-08T00:00:00Z 2625 2626 2627 xml 2628 https://example.com/streams/NETCONF 2629 2630 2631 2632 json 2633 https://example.com/streams/NETCONF-JSON 2634 2635 2636 2637 2638 SNMP 2639 SNMP notifications 2640 false 2641 2642 xml 2643 https://example.com/streams/SNMP 2644 2645 2646 2647 syslog-critical 2648 Critical and higher severity 2649 2650 true 2651 2652 2007-07-01T00:00:00Z 2653 2654 2655 xml 2656 2657 https://example.com/streams/syslog-critical 2658 2659 2660 2661 2663 6.3. Subscribing to Receive Notifications 2665 RESTCONF clients can determine the URL for the subscription resource 2666 (to receive notifications) by sending an HTTP GET request for the 2667 "location" leaf with the stream list entry. The value returned by 2668 the server can be used for the actual notification subscription. 2670 The client will send an HTTP GET request for the URL returned by the 2671 server with the "Accept" type "text/event-stream". 2673 The server will treat the connection as an event stream, using the 2674 Server Sent Events [W3C.CR-eventsource-20121211] transport strategy. 2676 The server MAY support query parameters for a GET method on this 2677 resource. These parameters are specific to each notification stream. 2679 For example: 2681 The client might send the following request: 2683 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2684 streams/stream=NETCONF/access=xml/location HTTP/1.1 2685 Host: example.com 2686 Accept: application/yang.data+xml 2688 The server might send the following response: 2690 HTTP/1.1 200 OK 2691 Content-Type: application/yang.api+xml 2693 2695 https://example.com/streams/NETCONF 2696 2698 The RESTCONF client can then use this URL value to start monitoring 2699 the event stream: 2701 GET /streams/NETCONF HTTP/1.1 2702 Host: example.com 2703 Accept: text/event-stream 2704 Cache-Control: no-cache 2705 Connection: keep-alive 2707 A RESTCONF client MAY request the server compress the events using 2708 the HTTP header field "Accept-Encoding". For instance: 2710 GET /streams/NETCONF HTTP/1.1 2711 Host: example.com 2712 Accept: text/event-stream 2713 Cache-Control: no-cache 2714 Connection: keep-alive 2715 Accept-Encoding: gzip, deflate 2717 6.3.1. NETCONF Event Stream 2719 The server SHOULD support the "NETCONF" notification stream defined 2720 in [RFC5277]. For this stream, RESTCONF notification subscription 2721 requests MAY specify parameters indicating the events it wishes to 2722 receive. These query parameters are optional to implement, and only 2723 available if the server supports them. 2725 +------------+---------+-------------------------+ 2726 | Name | Section | Description | 2727 +------------+---------+-------------------------+ 2728 | start-time | 4.8.7 | replay event start time | 2729 | stop-time | 4.8.8 | replay event stop time | 2730 | filter | 4.8.4 | boolean content filter | 2731 +------------+---------+-------------------------+ 2733 NETCONF Stream Query Parameters 2735 The semantics and syntax for these query parameters are defined in 2736 the sections listed above. The YANG definition MUST be converted to 2737 a URI-encoded string for use in the request URI. 2739 Refer to Appendix D.3.6 for filter parameter examples. 2741 6.4. Receiving Event Notifications 2743 RESTCONF notifications are encoded according to the definition of the 2744 event stream. The NETCONF stream defined in [RFC5277] is encoded in 2745 XML format. 2747 The structure of the event data is based on the "notification" 2748 element definition in Section 4 of [RFC5277]. It MUST conform to the 2749 schema for the "notification" element in Section 4 of [RFC5277], 2750 except the XML namespace for this element is defined as: 2752 urn:ietf:params:xml:ns:yang:ietf-restconf 2754 For JSON encoding purposes, the module name for the "notification" 2755 element is "ietf-restconf". 2757 Two child nodes within the "notification" container are expected, 2758 representing the event time and the event payload. The "event-time" 2759 node is defined within the "ietf-restconf" module namespace. The 2760 name and namespace of the payload element are determined by the YANG 2761 module containing the notification-stmt. 2763 In the following example, the YANG module "example-mod" is used: 2765 module example-mod { 2766 namespace "http://example.com/event/1.0"; 2767 prefix ex; 2769 notification event { 2770 leaf event-class { type string; } 2771 container reporting-entity { 2772 leaf card { type string; } 2773 } 2774 leaf severity { type string; } 2775 } 2776 } 2778 An example SSE event notification encoded using XML: 2780 data: 2782 data: 2013-12-21T00:01:00Z 2783 data: 2784 data: fault 2785 data: 2786 data: Ethernet0 2787 data: 2788 data: major 2789 data: 2790 data: 2792 An example SSE event notification encoded using JSON: 2794 data: { 2795 data: "ietf-restconf:notification": { 2796 data: "event-time": "2013-12-21T00:01:00Z", 2797 data: "example-mod:event": { 2798 data: "event-class": "fault", 2799 data: "reporting-entity": { "card": "Ethernet0" }, 2800 data: "severity": "major" 2801 data: } 2802 data: } 2803 data: } 2805 Alternatively, since neither XML nor JSON are whitespace sensitive, 2806 the above messages can be encoded onto a single line. For example: 2808 For example: ('\' line wrapping added for formatting only) 2810 XML: 2812 data: 2013-12-21T00:01:00ZfaultEthernet0\ 2816 major 2818 JSON: 2820 data: {"ietf-restconf:notification":{"event-time":"2013-12-21\ 2821 T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ 2822 tingEntity":{"card":"Ethernet0"},"severity":"major"}}} 2824 The SSE specifications supports the following additional fields: 2825 event, id and retry. A RESTCONF server MAY send the "retry" field 2826 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 2827 SHOULD NOT send the "event" or "id" fields, as there are no 2828 meaningful values that could be used for them that would not be 2829 redundant to the contents of the notification itself. RESTCONF 2830 servers that do not send the "id" field also do not need to support 2831 the HTTP header "Last-Event-Id". RESTCONF servers that do send the 2832 "id" field MUST still support the "startTime" query parameter as the 2833 preferred means for a client to specify where to restart the event 2834 stream. 2836 7. Error Reporting 2838 HTTP status-lines are used to report success or failure for RESTCONF 2839 operations. The element returned in NETCONF error 2840 responses contains some useful information. This error information 2841 is adapted for use in RESTCONF, and error information is returned for 2842 "4xx" class of status codes. 2844 The following table summarizes the return status codes used 2845 specifically by RESTCONF operations: 2847 +----------------------------+--------------------------------------+ 2848 | Status-Line | Description | 2849 +----------------------------+--------------------------------------+ 2850 | 100 Continue | POST accepted, 201 should follow | 2851 | 200 OK | Success with response message-body | 2852 | 201 Created | POST to create a resource success | 2853 | 204 No Content | Success without response message- | 2854 | | body | 2855 | 304 Not Modified | Conditional operation not done | 2856 | 400 Bad Request | Invalid request message | 2857 | 401 Unauthorized | Client cannot be authenticated | 2858 | 403 Forbidden | Access to resource denied | 2859 | 404 Not Found | Resource target or resource node not | 2860 | | found | 2861 | 405 Method Not Allowed | Method not allowed for target | 2862 | | resource | 2863 | 409 Conflict | Resource or lock in use | 2864 | 412 Precondition Failed | Conditional method is false | 2865 | 413 Request Entity Too | too-big error | 2866 | Large | | 2867 | 414 Request-URI Too Large | too-big error | 2868 | 415 Unsupported Media Type | non RESTCONF media type | 2869 | 500 Internal Server Error | operation-failed | 2870 | 501 Not Implemented | unknown-operation | 2871 | 503 Service Unavailable | Recoverable server error | 2872 +----------------------------+--------------------------------------+ 2874 HTTP Status Codes used in RESTCONF 2876 Since an operation resource is defined with a YANG "rpc" statement, 2877 and an action is defined with a YANG "action" statement, a mapping 2878 between the NETCONF value and the HTTP status code is 2879 needed. The specific error condition and response code to use are 2880 data-model specific and might be contained in the YANG "description" 2881 statement for the "action" or "rpc" statement. 2883 +-------------------------+-------------+ 2884 | | status code | 2885 +-------------------------+-------------+ 2886 | in-use | 409 | 2887 | invalid-value | 400 | 2888 | too-big | 413 | 2889 | missing-attribute | 400 | 2890 | bad-attribute | 400 | 2891 | unknown-attribute | 400 | 2892 | bad-element | 400 | 2893 | unknown-element | 400 | 2894 | unknown-namespace | 400 | 2895 | access-denied | 403 | 2896 | lock-denied | 409 | 2897 | resource-denied | 409 | 2898 | rollback-failed | 500 | 2899 | data-exists | 409 | 2900 | data-missing | 409 | 2901 | operation-not-supported | 501 | 2902 | operation-failed | 500 | 2903 | partial-operation | 500 | 2904 | malformed-message | 400 | 2905 +-------------------------+-------------+ 2907 Mapping from error-tag to status code 2909 7.1. Error Response Message 2911 When an error occurs for a request message on any resource type, and 2912 a "4xx" class of status codes will be returned (except for status 2913 code "403 Forbidden"), then the server SHOULD send a response 2914 message-body containing the information described by the "errors" 2915 container definition within the YANG module Section 8. The Content- 2916 Type of this response message MUST be a subtype of application/ 2917 yang.errors (see example below). 2919 The client SHOULD specify the desired encoding for error messages by 2920 specifying the appropriate media-type in the Accept header. If no 2921 error media is specified, then the media subtype (e.g., XML or JSON) 2922 of the request message SHOULD be used, or the server MAY choose any 2923 supported message encoding format. If there is no request message 2924 the server MUST select "application/yang.errors+xml" or "application/ 2925 yang.errors+json", depending on server preference. All of the 2926 examples in this document, except for the one below, assume that XML 2927 encoding will be returned if there is an error. 2929 YANG Tree Diagram for data: 2931 +--ro errors 2932 +--ro error* 2933 +--ro error-type enumeration 2934 +--ro error-tag string 2935 +--ro error-app-tag? string 2936 +--ro error-path? instance-identifier 2937 +--ro error-message? string 2938 +--ro error-info 2940 The semantics and syntax for RESTCONF error messages are defined in 2941 the "application/yang.errors" restconf-media-type extension in 2942 Section 8. 2944 Examples: 2946 The following example shows an error returned for an "lock-denied" 2947 error that can occur if a NETCONF client has locked a datastore. The 2948 RESTCONF client is attempting to delete a data resource. Note that 2949 an Accept header is used to specify the desired encoding for the 2950 error message. No response message-body content is expected by the 2951 client in this example. 2953 DELETE /restconf/data/example-jukebox:jukebox/ 2954 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2955 Host: example.com 2956 Accept: application/yang.errors+json 2958 The server might respond: 2960 HTTP/1.1 409 Conflict 2961 Date: Mon, 23 Apr 2012 17:11:00 GMT 2962 Server: example-server 2963 Content-Type: application/yang.errors+json 2965 { 2966 "ietf-restconf:errors": { 2967 "error": [ 2968 { 2969 "error-type": "protocol", 2970 "error-tag": "lock-denied", 2971 "error-message": "Lock failed, lock already held" 2972 } 2973 ] 2974 } 2975 } 2977 The following example shows an error returned for a "data-exists" 2978 error on a data resource. The "jukebox" resource already exists so 2979 it cannot be created. 2981 The client might send: 2983 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 2984 Host: example.com 2986 The server might respond (some lines wrapped for display purposes): 2988 HTTP/1.1 409 Conflict 2989 Date: Mon, 23 Apr 2012 17:11:00 GMT 2990 Server: example-server 2991 Content-Type: application/yang.errors+xml 2992 2993 2994 protocol 2995 data-exists 2996 2999 /rc:restconf/rc:data/jbox:jukebox 3000 3001 3002 Data already exists, cannot create new resource 3003 3004 3005 3007 8. RESTCONF module 3009 The "ietf-restconf" module defines conceptual definitions within an 3010 extension and two groupings, which are not meant to be implemented as 3011 datastore contents by a server. E.g., the "restconf" container is 3012 not intended to be implemented as a top-level data node (under the "/ 3013 restconf/data" entry point). 3015 RFC Ed.: update the date below with the date of RFC publication and 3016 remove this note. 3018 file "ietf-restconf@2016-03-16.yang" 3020 module ietf-restconf { 3021 yang-version 1.1; 3022 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 3023 prefix "rc"; 3025 organization 3026 "IETF NETCONF (Network Configuration) Working Group"; 3028 contact 3029 "WG Web: 3030 WG List: 3032 WG Chair: Mehmet Ersue 3033 3035 WG Chair: Mahesh Jethanandani 3036 3038 Editor: Andy Bierman 3039 3041 Editor: Martin Bjorklund 3042 3044 Editor: Kent Watsen 3045 "; 3047 description 3048 "This module contains conceptual YANG specifications 3049 for basic RESTCONF media type definitions used in 3050 RESTCONF protocol messages. 3052 Note that the YANG definitions within this module do not 3053 represent configuration data of any kind. 3054 The 'restconf-media-type' YANG extension statement 3055 provides a normative syntax for XML and JSON message 3056 encoding purposes. 3058 Copyright (c) 2016 IETF Trust and the persons identified as 3059 authors of the code. All rights reserved. 3061 Redistribution and use in source and binary forms, with or 3062 without modification, is permitted pursuant to, and subject 3063 to the license terms contained in, the Simplified BSD License 3064 set forth in Section 4.c of the IETF Trust's Legal Provisions 3065 Relating to IETF Documents 3066 (http://trustee.ietf.org/license-info). 3068 This version of this YANG module is part of RFC XXXX; see 3069 the RFC itself for full legal notices."; 3071 // RFC Ed.: replace XXXX with actual RFC number and remove this 3072 // note. 3074 // RFC Ed.: remove this note 3075 // Note: extracted from draft-ietf-netconf-restconf-12.txt 3077 // RFC Ed.: update the date below with the date of RFC publication 3078 // and remove this note. 3079 revision 2016-03-16 { 3080 description 3081 "Initial revision."; 3082 reference 3083 "RFC XXXX: RESTCONF Protocol."; 3084 } 3086 extension restconf-media-type { 3087 argument media-type-id { 3088 yin-element true; 3090 } 3091 // RFC Ed.: replace draft-ietf-netmod-yang-json with RFC number 3092 // in the description below, and remove this note. 3093 description 3094 "This extension is used to specify a YANG data structure which 3095 represents a conceptual RESTCONF media type. 3096 Data definition statements within this extension specify 3097 the generic syntax for the specific media type. 3099 YANG is mapped to specific encoding formats outside the 3100 scope of this extension statement. RFC 6020 defines XML 3101 encoding rules for all RESTCONF media types that use 3102 the '+xml' suffix. draft-ietf-netmod-yang-json defines 3103 JSON encoding rules for all RESTCONF media types that 3104 use the '+json' suffix. 3106 The 'media-type-id' parameter value identifies the media type 3107 that is being defined. It contains the string associated 3108 with the generic media type, i.e., no suffix is specified. 3110 This extension is ignored unless it appears as a top-level 3111 statement. It SHOULD contain data definition statements 3112 that result in exactly one container data node definition. 3113 This allows compliant translation to an XML instance 3114 document for each media type. 3116 The module name and namespace value for the YANG module using 3117 the extension statement is assigned to instance document data 3118 conforming to the data definition statements within 3119 this extension. 3121 The sub-statements of this extension MUST follow the 3122 'data-def-stmt' rule in the YANG ABNF. 3124 The XPath document root is the extension statement itself, 3125 such that the child nodes of the document root are 3126 represented by the data-def-stmt sub-statements within 3127 this extension. This conceptual document is the context 3128 for the following YANG statements: 3130 - must-stmt 3131 - when-stmt 3132 - path-stmt 3133 - min-elements-stmt 3134 - max-elements-stmt 3135 - mandatory-stmt 3136 - unique-stmt 3137 - ordered-by 3138 - instance-identifier data type 3140 The following data-def-stmt sub-statements have special 3141 meaning when used within a restconf-resource extension 3142 statement. 3144 - The list-stmt is not required to have a key-stmt defined. 3145 - The if-feature-stmt is ignored if present. 3146 - The config-stmt is ignored if present. 3147 - The available identity values for any 'identityref' 3148 leaf or leaf-list nodes is limited to the module 3149 containing this extension statement, and the modules 3150 imported into that module. 3151 "; 3152 } 3154 rc:restconf-media-type "application/yang.errors" { 3155 uses errors; 3156 } 3158 rc:restconf-media-type "application/yang.api" { 3159 uses restconf; 3160 } 3162 grouping errors { 3163 description 3164 "A grouping that contains a YANG container 3165 representing the syntax and semantics of a 3166 YANG Patch errors report within a response message."; 3168 container errors { 3169 description 3170 "Represents an error report returned by the server if 3171 a request results in an error."; 3173 list error { 3174 description 3175 "An entry containing information about one 3176 specific error that occurred while processing 3177 a RESTCONF request."; 3178 reference "RFC 6241, Section 4.3"; 3180 leaf error-type { 3181 type enumeration { 3182 enum transport { 3183 description "The transport layer"; 3184 } 3185 enum rpc { 3186 description "The rpc or notification layer"; 3187 } 3188 enum protocol { 3189 description "The protocol operation layer"; 3190 } 3191 enum application { 3192 description "The server application layer"; 3193 } 3194 } 3195 mandatory true; 3196 description 3197 "The protocol layer where the error occurred."; 3198 } 3200 leaf error-tag { 3201 type string; 3202 mandatory true; 3203 description 3204 "The enumerated error tag."; 3205 } 3207 leaf error-app-tag { 3208 type string; 3209 description 3210 "The application-specific error tag."; 3211 } 3213 leaf error-path { 3214 type instance-identifier; 3215 description 3216 "The YANG instance identifier associated 3217 with the error node."; 3218 } 3220 leaf error-message { 3221 type string; 3222 description 3223 "A message describing the error."; 3224 } 3226 anydata error-info { 3227 description 3228 "This anydata value MUST represent a container with 3229 zero or more data nodes representing additional 3230 error information."; 3231 } 3232 } 3233 } 3235 } 3237 grouping restconf { 3238 description 3239 "Conceptual container representing the 3240 application/yang.api resource type."; 3242 container restconf { 3243 description 3244 "Conceptual container representing the 3245 application/yang.api resource type."; 3247 container data { 3248 description 3249 "Container representing the application/yang.datastore 3250 resource type. Represents the conceptual root of all 3251 state data and configuration data supported by 3252 the server. The child nodes of this container can be 3253 any data resource (application/yang.data), which are 3254 defined as top-level data nodes from the YANG modules 3255 advertised by the server in the ietf-restconf-monitoring 3256 module."; 3257 } 3259 container operations { 3260 description 3261 "Container for all operation resources 3262 (application/yang.operation), 3264 Each resource is represented as an empty leaf with the 3265 name of the RPC operation from the YANG rpc statement. 3267 E.g.; 3269 POST /restconf/operations/show-log-errors 3271 leaf show-log-errors { 3272 type empty; 3273 } 3274 "; 3275 } 3277 leaf yang-library-version { 3278 type string { 3279 pattern '\d{4}-\d{2}-\d{2}'; 3280 } 3281 config false; 3282 mandatory true; 3283 description 3284 "Identifies the revision date of the ietf-yang-library 3285 module that is implemented by this RESTCONF server. 3286 Indicates the year, month, and day in YYYY-MM-DD 3287 numeric format."; 3288 } 3289 } 3290 } 3292 } 3294 3296 9. RESTCONF Monitoring 3298 The "ietf-restconf-monitoring" module provides information about the 3299 RESTCONF protocol capabilities and event notification streams 3300 available from the server. A RESTCONF server MUST implement the "/ 3301 restconf-state/capabilities" container in this module. 3303 YANG Tree Diagram for "ietf-restconf-monitoring" module: 3305 +--ro restconf-state 3306 +--ro capabilities 3307 | +--ro capability* inet:uri 3308 +--ro streams 3309 +--ro stream* [name] 3310 +--ro name string 3311 +--ro description? string 3312 +--ro replay-support? boolean 3313 +--ro replay-log-creation-time? yang:date-and-time 3314 +--ro access* [encoding] 3315 +--ro encoding string 3316 +--ro location inet:uri 3318 9.1. restconf-state/capabilities 3320 This mandatory container holds the RESTCONF protocol capability URIs 3321 supported by the server. 3323 The server MUST maintain a last-modified timestamp for this 3324 container, and return the "Last-Modified" header when this data node 3325 is retrieved with the GET or HEAD methods. 3327 The server SHOULD maintain an entity-tag for this container, and 3328 return the "ETag" header when this data node is retrieved with the 3329 GET or HEAD methods. 3331 The server MUST include a "capability" URI leaf-list entry for the 3332 "defaults" mode used by the server, defined in Section 9.1.2. 3334 The server MUST include a "capability" URI leaf-list entry 3335 identifying each supported optional protocol feature. This includes 3336 optional query parameters and MAY include other capability URIs 3337 defined outside this document. 3339 9.1.1. Query Parameter URIs 3341 A new set of RESTCONF Capability URIs are defined to identify the 3342 specific query parameters (defined in Section 4.8) supported by the 3343 server. 3345 The server MUST include a "capability" leaf-list entry for each 3346 optional query parameter that it supports. 3348 +-------------+-------+---------------------------------------------+ 3349 | Name | Secti | URI | 3350 | | on | | 3351 +-------------+-------+---------------------------------------------+ 3352 | depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 | 3353 | | | .0 | 3354 | fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: | 3355 | | | 1.0 | 3356 | filter | 4.8.4 | urn:ietf:params:restconf:capability:filter: | 3357 | | | 1.0 | 3358 | replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: | 3359 | | 4.8.8 | 1.0 | 3360 | with- | 4.8.9 | urn:ietf:params:restconf:capability:with- | 3361 | defaults | | defaults:1.0 | 3362 +-------------+-------+---------------------------------------------+ 3364 RESTCONF Query Parameter URIs 3366 9.1.2. The "defaults" Protocol Capability URI 3368 This URI identifies the defaults handling mode that is used by the 3369 server for processing default leafs in requests for data resources. 3370 A parameter named "basic-mode" is required for this capability URI. 3371 The "basic-mode" definitions are specified in the "With-Defaults 3372 Capability for NETCONF" [RFC6243]. 3374 +----------+--------------------------------------------------+ 3375 | Name | URI | 3376 +----------+--------------------------------------------------+ 3377 | defaults | urn:ietf:params:restconf:capability:defaults:1.0 | 3378 +----------+--------------------------------------------------+ 3379 RESTCONF defaults capability URI 3381 This protocol capability URI MUST be supported by the server, and 3382 MUST be listed in the "capability" leaf-list in Section 9.3. 3384 +------------------+------------------------------------------------+ 3385 | Value | Description | 3386 +------------------+------------------------------------------------+ 3387 | report-all | No data nodes are considered default | 3388 | trim | Values set to the YANG default-stmt value are | 3389 | | default | 3390 | explicit | Values set by the client are never considered | 3391 | | default | 3392 +------------------+------------------------------------------------+ 3394 If the "basic-mode" is set to "report-all" then the server MUST 3395 adhere to the defaults handling behavior defined in Section 2.1 of 3396 [RFC6243]. 3398 If the "basic-mode" is set to "trim" then the server MUST adhere to 3399 the defaults handling behavior defined in Section 2.2 of [RFC6243]. 3401 If the "basic-mode" is set to "explicit" then the server MUST adhere 3402 to the defaults handling behavior defined in Section 2.3 of 3403 [RFC6243]. 3405 Example: (split for display purposes only) 3407 urn:ietf:params:restconf:capability:defaults:1.0? 3408 basic-mode=explicit 3410 9.2. restconf-state/streams 3412 This optional container provides access to the event notification 3413 streams supported by the server. The server MAY omit this container 3414 if no event notification streams are supported. 3416 The server will populate this container with a stream list entry for 3417 each stream type it supports. Each stream contains a leaf called 3418 "events" which contains a URI that represents an event stream 3419 resource. 3421 Stream resources are defined in Section 3.8. Notifications are 3422 defined in Section 6. 3424 9.3. RESTCONF Monitoring Module 3425 The "ietf-restconf-monitoring" module defines monitoring information 3426 for the RESTCONF protocol. 3428 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 3429 are used by this module for some type definitions. 3431 RFC Ed.: update the date below with the date of RFC publication and 3432 remove this note. 3434 file "ietf-restconf-monitoring@2016-03-16.yang" 3436 module ietf-restconf-monitoring { 3437 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; 3438 prefix "rcmon"; 3440 import ietf-yang-types { prefix yang; } 3441 import ietf-inet-types { prefix inet; } 3443 organization 3444 "IETF NETCONF (Network Configuration) Working Group"; 3446 contact 3447 "WG Web: 3448 WG List: 3450 WG Chair: Mehmet Ersue 3451 3453 WG Chair: Mahesh Jethanandani 3454 3456 Editor: Andy Bierman 3457 3459 Editor: Martin Bjorklund 3460 3462 Editor: Kent Watsen 3463 "; 3465 description 3466 "This module contains monitoring information for the 3467 RESTCONF protocol. 3469 Copyright (c) 2016 IETF Trust and the persons identified as 3470 authors of the code. All rights reserved. 3472 Redistribution and use in source and binary forms, with or 3473 without modification, is permitted pursuant to, and subject 3474 to the license terms contained in, the Simplified BSD License 3475 set forth in Section 4.c of the IETF Trust's Legal Provisions 3476 Relating to IETF Documents 3477 (http://trustee.ietf.org/license-info). 3479 This version of this YANG module is part of RFC XXXX; see 3480 the RFC itself for full legal notices."; 3482 // RFC Ed.: replace XXXX with actual RFC number and remove this 3483 // note. 3485 // RFC Ed.: remove this note 3486 // Note: extracted from draft-ietf-netconf-restconf-12.txt 3488 // RFC Ed.: update the date below with the date of RFC publication 3489 // and remove this note. 3490 revision 2016-03-16 { 3491 description 3492 "Initial revision."; 3493 reference 3494 "RFC XXXX: RESTCONF Protocol."; 3495 } 3497 container restconf-state { 3498 config false; 3499 description 3500 "Contains RESTCONF protocol monitoring information."; 3502 container capabilities { 3503 description 3504 "Contains a list of protocol capability URIs"; 3506 leaf-list capability { 3507 type inet:uri; 3508 description "A RESTCONF protocol capability URI."; 3509 } 3510 } 3512 container streams { 3513 description 3514 "Container representing the notification event streams 3515 supported by the server."; 3516 reference 3517 "RFC 5277, Section 3.4, element."; 3519 list stream { 3520 key name; 3521 description 3522 "Each entry describes an event stream supported by 3523 the server."; 3525 leaf name { 3526 type string; 3527 description "The stream name"; 3528 reference "RFC 5277, Section 3.4, element."; 3529 } 3531 leaf description { 3532 type string; 3533 description "Description of stream content"; 3534 reference 3535 "RFC 5277, Section 3.4, element."; 3536 } 3538 leaf replay-support { 3539 type boolean; 3540 description 3541 "Indicates if replay buffer supported for this stream. 3542 If 'true', then the server MUST support the 'start-time' 3543 and 'stop-time' query parameters for this stream."; 3544 reference 3545 "RFC 5277, Section 3.4, element."; 3546 } 3548 leaf replay-log-creation-time { 3549 when "../replay-support" { 3550 description 3551 "Only present if notification replay is supported"; 3552 } 3553 type yang:date-and-time; 3554 description 3555 "Indicates the time the replay log for this stream 3556 was created."; 3557 reference 3558 "RFC 5277, Section 3.4, 3559 element."; 3560 } 3562 list access { 3563 key encoding; 3564 min-elements 1; 3565 description 3566 "The server will create an entry in this list for each 3567 encoding format that is supported for this stream. 3568 The media type 'application/yang.stream' is expected 3569 for all event streams. This list identifies the 3570 sub-types supported for this stream."; 3572 leaf encoding { 3573 type string; 3574 description 3575 "This is the secondary encoding format within the 3576 'text/event-stream' encoding used by all streams. 3577 The type 'xml' is supported for the media type 3578 'application/yang.stream+xml'. The type 'json' 3579 is supported for the media type 3580 'application/yang.stream+json'."; 3582 } 3584 leaf location { 3585 type inet:uri; 3586 mandatory true; 3587 description 3588 "Contains a URL that represents the entry point 3589 for establishing notification delivery via server 3590 sent events."; 3591 } 3592 } 3593 } 3594 } 3595 } 3597 } 3599 3601 10. YANG Module Library 3603 The "ietf-yang-library" module defined in 3604 [I-D.ietf-netconf-yang-library] provides information about the YANG 3605 modules and submodules used by the RESTCONF server. Implementation 3606 is mandatory for RESTCONF servers. All YANG modules and submodules 3607 used by the server MUST be identified in the YANG module library. 3609 10.1. modules 3611 This mandatory container holds the identifiers for the YANG data 3612 model modules supported by the server. 3614 The server MUST maintain a last-modified timestamp for this 3615 container, and return the "Last-Modified" header when this data node 3616 is retrieved with the GET or HEAD methods. 3618 The server SHOULD maintain an entity-tag for this container, and 3619 return the "ETag" header when this data node is retrieved with the 3620 GET or HEAD methods. 3622 10.1.1. modules/module 3624 This mandatory list contains one entry for each YANG data model 3625 module supported by the server. There MUST be an instance of this 3626 list for every YANG module that is used by the server. 3628 The contents of this list are defined in the "module" YANG list 3629 statement in [I-D.ietf-netconf-yang-library]. 3631 The server SHOULD maintain a last-modified timestamp for each 3632 instance of this list entry, and return the "Last-Modified" header 3633 when this data node is retrieved with the GET or HEAD methods. 3635 The server SHOULD maintain an entity-tag for each instance of this 3636 list entry, and return the "ETag" header when this data node is 3637 retrieved with the GET or HEAD methods. 3639 11. IANA Considerations 3641 11.1. The "restconf" Relation Type 3643 This specification registers the "restconf" relation type in the Link 3644 Relation Type Registry defined by [RFC5988]: 3646 Relation Name: restconf 3648 Description: Identifies the root of RESTCONF API as configured 3649 on this HTTP server. The "restconf" relation 3650 defines the root of the API defined in RFCXXXX. 3651 Subsequent revisions of RESTCONF will use alternate 3652 relation values to support protocol versioning. 3654 Reference: RFCXXXX 3656 ` 3658 11.2. YANG Module Registry 3660 This document registers two URIs in the IETF XML registry [RFC3688]. 3661 Following the format in RFC 3688, the following registration is 3662 requested to be made. 3664 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 3665 Registrant Contact: The NETMOD WG of the IETF. 3667 XML: N/A, the requested URI is an XML namespace. 3669 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3670 Registrant Contact: The NETMOD WG of the IETF. 3671 XML: N/A, the requested URI is an XML namespace. 3673 This document registers two YANG modules in the YANG Module Names 3674 registry [RFC6020]. 3676 name: ietf-restconf 3677 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3678 prefix: rc 3679 // RFC Ed.: replace XXXX with RFC number and remove this note 3680 reference: RFCXXXX 3682 name: ietf-restconf-monitoring 3683 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3684 prefix: rcmon 3685 // RFC Ed.: replace XXXX with RFC number and remove this note 3686 reference: RFCXXXX 3688 11.3. application/yang Media Sub Types 3690 The parent MIME media type for RESTCONF resources is application/ 3691 yang, which is defined in [RFC6020]. This document defines the 3692 following sub-types for this media type. 3694 - api 3695 - data 3696 - datastore 3697 - errors 3698 - operation 3699 - stream 3701 Type name: application 3703 Subtype name: yang.xxx, where "xxx" is 1 of "api", 3704 "data", "datastore", "errors", "operation", or "stream" 3706 Required parameters: none 3708 Optional parameters: See section 4.8 in RFC XXXX 3710 Encoding considerations: 8-bit 3712 Security considerations: See Section 12 in RFC XXXX 3714 Interoperability considerations: none 3715 // RFC Ed.: replace XXXX with RFC number and remove this note 3716 Published specification: RFC XXXX 3718 11.4. RESTCONF Capability URNs 3720 [Note to RFC Editor: 3721 The RESTCONF Protocol Capability Registry does not yet exist; 3722 Need to ask IANA to create it; remove this note for publication 3723 ] 3725 This document defines a registry for RESTCONF capability identifiers. 3726 The name of the registry is "RESTCONF Capability URNs". The review 3727 policy for this registry is "IETF Review". The registry shall record 3728 for each entry: 3730 o the name of the RESTCONF capability. By convention, this name is 3731 prefixed with the colon ':' character. 3733 o the URN for the RESTCONF capability. 3735 This document registers several capability identifiers in "RESTCONF 3736 Capability URNs" registry: 3738 Index 3739 Capability Identifier 3740 ------------------------ 3742 :defaults 3743 urn:ietf:params:restconf:capability:defaults:1.0 3745 :depth 3746 urn:ietf:params:restconf:capability:depth:1.0 3748 :fields 3749 urn:ietf:params:restconf:capability:fields:1.0 3751 :filter 3752 urn:ietf:params:restconf:capability:filter:1.0 3754 :replay 3755 urn:ietf:params:restconf:capability:replay:1.0 3757 :with-defaults 3758 urn:ietf:params:restconf:capability:with-defaults:1.0 3760 12. Security Considerations 3761 This section provides security considerations for the resources 3762 defined by the RESTCONF protocol. Security considerations for HTTPS 3763 are defined in [RFC2818]. RESTCONF does not specify which YANG 3764 modules a server needs to support. Security considerations for the 3765 YANG-defined content manipulated by RESTCONF can be found in the 3766 documents defining those YANG modules. 3768 This document does not require use of a specific client 3769 authentication mechanism or authorization model, but it does require 3770 that a client authentication mechanism and authorization model is 3771 used whenever a client accesses a protected resource. Client 3772 authentication MUST be implemented using client certificates or MUST 3773 be implemented using an HTTP authentication scheme. Client 3774 authorization MAY be configured using the NETCONF Access Control 3775 Model (NACM) [RFC6536]. 3777 Configuration information is by its very nature sensitive. Its 3778 transmission in the clear and without integrity checking leaves 3779 devices open to classic eavesdropping and false data injection 3780 attacks. Configuration information often contains passwords, user 3781 names, service descriptions, and topological information, all of 3782 which are sensitive. Because of this, this protocol SHOULD be 3783 implemented carefully with adequate attention to all manner of attack 3784 one might expect to experience with other management interfaces. 3786 Different environments may well allow different rights prior to and 3787 then after authentication. When an operation is not properly 3788 authorized, the RESTCONF server MUST return a "401 Unauthorized" 3789 status-line. Note that authorization information can be exchanged in 3790 the form of configuration information, which is all the more reason 3791 to ensure the security of the connection. 3793 13. Acknowledgements 3795 The authors would like to thank the following people for their 3796 contributions to this document: Ladislav Lhotka, Juergen 3797 Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. 3799 The authors would like to thank the following people for their 3800 excellent review comments and contributions to this document: Qin Wu, 3801 Joe Clarke, Bert Wijnen, Ladislav Lhotka, Rodney Cummings, Frank 3802 Xialiang, Tom Petch, Robert Sparks, Balint Uveges, Randy Presuhn, and 3803 Sue Hares. 3805 Contributions to this material by Andy Bierman are based upon work 3806 supported by the The Space & Terrestrial Communications Directorate 3807 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 3808 and conclusions or recommendations expressed in this material are 3809 those of the author(s) and do not necessarily reflect the views of 3810 The Space & Terrestrial Communications Directorate (S&TCD). 3812 14. References 3814 14.1. Normative References 3816 [I-D.ietf-netconf-yang-library] 3817 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 3818 Library", draft-ietf-netconf-yang-library-05 (work in 3819 progress), April 2016. 3821 [I-D.ietf-netmod-rfc6020bis] 3822 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 3823 draft-ietf-netmod-rfc6020bis-11 (work in progress), 3824 February 2016. 3826 [I-D.ietf-netmod-yang-json] 3827 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3828 draft-ietf-netmod-yang-json-06 (work in progress), October 3829 2015. 3831 [I-D.ietf-netmod-yang-metadata] 3832 Lhotka, L., "Defining and Using Metadata with YANG", 3833 draft-ietf-netmod-yang-metadata-02 (work in progress), 3834 September 2015. 3836 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3837 Extensions (MIME) Part Two: Media Types", RFC 2046, 3838 November 1996. 3840 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3841 Requirement Levels", BCP 14, RFC 2119, March 1997. 3843 [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. 3845 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3846 January 2004. 3848 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3849 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3850 3986, January 2005. 3852 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3853 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3855 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3856 Notifications", RFC 5277, July 2008. 3858 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3859 Housley, R., and T. Polk, "Internet X.509 Public Key 3860 Infrastructure Certificate and Certificate Revocation List 3861 (CRL) Profile", RFC 5280, May 2008. 3863 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3864 5789, March 2010. 3866 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3868 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 3869 Network Configuration Protocol (NETCONF)", RFC 6020, 3870 October 2010. 3872 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3873 Verification of Domain-Based Application Service Identity 3874 within Internet Public Key Infrastructure Using X.509 3875 (PKIX) Certificates in the Context of Transport Layer 3876 Security (TLS)", RFC 6125, March 2011. 3878 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3879 and A. Bierman, Ed., "Network Configuration Protocol 3880 (NETCONF)", RFC 6241, June 2011. 3882 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 3883 NETCONF", RFC 6243, June 2011. 3885 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 3886 6415, October 2011. 3888 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 3889 Protocol (NETCONF) Access Control Model", RFC 6536, March 3890 2012. 3892 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3893 and D. Orchard, "URI Template", RFC 6570, March 2012. 3895 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 3896 July 2013. 3898 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3899 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3900 2014, . 3902 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3903 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 3904 2014. 3906 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3907 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3909 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3910 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 3912 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3913 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3915 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 3916 7320, July 2014. 3918 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 3919 NETCONF Protocol over Transport Layer Security (TLS) with 3920 Mutual X.509 Authentication", RFC 7589, DOI 10.17487/ 3921 RFC7589, June 2015, 3922 . 3924 [W3C.CR-eventsource-20121211] 3925 Hickson, I., "Server-Sent Events", World Wide Web 3926 Consortium CR CR-eventsource-20121211, December 2012, 3927 . 3929 [W3C.REC-html5-20141028] 3930 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 3931 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", World 3932 Wide Web Consortium Recommendation REC-html5-20141028, 3933 October 2014, 3934 . 3936 [W3C.REC-xml-20081126] 3937 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 3938 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 3939 Edition)", World Wide Web Consortium Recommendation REC- 3940 xml-20081126, November 2008, 3941 . 3943 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 3944 Version 1.0", World Wide Web Consortium Recommendation 3945 REC-xpath-19991116, November 1999, 3946 . 3948 14.2. Informative References 3950 [I-D.ietf-netconf-yang-patch] 3951 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 3952 Media Type", draft-ietf-netconf-yang-patch-06 (work in 3953 progress), October 2015. 3955 [rest-dissertation] 3956 Fielding, R., "Architectural Styles and the Design of 3957 Network-based Software Architectures", 2000. 3959 Appendix A. Change Log 3961 -- RFC Ed.: remove this section before publication. 3963 The RESTCONF issue tracker can be found here: https://github.com/ 3964 netconf-wg/restconf/issues 3966 A.1. v11 - v12 3968 o clarify query parameter requirements 3970 o move filter query section to match table order in sec. 4.8 3972 o clarify that depth default is entire subtree for datastore 3973 resource 3975 o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml 3977 o made implementation of timestamps optional since ETags are 3978 mandatory 3980 o removed confusing text about data resource definition revision 3981 date 3983 o clarify that errors should be returned for any resource type 3985 o clarified media subtype (not type) for error response 3987 o clarified client SHOULD (not MAY) specify errors format in Accept 3988 header 3990 o clarified terminology in many sections 3992 A.2. v10 - v11 3994 o change term 'operational data' to 'state data' 3996 o clarify :startup behavior 3998 o clarify X.509 security text 4000 o change '403 Forbidden' to '401 Unauthorized' for GET error 4002 o clarify MUST have one "restconf" link relation 4003 o clarify that NV-storage is not mandatory 4005 o clarify how "Last-Modified" and "ETag" header info can be used by 4006 a client 4008 o clarify meaning of mandatory parameter 4010 o fix module name in action examples 4012 o clarify operation resource request needs to be known to parse the 4013 output 4015 o clarify ordered-by user terminology 4017 o fixed JSON example in D.1.1 4019 A.3. v09 - v10 4021 o address review comments: github issue #36 4023 o removed intro text about no knowledge of NETCONF needed 4025 o clarified candidate and confirmed-commit behavior in sec. 1.3 4027 o clarified that a RESTCONF server MUST support TLS 4029 o clarified choice of 403 or 404 error 4031 o fixed forward references to URI template (w/reference at first 4032 use) 4034 o added reference to HTML5 4036 o made error terminology more consistent 4038 o clarified that only 1 list or leaf-list instance can be returned 4039 in an XML response message-body 4041 o clarified that more than 1 instance must not be created by a POST 4042 method 4044 o clarified that PUT cannot be used to change a leaf-list value or 4045 any list key values 4047 o clarified that PATCH cannot be used to change a leaf-list value or 4048 any list key values 4050 o clarified that DELETE should not be used to delete more than one 4051 instance of a leaf-list or list 4053 o update JSON RFC reference 4055 o specified that leaf-list instances are data resources 4057 o specified how a leaf-list instance identifier is constructed 4059 o fixed get-schema example 4061 o clarified that if no Accept header the server SHOULD return the 4062 type specified in RESTCONF, but MAY return any media-type, 4063 according to HTTP rules 4065 o clarified that server SHOULD maintain timestamp and etag for data 4066 resources 4068 o clarified default for content query parameter 4070 o moved terminology section earlier in doc to avoid forward usage 4072 o clarified intro text wrt/ interactions with NETCONF and access to 4073 specific datastores 4075 o clarified server implementation requirements for YANG defaults 4077 o clarified that Errors is not a resource, just a media type 4079 o clarified that HTTP without TLS MUST NOT be used 4081 o add RESTCONF Extensibility section to make it clear how RESTCONF 4082 will be extended in the future 4084 o add text warning that NACM does not work with HTTP caching 4086 o remove sec. 5.2 Message Headers 4088 o remove 202 Accepted from list of used status-lines -- not allowed 4090 o made implementation of OPTIONS MUST instead of SHOULD 4092 o clarified that successful PUT for altering data returns 204 4094 o fixed "point" parameter example 4096 o added example of alternate value for root resource discovery 4097 o added YANG action examples 4099 o fixed some JSON examples 4101 o changed default value for content query parameter to "all" 4103 o changed empty container JSON encoding from "[null]" to "{}" 4105 o added mandatory /restconf/yang-library-version leaf to advertise 4106 revision-date of the YANG library implemented by the server 4108 o clarified URI encoding rules for leaf-list 4110 o clarified sec. 2.2 wrt/ certificates and TLS 4112 o added update procedure for entity tag and timestamp 4114 A.4. v08 - v09 4116 o fix introduction text regarding implementation requirements for 4117 the ietf-yang-library 4119 o clarified HTTP authentication requirements 4121 o fix host-meta example 4123 o changed list key encoding to clarify that quoted strings are not 4124 allowed. Percent-encoded values are used if quotes would be 4125 required. A missing key is treated as a zero-length string 4127 o Fixed example of percent-encoded string to match YANG model 4129 o Changed streams examples to align with naming already used 4131 A.5. v07 - v08 4133 o add support for YANG 1.1 action statement 4135 o changed mandatory encoding from XML to XML or JSON 4137 o fix syntax in fields parameter definition 4139 o add meta-data encoding examples for XML and JSON 4141 o remove RFC 2396 references and update with 3986 4142 o change encoding of a key so quoted string are not used, since they 4143 are already percent-encoded. A zero-length string is not encoded 4144 (/list=foo,,baz) 4146 o Add example of percent-encoded key value 4148 A.6. v06 - v07 4150 o fixed all issues identified in email from Jernej Tuljak in netconf 4151 email 2015-06-22 4153 o fixed error example bug where error-urlpath was still used. 4154 Changed to error-path. 4156 o added mention of YANG Patch and informative reference 4158 o added support for YANG 1.1, specifically support for anydata and 4159 actions 4161 o removed the special field value "*", since it is no longer needed 4163 A.7. v05 - v06 4165 o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) 4167 A.8. v04 - v05 4169 o changed term 'notification event' to 'event notification' 4171 o removed intro text about framework and meta-model 4173 o removed early mention of API resources 4175 o removed term unified datastore and cleaned up text about NETCONF 4176 datastores 4178 o removed text about not immediate persistence of edits 4180 o removed RESTCONF-specific data-resource-identifier typedef and its 4181 usage 4183 o clarified encoding of key leafs 4185 o changed several examples from JSON to XML encoding 4187 o made 'insert' and 'point' query parameters mandatory to implement 4189 o removed ":insert" capability URI 4190 o renamed stream/encoding to stream/access 4192 o renamed stream/encoding/type to stream/access/encoding 4194 o renamed stream/encoding/events to stream/access/location 4196 o changed XPath from informative to normative reference 4198 o changed rest-dissertation from normative to informative reference 4200 o changed example-jukebox playlist 'id' from a data-resource- 4201 identifier to a leafref pointing at the song name 4203 A.9. v03 - v04 4205 o renamed 'select' to 'fields' (#1) 4207 o moved collection resource and page capability to draft-ietf- 4208 netconf-restconf-collection-00 (#3) 4210 o added mandatory "defaults" protocol capability URI (#4) 4212 o added optional "with-defaults" query parameter URI (#4) 4214 o clarified authentication procedure (#9) 4216 o moved ietf-yang-library module to draft-ietf-netconf-yang- 4217 library-00 (#13) 4219 o clarified that JSON encoding of module name in a URI MUST follow 4220 the netmod-yang-json encoding rules (#14) 4222 o added restconf-media-type extension (#15) 4224 o remove "content" query parameter URI and made this parameter 4225 mandatory (#16) 4227 o clarified datastore usage 4229 o changed lock-denied error example 4231 o added with-defaults query parameter example 4233 o added term "RESTCONF Capability" 4235 o changed NETCONF Capability URI registry usage to new RESTCONF 4236 Capability URI Registry usage 4238 A.10. v02 - v03 4240 o added collection resource 4242 o added "page" query parameter capability 4244 o added "limit" and "offset" query parameters, which are available 4245 if the "page" capability is supported 4247 o added "stream list" term 4249 o fixed bugs in some examples 4251 o added "encoding" list within the "stream" list to allow different 4252 URLs for XML and JSON encoding. 4254 o made XML MUST implement and JSON MAY implement for servers 4256 o re-add JSON notification examples (previously removed) 4258 o updated JSON references 4260 A.11. v01 - v02 4262 o moved query parameter definitions from the YANG module back to the 4263 plain text sections 4265 o made all query parameters optional to implement 4267 o defined query parameter capability URI 4269 o moved 'streams' to new YANG module (ietf-restconf-monitoring) 4271 o added 'capabilities' container to new YANG module (ietf-restconf- 4272 monitoring) 4274 o moved 'modules' container to new YANG module (ietf-yang-library) 4276 o added new leaf 'module-set-id' (ietf-yang-library) 4278 o added new leaf 'conformance' (ietf-yang-library) 4280 o changed 'schema' leaf to type inet:uri that returns the location 4281 of the YANG schema (instead of returning the schema directly) 4283 o changed 'events' leaf to type inet:uri that returns the location 4284 of the event stream resource (instead of returning events 4285 directly) 4287 o changed examples for yang.api resource since the monitoring 4288 information is no longer in this resource 4290 o closed issue #1 'select parameter' since no objections to the 4291 proposed syntax 4293 o closed "encoding of list keys" issue since no objection to new 4294 encoding of list keys in a target resource URI. 4296 o moved open issues list to the issue tracker on github 4298 A.12. v00 - v01 4300 o fixed content=nonconfig example (non-config was incorrect) 4302 o closed open issue 'message-id'. There is no need for a message-id 4303 field, and RFC 2392 does not apply. 4305 o closed open issue 'server support verification'. The headers used 4306 by RESTCONF are widely supported. 4308 o removed encoding rules from section on RESTCONF Meta-Data. This 4309 is now defined in "I-D.lhotka-netmod-yang-json". 4311 o added media type application/yang.errors to map to errors YANG 4312 grouping. Updated error examples to use new media type. 4314 o closed open issue 'additional datastores'. Support may be added 4315 in the future to identify new datastores. 4317 o closed open issue 'PATCH media type discovery'. The section on 4318 PATCH has an added sentence on the Accept-Patch header. 4320 o closed open issue 'YANG to resource mapping'. Current mapping of 4321 all data nodes to resources will be used in order to allow 4322 mandatory DELETE support. The PATCH operation is optional, as 4323 well as the YANG Patch media type. 4325 o closed open issue '_self links for HATEOAS support'. It was 4326 decided that they are redundant because they can be derived from 4327 the YANG module for the specific data. 4329 o added explanatory text for the 'select' parameter. 4331 o added RESTCONF Path Resolution section for discovering the root of 4332 the RESTCONF API using the /.well-known/host-meta. 4334 o added an "error" media type to for structured error messages 4335 o added Secure Transport section requiring TLS 4337 o added Security Considerations section 4339 o removed all references to "REST-like" 4341 A.13. bierman:restconf-04 to ietf:restconf-00 4343 o updated open issues section 4345 Appendix B. Open Issues 4347 -- RFC Ed.: remove this section before publication. 4349 The RESTCONF issues are tracked on github.com: 4351 https://github.com/netconf-wg/restconf/issues 4353 Appendix C. Example YANG Module 4355 The example YANG module used in this document represents a simple 4356 media jukebox interface. 4358 YANG Tree Diagram for "example-jukebox" Module 4360 +--rw jukebox! 4361 +--rw library 4362 | +--rw artist* [name] 4363 | | +--rw name string 4364 | | +--rw album* [name] 4365 | | +--rw name string 4366 | | +--rw genre? identityref 4367 | | +--rw year? uint16 4368 | | +--rw admin 4369 | | | +--rw label? string 4370 | | | +--rw catalogue-number? string 4371 | | +--rw song* [name] 4372 | | +--rw name string 4373 | | +--rw location string 4374 | | +--rw format? string 4375 | | +--rw length? uint32 4376 | +--ro artist-count? uint32 4377 | +--ro album-count? uint32 4378 | +--ro song-count? uint32 4379 +--rw playlist* [name] 4380 | +--rw name string 4381 | +--rw description? string 4382 | +--rw song* [index] 4383 | +--rw index uint32 4384 | +--rw id leafref 4385 +--rw player 4386 +--rw gap? decimal64 4388 rpcs: 4390 +---x play 4391 +--ro input 4392 +--ro playlist string 4393 +--ro song-number uint32 4395 C.1. example-jukebox YANG Module 4397 module example-jukebox { 4399 namespace "http://example.com/ns/example-jukebox"; 4400 prefix "jbox"; 4402 organization "Example, Inc."; 4403 contact "support at example.com"; 4404 description "Example Jukebox Data Model Module"; 4405 revision "2015-04-04" { 4406 description "Initial version."; 4407 reference "example.com document 1-4673"; 4408 } 4410 identity genre { 4411 description "Base for all genre types"; 4412 } 4414 // abbreviated list of genre classifications 4415 identity alternative { 4416 base genre; 4417 description "Alternative music"; 4418 } 4419 identity blues { 4420 base genre; 4421 description "Blues music"; 4422 } 4423 identity country { 4424 base genre; 4425 description "Country music"; 4426 } 4427 identity jazz { 4428 base genre; 4429 description "Jazz music"; 4430 } 4431 identity pop { 4432 base genre; 4433 description "Pop music"; 4434 } 4435 identity rock { 4436 base genre; 4437 description "Rock music"; 4438 } 4440 container jukebox { 4441 presence 4442 "An empty container indicates that the jukebox 4443 service is available"; 4445 description 4446 "Represents a jukebox resource, with a library, playlists, 4447 and a play operation."; 4449 container library { 4451 description "Represents the jukebox library resource."; 4453 list artist { 4454 key name; 4456 description 4457 "Represents one artist resource within the 4458 jukebox library resource."; 4460 leaf name { 4461 type string { 4462 length "1 .. max"; 4463 } 4464 description "The name of the artist."; 4465 } 4467 list album { 4468 key name; 4470 description 4471 "Represents one album resource within one 4472 artist resource, within the jukebox library."; 4474 leaf name { 4475 type string { 4476 length "1 .. max"; 4477 } 4478 description "The name of the album."; 4480 } 4482 leaf genre { 4483 type identityref { base genre; } 4484 description 4485 "The genre identifying the type of music on 4486 the album."; 4487 } 4489 leaf year { 4490 type uint16 { 4491 range "1900 .. max"; 4492 } 4493 description "The year the album was released"; 4494 } 4496 container admin { 4497 description 4498 "Administrative information for the album."; 4500 leaf label { 4501 type string; 4502 description "The label that released the album."; 4503 } 4504 leaf catalogue-number { 4505 type string; 4506 description "The album's catalogue number."; 4507 } 4508 } 4510 list song { 4511 key name; 4513 description 4514 "Represents one song resource within one 4515 album resource, within the jukebox library."; 4517 leaf name { 4518 type string { 4519 length "1 .. max"; 4520 } 4521 description "The name of the song"; 4522 } 4523 leaf location { 4524 type string; 4525 mandatory true; 4526 description 4527 "The file location string of the 4528 media file for the song"; 4529 } 4530 leaf format { 4531 type string; 4532 description 4533 "An identifier string for the media type 4534 for the file associated with the 4535 'location' leaf for this entry."; 4536 } 4537 leaf length { 4538 type uint32; 4539 units "seconds"; 4540 description 4541 "The duration of this song in seconds."; 4542 } 4543 } // end list 'song' 4544 } // end list 'album' 4545 } // end list 'artist' 4547 leaf artist-count { 4548 type uint32; 4549 units "songs"; 4550 config false; 4551 description "Number of artists in the library"; 4552 } 4553 leaf album-count { 4554 type uint32; 4555 units "albums"; 4556 config false; 4557 description "Number of albums in the library"; 4558 } 4559 leaf song-count { 4560 type uint32; 4561 units "songs"; 4562 config false; 4563 description "Number of songs in the library"; 4564 } 4565 } // end library 4567 list playlist { 4568 key name; 4570 description 4571 "Example configuration data resource"; 4573 leaf name { 4574 type string; 4575 description 4576 "The name of the playlist."; 4577 } 4578 leaf description { 4579 type string; 4580 description 4581 "A comment describing the playlist."; 4582 } 4583 list song { 4584 key index; 4585 ordered-by user; 4587 description 4588 "Example nested configuration data resource"; 4590 leaf index { // not really needed 4591 type uint32; 4592 description 4593 "An arbitrary integer index for this playlist song."; 4594 } 4595 leaf id { 4596 type leafref { 4597 path "/jbox:jukebox/jbox:library/jbox:artist/" + 4598 "jbox:album/jbox:song/jbox:name"; 4599 } 4600 mandatory true; 4601 description 4602 "Song identifier. Must identify an instance of 4603 /jukebox/library/artist/album/song/name."; 4604 } 4605 } 4606 } 4608 container player { 4609 description 4610 "Represents the jukebox player resource."; 4612 leaf gap { 4613 type decimal64 { 4614 fraction-digits 1; 4615 range "0.0 .. 2.0"; 4616 } 4617 units "tenths of seconds"; 4618 description "Time gap between each song"; 4619 } 4620 } 4621 } 4623 rpc play { 4624 description "Control function for the jukebox player"; 4625 input { 4626 leaf playlist { 4627 type string; 4628 mandatory true; 4629 description "playlist name"; 4630 } 4631 leaf song-number { 4632 type uint32; 4633 mandatory true; 4634 description "Song number in playlist to play"; 4635 } 4636 } 4637 } 4638 } 4640 Appendix D. RESTCONF Message Examples 4642 The examples within this document use the normative YANG module 4643 defined in Section 8 and the non-normative example YANG module 4644 defined in Appendix C.1. 4646 This section shows some typical RESTCONF message exchanges. 4648 D.1. Resource Retrieval Examples 4650 D.1.1. Retrieve the Top-level API Resource 4652 The client may start by retrieving the top-level API resource, using 4653 the entry point URI "{+restconf}". 4655 GET /restconf HTTP/1.1 4656 Host: example.com 4657 Accept: application/yang.api+json 4659 The server might respond as follows: 4661 HTTP/1.1 200 OK 4662 Date: Mon, 23 Apr 2012 17:01:00 GMT 4663 Server: example-server 4664 Content-Type: application/yang.api+json 4666 { 4667 "ietf-restconf:restconf": { 4668 "data" : {}, 4669 "operations" : {}, 4670 "yang-library-version" : "2016-04-09" 4672 } 4673 } 4675 To request that the response content to be encoded in XML, the 4676 "Accept" header can be used, as in this example request: 4678 GET /restconf HTTP/1.1 4679 Host: example.com 4680 Accept: application/yang.api+xml 4682 The server will return the same response either way, which might be 4683 as follows : 4685 HTTP/1.1 200 OK 4686 Date: Mon, 23 Apr 2012 17:01:00 GMT 4687 Server: example-server 4688 Cache-Control: no-cache 4689 Pragma: no-cache 4690 Content-Type: application/yang.api+xml 4692 4693 4694 4695 2016-04-09 4696 4698 D.1.2. Retrieve The Server Module Information 4700 In this example the client is retrieving the modules information from 4701 the server in JSON format: 4703 GET /restconf/data/ietf-yang-library:modules HTTP/1.1 4704 Host: example.com 4705 Accept: application/yang.data+json 4707 The server might respond as follows (some strings wrapped for display 4708 purposes): 4710 HTTP/1.1 200 OK 4711 Date: Mon, 23 Apr 2012 17:01:00 GMT 4712 Server: example-server 4713 Cache-Control: no-cache 4714 Pragma: no-cache 4715 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4716 Content-Type: application/yang.data+json 4718 { 4719 "ietf-yang-library:modules": { 4720 "module": [ 4721 { 4722 "name" : "foo", 4723 "revision" : "2012-01-02", 4724 "schema" : "https://example.com/modules/foo/2012-01-02", 4725 "namespace" : "http://example.com/ns/foo", 4726 "feature" : [ "feature1", "feature2" ], 4727 "conformance-type" : "implement" 4728 }, 4729 { 4730 "name" : "ietf-yang-library", 4731 "revision" : "2016-04-09", 4732 "schema" : "https://example.com/modules/ietf-yang- 4733 library/2016-04-09", 4734 "namespace" : 4735 "urn:ietf:params:xml:ns:yang:ietf-yang-library", 4736 "conformance-type" : "implement" 4737 }, 4738 { 4739 "name" : "foo-types", 4740 "revision" : "2012-01-05", 4741 "schema" : 4742 "https://example.com/modules/foo-types/2012-01-05", 4743 "namespace" : "http://example.com/ns/foo-types", 4744 "conformance-type" : "import" 4745 }, 4746 { 4747 "name" : "bar", 4748 "revision" : "2012-11-05", 4749 "schema" : "https://example.com/modules/bar/2012-11-05", 4750 "namespace" : "http://example.com/ns/bar", 4751 "feature" : [ "bar-ext" ], 4752 "conformance-type" : "implement", 4753 "submodule" : [ 4754 { 4755 "name" : "bar-submod1", 4756 "revision" : "2012-11-05", 4757 "schema" : 4758 "https://example.com/modules/bar-submod1/2012-11-05" 4759 }, 4760 { 4761 "name" : "bar-submod2", 4762 "revision" : "2012-11-05", 4763 "schema" : 4764 "https://example.com/modules/bar-submod2/2012-11-05" 4765 } 4766 ] 4767 } 4769 ] 4770 } 4771 } 4773 D.1.3. Retrieve The Server Capability Information 4775 In this example the client is retrieving the capability information 4776 from the server in XML format, and the server supports all the 4777 RESTCONF query parameters, plus one vendor parameter: 4779 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 4780 capabilities HTTP/1.1 4781 Host: example.com 4782 Accept: application/yang.data+xml 4784 The server might respond as follows. The extra whitespace in 4785 'capability' elements for display purposes only. 4787 HTTP/1.1 200 OK 4788 Date: Mon, 23 Apr 2012 17:02:00 GMT 4789 Server: example-server 4790 Cache-Control: no-cache 4791 Pragma: no-cache 4792 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4793 Content-Type: application/yang.data+xml 4795 4796 4797 urn:ietf:params:restconf:capability:depth:1.0 4798 4799 4800 urn:ietf:params:restconf:capability:fields:1.0 4801 4802 4803 urn:ietf:params:restconf:capability:filter:1.0 4804 4805 4806 urn:ietf:params:restconf:capability:start-time:1.0 4807 4808 4809 urn:ietf:params:restconf:capability:stop-time:1.0 4810 4811 4812 http://example.com/capabilities/myparam 4813 4814 4816 D.2. Edit Resource Examples 4818 D.2.1. Create New Data Resources 4820 To create a new "artist" resource within the "library" resource, the 4821 client might send the following request. 4823 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 4824 Host: example.com 4825 Content-Type: application/yang.data+json 4827 { 4828 "example-jukebox:artist" : { 4829 "name" : "Foo Fighters" 4830 } 4831 } 4833 If the resource is created, the server might respond as follows. 4834 Note that the "Location" header line is wrapped for display purposes 4835 only: 4837 HTTP/1.1 201 Created 4838 Date: Mon, 23 Apr 2012 17:02:00 GMT 4839 Server: example-server 4840 Location: https://example.com/restconf/data/ 4841 example-jukebox:jukebox/library/artist=Foo%20Fighters 4842 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 4843 ETag: b3830f23a4c 4845 To create a new "album" resource for this artist within the "jukebox" 4846 resource, the client might send the following request. Note that the 4847 request URI header line is wrapped for display purposes only: 4849 POST /restconf/data/example-jukebox:jukebox/ 4850 library/artist=Foo%20Fighters HTTP/1.1 4851 Host: example.com 4852 Content-Type: application/yang.data+xml 4854 4855 Wasting Light 4856 2011 4857 4859 If the resource is created, the server might respond as follows. 4860 Note that the "Location" header line is wrapped for display purposes 4861 only: 4863 HTTP/1.1 201 Created 4864 Date: Mon, 23 Apr 2012 17:03:00 GMT 4865 Server: example-server 4866 Location: https://example.com/restconf/data/ 4867 example-jukebox:jukebox/library/artist=Foo%20Fighters/ 4868 album=Wasting%20Light 4869 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 4870 ETag: b8389233a4c 4872 D.2.2. Detect Resource Entity Tag Change 4874 In this example, the server just supports the mandatory datastore 4875 last-changed timestamp. The client has previously retrieved the 4876 "Last-Modified" header and has some value cached to provide in the 4877 following request to patch an "album" list entry with key value 4878 "Wasting Light". Only the "genre" field is being updated. 4880 PATCH /restconf/data/example-jukebox:jukebox/ 4881 library/artist=Foo%20Fighters/album=Wasting%20Light/genre 4882 HTTP/1.1 4883 Host: example.com 4884 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 4885 Content-Type: application/yang.data+json 4887 { "example-jukebox:genre" : "example-jukebox:alternative" } 4889 In this example the datastore resource has changed since the time 4890 specified in the "If-Unmodified-Since" header. The server might 4891 respond: 4893 HTTP/1.1 412 Precondition Failed 4894 Date: Mon, 23 Apr 2012 19:01:00 GMT 4895 Server: example-server 4896 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 4897 ETag: b34aed893a4c 4899 D.2.3. Edit a Datastore Resource 4901 In this example, the client modifies two different data nodes by 4902 sending a PATCH to the datastore resource: 4904 PATCH /restconf/data HTTP/1.1 4905 Host: example.com 4906 Content-Type: application/yang.datastore+xml 4908 4909 4910 4911 4912 Foo Fighters 4913 4914 Wasting Light 4915 2011 4916 4917 4918 4919 Nick Cave 4920 4921 Tender Prey 4922 1988 4923 4924 4925 4926 4927 4929 D.3. Query Parameter Examples 4931 D.3.1. "content" Parameter 4933 The "content" parameter is used to select the type of data child 4934 resources (configuration and/or not configuration) that are returned 4935 by the server for a GET method request. 4937 In this example, a simple YANG list that has configuration and non- 4938 configuration child resources. 4940 container events 4941 list event { 4942 key name; 4943 leaf name { type string; } 4944 leaf description { type string; } 4945 leaf event-count { 4946 type uint32; 4947 config false; 4948 } 4949 } 4950 } 4952 Example 1: content=all 4954 To retrieve all the child resources, the "content" parameter is set 4955 to "all". The client might send: 4957 GET /restconf/data/example-events:events?content=all 4958 HTTP/1.1 4960 Host: example.com 4961 Accept: application/yang.data+json 4963 The server might respond: 4965 HTTP/1.1 200 OK 4966 Date: Mon, 23 Apr 2012 17:11:30 GMT 4967 Server: example-server 4968 Cache-Control: no-cache 4969 Pragma: no-cache 4970 Content-Type: application/yang.data+json 4972 { 4973 "example-events:events" : { 4974 "event" : [ 4975 { 4976 "name" : "interface-up", 4977 "description" : "Interface up notification count", 4978 "event-count" : 42 4979 }, 4980 { 4981 "name" : "interface-down", 4982 "description" : "Interface down notification count", 4983 "event-count" : 4 4984 } 4985 ] 4986 } 4987 } 4989 Example 2: content=config 4991 To retrieve only the configuration child resources, the "content" 4992 parameter is set to "config" or omitted since this is the default 4993 value. Note that the "ETag" and "Last-Modified" headers are only 4994 returned if the content parameter value is "config". 4996 GET /restconf/data/example-events:events?content=config 4997 HTTP/1.1 4998 Host: example.com 4999 Accept: application/yang.data+json 5001 The server might respond: 5003 HTTP/1.1 200 OK 5004 Date: Mon, 23 Apr 2012 17:11:30 GMT 5005 Server: example-server 5006 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5007 ETag: eeeada438af 5008 Cache-Control: no-cache 5009 Pragma: no-cache 5010 Content-Type: application/yang.data+json 5012 { 5013 "example-events:events" : { 5014 "event" : [ 5015 { 5016 "name" : "interface-up", 5017 "description" : "Interface up notification count" 5018 }, 5019 { 5020 "name" : "interface-down", 5021 "description" : "Interface down notification count" 5022 } 5023 ] 5024 } 5025 } 5027 Example 3: content=nonconfig 5029 To retrieve only the non-configuration child resources, the "content" 5030 parameter is set to "nonconfig". Note that configuration ancestors 5031 (if any) and list key leafs (if any) are also returned. The client 5032 might send: 5034 GET /restconf/data/example-events:events?content=nonconfig 5035 HTTP/1.1 5036 Host: example.com 5037 Accept: application/yang.data+json 5039 The server might respond: 5041 HTTP/1.1 200 OK 5042 Date: Mon, 23 Apr 2012 17:11:30 GMT 5043 Server: example-server 5044 Cache-Control: no-cache 5045 Pragma: no-cache 5046 Content-Type: application/yang.data+json 5048 { 5049 "example-events:events" : { 5050 "event" : [ 5051 { 5052 "name" : "interface-up", 5053 "event-count" : 42 5054 }, 5055 { 5056 "name" : "interface-down", 5057 "event-count" : 4 5058 } 5059 ] 5060 } 5061 } 5063 D.3.2. "depth" Parameter 5065 The "depth" parameter is used to limit the number of levels of child 5066 resources that are returned by the server for a GET method request. 5068 The depth parameter starts counting levels at the level of the target 5069 resource that is specified, so that a depth level of "1" includes 5070 just the target resource level itself. A depth level of "2" includes 5071 the target resource level and its child nodes. 5073 This example shows how different values of the "depth" parameter 5074 would affect the reply content for retrieval of the top-level 5075 "jukebox" data resource. 5077 Example 1: depth=unbounded 5079 To retrieve all the child resources, the "depth" parameter is not 5080 present or set to the default value "unbounded". Note that some 5081 strings are wrapped for display purposes only. 5083 GET /restconf/data/example-jukebox:jukebox?depth=unbounded 5084 HTTP/1.1 5085 Host: example.com 5086 Accept: application/yang.data+json 5088 The server might respond: 5090 HTTP/1.1 200 OK 5091 Date: Mon, 23 Apr 2012 17:11:30 GMT 5092 Server: example-server 5093 Cache-Control: no-cache 5094 Pragma: no-cache 5095 Content-Type: application/yang.data+json 5097 { 5098 "example-jukebox:jukebox" : { 5099 "library" : { 5100 "artist" : [ 5101 { 5102 "name" : "Foo Fighters", 5103 "album" : [ 5104 { 5105 "name" : "Wasting Light", 5106 "genre" : "example-jukebox:alternative", 5107 "year" : 2011, 5108 "song" : [ 5109 { 5110 "name" : "Wasting Light", 5111 "location" : 5112 "/media/foo/a7/wasting-light.mp3", 5113 "format" : "MP3", 5114 "length" " 286 5115 }, 5116 { 5117 "name" : "Rope", 5118 "location" : "/media/foo/a7/rope.mp3", 5119 "format" : "MP3", 5120 "length" " 259 5121 } 5122 ] 5123 } 5124 ] 5125 } 5126 ] 5127 }, 5128 "playlist" : [ 5129 { 5130 "name" : "Foo-One", 5131 "description" : "example playlist 1", 5132 "song" : [ 5133 { 5134 "index" : 1, 5135 "id" : "https://example.com/restconf/data/ 5136 example-jukebox:jukebox/library/artist= 5137 Foo%20Fighters/album=Wasting%20Light/ 5138 song=Rope" 5139 }, 5140 { 5141 "index" : 2, 5142 "id" : "https://example.com/restconf/data/ 5143 example-jukebox:jukebox/library/artist= 5144 Foo%20Fighters/album=Wasting%20Light/song= 5145 Bridge%20Burning" 5146 } 5147 ] 5148 } 5149 ], 5150 "player" : { 5151 "gap" : 0.5 5153 } 5154 } 5155 } 5157 Example 2: depth=1 5159 To determine if 1 or more resource instances exist for a given target 5160 resource, the value "1" is used. 5162 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 5163 Host: example.com 5164 Accept: application/yang.data+json 5166 The server might respond: 5168 HTTP/1.1 200 OK 5169 Date: Mon, 23 Apr 2012 17:11:30 GMT 5170 Server: example-server 5171 Cache-Control: no-cache 5172 Pragma: no-cache 5173 Content-Type: application/yang.data+json 5175 { 5176 "example-jukebox:jukebox" : {} 5177 } 5179 Example 3: depth=3 5181 To limit the depth level to the target resource plus 2 child resource 5182 layers the value "3" is used. 5184 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 5185 Host: example.com 5186 Accept: application/yang.data+json 5188 The server might respond: 5190 HTTP/1.1 200 OK 5191 Date: Mon, 23 Apr 2012 17:11:30 GMT 5192 Server: example-server 5193 Cache-Control: no-cache 5194 Pragma: no-cache 5195 Content-Type: application/yang.data+json 5197 { 5198 "example-jukebox:jukebox" : { 5199 "library" : { 5200 "artist" : {} 5202 }, 5203 "playlist" : [ 5204 { 5205 "name" : "Foo-One", 5206 "description" : "example playlist 1", 5207 "song" : {} 5208 } 5209 ], 5210 "player" : { 5211 "gap" : 0.5 5212 } 5213 } 5214 } 5216 D.3.3. "fields" Parameter 5218 In this example the client is retrieving the API resource, but 5219 retrieving only the "name" and "revision" nodes from each module, in 5220 JSON format: 5222 GET /restconf/data?fields=ietf-yang-library:modules/ 5223 module(name;revision) HTTP/1.1 5224 Host: example.com 5225 Accept: application/yang.data+json 5227 The server might respond as follows. 5229 HTTP/1.1 200 OK 5230 Date: Mon, 23 Apr 2012 17:01:00 GMT 5231 Server: example-server 5232 Content-Type: application/yang.data+json 5234 { 5235 "ietf-yang-library:modules": { 5236 "module": [ 5237 { 5238 "name" : "example-jukebox", 5239 "revision" : "2015-06-04" 5240 }, 5241 { 5242 "name" : "ietf-inet-types", 5243 "revision" : "2013-07-15" 5244 }, 5245 { 5246 "name" : "ietf-restconf-monitoring", 5247 "revision" : "2015-06-19" 5248 }, 5249 { 5250 "name" : "ietf-yang-library", 5251 "revision" : "2016-04-09" 5252 }, 5253 { 5254 "name" : "ietf-yang-types", 5255 "revision" : "2013-07-15" 5256 } 5258 ] 5259 } 5260 } 5262 D.3.4. "insert" Parameter 5264 In this example, a new first song entry in the "Foo-One" playlist is 5265 being created. 5267 Request from client: 5269 POST /restconf/data/example-jukebox:jukebox/ 5270 playlist=Foo-One?insert=first HTTP/1.1 5271 Host: example.com 5272 Content-Type: application/yang.data+json 5274 { 5275 "example-jukebox:song" : { 5276 "index" : 1, 5277 "id" : "/example-jukebox:jukebox/library/ 5278 artist=Foo%20Fighters/album=Wasting%20Light/song=Rope" 5279 } 5280 } 5282 Response from server: 5284 HTTP/1.1 201 Created 5285 Date: Mon, 23 Apr 2012 13:01:20 GMT 5286 Server: example-server 5287 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5288 Location: https://example.com/restconf/data/ 5289 example-jukebox:jukebox/playlist=Foo-One/song=1 5290 ETag: eeeada438af 5292 D.3.5. "point" Parameter 5294 In this example, the client is inserting a new "song" resource within 5295 an "album" resource after another song. The request URI is split for 5296 display purposes only. 5298 Request from client: 5300 POST /restconf/data/example-jukebox:jukebox/ 5301 library/artist=Foo%20Fighters/album=Wasting%20Light? 5302 insert=after&point=%2Fexample-jukebox%3Ajukebox%2F 5303 library%2Fartist%3DFoo%20Fighters%2Falbum%3D 5304 Wasting%20Light%2Fsong%3DBridge%20Burning HTTP/1.1 5305 Host: example.com 5306 Content-Type: application/yang.data+json 5308 { 5309 "example-jukebox:song" : { 5310 "name" : "Rope", 5311 "location" : "/media/foo/a7/rope.mp3", 5312 "format" : "MP3", 5313 "length" : 259 5314 } 5315 } 5317 Response from server: 5319 HTTP/1.1 204 No Content 5320 Date: Mon, 23 Apr 2012 13:01:20 GMT 5321 Server: example-server 5322 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5323 ETag: abcada438af 5325 D.3.6. "filter" Parameter 5327 The following URIs show some examples of notification filter 5328 specifications (lines wrapped for display purposes only): 5330 // filter = /event/event-class='fault' 5331 GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' 5333 // filter = /event/severity<=4 5334 GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 5336 // filter = /linkUp|/linkDown 5337 GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown 5339 // filter = /*/reporting-entity/card!='Ethernet0' 5340 GET /streams/NETCONF? 5341 filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' 5343 // filter = /*/email-addr[contains(.,'company.com')] 5344 GET /streams/critical-syslog? 5345 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 5347 // Note: the module name is used as prefix. 5348 // filter = (/example-mod:event1/name='joe' and 5349 // /example-mod:event1/status='online') 5350 GET /streams/NETCONF? 5351 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and 5352 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 5354 // To get notifications from just two modules (e.g., m1 + m2) 5355 // filter=(/m1:* or /m2:*) 5356 GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*) 5358 D.3.7. "start-time" Parameter 5360 // start-time = 2014-10-25T10:02:00Z 5361 GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z 5363 D.3.8. "stop-time" Parameter 5365 // stop-time = 2014-10-25T12:31:00Z 5366 GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z 5368 D.3.9. "with-defaults" Parameter 5370 The following YANG module is assumed for this example. 5372 module example-interface { 5373 prefix "exif"; 5374 namespace "urn:example.com:params:xml:ns:yang:example-interface"; 5376 container interfaces { 5377 list interface { 5378 key name; 5379 leaf name { type string; } 5380 leaf mtu { type uint32; } 5381 leaf status { 5382 config false; 5383 type enumeration { 5384 enum up; 5385 enum down; 5386 enum testing; 5387 } 5388 } 5389 } 5390 } 5391 } 5393 Assume the same data model as defined in Appendix A.1 of [RFC6243]. 5394 Assume the same data set as defined in Appendix A.2 of [RFC6243]. If 5395 the server defaults-uri basic-mode is "trim", the the following 5396 request for interface "eth1" might be as follows: 5398 Without query parameter: 5400 GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1 5401 Host: example.com 5402 Accept: application/yang.data+json 5404 The server might respond as follows. 5406 HTTP/1.1 200 OK 5407 Date: Mon, 23 Apr 2012 17:01:00 GMT 5408 Server: example-server 5409 Content-Type: application/yang.data+json 5411 { 5412 "example:interface": [ 5413 { 5414 "name" : "eth1", 5415 "status" : "up" 5416 } 5417 ] 5418 } 5420 Note that the "mtu" leaf is missing because it is set to the default 5421 "1500", and the server defaults handling basic-mode is "trim". 5423 With query parameter: 5425 GET /restconf/data/example:interfaces/interface=eth1 5426 ?with-defaults=report-all HTTP/1.1 5427 Host: example.com 5428 Accept: application/yang.data+json 5430 The server might respond as follows. 5432 HTTP/1.1 200 OK 5433 Date: Mon, 23 Apr 2012 17:01:00 GMT 5434 Server: example-server 5435 Content-Type: application/yang.data+json 5437 { 5438 "example:interface": [ 5439 { 5440 "name" : "eth1", 5441 "mtu" : 1500, 5442 "status" : "up" 5444 } 5445 ] 5446 } 5448 Note that the server returns the "mtu" leaf because the "report-all" 5449 mode was requested with the "with-defaults" query parameter. 5451 Authors' Addresses 5453 Andy Bierman 5454 YumaWorks 5456 Email: andy@yumaworks.com 5458 Martin Bjorklund 5459 Tail-f Systems 5461 Email: mbj@tail-f.com 5463 Kent Watsen 5464 Juniper Networks 5466 Email: kwatsen@juniper.net