idnits 2.17.1 draft-ietf-netconf-restconf-10.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 2368 has weird spacing: '... method entry...' == Line 3287 has weird spacing: '...ncoding strin...' == Line 3288 has weird spacing: '...ocation inet:...' == Line 4292 has weird spacing: '...ocation str...' == Line 4302 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 PUT method MUST not change the value of the leaf-list instance. == 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 (March 16, 2016) is 2961 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-01 == 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 (~~), 15 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: September 17, 2016 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 March 16, 2016 10 RESTCONF Protocol 11 draft-ietf-netconf-restconf-10 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 September 17, 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 . . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 55 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 6 56 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6 57 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7 58 1.1.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 59 1.1.5. URI Template . . . . . . . . . . . . . . . . . . . . 9 60 1.1.6. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 9 61 1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 9 62 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 10 63 1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 11 64 1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 12 65 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 13 66 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 13 67 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 13 68 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 13 69 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 14 70 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 14 71 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 14 72 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 15 73 3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 17 74 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 17 75 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 18 76 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 18 77 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19 78 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 19 79 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20 80 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21 81 3.5.1. Encoding Data Resource Identifiers in the Request URI 22 82 3.5.2. Defaults Handling . . . . . . . . . . . . . . . . . . 25 83 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 25 84 3.6.1. Encoding Operation Resource Input Parameters . . . . 26 85 3.6.2. Encoding Operation Resource Output Parameters . . . . 29 86 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 31 87 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 32 88 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 33 89 3.9. Errors Media Type . . . . . . . . . . . . . . . . . . . . 33 90 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 34 91 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 35 92 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 35 93 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 94 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 37 95 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 37 96 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 38 97 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 98 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 41 99 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 41 100 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 42 101 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 43 102 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 44 103 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 45 104 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 45 105 4.8.4. The "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. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 85 150 A.2. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 87 151 A.3. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 88 152 A.4. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 88 153 A.5. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 88 154 A.6. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 88 155 A.7. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 89 156 A.8. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 90 157 A.9. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 90 158 A.10. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 91 159 A.11. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 92 160 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 92 161 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 92 162 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 93 163 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 98 164 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 99 165 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 99 166 D.1.2. Retrieve The Server Module Information . . . . . . . 100 167 D.1.3. Retrieve The Server Capability Information . . . . . 101 168 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 102 169 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 102 170 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 103 171 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 104 172 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 104 173 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 104 174 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 107 175 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 110 176 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 111 177 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 112 178 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 113 179 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 113 180 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 113 181 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 114 182 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 115 184 1. Introduction 185 There is a need for standard mechanisms to allow Web applications to 186 access the configuration data, operational data, data-model specific 187 protocol operations, and event notifications within a networking 188 device, in a modular and extensible manner. 190 This document defines an HTTP [RFC7230] based protocol called 191 RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or 192 YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using datastores 193 defined in NETCONF [RFC6241]. 195 NETCONF defines configuration datastores and a set of Create, 196 Retrieve, Update, Delete (CRUD) operations that can be used to access 197 these datastores. The YANG language defines the syntax and semantics 198 of datastore content, operational data, protocol operations, and 199 event notifications. 201 RESTCONF uses HTTP operations to provide CRUD operations on a 202 conceptual datastore containing YANG-defined data, which is 203 compatible with a server which implements NETCONF datastores. 205 If a RESTCONF server is co-located with a NETCONF server, then there 206 are protocol interactions to be considered, as described in 207 Section 1.4. The server MAY provide access to specific datastores 208 using operation resources, as described in Section 3.6. 210 Configuration data and state data are exposed as resources that can 211 be retrieved with the GET method. Resources representing 212 configuration data can be modified with the DELETE, PATCH, POST, and 213 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 214 or JSON [RFC7159]. 216 Data-model specific operations defined with the YANG "rpc" or 217 "action" statements can be invoked with the POST method. Data-model 218 specific event notifications defined with the YANG "notification" 219 statement can be accessed. 221 1.1. Terminology 223 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 224 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 225 "OPTIONAL" in this document are to be interpreted as described in BCP 226 14, [RFC2119]. 228 1.1.1. NETCONF 230 The following terms are defined in [RFC6241]: 232 o candidate configuration datastore 234 o client 236 o configuration data 238 o datastore 240 o configuration datastore 242 o protocol operation 244 o running configuration datastore 246 o server 248 o startup configuration datastore 250 o state data 252 o user 254 1.1.2. HTTP 256 The following terms are defined in [RFC3986]: 258 o fragment 260 o path 262 o query 264 The following terms are defined in [RFC7230]: 266 o header 268 o message-body 270 o request-line 272 o request URI 274 o status-line 275 The following terms are defined in [RFC7231]: 277 o method 279 o request 281 o resource 283 The following terms are defined in [RFC7232]: 285 o entity tag 287 1.1.3. YANG 289 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 291 o action 293 o container 295 o data node 297 o key leaf 299 o leaf 301 o leaf-list 303 o list 305 o non-presence container (or NP-container) 307 o ordered-by system 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. 422 RESTCONF achieves this by implementing a subset of the interaction 423 capabilities provided by the NETCONF protocol, for instance, by 424 eliminating datastores and explicit locking. 426 RESTCONF uses HTTP methods to implement the equivalent of NETCONF 427 operations, enabling basic CRUD operations on a hierarchy of 428 conceptual resources. 430 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 431 resources represented by YANG data models. These basic edit 432 operations allow the running configuration to be altered in an all- 433 or-none fashion. 435 RESTCONF is not intended to replace NETCONF, but rather provide an 436 additional interface that follows Representational State Transfer 437 (REST) principles and is compatible with a resource-oriented device 438 abstraction. 440 The following figure shows the system components if a RESTCONF server 441 is co-located with a NETCONF server: 443 +-----------+ +-----------------+ 444 | Web app | <-------> | | 445 +-----------+ HTTP | network device | 446 | | 447 +-----------+ | +-----------+ | 448 | NMS app | <-------> | | datastore | | 449 +-----------+ NETCONF | +-----------+ | 450 +-----------------+ 452 The following figure shows the system components if a RESTCONF server 453 is implemented in a device that does not have a NETCONF server: 455 +-----------+ +-----------------+ 456 | Web app | <-------> | | 457 +-----------+ HTTP | network device | 458 | | 459 +-----------------+ 461 1.3. Data Model Driven API 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 automatically copies the 516 content of running to startup after running has been updated as a 517 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 557 RESTCONF also supports a server-defined list of optional 558 capabilities, which are listed by a server using the 559 "ietf-restconf-monitoring" module defined in Section 9.3. For 560 example, this document defines several query parameters in 561 Section 4.8. Each optional parameter has a corresponding capability 562 URI defined in Section 9.1.1 that is advertised by the server if 563 supported. 565 The "capabilities" list can identify any sort of server extension. 566 Typically this extension mechanism is used to identify optional query 567 parameters but it is not limited to that purpose. For example, the 568 "defaults" URI defined in Section 9.1.2 specifies a mandatory URI 569 identifying server defaults handling behavior. 571 A new sub-resource type could be identified with a capability if it 572 is optional to implement. Mandatory protocol features and new 573 resource types require a new revision of the RESTCONF protocol. 575 2. Transport Protocol Requirements 577 2.1. Integrity and Confidentiality 579 HTTP [RFC7230] is an application layer protocol that may be layered 580 on any reliable transport-layer protocol. RESTCONF is defined on top 581 of HTTP, but due to the sensitive nature of the information conveyed, 582 RESTCONF requires that the transport-layer protocol provides both 583 data integrity and confidentiality. A RESTCONF server MUST support 584 the TLS protocol [RFC5246]. The RESTCONF protocol MUST NOT be used 585 over HTTP without using the TLS protocol. 587 HTTP/1.1 pipelining MUST be supported by the server. Responses MUST 588 be sent in the same order that requests are received. No other 589 versions of HTTP are supported for use with RESTCONF. 591 2.2. HTTPS with X.509v3 Certificates 593 Given the nearly ubiquitous support for HTTP over TLS [RFC7230], 594 RESTCONF implementations MUST support the "https" URI scheme, which 595 has the IANA assigned default port 443. 597 RESTCONF servers MUST present an X.509v3 based certificate when 598 establishing a TLS connection with a RESTCONF client. The exclusive 599 use the X.509v3 based certificates is consistent with NETCONF over 600 TLS [RFC7589]. 602 2.3. Certificate Validation 603 The RESTCONF client MUST use X.509 certificate path validation 604 [RFC5280] to verify the integrity of the RESTCONF server's TLS 605 certificate. The presented X.509 certificate MUST also be considered 606 valid if it matches a locally configured certificate fingerprint. If 607 X.509 certificate path validation fails and the presented X.509 608 certificate does not match a locally configured certificate 609 fingerprint, the connection MUST be terminated as defined in 610 [RFC5246]. 612 2.4. Authenticated Server Identity 614 The RESTCONF client MUST check the identity of the server according 615 to Section 6 of [RFC6125], including processing the outcome as 616 described in Section 6.6 of [RFC6125]. 618 2.5. Authenticated Client Identity 620 The RESTCONF server MUST authenticate client access to any protected 621 resource. If the RESTCONF client is not authorized to access a 622 resource, the server MUST send an HTTP response with "401 623 Unauthorized" status-line, as defined in Section 3.1 of [RFC7235]. 625 To authenticate a client, a RESTCONF server MUST use TLS based client 626 certificates (Section 7.4.6 of [RFC5246]), or MUST use any HTTP 627 authentication scheme defined in the HTTP Authentication Scheme 628 Registry (Section 5.1 in [RFC7235]). A server MAY also support the 629 combination of both client certificates and an HTTP client 630 authentication scheme, with the determination of how to process this 631 combination left as an implementation decision. 633 The RESTCONF client identity derived from the authentication 634 mechanism used is hereafter known as the "RESTCONF username" and 635 subject to the NETCONF Access Control Module (NACM) [RFC6536]. When 636 a client certificate is presented, the RESTCONF username MUST be 637 derived using the algorithm defined in Section 7 of [RFC7589]. For 638 all other cases, when HTTP authentication is used, the RESTCONF 639 username MUST be provided by the HTTP authentication scheme used. 641 3. Resources 643 The RESTCONF protocol operates on a hierarchy of resources, starting 644 with the top-level API resource itself (Section 3.1). Each resource 645 represents a manageable component within the device. 647 A resource can be considered a collection of data and the set of 648 allowed methods on that data. It can contain nested child resources. 649 The child resource types and methods allowed on them are data-model 650 specific. 652 A resource has a media type identifier, represented by the 653 "Content-Type" header in the HTTP response message. A resource can 654 contain zero or more nested resources. A resource can be created and 655 deleted independently of its parent resource, as long as the parent 656 resource exists. 658 All RESTCONF resource types are defined in this document except 659 specific datastore contents, protocol operations, and event 660 notifications. The syntax and semantics for these resource types are 661 defined in YANG modules. 663 The RESTCONF resources are accessed via a set of URIs defined in this 664 document. The set of YANG modules supported by the server will 665 determine the data model specific operations, top-level data nodes, 666 and event notification messages supported by the server. 668 The RESTCONF protocol does not include a data resource discovery 669 mechanism. Instead, the definitions within the YANG modules 670 advertised by the server are used to construct a predictable 671 operation or data resource identifier. 673 3.1. Root Resource Discovery 675 In line with the best practices defined by [RFC7320], RESTCONF 676 enables deployments to specify where the RESTCONF API is located. 677 When first connecting to a RESTCONF server, a RESTCONF client MUST 678 determine the root of the RESTCONF API. The client discovers this by 679 getting the "/.well-known/host-meta" resource ([RFC6415]) and using 680 the element containing the "restconf" attribute : 682 Example returning /restconf: 684 Request 685 ------- 686 GET /.well-known/host-meta HTTP/1.1 687 Host: example.com 688 Accept: application/xrd+xml 690 Response 691 -------- 692 HTTP/1.1 200 OK 693 Content-Type: application/xrd+xml 694 Content-Length: nnn 696 697 698 699 After discovering the RESTCONF API root, the client MUST prepend it 700 to any subsequent request to a RESTCONF resource. In this example, 701 the client would use the path "/restconf" as the RESTCONF entry 702 point. 704 Example returning /top/restconf: 706 Request 707 ------- 708 GET /.well-known/host-meta HTTP/1.1 709 Host: example.com 710 Accept: application/xrd+xml 712 Response 713 -------- 714 HTTP/1.1 200 OK 715 Content-Type: application/xrd+xml 716 Content-Length: nnn 718 719 720 722 In this example, the client would use the path "/top/restconf" as the 723 RESTCONF entry point. 725 The client can now determine the operation resources supported by the 726 the server. In this example a custom "play" operation is supported: 728 Request 729 ------- 730 GET /top/restconf/operations HTTP/1.1 731 Host: example.com 732 Accept: application/yang.api+json 734 Response 735 -------- 736 HTTP/1.1 200 OK 737 Date: Mon, 23 Apr 2012 17:01:00 GMT 738 Server: example-server 739 Cache-Control: no-cache 740 Pragma: no-cache 741 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 742 Content-Type: application/yang.api+json 744 { "operations" : { "example-jukebox:play" : {} } } 746 If the XRD contains more than one link relation, then only the 747 relation named "restconf" is relevant to this specification. 749 3.2. RESTCONF Media Types 751 The RESTCONF protocol defines a set of application specific media 752 types to identify each of the available resource types. The 753 following resource types are defined in RESTCONF: 755 +-----------+---------------------------------+ 756 | Resource | Media Type | 757 +-----------+---------------------------------+ 758 | API | application/yang.api+xml | 759 | | application/yang.api+json | 760 | Datastore | application/yang.datastore+xml | 761 | | application/yang.datastore+json | 762 | Data | application/yang.data+xml | 763 | | application/yang.data+json | 764 | [none] | application/yang.errors+xml | 765 | | application/yang.errors+json | 766 | Operation | application/yang.operation+xml | 767 | | application/yang.operation+json | 768 | Schema | application/yang | 769 +-----------+---------------------------------+ 771 RESTCONF Media Types 773 3.3. API Resource 775 The API resource contains the entry points for the RESTCONF datastore 776 and operation resources. It is the top-level resource located at 777 {+restconf} and has the media type "application/yang.api+xml" or 778 "application/yang.api+json". 780 YANG Tree Diagram for an API Resource: 782 +--rw restconf 783 +--rw data 784 +--rw operations 785 +--ro yang-library-version 787 The "application/yang.api" restconf-media-type extension in the 788 "ietf-restconf" module defined in Section 8 is used to specify the 789 structure and syntax of the conceptual child resources within the API 790 resource. 792 The API resource can be retrieved with the GET method. 794 This resource has the following child resources: 796 +----------------------+--------------------------------+ 797 | Child Resource | Description | 798 +----------------------+--------------------------------+ 799 | data | Contains all data resources | 800 | operations | Data-model specific operations | 801 | yang-library-version | ietf-yang-library module date | 802 +----------------------+--------------------------------+ 804 RESTCONF API Resource 806 3.3.1. {+restconf}/data 808 This mandatory resource represents the combined configuration and 809 operational data resources that can be accessed by a client. It 810 cannot be created or deleted by the client. The datastore resource 811 type is defined in Section 3.4. 813 Example: 815 This example request by the client would retrieve only the non- 816 configuration data nodes that exist within the "library" resource, 817 using the "content" query parameter (see Section 4.8.1). 819 GET /restconf/data/example-jukebox:jukebox/library 820 ?content=nonconfig HTTP/1.1 821 Host: example.com 822 Accept: application/yang.data+xml 824 The server might respond: 826 HTTP/1.1 200 OK 827 Date: Mon, 23 Apr 2012 17:01:30 GMT 828 Server: example-server 829 Cache-Control: no-cache 830 Pragma: no-cache 831 Content-Type: application/yang.data+xml 833 834 42 835 59 836 374 837 839 3.3.2. {+restconf}/operations 840 This optional resource is a container that provides access to the 841 data-model specific protocol operations supported by the server. The 842 server MAY omit this resource if no data-model specific operations 843 are advertised. 845 Any data-model specific protocol operations defined in the YANG 846 modules advertised by the server MUST be available as child nodes of 847 this resource. 849 Operation resources are defined in Section 3.6. 851 3.3.3. {+restconf}/yang-library-version 853 This mandatory leaf identifies the revision date of the 854 "ietf-yang-library" YANG module that is implemented by this server. 856 Example: 858 GET /restconf/yang-library-version HTTP/1.1 859 Host: example.com 860 Accept: application/yang.data+xml 862 The server might respond (response wrapped for display purposes): 864 HTTP/1.1 200 OK 865 Date: Mon, 23 Apr 2012 17:01:30 GMT 866 Server: example-server 867 Cache-Control: no-cache 868 Pragma: no-cache 869 Content-Type: application/yang.data+xml 871 873 2016-02-01 874 876 3.4. Datastore Resource 878 The "{+restconf}/data" subtree represents the datastore resource 879 type, which is a collection of configuration and operational data 880 nodes. 882 This resource type is an abstraction of the system's underlying 883 datastore implementation. It is used to simplify resource editing 884 for the client. The RESTCONF datastore resource is a conceptual 885 collection of all configuration and operational data that is present 886 on the device. 888 Configuration edit transaction management and configuration 889 persistence are handled by the server and not controlled by the 890 client. A datastore resource can be written directly with the POST 891 and PATCH methods. Each RESTCONF edit of a datastore resource is 892 saved to non-volatile storage by the server. 894 3.4.1. Edit Collision Detection 896 Two "edit collision detection" mechanisms are provided in RESTCONF, 897 for datastore and data resources. 899 3.4.1.1. Timestamp 901 The last change time is maintained and the "Last-Modified" 902 ([RFC7232], Section 2.2) header is returned in the response for a 903 retrieval request. The "If-Unmodified-Since" header can be used in 904 edit operation requests to cause the server to reject the request if 905 the resource has been modified since the specified timestamp. 907 The server MUST maintain a last-modified timestamp for the top-level 908 {+restconf}/data resource. This timestamp is only affected by 909 configuration data resources, and MUST NOT be updated for changes to 910 non-configuration data. 912 3.4.1.2. Entity tag 914 A unique opaque string is maintained and the "ETag" ([RFC7232], 915 Section 2.3) header is returned in the response for a retrieval 916 request. The "If-Match" header can be used in edit operation 917 requests to cause the server to reject the request if the resource 918 entity tag does not match the specified value. 920 The server MUST maintain an entity tag for the top-level {+restconf}/ 921 data resource. This entity tag is only affected by configuration 922 data resources, and MUST NOT be updated for changes to non- 923 configuration data. 925 3.4.1.3. Update Procedure 927 Changes to configuration data resources affect the timestamp and 928 entity tag to that resource, any ancestor data resources, and the 929 datastore resource. 931 For example, an edit to disable an interface might be done by setting 932 the leaf "/interfaces/interface/enabled" to "false". The "enabled" 933 data node and its ancestors (one "interface" list instance, and the 934 "interfaces" container) are considered to be changed. The datastore 935 is considered to be changed when any top-level configuration data 936 node is changed (e.g., "interfaces"). 938 3.5. Data Resource 940 A data resource represents a YANG data node that is a descendant node 941 of a datastore resource. Each YANG-defined data node can be uniquely 942 targeted by the request-line of an HTTP operation. Containers, 943 leafs, leaf-list entries, list entries, anydata and anyxml nodes are 944 data resources. 946 The representation maintained for each data resource is the YANG 947 defined subtree for that node. HTTP operations on a data resource 948 affect both the targeted data node and all its descendants, if any. 950 For configuration data resources, the server SHOULD maintain a last- 951 modified timestamp for the resource, and return the "Last-Modified" 952 header when it is retrieved with the GET or HEAD methods. If 953 maintained, the resource timestamp MUST be set to the current time 954 whenever the resource or any configuration resource within the 955 resource is altered. If not maintained, then the resource timestamp 956 for the datastore MUST be used instead. 958 This timestamp is only affected by configuration data resources, and 959 MUST NOT be updated for changes to non-configuration data. 961 For configuration data resources, the server SHOULD maintain a 962 resource entity tag for the resource, and return the "ETag" header 963 when it is retrieved as the target resource with the GET or HEAD 964 methods. If maintained, the resource entity tag MUST be updated 965 whenever the resource or any configuration resource within the 966 resource is altered. If not maintained, then the resource entity tag 967 for the datastore MUST be used instead. 969 This entity tag is only affected by configuration data resources, and 970 MUST NOT be updated for changes to non-configuration data. 972 A data resource can be retrieved with the GET method. Data resources 973 are accessed via the "{+restconf}/data" entry point. This sub-tree 974 is used to retrieve and edit data resources. 976 A configuration data resource can be altered by the client with some 977 or all of the edit operations, depending on the target resource and 978 the specific operation. Refer to Section 4 for more details on edit 979 operations. 981 The resource definition version for a data resource is identified by 982 the revision date of the YANG module containing the YANG definition 983 for the data resource. 985 3.5.1. Encoding Data Resource Identifiers in the Request URI 987 In YANG, data nodes are named with an absolute XPath expression, 988 defined in [XPath], starting from the document root to the target 989 resource. In RESTCONF, URL encoded path expressions are used 990 instead. 992 A predictable location for a data resource is important, since 993 applications will code to the YANG data model module, which uses 994 static naming and defines an absolute path location for all data 995 nodes. 997 A RESTCONF data resource identifier is not an XPath expression. It 998 is encoded from left to right, starting with the top-level data node, 999 according to the "api-path" rule in Section 3.5.1.1. The node name 1000 of each ancestor of the target resource node is encoded in order, 1001 ending with the node name for the target resource. If a node in the 1002 path is defined in another module than its parent node, then module 1003 name followed by a colon character (":") is prepended to the node 1004 name in the resource identifier. See Section 3.5.1.1 for details. 1006 If a data node in the path expression is a YANG leaf-list node, then 1007 the leaf-list value MUST be encoded according to the following rules: 1009 o The instance-identifier for the leaf-list MUST be encoded using 1010 one path segment [RFC3986]. 1012 o The path segment is constructed by having the leaf-list name, 1013 followed by an "=" character, followed by the leaf-list value. 1014 (e.g., /restconf/data/top-leaflist=fred). 1016 If a data node in the path expression is a YANG list node, then the 1017 key values for the list (if any) MUST be encoded according to the 1018 following rules: 1020 o The key leaf values for a data resource representing a YANG list 1021 MUST be encoded using one path segment [RFC3986]. 1023 o If there is only one key leaf value, the path segment is 1024 constructed by having the list name, followed by an "=" character, 1025 followed by the single key leaf value. 1027 o If there are multiple key leaf values, the path segment is 1028 constructed by having the list name, followed by the value of each 1029 leaf identified in the "key" statement, encoded in the order 1030 specified in the YANG "key" statement. Each key leaf value except 1031 the last one is followed by a comma character. 1033 o The key value is specified as a string, using the canonical 1034 representation for the YANG data type. Any reserved characters 1035 MUST be percent-encoded, according to [RFC3986], section 2.1. 1037 o All the components in the "key" statement MUST be encoded. 1038 Partial instance identifiers are not supported. 1040 o Since missing key values are not allowed, two consecutive commas 1041 are interpreted as a zero-length string. (example: 1042 list=foo,,baz). 1044 o The "list-instance" ABNF rule defined in Section 3.5.1.1 1045 represents the syntax of a list instance identifier. 1047 o Resource URI values returned in Location headers for data 1048 resources MUST identify the module name, even if there are no 1049 conflicting local names when the resource is created. This 1050 ensures the correct resource will be identified even if the server 1051 loads a new module that the old client does not know about. 1053 Examples: 1055 container top { 1056 list list1 { 1057 key "key1 key2 key3"; 1058 ... 1059 list list2 { 1060 key "key4 key5"; 1061 ... 1062 leaf X { type string; } 1063 } 1064 } 1065 leaf-list Y { 1066 type uint32; 1067 } 1068 } 1070 For the above YANG definition, a target resource URI for leaf "X" 1071 would be encoded as follows (line wrapped for display purposes only): 1073 /restconf/data/example-top:top/list1=key1,key2,key3/ 1074 list2=key4,key5/X 1076 For the above YANG definition, a target resource URI for leaf-list 1077 "Y" would be encoded as follows: 1079 /restconf/data/example-top:top/Y=instance-value 1081 The following example shows how reserved characters are percent- 1082 encoded within a key value. The value of "key1" contains a comma, 1083 single-quote, double-quote, colon, double-quote, space, and forward 1084 slash. (,'":" /). Note that double-quote is not a reserved 1085 characters and does not need to be percent-encoded. The value of 1086 "key2" is the empty string, and the value of "key3" is the string 1087 "foo". 1089 Example URL: 1091 /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo 1093 3.5.1.1. ABNF For Data Resource Identifiers 1095 The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to 1096 construct RESTCONF path identifiers: 1098 api-path = "/" | 1099 ("/" api-identifier 1100 0*("/" (api-identifier | list-instance ))) 1102 api-identifier = [module-name ":"] identifier ;; note 1 1104 module-name = identifier 1106 list-instance = api-identifier "=" key-value ["," key-value]* 1108 key-value = string ;; note 1 1110 string = 1112 ;; An identifier MUST NOT start with 1113 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 1114 identifier = (ALPHA / "_") 1115 *(ALPHA / DIGIT / "_" / "-" / ".") 1117 Note 1: The syntax for "api-identifier" and "key-value" MUST conform 1118 to the JSON identifier encoding rules in Section 4 of 1119 [I-D.ietf-netmod-yang-json]. 1121 3.5.2. Defaults Handling 1123 RESTCONF requires that a server report its default handling mode (see 1124 Section 9.1.2 for details). If the optional "with-defaults" query 1125 parameter is supported by the server, a client may use it to control 1126 retrieval of default values (see Section 4.8.9 for details). 1128 If a leaf or leaf-list is missing from the configuration and there is 1129 a YANG-defined default for that data resource, then the server MUST 1130 use the YANG-defined default as the configured value. 1132 If the target of a GET method is a data node that represents a leaf 1133 that has a default value, and the leaf has not been given a value 1134 yet, the server MUST return the default value that is in use by the 1135 server. 1137 If the target of a GET method is a data node that represents a 1138 container or list that has any child resources with default values, 1139 for the child resources that have not been given value yet, the 1140 server MAY return the default values that are in use by the server, 1141 in accordance with its reported default handing mode and query 1142 parameters passed by the client. 1144 3.6. Operation Resource 1146 An operation resource represents a protocol operation defined with 1147 the YANG "rpc" statement or a data-model specific action defined with 1148 a YANG "action" statement. It is invoked using a POST method on the 1149 operation resource. 1151 An RPC operation is invoked as: 1153 POST {+restconf}/operations/ 1155 The field identifies the module name and rpc identifier 1156 string for the desired operation. 1158 For example, if "module-A" defined a "reset" rpc operation, then 1159 invoking the operation from "module-A" would be requested as follows: 1161 POST /restconf/operations/module-A:reset HTTP/1.1 1162 Server example.com 1164 An action is invoked as: 1166 POST {+restconf}/data// 1168 where contains the path to the data node 1169 where the action is defined, and is the name of the action. 1171 For example, if "module-A" defined a "reset-all" action in the 1172 container "interfaces", then invoking this action would be requested 1173 as follows: 1175 POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 1176 Server example.com 1178 If the "rpc" or "action" statement has an "input" section, then a 1179 message-body MAY be sent by the client in the request, otherwise the 1180 request message MUST NOT include a message-body. If the "input" 1181 section contains mandatory parameters, then a message-body MUST be 1182 sent by the client. 1184 If the operation is invoked without errors, and if the "rpc" or 1185 "action" statement has an "output" section, then a message-body MAY 1186 be sent by the server in the response, otherwise the response message 1187 MUST NOT include a message-body in the response message, and MUST 1188 send a "204 No Content" status-line instead. 1190 If the operation input is not valid, or the operation is invoked but 1191 errors occur, then a message-body MUST be sent by the server, 1192 containing an "errors" resource, as defined in Section 3.9. A 1193 detailed example of an operation resource error response can be found 1194 in Section 3.6.3. 1196 All operation resources representing RPC operations supported by the 1197 server MUST be identified in the {+restconf}/operations subtree 1198 defined in Section 3.3.2. Operation resources representing YANG 1199 actions are not identified in this subtree since they are invoked 1200 using a URI within the {+restconf}/data subtree. 1202 3.6.1. Encoding Operation Resource Input Parameters 1204 If the "rpc" or "action" statement has an "input" section, then the 1205 "input" node is provided in the message-body, corresponding to the 1206 YANG data definition statements within the "input" section. 1208 Examples: 1210 The following YANG module is used for the RPC operation examples in 1211 this section. 1213 module example-ops { 1214 namespace "https://example.com/ns/example-ops"; 1215 prefix "ops"; 1216 revision "2016-03-10"; 1218 rpc reboot { 1219 input { 1220 leaf delay { 1221 units seconds; 1222 type uint32; 1223 default 0; 1224 } 1225 leaf message { type string; } 1226 leaf language { type string; } 1227 } 1228 } 1230 rpc get-reboot-info { 1231 output { 1232 leaf reboot-time { 1233 units seconds; 1234 type uint32; 1235 } 1236 leaf message { type string; } 1237 leaf language { type string; } 1238 } 1239 } 1240 } 1242 The following YANG module is used for the YANG action examples in 1243 this section. 1245 module example-actions { 1246 yang-version 1.1; 1247 namespace "https://example.com/ns/example-actions"; 1248 prefix "act"; 1249 import ietf-yang-types { prefix yang; } 1250 revision "2016-03-10"; 1252 container interfaces { 1253 list interface { 1254 key name; 1255 leaf name { type string; } 1257 action reset { 1258 input { 1259 leaf delay { 1260 units seconds; 1261 type uint32; 1262 default 0; 1263 } 1264 } 1265 } 1267 action get-last-reset-time { 1268 output { 1269 leaf last-reset { 1270 type yang:date-and-time; 1271 mandatory true; 1272 } 1273 } 1274 } 1275 } 1276 } 1278 } 1280 RPC Input Example: 1282 The client might send the following POST request message to invoke 1283 the "reboot" RPC operation: 1285 POST /restconf/operations/example-ops:reboot HTTP/1.1 1286 Host: example.com 1287 Content-Type: application/yang.operation+xml 1289 1290 600 1291 Going down for system maintenance 1292 en-US 1293 1295 The server might respond: 1297 HTTP/1.1 204 No Content 1298 Date: Mon, 25 Apr 2012 11:01:00 GMT 1299 Server: example-server 1301 The same example request message is shown here using JSON encoding: 1303 POST /restconf/operations/example-ops:reboot HTTP/1.1 1304 Host: example.com 1305 Content-Type: application/yang.operation+json 1306 { 1307 "example-ops:input" : { 1308 "delay" : 600, 1309 "message" : "Going down for system maintenance", 1310 "language" : "en-US" 1311 } 1312 } 1314 Action Input Example: 1316 The client might send the following POST request message to invoke 1317 the "reset" action (text wrap for display purposes): 1319 POST /restconf/data/example-actions:interfaces/interface=eth0 1320 /reset HTTP/1.1 1321 Host: example.com 1322 Content-Type: application/yang.operation+xml 1324 1325 600 1326 1328 The server might respond: 1330 HTTP/1.1 204 No Content 1331 Date: Mon, 25 Apr 2012 11:01:00 GMT 1332 Server: example-server 1334 The same example request message is shown here using JSON encoding 1335 (text wrap for display purposes): 1337 POST /restconf/data/example-action:interfaces/interface=eth0 1338 /reset HTTP/1.1 1339 Host: example.com 1340 Content-Type: application/yang.operation+json 1342 { "example-action:input" : { 1343 "delay" : 600 1344 } 1345 } 1347 3.6.2. Encoding Operation Resource Output Parameters 1349 If the "rpc" or "action" statement has an "output" section, then the 1350 "output" node is provided in the message-body, corresponding to the 1351 YANG data definition statements within the "output" section. 1353 Examples: 1355 RPC Output Example: 1357 The "example-ops" YANG module defined in Section 3.6.1 is used for 1358 this example. 1360 The client might send the following POST request message to invoke 1361 the "get-reboot-info" operation: 1363 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 1364 Host: example.com 1365 Accept: application/yang.operation+json 1367 The server might respond: 1369 HTTP/1.1 200 OK 1370 Date: Mon, 25 Apr 2012 11:10:30 GMT 1371 Server: example-server 1372 Content-Type: application/yang.operation+json 1374 { 1375 "example-ops:output" : { 1376 "reboot-time" : 30, 1377 "message" : "Going down for system maintenance", 1378 "language" : "en-US" 1379 } 1380 } 1382 The same response is shown here using XML encoding: 1384 HTTP/1.1 200 OK 1385 Date: Mon, 25 Apr 2012 11:10:30 GMT 1386 Server: example-server 1387 Content-Type: application/yang.operation+xml 1389 1390 30 1391 Going down for system maintenance 1392 en-US 1393 1395 Action Output Example: 1397 The "example-actions" YANG module defined in Section 3.6.1 is used 1398 for this example. 1400 The client might send the following POST request message to invoke 1401 the "get-last-reset-time" action: 1403 POST /restconf/data/example-actions:interfaces/interface=eth0 1404 /get-last-reset-time HTTP/1.1 1405 Host: example.com 1406 Accept: application/yang.operation+json 1408 The server might respond: 1410 HTTP/1.1 200 OK 1411 Date: Mon, 25 Apr 2012 11:10:30 GMT 1412 Server: example-server 1413 Content-Type: application/yang.operation+json 1415 { 1416 "example-actions:output" : { 1417 "last-reset" : "2015-10-10T02:14:11Z" 1418 } 1419 } 1421 3.6.3. Encoding Operation Resource Errors 1423 If any errors occur while attempting to invoke the operation or 1424 action, then an "errors" media type is returned with the appropriate 1425 error status. 1427 Using the "reboot" operation from the example in Section 3.6.1, the 1428 client might send the following POST request message: 1430 POST /restconf/operations/example-ops:reboot HTTP/1.1 1431 Host: example.com 1432 Content-Type: application/yang.operation+xml 1434 1435 -33 1436 Going down for system maintenance 1437 en-US 1438 1440 The server might respond with an "invalid-value" error: 1442 HTTP/1.1 400 Bad Request 1443 Date: Mon, 25 Apr 2012 11:10:30 GMT 1444 Server: example-server 1445 Content-Type: application/yang.errors+xml 1447 1448 1449 protocol 1450 invalid-value 1451 1452 /ops:input/ops:delay 1453 1454 Invalid input parameter 1455 1456 1458 The same response is shown here in JSON encoding: 1460 HTTP/1.1 400 Bad Request 1461 Date: Mon, 25 Apr 2012 11:10:30 GMT 1462 Server: example-server 1463 Content-Type: application/yang.errors+json 1465 { "ietf-restconf:errors" : { 1466 "error" : [ 1467 { 1468 "error-type" : "protocol", 1469 "error-tag" : "invalid-value", 1470 "error-path" : "/example-ops:input/delay", 1471 "error-message" : "Invalid input parameter", 1472 } 1473 ] 1474 } 1475 } 1477 3.7. Schema Resource 1479 The server can optionally support retrieval of the YANG modules it 1480 supports. If retrieval is supported, then the "schema" leaf MUST be 1481 present in the associated "module" list entry, defined in 1482 [I-D.ietf-netconf-yang-library]. 1484 To retrieve a YANG module, a client first needs to get the URL for 1485 retrieving the schema, which is stored in the "schema" leaf. Note 1486 that there is no required structure for this URL. The URL value 1487 shown below is just an example. 1489 The client might send the following GET request message: 1491 GET /restconf/data/ietf-yang-library:modules/module= 1492 example-jukebox,2015-04-04/schema HTTP/1.1 1493 Host: example.com 1494 Accept: application/yang.data+json 1496 The server might respond: 1498 HTTP/1.1 200 OK 1499 Date: Thu, 11 Feb 2016 11:10:30 GMT 1500 Server: example-server 1501 Content-Type: application/yang.data+json 1503 { 1504 "ietf-yang-library:schema": 1505 "https://example.com/mymodules/example-jukebox/2015-04-04" 1506 } 1508 Next the client needs to retrieve the actual YANG schema. 1510 The client might send the following GET request message: 1512 GET https://example.com/mymodules/example-jukebox/2015-04-04 1513 HTTP/1.1 1514 Host: example.com 1515 Accept: application/yang 1517 The server might respond: 1519 HTTP/1.1 200 OK 1520 Date: Thu, 11 Feb 2016 11:10:31 GMT 1521 Server: example-server 1522 Content-Type: application/yang 1524 module example-jukebox { 1526 // contents of YANG module deleted for this example... 1528 } 1530 3.8. Event Stream Resource 1532 An "event stream" resource represents a source for system generated 1533 event notifications. Each stream is created and modified by the 1534 server only. A client can retrieve a stream resource or initiate a 1535 long-poll server sent event stream, using the procedure specified in 1536 Section 6.3. 1538 A notification stream functions according to the NETCONF 1539 Notifications specification [RFC5277]. The available streams can be 1540 retrieved from the stream list, which specifies the syntax and 1541 semantics of a stream resource. 1543 3.9. Errors Media Type 1544 An "errors" media type is a collection of error information that is 1545 sent as the message-body in a server response message, if an error 1546 occurs while processing a request message. It is not considered a 1547 resource type because no instances can be retrieved with a GET 1548 request. 1550 The "ietf-restconf" YANG module contains the "application/ 1551 yang.errors" restconf-media-type extension which specifies the syntax 1552 and semantics of an "errors" media type. RESTCONF error handling 1553 behavior is defined in Section 7. 1555 4. Operations 1557 The RESTCONF protocol uses HTTP methods to identify the CRUD 1558 operation requested for a particular resource. 1560 The following table shows how the RESTCONF operations relate to 1561 NETCONF protocol operations: 1563 +----------+--------------------------------------------+ 1564 | RESTCONF | NETCONF | 1565 +----------+--------------------------------------------+ 1566 | OPTIONS | none | 1567 | HEAD | none | 1568 | GET | , | 1569 | POST | (operation="create") | 1570 | POST | invoke any operation | 1571 | PUT | (operation="create/replace") | 1572 | PATCH | (operation="merge") | 1573 | DELETE | (operation="delete") | 1574 +----------+--------------------------------------------+ 1576 CRUD Methods in RESTCONF 1578 The NETCONF "remove" operation attribute is not supported by the HTTP 1579 DELETE method. The resource must exist or the DELETE method will 1580 fail. The PATCH method is equivalent to a "merge" operation when 1581 using a plain patch (see Section 4.6.1); other media-types may 1582 provide more granular control. 1584 Access control mechanisms MUST be used to limit what operations can 1585 be used. In particular, RESTCONF is compatible with the NETCONF 1586 Access Control Model (NACM) [RFC6536], as there is a specific mapping 1587 between RESTCONF and NETCONF operations, defined in Section 4. The 1588 resource path needs to be converted internally by the server to the 1589 corresponding YANG instance-identifier. Using this information, the 1590 server can apply the NACM access control rules to RESTCONF messages. 1592 The server MUST NOT allow any operation to any resources that the 1593 client is not authorized to access. 1595 Operations are applied to a single data resource instance at once. 1596 The server MUST NOT allow any operation to be applied to multiple 1597 instances of a YANG list or leaf-list. 1599 Implementation of all methods (except PATCH) are defined in 1600 [RFC7231]. This section defines the RESTCONF protocol usage for each 1601 HTTP method. 1603 4.1. OPTIONS 1605 The OPTIONS method is sent by the client to discover which methods 1606 are supported by the server for a specific resource (e.g., GET, POST, 1607 DELETE, etc.). The server MUST implement this method. 1609 If the PATCH method is supported, then the "Accept-Patch" header MUST 1610 be supported and returned in the response to the OPTIONS request, as 1611 defined in [RFC5789]. 1613 4.2. HEAD 1615 The HEAD method is sent by the client to retrieve just the headers 1616 that would be returned for the comparable GET method, without the 1617 response message-body. It is supported for all resource types, 1618 except operation resources. 1620 The request MUST contain a request URI that contains at least the 1621 entry point. The same query parameters supported by the GET method 1622 are supported by the HEAD method. 1624 The access control behavior is enforced as if the method was GET 1625 instead of HEAD. The server MUST respond the same as if the method 1626 was GET instead of HEAD, except that no response message-body is 1627 included. 1629 4.3. GET 1631 The GET method is sent by the client to retrieve data and meta-data 1632 for a resource. It is supported for all resource types, except 1633 operation resources. The request MUST contain a request URI that 1634 contains at least the entry point. 1636 The server MUST NOT return any data resources for which the user does 1637 not have read privileges. If the user is not authorized to read the 1638 target resource, an error response containing a "403 Forbidden" 1639 status-line SHOULD be returned. A server MAY return a "404 Not 1640 Found" status-line, as described in section 6.5.3 in [RFC7231]. 1642 If the user is authorized to read some but not all of the target 1643 resource, the unauthorized content is omitted from the response 1644 message-body, and the authorized content is returned to the client. 1646 If any content is returned to the client, then the server MUST send a 1647 valid response message-body. More than one element MUST NOT be 1648 returned for XML encoding. 1650 If a retrieval request for a data resource representing a YANG leaf- 1651 list or list object identifies more than one instance, and XML 1652 encoding is used in the response, then an error response containing a 1653 "400 Bad Request" status-line MUST be returned by the server. 1655 If the target resource of a retrieval request is for an operation 1656 resource then a "405 Method Not Allowed" status-line MUST be returned 1657 by the server. 1659 Note that the way that access control is applied to data resources is 1660 completely incompatible with HTTP caching. The Last-Modified and 1661 ETag headers maintained for a data resource are not affected by 1662 changes to the access control rules for that data resource. It is 1663 possible for the representation of a data resource that is visible to 1664 a particular client to be changed without detection via the Last- 1665 Modified or ETag values. 1667 Example: 1669 The client might request the response headers for an XML 1670 representation of the a specific "album" resource: 1672 GET /restconf/data/example-jukebox:jukebox/ 1673 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1674 Host: example.com 1675 Accept: application/yang.data+xml 1677 The server might respond: 1679 HTTP/1.1 200 OK 1680 Date: Mon, 23 Apr 2012 17:02:40 GMT 1681 Server: example-server 1682 Content-Type: application/yang.data+xml 1683 Cache-Control: no-cache 1684 Pragma: no-cache 1685 ETag: a74eefc993a2b 1686 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1688 1690 Wasting Light 1691 jbox:alternative 1692 2011 1693 1695 4.4. POST 1697 The POST method is sent by the client to create a data resource or 1698 invoke an operation resource. The server uses the target resource 1699 media type to determine how to process the request. 1701 +-----------+------------------------------------------------+ 1702 | Type | Description | 1703 +-----------+------------------------------------------------+ 1704 | Datastore | Create a top-level configuration data resource | 1705 | Data | Create a configuration data child resource | 1706 | Operation | Invoke a protocol operation | 1707 +-----------+------------------------------------------------+ 1709 Resource Types that Support POST 1711 4.4.1. Create Resource Mode 1713 If the target resource type is a datastore or data resource, then the 1714 POST is treated as a request to create a top-level resource or child 1715 resource, respectively. The message-body is expected to contain the 1716 content of a child resource to create within the parent (target 1717 resource). The message-body MUST NOT contain more than one instance 1718 of the expected data resource. The data-model for the child tree is 1719 the subtree as defined by YANG for the child resource. 1721 The "insert" and "point" query parameters are supported by the POST 1722 method for datastore and data resources. If the server implements 1723 any YANG module that contains a configuration data node that is 1724 "ordered-by" user, then the "insert" and "point" query parameters 1725 MUST be supported. If not, then these parameters are not applicable. 1727 If the POST method succeeds, a "201 Created" status-line is returned 1728 and there is no response message-body. A "Location" header 1729 identifying the child resource that was created MUST be present in 1730 the response in this case. 1732 If the data resource already exists, then the POST request MUST fail 1733 and a "409 Conflict" status-line MUST be returned. 1735 If the user is not authorized to create the target resource, an error 1736 response containing a "403 Forbidden" status-line SHOULD be returned. 1737 A server MAY return a "404 Not Found" status-line, as described in 1738 section 6.5.3 in [RFC7231]. All other error responses are handled 1739 according to the procedures defined in Section 7. 1741 Example: 1743 To create a new "jukebox" resource, the client might send: 1745 POST /restconf/data HTTP/1.1 1746 Host: example.com 1747 Content-Type: application/yang.data+json 1749 { "example-jukebox:jukebox" : {} } 1751 If the resource is created, the server might respond as follows. 1752 Note that the "Location" header line is wrapped for display purposes 1753 only: 1755 HTTP/1.1 201 Created 1756 Date: Mon, 23 Apr 2012 17:01:00 GMT 1757 Server: example-server 1758 Location: https://example.com/restconf/data/ 1759 example-jukebox:jukebox 1760 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 1761 ETag: b3a3e673be2 1763 Refer to Appendix D.2.1 for more resource creation examples. 1765 4.4.2. Invoke Operation Mode 1767 If the target resource type is an operation resource, then the POST 1768 method is treated as a request to invoke that operation. The 1769 message-body (if any) is processed as the operation input parameters. 1770 Refer to Section 3.6 for details on operation resources. 1772 If the POST request succeeds, a "200 OK" status-line is returned if 1773 there is a response message-body, and a "204 No Content" status-line 1774 is returned if there is no response message-body. 1776 If the user is not authorized to invoke the target operation, an 1777 error response containing a "403 Forbidden" status-line is returned 1778 to the client. All other error responses are handled according to 1779 the procedures defined in Section 7. 1781 Example: 1783 In this example, the client is invoking the "play" operation defined 1784 in the "example-jukebox" YANG module. 1786 A client might send a "play" request as follows: 1788 POST /restconf/operations/example-jukebox:play HTTP/1.1 1789 Host: example.com 1790 Content-Type: application/yang.operation+json 1792 { 1793 "example-jukebox:input" : { 1794 "playlist" : "Foo-One", 1795 "song-number" : 2 1796 } 1797 } 1799 The server might respond: 1801 HTTP/1.1 204 No Content 1802 Date: Mon, 23 Apr 2012 17:50:00 GMT 1803 Server: example-server 1805 4.5. PUT 1807 The PUT method is sent by the client to create or replace the target 1808 data resource. A request message-body MUST be present, representing 1809 the new data resource, or the server MUST return "400 Bad Request" 1810 status-line. 1812 The only target resource media type that supports PUT is the data 1813 resource. The message-body is expected to contain the content used 1814 to create or replace the target resource. 1816 The "insert" (Section 4.8.4) and "point" (Section 4.8.5) query 1817 parameters are supported by the PUT method for data resources. 1819 Consistent with [RFC7231], if the PUT request creates a new resource, 1820 a "201 Created" status-line is returned. If an existing resource is 1821 modified, a "204 No Content" status-line is returned. 1823 If the user is not authorized to create or replace the target 1824 resource an error response containing a "403 Forbidden" status-line 1825 SHOULD be returned. A server MAY return a "404 Not Found" status- 1826 line, as described in section 6.5.3 in [RFC7231]. All other error 1827 responses are handled according to the procedures defined in 1828 Section 7. 1830 If the target resource represents a YANG leaf-list, then the PUT 1831 method MUST not change the value of the leaf-list instance. 1833 If the target resource represents a YANG list instance, then the PUT 1834 method MUST NOT change any key leaf values in the message-body 1835 representation. 1837 If the server implements any YANG module that contains a 1838 configuration data node that is "ordered-by" user, then the "insert" 1839 and "point" query parameters MUST be supported. If not, then these 1840 parameters are not applicable. 1842 Example: 1844 An "album" child resource defined in the "example-jukebox" YANG 1845 module is replaced or created if it does not already exist. 1847 To replace the "album" resource contents, the client might send as 1848 follows. Note that the request-line is wrapped for display purposes 1849 only: 1851 PUT /restconf/data/example-jukebox:jukebox/ 1852 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1853 Host: example.com 1854 Content-Type: application/yang.data+json 1856 { 1857 "example-jukebox:album" : { 1858 "name" : "Wasting Light", 1859 "genre" : "example-jukebox:alternative", 1860 "year" : 2011 1861 } 1862 } 1864 If the resource is updated, the server might respond: 1866 HTTP/1.1 204 No Content 1867 Date: Mon, 23 Apr 2012 17:04:00 GMT 1868 Server: example-server 1869 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 1870 ETag: b27480aeda4c 1872 The same request is shown here using XML encoding: 1874 PUT /restconf/data/example-jukebox:jukebox/ 1875 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1876 Host: example.com 1877 Content-Type: application/yang.data+xml 1878 1880 Wasting Light 1881 jbox:alternative 1882 2011 1883 1885 4.6. PATCH 1887 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 1888 an extensible framework for resource patching mechanisms. It is 1889 optional to implement by the server. Each patch mechanism needs a 1890 unique media type. Zero or more patch media types MAY be supported 1891 by the server. The media types supported by a server can be 1892 discovered by the client by sending an OPTIONS request (see 1893 Section 4.1). 1895 This document defines one patch mechanism (Section 4.6.1). The YANG 1896 PATCH mechanism is defined in [I-D.ietf-netconf-yang-patch]. Other 1897 patch mechanisms may be defined by future specifications. 1899 If the target resource instance does not exist, the server MUST NOT 1900 create it. 1902 If the PATCH request succeeds, a "200 OK" status-line is returned if 1903 there is a message-body, and "204 No Content" is returned if no 1904 response message-body is sent. 1906 If the user is not authorized to alter the target resource an error 1907 response containing a "403 Forbidden" status-line SHOULD be returned. 1908 A server MAY return a "404 Not Found" status-line, as described in 1909 section 6.5.3 in [RFC7231]. All other error responses are handled 1910 according to the procedures defined in Section 7. 1912 4.6.1. Plain Patch 1914 The plain patch mechanism merges the contents of the message body 1915 with the target resource. If the target resource is a datastore 1916 resource (see Section 3.4), the message body MUST be either 1917 application/yang.datastore+xml or application/yang.datastore+json. 1918 If then the target resource is a data resource (see Section 3.5), 1919 then the message body MUST be either application/yang.data+xml or 1920 application/yang.data+json. 1922 Plain patch can be used to create or update, but not delete, a child 1923 resource within the target resource. Please see 1924 [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting 1925 more granular control. The YANG Patch Media Type allows multiple 1926 sub-operations (e.g., merge, delete) within a single PATCH operation. 1928 If the target resource represents a YANG leaf-list, then the PATCH 1929 method MUST not change the value of the leaf-list instance. 1931 If the target resource represents a YANG list instance, then the 1932 PATCH method MUST NOT change any key leaf values in the message-body 1933 representation. 1935 Example: 1937 To replace just the "year" field in the "album" resource (instead of 1938 replacing the entire resource with the PUT method), the client might 1939 send a plain patch as follows. Note that the request-line is wrapped 1940 for display purposes only: 1942 PATCH /restconf/data/example-jukebox:jukebox/ 1943 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1944 Host: example.com 1945 If-Match: b8389233a4c 1946 Content-Type: application/yang.data+xml 1948 1949 2011 1950 1952 If the field is updated, the server might respond: 1954 HTTP/1.1 204 No Content 1955 Date: Mon, 23 Apr 2012 17:49:30 GMT 1956 Server: example-server 1957 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 1958 ETag: b2788923da4c 1960 4.7. DELETE 1962 The DELETE method is used to delete the target resource. If the 1963 DELETE request succeeds, a "204 No Content" status-line is returned, 1964 and there is no response message-body. 1966 If the user is not authorized to delete the target resource then an 1967 error response containing a "403 Forbidden" status-line SHOULD be 1968 returned. A server MAY return a "404 Not Found" status-line, as 1969 described in section 6.5.3 in [RFC7231]. All other error responses 1970 are handled according to the procedures defined in Section 7. 1972 If the target resource represents a YANG leaf-list or list, then the 1973 PATCH method SHOULD NOT delete more than one such instance. The 1974 server MAY delete more than one instance if a query parameter is used 1975 requesting this behavior. (Definition of this query parameter is 1976 outside the scope of this document.) 1978 Example: 1980 To delete a resource such as the "album" resource, the client might 1981 send: 1983 DELETE /restconf/data/example-jukebox:jukebox/ 1984 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1985 Host: example.com 1987 If the resource is deleted, the server might respond: 1989 HTTP/1.1 204 No Content 1990 Date: Mon, 23 Apr 2012 17:49:40 GMT 1991 Server: example-server 1993 4.8. Query Parameters 1995 Each RESTCONF operation allows zero or more query parameters to be 1996 present in the request URI. The specific parameters that are allowed 1997 depends on the resource type, and sometimes the specific target 1998 resource used, in the request. 2000 +-------------------+-------------+---------------------------------+ 2001 | Name | Methods | Description | 2002 +-------------------+-------------+---------------------------------+ 2003 | content | GET | Select config and/or non-config | 2004 | | | data resources | 2005 | depth | GET | Request limited sub-tree depth | 2006 | | | in the reply content | 2007 | fields | GET | Request a subset of the target | 2008 | | | resource contents | 2009 | filter | GET | Boolean notification filter for | 2010 | | | event stream resources | 2011 | insert | POST, PUT | Insertion mode for user-ordered | 2012 | | | data resources | 2013 | point | POST, PUT | Insertion point for user- | 2014 | | | ordered data resources | 2015 | start-time | GET | Replay buffer start time for | 2016 | | | event stream resources | 2017 | stop-time | GET | Replay buffer stop time for | 2018 | | | event stream resources | 2019 | with-defaults | GET | Control retrieval of default | 2020 | | | values | 2021 +-------------------+-------------+---------------------------------+ 2023 RESTCONF Query Parameters 2025 Query parameters can be given in any order. Each parameter can 2026 appear at most once in a request URI. A default value may apply if 2027 the parameter is missing. 2029 Refer to Appendix D.3 for examples of query parameter usage. 2031 If vendors define additional query parameters, they SHOULD use a 2032 prefix (such as the enterprise or organization name) for query 2033 parameter names in order to avoid collisions with other parameters. 2035 4.8.1. The "content" Query Parameter 2037 The "content" parameter controls how descendant nodes of the 2038 requested data nodes will be processed in the reply. 2040 The allowed values are: 2042 +-----------+-----------------------------------------------------+ 2043 | Value | Description | 2044 +-----------+-----------------------------------------------------+ 2045 | config | Return only configuration descendant data nodes | 2046 | nonconfig | Return only non-configuration descendant data nodes | 2047 | all | Return all descendant data nodes | 2048 +-----------+-----------------------------------------------------+ 2050 This parameter is only allowed for GET methods on datastore and data 2051 resources. A "400 Bad Request" status-line is returned if used for 2052 other methods or resource types. 2054 If this query parameter is not present, the default value is "all". 2055 This query parameter MUST be supported by the server. 2057 4.8.2. The "depth" Query Parameter 2059 The "depth" parameter is used to specify the number of nest levels 2060 returned in a response for a GET method. The first nest-level 2061 consists of the requested data node itself. If the "fields" 2062 parameter (Section 4.8.3) is used to select descendant data nodes, 2063 these nodes all have a depth value of 1. This has the effect of 2064 including the nodes specified by the fields, even if the "depth" 2065 value is less than the actual depth level of the specified fields. 2066 Any child nodes which are contained within a parent node have a depth 2067 value that is 1 greater than its parent. 2069 The value of the "depth" parameter is either an integer between 1 and 2070 65535, or the string "unbounded". "unbounded" is the default. 2072 This parameter is only allowed for GET methods on API, datastore, and 2073 data resources. A "400 Bad Request" status-line is returned if it 2074 used for other methods or resource types. 2076 More than one "depth" query parameter MUST NOT appear in a request. 2077 If more than one instance is present, then a "400 Bad Request" 2078 status-line MUST be returned by the server. 2080 By default, the server will include all sub-resources within a 2081 retrieved resource, which have the same resource type as the 2082 requested resource. Only one level of sub-resources with a different 2083 media type than the target resource will be returned. 2085 If the "depth" query parameter URI is listed in the "capability" 2086 leaf-list in Section 9.3, then the server supports the "depth" query 2087 parameter. 2089 4.8.3. The "fields" Query Parameter 2091 The "fields" query parameter is used to optionally identify data 2092 nodes within the target resource to be retrieved in a GET method. 2093 The client can use this parameter to retrieve a subset of all nodes 2094 in a resource. 2096 A value of the "fields" query parameter matches the following rule: 2098 fields-expr = path '(' fields-expr ')' / 2099 path ';' fields-expr / 2100 path 2101 path = api-identifier [ '/' path ] 2103 "api-identifier" is defined in Section 3.5.1.1. 2105 ";" is used to select multiple nodes. For example, to retrieve only 2106 the "genre" and "year" of an album, use: "fields=genre;year". 2108 Parentheses are used to specify sub-selectors of a node. 2110 For example, assume the target resource is the "album" list. To 2111 retrieve only the "label" and "catalogue-number" of the "admin" 2112 container within an album, use: 2113 "fields=admin(label;catalogue-number)". 2115 "/" is used in a path to retrieve a child node of a node. For 2116 example, to retrieve only the "label" of an album, use: "fields=admin 2117 /label". 2119 This parameter is only allowed for GET methods on api, datastore, and 2120 data resources. A "400 Bad Request" status-line is returned if used 2121 for other methods or resource types. 2123 More than one "fields" query parameter MUST NOT appear in a request. 2124 If more than one instance is present, then a "400 Bad Request" 2125 status-line MUST be returned by the server. 2127 If the "fields" query parameter URI is listed in the "capability" 2128 leaf-list in Section 9.3, then the server supports the "fields" 2129 parameter. 2131 4.8.4. The "insert" Query Parameter 2133 The "insert" parameter is used to specify how a resource should be 2134 inserted within a user-ordered list. 2136 The allowed values are: 2138 +-----------+-------------------------------------------------------+ 2139 | Value | Description | 2140 +-----------+-------------------------------------------------------+ 2141 | first | Insert the new data as the new first entry. | 2142 | last | Insert the new data as the new last entry. | 2143 | before | Insert the new data before the insertion point, as | 2144 | | specified by the value of the "point" parameter. | 2145 | after | Insert the new data after the insertion point, as | 2146 | | specified by the value of the "point" parameter. | 2147 +-----------+-------------------------------------------------------+ 2149 The default value is "last". 2151 This parameter is only supported for the POST and PUT methods. It is 2152 also only supported if the target resource is a data resource, and 2153 that data represents a YANG list or leaf-list that is ordered by the 2154 user. 2156 More than one "insert" query parameter MUST NOT appear in a request. 2157 If more than one instance is present, then a "400 Bad Request" 2158 status-line MUST be returned by the server. 2160 If the values "before" or "after" are used, then a "point" query 2161 parameter for the insertion parameter MUST also be present, or a "400 2162 Bad Request" status-line is returned. 2164 The "insert" query parameter MUST be supported by the server. 2166 4.8.5. The "point" Query Parameter 2168 The "point" parameter is used to specify the insertion point for a 2169 data resource that is being created or moved within a user ordered 2170 list or leaf-list. 2172 The value of the "point" parameter is a string that identifies the 2173 path to the insertion point object. The format is the same as a 2174 target resource URI string. 2176 This parameter is only supported for the POST and PUT methods. It is 2177 also only supported if the target resource is a data resource, and 2178 that data represents a YANG list or leaf-list that is ordered by the 2179 user. 2181 If the "insert" query parameter is not present, or has a value other 2182 than "before" or "after", then a "400 Bad Request" status-line is 2183 returned. 2185 More than one "point" query parameter MUST NOT appear in a request. 2186 If more than one instance is present, then a "400 Bad Request" 2187 status-line MUST be returned by the server. 2189 This parameter contains the instance identifier of the resource to be 2190 used as the insertion point for a POST or PUT method. 2192 The "point" query parameter MUST be supported by the server. 2194 4.8.6. The "filter" Query Parameter 2196 The "filter" parameter is used to indicate which subset of all 2197 possible events are of interest. If not present, all events not 2198 precluded by other parameters will be sent. 2200 This parameter is only allowed for GET methods on a text/event-stream 2201 data resource. A "400 Bad Request" status-line is returned if used 2202 for other methods or resource types. 2204 The format of this parameter is an XPath 1.0 expression, and is 2205 evaluated in the following context: 2207 o The set of namespace declarations is the set of prefix and 2208 namespace pairs for all supported YANG modules, where the prefix 2209 is the YANG module name, and the namespace is as defined by the 2210 "namespace" statement in the YANG module. 2212 o The function library is the core function library defined in XPath 2213 1.0. 2215 o The set of variable bindings is empty. 2217 o The context node is the root node. 2219 More than one "filter" query parameter MUST NOT appear in a request. 2220 If more than one instance is present, then a "400 Bad Request" 2221 status-line MUST be returned by the server. 2223 The filter is used as defined in [RFC5277], Section 3.6. If the 2224 boolean result of the expression is true when applied to the 2225 conceptual "notification" document root, then the event notification 2226 is delivered to the client. 2228 If the "filter" query parameter URI is listed in the "capability" 2229 leaf-list in Section 9.3, then the server supports the "filter" query 2230 parameter. 2232 4.8.7. The "start-time" Query Parameter 2234 The "start-time" parameter is used to trigger the notification replay 2235 feature and indicate that the replay should start at the time 2236 specified. If the stream does not support replay, per the 2237 "replay-support" attribute returned by stream list entry for the 2238 stream resource, then the server MUST return a "400 Bad Request" 2239 status-line. 2241 The value of the "start-time" parameter is of type "date-and-time", 2242 defined in the "ietf-yang" YANG module [RFC6991]. 2244 This parameter is only allowed for GET methods on a text/event-stream 2245 data resource. A "400 Bad Request" status-line is returned if used 2246 for other methods or resource types. 2248 More than one "start-time" query parameter MUST NOT appear in a 2249 request. If more than one instance is present, then a "400 Bad 2250 Request" status-line MUST be returned by the server. 2252 If this parameter is not present, then a replay subscription is not 2253 being requested. It is not valid to specify start times that are 2254 later than the current time. If the value specified is earlier than 2255 the log can support, the replay will begin with the earliest 2256 available notification. 2258 If this query parameter is supported by the server, then the "replay" 2259 query parameter URI MUST be listed in the "capability" leaf-list in 2260 Section 9.3. The "stop-time" query parameter MUST also be supported 2261 by the server. 2263 If the "replay-support" leaf is present in the "stream" entry 2264 (defined in Section 9.3) then the server MUST support the 2265 "start-time" and "stop-time" query parameters for that stream. 2267 4.8.8. The "stop-time" Query Parameter 2269 The "stop-time" parameter is used with the replay feature to indicate 2270 the newest notifications of interest. This parameter MUST be used 2271 with and have a value later than the "start-time" parameter. 2273 The value of the "stop-time" parameter is of type "date-and-time", 2274 defined in the "ietf-yang" YANG module [RFC6991]. 2276 This parameter is only allowed for GET methods on a text/event-stream 2277 data resource. A "400 Bad Request" status-line is returned if used 2278 for other methods or resource types. 2280 More than one "stop-time" query parameter MUST NOT appear in a 2281 request. If more than one instance is present, then a "400 Bad 2282 Request" status-line MUST be returned by the server. 2284 If this parameter is not present, the notifications will continue 2285 until the subscription is terminated. Values in the future are 2286 valid. 2288 If this query parameter is supported by the server, then the "replay" 2289 query parameter URI MUST be listed in the "capability" leaf-list in 2290 Section 9.3. The "start-time" query parameter MUST also be supported 2291 by the server. 2293 If the "replay-support" leaf is present in the "stream" entry 2294 (defined in Section 9.3) then the server MUST support the 2295 "start-time" and "stop-time" query parameters for that stream. 2297 4.8.9. The "with-defaults" Query Parameter 2299 The "with-defaults" parameter is used to specify how information 2300 about default data nodes should be returned in response to GET 2301 requests on data resources. 2303 If the server supports this capability, then it MUST implement the 2304 behavior in Section 4.5.1 of [RFC6243], except applied to the 2305 RESTCONF GET operation, instead of the NETCONF operations. 2307 +---------------------------+---------------------------------------+ 2308 | Value | Description | 2309 +---------------------------+---------------------------------------+ 2310 | report-all | All data nodes are reported | 2311 | trim | Data nodes set to the YANG default | 2312 | | are not reported | 2313 | explicit | Data nodes set to the YANG default by | 2314 | | the client are reported | 2315 | report-all-tagged | All data nodes are reported and | 2316 | | defaults are tagged | 2317 +---------------------------+---------------------------------------+ 2319 If the "with-defaults" parameter is set to "report-all" then the 2320 server MUST adhere to the defaults reporting behavior defined in 2321 Section 3.1 of [RFC6243]. 2323 If the "with-defaults" parameter is set to "trim" then the server 2324 MUST adhere to the defaults reporting behavior defined in Section 3.2 2325 of [RFC6243]. 2327 If the "with-defaults" parameter is set to "explicit" then the server 2328 MUST adhere to the defaults reporting behavior defined in Section 3.3 2329 of [RFC6243]. 2331 If the "with-defaults" parameter is set to "report-all-tagged" then 2332 the server MUST adhere to the defaults reporting behavior defined in 2333 Section 3.4 of [RFC6243]. 2335 More than one "with-defaults" query parameter MUST NOT appear in a 2336 request. If more than one instance is present, then a "400 Bad 2337 Request" status-line MUST be returned by the server. 2339 If the "with-defaults" parameter is not present then the server MUST 2340 adhere to the defaults reporting behavior defined in its "basic-mode" 2341 parameter for the "defaults" protocol capability URI, defined in 2342 Section 9.1.2. 2344 If the server includes the "with-defaults" query parameter URI in the 2345 "capability" leaf-list in Section 9.3, then the "with-defaults" query 2346 parameter MUST be supported. 2348 5. Messages 2350 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 2351 message corresponds to a single protocol method. Most messages can 2352 perform a single task on a single resource, such as retrieving a 2353 resource or editing a resource. The exception is the PATCH method, 2354 which allows multiple datastore edits within a single message. 2356 5.1. Request URI Structure 2358 Resources are represented with URIs following the structure for 2359 generic URIs in [RFC3986]. 2361 A RESTCONF operation is derived from the HTTP method and the request 2362 URI, using the following conceptual fields: 2364 //?# 2366 ^ ^ ^ ^ ^ 2367 | | | | | 2368 method entry resource query fragment 2370 M M O O I 2372 M=mandatory, O=optional, I=ignored 2374 where: 2376 is the HTTP method 2377 is the RESTCONF entry point 2378 is the Target Resource URI 2379 is the query parameter list 2380 is not used in RESTCONF 2382 o method: the HTTP method identifying the RESTCONF operation 2383 requested by the client, to act upon the target resource specified 2384 in the request URI. RESTCONF operation details are described in 2385 Section 4. 2387 o entry: the root of the RESTCONF API configured on this HTTP 2388 server, discovered by getting the "/.well-known/host-meta" 2389 resource, as described in Section 3.1. 2391 o resource: the path expression identifying the resource that is 2392 being accessed by the operation. If this field is not present, 2393 then the target resource is the API itself, represented by the 2394 media type "application/yang.api". 2396 o query: the set of parameters associated with the RESTCONF message. 2397 These have the familiar form of "name=value" pairs. Most query 2398 parameters are optional to implement by the server and optional to 2399 use by the client. Each optional query parameter is identified by 2400 a URI. The server MUST list the optional query parameter URIs it 2401 supports in the "capabilities" list defined in Section 9.3. 2403 There is a specific set of parameters defined, although the server 2404 MAY choose to support query parameters not defined in this document. 2405 The contents of the any query parameter value MUST be encoded 2406 according to [RFC3986], Section 3.4. Any reserved characters MUST be 2407 percent-encoded, according to [RFC3986], section 2.1. 2409 o fragment: This field is not used by the RESTCONF protocol. 2411 When new resources are created by the client, a "Location" header is 2412 returned, which identifies the path of the newly created resource. 2413 The client uses this exact path identifier to access the resource 2414 once it has been created. 2416 The "target" of an operation is a resource. The "path" field in the 2417 request URI represents the target resource for the operation. 2419 Refer to Appendix D for examples of RESTCONF Request URIs. 2421 5.2. Message Encoding 2423 RESTCONF messages are encoded in HTTP according to [RFC7230]. The 2424 "utf-8" character set is used for all messages. RESTCONF message 2425 content is sent in the HTTP message-body. 2427 Content is encoded in either JSON or XML format. A server MUST 2428 support XML or JSON encoding. XML encoding rules for data nodes are 2429 defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are 2430 used for all XML content. JSON encoding rules are defined in 2431 [I-D.ietf-netmod-yang-json]. JSON encoding of meta-data is defined 2432 in [I-D.ietf-netmod-yang-metadata]. This encoding is valid JSON, but 2433 also has special encoding rules to identify module namespaces and 2434 provide consistent type processing of YANG data. 2436 Request input content encoding format is identified with the Content- 2437 Type header. This field MUST be present if a message-body is sent by 2438 the client. 2440 The server MUST support the "Accept" header and "406 Not Acceptable" 2441 status-line, as defined in [RFC7231]. Response output content 2442 encoding format is identified with the Accept header in the request. 2443 If it is not specified, the request input encoding format SHOULD be 2444 used, or the server MAY choose any supported content encoding format. 2446 If there was no request input, then the default output encoding is 2447 XML or JSON, depending on server preference. File extensions encoded 2448 in the request are not used to identify format encoding. 2450 5.3. RESTCONF Meta-Data 2452 The RESTCONF protocol needs to retrieve the same meta-data that is 2453 used in the NETCONF protocol. Information about default leafs, last- 2454 modified timestamps, etc. are commonly used to annotate 2455 representations of the datastore contents. This meta-data is not 2456 defined in the YANG schema because it applies to the datastore, and 2457 is common across all data nodes. 2459 This information is encoded as attributes in XML. JSON encoding of 2460 meta-data is defined in [I-D.ietf-netmod-yang-metadata]. 2462 The following examples are based on the example in Appendix D.3.9. 2463 The "report-all-tagged" mode for the "with-defaults" query parameter 2464 requires that a "default" attribute be returned for default nodes. 2465 This example shows that attribute for the "mtu" leaf . 2467 5.3.1. XML MetaData Encoding Example 2469 GET /restconf/data/interfaces/interface=eth1 2470 ?with-defaults=report-all-tagged HTTP/1.1 2471 Host: example.com 2472 Accept: application/yang.data+xml 2474 The server might respond as follows. 2476 HTTP/1.1 200 OK 2477 Date: Mon, 23 Apr 2012 17:01:00 GMT 2478 Server: example-server 2479 Content-Type: application/yang.data+xml 2481 2483 eth1 2484 1500 2486 up 2487 2489 5.3.2. JSON MetaData Encoding Example 2491 Note that RFC 6243 defines the "default" attribute with XSD, not 2492 YANG, so the YANG module name has to be assigned manually. The value 2493 "ietf-netconf-with-defaults" is assigned for JSON meta-data encoding. 2495 GET /restconf/data/interfaces/interface=eth1 2496 ?with-defaults=report-all-tagged HTTP/1.1 2497 Host: example.com 2498 Accept: application/yang.data+json 2500 The server might respond as follows. 2502 HTTP/1.1 200 OK 2503 Date: Mon, 23 Apr 2012 17:01:00 GMT 2504 Server: example-server 2505 Content-Type: application/yang.data+json 2507 { 2508 "example:interface": [ 2509 { 2510 "name" : "eth1", 2511 "mtu" : 1500, 2512 "@mtu": { 2513 "ietf-netconf-with-defaults:default" : true 2514 }, 2515 "status" : "up" 2516 } 2517 ] 2518 } 2520 5.4. Return Status 2522 Each message represents some sort of resource access. An HTTP 2523 "status-line" header line is returned for each request. If a 4xx or 2524 5xx range status code is returned in the status-line, then the error 2525 information will be returned in the response, according to the format 2526 defined in Section 7.1. 2528 5.5. Message Caching 2530 Since the datastore contents change at unpredictable times, responses 2531 from a RESTCONF server generally SHOULD NOT be cached. 2533 The server SHOULD include a "Cache-Control" header in every response 2534 that specifies whether the response should be cached. A "Pragma" 2535 header specifying "no-cache" MAY also be sent in case the 2536 "Cache-Control" header is not supported. 2538 Instead of relying on HTTP caching, the client SHOULD track the 2539 "ETag" and/or "Last-Modified" headers returned by the server for the 2540 datastore resource (or data resource if the server supports it). A 2541 retrieval request for a resource can include the "If-None-Match" and/ 2542 or "If-Modified-Since" headers, which will cause the server to return 2543 a "304 Not Modified" status-line if the resource has not changed. 2544 The client MAY use the HEAD method to retrieve just the message 2545 headers, which SHOULD include the "ETag" and "Last-Modified" headers, 2546 if this meta-data is maintained for the target resource. 2548 6. Notifications 2550 The RESTCONF protocol supports YANG-defined event notifications. The 2551 solution preserves aspects of NETCONF Event Notifications [RFC5277] 2552 while utilizing the Server-Sent Events [W3C.CR-eventsource-20121211] 2553 transport strategy. 2555 6.1. Server Support 2557 A RESTCONF server MAY support RESTCONF notifications. Clients may 2558 determine if a server supports RESTCONF notifications by using the 2559 HTTP operation OPTIONS, HEAD, or GET on the stream list. The server 2560 does not support RESTCONF notifications if an HTTP error code is 2561 returned (e.g., "404 Not Found" status-line). 2563 6.2. Event Streams 2565 A RESTCONF server that supports notifications will populate a stream 2566 resource for each notification delivery service access point. A 2567 RESTCONF client can retrieve the list of supported event streams from 2568 a RESTCONF server using the GET operation on the stream list. 2570 The "restconf-state/streams" container definition in the 2571 "ietf-restconf-monitoring" module (defined in Section 9.3) is used to 2572 specify the structure and syntax of the conceptual child resources 2573 within the "streams" resource. 2575 For example: 2577 The client might send the following request: 2579 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2580 streams HTTP/1.1 2581 Host: example.com 2582 Accept: application/yang.data+xml 2584 The server might send the following response: 2586 HTTP/1.1 200 OK 2587 Content-Type: application/yang.api+xml 2588 2590 2591 NETCONF 2592 default NETCONF event stream 2593 2594 true 2595 2596 2007-07-08T00:00:00Z 2597 2598 2599 xml 2600 https://example.com/streams/NETCONF 2601 2602 2603 2604 json 2605 https://example.com/streams/NETCONF-JSON 2606 2607 2608 2609 2610 SNMP 2611 SNMP notifications 2612 false 2613 2614 xml 2615 https://example.com/streams/SNMP 2616 2617 2618 2619 syslog-critical 2620 Critical and higher severity 2621 2622 true 2623 2624 2007-07-01T00:00:00Z 2625 2626 2627 xml 2628 2629 https://example.com/streams/syslog-critical 2630 2631 2632 2633 2635 6.3. Subscribing to Receive Notifications 2637 RESTCONF clients can determine the URL for the subscription resource 2638 (to receive notifications) by sending an HTTP GET request for the 2639 "location" leaf with the stream list entry. The value returned by 2640 the server can be used for the actual notification subscription. 2642 The client will send an HTTP GET request for the URL returned by the 2643 server with the "Accept" type "text/event-stream". 2645 The server will treat the connection as an event stream, using the 2646 Server Sent Events [W3C.CR-eventsource-20121211] transport strategy. 2648 The server MAY support query parameters for a GET method on this 2649 resource. These parameters are specific to each notification stream. 2651 For example: 2653 The client might send the following request: 2655 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2656 streams/stream=NETCONF/access=xml/location HTTP/1.1 2657 Host: example.com 2658 Accept: application/yang.data+xml 2660 The server might send the following response: 2662 HTTP/1.1 200 OK 2663 Content-Type: application/yang.api+xml 2665 2667 https://example.com/streams/NETCONF 2668 2670 The RESTCONF client can then use this URL value to start monitoring 2671 the event stream: 2673 GET /streams/NETCONF HTTP/1.1 2674 Host: example.com 2675 Accept: text/event-stream 2676 Cache-Control: no-cache 2677 Connection: keep-alive 2679 A RESTCONF client MAY request the server compress the events using 2680 the HTTP header field "Accept-Encoding". For instance: 2682 GET /streams/NETCONF HTTP/1.1 2683 Host: example.com 2684 Accept: text/event-stream 2685 Cache-Control: no-cache 2686 Connection: keep-alive 2687 Accept-Encoding: gzip, deflate 2689 6.3.1. NETCONF Event Stream 2691 The server SHOULD support the "NETCONF" notification stream defined 2692 in [RFC5277]. For this stream, RESTCONF notification subscription 2693 requests MAY specify parameters indicating the events it wishes to 2694 receive. These query parameters are optional to implement, and only 2695 available if the server supports them. 2697 +------------+---------+-------------------------+ 2698 | Name | Section | Description | 2699 +------------+---------+-------------------------+ 2700 | start-time | 4.8.7 | replay event start time | 2701 | stop-time | 4.8.8 | replay event stop time | 2702 | filter | 4.8.6 | boolean content filter | 2703 +------------+---------+-------------------------+ 2705 NETCONF Stream Query Parameters 2707 The semantics and syntax for these query parameters are defined in 2708 the sections listed above. The YANG encoding MUST be converted to 2709 URL-encoded string for use in the request URI. 2711 Refer to Appendix D.3.6 for filter parameter examples. 2713 6.4. Receiving Event Notifications 2715 RESTCONF notifications are encoded according to the definition of the 2716 event stream. The NETCONF stream defined in [RFC5277] is encoded in 2717 XML format. 2719 The structure of the event data is based on the "notification" 2720 element definition in Section 4 of [RFC5277]. It MUST conform to the 2721 schema for the "notification" element in Section 4 of [RFC5277], 2722 except the XML namespace for this element is defined as: 2724 urn:ietf:params:xml:ns:yang:ietf-restconf 2726 For JSON encoding purposes, the module name for the "notification" 2727 element is "ietf-restconf". 2729 Two child nodes within the "notification" container are expected, 2730 representing the event time and the event payload. The "event-time" 2731 node is defined within the "ietf-restconf" module namespace. The 2732 name and namespace of the payload element are determined by the YANG 2733 module containing the notification-stmt. 2735 In the following example, the YANG module "example-mod" is used: 2737 module example-mod { 2738 namespace "http://example.com/event/1.0"; 2739 prefix ex; 2741 notification event { 2742 leaf event-class { type string; } 2743 container reporting-entity { 2744 leaf card { type string; } 2745 } 2746 leaf severity { type string; } 2747 } 2748 } 2750 An example SSE event notification encoded using XML: 2752 data: 2754 data: 2013-12-21T00:01:00Z 2755 data: 2756 data: fault 2757 data: 2758 data: Ethernet0 2759 data: 2760 data: major 2761 data: 2762 data: 2764 An example SSE event notification encoded using JSON: 2766 data: { 2767 data: "ietf-restconf:notification": { 2768 data: "event-time": "2013-12-21T00:01:00Z", 2769 data: "example-mod:event": { 2770 data: "event-class": "fault", 2771 data: "reporting-entity": { "card": "Ethernet0" }, 2772 data: "severity": "major" 2773 data: } 2774 data: } 2775 data: } 2776 Alternatively, since neither XML nor JSON are whitespace sensitive, 2777 the above messages can be encoded onto a single line. For example: 2779 For example: ('\' line wrapping added for formatting only) 2781 XML: 2783 data: 2013-12-21T00:01:00ZfaultEthernet0\ 2787 major 2789 JSON: 2791 data: {"ietf-restconf:notification":{"event-time":"2013-12-21\ 2792 T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ 2793 tingEntity":{"card":"Ethernet0"},"severity":"major"}}} 2795 The SSE specifications supports the following additional fields: 2796 event, id and retry. A RESTCONF server MAY send the "retry" field 2797 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 2798 SHOULD NOT send the "event" or "id" fields, as there are no 2799 meaningful values that could be used for them that would not be 2800 redundant to the contents of the notification itself. RESTCONF 2801 servers that do not send the "id" field also do not need to support 2802 the HTTP header "Last-Event-Id". RESTCONF servers that do send the 2803 "id" field MUST still support the "startTime" query parameter as the 2804 preferred means for a client to specify where to restart the event 2805 stream. 2807 7. Error Reporting 2809 HTTP status-lines are used to report success or failure for RESTCONF 2810 operations. The element returned in NETCONF error 2811 responses contains some useful information. This error information 2812 is adapted for use in RESTCONF, and error information is returned for 2813 "4xx" class of status codes. 2815 The following table summarizes the return status codes used 2816 specifically by RESTCONF operations: 2818 +----------------------------+--------------------------------------+ 2819 | Status-Line | Description | 2820 +----------------------------+--------------------------------------+ 2821 | 100 Continue | POST accepted, 201 should follow | 2822 | 200 OK | Success with response message-body | 2823 | 201 Created | POST to create a resource success | 2824 | 204 No Content | Success without response message- | 2825 | | body | 2826 | 304 Not Modified | Conditional operation not done | 2827 | 400 Bad Request | Invalid request message | 2828 | 401 Unauthorized | Client cannot be authenticated | 2829 | 403 Forbidden | Access to resource denied | 2830 | 404 Not Found | Resource target or resource node not | 2831 | | found | 2832 | 405 Method Not Allowed | Method not allowed for target | 2833 | | resource | 2834 | 409 Conflict | Resource or lock in use | 2835 | 412 Precondition Failed | Conditional method is false | 2836 | 413 Request Entity Too | too-big error | 2837 | Large | | 2838 | 414 Request-URI Too Large | too-big error | 2839 | 415 Unsupported Media Type | non RESTCONF media type | 2840 | 500 Internal Server Error | operation-failed | 2841 | 501 Not Implemented | unknown-operation | 2842 | 503 Service Unavailable | Recoverable server error | 2843 +----------------------------+--------------------------------------+ 2845 HTTP Status Codes used in RESTCONF 2847 Since an operation resource is defined with a YANG "rpc" statement, 2848 and an action is defined with a YANG "action" statement, a mapping 2849 between the NETCONF value and the HTTP status code is 2850 needed. The specific error condition and response code to use are 2851 data-model specific and might be contained in the YANG "description" 2852 statement for the "action" or "rpc" statement. 2854 +-------------------------+-------------+ 2855 | | status code | 2856 +-------------------------+-------------+ 2857 | in-use | 409 | 2858 | invalid-value | 400 | 2859 | too-big | 413 | 2860 | missing-attribute | 400 | 2861 | bad-attribute | 400 | 2862 | unknown-attribute | 400 | 2863 | bad-element | 400 | 2864 | unknown-element | 400 | 2865 | unknown-namespace | 400 | 2866 | access-denied | 403 | 2867 | lock-denied | 409 | 2868 | resource-denied | 409 | 2869 | rollback-failed | 500 | 2870 | data-exists | 409 | 2871 | data-missing | 409 | 2872 | operation-not-supported | 501 | 2873 | operation-failed | 500 | 2874 | partial-operation | 500 | 2875 | malformed-message | 400 | 2876 +-------------------------+-------------+ 2878 Mapping from error-tag to status code 2880 7.1. Error Response Message 2882 When an error occurs for a request message on a data resource or an 2883 operation resource, and a "4xx" class of status codes will be 2884 returned (except for status code "403 Forbidden"), then the server 2885 SHOULD send a response message-body containing the information 2886 described by the "errors" container definition within the YANG module 2887 Section 8. The Content-Type of this response message MUST be 2888 application/yang.errors (see example below). 2890 The client MAY specify the desired encoding for error messages by 2891 specifying the appropriate media-type in the Accept header. If no 2892 error media is specified, then the media type of the request message 2893 SHOULD be used, or the server MAY choose any supported message 2894 encoding format. If there is no request message the server MUST 2895 select "application/yang.errors+xml" or "application/ 2896 yang.errors+json", depending on server preference. All of the 2897 examples in this document, except for the one below, assume that XML 2898 encoding will be returned if there is an error. 2900 YANG Tree Diagram for data: 2902 +--ro errors 2903 +--ro error* 2904 +--ro error-type enumeration 2905 +--ro error-tag string 2906 +--ro error-app-tag? string 2907 +--ro error-path? instance-identifier 2908 +--ro error-message? string 2909 +--ro error-info 2911 The semantics and syntax for RESTCONF error messages are defined in 2912 the "application/yang.errors" restconf-media-type extension in 2913 Section 8. 2915 Examples: 2917 The following example shows an error returned for an "lock-denied" 2918 error that can occur if a NETCONF client has locked a datastore. The 2919 RESTCONF client is attempting to delete a data resource. Note that 2920 an Accept header is used to specify the desired encoding for the 2921 error message. This example's use of the Accept header is especially 2922 notable since the DELETE method typically doesn't return a message- 2923 body and hence Accept headers are typically not passed. 2925 DELETE /restconf/data/example-jukebox:jukebox/ 2926 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2927 Host: example.com 2928 Accept: application/yang.errors+json 2930 The server might respond: 2932 HTTP/1.1 409 Conflict 2933 Date: Mon, 23 Apr 2012 17:11:00 GMT 2934 Server: example-server 2935 Content-Type: application/yang.errors+json 2937 { 2938 "ietf-restconf:errors": { 2939 "error": [ 2940 { 2941 "error-type": "protocol", 2942 "error-tag": "lock-denied", 2943 "error-message": "Lock failed, lock already held" 2944 } 2945 ] 2946 } 2947 } 2949 The following example shows an error returned for a "data-exists" 2950 error on a data resource. The "jukebox" resource already exists so 2951 it cannot be created. 2953 The client might send: 2955 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 2956 Host: example.com 2958 The server might respond (some lines wrapped for display purposes): 2960 HTTP/1.1 409 Conflict 2961 Date: Mon, 23 Apr 2012 17:11:00 GMT 2962 Server: example-server 2963 Content-Type: application/yang.errors+xml 2965 2966 2967 protocol 2968 data-exists 2969 2972 /rc:restconf/rc:data/jbox:jukebox 2973 2974 2975 Data already exists, cannot create new resource 2976 2977 2978 2980 8. RESTCONF module 2982 The "ietf-restconf" module defines conceptual definitions within an 2983 extension and two groupings, which are not meant to be implemented as 2984 datastore contents by a server. E.g., the "restconf" container is 2985 not intended to be implemented as a top-level data node (under the "/ 2986 restconf/data" entry point). 2988 RFC Ed.: update the date below with the date of RFC publication and 2989 remove this note. 2991 file "ietf-restconf@2016-03-16.yang" 2993 module ietf-restconf { 2994 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 2995 prefix "rc"; 2997 organization 2998 "IETF NETCONF (Network Configuration) Working Group"; 3000 contact 3001 "WG Web: 3002 WG List: 3004 WG Chair: Mehmet Ersue 3005 3007 WG Chair: Mahesh Jethanandani 3008 3010 Editor: Andy Bierman 3011 3013 Editor: Martin Bjorklund 3014 3016 Editor: Kent Watsen 3017 "; 3019 description 3020 "This module contains conceptual YANG specifications 3021 for basic RESTCONF media type definitions used in 3022 RESTCONF protocol messages. 3024 Note that the YANG definitions within this module do not 3025 represent configuration data of any kind. 3026 The 'restconf-media-type' YANG extension statement 3027 provides a normative syntax for XML and JSON message 3028 encoding purposes. 3030 Copyright (c) 2016 IETF Trust and the persons identified as 3031 authors of the code. All rights reserved. 3033 Redistribution and use in source and binary forms, with or 3034 without modification, is permitted pursuant to, and subject 3035 to the license terms contained in, the Simplified BSD License 3036 set forth in Section 4.c of the IETF Trust's Legal Provisions 3037 Relating to IETF Documents 3038 (http://trustee.ietf.org/license-info). 3040 This version of this YANG module is part of RFC XXXX; see 3041 the RFC itself for full legal notices."; 3043 // RFC Ed.: replace XXXX with actual RFC number and remove this 3044 // note. 3046 // RFC Ed.: remove this note 3047 // Note: extracted from draft-ietf-netconf-restconf-10.txt 3049 // RFC Ed.: update the date below with the date of RFC publication 3050 // and remove this note. 3051 revision 2016-03-16 { 3052 description 3053 "Initial revision."; 3054 reference 3055 "RFC XXXX: RESTCONF Protocol."; 3056 } 3058 extension restconf-media-type { 3059 argument media-type-id { 3060 yin-element true; 3061 } 3062 // RFC Ed.: replace draft-ietf-netmod-yang-json with RFC number 3063 // in the description below, and remove this note. 3065 description 3066 "This extension is used to specify a YANG data structure which 3067 represents a conceptual RESTCONF media type. 3068 Data definition statements within this extension specify 3069 the generic syntax for the specific media type. 3071 YANG is mapped to specific encoding formats outside the 3072 scope of this extension statement. RFC 6020 defines XML 3073 encoding rules for all RESTCONF media types that use 3074 the '+xml' suffix. draft-ietf-netmod-yang-json defines 3075 JSON encoding rules for all RESTCONF media types that 3076 use the '+json' suffix. 3078 The 'media-type-id' parameter value identifies the media type 3079 that is being defined. It contains the string associated 3080 with the generic media type, i.e., no suffix is specified. 3082 This extension is ignored unless it appears as a top-level 3083 statement. It SHOULD contain data definition statements 3084 that result in exactly one container data node definition. 3085 This allows compliant translation to an XML instance 3086 document for each media type. 3088 The module name and namespace value for the YANG module using 3089 the extension statement is assigned to instance document data 3090 conforming to the data definition statements within 3091 this extension. 3093 The sub-statements of this extension MUST follow the 3094 'data-def-stmt' rule in the YANG ABNF. 3096 The XPath document root is the extension statement itself, 3097 such that the child nodes of the document root are 3098 represented by the data-def-stmt sub-statements within 3099 this extension. This conceptual document is the context 3100 for the following YANG statements: 3102 - must-stmt 3103 - when-stmt 3104 - path-stmt 3105 - min-elements-stmt 3106 - max-elements-stmt 3107 - mandatory-stmt 3108 - unique-stmt 3109 - ordered-by 3110 - instance-identifier data type 3112 The following data-def-stmt sub-statements have special 3113 meaning when used within a restconf-resource extension 3114 statement. 3116 - The list-stmt is not required to have a key-stmt defined. 3117 - The if-feature-stmt is ignored if present. 3118 - The config-stmt is ignored if present. 3119 - The available identity values for any 'identityref' 3120 leaf or leaf-list nodes is limited to the module 3121 containing this extension statement, and the modules 3122 imported into that module. 3123 "; 3124 } 3126 rc:restconf-media-type "application/yang.errors" { 3127 uses errors; 3128 } 3130 rc:restconf-media-type "application/yang.api" { 3131 uses restconf; 3132 } 3134 grouping errors { 3135 description 3136 "A grouping that contains a YANG container 3137 representing the syntax and semantics of a 3138 YANG Patch errors report within a response message."; 3140 container errors { 3141 description 3142 "Represents an error report returned by the server if 3143 a request results in an error."; 3145 list error { 3146 description 3147 "An entry containing information about one 3148 specific error that occurred while processing 3149 a RESTCONF request."; 3150 reference "RFC 6241, Section 4.3"; 3152 leaf error-type { 3153 type enumeration { 3154 enum transport { 3155 description "The transport layer"; 3156 } 3157 enum rpc { 3158 description "The rpc or notification layer"; 3159 } 3160 enum protocol { 3161 description "The protocol operation layer"; 3162 } 3163 enum application { 3164 description "The server application layer"; 3165 } 3166 } 3167 mandatory true; 3168 description 3169 "The protocol layer where the error occurred."; 3170 } 3172 leaf error-tag { 3173 type string; 3174 mandatory true; 3175 description 3176 "The enumerated error tag."; 3177 } 3179 leaf error-app-tag { 3180 type string; 3181 description 3182 "The application-specific error tag."; 3183 } 3185 leaf error-path { 3186 type instance-identifier; 3187 description 3188 "The YANG instance identifier associated 3189 with the error node."; 3190 } 3192 leaf error-message { 3193 type string; 3194 description 3195 "A message describing the error."; 3196 } 3198 anyxml error-info { 3199 description 3200 "This anyxml value MUST represent a container with 3201 zero or more data nodes representing additional 3202 error information."; 3203 } 3204 } 3205 } 3206 } 3208 grouping restconf { 3209 description 3210 "Conceptual container representing the 3211 application/yang.api resource type."; 3213 container restconf { 3214 description 3215 "Conceptual container representing the 3216 application/yang.api resource type."; 3218 container data { 3219 description 3220 "Container representing the application/yang.datastore 3221 resource type. Represents the conceptual root of all 3222 operational data and configuration data supported by 3223 the server. The child nodes of this container can be 3224 any data resource (application/yang.data), which are 3225 defined as top-level data nodes from the YANG modules 3226 advertised by the server in the ietf-restconf-monitoring 3227 module."; 3228 } 3230 container operations { 3231 description 3232 "Container for all operation resources 3233 (application/yang.operation), 3235 Each resource is represented as an empty leaf with the 3236 name of the RPC operation from the YANG rpc statement. 3238 E.g.; 3240 POST /restconf/operations/show-log-errors 3242 leaf show-log-errors { 3243 type empty; 3244 } 3245 "; 3246 } 3248 leaf yang-library-version { 3249 type string { 3250 pattern '\d{4}-\d{2}-\d{2}'; 3251 } 3252 config false; 3253 mandatory true; 3254 description 3255 "Identifies the revision date of the ietf-yang-library 3256 module that is implemented by this RESTCONF server. 3258 Indicates the year, month, and day in YYYY-MM-DD 3259 numeric format."; 3260 } 3261 } 3262 } 3264 } 3266 3268 9. RESTCONF Monitoring 3270 The "ietf-restconf-monitoring" module provides information about the 3271 RESTCONF protocol capabilities and event notification streams 3272 available from the server. A RESTCONF server MUST implement the "/ 3273 restconf-state/capabilities" container in this module. 3275 YANG Tree Diagram for "ietf-restconf-monitoring" module: 3277 +--ro restconf-state 3278 +--ro capabilities 3279 | +--ro capability* inet:uri 3280 +--ro streams 3281 +--ro stream* [name] 3282 +--ro name string 3283 +--ro description? string 3284 +--ro replay-support? boolean 3285 +--ro replay-log-creation-time? yang:date-and-time 3286 +--ro access* [encoding] 3287 +--ro encoding string 3288 +--ro location inet:uri 3290 9.1. restconf-state/capabilities 3292 This mandatory container holds the RESTCONF protocol capability URIs 3293 supported by the server. 3295 The server MUST maintain a last-modified timestamp for this 3296 container, and return the "Last-Modified" header when this data node 3297 is retrieved with the GET or HEAD methods. 3299 The server SHOULD maintain an entity-tag for this container, and 3300 return the "ETag" header when this data node is retrieved with the 3301 GET or HEAD methods. 3303 The server MUST include a "capability" URI leaf-list entry for the 3304 "defaults" mode used by the server, defined in Section 9.1.2. 3306 The server MUST include a "capability" URI leaf-list entry 3307 identifying each supported optional protocol feature. This includes 3308 optional query parameters and MAY include other capability URIs 3309 defined outside this document. 3311 9.1.1. Query Parameter URIs 3313 A new set of RESTCONF Capability URIs are defined to identify the 3314 specific query parameters (defined in Section 4.8) supported by the 3315 server. 3317 The server MUST include a "capability" leaf-list entry for each 3318 optional query parameter that it supports. 3320 +-------------+-------+---------------------------------------------+ 3321 | Name | Secti | URI | 3322 | | on | | 3323 +-------------+-------+---------------------------------------------+ 3324 | depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 | 3325 | | | .0 | 3326 | fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: | 3327 | | | 1.0 | 3328 | filter | 4.8.6 | urn:ietf:params:restconf:capability:filter: | 3329 | | | 1.0 | 3330 | replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: | 3331 | | 4.8.8 | 1.0 | 3332 | with- | 4.8.9 | urn:ietf:params:restconf:capability:with- | 3333 | defaults | | defaults:1.0 | 3334 +-------------+-------+---------------------------------------------+ 3336 RESTCONF Query Parameter URIs 3338 9.1.2. The "defaults" Protocol Capability URI 3340 This URI identifies the defaults handling mode that is used by the 3341 server for processing default leafs in requests for data resources. 3342 A parameter named "basic-mode" is required for this capability URI. 3343 The "basic-mode" definitions are specified in the "With-Defaults 3344 Capability for NETCONF" [RFC6243]. 3346 +----------+--------------------------------------------------+ 3347 | Name | URI | 3348 +----------+--------------------------------------------------+ 3349 | defaults | urn:ietf:params:restconf:capability:defaults:1.0 | 3350 +----------+--------------------------------------------------+ 3352 RESTCONF defaults capability URI 3354 This protocol capability URI MUST be supported by the server, and 3355 MUST be listed in the "capability" leaf-list in Section 9.3. 3357 +------------------+------------------------------------------------+ 3358 | Value | Description | 3359 +------------------+------------------------------------------------+ 3360 | report-all | No data nodes are considered default | 3361 | trim | Values set to the YANG default-stmt value are | 3362 | | default | 3363 | explicit | Values set by the client are never considered | 3364 | | default | 3365 +------------------+------------------------------------------------+ 3367 If the "basic-mode" is set to "report-all" then the server MUST 3368 adhere to the defaults handling behavior defined in Section 2.1 of 3369 [RFC6243]. 3371 If the "basic-mode" is set to "trim" then the server MUST adhere to 3372 the defaults handling behavior defined in Section 2.2 of [RFC6243]. 3374 If the "basic-mode" is set to "explicit" then the server MUST adhere 3375 to the defaults handling behavior defined in Section 2.3 of 3376 [RFC6243]. 3378 Example: (split for display purposes only) 3380 urn:ietf:params:restconf:capability:defaults:1.0? 3381 basic-mode=explicit 3383 9.2. restconf-state/streams 3385 This optional container provides access to the event notification 3386 streams supported by the server. The server MAY omit this container 3387 if no event notification streams are supported. 3389 The server will populate this container with a stream list entry for 3390 each stream type it supports. Each stream contains a leaf called 3391 "events" which contains a URI that represents an event stream 3392 resource. 3394 Stream resources are defined in Section 3.8. Notifications are 3395 defined in Section 6. 3397 9.3. RESTCONF Monitoring Module 3399 The "ietf-restconf-monitoring" module defines monitoring information 3400 for the RESTCONF protocol. 3402 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 3403 are used by this module for some type definitions. 3405 RFC Ed.: update the date below with the date of RFC publication and 3406 remove this note. 3408 file "ietf-restconf-monitoring@2016-03-16.yang" 3410 module ietf-restconf-monitoring { 3411 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; 3412 prefix "rcmon"; 3414 import ietf-yang-types { prefix yang; } 3415 import ietf-inet-types { prefix inet; } 3417 organization 3418 "IETF NETCONF (Network Configuration) Working Group"; 3420 contact 3421 "WG Web: 3422 WG List: 3424 WG Chair: Mehmet Ersue 3425 3427 WG Chair: Mahesh Jethanandani 3428 3430 Editor: Andy Bierman 3431 3433 Editor: Martin Bjorklund 3434 3436 Editor: Kent Watsen 3437 "; 3439 description 3440 "This module contains monitoring information for the 3441 RESTCONF protocol. 3443 Copyright (c) 2016 IETF Trust and the persons identified as 3444 authors of the code. All rights reserved. 3446 Redistribution and use in source and binary forms, with or 3447 without modification, is permitted pursuant to, and subject 3448 to the license terms contained in, the Simplified BSD License 3449 set forth in Section 4.c of the IETF Trust's Legal Provisions 3450 Relating to IETF Documents 3451 (http://trustee.ietf.org/license-info). 3453 This version of this YANG module is part of RFC XXXX; see 3454 the RFC itself for full legal notices."; 3456 // RFC Ed.: replace XXXX with actual RFC number and remove this 3457 // note. 3459 // RFC Ed.: remove this note 3460 // Note: extracted from draft-ietf-netconf-restconf-10.txt 3462 // RFC Ed.: update the date below with the date of RFC publication 3463 // and remove this note. 3464 revision 2016-03-16 { 3465 description 3466 "Initial revision."; 3467 reference 3468 "RFC XXXX: RESTCONF Protocol."; 3469 } 3471 container restconf-state { 3472 config false; 3473 description 3474 "Contains RESTCONF protocol monitoring information."; 3476 container capabilities { 3477 description 3478 "Contains a list of protocol capability URIs"; 3480 leaf-list capability { 3481 type inet:uri; 3482 description "A RESTCONF protocol capability URI."; 3483 } 3484 } 3486 container streams { 3487 description 3488 "Container representing the notification event streams 3489 supported by the server."; 3490 reference 3491 "RFC 5277, Section 3.4, element."; 3493 list stream { 3494 key name; 3495 description 3496 "Each entry describes an event stream supported by 3497 the server."; 3499 leaf name { 3500 type string; 3501 description "The stream name"; 3502 reference "RFC 5277, Section 3.4, element."; 3503 } 3505 leaf description { 3506 type string; 3507 description "Description of stream content"; 3508 reference 3509 "RFC 5277, Section 3.4, element."; 3510 } 3512 leaf replay-support { 3513 type boolean; 3514 description 3515 "Indicates if replay buffer supported for this stream. 3516 If 'true', then the server MUST support the 'start-time' 3517 and 'stop-time' query parameters for this stream."; 3518 reference 3519 "RFC 5277, Section 3.4, element."; 3520 } 3522 leaf replay-log-creation-time { 3523 when "../replay-support" { 3524 description 3525 "Only present if notification replay is supported"; 3526 } 3527 type yang:date-and-time; 3528 description 3529 "Indicates the time the replay log for this stream 3530 was created."; 3531 reference 3532 "RFC 5277, Section 3.4, 3533 element."; 3534 } 3536 list access { 3537 key encoding; 3538 min-elements 1; 3539 description 3540 "The server will create an entry in this list for each 3541 encoding format that is supported for this stream. 3543 The media type 'application/yang.stream' is expected 3544 for all event streams. This list identifies the 3545 sub-types supported for this stream."; 3547 leaf encoding { 3548 type string; 3549 description 3550 "This is the secondary encoding format within the 3551 'text/event-stream' encoding used by all streams. 3552 The type 'xml' is supported for the media type 3553 'application/yang.stream+xml'. The type 'json' 3554 is supported for the media type 3555 'application/yang.stream+json'."; 3557 } 3559 leaf location { 3560 type inet:uri; 3561 mandatory true; 3562 description 3563 "Contains a URL that represents the entry point 3564 for establishing notification delivery via server 3565 sent events."; 3566 } 3567 } 3568 } 3569 } 3570 } 3572 } 3574 3576 10. YANG Module Library 3578 The "ietf-yang-library" module defined in 3579 [I-D.ietf-netconf-yang-library] provides information about the YANG 3580 modules and submodules used by the RESTCONF server. Implementation 3581 is mandatory for RESTCONF servers. All YANG modules and submodules 3582 used by the server MUST be identified in the YANG module library. 3584 10.1. modules 3586 This mandatory container holds the identifiers for the YANG data 3587 model modules supported by the server. 3589 The server MUST maintain a last-modified timestamp for this 3590 container, and return the "Last-Modified" header when this data node 3591 is retrieved with the GET or HEAD methods. 3593 The server SHOULD maintain an entity-tag for this container, and 3594 return the "ETag" header when this data node is retrieved with the 3595 GET or HEAD methods. 3597 10.1.1. modules/module 3599 This mandatory list contains one entry for each YANG data model 3600 module supported by the server. There MUST be an instance of this 3601 list for every YANG module that is used by the server. 3603 The contents of this list are defined in the "module" YANG list 3604 statement in [I-D.ietf-netconf-yang-library]. 3606 The server SHOULD maintain a last-modified timestamp for each 3607 instance of this list entry, and return the "Last-Modified" header 3608 when this data node is retrieved with the GET or HEAD methods. 3610 The server SHOULD maintain an entity-tag for each instance of this 3611 list entry, and return the "ETag" header when this data node is 3612 retrieved with the GET or HEAD methods. 3614 11. IANA Considerations 3616 11.1. The "restconf" Relation Type 3618 This specification registers the "restconf" relation type in the Link 3619 Relation Type Registry defined by [RFC5988]: 3621 Relation Name: restconf 3623 Description: Identifies the root of RESTCONF API as configured 3624 on this HTTP server. The "restconf" relation 3625 defines the root of the API defined in RFCXXXX. 3626 Subsequent revisions of RESTCONF will use alternate 3627 relation values to support protocol versioning. 3629 Reference: RFCXXXX 3631 ` 3633 11.2. YANG Module Registry 3634 This document registers two URIs in the IETF XML registry [RFC3688]. 3635 Following the format in RFC 3688, the following registration is 3636 requested to be made. 3638 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 3639 Registrant Contact: The NETMOD WG of the IETF. 3640 XML: N/A, the requested URI is an XML namespace. 3642 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3643 Registrant Contact: The NETMOD WG of the IETF. 3644 XML: N/A, the requested URI is an XML namespace. 3646 This document registers two YANG modules in the YANG Module Names 3647 registry [RFC6020]. 3649 name: ietf-restconf 3650 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3651 prefix: rc 3652 // RFC Ed.: replace XXXX with RFC number and remove this note 3653 reference: RFCXXXX 3655 name: ietf-restconf-monitoring 3656 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3657 prefix: rcmon 3658 // RFC Ed.: replace XXXX with RFC number and remove this note 3659 reference: RFCXXXX 3661 11.3. application/yang Media Sub Types 3663 The parent MIME media type for RESTCONF resources is application/ 3664 yang, which is defined in [RFC6020]. This document defines the 3665 following sub-types for this media type. 3667 - api 3668 - data 3669 - datastore 3670 - errors 3671 - operation 3672 - stream 3674 Type name: application 3676 Subtype name: yang.xxx, where "xxx" is 1 of "api", 3677 "data", "datastore", "errors", "operation", or "stream" 3679 Required parameters: none 3681 Optional parameters: See section 4.8 in RFC XXXX 3682 Encoding considerations: 8-bit 3684 Security considerations: See Section 12 in RFC XXXX 3686 Interoperability considerations: none 3688 // RFC Ed.: replace XXXX with RFC number and remove this note 3689 Published specification: RFC XXXX 3691 11.4. RESTCONF Capability URNs 3693 [Note to RFC Editor: 3694 The RESTCONF Protocol Capability Registry does not yet exist; 3695 Need to ask IANA to create it; remove this note for publication 3696 ] 3698 This document defines a registry for RESTCONF capability identifiers. 3699 The name of the registry is "RESTCONF Capability URNs". The registry 3700 shall record for each entry: 3702 o the name of the RESTCONF capability. By convention, this name is 3703 prefixed with the colon ':' character. 3705 o the URN for the RESTCONF capability. 3707 This document registers several capability identifiers in "RESTCONF 3708 Capability URNs" registry: 3710 Index 3711 Capability Identifier 3712 ------------------------ 3714 :defaults 3715 urn:ietf:params:restconf:capability:defaults:1.0 3717 :depth 3718 urn:ietf:params:restconf:capability:depth:1.0 3720 :fields 3721 urn:ietf:params:restconf:capability:fields:1.0 3723 :filter 3724 urn:ietf:params:restconf:capability:filter:1.0 3726 :replay 3727 urn:ietf:params:restconf:capability:replay:1.0 3729 :with-defaults 3730 urn:ietf:params:restconf:capability:with-defaults:1.0 3732 12. Security Considerations 3734 This section provides security considerations for the resources 3735 defined by the RESTCONF protocol. Security considerations for HTTPS 3736 are defined in [RFC2818]. RESTCONF does not specify which YANG 3737 modules a server needs to support. Security considerations for the 3738 YANG-defined content manipulated by RESTCONF can be found in the 3739 documents defining those YANG modules. 3741 This document does not require use of a specific client 3742 authentication mechanism or authorization model, but it does require 3743 that a client authentication mechanism and authorization model is 3744 used whenever a client accesses a protected resource. Client 3745 authentication MUST be implemented using client certificates or MUST 3746 be implemented using an HTTP authentication scheme. Client 3747 authorization MAY be configured using the NETCONF Access Control 3748 Model (NACM) [RFC6536]. 3750 Configuration information is by its very nature sensitive. Its 3751 transmission in the clear and without integrity checking leaves 3752 devices open to classic eavesdropping and false data injection 3753 attacks. Configuration information often contains passwords, user 3754 names, service descriptions, and topological information, all of 3755 which are sensitive. Because of this, this protocol SHOULD be 3756 implemented carefully with adequate attention to all manner of attack 3757 one might expect to experience with other management interfaces. 3759 Different environments may well allow different rights prior to and 3760 then after authentication. When an operation is not properly 3761 authorized, the RESTCONF server MUST return a "401 Unauthorized" 3762 status-line. Note that authorization information can be exchanged in 3763 the form of configuration information, which is all the more reason 3764 to ensure the security of the connection. 3766 13. Acknowledgements 3768 The authors would like to thank the following people for their 3769 contributions to this document: Ladislav Lhotka, Juergen 3770 Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. 3772 The authors would like to thank the following people for their 3773 excellent review comments and contributions to this document: Qin Wu, 3774 Joe Clarke, Bert Wijnen, Ladislav Lhotka, Rodney Cummings, Frank 3775 Xialiang, Tom Petch, Robert Sparks, Balint Uveges, Randy Presuhn, and 3776 Sue Hares. 3778 Contributions to this material by Andy Bierman are based upon work 3779 supported by the The Space & Terrestrial Communications Directorate 3780 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 3781 and conclusions or recommendations expressed in this material are 3782 those of the author(s) and do not necessarily reflect the views of 3783 The Space & Terrestrial Communications Directorate (S&TCD). 3785 14. References 3787 14.1. Normative References 3789 [I-D.ietf-netconf-yang-library] 3790 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 3791 Library", draft-ietf-netconf-yang-library-01 (work in 3792 progress), July 2015. 3794 [I-D.ietf-netmod-rfc6020bis] 3795 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 3796 draft-ietf-netmod-rfc6020bis-11 (work in progress), 3797 February 2016. 3799 [I-D.ietf-netmod-yang-json] 3800 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3801 draft-ietf-netmod-yang-json-06 (work in progress), October 3802 2015. 3804 [I-D.ietf-netmod-yang-metadata] 3805 Lhotka, L., "Defining and Using Metadata with YANG", 3806 draft-ietf-netmod-yang-metadata-02 (work in progress), 3807 September 2015. 3809 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3810 Extensions (MIME) Part Two: Media Types", RFC 2046, 3811 November 1996. 3813 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3814 Requirement Levels", BCP 14, RFC 2119, March 1997. 3816 [RFC2818] Rescorla, E., "The IETF XML Registry", RFC 2818, May 2000. 3818 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3819 January 2004. 3821 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3822 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3823 3986, January 2005. 3825 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3826 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3828 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3829 Notifications", RFC 5277, July 2008. 3831 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3832 Housley, R., and T. Polk, "Internet X.509 Public Key 3833 Infrastructure Certificate and Certificate Revocation List 3834 (CRL) Profile", RFC 5280, May 2008. 3836 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3837 5789, March 2010. 3839 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3841 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 3842 Network Configuration Protocol (NETCONF)", RFC 6020, 3843 October 2010. 3845 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3846 Verification of Domain-Based Application Service Identity 3847 within Internet Public Key Infrastructure Using X.509 3848 (PKIX) Certificates in the Context of Transport Layer 3849 Security (TLS)", RFC 6125, March 2011. 3851 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3852 and A. Bierman, Ed., "Network Configuration Protocol 3853 (NETCONF)", RFC 6241, June 2011. 3855 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 3856 NETCONF", RFC 6243, June 2011. 3858 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 3859 6415, October 2011. 3861 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 3862 Protocol (NETCONF) Access Control Model", RFC 6536, March 3863 2012. 3865 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3866 and D. Orchard, "URI Template", RFC 6570, March 2012. 3868 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 3869 July 2013. 3871 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3872 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3873 2014, . 3875 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3876 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 3877 2014. 3879 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3880 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3882 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3883 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 3885 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3886 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3888 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 3889 7320, July 2014. 3891 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 3892 NETCONF Protocol over Transport Layer Security (TLS) with 3893 Mutual X.509 Authentication", RFC 7589, DOI 10.17487/ 3894 RFC7589, June 2015, 3895 . 3897 [W3C.CR-eventsource-20121211] 3898 Hickson, I., "Server-Sent Events", World Wide Web 3899 Consortium CR CR-eventsource-20121211, December 2012, 3900 . 3902 [W3C.REC-html5-20141028] 3903 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 3904 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", World 3905 Wide Web Consortium Recommendation REC-html5-20141028, 3906 October 2014, 3907 . 3909 [W3C.REC-xml-20081126] 3910 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 3911 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 3912 Edition)", World Wide Web Consortium Recommendation REC- 3913 xml-20081126, November 2008, 3914 . 3916 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 3917 Version 1.0", World Wide Web Consortium Recommendation 3918 REC-xpath-19991116, November 1999, 3919 . 3921 14.2. Informative References 3923 [I-D.ietf-netconf-yang-patch] 3924 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 3925 Media Type", draft-ietf-netconf-yang-patch-06 (work in 3926 progress), October 2015. 3928 [rest-dissertation] 3929 Fielding, R., "Architectural Styles and the Design of 3930 Network-based Software Architectures", 2000. 3932 Appendix A. Change Log 3934 -- RFC Ed.: remove this section before publication. 3936 The RESTCONF issue tracker can be found here: https://github.com/ 3937 netconf-wg/restconf/issues 3939 A.1. v09 - v10 3941 o address review comments: github issue #36 3943 o removed intro text about no knowledge of NETCONF needed 3945 o clarified candidate and confirmed-commit behavior in sec. 1.3 3946 o clarified that a RESTCONF server MUST support TLS 3948 o clarified choice of 403 or 404 error 3950 o fixed forward references to URI template (w/reference at first 3951 use) 3953 o added reference to HTML5 3955 o made error terminology more consistent 3957 o clarified that only 1 list or leaf-list instance can be returned 3958 in an XML response message-body 3960 o clarified that more than 1 instance must not be created by a POST 3961 method 3963 o clarified that PUT cannot be used to change a leaf-list value or 3964 any list key values 3966 o clarified that PATCH cannot be used to change a leaf-list value or 3967 any list key values 3969 o clarified that DELETE should not be used to delete more than one 3970 instance of a leaf-list or list 3972 o update JSON RFC reference 3974 o specified that leaf-list instances are data resources 3976 o specified how a leaf-list instance identifier is constructed 3978 o fixed get-schema example 3980 o clarified that if no Accept header the server SHOULD return the 3981 type specified in RESTCONF, but MAY return any media-type, 3982 according to HTTP rules 3984 o clarified that server SHOULD maintain timestamp and etag for data 3985 resources 3987 o clarified default for content query parameter 3989 o moved terminology section earlier in doc to avoid forward usage 3991 o clarified intro text wrt/ interactions with NETCONF and access to 3992 specific datastores 3994 o clarified server implementation requirements for YANG defaults 3996 o clarified that Errors is not a resource, just a media type 3998 o clarified that HTTP without TLS MUST NOT be used 4000 o add RESTCONF Extensibility section to make it clear how RESTCONF 4001 will be extended in the future 4003 o add text warning that NACM does not work with HTTP caching 4005 o remove sec. 5.2 Message Headers 4007 o remove 202 Accepted from list of used status-lines -- not allowed 4009 o made implementation of OPTIONS MUST instead of SHOULD 4011 o clarified that successful PUT for altering data returns 204 4013 o fixed "point" parameter example 4015 o added example of alternate value for root resource discovery 4017 o added YANG action examples 4019 o fixed some JSON examples 4021 o changed default value for content query parameter to "all" 4023 o changed empty container JSON encoding from "[null]" to "{}" 4025 o added mandatory /restconf/yang-library-version leaf to advertise 4026 revision-date of the YANG library implemented by the server 4028 o clarified URI encoding rules for leaf-list 4030 o clarified sec. 2.2 wrt/ certificates and TLS 4032 o added update procedure for entity tag and timestamp 4034 A.2. v08 - v09 4036 o fix introduction text regarding implementation requirements for 4037 the ietf-yang-library 4039 o clarified HTTP authentication requirements 4041 o fix host-meta example 4042 o changed list key encoding to clarify that quoted strings are not 4043 allowed. Percent-encoded values are used if quotes would be 4044 required. A missing key is treated as a zero-length string 4046 o Fixed example of percent-encoded string to match YANG model 4048 o Changed streams examples to align with naming already used 4050 A.3. v07 - v08 4052 o add support for YANG 1.1 action statement 4054 o changed mandatory encoding from XML to XML or JSON 4056 o fix syntax in fields parameter definition 4058 o add meta-data encoding examples for XML and JSON 4060 o remove RFC 2396 references and update with 3986 4062 o change encoding of a key so quoted string are not used, since they 4063 are already percent-encoded. A zero-length string is not encoded 4064 (/list=foo,,baz) 4066 o Add example of percent-encoded key value 4068 A.4. v06 - v07 4070 o fixed all issues identified in email from Jernej Tuljak in netconf 4071 email 2015-06-22 4073 o fixed error example bug where error-urlpath was still used. 4074 Changed to error-path. 4076 o added mention of YANG Patch and informative reference 4078 o added support for YANG 1.1, specifically support for anydata and 4079 actions 4081 o removed the special field value "*", since it is no longer needed 4083 A.5. v05 - v06 4085 o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) 4087 A.6. v04 - v05 4089 o changed term 'notification event' to 'event notification' 4090 o removed intro text about framework and meta-model 4092 o removed early mention of API resources 4094 o removed term unified datastore and cleaned up text about NETCONF 4095 datastores 4097 o removed text about not immediate persistence of edits 4099 o removed RESTCONF-specific data-resource-identifier typedef and its 4100 usage 4102 o clarified encoding of key leafs 4104 o changed several examples from JSON to XML encoding 4106 o made 'insert' and 'point' query parameters mandatory to implement 4108 o removed ":insert" capability URI 4110 o renamed stream/encoding to stream/access 4112 o renamed stream/encoding/type to stream/access/encoding 4114 o renamed stream/encoding/events to stream/access/location 4116 o changed XPath from informative to normative reference 4118 o changed rest-dissertation from normative to informative reference 4120 o changed example-jukebox playlist 'id' from a data-resource- 4121 identifier to a leafref pointing at the song name 4123 A.7. v03 - v04 4125 o renamed 'select' to 'fields' (#1) 4127 o moved collection resource and page capability to draft-ietf- 4128 netconf-restconf-collection-00 (#3) 4130 o added mandatory "defaults" protocol capability URI (#4) 4132 o added optional "with-defaults" query parameter URI (#4) 4134 o clarified authentication procedure (#9) 4136 o moved ietf-yang-library module to draft-ietf-netconf-yang- 4137 library-00 (#13) 4139 o clarified that JSON encoding of module name in a URI MUST follow 4140 the netmod-yang-json encoding rules (#14) 4142 o added restconf-media-type extension (#15) 4144 o remove "content" query parameter URI and made this parameter 4145 mandatory (#16) 4147 o clarified datastore usage 4149 o changed lock-denied error example 4151 o added with-defaults query parameter example 4153 o added term "RESTCONF Capability" 4155 o changed NETCONF Capability URI registry usage to new RESTCONF 4156 Capability URI Registry usage 4158 A.8. v02 - v03 4160 o added collection resource 4162 o added "page" query parameter capability 4164 o added "limit" and "offset" query parameters, which are available 4165 if the "page" capability is supported 4167 o added "stream list" term 4169 o fixed bugs in some examples 4171 o added "encoding" list within the "stream" list to allow different 4172 URLs for XML and JSON encoding. 4174 o made XML MUST implement and JSON MAY implement for servers 4176 o re-add JSON notification examples (previously removed) 4178 o updated JSON references 4180 A.9. v01 - v02 4182 o moved query parameter definitions from the YANG module back to the 4183 plain text sections 4185 o made all query parameters optional to implement 4186 o defined query parameter capability URI 4188 o moved 'streams' to new YANG module (ietf-restconf-monitoring) 4190 o added 'capabilities' container to new YANG module (ietf-restconf- 4191 monitoring) 4193 o moved 'modules' container to new YANG module (ietf-yang-library) 4195 o added new leaf 'module-set-id' (ietf-yang-library) 4197 o added new leaf 'conformance' (ietf-yang-library) 4199 o changed 'schema' leaf to type inet:uri that returns the location 4200 of the YANG schema (instead of returning the schema directly) 4202 o changed 'events' leaf to type inet:uri that returns the location 4203 of the event stream resource (instead of returning events 4204 directly) 4206 o changed examples for yang.api resource since the monitoring 4207 information is no longer in this resource 4209 o closed issue #1 'select parameter' since no objections to the 4210 proposed syntax 4212 o closed "encoding of list keys" issue since no objection to new 4213 encoding of list keys in a target resource URI. 4215 o moved open issues list to the issue tracker on github 4217 A.10. v00 - v01 4219 o fixed content=nonconfig example (non-config was incorrect) 4221 o closed open issue 'message-id'. There is no need for a message-id 4222 field, and RFC 2392 does not apply. 4224 o closed open issue 'server support verification'. The headers used 4225 by RESTCONF are widely supported. 4227 o removed encoding rules from section on RESTCONF Meta-Data. This 4228 is now defined in "I-D.lhotka-netmod-yang-json". 4230 o added media type application/yang.errors to map to errors YANG 4231 grouping. Updated error examples to use new media type. 4233 o closed open issue 'additional datastores'. Support may be added 4234 in the future to identify new datastores. 4236 o closed open issue 'PATCH media type discovery'. The section on 4237 PATCH has an added sentence on the Accept-Patch header. 4239 o closed open issue 'YANG to resource mapping'. Current mapping of 4240 all data nodes to resources will be used in order to allow 4241 mandatory DELETE support. The PATCH operation is optional, as 4242 well as the YANG Patch media type. 4244 o closed open issue '_self links for HATEOAS support'. It was 4245 decided that they are redundant because they can be derived from 4246 the YANG module for the specific data. 4248 o added explanatory text for the 'select' parameter. 4250 o added RESTCONF Path Resolution section for discovering the root of 4251 the RESTCONF API using the /.well-known/host-meta. 4253 o added an "error" media type to for structured error messages 4255 o added Secure Transport section requiring TLS 4257 o added Security Considerations section 4259 o removed all references to "REST-like" 4261 A.11. bierman:restconf-04 to ietf:restconf-00 4263 o updated open issues section 4265 Appendix B. Open Issues 4267 -- RFC Ed.: remove this section before publication. 4269 The RESTCONF issues are tracked on github.com: 4271 https://github.com/netconf-wg/restconf/issues 4273 Appendix C. Example YANG Module 4275 The example YANG module used in this document represents a simple 4276 media jukebox interface. 4278 YANG Tree Diagram for "example-jukebox" Module 4279 +--rw jukebox! 4280 +--rw library 4281 | +--rw artist* [name] 4282 | | +--rw name string 4283 | | +--rw album* [name] 4284 | | +--rw name string 4285 | | +--rw genre? identityref 4286 | | +--rw year? uint16 4287 | | +--rw admin 4288 | | | +--rw label? string 4289 | | | +--rw catalogue-number? string 4290 | | +--rw song* [name] 4291 | | +--rw name string 4292 | | +--rw location string 4293 | | +--rw format? string 4294 | | +--rw length? uint32 4295 | +--ro artist-count? uint32 4296 | +--ro album-count? uint32 4297 | +--ro song-count? uint32 4298 +--rw playlist* [name] 4299 | +--rw name string 4300 | +--rw description? string 4301 | +--rw song* [index] 4302 | +--rw index uint32 4303 | +--rw id leafref 4304 +--rw player 4305 +--rw gap? decimal64 4307 rpcs: 4309 +---x play 4310 +--ro input 4311 +--ro playlist string 4312 +--ro song-number uint32 4314 C.1. example-jukebox YANG Module 4316 module example-jukebox { 4318 namespace "http://example.com/ns/example-jukebox"; 4319 prefix "jbox"; 4321 organization "Example, Inc."; 4322 contact "support at example.com"; 4323 description "Example Jukebox Data Model Module"; 4324 revision "2015-04-04" { 4325 description "Initial version."; 4326 reference "example.com document 1-4673"; 4328 } 4330 identity genre { 4331 description "Base for all genre types"; 4332 } 4334 // abbreviated list of genre classifications 4335 identity alternative { 4336 base genre; 4337 description "Alternative music"; 4338 } 4339 identity blues { 4340 base genre; 4341 description "Blues music"; 4342 } 4343 identity country { 4344 base genre; 4345 description "Country music"; 4346 } 4347 identity jazz { 4348 base genre; 4349 description "Jazz music"; 4350 } 4351 identity pop { 4352 base genre; 4353 description "Pop music"; 4354 } 4355 identity rock { 4356 base genre; 4357 description "Rock music"; 4358 } 4360 container jukebox { 4361 presence 4362 "An empty container indicates that the jukebox 4363 service is available"; 4365 description 4366 "Represents a jukebox resource, with a library, playlists, 4367 and a play operation."; 4369 container library { 4371 description "Represents the jukebox library resource."; 4373 list artist { 4374 key name; 4375 description 4376 "Represents one artist resource within the 4377 jukebox library resource."; 4379 leaf name { 4380 type string { 4381 length "1 .. max"; 4382 } 4383 description "The name of the artist."; 4384 } 4386 list album { 4387 key name; 4389 description 4390 "Represents one album resource within one 4391 artist resource, within the jukebox library."; 4393 leaf name { 4394 type string { 4395 length "1 .. max"; 4396 } 4397 description "The name of the album."; 4398 } 4400 leaf genre { 4401 type identityref { base genre; } 4402 description 4403 "The genre identifying the type of music on 4404 the album."; 4405 } 4407 leaf year { 4408 type uint16 { 4409 range "1900 .. max"; 4410 } 4411 description "The year the album was released"; 4412 } 4414 container admin { 4415 description 4416 "Administrative information for the album."; 4418 leaf label { 4419 type string; 4420 description "The label that released the album."; 4421 } 4422 leaf catalogue-number { 4423 type string; 4424 description "The album's catalogue number."; 4425 } 4426 } 4428 list song { 4429 key name; 4431 description 4432 "Represents one song resource within one 4433 album resource, within the jukebox library."; 4435 leaf name { 4436 type string { 4437 length "1 .. max"; 4438 } 4439 description "The name of the song"; 4440 } 4441 leaf location { 4442 type string; 4443 mandatory true; 4444 description 4445 "The file location string of the 4446 media file for the song"; 4447 } 4448 leaf format { 4449 type string; 4450 description 4451 "An identifier string for the media type 4452 for the file associated with the 4453 'location' leaf for this entry."; 4454 } 4455 leaf length { 4456 type uint32; 4457 units "seconds"; 4458 description 4459 "The duration of this song in seconds."; 4460 } 4461 } // end list 'song' 4462 } // end list 'album' 4463 } // end list 'artist' 4465 leaf artist-count { 4466 type uint32; 4467 units "songs"; 4468 config false; 4469 description "Number of artists in the library"; 4470 } 4471 leaf album-count { 4472 type uint32; 4473 units "albums"; 4474 config false; 4475 description "Number of albums in the library"; 4476 } 4477 leaf song-count { 4478 type uint32; 4479 units "songs"; 4480 config false; 4481 description "Number of songs in the library"; 4482 } 4483 } // end library 4485 list playlist { 4486 key name; 4488 description 4489 "Example configuration data resource"; 4491 leaf name { 4492 type string; 4493 description 4494 "The name of the playlist."; 4495 } 4496 leaf description { 4497 type string; 4498 description 4499 "A comment describing the playlist."; 4500 } 4501 list song { 4502 key index; 4503 ordered-by user; 4505 description 4506 "Example nested configuration data resource"; 4508 leaf index { // not really needed 4509 type uint32; 4510 description 4511 "An arbitrary integer index for this playlist song."; 4512 } 4513 leaf id { 4514 type leafref { 4515 path "/jbox:jukebox/jbox:library/jbox:artist/" + 4516 "jbox:album/jbox:song/jbox:name"; 4517 } 4518 mandatory true; 4519 description 4520 "Song identifier. Must identify an instance of 4521 /jukebox/library/artist/album/song/name."; 4522 } 4523 } 4524 } 4526 container player { 4527 description 4528 "Represents the jukebox player resource."; 4530 leaf gap { 4531 type decimal64 { 4532 fraction-digits 1; 4533 range "0.0 .. 2.0"; 4534 } 4535 units "tenths of seconds"; 4536 description "Time gap between each song"; 4537 } 4538 } 4539 } 4541 rpc play { 4542 description "Control function for the jukebox player"; 4543 input { 4544 leaf playlist { 4545 type string; 4546 mandatory true; 4547 description "playlist name"; 4548 } 4549 leaf song-number { 4550 type uint32; 4551 mandatory true; 4552 description "Song number in playlist to play"; 4553 } 4554 } 4555 } 4556 } 4558 Appendix D. RESTCONF Message Examples 4560 The examples within this document use the normative YANG module 4561 defined in Section 8 and the non-normative example YANG module 4562 defined in Appendix C.1. 4564 This section shows some typical RESTCONF message exchanges. 4566 D.1. Resource Retrieval Examples 4568 D.1.1. Retrieve the Top-level API Resource 4570 The client may start by retrieving the top-level API resource, using 4571 the entry point URI "{+restconf}". 4573 GET /restconf HTTP/1.1 4574 Host: example.com 4575 Accept: application/yang.api+json 4577 The server might respond as follows: 4579 HTTP/1.1 200 OK 4580 Date: Mon, 23 Apr 2012 17:01:00 GMT 4581 Server: example-server 4582 Content-Type: application/yang.api+json 4584 { 4585 "ietf-restconf:restconf": { 4586 "data" : {}, 4587 "operations" : {} 4588 } 4589 } 4591 To request that the response content to be encoded in XML, the 4592 "Accept" header can be used, as in this example request: 4594 GET /restconf HTTP/1.1 4595 Host: example.com 4596 Accept: application/yang.api+xml 4598 The server will return the same response either way, which might be 4599 as follows : 4601 HTTP/1.1 200 OK 4602 Date: Mon, 23 Apr 2012 17:01:00 GMT 4603 Server: example-server 4604 Cache-Control: no-cache 4605 Pragma: no-cache 4606 Content-Type: application/yang.api+xml 4608 4609 4610 4611 2016-02-01 4612 4614 D.1.2. Retrieve The Server Module Information 4616 In this example the client is retrieving the modules information from 4617 the server in JSON format: 4619 GET /restconf/data/ietf-yang-library:modules HTTP/1.1 4620 Host: example.com 4621 Accept: application/yang.data+json 4623 The server might respond as follows (some strings wrapped for display 4624 purposes): 4626 HTTP/1.1 200 OK 4627 Date: Mon, 23 Apr 2012 17:01:00 GMT 4628 Server: example-server 4629 Cache-Control: no-cache 4630 Pragma: no-cache 4631 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4632 Content-Type: application/yang.data+json 4634 { 4635 "ietf-yang-library:modules": { 4636 "module": [ 4637 { 4638 "name" : "foo", 4639 "revision" : "2012-01-02", 4640 "schema" : "https://example.com/modules/foo/2012-01-02", 4641 "namespace" : "http://example.com/ns/foo", 4642 "feature" : [ "feature1", "feature2" ], 4643 "conformance-type" : "implement" 4644 }, 4645 { 4646 "name" : "ietf-yang-library", 4647 "revision" : "2016-02-01", 4648 "schema" : "https://example.com/modules/ietf-yang- 4649 library/2016-02-01", 4650 "namespace" : 4651 "urn:ietf:params:xml:ns:yang:ietf-yang-library", 4652 "conformance-type" : "implement" 4653 }, 4654 { 4655 "name" : "foo-types", 4656 "revision" : "2012-01-05", 4657 "schema" : 4658 "https://example.com/modules/foo-types/2012-01-05", 4659 "namespace" : "http://example.com/ns/foo-types", 4660 "conformance-type" : "import" 4661 }, 4662 { 4663 "name" : "bar", 4664 "revision" : "2012-11-05", 4665 "schema" : "https://example.com/modules/bar/2012-11-05", 4666 "namespace" : "http://example.com/ns/bar", 4667 "feature" : [ "bar-ext" ], 4668 "conformance-type" : "implement", 4669 "submodule" : [ 4670 { 4671 "name" : "bar-submod1", 4672 "revision" : "2012-11-05", 4673 "schema" : 4674 "https://example.com/modules/bar-submod1/2012-11-05" 4675 }, 4676 { 4677 "name" : "bar-submod2", 4678 "revision" : "2012-11-05", 4679 "schema" : 4680 "https://example.com/modules/bar-submod2/2012-11-05" 4681 } 4682 ] 4683 } 4684 ] 4685 } 4686 } 4688 D.1.3. Retrieve The Server Capability Information 4690 In this example the client is retrieving the capability information 4691 from the server in XML format, and the server supports all the 4692 RESTCONF query parameters, plus one vendor parameter: 4694 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 4695 capabilities HTTP/1.1 4696 Host: example.com 4697 Accept: application/yang.data+xml 4699 The server might respond as follows. The extra whitespace in 4700 'capability' elements for display purposes only. 4702 HTTP/1.1 200 OK 4703 Date: Mon, 23 Apr 2012 17:02:00 GMT 4704 Server: example-server 4705 Cache-Control: no-cache 4706 Pragma: no-cache 4707 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 4708 Content-Type: application/yang.data+xml 4709 4710 4711 urn:ietf:params:restconf:capability:depth:1.0 4712 4713 4714 urn:ietf:params:restconf:capability:fields:1.0 4715 4716 4717 urn:ietf:params:restconf:capability:filter:1.0 4718 4719 4720 urn:ietf:params:restconf:capability:start-time:1.0 4721 4722 4723 urn:ietf:params:restconf:capability:stop-time:1.0 4724 4725 4726 http://example.com/capabilities/myparam 4727 4728 4730 D.2. Edit Resource Examples 4732 D.2.1. Create New Data Resources 4734 To create a new "artist" resource within the "library" resource, the 4735 client might send the following request. 4737 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 4738 Host: example.com 4739 Content-Type: application/yang.data+json 4741 { 4742 "example-jukebox:artist" : { 4743 "name" : "Foo Fighters" 4744 } 4745 } 4747 If the resource is created, the server might respond as follows. 4748 Note that the "Location" header line is wrapped for display purposes 4749 only: 4751 HTTP/1.1 201 Created 4752 Date: Mon, 23 Apr 2012 17:02:00 GMT 4753 Server: example-server 4754 Location: https://example.com/restconf/data/ 4755 example-jukebox:jukebox/library/artist=Foo%20Fighters 4756 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 4757 ETag: b3830f23a4c 4759 To create a new "album" resource for this artist within the "jukebox" 4760 resource, the client might send the following request. Note that the 4761 request URI header line is wrapped for display purposes only: 4763 POST /restconf/data/example-jukebox:jukebox/ 4764 library/artist=Foo%20Fighters HTTP/1.1 4765 Host: example.com 4766 Content-Type: application/yang.data+xml 4768 4769 Wasting Light 4770 2011 4771 4773 If the resource is created, the server might respond as follows. 4774 Note that the "Location" header line is wrapped for display purposes 4775 only: 4777 HTTP/1.1 201 Created 4778 Date: Mon, 23 Apr 2012 17:03:00 GMT 4779 Server: example-server 4780 Location: https://example.com/restconf/data/ 4781 example-jukebox:jukebox/library/artist=Foo%20Fighters/ 4782 album=Wasting%20Light 4783 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 4784 ETag: b8389233a4c 4786 D.2.2. Detect Resource Entity Tag Change 4788 In this example, the server just supports the mandatory datastore 4789 last-changed timestamp. The client has previously retrieved the 4790 "Last-Modified" header and has some value cached to provide in the 4791 following request to patch an "album" list entry with key value 4792 "Wasting Light". Only the "genre" field is being updated. 4794 PATCH /restconf/data/example-jukebox:jukebox/ 4795 library/artist=Foo%20Fighters/album=Wasting%20Light/genre 4796 HTTP/1.1 4797 Host: example.com 4798 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 4799 Content-Type: application/yang.data+json 4801 { "example-jukebox:genre" : "example-jukebox:alternative" } 4803 In this example the datastore resource has changed since the time 4804 specified in the "If-Unmodified-Since" header. The server might 4805 respond: 4807 HTTP/1.1 412 Precondition Failed 4808 Date: Mon, 23 Apr 2012 19:01:00 GMT 4809 Server: example-server 4810 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 4811 ETag: b34aed893a4c 4813 D.2.3. Edit a Datastore Resource 4815 In this example, the client modifies two different data nodes by 4816 sending a PATCH to the datastore resource: 4818 PATCH /restconf/data HTTP/1.1 4819 Host: example.com 4820 Content-Type: application/yang.datastore+xml 4822 4823 4824 4825 4826 Foo Fighters 4827 4828 Wasting Light 4829 2011 4830 4831 4832 4833 Nick Cave 4834 4835 Tender Prey 4836 1988 4837 4838 4839 4840 4841 4843 D.3. Query Parameter Examples 4845 D.3.1. "content" Parameter 4846 The "content" parameter is used to select the type of data child 4847 resources (configuration and/or not configuration) that are returned 4848 by the server for a GET method request. 4850 In this example, a simple YANG list that has configuration and non- 4851 configuration child resources. 4853 container events 4854 list event { 4855 key name; 4856 leaf name { type string; } 4857 leaf description { type string; } 4858 leaf event-count { 4859 type uint32; 4860 config false; 4861 } 4862 } 4863 } 4865 Example 1: content=all 4867 To retrieve all the child resources, the "content" parameter is set 4868 to "all". The client might send: 4870 GET /restconf/data/example-events:events?content=all 4871 HTTP/1.1 4872 Host: example.com 4873 Accept: application/yang.data+json 4875 The server might respond: 4877 HTTP/1.1 200 OK 4878 Date: Mon, 23 Apr 2012 17:11:30 GMT 4879 Server: example-server 4880 Cache-Control: no-cache 4881 Pragma: no-cache 4882 Content-Type: application/yang.data+json 4884 { 4885 "example-events:events" : { 4886 "event" : [ 4887 { 4888 "name" : "interface-up", 4889 "description" : "Interface up notification count", 4890 "event-count" : 42 4891 }, 4892 { 4893 "name" : "interface-down", 4894 "description" : "Interface down notification count", 4895 "event-count" : 4 4896 } 4897 ] 4898 } 4899 } 4901 Example 2: content=config 4903 To retrieve only the configuration child resources, the "content" 4904 parameter is set to "config" or omitted since this is the default 4905 value. Note that the "ETag" and "Last-Modified" headers are only 4906 returned if the content parameter value is "config". 4908 GET /restconf/data/example-events:events?content=config 4909 HTTP/1.1 4910 Host: example.com 4911 Accept: application/yang.data+json 4913 The server might respond: 4915 HTTP/1.1 200 OK 4916 Date: Mon, 23 Apr 2012 17:11:30 GMT 4917 Server: example-server 4918 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 4919 ETag: eeeada438af 4920 Cache-Control: no-cache 4921 Pragma: no-cache 4922 Content-Type: application/yang.data+json 4924 { 4925 "example-events:events" : { 4926 "event" : [ 4927 { 4928 "name" : "interface-up", 4929 "description" : "Interface up notification count" 4930 }, 4931 { 4932 "name" : "interface-down", 4933 "description" : "Interface down notification count" 4934 } 4935 ] 4936 } 4937 } 4939 Example 3: content=nonconfig 4940 To retrieve only the non-configuration child resources, the "content" 4941 parameter is set to "nonconfig". Note that configuration ancestors 4942 (if any) and list key leafs (if any) are also returned. The client 4943 might send: 4945 GET /restconf/data/example-events:events?content=nonconfig 4946 HTTP/1.1 4947 Host: example.com 4948 Accept: application/yang.data+json 4950 The server might respond: 4952 HTTP/1.1 200 OK 4953 Date: Mon, 23 Apr 2012 17:11:30 GMT 4954 Server: example-server 4955 Cache-Control: no-cache 4956 Pragma: no-cache 4957 Content-Type: application/yang.data+json 4959 { 4960 "example-events:events" : { 4961 "event" : [ 4962 { 4963 "name" : "interface-up", 4964 "event-count" : 42 4965 }, 4966 { 4967 "name" : "interface-down", 4968 "event-count" : 4 4969 } 4970 ] 4971 } 4972 } 4974 D.3.2. "depth" Parameter 4976 The "depth" parameter is used to limit the number of levels of child 4977 resources that are returned by the server for a GET method request. 4979 The depth parameter starts counting levels at the level of the target 4980 resource that is specified, so that a depth level of "1" includes 4981 just the target resource level itself. A depth level of "2" includes 4982 the target resource level and its child nodes. 4984 This example shows how different values of the "depth" parameter 4985 would affect the reply content for retrieval of the top-level 4986 "jukebox" data resource. 4988 Example 1: depth=unbounded 4990 To retrieve all the child resources, the "depth" parameter is not 4991 present or set to the default value "unbounded". Note that some 4992 strings are wrapped for display purposes only. 4994 GET /restconf/data/example-jukebox:jukebox?depth=unbounded 4995 HTTP/1.1 4996 Host: example.com 4997 Accept: application/yang.data+json 4999 The server might respond: 5001 HTTP/1.1 200 OK 5002 Date: Mon, 23 Apr 2012 17:11:30 GMT 5003 Server: example-server 5004 Cache-Control: no-cache 5005 Pragma: no-cache 5006 Content-Type: application/yang.data+json 5008 { 5009 "example-jukebox:jukebox" : { 5010 "library" : { 5011 "artist" : [ 5012 { 5013 "name" : "Foo Fighters", 5014 "album" : [ 5015 { 5016 "name" : "Wasting Light", 5017 "genre" : "example-jukebox:alternative", 5018 "year" : 2011, 5019 "song" : [ 5020 { 5021 "name" : "Wasting Light", 5022 "location" : 5023 "/media/foo/a7/wasting-light.mp3", 5024 "format" : "MP3", 5025 "length" " 286 5026 }, 5027 { 5028 "name" : "Rope", 5029 "location" : "/media/foo/a7/rope.mp3", 5030 "format" : "MP3", 5031 "length" " 259 5032 } 5033 ] 5034 } 5035 ] 5037 } 5038 ] 5039 }, 5040 "playlist" : [ 5041 { 5042 "name" : "Foo-One", 5043 "description" : "example playlist 1", 5044 "song" : [ 5045 { 5046 "index" : 1, 5047 "id" : "https://example.com/restconf/data/ 5048 example-jukebox:jukebox/library/artist= 5049 Foo%20Fighters/album=Wasting%20Light/ 5050 song=Rope" 5051 }, 5052 { 5053 "index" : 2, 5054 "id" : "https://example.com/restconf/data/ 5055 example-jukebox:jukebox/library/artist= 5056 Foo%20Fighters/album=Wasting%20Light/song= 5057 Bridge%20Burning" 5058 } 5059 ] 5060 } 5061 ], 5062 "player" : { 5063 "gap" : 0.5 5064 } 5065 } 5066 } 5068 Example 2: depth=1 5070 To determine if 1 or more resource instances exist for a given target 5071 resource, the value "1" is used. 5073 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 5074 Host: example.com 5075 Accept: application/yang.data+json 5077 The server might respond: 5079 HTTP/1.1 200 OK 5080 Date: Mon, 23 Apr 2012 17:11:30 GMT 5081 Server: example-server 5082 Cache-Control: no-cache 5083 Pragma: no-cache 5084 Content-Type: application/yang.data+json 5085 { 5086 "example-jukebox:jukebox" : {} 5087 } 5089 Example 3: depth=3 5091 To limit the depth level to the target resource plus 2 child resource 5092 layers the value "3" is used. 5094 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 5095 Host: example.com 5096 Accept: application/yang.data+json 5098 The server might respond: 5100 HTTP/1.1 200 OK 5101 Date: Mon, 23 Apr 2012 17:11:30 GMT 5102 Server: example-server 5103 Cache-Control: no-cache 5104 Pragma: no-cache 5105 Content-Type: application/yang.data+json 5107 { 5108 "example-jukebox:jukebox" : { 5109 "library" : { 5110 "artist" : {} 5111 }, 5112 "playlist" : [ 5113 { 5114 "name" : "Foo-One", 5115 "description" : "example playlist 1", 5116 "song" : {} 5117 } 5118 ], 5119 "player" : { 5120 "gap" : 0.5 5121 } 5122 } 5123 } 5125 D.3.3. "fields" Parameter 5127 In this example the client is retrieving the API resource, but 5128 retrieving only the "name" and "revision" nodes from each module, in 5129 JSON format: 5131 GET /restconf/data?fields=ietf-yang-library:modules/ 5132 module(name;revision) HTTP/1.1 5134 Host: example.com 5135 Accept: application/yang.data+json 5137 The server might respond as follows. 5139 HTTP/1.1 200 OK 5140 Date: Mon, 23 Apr 2012 17:01:00 GMT 5141 Server: example-server 5142 Content-Type: application/yang.data+json 5144 { 5145 "ietf-yang-library:modules": { 5146 "module": [ 5147 { 5148 "name" : "example-jukebox", 5149 "revision" : "2015-06-04" 5150 }, 5151 { 5152 "name" : "ietf-inet-types", 5153 "revision" : "2013-07-15" 5154 }, 5155 { 5156 "name" : "ietf-restconf-monitoring", 5157 "revision" : "2015-06-19" 5158 }, 5159 { 5160 "name" : "ietf-yang-library", 5161 "revision" : "2016-02-01" 5162 }, 5163 { 5164 "name" : "ietf-yang-types", 5165 "revision" : "2013-07-15" 5166 } 5168 ] 5169 } 5170 } 5172 D.3.4. "insert" Parameter 5174 In this example, a new first entry in the "Foo-One" playlist is being 5175 created. 5177 Request from client: 5179 POST /restconf/data/example-jukebox:jukebox/ 5180 playlist=Foo-One?insert=first HTTP/1.1 5181 Host: example.com 5182 Content-Type: application/yang.data+json 5184 { 5185 "example-jukebox:song" : { 5186 "index" : 1, 5187 "id" : "/example-jukebox:jukebox/library/ 5188 artist=Foo%20Fighters/album=Wasting%20Light/song=Rope" 5189 } 5190 } 5192 Response from server: 5194 HTTP/1.1 201 Created 5195 Date: Mon, 23 Apr 2012 13:01:20 GMT 5196 Server: example-server 5197 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5198 Location: https://example.com/restconf/data/ 5199 example-jukebox:jukebox/playlist=Foo-One/song=1 5200 ETag: eeeada438af 5202 D.3.5. "point" Parameter 5204 In this example, the client is inserting a new "song" resource within 5205 an "album" resource after another song. The request URI is split for 5206 display purposes only. 5208 Request from client: 5210 POST /restconf/data/example-jukebox:jukebox/ 5211 library/artist=Foo%20Fighters/album=Wasting%20Light? 5212 insert=after&point=%2Fexample-jukebox%3Ajukebox%2F 5213 library%2Fartist%3DFoo%20Fighters%2Falbum%3D 5214 Wasting%20Light%2Fsong%3DBridge%20Burning HTTP/1.1 5215 Host: example.com 5216 Content-Type: application/yang.data+json 5218 { 5219 "example-jukebox:song" : { 5220 "name" : "Rope", 5221 "location" : "/media/foo/a7/rope.mp3", 5222 "format" : "MP3", 5223 "length" : 259 5224 } 5225 } 5227 Response from server: 5229 HTTP/1.1 204 No Content 5230 Date: Mon, 23 Apr 2012 13:01:20 GMT 5231 Server: example-server 5232 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5233 ETag: abcada438af 5235 D.3.6. "filter" Parameter 5237 The following URIs show some examples of notification filter 5238 specifications (lines wrapped for display purposes only): 5240 // filter = /event/event-class='fault' 5241 GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' 5243 // filter = /event/severity<=4 5244 GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 5246 // filter = /linkUp|/linkDown 5247 GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown 5249 // filter = /*/reporting-entity/card!='Ethernet0' 5250 GET /streams/NETCONF? 5251 filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' 5253 // filter = /*/email-addr[contains(.,'company.com')] 5254 GET /streams/critical-syslog? 5255 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 5257 // Note: the module name is used as prefix. 5258 // filter = (/example-mod:event1/name='joe' and 5259 // /example-mod:event1/status='online') 5260 GET /streams/NETCONF? 5261 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and 5262 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 5264 // To get notifications from just two modules (e.g., m1 + m2) 5265 // filter=(/m1:* or /m2:*) 5266 GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*) 5268 D.3.7. "start-time" Parameter 5270 // start-time = 2014-10-25T10:02:00Z 5271 GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z 5273 D.3.8. "stop-time" Parameter 5275 // stop-time = 2014-10-25T12:31:00Z 5276 GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z 5278 D.3.9. "with-defaults" Parameter 5280 The following YANG module is assumed for this example. 5282 module example-interface { 5283 prefix "exif"; 5284 namespace "urn:example.com:params:xml:ns:yang:example-interface"; 5286 container interfaces { 5287 list interface { 5288 key name; 5289 leaf name { type string; } 5290 leaf mtu { type uint32; } 5291 leaf status { 5292 config false; 5293 type enumeration { 5294 enum up; 5295 enum down; 5296 enum testing; 5297 } 5298 } 5299 } 5300 } 5301 } 5303 Assume the same data model as defined in Appendix A.1 of [RFC6243]. 5304 Assume the same data set as defined in Appendix A.2 of [RFC6243]. If 5305 the server defaults-uri basic-mode is "trim", the the following 5306 request for interface "eth1" might be as follows: 5308 Without query parameter: 5310 GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1 5311 Host: example.com 5312 Accept: application/yang.data+json 5314 The server might respond as follows. 5316 HTTP/1.1 200 OK 5317 Date: Mon, 23 Apr 2012 17:01:00 GMT 5318 Server: example-server 5319 Content-Type: application/yang.data+json 5321 { 5322 "example:interface": [ 5323 { 5324 "name" : "eth1", 5325 "status" : "up" 5327 } 5328 ] 5329 } 5331 Note that the "mtu" leaf is missing because it is set to the default 5332 "1500", and the server defaults handling basic-mode is "trim". 5334 With query parameter: 5336 GET /restconf/data/example:interfaces/interface=eth1 5337 ?with-defaults=report-all HTTP/1.1 5338 Host: example.com 5339 Accept: application/yang.data+json 5341 The server might respond as follows. 5343 HTTP/1.1 200 OK 5344 Date: Mon, 23 Apr 2012 17:01:00 GMT 5345 Server: example-server 5346 Content-Type: application/yang.data+json 5348 { 5349 "example:interface": [ 5350 { 5351 "name" : "eth1", 5352 "mtu" : 1500, 5353 "status" : "up" 5354 } 5355 ] 5356 } 5358 Note that the server returns the "mtu" leaf because the "report-all" 5359 mode was requested with the "with-defaults" query parameter. 5361 Authors' Addresses 5363 Andy Bierman 5364 YumaWorks 5366 Email: andy@yumaworks.com 5368 Martin Bjorklund 5369 Tail-f Systems 5371 Email: mbj@tail-f.com 5372 Kent Watsen 5373 Juniper Networks 5375 Email: kwatsen@juniper.net