idnits 2.17.1 draft-ietf-netconf-restconf-11.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 2387 has weird spacing: '... method entry...' == Line 3306 has weird spacing: '...ncoding strin...' == Line 3307 has weird spacing: '...ocation inet:...' == Line 4339 has weird spacing: '...ocation str...' == Line 4349 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 10, 2016) is 2938 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 12, 2016 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 April 10, 2016 10 RESTCONF Protocol 11 draft-ietf-netconf-restconf-11 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 12, 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 . . . . 27 85 3.6.2. Encoding Operation Resource Output Parameters . . . . 30 86 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 31 87 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 33 88 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 34 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 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 . . . . . . . . . . . . . . . . . . . . . 42 100 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 43 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 "insert" Query Parameter . . . . . . . . . . . . 46 106 4.8.5. The "point" Query Parameter . . . . . . . . . . . . . 47 107 4.8.6. The "filter" Query Parameter . . . . . . . . . . . . 47 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 . . . . . . . . . . 58 123 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 59 124 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 59 125 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 61 126 7.1. Error Response Message . . . . . . . . . . . . . . . . . 63 127 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 65 128 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 71 129 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 71 130 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 72 131 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 72 132 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 73 133 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 74 134 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 77 135 10.1. modules . . . . . . . . . . . . . . . . . . . . . . . . 77 136 10.1.1. modules/module . . . . . . . . . . . . . . . . . . . 78 138 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78 139 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 78 140 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 78 141 11.3. application/yang Media Sub Types . . . . . . . . . . . . 79 142 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 80 143 12. Security Considerations . . . . . . . . . . . . . . . . . . . 81 144 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 82 145 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 82 146 14.1. Normative References . . . . . . . . . . . . . . . . . . 82 147 14.2. Informative References . . . . . . . . . . . . . . . . . 85 148 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 85 149 A.1. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 85 150 A.2. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 86 151 A.3. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 88 152 A.4. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 88 153 A.5. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 89 154 A.6. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 89 155 A.7. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 89 156 A.8. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 90 157 A.9. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 91 158 A.10. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 91 159 A.11. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 92 160 A.12. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 93 161 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 93 162 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 93 163 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 94 164 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 99 165 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 99 166 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 99 167 D.1.2. Retrieve The Server Module Information . . . . . . . 100 168 D.1.3. Retrieve The Server Capability Information . . . . . 102 169 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 103 170 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 103 171 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 104 172 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 104 173 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 105 174 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 105 175 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 108 176 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 111 177 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 112 178 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 112 179 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 113 180 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 114 181 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 114 182 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 114 183 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 116 185 1. Introduction 187 There is a need for standard mechanisms to allow Web applications to 188 access the configuration data, state data, data-model specific 189 protocol operations, and event notifications within a networking 190 device, in a modular and extensible manner. 192 This document defines an HTTP [RFC7230] based protocol called 193 RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or 194 YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using datastores 195 defined in NETCONF [RFC6241]. 197 NETCONF defines configuration datastores and a set of Create, 198 Retrieve, Update, Delete (CRUD) operations that can be used to access 199 these datastores. The YANG language defines the syntax and semantics 200 of datastore content, state data, protocol operations, and event 201 notifications. 203 RESTCONF uses HTTP operations to provide CRUD operations on a 204 conceptual datastore containing YANG-defined data, which is 205 compatible with a server which implements NETCONF datastores. 207 If a RESTCONF server is co-located with a NETCONF server, then there 208 are protocol interactions to be considered, as described in 209 Section 1.4. The server MAY provide access to specific datastores 210 using operation resources, as described in Section 3.6. 212 Configuration data and state data are exposed as resources that can 213 be retrieved with the GET method. Resources representing 214 configuration data can be modified with the DELETE, PATCH, POST, and 215 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 216 or JSON [RFC7159]. 218 Data-model specific operations defined with the YANG "rpc" or 219 "action" statements can be invoked with the POST method. Data-model 220 specific event notifications defined with the YANG "notification" 221 statement can be accessed. 223 1.1. Terminology 225 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 226 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 227 "OPTIONAL" in this document are to be interpreted as described in BCP 228 14, [RFC2119]. 230 1.1.1. NETCONF 232 The following terms are defined in [RFC6241]: 234 o candidate configuration datastore 236 o client 238 o configuration data 240 o datastore 242 o configuration datastore 244 o protocol operation 246 o running configuration datastore 248 o server 250 o startup configuration datastore 252 o state data 254 o user 256 1.1.2. HTTP 258 The following terms are defined in [RFC3986]: 260 o fragment 262 o path 264 o query 266 The following terms are defined in [RFC7230]: 268 o header 270 o message-body 272 o request-line 274 o request URI 276 o status-line 278 The following terms are defined in [RFC7231]: 280 o method 281 o request 283 o resource 285 The following terms are defined in [RFC7232]: 287 o entity tag 289 1.1.3. YANG 291 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 293 o action 295 o container 297 o data node 299 o key leaf 301 o leaf 303 o leaf-list 305 o list 307 o non-presence container (or NP-container) 309 o ordered-by user 311 o presence container (or P-container) 313 o RPC operation 315 o top-level data node 317 1.1.4. Terms 319 The following terms are used within this document: 321 o API resource: a resource with the media type "application/ 322 yang.api+xml" or "application/yang.api+json". 324 o data resource: a resource with the media type "application/ 325 yang.data+xml" or "application/yang.data+json". Containers, 326 leafs, list entries, anydata and anyxml nodes can be data 327 resources. 329 o datastore resource: a resource with the media type "application/ 330 yang.datastore+xml" or "application/yang.datastore+json". 331 Represents a datastore. 333 o edit operation: a RESTCONF operation on a data resource using 334 either a POST, PUT, PATCH, or DELETE method. 336 o event stream resource: This resource represents an SSE (Server- 337 Sent Events) event stream. The content consists of text using the 338 media type "text/event-stream", as defined by the HTML5 339 [W3C.REC-html5-20141028] specification. Each event represents one 340 message generated by the server. It contains a 341 conceptual system or data-model specific event that is delivered 342 within an event notification stream. Also called a "stream 343 resource". 345 o media-type: HTTP uses Internet media types [RFC2046] in the 346 Content-Type and Accept header fields in order to provide open and 347 extensible data typing and type negotiation. 349 o operation: the conceptual RESTCONF operation for a message, 350 derived from the HTTP method, request URI, headers, and message- 351 body. 353 o operation resource: a resource with the media type "application/ 354 yang.operation+xml" or "application/yang.operation+json". 356 o patch: a generic PATCH request on the target datastore or data 357 resource. The media type of the message-body content will 358 identify the patch type in use. 360 o plain patch: a specific PATCH request type that can be used for 361 simple merge operations. 363 o query parameter: a parameter (and its value if any), encoded 364 within the query component of the request URI. 366 o RESTCONF capability: An optional RESTCONF protocol feature 367 supported by the server, which is identified by an IANA registered 368 NETCONF Capability URI, and advertised with an entry in the 369 "capability" leaf-list in Section 9.3. 371 o retrieval request: a request using the GET or HEAD methods. 373 o target resource: the resource that is associated with a particular 374 message, identified by the "path" component of the request URI. 376 o schema resource: a resource with the media type "application/ 377 yang". The YANG representation of the schema can be retrieved by 378 the client with the GET method. 380 o stream list: the set of data resource instances that describe the 381 event stream resources available from the server. This 382 information is defined in the "ietf-restconf-monitoring" module as 383 the "stream" list. It can be retrieved using the target resource 384 "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/ 385 stream". The stream list contains information about each stream, 386 such as the URL to retrieve the event stream data. 388 1.1.5. URI Template 390 Throughout this document, the URI template [RFC6570] syntax 391 "{+restconf}" is used to refer to the RESTCONF API entry point 392 outside of an example. See Section 3.1 for details. 394 For simplicity, all of the examples in this document assume "/ 395 restconf" as the discovered RESTCONF API root path. 397 1.1.6. Tree Diagrams 399 A simplified graphical representation of the data model is used in 400 this document. The meaning of the symbols in these diagrams is as 401 follows: 403 o Brackets "[" and "]" enclose list keys. 405 o Abbreviations before data node names: "rw" means configuration 406 data (read-write) and "ro" state data (read-only). 408 o Symbols after data node names: "?" means an optional node, "!" 409 means a presence container, and "*" denotes a list and leaf-list. 411 o Parentheses enclose choice and case nodes, and case nodes are also 412 marked with a colon (":"). 414 o Ellipsis ("...") stands for contents of subtrees that are not 415 shown. 417 1.2. Subset of NETCONF Functionality 419 RESTCONF does not need to mirror the full functionality of the 420 NETCONF protocol, but it does need to be compatible with NETCONF. 421 RESTCONF achieves this by implementing a subset of the interaction 422 capabilities provided by the NETCONF protocol, for instance, by 423 eliminating datastores and explicit locking. 425 RESTCONF uses HTTP methods to implement the equivalent of NETCONF 426 operations, enabling basic CRUD operations on a hierarchy of 427 conceptual resources. 429 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 430 resources represented by YANG data models. These basic edit 431 operations allow the running configuration to be altered in an all- 432 or-none fashion. 434 RESTCONF is not intended to replace NETCONF, but rather provide an 435 additional interface that follows Representational State Transfer 436 (REST) principles [rest-dissertation], and is compatible with a 437 resource-oriented device abstraction. 439 The following figure shows the system components if a RESTCONF server 440 is co-located with a NETCONF server: 442 +-----------+ +-----------------+ 443 | Web app | <-------> | | 444 +-----------+ HTTP | network device | 445 | | 446 +-----------+ | +-----------+ | 447 | NMS app | <-------> | | datastore | | 448 +-----------+ NETCONF | +-----------+ | 449 +-----------------+ 451 The following figure shows the system components if a RESTCONF server 452 is implemented in a device that does not have a NETCONF server: 454 +-----------+ +-----------------+ 455 | Web app | <-------> | | 456 +-----------+ HTTP | network device | 457 | | 458 +-----------------+ 460 1.3. Data Model Driven API 462 RESTCONF combines the simplicity of the HTTP protocol with the 463 predictability and automation potential of a schema-driven API. 464 Using YANG, a client can predict all management resources, much like 465 using URI Templates [RFC6570], but in a more holistic manner. This 466 strategy obviates the need for responses provided by the server to 467 contain Hypermedia as the Engine of Application State (HATEOAS) 468 links, originally described in Roy Fielding's doctoral dissertation 469 [rest-dissertation]. 471 RESTCONF provides the YANG module capability information supported by 472 the server, in case the client wants to use it. The URIs for custom 473 protocol operations and datastore content are predictable, based on 474 the YANG module definitions. 476 The RESTCONF protocol operates on a conceptual datastore defined with 477 the YANG data modeling language. The server lists each YANG module 478 it supports using the "ietf-yang-library" YANG module, defined in 479 [I-D.ietf-netconf-yang-library]. The server MUST implement the 480 "ietf-yang-library" module, which MUST identify all the YANG modules 481 used by the server. 483 The conceptual datastore contents, data-model-specific operations and 484 event notifications are identified by this set of YANG modules. 486 The classification of data as configuration or non-configuration is 487 derived from the YANG "config" statement. Data ordering behavior is 488 derived from the YANG "ordered-by" statement. 490 The RESTCONF datastore editing model is simple and direct, similar to 491 the behavior of the :writable-running capability in NETCONF. Each 492 RESTCONF edit of a datastore resource is activated upon successful 493 completion of the transaction. 495 1.4. Coexistence with NETCONF 497 RESTCONF can be implemented on a device that supports NETCONF. 499 If the device supports :writable-running, all edits to configuration 500 nodes in {+restconf}/data are performed in the running configuration 501 datastore. The URI template "{+restconf}" is defined in 502 Section 1.1.5. 504 Otherwise, if the device supports :candidate, all edits to 505 configuration nodes in {+restconf}/data are performed in the 506 candidate configuration datastore. The candidate MUST be 507 automatically committed to running immediately after each successful 508 edit. Any edits from other sources that are in the candidate 509 datastore will also be committed. If a confirmed-commit procedure is 510 in progress, then this commit will act as the confirming commit. If 511 the server is expecting a "persist-id" parameter to complete the 512 confirmed commit procedure then the RESTCONF edit operation MUST fail 513 with a "409 Conflict" status-line. 515 If the device supports :startup, the device MUST automatically update 516 the non-volatile "startup datastore", after the running datastore has 517 been updated as a consequence of a RESTCONF edit operation. 519 If a datastore that would be modified by a RESTCONF operation has an 520 active lock, the RESTCONF edit operation MUST fail with a "409 521 Conflict" status-line. 523 1.5. RESTCONF Extensibility 525 There are two extensibility mechanisms built into RESTCONF: 527 o protocol version 529 o optional capabilities 531 This document defines version 1 of the RESTCONF protocol. If a 532 future version of this protocol is defined, then that document will 533 specify how the new version of RESTCONF is identified. It is 534 expected that a different entry point {+restconf2} would be defined. 535 The server will advertise all protocol versions that it supports in 536 its host-meta data. 538 In this example, the server supports both RESTCONF version 1 and a 539 fictitious version 2. 541 Request 542 ------- 543 GET /.well-known/host-meta HTTP/1.1 544 Host: example.com 545 Accept: application/xrd+xml 547 Response 548 -------- 549 HTTP/1.1 200 OK 550 Content-Type: application/xrd+xml 551 Content-Length: nnn 553 554 555 556 558 RESTCONF also supports a server-defined list of optional 559 capabilities, which are listed by a server using the 560 "ietf-restconf-monitoring" module defined in Section 9.3. For 561 example, this document defines several query parameters in 562 Section 4.8. Each optional parameter has a corresponding capability 563 URI defined in Section 9.1.1 that is advertised by the server if 564 supported. 566 The "capabilities" list can identify any sort of server extension. 567 Typically this extension mechanism is used to identify optional query 568 parameters but it is not limited to that purpose. For example, the 569 "defaults" URI defined in Section 9.1.2 specifies a mandatory URI 570 identifying server defaults handling behavior. 572 A new sub-resource type could be identified with a capability if it 573 is optional to implement. Mandatory protocol features and new 574 resource types require a new revision of the RESTCONF protocol. 576 2. Transport Protocol Requirements 578 2.1. Integrity and Confidentiality 580 HTTP [RFC7230] is an application layer protocol that may be layered 581 on any reliable transport-layer protocol. RESTCONF is defined on top 582 of HTTP, but due to the sensitive nature of the information conveyed, 583 RESTCONF requires that the transport-layer protocol provides both 584 data integrity and confidentiality. A RESTCONF server MUST support 585 the TLS protocol [RFC5246]. The RESTCONF protocol MUST NOT be used 586 over HTTP without using the TLS protocol. 588 HTTP/1.1 pipelining MUST be supported by the server. Responses MUST 589 be sent in the same order that requests are received. No other 590 versions of HTTP are supported for use with RESTCONF. 592 2.2. HTTPS with X.509v3 Certificates 594 Given the nearly ubiquitous support for HTTP over TLS [RFC7230], 595 RESTCONF implementations MUST support the "https" URI scheme, which 596 has the IANA assigned default port 443. 598 RESTCONF servers MUST present an X.509v3 based certificate when 599 establishing a TLS connection with a RESTCONF client. The use the 600 X.509v3 based certificates is consistent with NETCONF over TLS 601 [RFC7589]. 603 2.3. Certificate Validation 605 The RESTCONF client MUST either use X.509 certificate path validation 606 [RFC5280] to verify the integrity of the RESTCONF server's TLS 607 certificate, or match the presented X.509 certificate with locally 608 configured certificate fingerprints. 610 The presented X.509 certificate MUST also be considered valid if it 611 matches a locally configured certificate fingerprint. If X.509 612 certificate path validation fails and the presented X.509 certificate 613 does not match a locally configured certificate fingerprint, the 614 connection MUST be terminated as defined in [RFC5246]. 616 2.4. Authenticated Server Identity 618 The RESTCONF client MUST check the identity of the server according 619 to Section 6 of [RFC6125], including processing the outcome as 620 described in Section 6.6 of [RFC6125]. 622 2.5. Authenticated Client Identity 624 The RESTCONF server MUST authenticate client access to any protected 625 resource. If the RESTCONF client is not authorized to access a 626 resource, the server MUST send an HTTP response with "401 627 Unauthorized" status-line, as defined in Section 3.1 of [RFC7235]. 629 To authenticate a client, a RESTCONF server MUST use TLS based client 630 certificates (Section 7.4.6 of [RFC5246]), or MUST use any HTTP 631 authentication scheme defined in the HTTP Authentication Scheme 632 Registry (Section 5.1 in [RFC7235]). A server MAY also support the 633 combination of both client certificates and an HTTP client 634 authentication scheme, with the determination of how to process this 635 combination left as an implementation decision. 637 The RESTCONF client identity derived from the authentication 638 mechanism used is hereafter known as the "RESTCONF username" and 639 subject to the NETCONF Access Control Module (NACM) [RFC6536]. When 640 a client certificate is presented, the RESTCONF username MUST be 641 derived using the algorithm defined in Section 7 of [RFC7589]. For 642 all other cases, when HTTP authentication is used, the RESTCONF 643 username MUST be provided by the HTTP authentication scheme used. 645 3. Resources 647 The RESTCONF protocol operates on a hierarchy of resources, starting 648 with the top-level API resource itself (Section 3.1). Each resource 649 represents a manageable component within the device. 651 A resource can be considered a collection of data and the set of 652 allowed methods on that data. It can contain nested child resources. 653 The child resource types and methods allowed on them are data-model 654 specific. 656 A resource has a media type identifier, represented by the 657 "Content-Type" header in the HTTP response message. A resource can 658 contain zero or more nested resources. A resource can be created and 659 deleted independently of its parent resource, as long as the parent 660 resource exists. 662 All RESTCONF resource types are defined in this document except 663 specific datastore contents, protocol operations, and event 664 notifications. The syntax and semantics for these resource types are 665 defined in YANG modules. 667 The RESTCONF resources are accessed via a set of URIs defined in this 668 document. The set of YANG modules supported by the server will 669 determine the data model specific operations, top-level data nodes, 670 and event notification messages supported by the server. 672 The RESTCONF protocol does not include a data resource discovery 673 mechanism. Instead, the definitions within the YANG modules 674 advertised by the server are used to construct a predictable 675 operation or data resource identifier. 677 3.1. Root Resource Discovery 679 In line with the best practices defined by [RFC7320], RESTCONF 680 enables deployments to specify where the RESTCONF API is located. 681 When first connecting to a RESTCONF server, a RESTCONF client MUST 682 determine the root of the RESTCONF API. There MUST be exactly one 683 "restconf" link relation returned by the device. 685 The client discovers this by getting the "/.well-known/host-meta" 686 resource ([RFC6415]) and using the element containing the 687 "restconf" attribute : 689 Example returning /restconf: 691 Request 692 ------- 693 GET /.well-known/host-meta HTTP/1.1 694 Host: example.com 695 Accept: application/xrd+xml 697 Response 698 -------- 699 HTTP/1.1 200 OK 700 Content-Type: application/xrd+xml 701 Content-Length: nnn 703 704 705 706 After discovering the RESTCONF API root, the client MUST prepend it 707 to any subsequent request to a RESTCONF resource. In this example, 708 the client would use the path "/restconf" as the RESTCONF entry 709 point. 711 Example returning /top/restconf: 713 Request 714 ------- 715 GET /.well-known/host-meta HTTP/1.1 716 Host: example.com 717 Accept: application/xrd+xml 719 Response 720 -------- 721 HTTP/1.1 200 OK 722 Content-Type: application/xrd+xml 723 Content-Length: nnn 725 726 727 729 In this example, the client would use the path "/top/restconf" as the 730 RESTCONF entry point. 732 The client can now determine the operation resources supported by the 733 the server. In this example a custom "play" operation is supported: 735 Request 736 ------- 737 GET /top/restconf/operations HTTP/1.1 738 Host: example.com 739 Accept: application/yang.api+json 741 Response 742 -------- 743 HTTP/1.1 200 OK 744 Date: Mon, 23 Apr 2012 17:01:00 GMT 745 Server: example-server 746 Cache-Control: no-cache 747 Pragma: no-cache 748 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 749 Content-Type: application/yang.api+json 751 { "operations" : { "example-jukebox:play" : {} } } 753 If the XRD contains more than one link relation, then only the 754 relation named "restconf" is relevant to this specification. 756 3.2. RESTCONF Media Types 758 The RESTCONF protocol defines a set of application specific media 759 types to identify each of the available resource types. The 760 following resource types are defined in RESTCONF: 762 +-----------+---------------------------------+ 763 | Resource | Media Type | 764 +-----------+---------------------------------+ 765 | API | application/yang.api+xml | 766 | | application/yang.api+json | 767 | Datastore | application/yang.datastore+xml | 768 | | application/yang.datastore+json | 769 | Data | application/yang.data+xml | 770 | | application/yang.data+json | 771 | [none] | application/yang.errors+xml | 772 | | application/yang.errors+json | 773 | Operation | application/yang.operation+xml | 774 | | application/yang.operation+json | 775 | Schema | application/yang | 776 +-----------+---------------------------------+ 778 RESTCONF Media Types 780 3.3. API Resource 782 The API resource contains the entry points for the RESTCONF datastore 783 and operation resources. It is the top-level resource located at 784 {+restconf} and has the media type "application/yang.api+xml" or 785 "application/yang.api+json". 787 YANG Tree Diagram for an API Resource: 789 +--rw restconf 790 +--rw data 791 +--rw operations 792 +--ro yang-library-version 794 The "application/yang.api" restconf-media-type extension in the 795 "ietf-restconf" module defined in Section 8 is used to specify the 796 structure and syntax of the conceptual child resources within the API 797 resource. 799 The API resource can be retrieved with the GET method. 801 This resource has the following child resources: 803 +----------------------+--------------------------------+ 804 | Child Resource | Description | 805 +----------------------+--------------------------------+ 806 | data | Contains all data resources | 807 | operations | Data-model specific operations | 808 | yang-library-version | ietf-yang-library module date | 809 +----------------------+--------------------------------+ 811 RESTCONF API Resource 813 3.3.1. {+restconf}/data 815 This mandatory resource represents the combined configuration and 816 state data resources that can be accessed by a client. It cannot be 817 created or deleted by the client. The datastore resource type is 818 defined in Section 3.4. 820 Example: 822 This example request by the client would retrieve only the non- 823 configuration data nodes that exist within the "library" resource, 824 using the "content" query parameter (see Section 4.8.1). 826 GET /restconf/data/example-jukebox:jukebox/library 827 ?content=nonconfig HTTP/1.1 828 Host: example.com 829 Accept: application/yang.data+xml 831 The server might respond: 833 HTTP/1.1 200 OK 834 Date: Mon, 23 Apr 2012 17:01:30 GMT 835 Server: example-server 836 Cache-Control: no-cache 837 Pragma: no-cache 838 Content-Type: application/yang.data+xml 840 841 42 842 59 843 374 844 846 3.3.2. {+restconf}/operations 847 This optional resource is a container that provides access to the 848 data-model specific protocol operations supported by the server. The 849 server MAY omit this resource if no data-model specific operations 850 are advertised. 852 Any data-model specific protocol operations defined in the YANG 853 modules advertised by the server MUST be available as child nodes of 854 this resource. 856 Operation resources are defined in Section 3.6. 858 3.3.3. {+restconf}/yang-library-version 860 This mandatory leaf identifies the revision date of the 861 "ietf-yang-library" YANG module that is implemented by this server. 863 Example: 865 GET /restconf/yang-library-version HTTP/1.1 866 Host: example.com 867 Accept: application/yang.data+xml 869 The server might respond (response wrapped for display purposes): 871 HTTP/1.1 200 OK 872 Date: Mon, 23 Apr 2012 17:01:30 GMT 873 Server: example-server 874 Cache-Control: no-cache 875 Pragma: no-cache 876 Content-Type: application/yang.data+xml 878 880 2016-04-09 881 883 3.4. Datastore Resource 885 The "{+restconf}/data" subtree represents the datastore resource 886 type, which is a collection of configuration data and state data 887 nodes. 889 This resource type is an abstraction of the system's underlying 890 datastore implementation. It is used to simplify resource editing 891 for the client. The RESTCONF datastore resource is a conceptual 892 collection of all configuration and state data that is present on the 893 device. 895 Configuration edit transaction management and configuration 896 persistence are handled by the server and not controlled by the 897 client. A datastore resource can be written directly with the POST 898 and PATCH methods. Each RESTCONF edit of a datastore resource is 899 saved to non-volatile storage by the server, if the server supports 900 non-volatile storage of configuration data. 902 3.4.1. Edit Collision Detection 904 Two "edit collision detection" mechanisms are provided in RESTCONF, 905 for datastore and data resources. 907 3.4.1.1. Timestamp 909 The last change time is maintained and the "Last-Modified" 910 ([RFC7232], Section 2.2) header is returned in the response for a 911 retrieval request. The "If-Unmodified-Since" header can be used in 912 edit operation requests to cause the server to reject the request if 913 the resource has been modified since the specified timestamp. 915 The server MUST maintain a last-modified timestamp for the top-level 916 {+restconf}/data resource. This timestamp is only affected by 917 configuration data resources, and MUST NOT be updated for changes to 918 non-configuration data. 920 3.4.1.2. Entity tag 922 A unique opaque string is maintained and the "ETag" ([RFC7232], 923 Section 2.3) header is returned in the response for a retrieval 924 request. The "If-Match" header can be used in edit operation 925 requests to cause the server to reject the request if the resource 926 entity tag does not match the specified value. 928 The server MUST maintain an entity tag for the top-level {+restconf}/ 929 data resource. This entity tag is only affected by configuration 930 data resources, and MUST NOT be updated for changes to non- 931 configuration data. 933 3.4.1.3. Update Procedure 935 Changes to configuration data resources affect the timestamp and 936 entity tag to that resource, any ancestor data resources, and the 937 datastore resource. 939 For example, an edit to disable an interface might be done by setting 940 the leaf "/interfaces/interface/enabled" to "false". The "enabled" 941 data node and its ancestors (one "interface" list instance, and the 942 "interfaces" container) are considered to be changed. The datastore 943 is considered to be changed when any top-level configuration data 944 node is changed (e.g., "interfaces"). 946 3.5. Data Resource 948 A data resource represents a YANG data node that is a descendant node 949 of a datastore resource. Each YANG-defined data node can be uniquely 950 targeted by the request-line of an HTTP operation. Containers, 951 leafs, leaf-list entries, list entries, anydata and anyxml nodes are 952 data resources. 954 The representation maintained for each data resource is the YANG 955 defined subtree for that node. HTTP operations on a data resource 956 affect both the targeted data node and all its descendants, if any. 958 For configuration data resources, the server SHOULD maintain a last- 959 modified timestamp for the resource, and return the "Last-Modified" 960 header when it is retrieved with the GET or HEAD methods. 962 The "Last-Modified" header information can be used by a RESTCONF 963 client in subsequent requests, within the "If-Modified-Since" and 964 "If-Unmodified-Since" headers. 966 If maintained, the resource timestamp MUST be set to the current time 967 whenever the resource or any configuration resource within the 968 resource is altered. If not maintained, then the resource timestamp 969 for the datastore MUST be used instead. 971 This timestamp is only affected by configuration data resources, and 972 MUST NOT be updated for changes to non-configuration data. 974 For configuration data resources, the server SHOULD maintain a 975 resource entity tag for the resource, and return the "ETag" header 976 when it is retrieved as the target resource with the GET or HEAD 977 methods. If maintained, the resource entity tag MUST be updated 978 whenever the resource or any configuration resource within the 979 resource is altered. If not maintained, then the resource entity tag 980 for the datastore MUST be used instead. 982 The "ETag" header information can be used by a RESTCONF client in 983 subsequent requests, within the "If-Match" and "If-None-Match" 984 headers. 986 This entity tag is only affected by configuration data resources, and 987 MUST NOT be updated for changes to non-configuration data. 989 A data resource can be retrieved with the GET method. Data resources 990 are accessed via the "{+restconf}/data" entry point. This sub-tree 991 is used to retrieve and edit data resources. 993 A configuration data resource can be altered by the client with some 994 or all of the edit operations, depending on the target resource and 995 the specific operation. Refer to Section 4 for more details on edit 996 operations. 998 The resource definition version for a data resource is identified by 999 the revision date of the YANG module containing the YANG definition 1000 for the data resource. 1002 3.5.1. Encoding Data Resource Identifiers in the Request URI 1004 In YANG, data nodes are named with an absolute XPath expression, 1005 defined in [XPath], starting from the document root to the target 1006 resource. In RESTCONF, URL encoded path expressions are used 1007 instead. 1009 A predictable location for a data resource is important, since 1010 applications will code to the YANG data model module, which uses 1011 static naming and defines an absolute path location for all data 1012 nodes. 1014 A RESTCONF data resource identifier is not an XPath expression. It 1015 is encoded from left to right, starting with the top-level data node, 1016 according to the "api-path" rule in Section 3.5.1.1. The node name 1017 of each ancestor of the target resource node is encoded in order, 1018 ending with the node name for the target resource. If a node in the 1019 path is defined in another module than its parent node, then module 1020 name followed by a colon character (":") is prepended to the node 1021 name in the resource identifier. See Section 3.5.1.1 for details. 1023 If a data node in the path expression is a YANG leaf-list node, then 1024 the leaf-list value MUST be encoded according to the following rules: 1026 o The instance-identifier for the leaf-list MUST be encoded using 1027 one path segment [RFC3986]. 1029 o The path segment is constructed by having the leaf-list name, 1030 followed by an "=" character, followed by the leaf-list value. 1031 (e.g., /restconf/data/top-leaflist=fred). 1033 If a data node in the path expression is a YANG list node, then the 1034 key values for the list (if any) MUST be encoded according to the 1035 following rules: 1037 o The key leaf values for a data resource representing a YANG list 1038 MUST be encoded using one path segment [RFC3986]. 1040 o If there is only one key leaf value, the path segment is 1041 constructed by having the list name, followed by an "=" character, 1042 followed by the single key leaf value. 1044 o If there are multiple key leaf values, the path segment is 1045 constructed by having the list name, followed by the value of each 1046 leaf identified in the "key" statement, encoded in the order 1047 specified in the YANG "key" statement. Each key leaf value except 1048 the last one is followed by a comma character. 1050 o The key value is specified as a string, using the canonical 1051 representation for the YANG data type. Any reserved characters 1052 MUST be percent-encoded, according to [RFC3986], section 2.1. 1054 o All the components in the "key" statement MUST be encoded. 1055 Partial instance identifiers are not supported. 1057 o Since missing key values are not allowed, two consecutive commas 1058 are interpreted as a zero-length string. (example: 1059 list=foo,,baz). 1061 o The "list-instance" ABNF rule defined in Section 3.5.1.1 1062 represents the syntax of a list instance identifier. 1064 o Resource URI values returned in Location headers for data 1065 resources MUST identify the module name, even if there are no 1066 conflicting local names when the resource is created. This 1067 ensures the correct resource will be identified even if the server 1068 loads a new module that the old client does not know about. 1070 Examples: 1072 container top { 1073 list list1 { 1074 key "key1 key2 key3"; 1075 ... 1076 list list2 { 1077 key "key4 key5"; 1078 ... 1079 leaf X { type string; } 1080 } 1081 } 1082 leaf-list Y { 1083 type uint32; 1084 } 1085 } 1087 For the above YANG definition, a target resource URI for leaf "X" 1088 would be encoded as follows (line wrapped for display purposes only): 1090 /restconf/data/example-top:top/list1=key1,key2,key3/ 1091 list2=key4,key5/X 1093 For the above YANG definition, a target resource URI for leaf-list 1094 "Y" would be encoded as follows: 1096 /restconf/data/example-top:top/Y=instance-value 1098 The following example shows how reserved characters are percent- 1099 encoded within a key value. The value of "key1" contains a comma, 1100 single-quote, double-quote, colon, double-quote, space, and forward 1101 slash. (,'":" /). Note that double-quote is not a reserved 1102 characters and does not need to be percent-encoded. The value of 1103 "key2" is the empty string, and the value of "key3" is the string 1104 "foo". 1106 Example URL: 1108 /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo 1110 3.5.1.1. ABNF For Data Resource Identifiers 1112 The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to 1113 construct RESTCONF path identifiers: 1115 api-path = "/" | 1116 ("/" api-identifier 1117 0*("/" (api-identifier | list-instance ))) 1119 api-identifier = [module-name ":"] identifier ;; note 1 1120 module-name = identifier 1122 list-instance = api-identifier "=" key-value ["," key-value]* 1124 key-value = string ;; note 1 1126 string = 1128 ;; An identifier MUST NOT start with 1129 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 1130 identifier = (ALPHA / "_") 1131 *(ALPHA / DIGIT / "_" / "-" / ".") 1133 Note 1: The syntax for "api-identifier" and "key-value" MUST conform 1134 to the JSON identifier encoding rules in Section 4 of 1135 [I-D.ietf-netmod-yang-json]. 1137 3.5.2. Defaults Handling 1139 RESTCONF requires that a server report its default handling mode (see 1140 Section 9.1.2 for details). If the optional "with-defaults" query 1141 parameter is supported by the server, a client may use it to control 1142 retrieval of default values (see Section 4.8.9 for details). 1144 If a leaf or leaf-list is missing from the configuration and there is 1145 a YANG-defined default for that data resource, then the server MUST 1146 use the YANG-defined default as the configured value. 1148 If the target of a GET method is a data node that represents a leaf 1149 that has a default value, and the leaf has not been configured yet, 1150 the server MUST return the default value that is in use by the 1151 server. 1153 If the target of a GET method is a data node that represents a 1154 container or list that has any child resources with default values, 1155 for the child resources that have not been given value yet, the 1156 server MAY return the default values that are in use by the server, 1157 in accordance with its reported default handing mode and query 1158 parameters passed by the client. 1160 3.6. Operation Resource 1162 An operation resource represents a protocol operation defined with 1163 the YANG "rpc" statement or a data-model specific action defined with 1164 a YANG "action" statement. It is invoked using a POST method on the 1165 operation resource. 1167 An RPC operation is invoked as: 1169 POST {+restconf}/operations/ 1171 The field identifies the module name and rpc identifier 1172 string for the desired operation. 1174 For example, if "module-A" defined a "reset" rpc operation, then 1175 invoking the operation from "module-A" would be requested as follows: 1177 POST /restconf/operations/module-A:reset HTTP/1.1 1178 Server example.com 1180 An action is invoked as: 1182 POST {+restconf}/data// 1184 where contains the path to the data node 1185 where the action is defined, and is the name of the action. 1187 For example, if "module-A" defined a "reset-all" action in the 1188 container "interfaces", then invoking this action would be requested 1189 as follows: 1191 POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 1192 Server example.com 1194 If the "rpc" or "action" statement has an "input" section, then a 1195 message-body MAY be sent by the client in the request, otherwise the 1196 request message MUST NOT include a message-body. If the "input" 1197 objcet tree contains mandatory parameters, then a message-body MUST 1198 be sent by the client. A mandatory parameter is a leaf or choice 1199 with a "mandatory" statement set to "true", or a list or leaf-list 1200 than have a "min-elements" statement value greater than zero. 1202 If the operation is invoked without errors, and if the "rpc" or 1203 "action" statement has an "output" section, then a message-body MAY 1204 be sent by the server in the response, otherwise the response message 1205 MUST NOT include a message-body in the response message, and MUST 1206 send a "204 No Content" status-line instead. 1208 If the operation input is not valid, or the operation is invoked but 1209 errors occur, then a message-body MUST be sent by the server, 1210 containing an "errors" resource, as defined in Section 3.9. A 1211 detailed example of an operation resource error response can be found 1212 in Section 3.6.3. 1214 All operation resources representing RPC operations supported by the 1215 server MUST be identified in the {+restconf}/operations subtree 1216 defined in Section 3.3.2. Operation resources representing YANG 1217 actions are not identified in this subtree since they are invoked 1218 using a URI within the {+restconf}/data subtree. 1220 3.6.1. Encoding Operation Resource Input Parameters 1222 If the "rpc" or "action" statement has an "input" section, then the 1223 "input" node is provided in the message-body, corresponding to the 1224 YANG data definition statements within the "input" section. 1226 Examples: 1228 The following YANG module is used for the RPC operation examples in 1229 this section. 1231 module example-ops { 1232 namespace "https://example.com/ns/example-ops"; 1233 prefix "ops"; 1234 revision "2016-03-10"; 1236 rpc reboot { 1237 input { 1238 leaf delay { 1239 units seconds; 1240 type uint32; 1241 default 0; 1242 } 1243 leaf message { type string; } 1244 leaf language { type string; } 1245 } 1246 } 1248 rpc get-reboot-info { 1249 output { 1250 leaf reboot-time { 1251 units seconds; 1252 type uint32; 1253 } 1254 leaf message { type string; } 1255 leaf language { type string; } 1256 } 1257 } 1258 } 1260 The following YANG module is used for the YANG action examples in 1261 this section. 1263 module example-actions { 1264 yang-version 1.1; 1265 namespace "https://example.com/ns/example-actions"; 1266 prefix "act"; 1267 import ietf-yang-types { prefix yang; } 1268 revision "2016-03-10"; 1270 container interfaces { 1271 list interface { 1272 key name; 1273 leaf name { type string; } 1275 action reset { 1276 input { 1277 leaf delay { 1278 units seconds; 1279 type uint32; 1280 default 0; 1281 } 1282 } 1283 } 1285 action get-last-reset-time { 1286 output { 1287 leaf last-reset { 1288 type yang:date-and-time; 1289 mandatory true; 1290 } 1291 } 1292 } 1293 } 1294 } 1296 } 1298 RPC Input Example: 1300 The client might send the following POST request message to invoke 1301 the "reboot" RPC operation: 1303 POST /restconf/operations/example-ops:reboot HTTP/1.1 1304 Host: example.com 1305 Content-Type: application/yang.operation+xml 1307 1308 600 1309 Going down for system maintenance 1310 en-US 1311 1313 The server might respond: 1315 HTTP/1.1 204 No Content 1316 Date: Mon, 25 Apr 2012 11:01:00 GMT 1317 Server: example-server 1319 The same example request message is shown here using JSON encoding: 1321 POST /restconf/operations/example-ops:reboot HTTP/1.1 1322 Host: example.com 1323 Content-Type: application/yang.operation+json 1325 { 1326 "example-ops:input" : { 1327 "delay" : 600, 1328 "message" : "Going down for system maintenance", 1329 "language" : "en-US" 1330 } 1331 } 1333 Action Input Example: 1335 The client might send the following POST request message to invoke 1336 the "reset" action (text wrap for display purposes): 1338 POST /restconf/data/example-actions:interfaces/interface=eth0 1339 /reset HTTP/1.1 1340 Host: example.com 1341 Content-Type: application/yang.operation+xml 1343 1344 600 1345 1347 The server might respond: 1349 HTTP/1.1 204 No Content 1350 Date: Mon, 25 Apr 2012 11:01:00 GMT 1351 Server: example-server 1353 The same example request message is shown here using JSON encoding 1354 (text wrap for display purposes): 1356 POST /restconf/data/example-actions:interfaces/interface=eth0 1357 /reset HTTP/1.1 1359 Host: example.com 1360 Content-Type: application/yang.operation+json 1362 { "example-actions:input" : { 1363 "delay" : 600 1364 } 1365 } 1367 3.6.2. Encoding Operation Resource Output Parameters 1369 If the "rpc" or "action" statement has an "output" section, then the 1370 "output" node is provided in the message-body, corresponding to the 1371 YANG data definition statements within the "output" section. 1373 The request URI is not returned in the response. This URI might have 1374 context information required to associate the output to the specific 1375 "rpc" or "action" statement used in the request. 1377 Examples: 1379 RPC Output Example: 1381 The "example-ops" YANG module defined in Section 3.6.1 is used for 1382 this example. 1384 The client might send the following POST request message to invoke 1385 the "get-reboot-info" operation: 1387 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 1388 Host: example.com 1389 Accept: application/yang.operation+json 1391 The server might respond: 1393 HTTP/1.1 200 OK 1394 Date: Mon, 25 Apr 2012 11:10:30 GMT 1395 Server: example-server 1396 Content-Type: application/yang.operation+json 1398 { 1399 "example-ops:output" : { 1400 "reboot-time" : 30, 1401 "message" : "Going down for system maintenance", 1402 "language" : "en-US" 1403 } 1404 } 1406 The same response is shown here using XML encoding: 1408 HTTP/1.1 200 OK 1409 Date: Mon, 25 Apr 2012 11:10:30 GMT 1410 Server: example-server 1411 Content-Type: application/yang.operation+xml 1413 1414 30 1415 Going down for system maintenance 1416 en-US 1417 1419 Action Output Example: 1421 The "example-actions" YANG module defined in Section 3.6.1 is used 1422 for this example. 1424 The client might send the following POST request message to invoke 1425 the "get-last-reset-time" action: 1427 POST /restconf/data/example-actions:interfaces/interface=eth0 1428 /get-last-reset-time HTTP/1.1 1429 Host: example.com 1430 Accept: application/yang.operation+json 1432 The server might respond: 1434 HTTP/1.1 200 OK 1435 Date: Mon, 25 Apr 2012 11:10:30 GMT 1436 Server: example-server 1437 Content-Type: application/yang.operation+json 1439 { 1440 "example-actions:output" : { 1441 "last-reset" : "2015-10-10T02:14:11Z" 1442 } 1443 } 1445 3.6.3. Encoding Operation Resource Errors 1447 If any errors occur while attempting to invoke the operation or 1448 action, then an "errors" media type is returned with the appropriate 1449 error status. 1451 Using the "reboot" operation from the example in Section 3.6.1, the 1452 client might send the following POST request message: 1454 POST /restconf/operations/example-ops:reboot HTTP/1.1 1455 Host: example.com 1456 Content-Type: application/yang.operation+xml 1458 1459 -33 1460 Going down for system maintenance 1461 en-US 1462 1464 The server might respond with an "invalid-value" error: 1466 HTTP/1.1 400 Bad Request 1467 Date: Mon, 25 Apr 2012 11:10:30 GMT 1468 Server: example-server 1469 Content-Type: application/yang.errors+xml 1471 1472 1473 protocol 1474 invalid-value 1475 1476 /ops:input/ops:delay 1477 1478 Invalid input parameter 1479 1480 1482 The same response is shown here in JSON encoding: 1484 HTTP/1.1 400 Bad Request 1485 Date: Mon, 25 Apr 2012 11:10:30 GMT 1486 Server: example-server 1487 Content-Type: application/yang.errors+json 1489 { "ietf-restconf:errors" : { 1490 "error" : [ 1491 { 1492 "error-type" : "protocol", 1493 "error-tag" : "invalid-value", 1494 "error-path" : "/example-ops:input/delay", 1495 "error-message" : "Invalid input parameter", 1496 } 1497 ] 1498 } 1499 } 1501 3.7. Schema Resource 1503 The server can optionally support retrieval of the YANG modules it 1504 supports. If retrieval is supported, then the "schema" leaf MUST be 1505 present in the associated "module" list entry, defined in 1506 [I-D.ietf-netconf-yang-library]. 1508 To retrieve a YANG module, a client first needs to get the URL for 1509 retrieving the schema, which is stored in the "schema" leaf. Note 1510 that there is no required structure for this URL. The URL value 1511 shown below is just an example. 1513 The client might send the following GET request message: 1515 GET /restconf/data/ietf-yang-library:modules/module= 1516 example-jukebox,2015-04-04/schema HTTP/1.1 1517 Host: example.com 1518 Accept: application/yang.data+json 1520 The server might respond: 1522 HTTP/1.1 200 OK 1523 Date: Thu, 11 Feb 2016 11:10:30 GMT 1524 Server: example-server 1525 Content-Type: application/yang.data+json 1527 { 1528 "ietf-yang-library:schema": 1529 "https://example.com/mymodules/example-jukebox/2015-04-04" 1530 } 1532 Next the client needs to retrieve the actual YANG schema. 1534 The client might send the following GET request message: 1536 GET https://example.com/mymodules/example-jukebox/2015-04-04 1537 HTTP/1.1 1538 Host: example.com 1539 Accept: application/yang 1541 The server might respond: 1543 HTTP/1.1 200 OK 1544 Date: Thu, 11 Feb 2016 11:10:31 GMT 1545 Server: example-server 1546 Content-Type: application/yang 1548 module example-jukebox { 1549 // contents of YANG module deleted for this example... 1551 } 1553 3.8. Event Stream Resource 1555 An "event stream" resource represents a source for system generated 1556 event notifications. Each stream is created and modified by the 1557 server only. A client can retrieve a stream resource or initiate a 1558 long-poll server sent event stream, using the procedure specified in 1559 Section 6.3. 1561 A notification stream functions according to the NETCONF 1562 Notifications specification [RFC5277]. The available streams can be 1563 retrieved from the stream list, which specifies the syntax and 1564 semantics of a stream resource. 1566 3.9. Errors Media Type 1568 An "errors" media type is a collection of error information that is 1569 sent as the message-body in a server response message, if an error 1570 occurs while processing a request message. It is not considered a 1571 resource type because no instances can be retrieved with a GET 1572 request. 1574 The "ietf-restconf" YANG module contains the "application/ 1575 yang.errors" restconf-media-type extension which specifies the syntax 1576 and semantics of an "errors" media type. RESTCONF error handling 1577 behavior is defined in Section 7. 1579 4. Operations 1581 The RESTCONF protocol uses HTTP methods to identify the CRUD 1582 operation requested for a particular resource. 1584 The following table shows how the RESTCONF operations relate to 1585 NETCONF protocol operations: 1587 +----------+--------------------------------------------+ 1588 | RESTCONF | NETCONF | 1589 +----------+--------------------------------------------+ 1590 | OPTIONS | none | 1591 | HEAD | none | 1592 | GET | , | 1593 | POST | (operation="create") | 1594 | POST | invoke any operation | 1595 | PUT | (operation="create/replace") | 1596 | PATCH | (operation="merge") | 1597 | DELETE | (operation="delete") | 1598 +----------+--------------------------------------------+ 1600 CRUD Methods in RESTCONF 1602 The NETCONF "remove" operation attribute is not supported by the HTTP 1603 DELETE method. The resource must exist or the DELETE method will 1604 fail. The PATCH method is equivalent to a "merge" operation when 1605 using a plain patch (see Section 4.6.1); other media-types may 1606 provide more granular control. 1608 Access control mechanisms MUST be used to limit what operations can 1609 be used. In particular, RESTCONF is compatible with the NETCONF 1610 Access Control Model (NACM) [RFC6536], as there is a specific mapping 1611 between RESTCONF and NETCONF operations, defined in Section 4. The 1612 resource path needs to be converted internally by the server to the 1613 corresponding YANG instance-identifier. Using this information, the 1614 server can apply the NACM access control rules to RESTCONF messages. 1616 The server MUST NOT allow any operation to any resources that the 1617 client is not authorized to access. 1619 Operations are applied to a single data resource instance at once. 1620 The server MUST NOT allow any operation to be applied to multiple 1621 instances of a YANG list or leaf-list. 1623 Implementation of all methods (except PATCH) are defined in 1624 [RFC7231]. This section defines the RESTCONF protocol usage for each 1625 HTTP method. 1627 4.1. OPTIONS 1629 The OPTIONS method is sent by the client to discover which methods 1630 are supported by the server for a specific resource (e.g., GET, POST, 1631 DELETE, etc.). The server MUST implement this method. 1633 If the PATCH method is supported, then the "Accept-Patch" header MUST 1634 be supported and returned in the response to the OPTIONS request, as 1635 defined in [RFC5789]. 1637 4.2. HEAD 1639 The HEAD method is sent by the client to retrieve just the headers 1640 that would be returned for the comparable GET method, without the 1641 response message-body. It is supported for all resource types, 1642 except operation resources. 1644 The request MUST contain a request URI that contains at least the 1645 entry point. The same query parameters supported by the GET method 1646 are supported by the HEAD method. 1648 The access control behavior is enforced as if the method was GET 1649 instead of HEAD. The server MUST respond the same as if the method 1650 was GET instead of HEAD, except that no response message-body is 1651 included. 1653 4.3. GET 1655 The GET method is sent by the client to retrieve data and meta-data 1656 for a resource. It is supported for all resource types, except 1657 operation resources. The request MUST contain a request URI that 1658 contains at least the entry point. 1660 The server MUST NOT return any data resources for which the user does 1661 not have read privileges. If the user is not authorized to read the 1662 target resource, an error response containing a "401 Unauthorized" 1663 status-line SHOULD be returned. A server MAY return a "404 Not 1664 Found" status-line, as described in section 6.5.3 in [RFC7231]. 1666 If the user is authorized to read some but not all of the target 1667 resource, the unauthorized content is omitted from the response 1668 message-body, and the authorized content is returned to the client. 1670 If any content is returned to the client, then the server MUST send a 1671 valid response message-body. More than one element MUST NOT be 1672 returned for XML encoding. 1674 If a retrieval request for a data resource representing a YANG leaf- 1675 list or list object identifies more than one instance, and XML 1676 encoding is used in the response, then an error response containing a 1677 "400 Bad Request" status-line MUST be returned by the server. 1679 If the target resource of a retrieval request is for an operation 1680 resource then a "405 Method Not Allowed" status-line MUST be returned 1681 by the server. 1683 Note that the way that access control is applied to data resources is 1684 completely incompatible with HTTP caching. The Last-Modified and 1685 ETag headers maintained for a data resource are not affected by 1686 changes to the access control rules for that data resource. It is 1687 possible for the representation of a data resource that is visible to 1688 a particular client to be changed without detection via the Last- 1689 Modified or ETag values. 1691 Example: 1693 The client might request the response headers for an XML 1694 representation of the a specific "album" resource: 1696 GET /restconf/data/example-jukebox:jukebox/ 1697 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1698 Host: example.com 1699 Accept: application/yang.data+xml 1701 The server might respond: 1703 HTTP/1.1 200 OK 1704 Date: Mon, 23 Apr 2012 17:02:40 GMT 1705 Server: example-server 1706 Content-Type: application/yang.data+xml 1707 Cache-Control: no-cache 1708 Pragma: no-cache 1709 ETag: a74eefc993a2b 1710 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1712 1714 Wasting Light 1715 jbox:alternative 1716 2011 1717 1719 4.4. POST 1721 The POST method is sent by the client to create a data resource or 1722 invoke an operation resource. The server uses the target resource 1723 media type to determine how to process the request. 1725 +-----------+------------------------------------------------+ 1726 | Type | Description | 1727 +-----------+------------------------------------------------+ 1728 | Datastore | Create a top-level configuration data resource | 1729 | Data | Create a configuration data child resource | 1730 | Operation | Invoke a protocol operation | 1731 +-----------+------------------------------------------------+ 1733 Resource Types that Support POST 1735 4.4.1. Create Resource Mode 1737 If the target resource type is a datastore or data resource, then the 1738 POST is treated as a request to create a top-level resource or child 1739 resource, respectively. The message-body is expected to contain the 1740 content of a child resource to create within the parent (target 1741 resource). The message-body MUST NOT contain more than one instance 1742 of the expected data resource. The data-model for the child tree is 1743 the subtree as defined by YANG for the child resource. 1745 The "insert" and "point" query parameters MUST be supported by the 1746 POST method for datastore and data resources. These parameters are 1747 only allowed if the list or leaf-list is ordered-by user. 1749 If the POST method succeeds, a "201 Created" status-line is returned 1750 and there is no response message-body. A "Location" header 1751 identifying the child resource that was created MUST be present in 1752 the response in this case. 1754 If the data resource already exists, then the POST request MUST fail 1755 and a "409 Conflict" status-line MUST be returned. 1757 If the user is not authorized to create the target resource, an error 1758 response containing a "403 Forbidden" status-line SHOULD be returned. 1759 A server MAY return a "404 Not Found" status-line, as described in 1760 section 6.5.3 in [RFC7231]. All other error responses are handled 1761 according to the procedures defined in Section 7. 1763 Example: 1765 To create a new "jukebox" resource, the client might send: 1767 POST /restconf/data HTTP/1.1 1768 Host: example.com 1769 Content-Type: application/yang.data+json 1771 { "example-jukebox:jukebox" : {} } 1773 If the resource is created, the server might respond as follows. 1774 Note that the "Location" header line is wrapped for display purposes 1775 only: 1777 HTTP/1.1 201 Created 1778 Date: Mon, 23 Apr 2012 17:01:00 GMT 1779 Server: example-server 1780 Location: https://example.com/restconf/data/ 1781 example-jukebox:jukebox 1782 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 1783 ETag: b3a3e673be2 1785 Refer to Appendix D.2.1 for more resource creation examples. 1787 4.4.2. Invoke Operation Mode 1788 If the target resource type is an operation resource, then the POST 1789 method is treated as a request to invoke that operation. The 1790 message-body (if any) is processed as the operation input parameters. 1791 Refer to Section 3.6 for details on operation resources. 1793 If the POST request succeeds, a "200 OK" status-line is returned if 1794 there is a response message-body, and a "204 No Content" status-line 1795 is returned if there is no response message-body. 1797 If the user is not authorized to invoke the target operation, an 1798 error response containing a "403 Forbidden" status-line is returned 1799 to the client. All other error responses are handled according to 1800 the procedures defined in Section 7. 1802 Example: 1804 In this example, the client is invoking the "play" operation defined 1805 in the "example-jukebox" YANG module. 1807 A client might send a "play" request as follows: 1809 POST /restconf/operations/example-jukebox:play HTTP/1.1 1810 Host: example.com 1811 Content-Type: application/yang.operation+json 1813 { 1814 "example-jukebox:input" : { 1815 "playlist" : "Foo-One", 1816 "song-number" : 2 1817 } 1818 } 1820 The server might respond: 1822 HTTP/1.1 204 No Content 1823 Date: Mon, 23 Apr 2012 17:50:00 GMT 1824 Server: example-server 1826 4.5. PUT 1828 The PUT method is sent by the client to create or replace the target 1829 data resource. A request message-body MUST be present, representing 1830 the new data resource, or the server MUST return "400 Bad Request" 1831 status-line. 1833 The only target resource media type that supports PUT is the data 1834 resource. The message-body is expected to contain the content used 1835 to create or replace the target resource. 1837 The "insert" (Section 4.8.4) and "point" (Section 4.8.5) query 1838 parameters MUST be supported by the PUT method for data resources. 1839 These parameters are only allowed if the list or leaf-list is 1840 ordered-by user. 1842 Consistent with [RFC7231], if the PUT request creates a new resource, 1843 a "201 Created" status-line is returned. If an existing resource is 1844 modified, a "204 No Content" status-line is returned. 1846 If the user is not authorized to create or replace the target 1847 resource an error response containing a "403 Forbidden" status-line 1848 SHOULD be returned. A server MAY return a "404 Not Found" status- 1849 line, as described in section 6.5.3 in [RFC7231]. All other error 1850 responses are handled according to the procedures defined in 1851 Section 7. 1853 If the target resource represents a YANG leaf-list, then the PUT 1854 method MUST NOT change the value of the leaf-list instance. 1856 If the target resource represents a YANG list instance, then the PUT 1857 method MUST NOT change any key leaf values in the message-body 1858 representation. 1860 Example: 1862 An "album" child resource defined in the "example-jukebox" YANG 1863 module is replaced or created if it does not already exist. 1865 To replace the "album" resource contents, the client might send as 1866 follows. Note that the request-line is wrapped for display purposes 1867 only: 1869 PUT /restconf/data/example-jukebox:jukebox/ 1870 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1871 Host: example.com 1872 Content-Type: application/yang.data+json 1874 { 1875 "example-jukebox:album" : { 1876 "name" : "Wasting Light", 1877 "genre" : "example-jukebox:alternative", 1878 "year" : 2011 1879 } 1880 } 1882 If the resource is updated, the server might respond: 1884 HTTP/1.1 204 No Content 1885 Date: Mon, 23 Apr 2012 17:04:00 GMT 1886 Server: example-server 1887 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 1888 ETag: b27480aeda4c 1890 The same request is shown here using XML encoding: 1892 PUT /restconf/data/example-jukebox:jukebox/ 1893 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1894 Host: example.com 1895 Content-Type: application/yang.data+xml 1897 1899 Wasting Light 1900 jbox:alternative 1901 2011 1902 1904 4.6. PATCH 1906 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 1907 an extensible framework for resource patching mechanisms. It is 1908 optional to implement by the server. Each patch mechanism needs a 1909 unique media type. Zero or more patch media types MAY be supported 1910 by the server. The media types supported by a server can be 1911 discovered by the client by sending an OPTIONS request (see 1912 Section 4.1). 1914 This document defines one patch mechanism (Section 4.6.1). The YANG 1915 PATCH mechanism is defined in [I-D.ietf-netconf-yang-patch]. Other 1916 patch mechanisms may be defined by future specifications. 1918 If the target resource instance does not exist, the server MUST NOT 1919 create it. 1921 If the PATCH request succeeds, a "200 OK" status-line is returned if 1922 there is a message-body, and "204 No Content" is returned if no 1923 response message-body is sent. 1925 If the user is not authorized to alter the target resource an error 1926 response containing a "403 Forbidden" status-line SHOULD be returned. 1927 A server MAY return a "404 Not Found" status-line, as described in 1928 section 6.5.3 in [RFC7231]. All other error responses are handled 1929 according to the procedures defined in Section 7. 1931 4.6.1. Plain Patch 1933 The plain patch mechanism merges the contents of the message body 1934 with the target resource. If the target resource is a datastore 1935 resource (see Section 3.4), the message body MUST be either 1936 application/yang.datastore+xml or application/yang.datastore+json. 1937 If then the target resource is a data resource (see Section 3.5), 1938 then the message body MUST be either application/yang.data+xml or 1939 application/yang.data+json. 1941 Plain patch can be used to create or update, but not delete, a child 1942 resource within the target resource. Please see 1943 [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting 1944 more granular control. The YANG Patch Media Type allows multiple 1945 sub-operations (e.g., merge, delete) within a single PATCH operation. 1947 If the target resource represents a YANG leaf-list, then the PATCH 1948 method MUST not change the value of the leaf-list instance. 1950 If the target resource represents a YANG list instance, then the 1951 PATCH method MUST NOT change any key leaf values in the message-body 1952 representation. 1954 Example: 1956 To replace just the "year" field in the "album" resource (instead of 1957 replacing the entire resource with the PUT method), the client might 1958 send a plain patch as follows. Note that the request-line is wrapped 1959 for display purposes only: 1961 PATCH /restconf/data/example-jukebox:jukebox/ 1962 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1963 Host: example.com 1964 If-Match: b8389233a4c 1965 Content-Type: application/yang.data+xml 1967 1968 2011 1969 1971 If the field is updated, the server might respond: 1973 HTTP/1.1 204 No Content 1974 Date: Mon, 23 Apr 2012 17:49:30 GMT 1975 Server: example-server 1976 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 1977 ETag: b2788923da4c 1979 4.7. DELETE 1981 The DELETE method is used to delete the target resource. If the 1982 DELETE request succeeds, a "204 No Content" status-line is returned, 1983 and there is no response message-body. 1985 If the user is not authorized to delete the target resource then an 1986 error response containing a "403 Forbidden" status-line SHOULD be 1987 returned. A server MAY return a "404 Not Found" status-line, as 1988 described in section 6.5.3 in [RFC7231]. All other error responses 1989 are handled according to the procedures defined in Section 7. 1991 If the target resource represents a YANG leaf-list or list, then the 1992 PATCH method SHOULD NOT delete more than one such instance. The 1993 server MAY delete more than one instance if a query parameter is used 1994 requesting this behavior. (Definition of this query parameter is 1995 outside the scope of this document.) 1997 Example: 1999 To delete a resource such as the "album" resource, the client might 2000 send: 2002 DELETE /restconf/data/example-jukebox:jukebox/ 2003 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2004 Host: example.com 2006 If the resource is deleted, the server might respond: 2008 HTTP/1.1 204 No Content 2009 Date: Mon, 23 Apr 2012 17:49:40 GMT 2010 Server: example-server 2012 4.8. Query Parameters 2014 Each RESTCONF operation allows zero or more query parameters to be 2015 present in the request URI. The specific parameters that are allowed 2016 depends on the resource type, and sometimes the specific target 2017 resource used, in the request. 2019 +-------------------+-------------+---------------------------------+ 2020 | Name | Methods | Description | 2021 +-------------------+-------------+---------------------------------+ 2022 | content | GET | Select config and/or non-config | 2023 | | | data resources | 2024 | depth | GET | Request limited sub-tree depth | 2025 | | | in the reply content | 2026 | fields | GET | Request a subset of the target | 2027 | | | resource contents | 2028 | filter | GET | Boolean notification filter for | 2029 | | | event stream resources | 2030 | insert | POST, PUT | Insertion mode for ordered-by | 2031 | | | user data resources | 2032 | point | POST, PUT | Insertion point for ordered-yb | 2033 | | | user data resources | 2034 | start-time | GET | Replay buffer start time for | 2035 | | | event stream resources | 2036 | stop-time | GET | Replay buffer stop time for | 2037 | | | event stream resources | 2038 | with-defaults | GET | Control retrieval of default | 2039 | | | values | 2040 +-------------------+-------------+---------------------------------+ 2042 RESTCONF Query Parameters 2044 Query parameters can be given in any order. Each parameter can 2045 appear at most once in a request URI. A default value may apply if 2046 the parameter is missing. 2048 Refer to Appendix D.3 for examples of query parameter usage. 2050 If vendors define additional query parameters, they SHOULD use a 2051 prefix (such as the enterprise or organization name) for query 2052 parameter names in order to avoid collisions with other parameters. 2054 4.8.1. The "content" Query Parameter 2056 The "content" parameter controls how descendant nodes of the 2057 requested data nodes will be processed in the reply. 2059 The allowed values are: 2061 +-----------+-----------------------------------------------------+ 2062 | Value | Description | 2063 +-----------+-----------------------------------------------------+ 2064 | config | Return only configuration descendant data nodes | 2065 | nonconfig | Return only non-configuration descendant data nodes | 2066 | all | Return all descendant data nodes | 2067 +-----------+-----------------------------------------------------+ 2069 This parameter is only allowed for GET methods on datastore and data 2070 resources. A "400 Bad Request" status-line is returned if used for 2071 other methods or resource types. 2073 If this query parameter is not present, the default value is "all". 2074 This query parameter MUST be supported by the server. 2076 4.8.2. The "depth" Query Parameter 2078 The "depth" parameter is used to specify the number of nest levels 2079 returned in a response for a GET method. The first nest-level 2080 consists of the requested data node itself. If the "fields" 2081 parameter (Section 4.8.3) is used to select descendant data nodes, 2082 these nodes all have a depth value of 1. This has the effect of 2083 including the nodes specified by the fields, even if the "depth" 2084 value is less than the actual depth level of the specified fields. 2085 Any child nodes which are contained within a parent node have a depth 2086 value that is 1 greater than its parent. 2088 The value of the "depth" parameter is either an integer between 1 and 2089 65535, or the string "unbounded". "unbounded" is the default. 2091 This parameter is only allowed for GET methods on API, datastore, and 2092 data resources. A "400 Bad Request" status-line is returned if it 2093 used for other methods or resource types. 2095 More than one "depth" query parameter MUST NOT appear in a request. 2096 If more than one instance is present, then a "400 Bad Request" 2097 status-line MUST be returned by the server. 2099 By default, the server will include all sub-resources within a 2100 retrieved resource, which have the same resource type as the 2101 requested resource. Only one level of sub-resources with a different 2102 media type than the target resource will be returned. 2104 If the "depth" query parameter URI is listed in the "capability" 2105 leaf-list in Section 9.3, then the server supports the "depth" query 2106 parameter. 2108 4.8.3. The "fields" Query Parameter 2110 The "fields" query parameter is used to optionally identify data 2111 nodes within the target resource to be retrieved in a GET method. 2112 The client can use this parameter to retrieve a subset of all nodes 2113 in a resource. 2115 A value of the "fields" query parameter matches the following rule: 2117 fields-expr = path '(' fields-expr ')' / 2118 path ';' fields-expr / 2119 path 2120 path = api-identifier [ '/' path ] 2122 "api-identifier" is defined in Section 3.5.1.1. 2124 ";" is used to select multiple nodes. For example, to retrieve only 2125 the "genre" and "year" of an album, use: "fields=genre;year". 2127 Parentheses are used to specify sub-selectors of a node. 2129 For example, assume the target resource is the "album" list. To 2130 retrieve only the "label" and "catalogue-number" of the "admin" 2131 container within an album, use: 2132 "fields=admin(label;catalogue-number)". 2134 "/" is used in a path to retrieve a child node of a node. For 2135 example, to retrieve only the "label" of an album, use: "fields=admin 2136 /label". 2138 This parameter is only allowed for GET methods on api, datastore, and 2139 data resources. A "400 Bad Request" status-line is returned if used 2140 for other methods or resource types. 2142 More than one "fields" query parameter MUST NOT appear in a request. 2143 If more than one instance is present, then a "400 Bad Request" 2144 status-line MUST be returned by the server. 2146 If the "fields" query parameter URI is listed in the "capability" 2147 leaf-list in Section 9.3, then the server supports the "fields" 2148 parameter. 2150 4.8.4. The "insert" Query Parameter 2152 The "insert" parameter is used to specify how a resource should be 2153 inserted within a ordered-by user list. 2155 The allowed values are: 2157 +-----------+-------------------------------------------------------+ 2158 | Value | Description | 2159 +-----------+-------------------------------------------------------+ 2160 | first | Insert the new data as the new first entry. | 2161 | last | Insert the new data as the new last entry. | 2162 | before | Insert the new data before the insertion point, as | 2163 | | specified by the value of the "point" parameter. | 2164 | after | Insert the new data after the insertion point, as | 2165 | | specified by the value of the "point" parameter. | 2166 +-----------+-------------------------------------------------------+ 2168 The default value is "last". 2170 This parameter is only supported for the POST and PUT methods. It is 2171 also only supported if the target resource is a data resource, and 2172 that data represents a YANG list or leaf-list that is ordered-by 2173 user. 2175 More than one "insert" query parameter MUST NOT appear in a request. 2176 If more than one instance is present, then a "400 Bad Request" 2177 status-line MUST be returned by the server. 2179 If the values "before" or "after" are used, then a "point" query 2180 parameter for the insertion parameter MUST also be present, or a "400 2181 Bad Request" status-line is returned. 2183 The "insert" query parameter MUST be supported by the server. 2185 4.8.5. The "point" Query Parameter 2187 The "point" parameter is used to specify the insertion point for a 2188 data resource that is being created or moved within an ordered-by 2189 user list or leaf-list. 2191 The value of the "point" parameter is a string that identifies the 2192 path to the insertion point object. The format is the same as a 2193 target resource URI string. 2195 This parameter is only supported for the POST and PUT methods. It is 2196 also only supported if the target resource is a data resource, and 2197 that data represents a YANG list or leaf-list that is ordered-by 2198 user. 2200 If the "insert" query parameter is not present, or has a value other 2201 than "before" or "after", then a "400 Bad Request" status-line is 2202 returned. 2204 More than one "point" query parameter MUST NOT appear in a request. 2205 If more than one instance is present, then a "400 Bad Request" 2206 status-line MUST be returned by the server. 2208 This parameter contains the instance identifier of the resource to be 2209 used as the insertion point for a POST or PUT method. 2211 The "point" query parameter MUST be supported by the server. 2213 4.8.6. The "filter" Query Parameter 2215 The "filter" parameter is used to indicate which subset of all 2216 possible events are of interest. If not present, all events not 2217 precluded by other parameters will be sent. 2219 This parameter is only allowed for GET methods on a text/event-stream 2220 data resource. A "400 Bad Request" status-line is returned if used 2221 for other methods or resource types. 2223 The format of this parameter is an XPath 1.0 expression, and is 2224 evaluated in the following context: 2226 o The set of namespace declarations is the set of prefix and 2227 namespace pairs for all supported YANG modules, where the prefix 2228 is the YANG module name, and the namespace is as defined by the 2229 "namespace" statement in the YANG module. 2231 o The function library is the core function library defined in XPath 2232 1.0. 2234 o The set of variable bindings is empty. 2236 o The context node is the root node. 2238 More than one "filter" query parameter MUST NOT appear in a request. 2239 If more than one instance is present, then a "400 Bad Request" 2240 status-line MUST be returned by the server. 2242 The filter is used as defined in [RFC5277], Section 3.6. If the 2243 boolean result of the expression is true when applied to the 2244 conceptual "notification" document root, then the event notification 2245 is delivered to the client. 2247 If the "filter" query parameter URI is listed in the "capability" 2248 leaf-list in Section 9.3, then the server supports the "filter" query 2249 parameter. 2251 4.8.7. The "start-time" Query Parameter 2253 The "start-time" parameter is used to trigger the notification replay 2254 feature and indicate that the replay should start at the time 2255 specified. If the stream does not support replay, per the 2256 "replay-support" attribute returned by stream list entry for the 2257 stream resource, then the server MUST return a "400 Bad Request" 2258 status-line. 2260 The value of the "start-time" parameter is of type "date-and-time", 2261 defined in the "ietf-yang" YANG module [RFC6991]. 2263 This parameter is only allowed for GET methods on a text/event-stream 2264 data resource. A "400 Bad Request" status-line is returned if used 2265 for other methods or resource types. 2267 More than one "start-time" query parameter MUST NOT appear in a 2268 request. If more than one instance is present, then a "400 Bad 2269 Request" status-line MUST be returned by the server. 2271 If this parameter is not present, then a replay subscription is not 2272 being requested. It is not valid to specify start times that are 2273 later than the current time. If the value specified is earlier than 2274 the log can support, the replay will begin with the earliest 2275 available notification. 2277 If this query parameter is supported by the server, then the "replay" 2278 query parameter URI MUST be listed in the "capability" leaf-list in 2279 Section 9.3. The "stop-time" query parameter MUST also be supported 2280 by the server. 2282 If the "replay-support" leaf is present in the "stream" entry 2283 (defined in Section 9.3) then the server MUST support the 2284 "start-time" and "stop-time" query parameters for that stream. 2286 4.8.8. The "stop-time" Query Parameter 2288 The "stop-time" parameter is used with the replay feature to indicate 2289 the newest notifications of interest. This parameter MUST be used 2290 with and have a value later than the "start-time" parameter. 2292 The value of the "stop-time" parameter is of type "date-and-time", 2293 defined in the "ietf-yang" YANG module [RFC6991]. 2295 This parameter is only allowed for GET methods on a text/event-stream 2296 data resource. A "400 Bad Request" status-line is returned if used 2297 for other methods or resource types. 2299 More than one "stop-time" query parameter MUST NOT appear in a 2300 request. If more than one instance is present, then a "400 Bad 2301 Request" status-line MUST be returned by the server. 2303 If this parameter is not present, the notifications will continue 2304 until the subscription is terminated. Values in the future are 2305 valid. 2307 If this query parameter is supported by the server, then the "replay" 2308 query parameter URI MUST be listed in the "capability" leaf-list in 2309 Section 9.3. The "start-time" query parameter MUST also be supported 2310 by the server. 2312 If the "replay-support" leaf is present in the "stream" entry 2313 (defined in Section 9.3) then the server MUST support the 2314 "start-time" and "stop-time" query parameters for that stream. 2316 4.8.9. The "with-defaults" Query Parameter 2318 The "with-defaults" parameter is used to specify how information 2319 about default data nodes should be returned in response to GET 2320 requests on data resources. 2322 If the server supports this capability, then it MUST implement the 2323 behavior in Section 4.5.1 of [RFC6243], except applied to the 2324 RESTCONF GET operation, instead of the NETCONF operations. 2326 +---------------------------+---------------------------------------+ 2327 | Value | Description | 2328 +---------------------------+---------------------------------------+ 2329 | report-all | All data nodes are reported | 2330 | trim | Data nodes set to the YANG default | 2331 | | are not reported | 2332 | explicit | Data nodes set to the YANG default by | 2333 | | the client are reported | 2334 | report-all-tagged | All data nodes are reported and | 2335 | | defaults are tagged | 2336 +---------------------------+---------------------------------------+ 2338 If the "with-defaults" parameter is set to "report-all" then the 2339 server MUST adhere to the defaults reporting behavior defined in 2340 Section 3.1 of [RFC6243]. 2342 If the "with-defaults" parameter is set to "trim" then the server 2343 MUST adhere to the defaults reporting behavior defined in Section 3.2 2344 of [RFC6243]. 2346 If the "with-defaults" parameter is set to "explicit" then the server 2347 MUST adhere to the defaults reporting behavior defined in Section 3.3 2348 of [RFC6243]. 2350 If the "with-defaults" parameter is set to "report-all-tagged" then 2351 the server MUST adhere to the defaults reporting behavior defined in 2352 Section 3.4 of [RFC6243]. 2354 More than one "with-defaults" query parameter MUST NOT appear in a 2355 request. If more than one instance is present, then a "400 Bad 2356 Request" status-line MUST be returned by the server. 2358 If the "with-defaults" parameter is not present then the server MUST 2359 adhere to the defaults reporting behavior defined in its "basic-mode" 2360 parameter for the "defaults" protocol capability URI, defined in 2361 Section 9.1.2. 2363 If the server includes the "with-defaults" query parameter URI in the 2364 "capability" leaf-list in Section 9.3, then the "with-defaults" query 2365 parameter MUST be supported. 2367 5. Messages 2369 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 2370 message corresponds to a single protocol method. Most messages can 2371 perform a single task on a single resource, such as retrieving a 2372 resource or editing a resource. The exception is the PATCH method, 2373 which allows multiple datastore edits within a single message. 2375 5.1. Request URI Structure 2377 Resources are represented with URIs following the structure for 2378 generic URIs in [RFC3986]. 2380 A RESTCONF operation is derived from the HTTP method and the request 2381 URI, using the following conceptual fields: 2383 //?# 2385 ^ ^ ^ ^ ^ 2386 | | | | | 2387 method entry resource query fragment 2389 M M O O I 2391 M=mandatory, O=optional, I=ignored 2393 where: 2395 is the HTTP method 2396 is the RESTCONF entry point 2397 is the Target Resource URI 2398 is the query parameter list 2399 is not used in RESTCONF 2401 o method: the HTTP method identifying the RESTCONF operation 2402 requested by the client, to act upon the target resource specified 2403 in the request URI. RESTCONF operation details are described in 2404 Section 4. 2406 o entry: the root of the RESTCONF API configured on this HTTP 2407 server, discovered by getting the "/.well-known/host-meta" 2408 resource, as described in Section 3.1. 2410 o resource: the path expression identifying the resource that is 2411 being accessed by the operation. If this field is not present, 2412 then the target resource is the API itself, represented by the 2413 media type "application/yang.api". 2415 o query: the set of parameters associated with the RESTCONF message. 2416 These have the familiar form of "name=value" pairs. Most query 2417 parameters are optional to implement by the server and optional to 2418 use by the client. Each optional query parameter is identified by 2419 a URI. The server MUST list the optional query parameter URIs it 2420 supports in the "capabilities" list defined in Section 9.3. 2422 There is a specific set of parameters defined, although the server 2423 MAY choose to support query parameters not defined in this document. 2424 The contents of the any query parameter value MUST be encoded 2425 according to [RFC3986], Section 3.4. Any reserved characters MUST be 2426 percent-encoded, according to [RFC3986], section 2.1. 2428 o fragment: This field is not used by the RESTCONF protocol. 2430 When new resources are created by the client, a "Location" header is 2431 returned, which identifies the path of the newly created resource. 2432 The client uses this exact path identifier to access the resource 2433 once it has been created. 2435 The "target" of an operation is a resource. The "path" field in the 2436 request URI represents the target resource for the operation. 2438 Refer to Appendix D for examples of RESTCONF Request URIs. 2440 5.2. Message Encoding 2442 RESTCONF messages are encoded in HTTP according to [RFC7230]. The 2443 "utf-8" character set is used for all messages. RESTCONF message 2444 content is sent in the HTTP message-body. 2446 Content is encoded in either JSON or XML format. A server MUST 2447 support XML or JSON encoding. XML encoding rules for data nodes are 2448 defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are 2449 used for all XML content. JSON encoding rules are defined in 2450 [I-D.ietf-netmod-yang-json]. JSON encoding of meta-data is defined 2451 in [I-D.ietf-netmod-yang-metadata]. This encoding is valid JSON, but 2452 also has special encoding rules to identify module namespaces and 2453 provide consistent type processing of YANG data. 2455 Request input content encoding format is identified with the Content- 2456 Type header. This field MUST be present if a message-body is sent by 2457 the client. 2459 The server MUST support the "Accept" header and "406 Not Acceptable" 2460 status-line, as defined in [RFC7231]. Response output content 2461 encoding format is identified with the Accept header in the request. 2462 If it is not specified, the request input encoding format SHOULD be 2463 used, or the server MAY choose any supported content encoding format. 2465 If there was no request input, then the default output encoding is 2466 XML or JSON, depending on server preference. File extensions encoded 2467 in the request are not used to identify format encoding. 2469 5.3. RESTCONF Meta-Data 2471 The RESTCONF protocol needs to retrieve the same meta-data that is 2472 used in the NETCONF protocol. Information about default leafs, last- 2473 modified timestamps, etc. are commonly used to annotate 2474 representations of the datastore contents. This meta-data is not 2475 defined in the YANG schema because it applies to the datastore, and 2476 is common across all data nodes. 2478 This information is encoded as attributes in XML. JSON encoding of 2479 meta-data is defined in [I-D.ietf-netmod-yang-metadata]. 2481 The following examples are based on the example in Appendix D.3.9. 2482 The "report-all-tagged" mode for the "with-defaults" query parameter 2483 requires that a "default" attribute be returned for default nodes. 2484 This example shows that attribute for the "mtu" leaf . 2486 5.3.1. XML MetaData Encoding Example 2488 GET /restconf/data/interfaces/interface=eth1 2489 ?with-defaults=report-all-tagged HTTP/1.1 2490 Host: example.com 2491 Accept: application/yang.data+xml 2493 The server might respond as follows. 2495 HTTP/1.1 200 OK 2496 Date: Mon, 23 Apr 2012 17:01:00 GMT 2497 Server: example-server 2498 Content-Type: application/yang.data+xml 2500 2502 eth1 2503 1500 2505 up 2506 2508 5.3.2. JSON MetaData Encoding Example 2510 Note that RFC 6243 defines the "default" attribute with XSD, not 2511 YANG, so the YANG module name has to be assigned manually. The value 2512 "ietf-netconf-with-defaults" is assigned for JSON meta-data encoding. 2514 GET /restconf/data/interfaces/interface=eth1 2515 ?with-defaults=report-all-tagged HTTP/1.1 2516 Host: example.com 2517 Accept: application/yang.data+json 2519 The server might respond as follows. 2521 HTTP/1.1 200 OK 2522 Date: Mon, 23 Apr 2012 17:01:00 GMT 2523 Server: example-server 2524 Content-Type: application/yang.data+json 2526 { 2527 "example:interface": [ 2528 { 2529 "name" : "eth1", 2530 "mtu" : 1500, 2531 "@mtu": { 2532 "ietf-netconf-with-defaults:default" : true 2533 }, 2534 "status" : "up" 2535 } 2536 ] 2537 } 2539 5.4. Return Status 2541 Each message represents some sort of resource access. An HTTP 2542 "status-line" header line is returned for each request. If a 4xx or 2543 5xx range status code is returned in the status-line, then the error 2544 information will be returned in the response, according to the format 2545 defined in Section 7.1. 2547 5.5. Message Caching 2549 Since the datastore contents change at unpredictable times, responses 2550 from a RESTCONF server generally SHOULD NOT be cached. 2552 The server SHOULD include a "Cache-Control" header in every response 2553 that specifies whether the response should be cached. A "Pragma" 2554 header specifying "no-cache" MAY also be sent in case the 2555 "Cache-Control" header is not supported. 2557 Instead of relying on HTTP caching, the client SHOULD track the 2558 "ETag" and/or "Last-Modified" headers returned by the server for the 2559 datastore resource (or data resource if the server supports it). A 2560 retrieval request for a resource can include the "If-None-Match" and/ 2561 or "If-Modified-Since" headers, which will cause the server to return 2562 a "304 Not Modified" status-line if the resource has not changed. 2563 The client MAY use the HEAD method to retrieve just the message 2564 headers, which SHOULD include the "ETag" and "Last-Modified" headers, 2565 if this meta-data is maintained for the target resource. 2567 6. Notifications 2569 The RESTCONF protocol supports YANG-defined event notifications. The 2570 solution preserves aspects of NETCONF Event Notifications [RFC5277] 2571 while utilizing the Server-Sent Events [W3C.CR-eventsource-20121211] 2572 transport strategy. 2574 6.1. Server Support 2576 A RESTCONF server MAY support RESTCONF notifications. Clients may 2577 determine if a server supports RESTCONF notifications by using the 2578 HTTP operation OPTIONS, HEAD, or GET on the stream list. The server 2579 does not support RESTCONF notifications if an HTTP error code is 2580 returned (e.g., "404 Not Found" status-line). 2582 6.2. Event Streams 2584 A RESTCONF server that supports notifications will populate a stream 2585 resource for each notification delivery service access point. A 2586 RESTCONF client can retrieve the list of supported event streams from 2587 a RESTCONF server using the GET operation on the stream list. 2589 The "restconf-state/streams" container definition in the 2590 "ietf-restconf-monitoring" module (defined in Section 9.3) is used to 2591 specify the structure and syntax of the conceptual child resources 2592 within the "streams" resource. 2594 For example: 2596 The client might send the following request: 2598 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2599 streams HTTP/1.1 2600 Host: example.com 2601 Accept: application/yang.data+xml 2603 The server might send the following response: 2605 HTTP/1.1 200 OK 2606 Content-Type: application/yang.api+xml 2607 2609 2610 NETCONF 2611 default NETCONF event stream 2612 2613 true 2614 2615 2007-07-08T00:00:00Z 2616 2617 2618 xml 2619 https://example.com/streams/NETCONF 2620 2621 2622 2623 json 2624 https://example.com/streams/NETCONF-JSON 2625 2626 2627 2628 2629 SNMP 2630 SNMP notifications 2631 false 2632 2633 xml 2634 https://example.com/streams/SNMP 2635 2636 2637 2638 syslog-critical 2639 Critical and higher severity 2640 2641 true 2642 2643 2007-07-01T00:00:00Z 2644 2645 2646 xml 2647 2648 https://example.com/streams/syslog-critical 2649 2650 2651 2652 2654 6.3. Subscribing to Receive Notifications 2656 RESTCONF clients can determine the URL for the subscription resource 2657 (to receive notifications) by sending an HTTP GET request for the 2658 "location" leaf with the stream list entry. The value returned by 2659 the server can be used for the actual notification subscription. 2661 The client will send an HTTP GET request for the URL returned by the 2662 server with the "Accept" type "text/event-stream". 2664 The server will treat the connection as an event stream, using the 2665 Server Sent Events [W3C.CR-eventsource-20121211] transport strategy. 2667 The server MAY support query parameters for a GET method on this 2668 resource. These parameters are specific to each notification stream. 2670 For example: 2672 The client might send the following request: 2674 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2675 streams/stream=NETCONF/access=xml/location HTTP/1.1 2676 Host: example.com 2677 Accept: application/yang.data+xml 2679 The server might send the following response: 2681 HTTP/1.1 200 OK 2682 Content-Type: application/yang.api+xml 2684 2686 https://example.com/streams/NETCONF 2687 2689 The RESTCONF client can then use this URL value to start monitoring 2690 the event stream: 2692 GET /streams/NETCONF HTTP/1.1 2693 Host: example.com 2694 Accept: text/event-stream 2695 Cache-Control: no-cache 2696 Connection: keep-alive 2698 A RESTCONF client MAY request the server compress the events using 2699 the HTTP header field "Accept-Encoding". For instance: 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 2706 Accept-Encoding: gzip, deflate 2708 6.3.1. NETCONF Event Stream 2710 The server SHOULD support the "NETCONF" notification stream defined 2711 in [RFC5277]. For this stream, RESTCONF notification subscription 2712 requests MAY specify parameters indicating the events it wishes to 2713 receive. These query parameters are optional to implement, and only 2714 available if the server supports them. 2716 +------------+---------+-------------------------+ 2717 | Name | Section | Description | 2718 +------------+---------+-------------------------+ 2719 | start-time | 4.8.7 | replay event start time | 2720 | stop-time | 4.8.8 | replay event stop time | 2721 | filter | 4.8.6 | boolean content filter | 2722 +------------+---------+-------------------------+ 2724 NETCONF Stream Query Parameters 2726 The semantics and syntax for these query parameters are defined in 2727 the sections listed above. The YANG encoding MUST be converted to 2728 URL-encoded string for use in the request URI. 2730 Refer to Appendix D.3.6 for filter parameter examples. 2732 6.4. Receiving Event Notifications 2734 RESTCONF notifications are encoded according to the definition of the 2735 event stream. The NETCONF stream defined in [RFC5277] is encoded in 2736 XML format. 2738 The structure of the event data is based on the "notification" 2739 element definition in Section 4 of [RFC5277]. It MUST conform to the 2740 schema for the "notification" element in Section 4 of [RFC5277], 2741 except the XML namespace for this element is defined as: 2743 urn:ietf:params:xml:ns:yang:ietf-restconf 2745 For JSON encoding purposes, the module name for the "notification" 2746 element is "ietf-restconf". 2748 Two child nodes within the "notification" container are expected, 2749 representing the event time and the event payload. The "event-time" 2750 node is defined within the "ietf-restconf" module namespace. The 2751 name and namespace of the payload element are determined by the YANG 2752 module containing the notification-stmt. 2754 In the following example, the YANG module "example-mod" is used: 2756 module example-mod { 2757 namespace "http://example.com/event/1.0"; 2758 prefix ex; 2760 notification event { 2761 leaf event-class { type string; } 2762 container reporting-entity { 2763 leaf card { type string; } 2764 } 2765 leaf severity { type string; } 2766 } 2767 } 2769 An example SSE event notification encoded using XML: 2771 data: 2773 data: 2013-12-21T00:01:00Z 2774 data: 2775 data: fault 2776 data: 2777 data: Ethernet0 2778 data: 2779 data: major 2780 data: 2781 data: 2783 An example SSE event notification encoded using JSON: 2785 data: { 2786 data: "ietf-restconf:notification": { 2787 data: "event-time": "2013-12-21T00:01:00Z", 2788 data: "example-mod:event": { 2789 data: "event-class": "fault", 2790 data: "reporting-entity": { "card": "Ethernet0" }, 2791 data: "severity": "major" 2792 data: } 2793 data: } 2794 data: } 2795 Alternatively, since neither XML nor JSON are whitespace sensitive, 2796 the above messages can be encoded onto a single line. For example: 2798 For example: ('\' line wrapping added for formatting only) 2800 XML: 2802 data: 2013-12-21T00:01:00ZfaultEthernet0\ 2806 major 2808 JSON: 2810 data: {"ietf-restconf:notification":{"event-time":"2013-12-21\ 2811 T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ 2812 tingEntity":{"card":"Ethernet0"},"severity":"major"}}} 2814 The SSE specifications supports the following additional fields: 2815 event, id and retry. A RESTCONF server MAY send the "retry" field 2816 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 2817 SHOULD NOT send the "event" or "id" fields, as there are no 2818 meaningful values that could be used for them that would not be 2819 redundant to the contents of the notification itself. RESTCONF 2820 servers that do not send the "id" field also do not need to support 2821 the HTTP header "Last-Event-Id". RESTCONF servers that do send the 2822 "id" field MUST still support the "startTime" query parameter as the 2823 preferred means for a client to specify where to restart the event 2824 stream. 2826 7. Error Reporting 2828 HTTP status-lines are used to report success or failure for RESTCONF 2829 operations. The element returned in NETCONF error 2830 responses contains some useful information. This error information 2831 is adapted for use in RESTCONF, and error information is returned for 2832 "4xx" class of status codes. 2834 The following table summarizes the return status codes used 2835 specifically by RESTCONF operations: 2837 +----------------------------+--------------------------------------+ 2838 | Status-Line | Description | 2839 +----------------------------+--------------------------------------+ 2840 | 100 Continue | POST accepted, 201 should follow | 2841 | 200 OK | Success with response message-body | 2842 | 201 Created | POST to create a resource success | 2843 | 204 No Content | Success without response message- | 2844 | | body | 2845 | 304 Not Modified | Conditional operation not done | 2846 | 400 Bad Request | Invalid request message | 2847 | 401 Unauthorized | Client cannot be authenticated | 2848 | 403 Forbidden | Access to resource denied | 2849 | 404 Not Found | Resource target or resource node not | 2850 | | found | 2851 | 405 Method Not Allowed | Method not allowed for target | 2852 | | resource | 2853 | 409 Conflict | Resource or lock in use | 2854 | 412 Precondition Failed | Conditional method is false | 2855 | 413 Request Entity Too | too-big error | 2856 | Large | | 2857 | 414 Request-URI Too Large | too-big error | 2858 | 415 Unsupported Media Type | non RESTCONF media type | 2859 | 500 Internal Server Error | operation-failed | 2860 | 501 Not Implemented | unknown-operation | 2861 | 503 Service Unavailable | Recoverable server error | 2862 +----------------------------+--------------------------------------+ 2864 HTTP Status Codes used in RESTCONF 2866 Since an operation resource is defined with a YANG "rpc" statement, 2867 and an action is defined with a YANG "action" statement, a mapping 2868 between the NETCONF value and the HTTP status code is 2869 needed. The specific error condition and response code to use are 2870 data-model specific and might be contained in the YANG "description" 2871 statement for the "action" or "rpc" statement. 2873 +-------------------------+-------------+ 2874 | | status code | 2875 +-------------------------+-------------+ 2876 | in-use | 409 | 2877 | invalid-value | 400 | 2878 | too-big | 413 | 2879 | missing-attribute | 400 | 2880 | bad-attribute | 400 | 2881 | unknown-attribute | 400 | 2882 | bad-element | 400 | 2883 | unknown-element | 400 | 2884 | unknown-namespace | 400 | 2885 | access-denied | 403 | 2886 | lock-denied | 409 | 2887 | resource-denied | 409 | 2888 | rollback-failed | 500 | 2889 | data-exists | 409 | 2890 | data-missing | 409 | 2891 | operation-not-supported | 501 | 2892 | operation-failed | 500 | 2893 | partial-operation | 500 | 2894 | malformed-message | 400 | 2895 +-------------------------+-------------+ 2897 Mapping from error-tag to status code 2899 7.1. Error Response Message 2901 When an error occurs for a request message on a data resource or an 2902 operation resource, and a "4xx" class of status codes will be 2903 returned (except for status code "403 Forbidden"), then the server 2904 SHOULD send a response message-body containing the information 2905 described by the "errors" container definition within the YANG module 2906 Section 8. The Content-Type of this response message MUST be 2907 application/yang.errors (see example below). 2909 The client MAY specify the desired encoding for error messages by 2910 specifying the appropriate media-type in the Accept header. If no 2911 error media is specified, then the media type of the request message 2912 SHOULD be used, or the server MAY choose any supported message 2913 encoding format. If there is no request message the server MUST 2914 select "application/yang.errors+xml" or "application/ 2915 yang.errors+json", depending on server preference. All of the 2916 examples in this document, except for the one below, assume that XML 2917 encoding will be returned if there is an error. 2919 YANG Tree Diagram for data: 2921 +--ro errors 2922 +--ro error* 2923 +--ro error-type enumeration 2924 +--ro error-tag string 2925 +--ro error-app-tag? string 2926 +--ro error-path? instance-identifier 2927 +--ro error-message? string 2928 +--ro error-info 2930 The semantics and syntax for RESTCONF error messages are defined in 2931 the "application/yang.errors" restconf-media-type extension in 2932 Section 8. 2934 Examples: 2936 The following example shows an error returned for an "lock-denied" 2937 error that can occur if a NETCONF client has locked a datastore. The 2938 RESTCONF client is attempting to delete a data resource. Note that 2939 an Accept header is used to specify the desired encoding for the 2940 error message. This example's use of the Accept header is especially 2941 notable since the DELETE method typically doesn't return a message- 2942 body and hence Accept headers are typically not passed. 2944 DELETE /restconf/data/example-jukebox:jukebox/ 2945 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2946 Host: example.com 2947 Accept: application/yang.errors+json 2949 The server might respond: 2951 HTTP/1.1 409 Conflict 2952 Date: Mon, 23 Apr 2012 17:11:00 GMT 2953 Server: example-server 2954 Content-Type: application/yang.errors+json 2956 { 2957 "ietf-restconf:errors": { 2958 "error": [ 2959 { 2960 "error-type": "protocol", 2961 "error-tag": "lock-denied", 2962 "error-message": "Lock failed, lock already held" 2963 } 2964 ] 2965 } 2966 } 2968 The following example shows an error returned for a "data-exists" 2969 error on a data resource. The "jukebox" resource already exists so 2970 it cannot be created. 2972 The client might send: 2974 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 2975 Host: example.com 2977 The server might respond (some lines wrapped for display purposes): 2979 HTTP/1.1 409 Conflict 2980 Date: Mon, 23 Apr 2012 17:11:00 GMT 2981 Server: example-server 2982 Content-Type: application/yang.errors+xml 2984 2985 2986 protocol 2987 data-exists 2988 2991 /rc:restconf/rc:data/jbox:jukebox 2992 2993 2994 Data already exists, cannot create new resource 2995 2996 2997 2999 8. RESTCONF module 3001 The "ietf-restconf" module defines conceptual definitions within an 3002 extension and two groupings, which are not meant to be implemented as 3003 datastore contents by a server. E.g., the "restconf" container is 3004 not intended to be implemented as a top-level data node (under the "/ 3005 restconf/data" entry point). 3007 RFC Ed.: update the date below with the date of RFC publication and 3008 remove this note. 3010 file "ietf-restconf@2016-03-16.yang" 3012 module ietf-restconf { 3013 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 3014 prefix "rc"; 3016 organization 3017 "IETF NETCONF (Network Configuration) Working Group"; 3019 contact 3020 "WG Web: 3021 WG List: 3023 WG Chair: Mehmet Ersue 3024 3026 WG Chair: Mahesh Jethanandani 3027 3029 Editor: Andy Bierman 3030 3032 Editor: Martin Bjorklund 3033 3035 Editor: Kent Watsen 3036 "; 3038 description 3039 "This module contains conceptual YANG specifications 3040 for basic RESTCONF media type definitions used in 3041 RESTCONF protocol messages. 3043 Note that the YANG definitions within this module do not 3044 represent configuration data of any kind. 3045 The 'restconf-media-type' YANG extension statement 3046 provides a normative syntax for XML and JSON message 3047 encoding purposes. 3049 Copyright (c) 2016 IETF Trust and the persons identified as 3050 authors of the code. All rights reserved. 3052 Redistribution and use in source and binary forms, with or 3053 without modification, is permitted pursuant to, and subject 3054 to the license terms contained in, the Simplified BSD License 3055 set forth in Section 4.c of the IETF Trust's Legal Provisions 3056 Relating to IETF Documents 3057 (http://trustee.ietf.org/license-info). 3059 This version of this YANG module is part of RFC XXXX; see 3060 the RFC itself for full legal notices."; 3062 // RFC Ed.: replace XXXX with actual RFC number and remove this 3063 // note. 3065 // RFC Ed.: remove this note 3066 // Note: extracted from draft-ietf-netconf-restconf-11.txt 3068 // RFC Ed.: update the date below with the date of RFC publication 3069 // and remove this note. 3070 revision 2016-03-16 { 3071 description 3072 "Initial revision."; 3073 reference 3074 "RFC XXXX: RESTCONF Protocol."; 3075 } 3077 extension restconf-media-type { 3078 argument media-type-id { 3079 yin-element true; 3080 } 3081 // RFC Ed.: replace draft-ietf-netmod-yang-json with RFC number 3082 // in the description below, and remove this note. 3084 description 3085 "This extension is used to specify a YANG data structure which 3086 represents a conceptual RESTCONF media type. 3087 Data definition statements within this extension specify 3088 the generic syntax for the specific media type. 3090 YANG is mapped to specific encoding formats outside the 3091 scope of this extension statement. RFC 6020 defines XML 3092 encoding rules for all RESTCONF media types that use 3093 the '+xml' suffix. draft-ietf-netmod-yang-json defines 3094 JSON encoding rules for all RESTCONF media types that 3095 use the '+json' suffix. 3097 The 'media-type-id' parameter value identifies the media type 3098 that is being defined. It contains the string associated 3099 with the generic media type, i.e., no suffix is specified. 3101 This extension is ignored unless it appears as a top-level 3102 statement. It SHOULD contain data definition statements 3103 that result in exactly one container data node definition. 3104 This allows compliant translation to an XML instance 3105 document for each media type. 3107 The module name and namespace value for the YANG module using 3108 the extension statement is assigned to instance document data 3109 conforming to the data definition statements within 3110 this extension. 3112 The sub-statements of this extension MUST follow the 3113 'data-def-stmt' rule in the YANG ABNF. 3115 The XPath document root is the extension statement itself, 3116 such that the child nodes of the document root are 3117 represented by the data-def-stmt sub-statements within 3118 this extension. This conceptual document is the context 3119 for the following YANG statements: 3121 - must-stmt 3122 - when-stmt 3123 - path-stmt 3124 - min-elements-stmt 3125 - max-elements-stmt 3126 - mandatory-stmt 3127 - unique-stmt 3128 - ordered-by 3129 - instance-identifier data type 3131 The following data-def-stmt sub-statements have special 3132 meaning when used within a restconf-resource extension 3133 statement. 3135 - The list-stmt is not required to have a key-stmt defined. 3136 - The if-feature-stmt is ignored if present. 3137 - The config-stmt is ignored if present. 3138 - The available identity values for any 'identityref' 3139 leaf or leaf-list nodes is limited to the module 3140 containing this extension statement, and the modules 3141 imported into that module. 3142 "; 3143 } 3145 rc:restconf-media-type "application/yang.errors" { 3146 uses errors; 3147 } 3149 rc:restconf-media-type "application/yang.api" { 3150 uses restconf; 3151 } 3153 grouping errors { 3154 description 3155 "A grouping that contains a YANG container 3156 representing the syntax and semantics of a 3157 YANG Patch errors report within a response message."; 3159 container errors { 3160 description 3161 "Represents an error report returned by the server if 3162 a request results in an error."; 3164 list error { 3165 description 3166 "An entry containing information about one 3167 specific error that occurred while processing 3168 a RESTCONF request."; 3169 reference "RFC 6241, Section 4.3"; 3171 leaf error-type { 3172 type enumeration { 3173 enum transport { 3174 description "The transport layer"; 3175 } 3176 enum rpc { 3177 description "The rpc or notification layer"; 3178 } 3179 enum protocol { 3180 description "The protocol operation layer"; 3181 } 3182 enum application { 3183 description "The server application layer"; 3184 } 3185 } 3186 mandatory true; 3187 description 3188 "The protocol layer where the error occurred."; 3189 } 3191 leaf error-tag { 3192 type string; 3193 mandatory true; 3194 description 3195 "The enumerated error tag."; 3196 } 3198 leaf error-app-tag { 3199 type string; 3200 description 3201 "The application-specific error tag."; 3202 } 3204 leaf error-path { 3205 type instance-identifier; 3206 description 3207 "The YANG instance identifier associated 3208 with the error node."; 3209 } 3211 leaf error-message { 3212 type string; 3213 description 3214 "A message describing the error."; 3215 } 3217 anyxml error-info { 3218 description 3219 "This anyxml value MUST represent a container with 3220 zero or more data nodes representing additional 3221 error information."; 3222 } 3223 } 3224 } 3225 } 3227 grouping restconf { 3228 description 3229 "Conceptual container representing the 3230 application/yang.api resource type."; 3232 container restconf { 3233 description 3234 "Conceptual container representing the 3235 application/yang.api resource type."; 3237 container data { 3238 description 3239 "Container representing the application/yang.datastore 3240 resource type. Represents the conceptual root of all 3241 state data and configuration data supported by 3242 the server. The child nodes of this container can be 3243 any data resource (application/yang.data), which are 3244 defined as top-level data nodes from the YANG modules 3245 advertised by the server in the ietf-restconf-monitoring 3246 module."; 3247 } 3249 container operations { 3250 description 3251 "Container for all operation resources 3252 (application/yang.operation), 3254 Each resource is represented as an empty leaf with the 3255 name of the RPC operation from the YANG rpc statement. 3257 E.g.; 3259 POST /restconf/operations/show-log-errors 3261 leaf show-log-errors { 3262 type empty; 3263 } 3264 "; 3265 } 3267 leaf yang-library-version { 3268 type string { 3269 pattern '\d{4}-\d{2}-\d{2}'; 3270 } 3271 config false; 3272 mandatory true; 3273 description 3274 "Identifies the revision date of the ietf-yang-library 3275 module that is implemented by this RESTCONF server. 3277 Indicates the year, month, and day in YYYY-MM-DD 3278 numeric format."; 3279 } 3280 } 3281 } 3283 } 3285 3287 9. RESTCONF Monitoring 3289 The "ietf-restconf-monitoring" module provides information about the 3290 RESTCONF protocol capabilities and event notification streams 3291 available from the server. A RESTCONF server MUST implement the "/ 3292 restconf-state/capabilities" container in this module. 3294 YANG Tree Diagram for "ietf-restconf-monitoring" module: 3296 +--ro restconf-state 3297 +--ro capabilities 3298 | +--ro capability* inet:uri 3299 +--ro streams 3300 +--ro stream* [name] 3301 +--ro name string 3302 +--ro description? string 3303 +--ro replay-support? boolean 3304 +--ro replay-log-creation-time? yang:date-and-time 3305 +--ro access* [encoding] 3306 +--ro encoding string 3307 +--ro location inet:uri 3309 9.1. restconf-state/capabilities 3311 This mandatory container holds the RESTCONF protocol capability URIs 3312 supported by the server. 3314 The server MUST maintain a last-modified timestamp for this 3315 container, and return the "Last-Modified" header when this data node 3316 is retrieved with the GET or HEAD methods. 3318 The server SHOULD maintain an entity-tag for this container, and 3319 return the "ETag" header when this data node is retrieved with the 3320 GET or HEAD methods. 3322 The server MUST include a "capability" URI leaf-list entry for the 3323 "defaults" mode used by the server, defined in Section 9.1.2. 3325 The server MUST include a "capability" URI leaf-list entry 3326 identifying each supported optional protocol feature. This includes 3327 optional query parameters and MAY include other capability URIs 3328 defined outside this document. 3330 9.1.1. Query Parameter URIs 3332 A new set of RESTCONF Capability URIs are defined to identify the 3333 specific query parameters (defined in Section 4.8) supported by the 3334 server. 3336 The server MUST include a "capability" leaf-list entry for each 3337 optional query parameter that it supports. 3339 +-------------+-------+---------------------------------------------+ 3340 | Name | Secti | URI | 3341 | | on | | 3342 +-------------+-------+---------------------------------------------+ 3343 | depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 | 3344 | | | .0 | 3345 | fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: | 3346 | | | 1.0 | 3347 | filter | 4.8.6 | urn:ietf:params:restconf:capability:filter: | 3348 | | | 1.0 | 3349 | replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: | 3350 | | 4.8.8 | 1.0 | 3351 | with- | 4.8.9 | urn:ietf:params:restconf:capability:with- | 3352 | defaults | | defaults:1.0 | 3353 +-------------+-------+---------------------------------------------+ 3355 RESTCONF Query Parameter URIs 3357 9.1.2. The "defaults" Protocol Capability URI 3359 This URI identifies the defaults handling mode that is used by the 3360 server for processing default leafs in requests for data resources. 3361 A parameter named "basic-mode" is required for this capability URI. 3362 The "basic-mode" definitions are specified in the "With-Defaults 3363 Capability for NETCONF" [RFC6243]. 3365 +----------+--------------------------------------------------+ 3366 | Name | URI | 3367 +----------+--------------------------------------------------+ 3368 | defaults | urn:ietf:params:restconf:capability:defaults:1.0 | 3369 +----------+--------------------------------------------------+ 3371 RESTCONF defaults capability URI 3373 This protocol capability URI MUST be supported by the server, and 3374 MUST be listed in the "capability" leaf-list in Section 9.3. 3376 +------------------+------------------------------------------------+ 3377 | Value | Description | 3378 +------------------+------------------------------------------------+ 3379 | report-all | No data nodes are considered default | 3380 | trim | Values set to the YANG default-stmt value are | 3381 | | default | 3382 | explicit | Values set by the client are never considered | 3383 | | default | 3384 +------------------+------------------------------------------------+ 3386 If the "basic-mode" is set to "report-all" then the server MUST 3387 adhere to the defaults handling behavior defined in Section 2.1 of 3388 [RFC6243]. 3390 If the "basic-mode" is set to "trim" then the server MUST adhere to 3391 the defaults handling behavior defined in Section 2.2 of [RFC6243]. 3393 If the "basic-mode" is set to "explicit" then the server MUST adhere 3394 to the defaults handling behavior defined in Section 2.3 of 3395 [RFC6243]. 3397 Example: (split for display purposes only) 3399 urn:ietf:params:restconf:capability:defaults:1.0? 3400 basic-mode=explicit 3402 9.2. restconf-state/streams 3404 This optional container provides access to the event notification 3405 streams supported by the server. The server MAY omit this container 3406 if no event notification streams are supported. 3408 The server will populate this container with a stream list entry for 3409 each stream type it supports. Each stream contains a leaf called 3410 "events" which contains a URI that represents an event stream 3411 resource. 3413 Stream resources are defined in Section 3.8. Notifications are 3414 defined in Section 6. 3416 9.3. RESTCONF Monitoring Module 3418 The "ietf-restconf-monitoring" module defines monitoring information 3419 for the RESTCONF protocol. 3421 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 3422 are used by this module for some type definitions. 3424 RFC Ed.: update the date below with the date of RFC publication and 3425 remove this note. 3427 file "ietf-restconf-monitoring@2016-03-16.yang" 3429 module ietf-restconf-monitoring { 3430 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; 3431 prefix "rcmon"; 3433 import ietf-yang-types { prefix yang; } 3434 import ietf-inet-types { prefix inet; } 3436 organization 3437 "IETF NETCONF (Network Configuration) Working Group"; 3439 contact 3440 "WG Web: 3441 WG List: 3443 WG Chair: Mehmet Ersue 3444 3446 WG Chair: Mahesh Jethanandani 3447 3449 Editor: Andy Bierman 3450 3452 Editor: Martin Bjorklund 3453 3455 Editor: Kent Watsen 3456 "; 3458 description 3459 "This module contains monitoring information for the 3460 RESTCONF protocol. 3462 Copyright (c) 2016 IETF Trust and the persons identified as 3463 authors of the code. All rights reserved. 3465 Redistribution and use in source and binary forms, with or 3466 without modification, is permitted pursuant to, and subject 3467 to the license terms contained in, the Simplified BSD License 3468 set forth in Section 4.c of the IETF Trust's Legal Provisions 3469 Relating to IETF Documents 3470 (http://trustee.ietf.org/license-info). 3472 This version of this YANG module is part of RFC XXXX; see 3473 the RFC itself for full legal notices."; 3475 // RFC Ed.: replace XXXX with actual RFC number and remove this 3476 // note. 3478 // RFC Ed.: remove this note 3479 // Note: extracted from draft-ietf-netconf-restconf-11.txt 3481 // RFC Ed.: update the date below with the date of RFC publication 3482 // and remove this note. 3483 revision 2016-03-16 { 3484 description 3485 "Initial revision."; 3486 reference 3487 "RFC XXXX: RESTCONF Protocol."; 3488 } 3490 container restconf-state { 3491 config false; 3492 description 3493 "Contains RESTCONF protocol monitoring information."; 3495 container capabilities { 3496 description 3497 "Contains a list of protocol capability URIs"; 3499 leaf-list capability { 3500 type inet:uri; 3501 description "A RESTCONF protocol capability URI."; 3502 } 3503 } 3505 container streams { 3506 description 3507 "Container representing the notification event streams 3508 supported by the server."; 3509 reference 3510 "RFC 5277, Section 3.4, element."; 3512 list stream { 3513 key name; 3514 description 3515 "Each entry describes an event stream supported by 3516 the server."; 3518 leaf name { 3519 type string; 3520 description "The stream name"; 3521 reference "RFC 5277, Section 3.4, element."; 3522 } 3524 leaf description { 3525 type string; 3526 description "Description of stream content"; 3527 reference 3528 "RFC 5277, Section 3.4, element."; 3529 } 3531 leaf replay-support { 3532 type boolean; 3533 description 3534 "Indicates if replay buffer supported for this stream. 3535 If 'true', then the server MUST support the 'start-time' 3536 and 'stop-time' query parameters for this stream."; 3537 reference 3538 "RFC 5277, Section 3.4, element."; 3539 } 3541 leaf replay-log-creation-time { 3542 when "../replay-support" { 3543 description 3544 "Only present if notification replay is supported"; 3545 } 3546 type yang:date-and-time; 3547 description 3548 "Indicates the time the replay log for this stream 3549 was created."; 3550 reference 3551 "RFC 5277, Section 3.4, 3552 element."; 3553 } 3555 list access { 3556 key encoding; 3557 min-elements 1; 3558 description 3559 "The server will create an entry in this list for each 3560 encoding format that is supported for this stream. 3562 The media type 'application/yang.stream' is expected 3563 for all event streams. This list identifies the 3564 sub-types supported for this stream."; 3566 leaf encoding { 3567 type string; 3568 description 3569 "This is the secondary encoding format within the 3570 'text/event-stream' encoding used by all streams. 3571 The type 'xml' is supported for the media type 3572 'application/yang.stream+xml'. The type 'json' 3573 is supported for the media type 3574 'application/yang.stream+json'."; 3576 } 3578 leaf location { 3579 type inet:uri; 3580 mandatory true; 3581 description 3582 "Contains a URL that represents the entry point 3583 for establishing notification delivery via server 3584 sent events."; 3585 } 3586 } 3587 } 3588 } 3589 } 3591 } 3593 3595 10. YANG Module Library 3597 The "ietf-yang-library" module defined in 3598 [I-D.ietf-netconf-yang-library] provides information about the YANG 3599 modules and submodules used by the RESTCONF server. Implementation 3600 is mandatory for RESTCONF servers. All YANG modules and submodules 3601 used by the server MUST be identified in the YANG module library. 3603 10.1. modules 3605 This mandatory container holds the identifiers for the YANG data 3606 model modules supported by the server. 3608 The server MUST maintain a last-modified timestamp for this 3609 container, and return the "Last-Modified" header when this data node 3610 is retrieved with the GET or HEAD methods. 3612 The server SHOULD maintain an entity-tag for this container, and 3613 return the "ETag" header when this data node is retrieved with the 3614 GET or HEAD methods. 3616 10.1.1. modules/module 3618 This mandatory list contains one entry for each YANG data model 3619 module supported by the server. There MUST be an instance of this 3620 list for every YANG module that is used by the server. 3622 The contents of this list are defined in the "module" YANG list 3623 statement in [I-D.ietf-netconf-yang-library]. 3625 The server SHOULD maintain a last-modified timestamp for each 3626 instance of this list entry, and return the "Last-Modified" header 3627 when this data node is retrieved with the GET or HEAD methods. 3629 The server SHOULD maintain an entity-tag for each instance of this 3630 list entry, and return the "ETag" header when this data node is 3631 retrieved with the GET or HEAD methods. 3633 11. IANA Considerations 3635 11.1. The "restconf" Relation Type 3637 This specification registers the "restconf" relation type in the Link 3638 Relation Type Registry defined by [RFC5988]: 3640 Relation Name: restconf 3642 Description: Identifies the root of RESTCONF API as configured 3643 on this HTTP server. The "restconf" relation 3644 defines the root of the API defined in RFCXXXX. 3645 Subsequent revisions of RESTCONF will use alternate 3646 relation values to support protocol versioning. 3648 Reference: RFCXXXX 3650 ` 3652 11.2. YANG Module Registry 3653 This document registers two URIs in the IETF XML registry [RFC3688]. 3654 Following the format in RFC 3688, the following registration is 3655 requested to be made. 3657 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 3658 Registrant Contact: The NETMOD WG of the IETF. 3659 XML: N/A, the requested URI is an XML namespace. 3661 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3662 Registrant Contact: The NETMOD WG of the IETF. 3663 XML: N/A, the requested URI is an XML namespace. 3665 This document registers two YANG modules in the YANG Module Names 3666 registry [RFC6020]. 3668 name: ietf-restconf 3669 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3670 prefix: rc 3671 // RFC Ed.: replace XXXX with RFC number and remove this note 3672 reference: RFCXXXX 3674 name: ietf-restconf-monitoring 3675 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3676 prefix: rcmon 3677 // RFC Ed.: replace XXXX with RFC number and remove this note 3678 reference: RFCXXXX 3680 11.3. application/yang Media Sub Types 3682 The parent MIME media type for RESTCONF resources is application/ 3683 yang, which is defined in [RFC6020]. This document defines the 3684 following sub-types for this media type. 3686 - api 3687 - data 3688 - datastore 3689 - errors 3690 - operation 3691 - stream 3693 Type name: application 3695 Subtype name: yang.xxx, where "xxx" is 1 of "api", 3696 "data", "datastore", "errors", "operation", or "stream" 3698 Required parameters: none 3700 Optional parameters: See section 4.8 in RFC XXXX 3701 Encoding considerations: 8-bit 3703 Security considerations: See Section 12 in RFC XXXX 3705 Interoperability considerations: none 3707 // RFC Ed.: replace XXXX with RFC number and remove this note 3708 Published specification: RFC XXXX 3710 11.4. RESTCONF Capability URNs 3712 [Note to RFC Editor: 3713 The RESTCONF Protocol Capability Registry does not yet exist; 3714 Need to ask IANA to create it; remove this note for publication 3715 ] 3717 This document defines a registry for RESTCONF capability identifiers. 3718 The name of the registry is "RESTCONF Capability URNs". The registry 3719 shall record for each entry: 3721 o the name of the RESTCONF capability. By convention, this name is 3722 prefixed with the colon ':' character. 3724 o the URN for the RESTCONF capability. 3726 This document registers several capability identifiers in "RESTCONF 3727 Capability URNs" registry: 3729 Index 3730 Capability Identifier 3731 ------------------------ 3733 :defaults 3734 urn:ietf:params:restconf:capability:defaults:1.0 3736 :depth 3737 urn:ietf:params:restconf:capability:depth:1.0 3739 :fields 3740 urn:ietf:params:restconf:capability:fields:1.0 3742 :filter 3743 urn:ietf:params:restconf:capability:filter:1.0 3745 :replay 3746 urn:ietf:params:restconf:capability:replay:1.0 3748 :with-defaults 3749 urn:ietf:params:restconf:capability:with-defaults:1.0 3751 12. Security Considerations 3753 This section provides security considerations for the resources 3754 defined by the RESTCONF protocol. Security considerations for HTTPS 3755 are defined in [RFC2818]. RESTCONF does not specify which YANG 3756 modules a server needs to support. Security considerations for the 3757 YANG-defined content manipulated by RESTCONF can be found in the 3758 documents defining those YANG modules. 3760 This document does not require use of a specific client 3761 authentication mechanism or authorization model, but it does require 3762 that a client authentication mechanism and authorization model is 3763 used whenever a client accesses a protected resource. Client 3764 authentication MUST be implemented using client certificates or MUST 3765 be implemented using an HTTP authentication scheme. Client 3766 authorization MAY be configured using the NETCONF Access Control 3767 Model (NACM) [RFC6536]. 3769 Configuration information is by its very nature sensitive. Its 3770 transmission in the clear and without integrity checking leaves 3771 devices open to classic eavesdropping and false data injection 3772 attacks. Configuration information often contains passwords, user 3773 names, service descriptions, and topological information, all of 3774 which are sensitive. Because of this, this protocol SHOULD be 3775 implemented carefully with adequate attention to all manner of attack 3776 one might expect to experience with other management interfaces. 3778 Different environments may well allow different rights prior to and 3779 then after authentication. When an operation is not properly 3780 authorized, the RESTCONF server MUST return a "401 Unauthorized" 3781 status-line. Note that authorization information can be exchanged in 3782 the form of configuration information, which is all the more reason 3783 to ensure the security of the connection. 3785 13. Acknowledgements 3787 The authors would like to thank the following people for their 3788 contributions to this document: Ladislav Lhotka, Juergen 3789 Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. 3791 The authors would like to thank the following people for their 3792 excellent review comments and contributions to this document: Qin Wu, 3793 Joe Clarke, Bert Wijnen, Ladislav Lhotka, Rodney Cummings, Frank 3794 Xialiang, Tom Petch, Robert Sparks, Balint Uveges, Randy Presuhn, and 3795 Sue Hares. 3797 Contributions to this material by Andy Bierman are based upon work 3798 supported by the The Space & Terrestrial Communications Directorate 3799 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 3800 and conclusions or recommendations expressed in this material are 3801 those of the author(s) and do not necessarily reflect the views of 3802 The Space & Terrestrial Communications Directorate (S&TCD). 3804 14. References 3806 14.1. Normative References 3808 [I-D.ietf-netconf-yang-library] 3809 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 3810 Library", draft-ietf-netconf-yang-library-05 (work in 3811 progress), April 2016. 3813 [I-D.ietf-netmod-rfc6020bis] 3814 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 3815 draft-ietf-netmod-rfc6020bis-11 (work in progress), 3816 February 2016. 3818 [I-D.ietf-netmod-yang-json] 3819 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3820 draft-ietf-netmod-yang-json-06 (work in progress), October 3821 2015. 3823 [I-D.ietf-netmod-yang-metadata] 3824 Lhotka, L., "Defining and Using Metadata with YANG", 3825 draft-ietf-netmod-yang-metadata-02 (work in progress), 3826 September 2015. 3828 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3829 Extensions (MIME) Part Two: Media Types", RFC 2046, 3830 November 1996. 3832 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3833 Requirement Levels", BCP 14, RFC 2119, March 1997. 3835 [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. 3837 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3838 January 2004. 3840 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3841 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3842 3986, January 2005. 3844 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3845 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3847 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3848 Notifications", RFC 5277, July 2008. 3850 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3851 Housley, R., and T. Polk, "Internet X.509 Public Key 3852 Infrastructure Certificate and Certificate Revocation List 3853 (CRL) Profile", RFC 5280, May 2008. 3855 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3856 5789, March 2010. 3858 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3860 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 3861 Network Configuration Protocol (NETCONF)", RFC 6020, 3862 October 2010. 3864 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3865 Verification of Domain-Based Application Service Identity 3866 within Internet Public Key Infrastructure Using X.509 3867 (PKIX) Certificates in the Context of Transport Layer 3868 Security (TLS)", RFC 6125, March 2011. 3870 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3871 and A. Bierman, Ed., "Network Configuration Protocol 3872 (NETCONF)", RFC 6241, June 2011. 3874 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 3875 NETCONF", RFC 6243, June 2011. 3877 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 3878 6415, October 2011. 3880 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 3881 Protocol (NETCONF) Access Control Model", RFC 6536, March 3882 2012. 3884 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3885 and D. Orchard, "URI Template", RFC 6570, March 2012. 3887 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 3888 July 2013. 3890 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3891 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3892 2014, . 3894 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3895 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 3896 2014. 3898 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3899 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3901 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3902 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 3904 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3905 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3907 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 3908 7320, July 2014. 3910 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 3911 NETCONF Protocol over Transport Layer Security (TLS) with 3912 Mutual X.509 Authentication", RFC 7589, DOI 10.17487/ 3913 RFC7589, June 2015, 3914 . 3916 [W3C.CR-eventsource-20121211] 3917 Hickson, I., "Server-Sent Events", World Wide Web 3918 Consortium CR CR-eventsource-20121211, December 2012, 3919 . 3921 [W3C.REC-html5-20141028] 3922 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 3923 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", World 3924 Wide Web Consortium Recommendation REC-html5-20141028, 3925 October 2014, 3926 . 3928 [W3C.REC-xml-20081126] 3929 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 3930 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 3931 Edition)", World Wide Web Consortium Recommendation REC- 3932 xml-20081126, November 2008, 3933 . 3935 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 3936 Version 1.0", World Wide Web Consortium Recommendation 3937 REC-xpath-19991116, November 1999, 3938 . 3940 14.2. Informative References 3942 [I-D.ietf-netconf-yang-patch] 3943 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 3944 Media Type", draft-ietf-netconf-yang-patch-06 (work in 3945 progress), October 2015. 3947 [rest-dissertation] 3948 Fielding, R., "Architectural Styles and the Design of 3949 Network-based Software Architectures", 2000. 3951 Appendix A. Change Log 3953 -- RFC Ed.: remove this section before publication. 3955 The RESTCONF issue tracker can be found here: https://github.com/ 3956 netconf-wg/restconf/issues 3958 A.1. v10 - v11 3960 o change term 'operational data' to 'state data' 3962 o clarify :startup behavior 3964 o clarify X.509 security text 3965 o change '403 Forbidden' to '401 Unauthorized' for GET error 3967 o clarify MUST have one "restconf" link relation 3969 o clarify that NV-storage is not mandatory 3971 o clarify how "Last-Modified" and "ETag" header info can be used by 3972 a client 3974 o clarify meaning of mandatory parameter 3976 o fix module name in action examples 3978 o clarify operation resource request needs to be known to parse the 3979 output 3981 o clarify ordered-by user terminology 3983 o fixed JSON example in D.1.1 3985 A.2. v09 - v10 3987 o address review comments: github issue #36 3989 o removed intro text about no knowledge of NETCONF needed 3991 o clarified candidate and confirmed-commit behavior in sec. 1.3 3993 o clarified that a RESTCONF server MUST support TLS 3995 o clarified choice of 403 or 404 error 3997 o fixed forward references to URI template (w/reference at first 3998 use) 4000 o added reference to HTML5 4002 o made error terminology more consistent 4004 o clarified that only 1 list or leaf-list instance can be returned 4005 in an XML response message-body 4007 o clarified that more than 1 instance must not be created by a POST 4008 method 4010 o clarified that PUT cannot be used to change a leaf-list value or 4011 any list key values 4013 o clarified that PATCH cannot be used to change a leaf-list value or 4014 any list key values 4016 o clarified that DELETE should not be used to delete more than one 4017 instance of a leaf-list or list 4019 o update JSON RFC reference 4021 o specified that leaf-list instances are data resources 4023 o specified how a leaf-list instance identifier is constructed 4025 o fixed get-schema example 4027 o clarified that if no Accept header the server SHOULD return the 4028 type specified in RESTCONF, but MAY return any media-type, 4029 according to HTTP rules 4031 o clarified that server SHOULD maintain timestamp and etag for data 4032 resources 4034 o clarified default for content query parameter 4036 o moved terminology section earlier in doc to avoid forward usage 4038 o clarified intro text wrt/ interactions with NETCONF and access to 4039 specific datastores 4041 o clarified server implementation requirements for YANG defaults 4043 o clarified that Errors is not a resource, just a media type 4045 o clarified that HTTP without TLS MUST NOT be used 4047 o add RESTCONF Extensibility section to make it clear how RESTCONF 4048 will be extended in the future 4050 o add text warning that NACM does not work with HTTP caching 4052 o remove sec. 5.2 Message Headers 4054 o remove 202 Accepted from list of used status-lines -- not allowed 4056 o made implementation of OPTIONS MUST instead of SHOULD 4058 o clarified that successful PUT for altering data returns 204 4060 o fixed "point" parameter example 4061 o added example of alternate value for root resource discovery 4063 o added YANG action examples 4065 o fixed some JSON examples 4067 o changed default value for content query parameter to "all" 4069 o changed empty container JSON encoding from "[null]" to "{}" 4071 o added mandatory /restconf/yang-library-version leaf to advertise 4072 revision-date of the YANG library implemented by the server 4074 o clarified URI encoding rules for leaf-list 4076 o clarified sec. 2.2 wrt/ certificates and TLS 4078 o added update procedure for entity tag and timestamp 4080 A.3. v08 - v09 4082 o fix introduction text regarding implementation requirements for 4083 the ietf-yang-library 4085 o clarified HTTP authentication requirements 4087 o fix host-meta example 4089 o changed list key encoding to clarify that quoted strings are not 4090 allowed. Percent-encoded values are used if quotes would be 4091 required. A missing key is treated as a zero-length string 4093 o Fixed example of percent-encoded string to match YANG model 4095 o Changed streams examples to align with naming already used 4097 A.4. v07 - v08 4099 o add support for YANG 1.1 action statement 4101 o changed mandatory encoding from XML to XML or JSON 4103 o fix syntax in fields parameter definition 4105 o add meta-data encoding examples for XML and JSON 4107 o remove RFC 2396 references and update with 3986 4108 o change encoding of a key so quoted string are not used, since they 4109 are already percent-encoded. A zero-length string is not encoded 4110 (/list=foo,,baz) 4112 o Add example of percent-encoded key value 4114 A.5. v06 - v07 4116 o fixed all issues identified in email from Jernej Tuljak in netconf 4117 email 2015-06-22 4119 o fixed error example bug where error-urlpath was still used. 4120 Changed to error-path. 4122 o added mention of YANG Patch and informative reference 4124 o added support for YANG 1.1, specifically support for anydata and 4125 actions 4127 o removed the special field value "*", since it is no longer needed 4129 A.6. v05 - v06 4131 o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) 4133 A.7. v04 - v05 4135 o changed term 'notification event' to 'event notification' 4137 o removed intro text about framework and meta-model 4139 o removed early mention of API resources 4141 o removed term unified datastore and cleaned up text about NETCONF 4142 datastores 4144 o removed text about not immediate persistence of edits 4146 o removed RESTCONF-specific data-resource-identifier typedef and its 4147 usage 4149 o clarified encoding of key leafs 4151 o changed several examples from JSON to XML encoding 4153 o made 'insert' and 'point' query parameters mandatory to implement 4155 o removed ":insert" capability URI 4156 o renamed stream/encoding to stream/access 4158 o renamed stream/encoding/type to stream/access/encoding 4160 o renamed stream/encoding/events to stream/access/location 4162 o changed XPath from informative to normative reference 4164 o changed rest-dissertation from normative to informative reference 4166 o changed example-jukebox playlist 'id' from a data-resource- 4167 identifier to a leafref pointing at the song name 4169 A.8. v03 - v04 4171 o renamed 'select' to 'fields' (#1) 4173 o moved collection resource and page capability to draft-ietf- 4174 netconf-restconf-collection-00 (#3) 4176 o added mandatory "defaults" protocol capability URI (#4) 4178 o added optional "with-defaults" query parameter URI (#4) 4180 o clarified authentication procedure (#9) 4182 o moved ietf-yang-library module to draft-ietf-netconf-yang- 4183 library-00 (#13) 4185 o clarified that JSON encoding of module name in a URI MUST follow 4186 the netmod-yang-json encoding rules (#14) 4188 o added restconf-media-type extension (#15) 4190 o remove "content" query parameter URI and made this parameter 4191 mandatory (#16) 4193 o clarified datastore usage 4195 o changed lock-denied error example 4197 o added with-defaults query parameter example 4199 o added term "RESTCONF Capability" 4201 o changed NETCONF Capability URI registry usage to new RESTCONF 4202 Capability URI Registry usage 4204 A.9. v02 - v03 4206 o added collection resource 4208 o added "page" query parameter capability 4210 o added "limit" and "offset" query parameters, which are available 4211 if the "page" capability is supported 4213 o added "stream list" term 4215 o fixed bugs in some examples 4217 o added "encoding" list within the "stream" list to allow different 4218 URLs for XML and JSON encoding. 4220 o made XML MUST implement and JSON MAY implement for servers 4222 o re-add JSON notification examples (previously removed) 4224 o updated JSON references 4226 A.10. v01 - v02 4228 o moved query parameter definitions from the YANG module back to the 4229 plain text sections 4231 o made all query parameters optional to implement 4233 o defined query parameter capability URI 4235 o moved 'streams' to new YANG module (ietf-restconf-monitoring) 4237 o added 'capabilities' container to new YANG module (ietf-restconf- 4238 monitoring) 4240 o moved 'modules' container to new YANG module (ietf-yang-library) 4242 o added new leaf 'module-set-id' (ietf-yang-library) 4244 o added new leaf 'conformance' (ietf-yang-library) 4246 o changed 'schema' leaf to type inet:uri that returns the location 4247 of the YANG schema (instead of returning the schema directly) 4249 o changed 'events' leaf to type inet:uri that returns the location 4250 of the event stream resource (instead of returning events 4251 directly) 4253 o changed examples for yang.api resource since the monitoring 4254 information is no longer in this resource 4256 o closed issue #1 'select parameter' since no objections to the 4257 proposed syntax 4259 o closed "encoding of list keys" issue since no objection to new 4260 encoding of list keys in a target resource URI. 4262 o moved open issues list to the issue tracker on github 4264 A.11. v00 - v01 4266 o fixed content=nonconfig example (non-config was incorrect) 4268 o closed open issue 'message-id'. There is no need for a message-id 4269 field, and RFC 2392 does not apply. 4271 o closed open issue 'server support verification'. The headers used 4272 by RESTCONF are widely supported. 4274 o removed encoding rules from section on RESTCONF Meta-Data. This 4275 is now defined in "I-D.lhotka-netmod-yang-json". 4277 o added media type application/yang.errors to map to errors YANG 4278 grouping. Updated error examples to use new media type. 4280 o closed open issue 'additional datastores'. Support may be added 4281 in the future to identify new datastores. 4283 o closed open issue 'PATCH media type discovery'. The section on 4284 PATCH has an added sentence on the Accept-Patch header. 4286 o closed open issue 'YANG to resource mapping'. Current mapping of 4287 all data nodes to resources will be used in order to allow 4288 mandatory DELETE support. The PATCH operation is optional, as 4289 well as the YANG Patch media type. 4291 o closed open issue '_self links for HATEOAS support'. It was 4292 decided that they are redundant because they can be derived from 4293 the YANG module for the specific data. 4295 o added explanatory text for the 'select' parameter. 4297 o added RESTCONF Path Resolution section for discovering the root of 4298 the RESTCONF API using the /.well-known/host-meta. 4300 o added an "error" media type to for structured error messages 4301 o added Secure Transport section requiring TLS 4303 o added Security Considerations section 4305 o removed all references to "REST-like" 4307 A.12. bierman:restconf-04 to ietf:restconf-00 4309 o updated open issues section 4311 Appendix B. Open Issues 4313 -- RFC Ed.: remove this section before publication. 4315 The RESTCONF issues are tracked on github.com: 4317 https://github.com/netconf-wg/restconf/issues 4319 Appendix C. Example YANG Module 4321 The example YANG module used in this document represents a simple 4322 media jukebox interface. 4324 YANG Tree Diagram for "example-jukebox" Module 4326 +--rw jukebox! 4327 +--rw library 4328 | +--rw artist* [name] 4329 | | +--rw name string 4330 | | +--rw album* [name] 4331 | | +--rw name string 4332 | | +--rw genre? identityref 4333 | | +--rw year? uint16 4334 | | +--rw admin 4335 | | | +--rw label? string 4336 | | | +--rw catalogue-number? string 4337 | | +--rw song* [name] 4338 | | +--rw name string 4339 | | +--rw location string 4340 | | +--rw format? string 4341 | | +--rw length? uint32 4342 | +--ro artist-count? uint32 4343 | +--ro album-count? uint32 4344 | +--ro song-count? uint32 4345 +--rw playlist* [name] 4346 | +--rw name string 4347 | +--rw description? string 4348 | +--rw song* [index] 4349 | +--rw index uint32 4350 | +--rw id leafref 4351 +--rw player 4352 +--rw gap? decimal64 4354 rpcs: 4356 +---x play 4357 +--ro input 4358 +--ro playlist string 4359 +--ro song-number uint32 4361 C.1. example-jukebox YANG Module 4363 module example-jukebox { 4365 namespace "http://example.com/ns/example-jukebox"; 4366 prefix "jbox"; 4368 organization "Example, Inc."; 4369 contact "support at example.com"; 4370 description "Example Jukebox Data Model Module"; 4371 revision "2015-04-04" { 4372 description "Initial version."; 4373 reference "example.com document 1-4673"; 4374 } 4376 identity genre { 4377 description "Base for all genre types"; 4378 } 4380 // abbreviated list of genre classifications 4381 identity alternative { 4382 base genre; 4383 description "Alternative music"; 4384 } 4385 identity blues { 4386 base genre; 4387 description "Blues music"; 4388 } 4389 identity country { 4390 base genre; 4391 description "Country music"; 4392 } 4393 identity jazz { 4394 base genre; 4395 description "Jazz music"; 4396 } 4397 identity pop { 4398 base genre; 4399 description "Pop music"; 4400 } 4401 identity rock { 4402 base genre; 4403 description "Rock music"; 4404 } 4406 container jukebox { 4407 presence 4408 "An empty container indicates that the jukebox 4409 service is available"; 4411 description 4412 "Represents a jukebox resource, with a library, playlists, 4413 and a play operation."; 4415 container library { 4417 description "Represents the jukebox library resource."; 4419 list artist { 4420 key name; 4422 description 4423 "Represents one artist resource within the 4424 jukebox library resource."; 4426 leaf name { 4427 type string { 4428 length "1 .. max"; 4429 } 4430 description "The name of the artist."; 4431 } 4433 list album { 4434 key name; 4436 description 4437 "Represents one album resource within one 4438 artist resource, within the jukebox library."; 4440 leaf name { 4441 type string { 4442 length "1 .. max"; 4443 } 4444 description "The name of the album."; 4446 } 4448 leaf genre { 4449 type identityref { base genre; } 4450 description 4451 "The genre identifying the type of music on 4452 the album."; 4453 } 4455 leaf year { 4456 type uint16 { 4457 range "1900 .. max"; 4458 } 4459 description "The year the album was released"; 4460 } 4462 container admin { 4463 description 4464 "Administrative information for the album."; 4466 leaf label { 4467 type string; 4468 description "The label that released the album."; 4469 } 4470 leaf catalogue-number { 4471 type string; 4472 description "The album's catalogue number."; 4473 } 4474 } 4476 list song { 4477 key name; 4479 description 4480 "Represents one song resource within one 4481 album resource, within the jukebox library."; 4483 leaf name { 4484 type string { 4485 length "1 .. max"; 4486 } 4487 description "The name of the song"; 4488 } 4489 leaf location { 4490 type string; 4491 mandatory true; 4492 description 4493 "The file location string of the 4494 media file for the song"; 4495 } 4496 leaf format { 4497 type string; 4498 description 4499 "An identifier string for the media type 4500 for the file associated with the 4501 'location' leaf for this entry."; 4502 } 4503 leaf length { 4504 type uint32; 4505 units "seconds"; 4506 description 4507 "The duration of this song in seconds."; 4508 } 4509 } // end list 'song' 4510 } // end list 'album' 4511 } // end list 'artist' 4513 leaf artist-count { 4514 type uint32; 4515 units "songs"; 4516 config false; 4517 description "Number of artists in the library"; 4518 } 4519 leaf album-count { 4520 type uint32; 4521 units "albums"; 4522 config false; 4523 description "Number of albums in the library"; 4524 } 4525 leaf song-count { 4526 type uint32; 4527 units "songs"; 4528 config false; 4529 description "Number of songs in the library"; 4530 } 4531 } // end library 4533 list playlist { 4534 key name; 4536 description 4537 "Example configuration data resource"; 4539 leaf name { 4540 type string; 4541 description 4542 "The name of the playlist."; 4543 } 4544 leaf description { 4545 type string; 4546 description 4547 "A comment describing the playlist."; 4548 } 4549 list song { 4550 key index; 4551 ordered-by user; 4553 description 4554 "Example nested configuration data resource"; 4556 leaf index { // not really needed 4557 type uint32; 4558 description 4559 "An arbitrary integer index for this playlist song."; 4560 } 4561 leaf id { 4562 type leafref { 4563 path "/jbox:jukebox/jbox:library/jbox:artist/" + 4564 "jbox:album/jbox:song/jbox:name"; 4565 } 4566 mandatory true; 4567 description 4568 "Song identifier. Must identify an instance of 4569 /jukebox/library/artist/album/song/name."; 4570 } 4571 } 4572 } 4574 container player { 4575 description 4576 "Represents the jukebox player resource."; 4578 leaf gap { 4579 type decimal64 { 4580 fraction-digits 1; 4581 range "0.0 .. 2.0"; 4582 } 4583 units "tenths of seconds"; 4584 description "Time gap between each song"; 4585 } 4586 } 4587 } 4589 rpc play { 4590 description "Control function for the jukebox player"; 4591 input { 4592 leaf playlist { 4593 type string; 4594 mandatory true; 4595 description "playlist name"; 4596 } 4597 leaf song-number { 4598 type uint32; 4599 mandatory true; 4600 description "Song number in playlist to play"; 4601 } 4602 } 4603 } 4604 } 4606 Appendix D. RESTCONF Message Examples 4608 The examples within this document use the normative YANG module 4609 defined in Section 8 and the non-normative example YANG module 4610 defined in Appendix C.1. 4612 This section shows some typical RESTCONF message exchanges. 4614 D.1. Resource Retrieval Examples 4616 D.1.1. Retrieve the Top-level API Resource 4618 The client may start by retrieving the top-level API resource, using 4619 the entry point URI "{+restconf}". 4621 GET /restconf HTTP/1.1 4622 Host: example.com 4623 Accept: application/yang.api+json 4625 The server might respond as follows: 4627 HTTP/1.1 200 OK 4628 Date: Mon, 23 Apr 2012 17:01:00 GMT 4629 Server: example-server 4630 Content-Type: application/yang.api+json 4632 { 4633 "ietf-restconf:restconf": { 4634 "data" : {}, 4635 "operations" : {}, 4636 "yang-library-version" : "2016-04-09" 4638 } 4639 } 4641 To request that the response content to be encoded in XML, the 4642 "Accept" header can be used, as in this example request: 4644 GET /restconf HTTP/1.1 4645 Host: example.com 4646 Accept: application/yang.api+xml 4648 The server will return the same response either way, which might be 4649 as follows : 4651 HTTP/1.1 200 OK 4652 Date: Mon, 23 Apr 2012 17:01:00 GMT 4653 Server: example-server 4654 Cache-Control: no-cache 4655 Pragma: no-cache 4656 Content-Type: application/yang.api+xml 4658 4659 4660 4661 2016-04-09 4662 4664 D.1.2. Retrieve The Server Module Information 4666 In this example the client is retrieving the modules information from 4667 the server in JSON format: 4669 GET /restconf/data/ietf-yang-library:modules HTTP/1.1 4670 Host: example.com 4671 Accept: application/yang.data+json 4673 The server might respond as follows (some strings wrapped for display 4674 purposes): 4676 HTTP/1.1 200 OK 4677 Date: Mon, 23 Apr 2012 17:01:00 GMT 4678 Server: example-server 4679 Cache-Control: no-cache 4680 Pragma: no-cache 4681 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4682 Content-Type: application/yang.data+json 4684 { 4685 "ietf-yang-library:modules": { 4686 "module": [ 4687 { 4688 "name" : "foo", 4689 "revision" : "2012-01-02", 4690 "schema" : "https://example.com/modules/foo/2012-01-02", 4691 "namespace" : "http://example.com/ns/foo", 4692 "feature" : [ "feature1", "feature2" ], 4693 "conformance-type" : "implement" 4694 }, 4695 { 4696 "name" : "ietf-yang-library", 4697 "revision" : "2016-04-09", 4698 "schema" : "https://example.com/modules/ietf-yang- 4699 library/2016-04-09", 4700 "namespace" : 4701 "urn:ietf:params:xml:ns:yang:ietf-yang-library", 4702 "conformance-type" : "implement" 4703 }, 4704 { 4705 "name" : "foo-types", 4706 "revision" : "2012-01-05", 4707 "schema" : 4708 "https://example.com/modules/foo-types/2012-01-05", 4709 "namespace" : "http://example.com/ns/foo-types", 4710 "conformance-type" : "import" 4711 }, 4712 { 4713 "name" : "bar", 4714 "revision" : "2012-11-05", 4715 "schema" : "https://example.com/modules/bar/2012-11-05", 4716 "namespace" : "http://example.com/ns/bar", 4717 "feature" : [ "bar-ext" ], 4718 "conformance-type" : "implement", 4719 "submodule" : [ 4720 { 4721 "name" : "bar-submod1", 4722 "revision" : "2012-11-05", 4723 "schema" : 4724 "https://example.com/modules/bar-submod1/2012-11-05" 4725 }, 4726 { 4727 "name" : "bar-submod2", 4728 "revision" : "2012-11-05", 4729 "schema" : 4730 "https://example.com/modules/bar-submod2/2012-11-05" 4731 } 4732 ] 4733 } 4735 ] 4736 } 4737 } 4739 D.1.3. Retrieve The Server Capability Information 4741 In this example the client is retrieving the capability information 4742 from the server in XML format, and the server supports all the 4743 RESTCONF query parameters, plus one vendor parameter: 4745 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 4746 capabilities HTTP/1.1 4747 Host: example.com 4748 Accept: application/yang.data+xml 4750 The server might respond as follows. The extra whitespace in 4751 'capability' elements for display purposes only. 4753 HTTP/1.1 200 OK 4754 Date: Mon, 23 Apr 2012 17:02:00 GMT 4755 Server: example-server 4756 Cache-Control: no-cache 4757 Pragma: no-cache 4758 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4759 Content-Type: application/yang.data+xml 4761 4762 4763 urn:ietf:params:restconf:capability:depth:1.0 4764 4765 4766 urn:ietf:params:restconf:capability:fields:1.0 4767 4768 4769 urn:ietf:params:restconf:capability:filter:1.0 4770 4771 4772 urn:ietf:params:restconf:capability:start-time:1.0 4773 4774 4775 urn:ietf:params:restconf:capability:stop-time:1.0 4776 4777 4778 http://example.com/capabilities/myparam 4779 4780 4782 D.2. Edit Resource Examples 4784 D.2.1. Create New Data Resources 4786 To create a new "artist" resource within the "library" resource, the 4787 client might send the following request. 4789 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 4790 Host: example.com 4791 Content-Type: application/yang.data+json 4793 { 4794 "example-jukebox:artist" : { 4795 "name" : "Foo Fighters" 4796 } 4797 } 4799 If the resource is created, the server might respond as follows. 4800 Note that the "Location" header line is wrapped for display purposes 4801 only: 4803 HTTP/1.1 201 Created 4804 Date: Mon, 23 Apr 2012 17:02:00 GMT 4805 Server: example-server 4806 Location: https://example.com/restconf/data/ 4807 example-jukebox:jukebox/library/artist=Foo%20Fighters 4808 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 4809 ETag: b3830f23a4c 4811 To create a new "album" resource for this artist within the "jukebox" 4812 resource, the client might send the following request. Note that the 4813 request URI header line is wrapped for display purposes only: 4815 POST /restconf/data/example-jukebox:jukebox/ 4816 library/artist=Foo%20Fighters HTTP/1.1 4817 Host: example.com 4818 Content-Type: application/yang.data+xml 4820 4821 Wasting Light 4822 2011 4823 4825 If the resource is created, the server might respond as follows. 4826 Note that the "Location" header line is wrapped for display purposes 4827 only: 4829 HTTP/1.1 201 Created 4830 Date: Mon, 23 Apr 2012 17:03:00 GMT 4831 Server: example-server 4832 Location: https://example.com/restconf/data/ 4833 example-jukebox:jukebox/library/artist=Foo%20Fighters/ 4834 album=Wasting%20Light 4835 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 4836 ETag: b8389233a4c 4838 D.2.2. Detect Resource Entity Tag Change 4840 In this example, the server just supports the mandatory datastore 4841 last-changed timestamp. The client has previously retrieved the 4842 "Last-Modified" header and has some value cached to provide in the 4843 following request to patch an "album" list entry with key value 4844 "Wasting Light". Only the "genre" field is being updated. 4846 PATCH /restconf/data/example-jukebox:jukebox/ 4847 library/artist=Foo%20Fighters/album=Wasting%20Light/genre 4848 HTTP/1.1 4849 Host: example.com 4850 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 4851 Content-Type: application/yang.data+json 4853 { "example-jukebox:genre" : "example-jukebox:alternative" } 4855 In this example the datastore resource has changed since the time 4856 specified in the "If-Unmodified-Since" header. The server might 4857 respond: 4859 HTTP/1.1 412 Precondition Failed 4860 Date: Mon, 23 Apr 2012 19:01:00 GMT 4861 Server: example-server 4862 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 4863 ETag: b34aed893a4c 4865 D.2.3. Edit a Datastore Resource 4867 In this example, the client modifies two different data nodes by 4868 sending a PATCH to the datastore resource: 4870 PATCH /restconf/data HTTP/1.1 4871 Host: example.com 4872 Content-Type: application/yang.datastore+xml 4874 4875 4876 4877 4878 Foo Fighters 4879 4880 Wasting Light 4881 2011 4882 4883 4884 4885 Nick Cave 4886 4887 Tender Prey 4888 1988 4889 4890 4891 4892 4893 4895 D.3. Query Parameter Examples 4897 D.3.1. "content" Parameter 4899 The "content" parameter is used to select the type of data child 4900 resources (configuration and/or not configuration) that are returned 4901 by the server for a GET method request. 4903 In this example, a simple YANG list that has configuration and non- 4904 configuration child resources. 4906 container events 4907 list event { 4908 key name; 4909 leaf name { type string; } 4910 leaf description { type string; } 4911 leaf event-count { 4912 type uint32; 4913 config false; 4914 } 4915 } 4916 } 4918 Example 1: content=all 4920 To retrieve all the child resources, the "content" parameter is set 4921 to "all". The client might send: 4923 GET /restconf/data/example-events:events?content=all 4924 HTTP/1.1 4926 Host: example.com 4927 Accept: application/yang.data+json 4929 The server might respond: 4931 HTTP/1.1 200 OK 4932 Date: Mon, 23 Apr 2012 17:11:30 GMT 4933 Server: example-server 4934 Cache-Control: no-cache 4935 Pragma: no-cache 4936 Content-Type: application/yang.data+json 4938 { 4939 "example-events:events" : { 4940 "event" : [ 4941 { 4942 "name" : "interface-up", 4943 "description" : "Interface up notification count", 4944 "event-count" : 42 4945 }, 4946 { 4947 "name" : "interface-down", 4948 "description" : "Interface down notification count", 4949 "event-count" : 4 4950 } 4951 ] 4952 } 4953 } 4955 Example 2: content=config 4957 To retrieve only the configuration child resources, the "content" 4958 parameter is set to "config" or omitted since this is the default 4959 value. Note that the "ETag" and "Last-Modified" headers are only 4960 returned if the content parameter value is "config". 4962 GET /restconf/data/example-events:events?content=config 4963 HTTP/1.1 4964 Host: example.com 4965 Accept: application/yang.data+json 4967 The server might respond: 4969 HTTP/1.1 200 OK 4970 Date: Mon, 23 Apr 2012 17:11:30 GMT 4971 Server: example-server 4972 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4973 ETag: eeeada438af 4974 Cache-Control: no-cache 4975 Pragma: no-cache 4976 Content-Type: application/yang.data+json 4978 { 4979 "example-events:events" : { 4980 "event" : [ 4981 { 4982 "name" : "interface-up", 4983 "description" : "Interface up notification count" 4984 }, 4985 { 4986 "name" : "interface-down", 4987 "description" : "Interface down notification count" 4988 } 4989 ] 4990 } 4991 } 4993 Example 3: content=nonconfig 4995 To retrieve only the non-configuration child resources, the "content" 4996 parameter is set to "nonconfig". Note that configuration ancestors 4997 (if any) and list key leafs (if any) are also returned. The client 4998 might send: 5000 GET /restconf/data/example-events:events?content=nonconfig 5001 HTTP/1.1 5002 Host: example.com 5003 Accept: application/yang.data+json 5005 The server might respond: 5007 HTTP/1.1 200 OK 5008 Date: Mon, 23 Apr 2012 17:11:30 GMT 5009 Server: example-server 5010 Cache-Control: no-cache 5011 Pragma: no-cache 5012 Content-Type: application/yang.data+json 5014 { 5015 "example-events:events" : { 5016 "event" : [ 5017 { 5018 "name" : "interface-up", 5019 "event-count" : 42 5020 }, 5021 { 5022 "name" : "interface-down", 5023 "event-count" : 4 5024 } 5025 ] 5026 } 5027 } 5029 D.3.2. "depth" Parameter 5031 The "depth" parameter is used to limit the number of levels of child 5032 resources that are returned by the server for a GET method request. 5034 The depth parameter starts counting levels at the level of the target 5035 resource that is specified, so that a depth level of "1" includes 5036 just the target resource level itself. A depth level of "2" includes 5037 the target resource level and its child nodes. 5039 This example shows how different values of the "depth" parameter 5040 would affect the reply content for retrieval of the top-level 5041 "jukebox" data resource. 5043 Example 1: depth=unbounded 5045 To retrieve all the child resources, the "depth" parameter is not 5046 present or set to the default value "unbounded". Note that some 5047 strings are wrapped for display purposes only. 5049 GET /restconf/data/example-jukebox:jukebox?depth=unbounded 5050 HTTP/1.1 5051 Host: example.com 5052 Accept: application/yang.data+json 5054 The server might respond: 5056 HTTP/1.1 200 OK 5057 Date: Mon, 23 Apr 2012 17:11:30 GMT 5058 Server: example-server 5059 Cache-Control: no-cache 5060 Pragma: no-cache 5061 Content-Type: application/yang.data+json 5063 { 5064 "example-jukebox:jukebox" : { 5065 "library" : { 5066 "artist" : [ 5067 { 5068 "name" : "Foo Fighters", 5069 "album" : [ 5070 { 5071 "name" : "Wasting Light", 5072 "genre" : "example-jukebox:alternative", 5073 "year" : 2011, 5074 "song" : [ 5075 { 5076 "name" : "Wasting Light", 5077 "location" : 5078 "/media/foo/a7/wasting-light.mp3", 5079 "format" : "MP3", 5080 "length" " 286 5081 }, 5082 { 5083 "name" : "Rope", 5084 "location" : "/media/foo/a7/rope.mp3", 5085 "format" : "MP3", 5086 "length" " 259 5087 } 5088 ] 5089 } 5090 ] 5091 } 5092 ] 5093 }, 5094 "playlist" : [ 5095 { 5096 "name" : "Foo-One", 5097 "description" : "example playlist 1", 5098 "song" : [ 5099 { 5100 "index" : 1, 5101 "id" : "https://example.com/restconf/data/ 5102 example-jukebox:jukebox/library/artist= 5103 Foo%20Fighters/album=Wasting%20Light/ 5104 song=Rope" 5105 }, 5106 { 5107 "index" : 2, 5108 "id" : "https://example.com/restconf/data/ 5109 example-jukebox:jukebox/library/artist= 5110 Foo%20Fighters/album=Wasting%20Light/song= 5111 Bridge%20Burning" 5112 } 5113 ] 5114 } 5115 ], 5116 "player" : { 5117 "gap" : 0.5 5119 } 5120 } 5121 } 5123 Example 2: depth=1 5125 To determine if 1 or more resource instances exist for a given target 5126 resource, the value "1" is used. 5128 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 5129 Host: example.com 5130 Accept: application/yang.data+json 5132 The server might respond: 5134 HTTP/1.1 200 OK 5135 Date: Mon, 23 Apr 2012 17:11:30 GMT 5136 Server: example-server 5137 Cache-Control: no-cache 5138 Pragma: no-cache 5139 Content-Type: application/yang.data+json 5141 { 5142 "example-jukebox:jukebox" : {} 5143 } 5145 Example 3: depth=3 5147 To limit the depth level to the target resource plus 2 child resource 5148 layers the value "3" is used. 5150 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 5151 Host: example.com 5152 Accept: application/yang.data+json 5154 The server might respond: 5156 HTTP/1.1 200 OK 5157 Date: Mon, 23 Apr 2012 17:11:30 GMT 5158 Server: example-server 5159 Cache-Control: no-cache 5160 Pragma: no-cache 5161 Content-Type: application/yang.data+json 5163 { 5164 "example-jukebox:jukebox" : { 5165 "library" : { 5166 "artist" : {} 5168 }, 5169 "playlist" : [ 5170 { 5171 "name" : "Foo-One", 5172 "description" : "example playlist 1", 5173 "song" : {} 5174 } 5175 ], 5176 "player" : { 5177 "gap" : 0.5 5178 } 5179 } 5180 } 5182 D.3.3. "fields" Parameter 5184 In this example the client is retrieving the API resource, but 5185 retrieving only the "name" and "revision" nodes from each module, in 5186 JSON format: 5188 GET /restconf/data?fields=ietf-yang-library:modules/ 5189 module(name;revision) HTTP/1.1 5190 Host: example.com 5191 Accept: application/yang.data+json 5193 The server might respond as follows. 5195 HTTP/1.1 200 OK 5196 Date: Mon, 23 Apr 2012 17:01:00 GMT 5197 Server: example-server 5198 Content-Type: application/yang.data+json 5200 { 5201 "ietf-yang-library:modules": { 5202 "module": [ 5203 { 5204 "name" : "example-jukebox", 5205 "revision" : "2015-06-04" 5206 }, 5207 { 5208 "name" : "ietf-inet-types", 5209 "revision" : "2013-07-15" 5210 }, 5211 { 5212 "name" : "ietf-restconf-monitoring", 5213 "revision" : "2015-06-19" 5214 }, 5215 { 5216 "name" : "ietf-yang-library", 5217 "revision" : "2016-04-09" 5218 }, 5219 { 5220 "name" : "ietf-yang-types", 5221 "revision" : "2013-07-15" 5222 } 5224 ] 5225 } 5226 } 5228 D.3.4. "insert" Parameter 5230 In this example, a new first song entry in the "Foo-One" playlist is 5231 being created. 5233 Request from client: 5235 POST /restconf/data/example-jukebox:jukebox/ 5236 playlist=Foo-One?insert=first HTTP/1.1 5237 Host: example.com 5238 Content-Type: application/yang.data+json 5240 { 5241 "example-jukebox:song" : { 5242 "index" : 1, 5243 "id" : "/example-jukebox:jukebox/library/ 5244 artist=Foo%20Fighters/album=Wasting%20Light/song=Rope" 5245 } 5246 } 5248 Response from server: 5250 HTTP/1.1 201 Created 5251 Date: Mon, 23 Apr 2012 13:01:20 GMT 5252 Server: example-server 5253 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5254 Location: https://example.com/restconf/data/ 5255 example-jukebox:jukebox/playlist=Foo-One/song=1 5256 ETag: eeeada438af 5258 D.3.5. "point" Parameter 5260 In this example, the client is inserting a new "song" resource within 5261 an "album" resource after another song. The request URI is split for 5262 display purposes only. 5264 Request from client: 5266 POST /restconf/data/example-jukebox:jukebox/ 5267 library/artist=Foo%20Fighters/album=Wasting%20Light? 5268 insert=after&point=%2Fexample-jukebox%3Ajukebox%2F 5269 library%2Fartist%3DFoo%20Fighters%2Falbum%3D 5270 Wasting%20Light%2Fsong%3DBridge%20Burning HTTP/1.1 5271 Host: example.com 5272 Content-Type: application/yang.data+json 5274 { 5275 "example-jukebox:song" : { 5276 "name" : "Rope", 5277 "location" : "/media/foo/a7/rope.mp3", 5278 "format" : "MP3", 5279 "length" : 259 5280 } 5281 } 5283 Response from server: 5285 HTTP/1.1 204 No Content 5286 Date: Mon, 23 Apr 2012 13:01:20 GMT 5287 Server: example-server 5288 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5289 ETag: abcada438af 5291 D.3.6. "filter" Parameter 5293 The following URIs show some examples of notification filter 5294 specifications (lines wrapped for display purposes only): 5296 // filter = /event/event-class='fault' 5297 GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' 5299 // filter = /event/severity<=4 5300 GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 5302 // filter = /linkUp|/linkDown 5303 GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown 5305 // filter = /*/reporting-entity/card!='Ethernet0' 5306 GET /streams/NETCONF? 5307 filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' 5309 // filter = /*/email-addr[contains(.,'company.com')] 5310 GET /streams/critical-syslog? 5311 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 5313 // Note: the module name is used as prefix. 5314 // filter = (/example-mod:event1/name='joe' and 5315 // /example-mod:event1/status='online') 5316 GET /streams/NETCONF? 5317 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and 5318 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 5320 // To get notifications from just two modules (e.g., m1 + m2) 5321 // filter=(/m1:* or /m2:*) 5322 GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*) 5324 D.3.7. "start-time" Parameter 5326 // start-time = 2014-10-25T10:02:00Z 5327 GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z 5329 D.3.8. "stop-time" Parameter 5331 // stop-time = 2014-10-25T12:31:00Z 5332 GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z 5334 D.3.9. "with-defaults" Parameter 5336 The following YANG module is assumed for this example. 5338 module example-interface { 5339 prefix "exif"; 5340 namespace "urn:example.com:params:xml:ns:yang:example-interface"; 5342 container interfaces { 5343 list interface { 5344 key name; 5345 leaf name { type string; } 5346 leaf mtu { type uint32; } 5347 leaf status { 5348 config false; 5349 type enumeration { 5350 enum up; 5351 enum down; 5352 enum testing; 5353 } 5354 } 5355 } 5356 } 5357 } 5359 Assume the same data model as defined in Appendix A.1 of [RFC6243]. 5360 Assume the same data set as defined in Appendix A.2 of [RFC6243]. If 5361 the server defaults-uri basic-mode is "trim", the the following 5362 request for interface "eth1" might be as follows: 5364 Without query parameter: 5366 GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1 5367 Host: example.com 5368 Accept: application/yang.data+json 5370 The server might respond as follows. 5372 HTTP/1.1 200 OK 5373 Date: Mon, 23 Apr 2012 17:01:00 GMT 5374 Server: example-server 5375 Content-Type: application/yang.data+json 5377 { 5378 "example:interface": [ 5379 { 5380 "name" : "eth1", 5381 "status" : "up" 5382 } 5383 ] 5384 } 5386 Note that the "mtu" leaf is missing because it is set to the default 5387 "1500", and the server defaults handling basic-mode is "trim". 5389 With query parameter: 5391 GET /restconf/data/example:interfaces/interface=eth1 5392 ?with-defaults=report-all HTTP/1.1 5393 Host: example.com 5394 Accept: application/yang.data+json 5396 The server might respond as follows. 5398 HTTP/1.1 200 OK 5399 Date: Mon, 23 Apr 2012 17:01:00 GMT 5400 Server: example-server 5401 Content-Type: application/yang.data+json 5403 { 5404 "example:interface": [ 5405 { 5406 "name" : "eth1", 5407 "mtu" : 1500, 5408 "status" : "up" 5410 } 5411 ] 5412 } 5414 Note that the server returns the "mtu" leaf because the "report-all" 5415 mode was requested with the "with-defaults" query parameter. 5417 Authors' Addresses 5419 Andy Bierman 5420 YumaWorks 5422 Email: andy@yumaworks.com 5424 Martin Bjorklund 5425 Tail-f Systems 5427 Email: mbj@tail-f.com 5429 Kent Watsen 5430 Juniper Networks 5432 Email: kwatsen@juniper.net