idnits 2.17.1 draft-ietf-netconf-restconf-15.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 2496 has weird spacing: '... method entry...' == Line 3410 has weird spacing: '...ncoding strin...' == Line 3411 has weird spacing: '...ocation inet:...' == Line 4707 has weird spacing: '...ocation str...' == Line 4717 has weird spacing: '...w index uin...' == (1 more instance...) -- The document date (July 7, 2016) is 2850 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) == Missing Reference: 'RFCXXXX' is mentioned on line 3914, but not defined ** 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) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPath' == Outdated reference: A later version (-14) exists of draft-ietf-netconf-yang-patch-08 Summary: 11 errors (**), 0 flaws (~~), 9 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: January 8, 2017 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 July 7, 2016 10 RESTCONF Protocol 11 draft-ietf-netconf-restconf-15 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 datastore concepts 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 January 8, 2017. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 55 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 6 56 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6 57 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7 58 1.1.4. NETCONF Notifications . . . . . . . . . . . . . . . . 7 59 1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 60 1.1.6. URI Template and Examples . . . . . . . . . . . . . . 10 61 1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10 62 1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 10 63 1.3. Data Model Driven API . . . . . . . . . . . . . . . . . . 11 64 1.4. Coexistence with NETCONF . . . . . . . . . . . . . . . . 12 65 1.5. RESTCONF Extensibility . . . . . . . . . . . . . . . . . 13 66 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 14 67 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 14 68 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 14 69 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 14 70 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 15 71 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 15 72 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 15 73 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 16 74 3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 17 75 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 18 76 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 19 77 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 19 78 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 20 79 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 20 80 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 21 81 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 22 82 3.5.1. Timestamp . . . . . . . . . . . . . . . . . . . . . . 22 83 3.5.2. Entity tag . . . . . . . . . . . . . . . . . . . . . 23 84 3.5.3. Encoding Data Resource Identifiers in the Request URI 23 85 3.5.4. Defaults Handling . . . . . . . . . . . . . . . . . . 26 86 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 27 87 3.6.1. Encoding Operation Resource Input Parameters . . . . 29 88 3.6.2. Encoding Operation Resource Output Parameters . . . . 32 89 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 34 90 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 35 91 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 36 92 3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 37 93 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 37 94 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 38 95 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 38 96 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 97 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 40 98 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 40 99 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 41 100 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 101 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 44 102 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 44 103 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 45 104 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 46 105 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 47 106 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 47 107 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 48 108 4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 49 109 4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 50 110 4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 50 111 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 51 112 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 52 113 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 52 114 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 53 115 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 53 116 5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 55 117 5.3. RESTCONF Metadata . . . . . . . . . . . . . . . . . . . . 55 118 5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 56 119 5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 56 120 5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 57 121 5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 57 122 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 57 123 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 58 124 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 58 125 6.3. Subscribing to Receive Notifications . . . . . . . . . . 59 126 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 60 127 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 61 128 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 63 129 7.1. Error Response Message . . . . . . . . . . . . . . . . . 64 130 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 66 131 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 72 132 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 73 133 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 73 134 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 74 135 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 75 136 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 75 138 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 79 139 10.1. modules-state . . . . . . . . . . . . . . . . . . . . . 79 140 10.1.1. modules-state/module . . . . . . . . . . . . . . . . 79 141 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 142 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 79 143 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 80 144 11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 80 145 11.3.1. Media Type application/yang-data . . . . . . . . . . 80 146 11.3.2. Media Type application/yang-data+json . . . . . . . 82 147 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 84 148 12. Security Considerations . . . . . . . . . . . . . . . . . . . 84 149 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 85 150 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 86 151 14.1. Normative References . . . . . . . . . . . . . . . . . . 86 152 14.2. Informative References . . . . . . . . . . . . . . . . . 89 153 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 89 154 A.1. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . 89 155 A.2. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 89 156 A.3. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 91 157 A.4. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 91 158 A.5. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 92 159 A.6. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 93 160 A.7. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 95 161 A.8. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 95 162 A.9. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 95 163 A.10. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 96 164 A.11. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 96 165 A.12. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 97 166 A.13. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 97 167 A.14. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 98 168 A.15. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 99 169 A.16. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 99 170 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 100 171 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 100 172 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 101 173 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 106 174 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 106 175 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 106 176 D.1.2. Retrieve The Server Module Information . . . . . . . 108 177 D.1.3. Retrieve The Server Capability Information . . . . . 109 178 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 110 179 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 110 180 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 112 181 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 112 182 D.2.4. Edit a Data Resource . . . . . . . . . . . . . . . . 113 183 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 113 184 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 113 185 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 116 186 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 119 187 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 120 188 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 121 189 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 122 190 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 122 191 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 122 192 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 123 193 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 124 195 1. Introduction 197 There is a need for standard mechanisms to allow Web applications to 198 access the configuration data, state data, data-model specific RPC 199 operations, and event notifications within a networking device, in a 200 modular and extensible manner. 202 This document defines an HTTP [RFC7230] based protocol called 203 RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or 204 YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using the datastore 205 concepts defined in NETCONF [RFC6241]. 207 NETCONF defines configuration datastores and a set of Create, 208 Retrieve, Update, Delete (CRUD) operations that can be used to access 209 these datastores. The YANG language defines the syntax and semantics 210 of datastore content, configuration, state data, RPC operations, and 211 event notifications. 213 RESTCONF uses HTTP methods to provide CRUD operations on a conceptual 214 datastore containing YANG-defined data, which is compatible with a 215 server which implements NETCONF datastores. 217 If a RESTCONF server is co-located with a NETCONF server, then there 218 are protocol interactions to be considered, as described in 219 Section 1.4. The RESTCONF server MAY provide access to specific 220 datastores using operation resources, as described in Section 3.6. 222 Configuration data and state data are exposed as resources that can 223 be retrieved with the GET method. Resources representing 224 configuration data can be modified with the DELETE, PATCH, POST, and 225 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 226 or JSON [RFC7159]. 228 Data-model specific RPC operations defined with the YANG "rpc" or 229 "action" statements can be invoked with the POST method. Data-model 230 specific event notifications defined with the YANG "notification" 231 statement can be accessed. 233 1.1. Terminology 235 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 236 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 237 document are to be interpreted as described in [RFC2119]. 239 1.1.1. NETCONF 241 The following terms are defined in [RFC6241]: 243 o candidate configuration datastore 245 o configuration data 247 o datastore 249 o configuration datastore 251 o running configuration datastore 253 o startup configuration datastore 255 o state data 257 o user 259 1.1.2. HTTP 261 The following terms are defined in [RFC3986]: 263 o fragment 265 o path 267 o query 269 The following terms are defined in [RFC7230]: 271 o header 273 o message-body 275 o request-line 277 o request URI 279 o status-line 280 The following terms are defined in [RFC7231]: 282 o method 284 o request 286 o resource 288 The following terms are defined in [RFC7232]: 290 o entity tag 292 1.1.3. YANG 294 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 296 o action 298 o container 300 o data node 302 o key leaf 304 o leaf 306 o leaf-list 308 o list 310 o mandatory node 312 o ordered-by user 314 o presence container 316 o RPC operation 318 o top-level data node 320 1.1.4. NETCONF Notifications 322 The following terms are defined in [RFC5277]: 324 o notification replay 326 1.1.5. Terms 327 The following terms are used within this document: 329 o API resource: a resource that models the RESTCONF entry point and 330 the sub-resources to access YANG-defined content. It is defined 331 with the YANG data template named "yang-api" in the 332 "ietf-restconf" module. 334 o data resource: a resource that models a YANG data node. It is 335 defined with YANG data definition statements, and YANG containers, 336 leafs, leaf-list entries, list entries, anydata and anyxml nodes 337 can be data resources. 339 o datastore resource: a resource that models a programmatic 340 interface to NETCONF datastores. By default, RESTCONF methods 341 access a unified view of the underlying datastore implementation 342 on the server. It is defined as a sub-resource within the API 343 resource. 345 o edit operation: a RESTCONF operation on a data resource using 346 either a POST, PUT, PATCH, or DELETE method. This is not the same 347 as the NETCONF edit operation (i.e., one of the values for the 348 "nc:operation" attribute: "create", "replace", "merge", "delete", 349 or "remove"). 351 o event stream resource: This resource represents an SSE (Server- 352 Sent Events) event stream. The content consists of text using the 353 media type "text/event-stream", as defined by the SSE 354 [W3C.REC-eventsource-20150203] specification. Each event 355 represents one message generated by the server. It 356 contains a conceptual system or data-model specific event that is 357 delivered within an event notification stream. Also called a 358 "stream resource". 360 o media-type: HTTP uses Internet media types [RFC2046] in the 361 Content-Type and Accept header fields in order to provide open and 362 extensible data typing and type negotiation. 364 o NETCONF client: a client which implements the NETCONF protocol. 365 Called "client" in [RFC6241]. 367 o NETCONF server: a server which implements the NETCONF protocol. 368 Called "server" in [RFC6241]. 370 o operation: the conceptual RESTCONF operation for a message, 371 derived from the HTTP method, request URI, headers, and message- 372 body. 374 o operation resource: a resource that models a data-model specific 375 operation, that is defined with a YANG "rpc" or "action" 376 statement. It is invoked with the POST method. 378 o patch: a generic PATCH request on the target datastore or data 379 resource. The media type of the message-body content will 380 identify the patch type in use. 382 o plain patch: a specific PATCH request type, defined in 383 Section 4.6.1, that can be used for simple merge operations. It 384 has a representation with the media-type "application/yang-data" 385 or "application/yang-data+json". 387 o query parameter: a parameter (and its value if any), encoded 388 within the query component of the request URI. 390 o RESTCONF capability: An optional RESTCONF protocol feature 391 supported by the server, which is identified by an IANA registered 392 NETCONF Capability URI, and advertised with an entry in the 393 "capability" leaf-list in Section 9.3. 395 o RESTCONF client: a client which implements the RESTCONF protocol. 396 Also called "client". 398 o RESTCONF server: a server which implements the RESTCONF protocol. 399 Also called "server". 401 o retrieval request: a request using the GET or HEAD methods. 403 o target resource: the resource that is associated with a particular 404 message, identified by the "path" component of the request URI. 406 o schema resource: a resource that has a representation with the 407 media type "application/yang". The schema resource is used by the 408 client to retrieve the YANG schema with the GET method. 410 o stream list: the set of data resource instances that describe the 411 event stream resources available from the server. This 412 information is defined in the "ietf-restconf-monitoring" module as 413 the "stream" list. It can be retrieved using the target resource 414 "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/ 415 stream". The stream list contains information about each stream, 416 such as the URL to retrieve the event stream data. 418 o YANG data template: a schema for modeling a conceptual data 419 structure in an encoding-independent manner. It is defined with 420 the "yang-data" extension, found in Section 8. It has a 421 representation with the media-type "application/yang-data" or 422 "application/yang-data+json". 424 1.1.6. URI Template and Examples 426 Throughout this document, the URI template [RFC6570] syntax 427 "{+restconf}" is used to refer to the RESTCONF API entry point 428 outside of an example. See Section 3.1 for details. 430 For simplicity, all of the examples in this document assume "/ 431 restconf" as the discovered RESTCONF API root path. 433 Many of the examples throughout the document are based on the 434 "example-jukebox" YANG module, defined in Appendix C.1. 436 1.1.7. Tree Diagrams 438 A simplified graphical representation of the data model is used in 439 this document. The meaning of the symbols in these diagrams is as 440 follows: 442 o Brackets "[" and "]" enclose list keys. 444 o Abbreviations before data node names: "rw" means configuration 445 data (read-write) and "ro" state data (read-only). 447 o Symbols after data node names: "?" means an optional node, "!" 448 means a presence container, and "*" denotes a list and leaf-list. 450 o Parentheses enclose choice and case nodes, and case nodes are also 451 marked with a colon (":"). 453 o Ellipsis ("...") stands for contents of subtrees that are not 454 shown. 456 1.2. Subset of NETCONF Functionality 458 RESTCONF does not need to mirror the full functionality of the 459 NETCONF protocol, but it does need to be compatible with NETCONF. 460 RESTCONF achieves this by implementing a subset of the interaction 461 capabilities provided by the NETCONF protocol, for instance, by 462 eliminating datastores and explicit locking. 464 RESTCONF uses HTTP methods to implement the equivalent of NETCONF 465 operations, enabling basic CRUD operations on a hierarchy of 466 conceptual resources. 468 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 469 resources represented by YANG data models. These basic edit 470 operations allow the running configuration to be altered in an all- 471 or-none fashion. 473 RESTCONF is not intended to replace NETCONF, but rather provide an 474 additional interface that follows Representational State Transfer 475 (REST) principles [rest-dissertation], and is compatible with a 476 resource-oriented device abstraction. 478 The following figure shows the system components if a RESTCONF server 479 is co-located with a NETCONF server: 481 +-----------+ +-----------------+ 482 | Web app | <-------> | | 483 +-----------+ HTTP | network device | 484 | | 485 +-----------+ | +-----------+ | 486 | NMS app | <-------> | | datastore | | 487 +-----------+ NETCONF | +-----------+ | 488 +-----------------+ 490 The following figure shows the system components if a RESTCONF server 491 is implemented in a device that does not have a NETCONF server: 493 +-----------+ +-----------------+ 494 | Web app | <-------> | | 495 +-----------+ HTTP | network device | 496 | | 497 +-----------------+ 499 1.3. Data Model Driven API 501 RESTCONF combines the simplicity of the HTTP protocol with the 502 predictability and automation potential of a schema-driven API. 503 Using YANG, a client can predict all management resources, much like 504 using URI Templates [RFC6570], but in a more holistic manner. This 505 strategy obviates the need for responses provided by the server to 506 contain Hypermedia as the Engine of Application State (HATEOAS) 507 links, originally described in Roy Fielding's doctoral dissertation 508 [rest-dissertation], because the client can determine the links it 509 needs from the YANG modules. 511 RESTCONF provides the YANG module capability information supported by 512 the server, in case the client wants to use it. The URIs for data- 513 model specific RPC operations and datastore content are predictable, 514 based on the YANG module definitions. 516 The RESTCONF protocol operates on a conceptual datastore defined with 517 the YANG data modeling language. The server lists each YANG module 518 it supports using the "ietf-yang-library" YANG module, defined in 519 [I-D.ietf-netconf-yang-library]. The server MUST implement the 520 "ietf-yang-library" module, which MUST identify all the YANG modules 521 used by the server. 523 The conceptual datastore contents, data-model-specific operations and 524 event notifications are identified by this set of YANG modules. 526 The classification of data as configuration or non-configuration is 527 derived from the YANG "config" statement. Data ordering behavior is 528 derived from the YANG "ordered-by" statement. 530 The RESTCONF datastore editing model is simple and direct, similar to 531 the behavior of the :writable-running capability in NETCONF. Each 532 RESTCONF edit of a datastore resource is activated upon successful 533 completion of the transaction. 535 1.4. Coexistence with NETCONF 537 RESTCONF can be implemented on a device that supports NETCONF. 539 If the device supports :writable-running, all edits to configuration 540 nodes in {+restconf}/data are performed in the running configuration 541 datastore. The URI template "{+restconf}" is defined in 542 Section 1.1.6. 544 Otherwise, if the device supports :candidate, all edits to 545 configuration nodes in {+restconf}/data are performed in the 546 candidate configuration datastore. The candidate MUST be 547 automatically committed to running immediately after each successful 548 edit. Any edits from other sources that are in the candidate 549 datastore will also be committed. If a confirmed-commit procedure is 550 in progress, then this commit will act as the confirming commit. If 551 the server is expecting a "persist-id" parameter to complete the 552 confirmed commit procedure then the RESTCONF edit operation MUST fail 553 with a "409 Conflict" status-line. 555 If the device supports :startup, the device MUST automatically update 556 the non-volatile "startup datastore", after the running datastore has 557 been updated as a consequence of a RESTCONF edit operation. 559 If a datastore that would be modified by a RESTCONF operation has an 560 active lock from a NETCONF client, the RESTCONF edit operation MUST 561 fail with a "409 Conflict" status-line. 563 1.5. RESTCONF Extensibility 565 There are two extensibility mechanisms built into RESTCONF: 567 o protocol version 569 o optional capabilities 571 This document defines version 1 of the RESTCONF protocol. If a 572 future version of this protocol is defined, then that document will 573 specify how the new version of RESTCONF is identified. It is 574 expected that a different entry point {+restconf2} would be defined. 575 The server will advertise all protocol versions that it supports in 576 its host-meta data. 578 In this example, the server supports both RESTCONF version 1 and a 579 fictitious version 2. 581 Request 582 ------- 583 GET /.well-known/host-meta HTTP/1.1 584 Host: example.com 585 Accept: application/xrd+xml 587 Response 588 -------- 589 HTTP/1.1 200 OK 590 Content-Type: application/xrd+xml 591 Content-Length: nnn 593 594 595 596 598 RESTCONF also supports a server-defined list of optional 599 capabilities, which are listed by a server using the 600 "ietf-restconf-monitoring" module defined in Section 9.3. This 601 document defines several query parameters in Section 4.8. Each 602 optional parameter has a corresponding capability URI defined in 603 Section 9.1.1 that is advertised by the server if supported. 605 The "capabilities" list can identify any sort of server extension. 606 Typically this extension mechanism is used to identify optional query 607 parameters but it is not limited to that purpose. For example, the 608 "defaults" URI defined in Section 9.1.2 specifies a mandatory URI 609 identifying server defaults handling behavior. 611 A new sub-resource type could be identified with a capability if it 612 is optional to implement. Mandatory protocol features and new 613 resource types require a new revision of the RESTCONF protocol. 615 2. Transport Protocol Requirements 617 2.1. Integrity and Confidentiality 619 HTTP [RFC7230] is an application layer protocol that may be layered 620 on any reliable transport-layer protocol. RESTCONF is defined on top 621 of HTTP, but due to the sensitive nature of the information conveyed, 622 RESTCONF requires that the transport-layer protocol provides both 623 data integrity and confidentiality. A RESTCONF server MUST support 624 the TLS protocol [RFC5246]. The RESTCONF protocol MUST NOT be used 625 over HTTP without using the TLS protocol. 627 HTTP/2 [RFC7540] MAY be used for RESTCONF. The server MUST respond 628 using a single HTTP/2 stream for all client requests from a stream. 629 The server MAY respond using same HTTP/2 stream that was used for the 630 corresponding request. 632 2.2. HTTPS with X.509v3 Certificates 634 Given the nearly ubiquitous support for HTTP over TLS [RFC7230], 635 RESTCONF implementations MUST support the "https" URI scheme, which 636 has the IANA assigned default port 443. 638 RESTCONF servers MUST present an X.509v3 based certificate when 639 establishing a TLS connection with a RESTCONF client. The use the 640 X.509v3 based certificates is consistent with NETCONF over TLS 641 [RFC7589]. 643 2.3. Certificate Validation 645 The RESTCONF client MUST either use X.509 certificate path validation 646 [RFC5280] to verify the integrity of the RESTCONF server's TLS 647 certificate, or match the presented X.509 certificate with locally 648 configured certificate fingerprints. 650 The presented X.509 certificate MUST also be considered valid if it 651 matches a locally configured certificate fingerprint. If X.509 652 certificate path validation fails and the presented X.509 certificate 653 does not match a locally configured certificate fingerprint, the 654 connection MUST be terminated as defined in [RFC5246]. 656 2.4. Authenticated Server Identity 658 The RESTCONF client MUST check the identity of the server according 659 to Section 6 of [RFC6125], including processing the outcome as 660 described in Section 6.6 of [RFC6125]. 662 2.5. Authenticated Client Identity 664 The RESTCONF server MUST authenticate client access to any protected 665 resource. If the RESTCONF client is not authenticated, the server 666 SHOULD send an HTTP response with "401 Unauthorized" status-line, as 667 defined in Section 3.1 of [RFC7235]. 669 To authenticate a client, a RESTCONF server MUST use TLS based client 670 certificates (Section 7.4.6 of [RFC5246]), or MUST use any HTTP 671 authentication scheme defined in the HTTP Authentication Scheme 672 Registry (Section 5.1 in [RFC7235]). A server MAY also support the 673 combination of both client certificates and an HTTP client 674 authentication scheme, with the determination of how to process this 675 combination left as an implementation decision. 677 The RESTCONF client identity derived from the authentication 678 mechanism used is hereafter known as the "RESTCONF username" and 679 subject to the NETCONF Access Control Module (NACM) [RFC6536]. When 680 a client certificate is presented, the RESTCONF username MUST be 681 derived using the algorithm defined in Section 7 of [RFC7589]. For 682 all other cases, when HTTP authentication is used, the RESTCONF 683 username MUST be provided by the HTTP authentication scheme used. 685 3. Resources 687 The RESTCONF protocol operates on a hierarchy of resources, starting 688 with the top-level API resource itself (Section 3.1). Each resource 689 represents a manageable component within the device. 691 A resource can be considered a collection of data and the set of 692 allowed methods on that data. It can contain nested child resources. 693 The child resource types and methods allowed on them are data-model 694 specific. 696 A resource has a representation associated with a media type 697 identifier, as represented by the "Content-Type" header in the HTTP 698 response message. A resource can contain zero or more nested 699 resources. A resource can be created and deleted independently of 700 its parent resource, as long as the parent resource exists. 702 All RESTCONF resource types are defined in this document except 703 specific datastore contents, RPC operations, and event notifications. 705 The syntax and semantics for these resource types are defined in YANG 706 modules. 708 The RESTCONF resources are accessed via a set of URIs defined in this 709 document. The set of YANG modules supported by the server will 710 determine the data model specific RPC operations, top-level data 711 nodes, and event notification messages supported by the server. 713 The RESTCONF protocol does not include a data resource discovery 714 mechanism. Instead, the definitions within the YANG modules 715 advertised by the server are used to construct a predictable 716 operation or data resource identifier. 718 3.1. Root Resource Discovery 720 In line with the best practices defined by [RFC7320], RESTCONF 721 enables deployments to specify where the RESTCONF API is located. 722 When first connecting to a RESTCONF server, a RESTCONF client MUST 723 determine the root of the RESTCONF API. There MUST be exactly one 724 "restconf" link relation returned by the device. 726 The client discovers this by getting the "/.well-known/host-meta" 727 resource ([RFC6415]) and using the element containing the 728 "restconf" attribute : 730 Example returning /restconf: 732 Request 733 ------- 734 GET /.well-known/host-meta HTTP/1.1 735 Host: example.com 736 Accept: application/xrd+xml 738 Response 739 -------- 740 HTTP/1.1 200 OK 741 Content-Type: application/xrd+xml 742 Content-Length: nnn 744 745 746 748 After discovering the RESTCONF API root, the client MUST prepend it 749 to any subsequent request to a RESTCONF resource. In this example, 750 the client would use the path "/restconf" as the RESTCONF entry 751 point. 753 Example returning /top/restconf: 755 Request 756 ------- 757 GET /.well-known/host-meta HTTP/1.1 758 Host: example.com 759 Accept: application/xrd+xml 761 Response 762 -------- 763 HTTP/1.1 200 OK 764 Content-Type: application/xrd+xml 765 Content-Length: nnn 767 768 769 771 In this example, the client would use the path "/top/restconf" as the 772 RESTCONF entry point. 774 The client can now determine the operation resources supported by the 775 the server. In this example a custom "play" operation is supported: 777 Request 778 ------- 779 GET /top/restconf/operations HTTP/1.1 780 Host: example.com 781 Accept: application/yang-data+json 783 Response 784 -------- 785 HTTP/1.1 200 OK 786 Date: Mon, 23 Apr 2012 17:01:00 GMT 787 Server: example-server 788 Cache-Control: no-cache 789 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 790 Content-Type: application/yang-data+json 792 { "operations" : { "example-jukebox:play" : [null] } } 794 If the XRD contains more than one link relation, then only the 795 relation named "restconf" is relevant to this specification. 797 3.2. RESTCONF Media Types 798 The RESTCONF protocol defines two application specific media types to 799 identify representations of data which conforms to the schema for a 800 particular YANG construct. 802 This document defines media types for XML and JSON serialization of 803 YANG data. Other documents MAY define other media types for 804 different serializations of YANG data. The "application/yang-data" 805 media-type is defined in Section 11.3.1. The "application/ 806 yang-data+json" media-type is defined in Section 11.3.2. 808 3.3. API Resource 810 The API resource contains the entry points for the RESTCONF datastore 811 and operation resources. It is the top-level resource located at 812 {+restconf} and has the media type "application/yang-data" or 813 "application/yang-data+json". 815 YANG Tree Diagram for an API Resource: 817 +--rw restconf 818 +--rw data 819 +--rw operations 820 +--ro yang-library-version 822 The "yang-api" YANG data template is defined with the "yang-data" 823 extension in the "ietf-restconf" module, found in Section 8. It is 824 used to specify the structure and syntax of the conceptual child 825 resources within the API resource. 827 The API resource can be retrieved with the GET method. 829 The {+restconf} entry point resource name used in responses MUST 830 identify the "ietf-restconf" YANG module. For example, a request to 831 GET the entry point "/restconf" in JSON format will return a 832 representation of the API resource named "ietf-restconf:restconf". 834 This resource has the following child resources: 836 +----------------------+--------------------------------+ 837 | Child Resource | Description | 838 +----------------------+--------------------------------+ 839 | data | Contains all data resources | 840 | operations | Data-model specific operations | 841 | yang-library-version | ietf-yang-library module date | 842 +----------------------+--------------------------------+ 844 RESTCONF API Resource 846 3.3.1. {+restconf}/data 848 This mandatory resource represents the combined configuration and 849 state data resources that can be accessed by a client. It cannot be 850 created or deleted by the client. The datastore resource type is 851 defined in Section 3.4. 853 Example: 855 This example request by the client would retrieve only the non- 856 configuration data nodes that exist within the "library" resource, 857 using the "content" query parameter (see Section 4.8.1). 859 GET /restconf/data/example-jukebox:jukebox/library 860 ?content=nonconfig HTTP/1.1 861 Host: example.com 862 Accept: application/yang-data 864 The server might respond: 866 HTTP/1.1 200 OK 867 Date: Mon, 23 Apr 2012 17:01:30 GMT 868 Server: example-server 869 Cache-Control: no-cache 870 Content-Type: application/yang-data 872 873 42 874 59 875 374 876 878 3.3.2. {+restconf}/operations 880 This optional resource is a container that provides access to the 881 data-model specific RPC operations supported by the server. The 882 server MAY omit this resource if no data-model specific operations 883 are advertised. 885 Any data-model specific RPC operations defined in the YANG modules 886 advertised by the server MUST be available as child nodes of this 887 resource. 889 The entry point for each RPC operation is represented as an empty 890 leaf. If an operation resource is retrieved, the empty leaf 891 representation is returned by the server. 893 Operation resources are defined in Section 3.6. 895 3.3.3. {+restconf}/yang-library-version 897 This mandatory leaf identifies the revision date of the 898 "ietf-yang-library" YANG module that is implemented by this server. 900 [RFC Editor Note: Adjust the date for ietf-yang-library below to the 901 date in the published ietf-yang-library YANG module, and remove this 902 note.] 904 Example: 906 GET /restconf/yang-library-version HTTP/1.1 907 Host: example.com 908 Accept: application/yang-data 910 The server might respond (response wrapped for display purposes): 912 HTTP/1.1 200 OK 913 Date: Mon, 23 Apr 2012 17:01:30 GMT 914 Server: example-server 915 Cache-Control: no-cache 916 Content-Type: application/yang-data 918 920 2016-04-09 921 923 3.4. Datastore Resource 925 The "{+restconf}/data" subtree represents the datastore resource 926 type, which is a collection of configuration data and state data 927 nodes. The fragment field in the request URI has no defined purpose 928 if the target resource is a datastore resource. 930 This resource type is an abstraction of the system's underlying 931 datastore implementation. It is used to simplify resource editing 932 for the client. The RESTCONF datastore resource is a conceptual 933 collection of all configuration and state data that is present on the 934 device. 936 Configuration edit transaction management and configuration 937 persistence are handled by the server and not controlled by the 938 client. A datastore resource can be written directly with the POST 939 and PATCH methods. Each RESTCONF edit of a datastore resource is 940 saved to non-volatile storage by the server, if the server supports 941 non-volatile storage of configuration data. 943 If the datastore resource represented by the "{+restconf}/data" 944 subtree is retrieved, then the datastore and its contents are 945 returned by the server. The datastore is represented by a node named 946 "data" in the "ietf-restconf" module namespace. 948 3.4.1. Edit Collision Detection 950 Two "edit collision detection" mechanisms are provided in RESTCONF, 951 for datastore and data resources. 953 3.4.1.1. Timestamp 955 The last change time is maintained and the "Last-Modified" 956 ([RFC7232], Section 2.2) header is returned in the response for a 957 retrieval request. The "If-Unmodified-Since" header can be used in 958 edit operation requests to cause the server to reject the request if 959 the resource has been modified since the specified timestamp. 961 The server SHOULD maintain a last-modified timestamp for the 962 datastore resource, defined in Section 3.4. This timestamp is only 963 affected by configuration child data resources, and MUST NOT be 964 updated for changes to non-configuration child data resources. Last- 965 modified timestamps for data resources are discussed in Section 3.5. 967 If the RESTCONF server is colocated with a NETCONF server, then the 968 last-modified timestamp MUST represent the "running" datastore. 970 3.4.1.2. Entity tag 972 A unique opaque string is maintained and the "ETag" ([RFC7232], 973 Section 2.3) header is returned in the response for a retrieval 974 request. The "If-Match" header can be used in edit operation 975 requests to cause the server to reject the request if the resource 976 entity tag does not match the specified value. 978 The server MUST maintain an entity tag for the top-level {+restconf}/ 979 data resource. This entity tag is only affected by configuration 980 data resources, and MUST NOT be updated for changes to non- 981 configuration data. Entity tags for data resources are discussed in 982 Section 3.5. 984 If the RESTCONF server is colocated with a NETCONF server, then this 985 entity tag MUST represent the "running" datastore. 987 3.4.1.3. Update Procedure 988 Changes to configuration data resources affect the timestamp and 989 entity tag to that resource, any ancestor data resources, and the 990 datastore resource. 992 For example, an edit to disable an interface might be done by setting 993 the leaf "/interfaces/interface/enabled" to "false". The "enabled" 994 data node and its ancestors (one "interface" list instance, and the 995 "interfaces" container) are considered to be changed. The datastore 996 is considered to be changed when any top-level configuration data 997 node is changed (e.g., "interfaces"). 999 3.5. Data Resource 1001 A data resource represents a YANG data node that is a descendant node 1002 of a datastore resource. Each YANG-defined data node can be uniquely 1003 targeted by the request-line of an HTTP method. Containers, leafs, 1004 leaf-list entries, list entries, anydata and anyxml nodes are data 1005 resources. 1007 The representation maintained for each data resource is the YANG 1008 defined subtree for that node. HTTP methods on a data resource 1009 affect both the targeted data node and all its descendants, if any. 1011 A data resource can be retrieved with the GET method. Data resources 1012 are accessed via the "{+restconf}/data" entry point. This sub-tree 1013 is used to retrieve and edit data resources. The fragment field in 1014 the request URI has no defined purpose if the target resource is a 1015 data resource. 1017 A configuration data resource can be altered by the client with some 1018 or all of the edit operations, depending on the target resource and 1019 the specific operation. Refer to Section 4 for more details on edit 1020 operations. 1022 3.5.1. Timestamp 1024 For configuration data resources, the server MAY maintain a last- 1025 modified timestamp for the resource, and return the "Last-Modified" 1026 header when it is retrieved with the GET or HEAD methods. 1028 The "Last-Modified" header information can be used by a RESTCONF 1029 client in subsequent requests, within the "If-Modified-Since" and 1030 "If-Unmodified-Since" headers. 1032 If maintained, the resource timestamp MUST be set to the current time 1033 whenever the resource or any configuration resource within the 1034 resource is altered. If not maintained, then the resource timestamp 1035 for the datastore MUST be used instead. If the RESTCONF server is 1036 colocated with a NETCONF server, then the last-modified timestamp for 1037 a configuration data resource MUST represent the instance within the 1038 "running" datastore. 1040 This timestamp is only affected by configuration data resources, and 1041 MUST NOT be updated for changes to non-configuration data. 1043 For non-configuration data resources, the server MAY maintain a last- 1044 modified timestamp for the resource, and return the "Last-Modified" 1045 header when it is retrieved with the GET or HEAD methods. The 1046 timestamps for non-configuration data resources are updated in an 1047 implementation-specific manner. 1049 3.5.2. Entity tag 1051 For configuration data resources, the server SHOULD maintain a 1052 resource entity tag for each resource, and return the "ETag" header 1053 when it is retrieved as the target resource with the GET or HEAD 1054 methods. If maintained, the resource entity tag MUST be updated 1055 whenever the resource or any configuration resource within the 1056 resource is altered. If not maintained, then the resource entity tag 1057 for the datastore MUST be used instead. 1059 The "ETag" header information can be used by a RESTCONF client in 1060 subsequent requests, within the "If-Match" and "If-None-Match" 1061 headers. 1063 This entity tag is only affected by configuration data resources, and 1064 MUST NOT be updated for changes to non-configuration data. If the 1065 RESTCONF server is colocated with a NETCONF server, then the entity 1066 tag for a configuration data resource MUST represent the instance 1067 within the "running" datastore. 1069 For non-configuration data resources, the server MAY maintain an 1070 entity tag for each resource, and return the "ETag" header when it is 1071 retrieved with the GET or HEAD methods. The entity tags for non- 1072 configuration data resources are updated in an implementation- 1073 specific manner. 1075 3.5.3. Encoding Data Resource Identifiers in the Request URI 1077 In YANG, data nodes are identified with an absolute XPath expression, 1078 defined in [XPath], starting from the document root to the target 1079 resource. In RESTCONF, URI-encoded path expressions are used 1080 instead. 1082 A predictable location for a data resource is important, since 1083 applications will code to the YANG data model module, which uses 1084 static naming and defines an absolute path location for all data 1085 nodes. 1087 A RESTCONF data resource identifier is not an XPath expression. It 1088 is encoded from left to right, starting with the top-level data node, 1089 according to the "api-path" rule in Section 3.5.3.1. The node name 1090 of each ancestor of the target resource node is encoded in order, 1091 ending with the node name for the target resource. If a node in the 1092 path is defined in another module than its parent node, then module 1093 name followed by a colon character (":") is prepended to the node 1094 name in the resource identifier. See Section 3.5.3.1 for details. 1096 If a data node in the path expression is a YANG leaf-list node, then 1097 the leaf-list value MUST be encoded according to the following rules: 1099 o The identifier for the leaf-list MUST be encoded using one path 1100 segment [RFC3986]. 1102 o The path segment is constructed by having the leaf-list name, 1103 followed by an "=" character, followed by the leaf-list value. 1104 (e.g., /restconf/data/top-leaflist=fred). 1106 If a data node in the path expression is a YANG list node, then the 1107 key values for the list (if any) MUST be encoded according to the 1108 following rules: 1110 o The key leaf values for a data resource representing a YANG list 1111 MUST be encoded using one path segment [RFC3986]. 1113 o If there is only one key leaf value, the path segment is 1114 constructed by having the list name, followed by an "=" character, 1115 followed by the single key leaf value. 1117 o If there are multiple key leaf values, the path segment is 1118 constructed by having the list name, followed by the value of each 1119 leaf identified in the "key" statement, encoded in the order 1120 specified in the YANG "key" statement. Each key leaf value except 1121 the last one is followed by a comma character. 1123 o The key value is specified as a string, using the canonical 1124 representation for the YANG data type. Any reserved characters 1125 MUST be percent-encoded, according to [RFC3986], section 2.1. 1127 o All the components in the "key" statement MUST be encoded. 1128 Partial instance identifiers are not supported. 1130 o Since missing key values are not allowed, two consecutive commas 1131 are interpreted as a zero-length string. (example: 1132 list=foo,,baz). 1134 o The "list-instance" ABNF rule defined in Section 3.5.3.1 1135 represents the syntax of a list instance identifier. 1137 Resource URI values returned in Location headers for data resources 1138 MUST identify the module name as specified in 1139 [I-D.ietf-netmod-yang-json], even if there are no conflicting local 1140 names when the resource is created. This ensures the correct 1141 resource will be identified even if the server loads a new module 1142 that the old client does not know about. 1144 Examples: 1146 container top { 1147 list list1 { 1148 key "key1 key2 key3"; 1149 ... 1150 list list2 { 1151 key "key4 key5"; 1152 ... 1153 leaf X { type string; } 1154 } 1155 } 1156 leaf-list Y { 1157 type uint32; 1158 } 1159 } 1161 For the above YANG definition, the container "top" is defined in the 1162 "example-top" YANG module, and a target resource URI for leaf "X" 1163 would be encoded as follows (line wrapped for display purposes only): 1165 /restconf/data/example-top:top/list1=key1,key2,key3/ 1166 list2=key4,key5/X 1168 For the above YANG definition, a target resource URI for leaf-list 1169 "Y" would be encoded as follows: 1171 /restconf/data/example-top:top/Y=instance-value 1173 The following example shows how reserved characters are percent- 1174 encoded within a key value. The value of "key1" contains a comma, 1175 single-quote, double-quote, colon, double-quote, space, and forward 1176 slash. (,'":" /). Note that double-quote is not a reserved 1177 characters and does not need to be percent-encoded. The value of 1178 "key2" is the empty string, and the value of "key3" is the string 1179 "foo". 1181 Example URL: 1183 /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo 1185 3.5.3.1. ABNF For Data Resource Identifiers 1187 The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to 1188 construct RESTCONF path identifiers: 1190 api-path = "/" | 1191 ("/" api-identifier 1192 0*("/" (api-identifier | list-instance ))) 1194 api-identifier = [module-name ":"] identifier ;; note 1 1196 module-name = identifier 1198 list-instance = api-identifier "=" key-value ["," key-value]* 1200 key-value = string ;; note 1 1202 string = 1204 ;; An identifier MUST NOT start with 1205 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 1206 identifier = (ALPHA / "_") 1207 *(ALPHA / DIGIT / "_" / "-" / ".") 1209 Note 1: The syntax for "api-identifier" and "key-value" MUST conform 1210 to the JSON identifier encoding rules in Section 4 of 1211 [I-D.ietf-netmod-yang-json]. 1213 3.5.4. Defaults Handling 1215 RESTCONF requires that a server report its default handling mode (see 1216 Section 9.1.2 for details). If the optional "with-defaults" query 1217 parameter is supported by the server, a client may use it to control 1218 retrieval of default values (see Section 4.8.9 for details). 1220 If a leaf or leaf-list is missing from the configuration and there is 1221 a YANG-defined default for that data resource, then the server MUST 1222 use the YANG-defined default as the configured value. 1224 If the target of a GET method is a data node that represents a leaf 1225 or leaf-list that has a default value, and the leaf or leaf-list has 1226 not been instantiated yet, the server MUST return the default 1227 value(s) that are in use by the server. In this case, the server 1228 MUST ignore its basic-mode, described in Section 4.8.9, and return 1229 the default value. 1231 If the target of a GET method is a data node that represents a 1232 container or list that has any child resources with default values, 1233 for the child resources that have not been given value yet, the 1234 server MAY return the default values that are in use by the server, 1235 in accordance with its reported default handing mode and query 1236 parameters passed by the client. 1238 3.6. Operation Resource 1240 An operation resource represents an RPC operation defined with the 1241 YANG "rpc" statement or a data-model specific action defined with a 1242 YANG "action" statement. It is invoked using a POST method on the 1243 operation resource. The fragment field in the request URI has no 1244 defined purpose if the target resource is an operation resource. 1246 An RPC operation is invoked as: 1248 POST {+restconf}/operations/ 1250 The field identifies the module name and rpc identifier 1251 string for the desired operation. 1253 For example, if "module-A" defined a "reset" rpc operation, then 1254 invoking the operation from "module-A" would be requested as follows: 1256 POST /restconf/operations/module-A:reset HTTP/1.1 1257 Server: example.com 1259 An action is invoked as: 1261 POST {+restconf}/data// 1263 where contains the path to the data node 1264 where the action is defined, and is the name of the action. 1266 For example, if "module-A" defined a "reset-all" action in the 1267 container "interfaces", then invoking this action would be requested 1268 as follows: 1270 POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 1271 Server: example.com 1272 If the "rpc" or "action" statement has an "input" section then 1273 instances of these input parameters are encoded in the module 1274 namespace where the "rpc" or "action" statement is defined, in an XML 1275 element or JSON object named "input", which is in the module 1276 namespace where the "rpc" or "action" statement is defined. 1278 If the "rpc" or "action" statement has an "input" section and the 1279 "input" object tree contains any child data nodes which are 1280 considered mandatory nodes, then a message-body MUST be sent by the 1281 client in the request. 1283 If the "rpc" or "action" statement has an "input" section and the 1284 "input" object tree does not contain any child nodes which are 1285 considered mandatory nodes, then a message-body MAY be sent by the 1286 client in the request. 1288 If the "rpc" or "action" statement has no "input" section, the 1289 request message MUST NOT include a message-body. 1291 If the "rpc" or "action" statement has an "output" section then 1292 instances of these output parameters are encoded in the module 1293 namespace where the "rpc" or "action" statement is defined, in an XML 1294 element or JSON object named "output", which is in the module 1295 namespace where the "rpc" or "action" statement is defined. 1297 If the RPC operation is invoked without errors, and if the "rpc" or 1298 "action" statement has an "output" section and the "output" object 1299 tree contains any child data nodes which are considered mandatory 1300 nodes, then a response message-body MUST be sent by the server in the 1301 response. 1303 If the RPC operation is invoked without errors, and if the "rpc" or 1304 "action" statement has an "output" section and the "output" object 1305 tree does not contain any child nodes which are considered mandatory 1306 nodes, then a response message-body MAY be sent by the server in the 1307 response. 1309 If the RPC operation is invoked without errors, and if the "rpc" or 1310 "action" statement has no "output" section, the response message MUST 1311 NOT include a message-body, and MUST send a "204 No Content" status- 1312 line instead. 1314 If the RPC operation input is not valid, or the RPC operation is 1315 invoked but errors occur, then a message-body MUST be sent by the 1316 server, containing an "errors" resource, as defined in Section 3.9. 1317 A detailed example of an operation resource error response can be 1318 found in Section 3.6.3. 1320 All operation resources representing RPC operations supported by the 1321 server MUST be identified in the {+restconf}/operations subtree 1322 defined in Section 3.3.2. Operation resources representing YANG 1323 actions are not identified in this subtree since they are invoked 1324 using a URI within the {+restconf}/data subtree. 1326 3.6.1. Encoding Operation Resource Input Parameters 1328 If the "rpc" or "action" statement has an "input" section, then the 1329 "input" node is provided in the message-body, corresponding to the 1330 YANG data definition statements within the "input" section. The 1331 "input" node is defined to be in the namespace of the module 1332 containing the "rpc" or "action" statement. 1334 Examples: 1336 The following YANG module is used for the RPC operation examples in 1337 this section. 1339 module example-ops { 1340 namespace "https://example.com/ns/example-ops"; 1341 prefix "ops"; 1343 organization "Example, Inc."; 1344 contact "support at example.com"; 1345 description "Example Operations Data Model Module"; 1346 revision "2016-07-07" { 1347 description "Initial version."; 1348 reference "example.com document 3-3373"; 1349 } 1351 rpc reboot { 1352 input { 1353 leaf delay { 1354 units seconds; 1355 type uint32; 1356 default 0; 1357 } 1358 leaf message { type string; } 1359 leaf language { type string; } 1360 } 1361 } 1363 rpc get-reboot-info { 1364 output { 1365 leaf reboot-time { 1366 units seconds; 1367 type uint32; 1368 } 1369 leaf message { type string; } 1370 leaf language { type string; } 1371 } 1372 } 1373 } 1375 The following YANG module is used for the YANG action examples in 1376 this section. 1378 module example-actions { 1379 yang-version 1.1; 1380 namespace "https://example.com/ns/example-actions"; 1381 prefix "act"; 1382 import ietf-yang-types { prefix yang; } 1384 organization "Example, Inc."; 1385 contact "support at example.com"; 1386 description "Example Actions Data Model Module"; 1387 revision "2016-07-07" { 1388 description "Initial version."; 1389 reference "example.com document 2-9973"; 1390 } 1392 revision "2016-03-10"; 1394 container interfaces { 1395 list interface { 1396 key name; 1397 leaf name { type string; } 1399 action reset { 1400 input { 1401 leaf delay { 1402 units seconds; 1403 type uint32; 1404 default 0; 1405 } 1406 } 1407 } 1409 action get-last-reset-time { 1410 output { 1411 leaf last-reset { 1412 type yang:date-and-time; 1413 mandatory true; 1415 } 1416 } 1417 } 1418 } 1419 } 1421 } 1423 RPC Input Example: 1425 The client might send the following POST request message to invoke 1426 the "reboot" RPC operation: 1428 POST /restconf/operations/example-ops:reboot HTTP/1.1 1429 Host: example.com 1430 Content-Type: application/yang-data 1432 1433 600 1434 Going down for system maintenance 1435 en-US 1436 1438 The server might respond: 1440 HTTP/1.1 204 No Content 1441 Date: Mon, 25 Apr 2012 11:01:00 GMT 1442 Server: example-server 1444 The same example request message is shown here using JSON encoding: 1446 POST /restconf/operations/example-ops:reboot HTTP/1.1 1447 Host: example.com 1448 Content-Type: application/yang-data+json 1450 { 1451 "example-ops:input" : { 1452 "delay" : 600, 1453 "message" : "Going down for system maintenance", 1454 "language" : "en-US" 1455 } 1456 } 1458 Action Input Example: 1460 The client might send the following POST request message to invoke 1461 the "reset" action (text wrap for display purposes): 1463 POST /restconf/data/example-actions:interfaces/interface=eth0 1464 /reset HTTP/1.1 1465 Host: example.com 1466 Content-Type: application/yang-data 1468 1469 600 1470 1472 The server might respond: 1474 HTTP/1.1 204 No Content 1475 Date: Mon, 25 Apr 2012 11:01:00 GMT 1476 Server: example-server 1478 The same example request message is shown here using JSON encoding 1479 (text wrap for display purposes): 1481 POST /restconf/data/example-actions:interfaces/interface=eth0 1482 /reset HTTP/1.1 1483 Host: example.com 1484 Content-Type: application/yang-data+json 1486 { "example-actions:input" : { 1487 "delay" : 600 1488 } 1489 } 1491 3.6.2. Encoding Operation Resource Output Parameters 1493 If the "rpc" or "action" statement has an "output" section, then the 1494 "output" node is provided in the message-body, corresponding to the 1495 YANG data definition statements within the "output" section. The 1496 "output" node is defined to be in the namespace of the module 1497 containing the "rpc" or "action" statement. 1499 The request URI is not returned in the response. This URI might have 1500 context information required to associate the output to the specific 1501 "rpc" or "action" statement used in the request. 1503 Examples: 1505 RPC Output Example: 1507 The "example-ops" YANG module defined in Section 3.6.1 is used for 1508 this example. 1510 The client might send the following POST request message to invoke 1511 the "get-reboot-info" operation: 1513 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 1514 Host: example.com 1515 Accept: application/yang-data+json 1517 The server might respond: 1519 HTTP/1.1 200 OK 1520 Date: Mon, 25 Apr 2012 11:10:30 GMT 1521 Server: example-server 1522 Content-Type: application/yang-data+json 1524 { 1525 "example-ops:output" : { 1526 "reboot-time" : 30, 1527 "message" : "Going down for system maintenance", 1528 "language" : "en-US" 1529 } 1530 } 1532 The same response is shown here using XML encoding: 1534 HTTP/1.1 200 OK 1535 Date: Mon, 25 Apr 2012 11:10:30 GMT 1536 Server: example-server 1537 Content-Type: application/yang-data 1539 1540 30 1541 Going down for system maintenance 1542 en-US 1543 1545 Action Output Example: 1547 The "example-actions" YANG module defined in Section 3.6.1 is used 1548 for this example. 1550 The client might send the following POST request message to invoke 1551 the "get-last-reset-time" action: 1553 POST /restconf/data/example-actions:interfaces/interface=eth0 1554 /get-last-reset-time HTTP/1.1 1555 Host: example.com 1556 Accept: application/yang-data+json 1557 The server might respond: 1559 HTTP/1.1 200 OK 1560 Date: Mon, 25 Apr 2012 11:10:30 GMT 1561 Server: example-server 1562 Content-Type: application/yang-data+json 1564 { 1565 "example-actions:output" : { 1566 "last-reset" : "2015-10-10T02:14:11Z" 1567 } 1568 } 1570 3.6.3. Encoding Operation Resource Errors 1572 If any errors occur while attempting to invoke the operation or 1573 action, then an "errors" media type is returned with the appropriate 1574 error status. 1576 Using the "reboot" RPC operation from the example in Section 3.6.1, 1577 the client might send the following POST request message: 1579 POST /restconf/operations/example-ops:reboot HTTP/1.1 1580 Host: example.com 1581 Content-Type: application/yang-data 1583 1584 -33 1585 Going down for system maintenance 1586 en-US 1587 1589 The server might respond with an "invalid-value" error: 1591 HTTP/1.1 400 Bad Request 1592 Date: Mon, 25 Apr 2012 11:10:30 GMT 1593 Server: example-server 1594 Content-Type: application/yang-data 1595 1596 1597 protocol 1598 invalid-value 1599 1600 /ops:input/ops:delay 1601 1602 Invalid input parameter 1603 1604 1606 The same response is shown here in JSON encoding: 1608 HTTP/1.1 400 Bad Request 1609 Date: Mon, 25 Apr 2012 11:10:30 GMT 1610 Server: example-server 1611 Content-Type: application/yang-data+json 1613 { "ietf-restconf:errors" : { 1614 "error" : [ 1615 { 1616 "error-type" : "protocol", 1617 "error-tag" : "invalid-value", 1618 "error-path" : "/example-ops:input/delay", 1619 "error-message" : "Invalid input parameter", 1620 } 1621 ] 1622 } 1623 } 1625 3.7. Schema Resource 1627 The server can optionally support retrieval of the YANG modules it 1628 supports. If retrieval is supported, then the "schema" leaf MUST be 1629 present in the associated "module" list entry, defined in 1630 [I-D.ietf-netconf-yang-library]. 1632 To retrieve a YANG module, a client first needs to get the URL for 1633 retrieving the schema, which is stored in the "schema" leaf. Note 1634 that there is no required structure for this URL. The URL value 1635 shown below is just an example. 1637 The client might send the following GET request message: 1639 GET /restconf/data/ietf-yang-library:modules-state/module= 1640 example-jukebox,2015-04-04/schema HTTP/1.1 1641 Host: example.com 1642 Accept: application/yang-data+json 1643 The server might respond: 1645 HTTP/1.1 200 OK 1646 Date: Thu, 11 Feb 2016 11:10:30 GMT 1647 Server: example-server 1648 Content-Type: application/yang-data+json 1650 { 1651 "ietf-yang-library:schema": 1652 "https://example.com/mymodules/example-jukebox/2015-04-04" 1653 } 1655 Next the client needs to retrieve the actual YANG schema. 1657 The client might send the following GET request message: 1659 GET https://example.com/mymodules/example-jukebox/2015-04-04 1660 HTTP/1.1 1661 Host: example.com 1662 Accept: application/yang 1664 The server might respond: 1666 HTTP/1.1 200 OK 1667 Date: Thu, 11 Feb 2016 11:10:31 GMT 1668 Server: example-server 1669 Content-Type: application/yang 1671 module example-jukebox { 1673 // contents of YANG module deleted for this example... 1675 } 1677 3.8. Event Stream Resource 1679 An "event stream" resource represents a source for system generated 1680 event notifications. Each stream is created and modified by the 1681 server only. A client can retrieve a stream resource or initiate a 1682 long-poll server sent event stream, using the procedure specified in 1683 Section 6.3. 1685 A notification stream functions according to the NETCONF 1686 Notifications specification [RFC5277]. The available streams can be 1687 retrieved from the stream list, which specifies the syntax and 1688 semantics of a stream resource. 1690 The fragment field in the request URI has no defined purpose if the 1691 target resource is an event stream resource. 1693 3.9. Errors YANG Data Template 1695 An "errors" YANG data template models a collection of error 1696 information that is sent as the message-body in a server response 1697 message, if an error occurs while processing a request message. It 1698 is not considered a resource type because no instances can be 1699 retrieved with a GET request. 1701 The "ietf-restconf" YANG module contains the "yang-errors" YANG data 1702 template, that specifies the syntax and semantics of an "errors" 1703 container within a RESTCONF response. RESTCONF error handling 1704 behavior is defined in Section 7. 1706 4. Operations 1708 The RESTCONF protocol uses HTTP methods to identify the CRUD 1709 operation requested for a particular resource. 1711 The following table shows how the RESTCONF operations relate to 1712 NETCONF protocol operations and edit operations, which are identified 1713 with the NETCONF "nc:operation" attribute. 1715 +----------+-----------------------------------------------+ 1716 | RESTCONF | NETCONF | 1717 +----------+-----------------------------------------------+ 1718 | OPTIONS | none | 1719 | HEAD | none | 1720 | GET | , | 1721 | POST | (nc:operation="create") | 1722 | POST | invoke an RPC operation | 1723 | PUT | (nc:operation="create/replace") | 1724 | PATCH | (nc:operation="merge") | 1725 | DELETE | (nc:operation="delete") | 1726 +----------+-----------------------------------------------+ 1728 CRUD Methods in RESTCONF 1730 The "remove" operation attribute for the NETCONF 1731 operation is not supported by the HTTP DELETE method. The resource 1732 must exist or the DELETE method will fail. The PATCH method is 1733 equivalent to a "merge" operation when using a plain patch (see 1734 Section 4.6.1); other media-types may provide more granular control. 1736 Access control mechanisms MUST be used to limit what operations can 1737 be used. In particular, RESTCONF is compatible with the NETCONF 1738 Access Control Model (NACM) [RFC6536], as there is a specific mapping 1739 between RESTCONF and NETCONF operations, defined in Section 4. The 1740 resource path needs to be converted internally by the server to the 1741 corresponding YANG instance-identifier. Using this information, the 1742 server can apply the NACM access control rules to RESTCONF messages. 1744 The server MUST NOT allow any operation to any resources that the 1745 client is not authorized to access. 1747 Implementation of all methods (except PATCH) are defined in 1748 [RFC7231]. This section defines the RESTCONF protocol usage for each 1749 HTTP method. 1751 4.1. OPTIONS 1753 The OPTIONS method is sent by the client to discover which methods 1754 are supported by the server for a specific resource (e.g., GET, POST, 1755 DELETE, etc.). The server MUST implement this method. 1757 If the PATCH method is supported, then the "Accept-Patch" header MUST 1758 be supported and returned in the response to the OPTIONS request, as 1759 defined in [RFC5789]. 1761 4.2. HEAD 1763 The HEAD method is sent by the client to retrieve just the headers 1764 that would be returned for the comparable GET method, without the 1765 response message-body. It is supported for all resource types, 1766 except operation resources. 1768 The request MUST contain a request URI that contains at least the 1769 entry point. The same query parameters supported by the GET method 1770 are supported by the HEAD method. 1772 The access control behavior is enforced as if the method was GET 1773 instead of HEAD. The server MUST respond the same as if the method 1774 was GET instead of HEAD, except that no response message-body is 1775 included. 1777 4.3. GET 1779 The GET method is sent by the client to retrieve data and metadata 1780 for a resource. It is supported for all resource types, except 1781 operation resources. The request MUST contain a request URI that 1782 contains at least the entry point. 1784 The server MUST NOT return any data resources for which the user does 1785 not have read privileges. If the user is not authorized to read the 1786 target resource, an error response containing a "401 Unauthorized" 1787 status-line SHOULD be returned. A server MAY return a "404 Not 1788 Found" status-line, as described in section 6.5.3 in [RFC7231]. 1790 If the user is authorized to read some but not all of the target 1791 resource, the unauthorized content is omitted from the response 1792 message-body, and the authorized content is returned to the client. 1794 If any content is returned to the client, then the server MUST send a 1795 valid response message-body. More than one element MUST NOT be 1796 returned for XML encoding. 1798 If a retrieval request for a data resource representing a YANG leaf- 1799 list or list object identifies more than one instance, and XML 1800 encoding is used in the response, then an error response containing a 1801 "400 Bad Request" status-line MUST be returned by the server. 1803 If a retrieval request for a data resource represents an instance 1804 that does not exist, then an error response containing a "404 Not 1805 Found" status-line MUST be returned by the server. 1807 If the target resource of a retrieval request is for an operation 1808 resource then a "405 Method Not Allowed" status-line MUST be returned 1809 by the server. 1811 Note that the way that access control is applied to data resources 1812 may not be completely compatible with HTTP caching. The Last- 1813 Modified and ETag headers maintained for a data resource are not 1814 affected by changes to the access control rules for that data 1815 resource. It is possible for the representation of a data resource 1816 that is visible to a particular client to be changed without 1817 detection via the Last-Modified or ETag values. 1819 Example: 1821 The client might request the response headers for an XML 1822 representation of the a specific "album" resource: 1824 GET /restconf/data/example-jukebox:jukebox/ 1825 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1826 Host: example.com 1827 Accept: application/yang-data 1829 The server might respond: 1831 HTTP/1.1 200 OK 1832 Date: Mon, 23 Apr 2012 17:02:40 GMT 1833 Server: example-server 1834 Content-Type: application/yang-data 1835 Cache-Control: no-cache 1836 ETag: "a74eefc993a2b" 1837 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1839 1841 Wasting Light 1842 jbox:alternative 1843 2011 1844 1846 4.4. POST 1848 The POST method is sent by the client to create a data resource or 1849 invoke an operation resource. The server uses the target resource 1850 media type to determine how to process the request. 1852 +-----------+------------------------------------------------+ 1853 | Type | Description | 1854 +-----------+------------------------------------------------+ 1855 | Datastore | Create a top-level configuration data resource | 1856 | Data | Create a configuration data child resource | 1857 | Operation | Invoke an RPC operation | 1858 +-----------+------------------------------------------------+ 1860 Resource Types that Support POST 1862 4.4.1. Create Resource Mode 1864 If the target resource type is a datastore or data resource, then the 1865 POST is treated as a request to create a top-level resource or child 1866 resource, respectively. The message-body is expected to contain the 1867 content of a child resource to create within the parent (target 1868 resource). The message-body MUST contain exactly one instance of the 1869 expected data resource. The data-model for the child tree is the 1870 subtree as defined by YANG for the child resource. 1872 The "insert" Section 4.8.5 and "point" Section 4.8.6 query parameters 1873 MUST be supported by the POST method for datastore and data 1874 resources. These parameters are only allowed if the list or leaf- 1875 list is ordered-by user. 1877 If the POST method succeeds, a "201 Created" status-line is returned 1878 and there is no response message-body. A "Location" header 1879 identifying the child resource that was created MUST be present in 1880 the response in this case. 1882 If the data resource already exists, then the POST request MUST fail 1883 and a "409 Conflict" status-line MUST be returned. 1885 If the user is not authorized to create the target resource, an error 1886 response containing a "403 Forbidden" status-line SHOULD be returned. 1887 A server MAY return a "404 Not Found" status-line, as described in 1888 section 6.5.3 in [RFC7231]. All other error responses are handled 1889 according to the procedures defined in Section 7. 1891 Example: 1893 To create a new "jukebox" resource, the client might send: 1895 POST /restconf/data HTTP/1.1 1896 Host: example.com 1897 Content-Type: application/yang-data+json 1899 { "example-jukebox:jukebox" : {} } 1901 If the resource is created, the server might respond as follows. 1902 Note that the "Location" header line is wrapped for display purposes 1903 only: 1905 HTTP/1.1 201 Created 1906 Date: Mon, 23 Apr 2012 17:01:00 GMT 1907 Server: example-server 1908 Location: https://example.com/restconf/data/ 1909 example-jukebox:jukebox 1910 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 1911 ETag: "b3a3e673be2" 1913 Refer to Appendix D.2.1 for more resource creation examples. 1915 4.4.2. Invoke Operation Mode 1917 If the target resource type is an operation resource, then the POST 1918 method is treated as a request to invoke that operation. The 1919 message-body (if any) is processed as the operation input parameters. 1920 Refer to Section 3.6 for details on operation resources. 1922 If the POST request succeeds, a "200 OK" status-line is returned if 1923 there is a response message-body, and a "204 No Content" status-line 1924 is returned if there is no response message-body. 1926 If the user is not authorized to invoke the target operation, an 1927 error response containing a "403 Forbidden" status-line is returned 1928 to the client. All other error responses are handled according to 1929 the procedures defined in Section 7. 1931 Example: 1933 In this example, the client is invoking the "play" operation defined 1934 in the "example-jukebox" YANG module. 1936 A client might send a "play" request as follows: 1938 POST /restconf/operations/example-jukebox:play HTTP/1.1 1939 Host: example.com 1940 Content-Type: application/yang-data+json 1942 { 1943 "example-jukebox:input" : { 1944 "playlist" : "Foo-One", 1945 "song-number" : 2 1946 } 1947 } 1949 The server might respond: 1951 HTTP/1.1 204 No Content 1952 Date: Mon, 23 Apr 2012 17:50:00 GMT 1953 Server: example-server 1955 4.5. PUT 1957 The PUT method is sent by the client to create or replace the target 1958 data resource. A request message-body MUST be present, representing 1959 the new data resource, or the server MUST return "400 Bad Request" 1960 status-line. 1962 The only target resource media type that supports PUT is the data 1963 resource. The message-body is expected to contain the content used 1964 to create or replace the target resource. 1966 The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query 1967 parameters MUST be supported by the PUT method for data resources. 1968 These parameters are only allowed if the list or leaf-list is 1969 ordered-by user. 1971 Consistent with [RFC7231], if the PUT request creates a new resource, 1972 a "201 Created" status-line is returned. If an existing resource is 1973 modified, a "204 No Content" status-line is returned. 1975 If the user is not authorized to create or replace the target 1976 resource an error response containing a "403 Forbidden" status-line 1977 SHOULD be returned. A server MAY return a "404 Not Found" status- 1978 line, as described in section 6.5.3 in [RFC7231]. All other error 1979 responses are handled according to the procedures defined in 1980 Section 7. 1982 If the target resource represents a YANG leaf-list, then the PUT 1983 method MUST NOT change the value of the leaf-list instance. 1985 If the target resource represents a YANG list instance, then the PUT 1986 method MUST NOT change any key leaf values in the message-body 1987 representation. 1989 Example: 1991 An "album" child resource defined in the "example-jukebox" YANG 1992 module is replaced or created if it does not already exist. 1994 To replace the "album" resource contents, the client might send as 1995 follows. Note that the request-line is wrapped for display purposes 1996 only: 1998 PUT /restconf/data/example-jukebox:jukebox/ 1999 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2000 Host: example.com 2001 Content-Type: application/yang-data+json 2003 { 2004 "example-jukebox:album" : [ 2005 { 2006 "name" : "Wasting Light", 2007 "genre" : "example-jukebox:alternative", 2008 "year" : 2011 2009 } 2010 ] 2011 } 2013 If the resource is updated, the server might respond: 2015 HTTP/1.1 204 No Content 2016 Date: Mon, 23 Apr 2012 17:04:00 GMT 2017 Server: example-server 2018 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 2019 ETag: "b27480aeda4c" 2021 The same request is shown here using XML encoding: 2023 PUT /restconf/data/example-jukebox:jukebox/ 2024 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2025 Host: example.com 2026 Content-Type: application/yang-data 2027 2029 Wasting Light 2030 jbox:alternative 2031 2011 2032 2034 4.6. PATCH 2036 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 2037 an extensible framework for resource patching mechanisms. It is 2038 optional to implement by the server. Each patch mechanism needs a 2039 unique media type. Zero or more patch media types MAY be supported 2040 by the server. The media types supported by a server can be 2041 discovered by the client by sending an OPTIONS request, and examining 2042 the Accept-Patch header field in the response. (see Section 4.1). 2044 This document defines one patch mechanism (Section 4.6.1). Another 2045 patch mechanism, the YANG PATCH mechanism, is defined in 2046 [I-D.ietf-netconf-yang-patch]. Other patch mechanisms may be defined 2047 by future specifications. 2049 If the target resource instance does not exist, the server MUST NOT 2050 create it. 2052 If the PATCH request succeeds, a "200 OK" status-line is returned if 2053 there is a message-body, and "204 No Content" is returned if no 2054 response message-body is sent. 2056 If the user is not authorized to alter the target resource an error 2057 response containing a "403 Forbidden" status-line SHOULD be returned. 2058 A server MAY return a "404 Not Found" status-line, as described in 2059 section 6.5.3 in [RFC7231]. All other error responses are handled 2060 according to the procedures defined in Section 7. 2062 4.6.1. Plain Patch 2064 The plain patch mechanism merges the contents of the message-body 2065 with the target resource. The message-body for a plain patch MUST be 2066 present and MUST be represented by the media type "application/ 2067 yang-data" or "application/yang-data+json". 2069 Plain patch can be used to create or update, but not delete, a child 2070 resource within the target resource. Please see 2071 [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting 2072 the ability to delete child resources. The YANG Patch Media Type 2073 allows multiple sub-operations (e.g., merge, delete) within a single 2074 PATCH operation. 2076 If the target resource represents a YANG leaf-list, then the PATCH 2077 method MUST NOT change the value of the leaf-list instance. 2079 If the target resource represents a YANG list instance, then the 2080 PATCH method MUST NOT change any key leaf values in the message-body 2081 representation. 2083 Example: 2085 To replace just the "year" field in the "album" resource (instead of 2086 replacing the entire resource with the PUT method), the client might 2087 send a plain patch as follows. Note that the request-line is wrapped 2088 for display purposes only: 2090 PATCH /restconf/data/example-jukebox:jukebox/ 2091 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2092 Host: example.com 2093 If-Match: "b8389233a4c" 2094 Content-Type: application/yang-data 2096 2097 2011 2098 2100 If the field is updated, the server might respond: 2102 HTTP/1.1 204 No Content 2103 Date: Mon, 23 Apr 2012 17:49:30 GMT 2104 Server: example-server 2105 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 2106 ETag: "b2788923da4c" 2108 4.7. DELETE 2110 The DELETE method is used to delete the target resource. If the 2111 DELETE request succeeds, a "204 No Content" status-line is returned. 2113 If the user is not authorized to delete the target resource then an 2114 error response containing a "403 Forbidden" status-line SHOULD be 2115 returned. A server MAY return a "404 Not Found" status-line, as 2116 described in section 6.5.3 in [RFC7231]. All other error responses 2117 are handled according to the procedures defined in Section 7. 2119 If the target resource represents a YANG leaf-list or list, then the 2120 DELETE method SHOULD NOT delete more than one such instance. The 2121 server MAY delete more than one instance if a query parameter is used 2122 requesting this behavior. (Definition of this query parameter is 2123 outside the scope of this document.) 2124 Example: 2126 To delete a resource such as the "album" resource, the client might 2127 send: 2129 DELETE /restconf/data/example-jukebox:jukebox/ 2130 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2131 Host: example.com 2133 If the resource is deleted, the server might respond: 2135 HTTP/1.1 204 No Content 2136 Date: Mon, 23 Apr 2012 17:49:40 GMT 2137 Server: example-server 2139 4.8. Query Parameters 2141 Each RESTCONF operation allows zero or more query parameters to be 2142 present in the request URI. The specific parameters that are allowed 2143 depends on the resource type, and sometimes the specific target 2144 resource used, in the request. 2146 o Query parameters can be given in any order. 2148 o Each parameter can appear at most once in a request URI. 2150 o If more than one instance of a query parameter is present, then a 2151 "400 Bad Request" status-line MUST be returned by the server. 2153 o A default value may apply if the parameter is missing. 2155 o Query parameter names and values are case-sensitive 2157 o A server MUST return an error with a '400 Bad Request' status-line 2158 if a query parameter is unexpected. 2160 +-------------------+-------------+---------------------------------+ 2161 | Name | Methods | Description | 2162 +-------------------+-------------+---------------------------------+ 2163 | content | GET, HEAD | Select config and/or non-config | 2164 | | | data resources | 2165 | depth | GET, HEAD | Request limited sub-tree depth | 2166 | | | in the reply content | 2167 | fields | GET, HEAD | Request a subset of the target | 2168 | | | resource contents | 2169 | filter | GET, HEAD | Boolean notification filter for | 2170 | | | event stream resources | 2171 | insert | POST, PUT | Insertion mode for ordered-by | 2172 | | | user data resources | 2173 | point | POST, PUT | Insertion point for ordered-by | 2174 | | | user data resources | 2175 | start-time | GET, HEAD | Replay buffer start time for | 2176 | | | event stream resources | 2177 | stop-time | GET, HEAD | Replay buffer stop time for | 2178 | | | event stream resources | 2179 | with-defaults | GET, HEAD | Control retrieval of default | 2180 | | | values | 2181 +-------------------+-------------+---------------------------------+ 2183 RESTCONF Query Parameters 2185 Refer to Appendix D.3 for examples of query parameter usage. 2187 If vendors define additional query parameters, they SHOULD use a 2188 prefix (such as the enterprise or organization name) for query 2189 parameter names in order to avoid collisions with other parameters. 2191 4.8.1. The "content" Query Parameter 2193 The "content" parameter controls how descendant nodes of the 2194 requested data nodes will be processed in the reply. 2196 The allowed values are: 2198 +-----------+-----------------------------------------------------+ 2199 | Value | Description | 2200 +-----------+-----------------------------------------------------+ 2201 | config | Return only configuration descendant data nodes | 2202 | nonconfig | Return only non-configuration descendant data nodes | 2203 | all | Return all descendant data nodes | 2204 +-----------+-----------------------------------------------------+ 2206 This parameter is only allowed for GET methods on datastore and data 2207 resources. A "400 Bad Request" status-line is returned if used for 2208 other methods or resource types. 2210 If this query parameter is not present, the default value is "all". 2211 This query parameter MUST be supported by the server. 2213 4.8.2. The "depth" Query Parameter 2215 The "depth" parameter is used to specify the number of nest levels 2216 returned in a response for a GET method. The first nest-level 2217 consists of the requested data node itself. If the "fields" 2218 parameter (Section 4.8.3) is used to select descendant data nodes, 2219 these nodes all have a depth value of 1. This has the effect of 2220 including the nodes specified by the fields, even if the "depth" 2221 value is less than the actual depth level of the specified fields. 2222 Any child nodes which are contained within a parent node have a depth 2223 value that is 1 greater than its parent. 2225 The value of the "depth" parameter is either an integer between 1 and 2226 65535, or the string "unbounded". "unbounded" is the default. 2228 This parameter is only allowed for GET methods on API, datastore, and 2229 data resources. A "400 Bad Request" status-line is returned if it 2230 used for other methods or resource types. 2232 By default, the server will include all sub-resources within a 2233 retrieved resource, which have the same resource type as the 2234 requested resource. The exception is the datastore resource. If 2235 this resource type is retrieved then by default the datastore and all 2236 child data resources are returned. 2238 If the "depth" query parameter URI is listed in the "capability" 2239 leaf-list in Section 9.3, then the server supports the "depth" query 2240 parameter. 2242 4.8.3. The "fields" Query Parameter 2244 The "fields" query parameter is used to optionally identify data 2245 nodes within the target resource to be retrieved in a GET method. 2246 The client can use this parameter to retrieve a subset of all nodes 2247 in a resource. 2249 A value of the "fields" query parameter matches the following rule: 2251 fields-expr = path '(' fields-expr ')' / 2252 path ';' fields-expr / 2253 path 2254 path = api-identifier [ '/' path ] 2256 "api-identifier" is defined in Section 3.5.3.1. 2258 ";" is used to select multiple nodes. For example, to retrieve only 2259 the "genre" and "year" of an album, use: "fields=genre;year". 2261 Parentheses are used to specify sub-selectors of a node. Note that 2262 there is no path separator character '/' between a "path" field and 2263 left parenthesis character '('. 2265 For example, assume the target resource is the "album" list. To 2266 retrieve only the "label" and "catalogue-number" of the "admin" 2267 container within an album, use: 2268 "fields=admin(label;catalogue-number)". 2270 "/" is used in a path to retrieve a child node of a node. For 2271 example, to retrieve only the "label" of an album, use: "fields=admin 2272 /label". 2274 This parameter is only allowed for GET methods on api, datastore, and 2275 data resources. A "400 Bad Request" status-line is returned if used 2276 for other methods or resource types. 2278 If the "fields" query parameter URI is listed in the "capability" 2279 leaf-list in Section 9.3, then the server supports the "fields" 2280 parameter. 2282 4.8.4. The "filter" Query Parameter 2284 The "filter" parameter is used to indicate which subset of all 2285 possible events are of interest. If not present, all events not 2286 precluded by other parameters will be sent. 2288 This parameter is only allowed for GET methods on a text/event-stream 2289 data resource. A "400 Bad Request" status-line is returned if used 2290 for other methods or resource types. 2292 The format of this parameter is an XPath 1.0 expression, and is 2293 evaluated in the following context: 2295 o The set of namespace declarations is the set of prefix and 2296 namespace pairs for all supported YANG modules, where the prefix 2297 is the YANG module name, and the namespace is as defined by the 2298 "namespace" statement in the YANG module. 2300 o The function library is the core function library defined in XPath 2301 1.0, plus any functions defined by the data model. 2303 o The set of variable bindings is empty. 2305 o The context node is the root node. 2307 The filter is used as defined in [RFC5277], Section 3.6. If the 2308 boolean result of the expression is true when applied to the 2309 conceptual "notification" document root, then the event notification 2310 is delivered to the client. 2312 If the "filter" query parameter URI is listed in the "capability" 2313 leaf-list in Section 9.3, then the server supports the "filter" query 2314 parameter. 2316 4.8.5. The "insert" Query Parameter 2318 The "insert" parameter is used to specify how a resource should be 2319 inserted within a ordered-by user list. 2321 The allowed values are: 2323 +-----------+-------------------------------------------------------+ 2324 | Value | Description | 2325 +-----------+-------------------------------------------------------+ 2326 | first | Insert the new data as the new first entry. | 2327 | last | Insert the new data as the new last entry. | 2328 | before | Insert the new data before the insertion point, as | 2329 | | specified by the value of the "point" parameter. | 2330 | after | Insert the new data after the insertion point, as | 2331 | | specified by the value of the "point" parameter. | 2332 +-----------+-------------------------------------------------------+ 2334 The default value is "last". 2336 This parameter is only supported for the POST and PUT methods. It is 2337 also only supported if the target resource is a data resource, and 2338 that data represents a YANG list or leaf-list that is ordered-by 2339 user. 2341 If the values "before" or "after" are used, then a "point" query 2342 parameter for the insertion parameter MUST also be present, or a "400 2343 Bad Request" status-line is returned. 2345 The "insert" query parameter MUST be supported by the server. 2347 4.8.6. The "point" Query Parameter 2349 The "point" parameter is used to specify the insertion point for a 2350 data resource that is being created or moved within an ordered-by 2351 user list or leaf-list. 2353 The value of the "point" parameter is a string that identifies the 2354 path to the insertion point object. The format is the same as a 2355 target resource URI string. 2357 This parameter is only supported for the POST and PUT methods. It is 2358 also only supported if the target resource is a data resource, and 2359 that data represents a YANG list or leaf-list that is ordered-by 2360 user. 2362 If the "insert" query parameter is not present, or has a value other 2363 than "before" or "after", then a "400 Bad Request" status-line is 2364 returned. 2366 This parameter contains the instance identifier of the resource to be 2367 used as the insertion point for a POST or PUT method. 2369 The "point" query parameter MUST be supported by the server. 2371 4.8.7. The "start-time" Query Parameter 2373 The "start-time" parameter is used to trigger the notification replay 2374 feature defined in [RFC5277] and indicate that the replay should 2375 start at the time specified. If the stream does not support replay, 2376 per the "replay-support" attribute returned by stream list entry for 2377 the stream resource, then the server MUST return a "400 Bad Request" 2378 status-line. 2380 The value of the "start-time" parameter is of type "date-and-time", 2381 defined in the "ietf-yang" YANG module [RFC6991]. 2383 This parameter is only allowed for GET methods on a text/event-stream 2384 data resource. A "400 Bad Request" status-line is returned if used 2385 for other methods or resource types. 2387 If this parameter is not present, then a replay subscription is not 2388 being requested. It is not valid to specify start times that are 2389 later than the current time. If the value specified is earlier than 2390 the log can support, the replay will begin with the earliest 2391 available notification. A client can obtain a server's current time 2392 by examining the "Date" header field that the server returns in 2393 response messages, according to [RFC7231]. 2395 If this query parameter is supported by the server, then the "replay" 2396 query parameter URI MUST be listed in the "capability" leaf-list in 2397 Section 9.3. The "stop-time" query parameter MUST also be supported 2398 by the server. 2400 If the "replay-support" leaf has the value 'true' in the "stream" 2401 entry (defined in Section 9.3) then the server MUST support the 2402 "start-time" and "stop-time" query parameters for that stream. 2404 4.8.8. The "stop-time" Query Parameter 2406 The "stop-time" parameter is used with the replay feature to indicate 2407 the newest notifications of interest. This parameter MUST be used 2408 with and have a value later than the "start-time" parameter. 2410 The value of the "stop-time" parameter is of type "date-and-time", 2411 defined in the "ietf-yang" YANG module [RFC6991]. 2413 This parameter is only allowed for GET methods on a text/event-stream 2414 data resource. A "400 Bad Request" status-line is returned if used 2415 for other methods or resource types. 2417 If this parameter is not present, the notifications will continue 2418 until the subscription is terminated. Values in the future are 2419 valid. 2421 If this query parameter is supported by the server, then the "replay" 2422 query parameter URI MUST be listed in the "capability" leaf-list in 2423 Section 9.3. The "start-time" query parameter MUST also be supported 2424 by the server. 2426 If the "replay-support" leaf is present in the "stream" entry 2427 (defined in Section 9.3) then the server MUST support the 2428 "start-time" and "stop-time" query parameters for that stream. 2430 4.8.9. The "with-defaults" Query Parameter 2432 The "with-defaults" parameter is used to specify how information 2433 about default data nodes should be returned in response to GET 2434 requests on data resources. 2436 If the server supports this capability, then it MUST implement the 2437 behavior in Section 4.5.1 of [RFC6243], except applied to the 2438 RESTCONF GET operation, instead of the NETCONF operations. 2440 +---------------------------+---------------------------------------+ 2441 | Value | Description | 2442 +---------------------------+---------------------------------------+ 2443 | report-all | All data nodes are reported | 2444 | trim | Data nodes set to the YANG default | 2445 | | are not reported | 2446 | explicit | Data nodes set to the YANG default by | 2447 | | the client are reported | 2448 | report-all-tagged | All data nodes are reported and | 2449 | | defaults are tagged | 2450 +---------------------------+---------------------------------------+ 2451 If the "with-defaults" parameter is set to "report-all" then the 2452 server MUST adhere to the defaults reporting behavior defined in 2453 Section 3.1 of [RFC6243]. 2455 If the "with-defaults" parameter is set to "trim" then the server 2456 MUST adhere to the defaults reporting behavior defined in Section 3.2 2457 of [RFC6243]. 2459 If the "with-defaults" parameter is set to "explicit" then the server 2460 MUST adhere to the defaults reporting behavior defined in Section 3.3 2461 of [RFC6243]. 2463 If the "with-defaults" parameter is set to "report-all-tagged" then 2464 the server MUST adhere to the defaults reporting behavior defined in 2465 Section 3.4 of [RFC6243]. 2467 If the "with-defaults" parameter is not present then the server MUST 2468 adhere to the defaults reporting behavior defined in its "basic-mode" 2469 parameter for the "defaults" protocol capability URI, defined in 2470 Section 9.1.2. 2472 If the server includes the "with-defaults" query parameter URI in the 2473 "capability" leaf-list in Section 9.3, then the "with-defaults" query 2474 parameter MUST be supported. 2476 5. Messages 2478 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 2479 message corresponds to a single protocol method. Most messages can 2480 perform a single task on a single resource, such as retrieving a 2481 resource or editing a resource. The exception is the PATCH method, 2482 which allows multiple datastore edits within a single message. 2484 5.1. Request URI Structure 2486 Resources are represented with URIs following the structure for 2487 generic URIs in [RFC3986]. 2489 A RESTCONF operation is derived from the HTTP method and the request 2490 URI, using the following conceptual fields: 2492 //?# 2494 ^ ^ ^ ^ ^ 2495 | | | | | 2496 method entry resource query fragment 2498 M M O O I 2500 M=mandatory, O=optional, I=ignored 2502 where: 2504 is the HTTP method 2505 is the RESTCONF entry point 2506 is the Target Resource URI 2507 is the query parameter list 2508 is not used in RESTCONF 2510 o method: the HTTP method identifying the RESTCONF operation 2511 requested by the client, to act upon the target resource specified 2512 in the request URI. RESTCONF operation details are described in 2513 Section 4. 2515 o entry: the root of the RESTCONF API configured on this HTTP 2516 server, discovered by getting the "/.well-known/host-meta" 2517 resource, as described in Section 3.1. 2519 o resource: the path expression identifying the resource that is 2520 being accessed by the operation. If this field is not present, 2521 then the target resource is the API itself, represented by the 2522 YANG data template named "yang-api", found in Section 8. 2524 o query: the set of parameters associated with the RESTCONF message, 2525 as defined in section 3.4 of [RFC3986]. RESTCONF parameters have 2526 the familiar form of "name=value" pairs. Most query parameters 2527 are optional to implement by the server and optional to use by the 2528 client. Each optional query parameter is identified by a URI. 2529 The server MUST list the optional query parameter URIs it supports 2530 in the "capabilities" list defined in Section 9.3. 2532 There is a specific set of parameters defined, although the server 2533 MAY choose to support query parameters not defined in this document. 2534 The contents of the any query parameter value MUST be encoded 2535 according to [RFC3986], Section 3.4. Any reserved characters MUST be 2536 percent-encoded, according to [RFC3986], section 2.1. 2538 o fragment: This field is not used by the RESTCONF protocol. 2540 When new resources are created by the client, a "Location" header is 2541 returned, which identifies the path of the newly created resource. 2542 The client uses this exact path identifier to access the resource 2543 once it has been created. 2545 The "target" of an operation is a resource. The "path" field in the 2546 request URI represents the target resource for the operation. 2548 Refer to Appendix D for examples of RESTCONF Request URIs. 2550 5.2. Message Encoding 2552 RESTCONF messages are encoded in HTTP according to [RFC7230]. The 2553 "utf-8" character set is used for all messages. RESTCONF message 2554 content is sent in the HTTP message-body. 2556 Content is encoded in either JSON or XML format. A server MUST 2557 support XML or JSON encoding. XML encoding rules for data nodes are 2558 defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are 2559 used for all XML content. JSON encoding rules are defined in 2560 [I-D.ietf-netmod-yang-json]. JSON encoding of metadata is defined in 2561 [I-D.ietf-netmod-yang-metadata]. This encoding is valid JSON, but 2562 also has special encoding rules to identify module namespaces and 2563 provide consistent type processing of YANG data. 2565 Request input content encoding format is identified with the Content- 2566 Type header. This field MUST be present if a message-body is sent by 2567 the client. 2569 The server MUST support the "Accept" header and "406 Not Acceptable" 2570 status-line, as defined in [RFC7231]. Response output content 2571 encoding format is identified with the Accept header in the request. 2572 If it is not specified, the request input encoding format SHOULD be 2573 used, or the server MAY choose any supported content encoding format. 2575 If there was no request input, then the default output encoding is 2576 XML or JSON, depending on server preference. File extensions encoded 2577 in the request are not used to identify format encoding. 2579 A client can determine if the RESTCONF server supports an encoding 2580 format by sending a request using a specific format in the Content- 2581 Type and/or Accept header. If the server does not support the 2582 requested input encoding for a request, then it MUST return an error 2583 response with a '415 Unsupported Media Type' status-line. If the 2584 server does not support any of the requested output encodings for a 2585 request, then it MUST return an error response with a '406 Not 2586 Acceptable' status-line. 2588 5.3. RESTCONF Metadata 2590 The RESTCONF protocol needs to retrieve the same metadata that is 2591 used in the NETCONF protocol. Information about default leafs, last- 2592 modified timestamps, etc. are commonly used to annotate 2593 representations of the datastore contents. 2595 With the XML encoding, the metadata is encoded as attributes in XML. 2596 With the JSON encoding, the metadata is encoded as specified in 2597 [I-D.ietf-netmod-yang-metadata]. 2599 The following examples are based on the example in Appendix D.3.9. 2600 The "report-all-tagged" mode for the "with-defaults" query parameter 2601 requires that a "default" attribute be returned for default nodes. 2602 This example shows that attribute for the "mtu" leaf . 2604 5.3.1. XML MetaData Encoding Example 2606 GET /restconf/data/interfaces/interface=eth1 2607 ?with-defaults=report-all-tagged HTTP/1.1 2608 Host: example.com 2609 Accept: application/yang-data 2611 The server might respond as follows. 2613 HTTP/1.1 200 OK 2614 Date: Mon, 23 Apr 2012 17:01:00 GMT 2615 Server: example-server 2616 Content-Type: application/yang-data 2618 2620 eth1 2621 1500 2623 up 2624 2626 5.3.2. JSON MetaData Encoding Example 2628 Note that RFC 6243 defines the "default" attribute with XSD, not 2629 YANG, so the YANG module name has to be assigned instead of derived 2630 from the YANG module name. The value "ietf-netconf-with-defaults" is 2631 assigned for JSON metadata encoding. 2633 GET /restconf/data/interfaces/interface=eth1 2634 ?with-defaults=report-all-tagged HTTP/1.1 2635 Host: example.com 2636 Accept: application/yang-data+json 2638 The server might respond as follows. 2640 HTTP/1.1 200 OK 2641 Date: Mon, 23 Apr 2012 17:01:00 GMT 2642 Server: example-server 2643 Content-Type: application/yang-data+json 2645 { 2646 "example:interface": [ 2647 { 2648 "name" : "eth1", 2649 "mtu" : 1500, 2650 "@mtu": { 2651 "ietf-netconf-with-defaults:default" : true 2652 }, 2653 "status" : "up" 2654 } 2655 ] 2656 } 2658 5.4. Return Status 2660 Each message represents some sort of resource access. An HTTP 2661 "status-line" header line is returned for each request. If a "4xx" 2662 range status code is returned in the status-line, then the error 2663 information SHOULD be returned in the response, according to the 2664 format defined in Section 7.1. If a "5xx" range status code is 2665 returned in the status-line, then the error information MAY be 2666 returned in the response, according to the format defined in 2667 Section 7.1. If a 1xx, 2xx, or 3xx range status code is returned in 2668 the status-line, then error information MUST NOT be returned in the 2669 response, since these ranges do not represent error conditions. 2671 5.5. Message Caching 2673 Since the datastore contents change at unpredictable times, responses 2674 from a RESTCONF server generally SHOULD NOT be cached. 2676 The server SHOULD include a "Cache-Control" header in every response 2677 that specifies whether the response should be cached. 2679 Instead of relying on HTTP caching, the client SHOULD track the 2680 "ETag" and/or "Last-Modified" headers returned by the server for the 2681 datastore resource (or data resource if the server supports it). A 2682 retrieval request for a resource can include the "If-None-Match" and/ 2683 or "If-Modified-Since" headers, which will cause the server to return 2684 a "304 Not Modified" status-line if the resource has not changed. 2685 The client MAY use the HEAD method to retrieve just the message 2686 headers, which SHOULD include the "ETag" and "Last-Modified" headers, 2687 if this metadata is maintained for the target resource. 2689 6. Notifications 2690 The RESTCONF protocol supports YANG-defined event notifications. The 2691 solution preserves aspects of NETCONF Event Notifications [RFC5277] 2692 while utilizing the Server-Sent Events [W3C.REC-eventsource-20150203] 2693 transport strategy. 2695 6.1. Server Support 2697 A RESTCONF server MAY support RESTCONF notifications. Clients may 2698 determine if a server supports RESTCONF notifications by using the 2699 HTTP operation OPTIONS, HEAD, or GET on the stream list. The server 2700 does not support RESTCONF notifications if an HTTP error code is 2701 returned (e.g., "404 Not Found" status-line). 2703 6.2. Event Streams 2705 A RESTCONF server that supports notifications will populate a stream 2706 resource for each notification delivery service access point. A 2707 RESTCONF client can retrieve the list of supported event streams from 2708 a RESTCONF server using the GET operation on the stream list. 2710 The "restconf-state/streams" container definition in the 2711 "ietf-restconf-monitoring" module (defined in Section 9.3) is used to 2712 specify the structure and syntax of the conceptual child resources 2713 within the "streams" resource. 2715 For example: 2717 The client might send the following request: 2719 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2720 streams HTTP/1.1 2721 Host: example.com 2722 Accept: application/yang-data 2724 The server might send the following response: 2726 HTTP/1.1 200 OK 2727 Content-Type: application/yang-data 2729 2731 2732 NETCONF 2733 default NETCONF event stream 2734 2735 true 2736 2737 2007-07-08T00:00:00Z 2739 2740 2741 xml 2742 https://example.com/streams/NETCONF 2743 2744 2745 2746 json 2747 https://example.com/streams/NETCONF-JSON 2748 2749 2750 2751 2752 SNMP 2753 SNMP notifications 2754 false 2755 2756 xml 2757 https://example.com/streams/SNMP 2758 2759 2760 2761 syslog-critical 2762 Critical and higher severity 2763 2764 true 2765 2766 2007-07-01T00:00:00Z 2767 2768 2769 xml 2770 2771 https://example.com/streams/syslog-critical 2772 2773 2774 2775 2777 6.3. Subscribing to Receive Notifications 2779 RESTCONF clients can determine the URL for the subscription resource 2780 (to receive notifications) by sending an HTTP GET request for the 2781 "location" leaf with the stream list entry. The value returned by 2782 the server can be used for the actual notification subscription. 2784 The client will send an HTTP GET request for the URL returned by the 2785 server with the "Accept" type "text/event-stream". 2787 The server will treat the connection as an event stream, using the 2788 Server Sent Events [W3C.REC-eventsource-20150203] transport strategy. 2790 The server MAY support query parameters for a GET method on this 2791 resource. These parameters are specific to each notification stream. 2793 For example: 2795 The client might send the following request: 2797 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2798 streams/stream=NETCONF/access=xml/location HTTP/1.1 2799 Host: example.com 2800 Accept: application/yang-data 2802 The server might send the following response: 2804 HTTP/1.1 200 OK 2805 Content-Type: application/yang-data 2807 2809 https://example.com/streams/NETCONF 2810 2812 The RESTCONF client can then use this URL value to start monitoring 2813 the event stream: 2815 GET /streams/NETCONF HTTP/1.1 2816 Host: example.com 2817 Accept: text/event-stream 2818 Cache-Control: no-cache 2819 Connection: keep-alive 2821 A RESTCONF client MAY request that the server compress the events 2822 using the HTTP header field "Accept-Encoding". For instance: 2824 GET /streams/NETCONF HTTP/1.1 2825 Host: example.com 2826 Accept: text/event-stream 2827 Cache-Control: no-cache 2828 Connection: keep-alive 2829 Accept-Encoding: gzip, deflate 2831 6.3.1. NETCONF Event Stream 2833 The server SHOULD support the "NETCONF" notification stream defined 2834 in [RFC5277]. For this stream, RESTCONF notification subscription 2835 requests MAY specify parameters indicating the events it wishes to 2836 receive. These query parameters are optional to implement, and only 2837 available if the server supports them. 2839 +------------+---------+-------------------------+ 2840 | Name | Section | Description | 2841 +------------+---------+-------------------------+ 2842 | start-time | 4.8.7 | replay event start time | 2843 | stop-time | 4.8.8 | replay event stop time | 2844 | filter | 4.8.4 | boolean content filter | 2845 +------------+---------+-------------------------+ 2847 NETCONF Stream Query Parameters 2849 The semantics and syntax for these query parameters are defined in 2850 the sections listed above. The YANG definition MUST be converted to 2851 a URI-encoded string for use in the request URI. 2853 Refer to Appendix D.3.6 for filter parameter examples. 2855 6.4. Receiving Event Notifications 2857 RESTCONF notifications are encoded according to the definition of the 2858 event stream. The NETCONF stream defined in [RFC5277] is encoded in 2859 XML format. 2861 The structure of the event data is based on the "notification" 2862 element definition in Section 4 of [RFC5277]. It MUST conform to the 2863 schema for the "notification" element in Section 4 of [RFC5277], 2864 except the XML namespace for this element is defined as: 2866 urn:ietf:params:xml:ns:yang:ietf-restconf 2868 For JSON encoding purposes, the module name for the "notification" 2869 element is "ietf-restconf". 2871 Two child nodes within the "notification" container are expected, 2872 representing the event time and the event payload. The "event-time" 2873 node is defined within the "ietf-restconf" module namespace. The 2874 name and namespace of the payload element are determined by the YANG 2875 module containing the notification-stmt. 2877 In the following example, the YANG module "example-mod" is used: 2879 module example-mod { 2880 namespace "http://example.com/event/1.0"; 2881 prefix ex; 2882 notification event { 2883 leaf event-class { type string; } 2884 container reporting-entity { 2885 leaf card { type string; } 2886 } 2887 leaf severity { type string; } 2888 } 2889 } 2891 An example SSE event notification encoded using XML: 2893 data: 2895 data: 2013-12-21T00:01:00Z 2896 data: 2897 data: fault 2898 data: 2899 data: Ethernet0 2900 data: 2901 data: major 2902 data: 2903 data: 2905 An example SSE event notification encoded using JSON: 2907 data: { 2908 data: "ietf-restconf:notification": { 2909 data: "event-time": "2013-12-21T00:01:00Z", 2910 data: "example-mod:event": { 2911 data: "event-class": "fault", 2912 data: "reporting-entity": { "card": "Ethernet0" }, 2913 data: "severity": "major" 2914 data: } 2915 data: } 2916 data: } 2918 Alternatively, since neither XML nor JSON are whitespace sensitive, 2919 the above messages can be encoded onto a single line. For example: 2921 For example: ('\' line wrapping added for formatting only) 2923 XML: 2925 data: 2013-12-21T00:01:00ZfaultEthernet0\ 2929 major 2930 JSON: 2932 data: {"ietf-restconf:notification":{"event-time":"2013-12-21\ 2933 T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ 2934 tingEntity":{"card":"Ethernet0"},"severity":"major"}}} 2936 The SSE specifications supports the following additional fields: 2937 event, id and retry. A RESTCONF server MAY send the "retry" field 2938 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 2939 SHOULD NOT send the "event" or "id" fields, as there are no 2940 meaningful values that could be used for them that would not be 2941 redundant to the contents of the notification itself. RESTCONF 2942 servers that do not send the "id" field also do not need to support 2943 the HTTP header "Last-Event-Id". RESTCONF servers that do send the 2944 "id" field MUST still support the "startTime" query parameter as the 2945 preferred means for a client to specify where to restart the event 2946 stream. 2948 7. Error Reporting 2950 HTTP status codes are used to report success or failure for RESTCONF 2951 operations. The element returned in NETCONF error 2952 responses contains some useful information. This error information 2953 is adapted for use in RESTCONF, and error information is returned for 2954 "4xx" and "5xx" class of status codes. 2956 Since an operation resource is defined with a YANG "rpc" statement, 2957 and an action is defined with a YANG "action" statement, a mapping 2958 between the NETCONF value and the HTTP status code is 2959 needed. The specific error-tag and response code to use are data- 2960 model specific and might be contained in the YANG "description" 2961 statement for the "action" or "rpc" statement. 2963 +-------------------------+-------------+ 2964 | error-tag | status code | 2965 +-------------------------+-------------+ 2966 | in-use | 409 | 2967 | invalid-value | 400 or 406 | 2968 | (request) too-big | 413 | 2969 | (response) too-big | 400 | 2970 | missing-attribute | 400 | 2971 | bad-attribute | 400 | 2972 | unknown-attribute | 400 | 2973 | bad-element | 400 | 2974 | unknown-element | 400 | 2975 | unknown-namespace | 400 | 2976 | access-denied | 403 | 2977 | lock-denied | 409 | 2978 | resource-denied | 409 | 2979 | rollback-failed | 500 | 2980 | data-exists | 409 | 2981 | data-missing | 409 | 2982 | operation-not-supported | 501 | 2983 | operation-failed | 412 or 500 | 2984 | partial-operation | 500 | 2985 | malformed-message | 400 | 2986 +-------------------------+-------------+ 2988 Mapping from error-tag to status code 2990 7.1. Error Response Message 2992 When an error occurs for a request message on any resource type, and 2993 the status code that will be returned is in the "4xx" range (except 2994 for status code "403 Forbidden"), then the server SHOULD send a 2995 response message-body containing the information described by the 2996 "yang-errors" YANG template definition within the "ietf-restconf" 2997 module, found in Section 8. The Content-Type of this response 2998 message MUST be a subtype of application/yang-data (see example 2999 below). 3001 The client SHOULD specify the desired encoding for error messages by 3002 specifying the appropriate media-type in the Accept header. If no 3003 error media is specified, then the media subtype (e.g., XML or JSON) 3004 of the request message SHOULD be used, or the server MAY choose any 3005 supported message encoding format. If there is no request message 3006 the server MUST select "application/yang-data" or "application/ 3007 yang-data+json", depending on server preference. All of the examples 3008 in this document, except for the one below, assume that XML encoding 3009 will be returned if there is an error. 3011 YANG Tree Diagram for data: 3013 +--ro errors 3014 +--ro error* 3015 +--ro error-type enumeration 3016 +--ro error-tag string 3017 +--ro error-app-tag? string 3018 +--ro error-path? instance-identifier 3019 +--ro error-message? string 3020 +--ro error-info 3022 The semantics and syntax for RESTCONF error messages are defined with 3023 the "yang-errors" YANG data template extension, found in Section 8. 3025 Examples: 3027 The following example shows an error returned for an "lock-denied" 3028 error that can occur if a NETCONF client has locked a datastore. The 3029 RESTCONF client is attempting to delete a data resource. Note that 3030 an Accept header is used to specify the desired encoding for the 3031 error message. No response message-body content is expected by the 3032 client in this example. 3034 DELETE /restconf/data/example-jukebox:jukebox/ 3035 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 3036 Host: example.com 3037 Accept: application/yang-data+json 3039 The server might respond: 3041 HTTP/1.1 409 Conflict 3042 Date: Mon, 23 Apr 2012 17:11:00 GMT 3043 Server: example-server 3044 Content-Type: application/yang-data+json 3046 { 3047 "ietf-restconf:errors": { 3048 "error": [ 3049 { 3050 "error-type": "protocol", 3051 "error-tag": "lock-denied", 3052 "error-message": "Lock failed, lock already held" 3053 } 3054 ] 3055 } 3056 } 3058 The following example shows an error returned for a "data-exists" 3059 error on a data resource. The "jukebox" resource already exists so 3060 it cannot be created. 3062 The client might send: 3064 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 3065 Host: example.com 3067 The server might respond (some lines wrapped for display purposes): 3069 HTTP/1.1 409 Conflict 3070 Date: Mon, 23 Apr 2012 17:11:00 GMT 3071 Server: example-server 3072 Content-Type: application/yang-data 3073 3074 3075 protocol 3076 data-exists 3077 3080 /rc:restconf/rc:data/jbox:jukebox 3081 3082 3083 Data already exists, cannot create new resource 3084 3085 3086 3088 8. RESTCONF module 3090 The "ietf-restconf" module defines conceptual definitions within an 3091 extension and two groupings, which are not meant to be implemented as 3092 datastore contents by a server. E.g., the "restconf" container is 3093 not intended to be implemented as a top-level data node (under the "/ 3094 restconf/data" entry point). 3096 Note that the "ietf-restconf" module does not have any protocol- 3097 accessible objects, so no YANG tree diagram is shown. 3099 RFC Ed.: update the date below with the date of RFC publication and 3100 remove this note. 3102 file "ietf-restconf@2016-07-07.yang" 3104 module ietf-restconf { 3105 yang-version 1.1; 3106 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 3107 prefix "rc"; 3109 organization 3110 "IETF NETCONF (Network Configuration) Working Group"; 3112 contact 3113 "WG Web: 3114 WG List: 3116 Editor: Andy Bierman 3117 3119 Editor: Martin Bjorklund 3120 3122 Editor: Kent Watsen 3123 "; 3125 description 3126 "This module contains conceptual YANG specifications 3127 for basic RESTCONF media type definitions used in 3128 RESTCONF protocol messages. 3130 Note that the YANG definitions within this module do not 3131 represent configuration data of any kind. 3132 The 'restconf-media-type' YANG extension statement 3133 provides a normative syntax for XML and JSON message 3134 encoding purposes. 3136 Copyright (c) 2016 IETF Trust and the persons identified as 3137 authors of the code. All rights reserved. 3139 Redistribution and use in source and binary forms, with or 3140 without modification, is permitted pursuant to, and subject 3141 to the license terms contained in, the Simplified BSD License 3142 set forth in Section 4.c of the IETF Trust's Legal Provisions 3143 Relating to IETF Documents 3144 (http://trustee.ietf.org/license-info). 3146 This version of this YANG module is part of RFC XXXX; see 3147 the RFC itself for full legal notices."; 3149 // RFC Ed.: replace XXXX with actual RFC number and remove this 3150 // note. 3152 // RFC Ed.: remove this note 3153 // Note: extracted from draft-ietf-netconf-restconf-15.txt 3155 // RFC Ed.: update the date below with the date of RFC publication 3156 // and remove this note. 3157 revision 2016-07-07 { 3158 description 3159 "Initial revision."; 3160 reference 3161 "RFC XXXX: RESTCONF Protocol."; 3162 } 3164 extension yang-data { 3165 argument name { 3166 yin-element true; 3167 } 3168 description 3169 "This extension is used to specify a YANG data template which 3170 represents conceptual data defined in YANG. It is 3171 intended to describe hierarchical data independent of 3172 protocol context or specific message encoding format. 3173 Data definition statements within this extension specify 3174 the generic syntax for the specific YANG data template. 3176 Note that this extension does not define a media-type. 3177 A specification using this extension MUST specify the 3178 message encoding rules, including the content media type. 3180 The mandatory 'name' parameter value identifies the YANG 3181 data template that is being defined. It contains the 3182 template name. 3184 This extension is ignored unless it appears as a top-level 3185 statement. It SHOULD contain data definition statements 3186 that result in exactly one container data node definition. 3187 This allows compliant translation to an XML instance 3188 document for each YANG data template. 3190 The module name and namespace value for the YANG module using 3191 the extension statement is assigned to instance document data 3192 conforming to the data definition statements within 3193 this extension. 3195 The sub-statements of this extension MUST follow the 3196 'data-def-stmt' rule in the YANG ABNF. 3198 The XPath document root is the extension statement itself, 3199 such that the child nodes of the document root are 3200 represented by the data-def-stmt sub-statements within 3201 this extension. This conceptual document is the context 3202 for the following YANG statements: 3204 - must-stmt 3205 - when-stmt 3206 - path-stmt 3207 - min-elements-stmt 3208 - max-elements-stmt 3209 - mandatory-stmt 3210 - unique-stmt 3211 - ordered-by 3212 - instance-identifier data type 3214 The following data-def-stmt sub-statements have special 3215 meaning when used within a yang-data-resource extension 3216 statement. 3218 - The list-stmt is not required to have a key-stmt defined. 3219 - The if-feature-stmt is ignored if present. 3220 - The config-stmt is ignored if present. 3221 - The available identity values for any 'identityref' 3222 leaf or leaf-list nodes is limited to the module 3223 containing this extension statement, and the modules 3224 imported into that module. 3225 "; 3226 } 3228 rc:yang-data yang-errors { 3229 uses errors; 3230 } 3232 rc:yang-data yang-api { 3233 uses restconf; 3234 } 3236 grouping errors { 3237 description 3238 "A grouping that contains a YANG container 3239 representing the syntax and semantics of a 3240 YANG Patch errors report within a response message."; 3242 container errors { 3243 description 3244 "Represents an error report returned by the server if 3245 a request results in an error."; 3247 list error { 3248 description 3249 "An entry containing information about one 3250 specific error that occurred while processing 3251 a RESTCONF request."; 3252 reference "RFC 6241, Section 4.3"; 3254 leaf error-type { 3255 type enumeration { 3256 enum transport { 3257 description "The transport layer"; 3258 } 3259 enum rpc { 3260 description "The rpc or notification layer"; 3261 } 3262 enum protocol { 3263 description "The protocol operation layer"; 3264 } 3265 enum application { 3266 description "The server application layer"; 3267 } 3268 } 3269 mandatory true; 3270 description 3271 "The protocol layer where the error occurred."; 3272 } 3274 leaf error-tag { 3275 type string; 3276 mandatory true; 3277 description 3278 "The enumerated error tag."; 3279 } 3281 leaf error-app-tag { 3282 type string; 3283 description 3284 "The application-specific error tag."; 3285 } 3287 leaf error-path { 3288 type instance-identifier; 3289 description 3290 "The YANG instance identifier associated 3291 with the error node."; 3292 } 3294 leaf error-message { 3295 type string; 3296 description 3297 "A message describing the error."; 3298 } 3300 anydata error-info { 3301 description 3302 "This anydata value MUST represent a container with 3303 zero or more data nodes representing additional 3304 error information."; 3305 } 3306 } 3307 } 3308 } 3310 grouping restconf { 3311 description 3312 "Conceptual container representing the 3313 application/yang-api resource type."; 3315 container restconf { 3316 description 3317 "Conceptual container representing the 3318 application/yang-api resource type."; 3320 container data { 3321 description 3322 "Container representing the application/yang-datastore 3323 resource type. Represents the conceptual root of all 3324 state data and configuration data supported by 3325 the server. The child nodes of this container can be 3326 any data resource (application/yang-data), which are 3327 defined as top-level data nodes from the YANG modules 3328 advertised by the server in the ietf-restconf-monitoring 3329 module."; 3330 } 3332 container operations { 3333 description 3334 "Container for all operation resources 3335 (application/yang-operation), 3337 Each resource is represented as an empty leaf with the 3338 name of the RPC operation from the YANG rpc statement. 3340 For example, the 'system-restart' RPC operation defined 3341 in the 'ietf-system' module would be represented as 3342 an empty leaf in the 'ietf-system' namespace. This is 3343 a conceptual leaf, and will not actually be found in 3344 the module: 3346 module ietf-system { 3347 leaf system-reset { 3348 type empty; 3349 } 3350 } 3352 To invoke the 'system-restart' RPC operation: 3354 POST /restconf/operations/ietf-system:system-restart 3356 To discover the RPC operations supported by the server: 3358 GET /restconf/operations 3360 In XML the YANG module namespace identifies the module: 3362 3365 In JSON the YANG module name identifies the module: 3367 { 'ietf-system:system-restart' : [null] } 3369 "; 3370 } 3372 leaf yang-library-version { 3373 type string { 3374 pattern '\d{4}-\d{2}-\d{2}'; 3375 } 3376 config false; 3377 mandatory true; 3378 description 3379 "Identifies the revision date of the ietf-yang-library 3380 module that is implemented by this RESTCONF server. 3381 Indicates the year, month, and day in YYYY-MM-DD 3382 numeric format."; 3383 } 3384 } 3385 } 3387 } 3389 3391 9. RESTCONF Monitoring 3393 The "ietf-restconf-monitoring" module provides information about the 3394 RESTCONF protocol capabilities and event notification streams 3395 available from the server. A RESTCONF server MUST implement the "/ 3396 restconf-state/capabilities" container in this module. 3398 YANG Tree Diagram for "ietf-restconf-monitoring" module: 3400 +--ro restconf-state 3401 +--ro capabilities 3402 | +--ro capability* inet:uri 3403 +--ro streams 3404 +--ro stream* [name] 3405 +--ro name string 3406 +--ro description? string 3407 +--ro replay-support? boolean 3408 +--ro replay-log-creation-time? yang:date-and-time 3409 +--ro access* [encoding] 3410 +--ro encoding string 3411 +--ro location inet:uri 3413 9.1. restconf-state/capabilities 3415 This mandatory container holds the RESTCONF protocol capability URIs 3416 supported by the server. 3418 The server MAY maintain a last-modified timestamp for this container, 3419 and return the "Last-Modified" header when this data node is 3420 retrieved with the GET or HEAD methods. Note that the last-modified 3421 timestamp for the datastore resource is not affected by changes to 3422 this subtree. 3424 The server SHOULD maintain an entity-tag for this container, and 3425 return the "ETag" header when this data node is retrieved with the 3426 GET or HEAD methods. Note that the entity-tag for the datastore 3427 resource is not affected by changes to this subtree. 3429 The server MUST include a "capability" URI leaf-list entry for the 3430 "defaults" mode used by the server, defined in Section 9.1.2. 3432 The server MUST include a "capability" URI leaf-list entry 3433 identifying each supported optional protocol feature. This includes 3434 optional query parameters and MAY include other capability URIs 3435 defined outside this document. 3437 9.1.1. Query Parameter URIs 3439 A new set of RESTCONF Capability URIs are defined to identify the 3440 specific query parameters (defined in Section 4.8) supported by the 3441 server. 3443 The server MUST include a "capability" leaf-list entry for each 3444 optional query parameter that it supports. 3446 +-------------+-------+---------------------------------------------+ 3447 | Name | Secti | URI | 3448 | | on | | 3449 +-------------+-------+---------------------------------------------+ 3450 | depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 | 3451 | | | .0 | 3452 | fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: | 3453 | | | 1.0 | 3454 | filter | 4.8.4 | urn:ietf:params:restconf:capability:filter: | 3455 | | | 1.0 | 3456 | replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: | 3457 | | 4.8.8 | 1.0 | 3458 | with- | 4.8.9 | urn:ietf:params:restconf:capability:with- | 3459 | defaults | | defaults:1.0 | 3460 +-------------+-------+---------------------------------------------+ 3462 RESTCONF Query Parameter URIs 3464 9.1.2. The "defaults" Protocol Capability URI 3466 This URI identifies the defaults handling mode that is used by the 3467 server for processing default leafs in requests for data resources. 3468 A parameter named "basic-mode" is required for this capability URI. 3469 The "basic-mode" definitions are specified in the "With-Defaults 3470 Capability for NETCONF" [RFC6243]. 3472 +----------+--------------------------------------------------+ 3473 | Name | URI | 3474 +----------+--------------------------------------------------+ 3475 | defaults | urn:ietf:params:restconf:capability:defaults:1.0 | 3476 +----------+--------------------------------------------------+ 3478 RESTCONF defaults capability URI 3480 This protocol capability URI MUST be supported by the server, and 3481 MUST be listed in the "capability" leaf-list in Section 9.3. 3483 +------------------+------------------------------------------------+ 3484 | Value | Description | 3485 +------------------+------------------------------------------------+ 3486 | report-all | No data nodes are considered default | 3487 | trim | Values set to the YANG default-stmt value are | 3488 | | default | 3489 | explicit | Values set by the client are never considered | 3490 | | default | 3491 +------------------+------------------------------------------------+ 3493 If the "basic-mode" is set to "report-all" then the server MUST 3494 adhere to the defaults handling behavior defined in Section 2.1 of 3495 [RFC6243]. 3497 If the "basic-mode" is set to "trim" then the server MUST adhere to 3498 the defaults handling behavior defined in Section 2.2 of [RFC6243]. 3500 If the "basic-mode" is set to "explicit" then the server MUST adhere 3501 to the defaults handling behavior defined in Section 2.3 of 3502 [RFC6243]. 3504 Example: (split for display purposes only) 3506 urn:ietf:params:restconf:capability:defaults:1.0? 3507 basic-mode=explicit 3509 9.2. restconf-state/streams 3511 This optional container provides access to the event notification 3512 streams supported by the server. The server MAY omit this container 3513 if no event notification streams are supported. 3515 The server will populate this container with a stream list entry for 3516 each stream type it supports. Each stream contains a leaf called 3517 "events" which contains a URI that represents an event stream 3518 resource. 3520 Stream resources are defined in Section 3.8. Notifications are 3521 defined in Section 6. 3523 9.3. RESTCONF Monitoring Module 3525 The "ietf-restconf-monitoring" module defines monitoring information 3526 for the RESTCONF protocol. 3528 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 3529 are used by this module for some type definitions. 3531 RFC Ed.: update the date below with the date of RFC publication and 3532 remove this note. 3534 file "ietf-restconf-monitoring@2016-07-07.yang" 3536 module ietf-restconf-monitoring { 3537 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; 3538 prefix "rcmon"; 3540 import ietf-yang-types { prefix yang; } 3541 import ietf-inet-types { prefix inet; } 3543 organization 3544 "IETF NETCONF (Network Configuration) Working Group"; 3546 contact 3547 "WG Web: 3548 WG List: 3550 Editor: Andy Bierman 3551 3553 Editor: Martin Bjorklund 3554 3556 Editor: Kent Watsen 3557 "; 3559 description 3560 "This module contains monitoring information for the 3561 RESTCONF protocol. 3563 Copyright (c) 2016 IETF Trust and the persons identified as 3564 authors of the code. All rights reserved. 3566 Redistribution and use in source and binary forms, with or 3567 without modification, is permitted pursuant to, and subject 3568 to the license terms contained in, the Simplified BSD License 3569 set forth in Section 4.c of the IETF Trust's Legal Provisions 3570 Relating to IETF Documents 3571 (http://trustee.ietf.org/license-info). 3573 This version of this YANG module is part of RFC XXXX; see 3574 the RFC itself for full legal notices."; 3576 // RFC Ed.: replace XXXX with actual RFC number and remove this 3577 // note. 3579 // RFC Ed.: remove this note 3580 // Note: extracted from draft-ietf-netconf-restconf-15.txt 3582 // RFC Ed.: update the date below with the date of RFC publication 3583 // and remove this note. 3584 revision 2016-07-07 { 3585 description 3586 "Initial revision."; 3587 reference 3588 "RFC XXXX: RESTCONF Protocol."; 3589 } 3591 container restconf-state { 3592 config false; 3593 description 3594 "Contains RESTCONF protocol monitoring information."; 3596 container capabilities { 3597 description 3598 "Contains a list of protocol capability URIs"; 3600 leaf-list capability { 3601 type inet:uri; 3602 description "A RESTCONF protocol capability URI."; 3603 } 3604 } 3606 container streams { 3607 description 3608 "Container representing the notification event streams 3609 supported by the server."; 3610 reference 3611 "RFC 5277, Section 3.4, element."; 3613 list stream { 3614 key name; 3615 description 3616 "Each entry describes an event stream supported by 3617 the server."; 3619 leaf name { 3620 type string; 3621 description "The stream name"; 3622 reference "RFC 5277, Section 3.4, element."; 3623 } 3625 leaf description { 3626 type string; 3627 description "Description of stream content"; 3628 reference 3629 "RFC 5277, Section 3.4, element."; 3630 } 3632 leaf replay-support { 3633 type boolean; 3634 description 3635 "Indicates if replay buffer supported for this stream. 3636 If 'true', then the server MUST support the 'start-time' 3637 and 'stop-time' query parameters for this stream."; 3638 reference 3639 "RFC 5277, Section 3.4, element."; 3640 } 3641 leaf replay-log-creation-time { 3642 when "../replay-support" { 3643 description 3644 "Only present if notification replay is supported"; 3645 } 3646 type yang:date-and-time; 3647 description 3648 "Indicates the time the replay log for this stream 3649 was created."; 3650 reference 3651 "RFC 5277, Section 3.4, 3652 element."; 3653 } 3655 list access { 3656 key encoding; 3657 min-elements 1; 3658 description 3659 "The server will create an entry in this list for each 3660 encoding format that is supported for this stream. 3661 The media type 'text/event-stream' is expected 3662 for all event streams. This list identifies the 3663 sub-types supported for this stream."; 3665 leaf encoding { 3666 type string; 3667 description 3668 "This is the secondary encoding format within the 3669 'text/event-stream' encoding used by all streams. 3670 The type 'xml' is supported for XML encoding. 3671 The type 'json' is supported for JSON encoding."; 3672 } 3674 leaf location { 3675 type inet:uri; 3676 mandatory true; 3677 description 3678 "Contains a URL that represents the entry point 3679 for establishing notification delivery via server 3680 sent events."; 3681 } 3682 } 3683 } 3684 } 3685 } 3687 } 3688 3690 10. YANG Module Library 3692 The "ietf-yang-library" module defined in 3693 [I-D.ietf-netconf-yang-library] provides information about the YANG 3694 modules and submodules used by the RESTCONF server. Implementation 3695 is mandatory for RESTCONF servers. All YANG modules and submodules 3696 used by the server MUST be identified in the YANG module library. 3698 10.1. modules-state 3700 This mandatory container holds the identifiers for the YANG data 3701 model modules supported by the server. 3703 10.1.1. modules-state/module 3705 This mandatory list contains one entry for each YANG data model 3706 module supported by the server. There MUST be an instance of this 3707 list for every YANG module that is used by the server. 3709 The contents of this list are defined in the "module" YANG list 3710 statement in [I-D.ietf-netconf-yang-library]. 3712 11. IANA Considerations 3714 11.1. The "restconf" Relation Type 3716 This specification registers the "restconf" relation type in the Link 3717 Relation Type Registry defined by [RFC5988]: 3719 Relation Name: restconf 3721 Description: Identifies the root of RESTCONF API as configured 3722 on this HTTP server. The "restconf" relation 3723 defines the root of the API defined in RFCXXXX. 3724 Subsequent revisions of RESTCONF will use alternate 3725 relation values to support protocol versioning. 3727 Reference: RFCXXXX 3729 ` 3731 11.2. YANG Module Registry 3733 This document registers two URIs as namespaces in the IETF XML 3734 registry [RFC3688]. Following the format in RFC 3688, the following 3735 registration is requested: 3737 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 3738 Registrant Contact: The NETMOD WG of the IETF. 3739 XML: N/A, the requested URI is an XML namespace. 3741 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3742 Registrant Contact: The NETMOD WG of the IETF. 3743 XML: N/A, the requested URI is an XML namespace. 3745 This document registers two YANG modules in the YANG Module Names 3746 registry [RFC6020]: 3748 name: ietf-restconf 3749 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3750 prefix: rc 3751 // RFC Ed.: replace XXXX with RFC number and remove this note 3752 reference: RFCXXXX 3754 name: ietf-restconf-monitoring 3755 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3756 prefix: rcmon 3757 // RFC Ed.: replace XXXX with RFC number and remove this note 3758 reference: RFCXXXX 3760 11.3. Media Types 3762 11.3.1. Media Type application/yang-data 3764 Type name: application 3766 Subtype name: yang-data 3768 Required parameters: None 3770 Optional parameters: None 3772 // RFC Ed.: replace draft-ietf-netmod-rfc6020bis with 3773 // the actual RFC reference for YANG 1.1, and remove this note. 3775 Encoding considerations: 8-bit 3776 Each conceptual YANG data node is encoded according to the 3777 XML Encoding Rules and Canonical Format for the specific 3778 YANG data node type defined in [draft-ietf-netmod-rfc6020bis]. 3780 // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the 3781 // section number for Security Considerations 3782 // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual 3783 // RFC number, and remove this note. 3785 Security considerations: Security considerations related 3786 to the generation and consumption of RESTCONF messages 3787 are discussed in Section NN of [RFCXXXX]. 3788 Additional security considerations are specific to the 3789 semantics of particular YANG data models. Each YANG module 3790 is expected to specify security considerations for the 3791 YANG data defined in that module. 3793 // RFC Ed.: replace XXXX with actual RFC number and remove this 3794 // note. 3796 Interoperability considerations: [RFCXXXX] specifies the 3797 format of conforming messages and the interpretation 3798 thereof. 3800 // RFC Ed.: replace XXXX with actual RFC number and remove this 3801 // note. 3803 Published specification: RFC XXXX 3805 Applications that use this media type: Instance document 3806 data parsers used within a protocol or automation tool 3807 that utilize YANG defined data structures. 3809 Fragment identifier considerations: The fragment field in the 3810 request URI has no defined purpose. 3812 Additional information: 3814 Deprecated alias names for this type: N/A 3815 Magic number(s): N/A 3816 File extension(s): .xml 3817 Macintosh file type code(s): "TEXT" 3819 // RFC Ed.: replace XXXX with actual RFC number and remove this 3820 // note. 3822 Person & email address to contact for further information: See 3823 Authors' Addresses section of [RFCXXXX]. 3825 Intended usage: COMMON 3827 Restrictions on usage: N/A 3829 // RFC Ed.: replace XXXX with actual RFC number and remove this 3830 // note. 3832 Author: See Authors' Addresses section of [RFCXXXX]. 3834 Change controller: Internet Engineering Task Force 3835 (mailto:iesg&ietf.org). 3837 Provisional registration? (standards tree only): no 3839 11.3.2. Media Type application/yang-data+json 3841 Type name: application 3843 Subtype name: yang-data+json 3845 Required parameters: None 3847 Optional parameters: None 3849 // RFC Ed.: replace draft-ietf-netmod-yang-json with 3850 // the actual RFC reference for JSON Encoding of YANG Data, 3851 // and remove this note. 3853 // RFC Ed.: replace draft-ietf-netmod-yang-metadata with 3854 // the actual RFC reference for JSON Encoding of YANG Data, 3855 // and remove this note. 3857 Encoding considerations: 8-bit 3858 Each conceptual YANG data node is encoded according to 3859 [draft-ietf-netmod-yang-json]. A data annotation is 3860 encoded according to [draft-ietf-netmod-yang-metadata] 3862 // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the 3863 // section number for Security Considerations 3864 // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual 3865 // RFC number, and remove this note. 3867 Security considerations: Security considerations related 3868 to the generation and consumption of RESTCONF messages 3869 are discussed in Section NN of [RFCXXXX]. 3870 Additional security considerations are specific to the 3871 semantics of particular YANG data models. Each YANG module 3872 is expected to specify security considerations for the 3873 YANG data defined in that module. 3875 // RFC Ed.: replace XXXX with actual RFC number and remove this 3876 // note. 3878 Interoperability considerations: [RFCXXXX] specifies the format 3879 of conforming messages and the interpretation thereof. 3881 // RFC Ed.: replace XXXX with actual RFC number and remove this 3882 // note. 3884 Published specification: RFC XXXX 3886 Applications that use this media type: Instance document 3887 data parsers used within a protocol or automation tool 3888 that utilize YANG defined data structures. 3890 Fragment identifier considerations: The syntax and semantics 3891 of fragment identifiers are the same as specified for the 3892 "application/json" media type. 3894 Additional information: 3896 Deprecated alias names for this type: N/A 3897 Magic number(s): N/A 3898 File extension(s): .json 3899 Macintosh file type code(s): "TEXT" 3901 // RFC Ed.: replace XXXX with actual RFC number and remove this 3902 // note. 3904 Person & email address to contact for further information: See 3905 Authors' Addresses section of [RFCXXXX]. 3907 Intended usage: COMMON 3909 Restrictions on usage: N/A 3911 // RFC Ed.: replace XXXX with actual RFC number and remove this 3912 // note. 3914 Author: See Authors' Addresses section of [RFCXXXX]. 3916 Change controller: Internet Engineering Task Force 3917 (mailto:iesg&ietf.org). 3919 Provisional registration? (standards tree only): no 3921 11.4. RESTCONF Capability URNs 3923 [Note to RFC Editor: 3924 The RESTCONF Protocol Capability Registry does not yet exist; 3925 Need to ask IANA to create it; remove this note for publication 3926 ] 3928 This document defines a registry for RESTCONF capability identifiers. 3929 The name of the registry is "RESTCONF Capability URNs". The review 3930 policy for this registry is "IETF Review". The registry shall record 3931 for each entry: 3933 o the name of the RESTCONF capability. By convention, this name 3934 begins with the colon ':' character. 3936 o the URN for the RESTCONF capability. 3938 This document registers several capability identifiers in "RESTCONF 3939 Capability URNs" registry: 3941 Index 3942 Capability Identifier 3943 ------------------------ 3945 :defaults 3946 urn:ietf:params:restconf:capability:defaults:1.0 3948 :depth 3949 urn:ietf:params:restconf:capability:depth:1.0 3951 :fields 3952 urn:ietf:params:restconf:capability:fields:1.0 3954 :filter 3955 urn:ietf:params:restconf:capability:filter:1.0 3957 :replay 3958 urn:ietf:params:restconf:capability:replay:1.0 3960 :with-defaults 3961 urn:ietf:params:restconf:capability:with-defaults:1.0 3963 12. Security Considerations 3965 The "ietf-restconf-monitoring" YANG module defined in this memo is 3966 designed to be accessed via the NETCONF protocol [RFC6241]. The 3967 lowest NETCONF layer is the secure transport layer, and the 3968 mandatory-to-implement secure transport is Secure Shell (SSH) 3970 [RFC6242]. The NETCONF access control model [RFC6536] provides the 3971 means to restrict access for particular NETCONF users to a pre- 3972 configured subset of all available NETCONF protocol operations and 3973 content. 3975 This section provides security considerations for the resources 3976 defined by the RESTCONF protocol. Security considerations for HTTPS 3977 are defined in [RFC7230]. RESTCONF does not specify which YANG 3978 modules a server needs to support. Security considerations for the 3979 YANG-defined content manipulated by RESTCONF can be found in the 3980 documents defining those YANG modules. 3982 This document does not require use of a specific client 3983 authentication mechanism or authorization model, but it does require 3984 that a client authentication mechanism and authorization model is 3985 used whenever a client accesses a protected resource. Client 3986 authentication MUST be implemented using client certificates or MUST 3987 be implemented using an HTTP authentication scheme. Client 3988 authorization MAY be configured using the NETCONF Access Control 3989 Model (NACM) [RFC6536]. 3991 Configuration information is by its very nature sensitive. Its 3992 transmission in the clear and without integrity checking leaves 3993 devices open to classic eavesdropping and false data injection 3994 attacks. Configuration information often contains passwords, user 3995 names, service descriptions, and topological information, all of 3996 which are sensitive. Because of this, this protocol SHOULD be 3997 implemented carefully with adequate attention to all manner of attack 3998 one might expect to experience with other management interfaces. 4000 Different environments may well allow different rights prior to and 4001 then after authentication. When an operation is not properly 4002 authorized, the RESTCONF server MUST return a "401 Unauthorized" 4003 status-line. Note that authorization information can be exchanged in 4004 the form of configuration information, which is all the more reason 4005 to ensure the security of the connection. Note that it is possible 4006 for a client to detect configuration changes in data resources it is 4007 not authorized to access by monitoring changes in the ETag and Last- 4008 Modified header fields returned by the server for the datastore 4009 resource. 4011 13. Acknowledgements 4013 The authors would like to thank the following people for their 4014 contributions to this document: Ladislav Lhotka, Juergen 4015 Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. 4017 The authors would like to thank the following people for their 4018 excellent technical reviews of this document: Mehmet Ersue, Mahesh 4019 Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka, 4020 Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint 4021 Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise, and 4022 Dale Worley. 4024 Contributions to this material by Andy Bierman are based upon work 4025 supported by the United States Army, Space & Terrestrial 4026 Communications Directorate (S&TCD) under Contract No. 4027 W15P7T-13-C-A616. Any opinions, findings and conclusions or 4028 recommendations expressed in this material are those of the author(s) 4029 and do not necessarily reflect the views of The Space & Terrestrial 4030 Communications Directorate (S&TCD). 4032 14. References 4034 14.1. Normative References 4036 [I-D.ietf-netconf-yang-library] 4037 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 4038 Library", draft-ietf-netconf-yang-library-06 (work in 4039 progress), April 2016. 4041 [I-D.ietf-netmod-rfc6020bis] 4042 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 4043 draft-ietf-netmod-rfc6020bis-14 (work in progress), June 4044 2016. 4046 [I-D.ietf-netmod-yang-json] 4047 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 4048 draft-ietf-netmod-yang-json-10 (work in progress), March 4049 2016. 4051 [I-D.ietf-netmod-yang-metadata] 4052 Lhotka, L., "Defining and Using Metadata with YANG", 4053 draft-ietf-netmod-yang-metadata-07 (work in progress), 4054 March 2016. 4056 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4057 Extensions (MIME) Part Two: Media Types", RFC 2046, 4058 November 1996. 4060 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4061 Requirement Levels", BCP 14, RFC 2119, March 1997. 4063 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4064 January 2004. 4066 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4067 Resource Identifier (URI): Generic Syntax", STD 66, RFC 4068 3986, January 2005. 4070 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4071 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 4073 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 4074 Notifications", RFC 5277, July 2008. 4076 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4077 Housley, R., and T. Polk, "Internet X.509 Public Key 4078 Infrastructure Certificate and Certificate Revocation List 4079 (CRL) Profile", RFC 5280, May 2008. 4081 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 4082 5789, March 2010. 4084 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 4086 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 4087 Network Configuration Protocol (NETCONF)", RFC 6020, 4088 October 2010. 4090 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4091 Verification of Domain-Based Application Service Identity 4092 within Internet Public Key Infrastructure Using X.509 4093 (PKIX) Certificates in the Context of Transport Layer 4094 Security (TLS)", RFC 6125, March 2011. 4096 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 4097 and A. Bierman, Ed., "Network Configuration Protocol 4098 (NETCONF)", RFC 6241, June 2011. 4100 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 4101 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 4102 . 4104 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 4105 NETCONF", RFC 6243, June 2011. 4107 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 4108 6415, October 2011. 4110 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 4111 Protocol (NETCONF) Access Control Model", RFC 6536, March 4112 2012. 4114 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 4115 and D. Orchard, "URI Template", RFC 6570, March 2012. 4117 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 4118 July 2013. 4120 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4121 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 4122 2014, . 4124 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4125 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 4126 2014. 4128 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4129 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 4131 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4132 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 4134 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4135 (HTTP/1.1): Authentication", RFC 7235, June 2014. 4137 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 4138 7320, July 2014. 4140 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 4141 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 4142 10.17487/RFC7540, May 2015, 4143 . 4145 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 4146 NETCONF Protocol over Transport Layer Security (TLS) with 4147 Mutual X.509 Authentication", RFC 7589, DOI 10.17487/ 4148 RFC7589, June 2015, 4149 . 4151 [W3C.REC-eventsource-20150203] 4152 Hickson, I., "Server-Sent Events", World Wide Web 4153 Consortium Recommendation REC-eventsource-20150203, 4154 February 2015, 4155 . 4157 [W3C.REC-html5-20141028] 4158 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 4159 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", World 4160 Wide Web Consortium Recommendation REC-html5-20141028, 4161 October 2014, 4162 . 4164 [W3C.REC-xml-20081126] 4165 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 4166 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 4167 Edition)", World Wide Web Consortium Recommendation REC- 4168 xml-20081126, November 2008, 4169 . 4171 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 4172 Version 1.0", World Wide Web Consortium Recommendation 4173 REC-xpath-19991116, November 1999, 4174 . 4176 14.2. Informative References 4178 [I-D.ietf-netconf-yang-patch] 4179 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 4180 Media Type", draft-ietf-netconf-yang-patch-08 (work in 4181 progress), March 2016. 4183 [rest-dissertation] 4184 Fielding, R., "Architectural Styles and the Design of 4185 Network-based Software Architectures", 2000. 4187 Appendix A. Change Log 4189 -- RFC Ed.: remove this section before publication. 4191 The RESTCONF issue tracker can be found here: https://github.com/ 4192 netconf-wg/restconf/issues 4194 A.1. v14 to v15 4196 o added text for HTTP/2 usage 4198 o changed media type definitions per review comments 4200 o added some clarifications and typos 4202 o added error-tag mapping for 406 and 412 errors 4204 A.2. v13 - v14 4205 This release addresses github issues #61, #62, #63, #65, #66, and 4206 #67. 4208 o change term 'server' to 'NETCONF server' 4210 o add term 'RESTCONF server' also called 'server' 4212 o change term 'client' to 'NETCONF client' 4214 o add term 'RESTCONF client' also called 'client' 4216 o remove unused YANG terms 4218 o clarified operation resource and schema resource terms 4220 o clarified abstract and intro: RESTCONF uses NETCONF datastore 4221 concepts 4223 o removed term 'protocol operation'; use 'RPC operation' instead 4225 o clarified edit operation from NETCONF as nc:operation 4227 o clarified retrieval of an operation resource 4229 o remove ETag and Last-Modified requirements for /modules-state and 4230 /modules-state/module objects, since these are not configuration 4231 data nodes 4233 o clarified Last-Modified and ETag requirements for datastore and 4234 data resources 4236 o clarified defaults retrieval for leaf and leaf-list target 4237 resources 4239 o clarified request message-body for operation resources 4241 o clarified query parameters for GET also allowed for HEAD 4243 o clarified error handling for query parameters 4245 o clarified XPath function library for "filter" parameter 4247 o added example for 'edit a data resource' 4249 o added term 'notification replay' from RFC 5277 4251 o clarified unsupported encoding format error handling 4252 o change term 'meta-data' to 'metadata' 4254 o clarified RESTCONF metadata definition 4256 o clarified error info not returned for 1xx, 2xx, and 3xx ranges 4258 o clarified operations description in ietf-restconf module 4260 o clarified Acknowledgements section 4262 o clarified some examples 4264 o update some references 4266 o update RFC 2119 boilerplate 4268 o remove requirements that simply restate HTTP requirements 4270 o remove Pragma: no-cache from examples since RFC 7234 says this 4271 pragma is not defined for responses 4273 o remove suggestion MAY send Pragma: no-cache in response 4275 o remove table of HTTP status codes used in RESTCONF 4277 o changed media type names so they conform to RFC 6838 4279 o clarified too-big error-tag conversion 4281 o update SSE reference 4283 o clarify leaf-list identifier encoding 4285 o removed all media types except yang-data 4287 o changed restconf-media-type extension to be more generic yang-data 4288 extension 4290 A.3. v12 - v13 4292 o fix YANG library module examples (now called module-state) 4294 o fix terminology idnit issue 4296 o removed RFC 2818 reference (changed citation to RFC 7230) 4298 A.4. v11 - v12 4299 o clarify query parameter requirements 4301 o move filter query section to match table order in sec. 4.8 4303 o clarify that depth default is entire subtree for datastore 4304 resource 4306 o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml 4308 o made implementation of timestamps optional since ETags are 4309 mandatory 4311 o removed confusing text about data resource definition revision 4312 date 4314 o clarify that errors should be returned for any resource type 4316 o clarified media subtype (not type) for error response 4318 o clarified client SHOULD (not MAY) specify errors format in Accept 4319 header 4321 o clarified terminology in many sections 4323 A.5. v10 - v11 4325 o change term 'operational data' to 'state data' 4327 o clarify :startup behavior 4329 o clarify X.509 security text 4331 o change '403 Forbidden' to '401 Unauthorized' for GET error 4333 o clarify MUST have one "restconf" link relation 4335 o clarify that NV-storage is not mandatory 4337 o clarify how "Last-Modified" and "ETag" header info can be used by 4338 a client 4340 o clarify meaning of mandatory parameter 4342 o fix module name in action examples 4344 o clarify operation resource request needs to be known to parse the 4345 output 4347 o clarify ordered-by user terminology 4349 o fixed JSON example in D.1.1 4351 A.6. v09 - v10 4353 o address review comments: github issue #36 4355 o removed intro text about no knowledge of NETCONF needed 4357 o clarified candidate and confirmed-commit behavior in sec. 1.3 4359 o clarified that a RESTCONF server MUST support TLS 4361 o clarified choice of 403 or 404 error 4363 o fixed forward references to URI template (w/reference at first 4364 use) 4366 o added reference to HTML5 4368 o made error terminology more consistent 4370 o clarified that only 1 list or leaf-list instance can be returned 4371 in an XML response message-body 4373 o clarified that more than 1 instance must not be created by a POST 4374 method 4376 o clarified that PUT cannot be used to change a leaf-list value or 4377 any list key values 4379 o clarified that PATCH cannot be used to change a leaf-list value or 4380 any list key values 4382 o clarified that DELETE should not be used to delete more than one 4383 instance of a leaf-list or list 4385 o update JSON RFC reference 4387 o specified that leaf-list instances are data resources 4389 o specified how a leaf-list instance identifier is constructed 4391 o fixed get-schema example 4392 o clarified that if no Accept header the server SHOULD return the 4393 type specified in RESTCONF, but MAY return any media-type, 4394 according to HTTP rules 4396 o clarified that server SHOULD maintain timestamp and etag for data 4397 resources 4399 o clarified default for content query parameter 4401 o moved terminology section earlier in doc to avoid forward usage 4403 o clarified intro text wrt/ interactions with NETCONF and access to 4404 specific datastores 4406 o clarified server implementation requirements for YANG defaults 4408 o clarified that Errors is not a resource, just a media type 4410 o clarified that HTTP without TLS MUST NOT be used 4412 o add RESTCONF Extensibility section to make it clear how RESTCONF 4413 will be extended in the future 4415 o add text warning that NACM does not work with HTTP caching 4417 o remove sec. 5.2 Message Headers 4419 o remove 202 Accepted from list of used status-lines -- not allowed 4421 o made implementation of OPTIONS MUST instead of SHOULD 4423 o clarified that successful PUT for altering data returns 204 4425 o fixed "point" parameter example 4427 o added example of alternate value for root resource discovery 4429 o added YANG action examples 4431 o fixed some JSON examples 4433 o changed default value for content query parameter to "all" 4435 o changed empty container JSON encoding from "[null]" to "{}" 4437 o added mandatory /restconf/yang-library-version leaf to advertise 4438 revision-date of the YANG library implemented by the server 4440 o clarified URI encoding rules for leaf-list 4442 o clarified sec. 2.2 wrt/ certificates and TLS 4444 o added update procedure for entity tag and timestamp 4446 A.7. v08 - v09 4448 o fix introduction text regarding implementation requirements for 4449 the ietf-yang-library 4451 o clarified HTTP authentication requirements 4453 o fix host-meta example 4455 o changed list key encoding to clarify that quoted strings are not 4456 allowed. Percent-encoded values are used if quotes would be 4457 required. A missing key is treated as a zero-length string 4459 o Fixed example of percent-encoded string to match YANG model 4461 o Changed streams examples to align with naming already used 4463 A.8. v07 - v08 4465 o add support for YANG 1.1 action statement 4467 o changed mandatory encoding from XML to XML or JSON 4469 o fix syntax in fields parameter definition 4471 o add meta-data encoding examples for XML and JSON 4473 o remove RFC 2396 references and update with 3986 4475 o change encoding of a key so quoted string are not used, since they 4476 are already percent-encoded. A zero-length string is not encoded 4477 (/list=foo,,baz) 4479 o Add example of percent-encoded key value 4481 A.9. v06 - v07 4483 o fixed all issues identified in email from Jernej Tuljak in netconf 4484 email 2015-06-22 4486 o fixed error example bug where error-urlpath was still used. 4487 Changed to error-path. 4489 o added mention of YANG Patch and informative reference 4491 o added support for YANG 1.1, specifically support for anydata and 4492 actions 4494 o removed the special field value "*", since it is no longer needed 4496 A.10. v05 - v06 4498 o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) 4500 A.11. v04 - v05 4502 o changed term 'notification event' to 'event notification' 4504 o removed intro text about framework and meta-model 4506 o removed early mention of API resources 4508 o removed term unified datastore and cleaned up text about NETCONF 4509 datastores 4511 o removed text about not immediate persistence of edits 4513 o removed RESTCONF-specific data-resource-identifier typedef and its 4514 usage 4516 o clarified encoding of key leafs 4518 o changed several examples from JSON to XML encoding 4520 o made 'insert' and 'point' query parameters mandatory to implement 4522 o removed ":insert" capability URI 4524 o renamed stream/encoding to stream/access 4526 o renamed stream/encoding/type to stream/access/encoding 4528 o renamed stream/encoding/events to stream/access/location 4530 o changed XPath from informative to normative reference 4532 o changed rest-dissertation from normative to informative reference 4534 o changed example-jukebox playlist 'id' from a data-resource- 4535 identifier to a leafref pointing at the song name 4537 A.12. v03 - v04 4539 o renamed 'select' to 'fields' (#1) 4541 o moved collection resource and page capability to draft-ietf- 4542 netconf-restconf-collection-00 (#3) 4544 o added mandatory "defaults" protocol capability URI (#4) 4546 o added optional "with-defaults" query parameter URI (#4) 4548 o clarified authentication procedure (#9) 4550 o moved ietf-yang-library module to draft-ietf-netconf-yang- 4551 library-00 (#13) 4553 o clarified that JSON encoding of module name in a URI MUST follow 4554 the netmod-yang-json encoding rules (#14) 4556 o added restconf-media-type extension (#15) 4558 o remove "content" query parameter URI and made this parameter 4559 mandatory (#16) 4561 o clarified datastore usage 4563 o changed lock-denied error example 4565 o added with-defaults query parameter example 4567 o added term "RESTCONF Capability" 4569 o changed NETCONF Capability URI registry usage to new RESTCONF 4570 Capability URI Registry usage 4572 A.13. v02 - v03 4574 o added collection resource 4576 o added "page" query parameter capability 4578 o added "limit" and "offset" query parameters, which are available 4579 if the "page" capability is supported 4581 o added "stream list" term 4583 o fixed bugs in some examples 4584 o added "encoding" list within the "stream" list to allow different 4585 URLs for XML and JSON encoding. 4587 o made XML MUST implement and JSON MAY implement for servers 4589 o re-add JSON notification examples (previously removed) 4591 o updated JSON references 4593 A.14. v01 - v02 4595 o moved query parameter definitions from the YANG module back to the 4596 plain text sections 4598 o made all query parameters optional to implement 4600 o defined query parameter capability URI 4602 o moved 'streams' to new YANG module (ietf-restconf-monitoring) 4604 o added 'capabilities' container to new YANG module (ietf-restconf- 4605 monitoring) 4607 o moved 'modules' container to new YANG module (ietf-yang-library) 4609 o added new leaf 'module-set-id' (ietf-yang-library) 4611 o added new leaf 'conformance' (ietf-yang-library) 4613 o changed 'schema' leaf to type inet:uri that returns the location 4614 of the YANG schema (instead of returning the schema directly) 4616 o changed 'events' leaf to type inet:uri that returns the location 4617 of the event stream resource (instead of returning events 4618 directly) 4620 o changed examples for yang.api resource since the monitoring 4621 information is no longer in this resource 4623 o closed issue #1 'select parameter' since no objections to the 4624 proposed syntax 4626 o closed "encoding of list keys" issue since no objection to new 4627 encoding of list keys in a target resource URI. 4629 o moved open issues list to the issue tracker on github 4631 A.15. v00 - v01 4633 o fixed content=nonconfig example (non-config was incorrect) 4635 o closed open issue 'message-id'. There is no need for a message-id 4636 field, and RFC 2392 does not apply. 4638 o closed open issue 'server support verification'. The headers used 4639 by RESTCONF are widely supported. 4641 o removed encoding rules from section on RESTCONF Meta-Data. This 4642 is now defined in "I-D.lhotka-netmod-yang-json". 4644 o added media type application/yang.errors to map to errors YANG 4645 grouping. Updated error examples to use new media type. 4647 o closed open issue 'additional datastores'. Support may be added 4648 in the future to identify new datastores. 4650 o closed open issue 'PATCH media type discovery'. The section on 4651 PATCH has an added sentence on the Accept-Patch header. 4653 o closed open issue 'YANG to resource mapping'. Current mapping of 4654 all data nodes to resources will be used in order to allow 4655 mandatory DELETE support. The PATCH operation is optional, as 4656 well as the YANG Patch media type. 4658 o closed open issue '_self links for HATEOAS support'. It was 4659 decided that they are redundant because they can be derived from 4660 the YANG module for the specific data. 4662 o added explanatory text for the 'select' parameter. 4664 o added RESTCONF Path Resolution section for discovering the root of 4665 the RESTCONF API using the /.well-known/host-meta. 4667 o added an "error" media type to for structured error messages 4669 o added Secure Transport section requiring TLS 4671 o added Security Considerations section 4673 o removed all references to "REST-like" 4675 A.16. bierman:restconf-04 to ietf:restconf-00 4677 o updated open issues section 4679 Appendix B. Open Issues 4681 -- RFC Ed.: remove this section before publication. 4683 The RESTCONF issues are tracked on github.com: 4685 https://github.com/netconf-wg/restconf/issues 4687 Appendix C. Example YANG Module 4689 The example YANG module used in this document represents a simple 4690 media jukebox interface. 4692 YANG Tree Diagram for "example-jukebox" Module 4694 +--rw jukebox! 4695 +--rw library 4696 | +--rw artist* [name] 4697 | | +--rw name string 4698 | | +--rw album* [name] 4699 | | +--rw name string 4700 | | +--rw genre? identityref 4701 | | +--rw year? uint16 4702 | | +--rw admin 4703 | | | +--rw label? string 4704 | | | +--rw catalogue-number? string 4705 | | +--rw song* [name] 4706 | | +--rw name string 4707 | | +--rw location string 4708 | | +--rw format? string 4709 | | +--rw length? uint32 4710 | +--ro artist-count? uint32 4711 | +--ro album-count? uint32 4712 | +--ro song-count? uint32 4713 +--rw playlist* [name] 4714 | +--rw name string 4715 | +--rw description? string 4716 | +--rw song* [index] 4717 | +--rw index uint32 4718 | +--rw id leafref 4719 +--rw player 4720 +--rw gap? decimal64 4722 rpcs: 4724 +---x play 4725 +--ro input 4726 +--ro playlist string 4727 +--ro song-number uint32 4729 C.1. example-jukebox YANG Module 4731 module example-jukebox { 4733 namespace "http://example.com/ns/example-jukebox"; 4734 prefix "jbox"; 4736 organization "Example, Inc."; 4737 contact "support at example.com"; 4738 description "Example Jukebox Data Model Module"; 4739 revision "2015-04-04" { 4740 description "Initial version."; 4741 reference "example.com document 1-4673"; 4742 } 4744 identity genre { 4745 description "Base for all genre types"; 4746 } 4748 // abbreviated list of genre classifications 4749 identity alternative { 4750 base genre; 4751 description "Alternative music"; 4752 } 4753 identity blues { 4754 base genre; 4755 description "Blues music"; 4756 } 4757 identity country { 4758 base genre; 4759 description "Country music"; 4760 } 4761 identity jazz { 4762 base genre; 4763 description "Jazz music"; 4764 } 4765 identity pop { 4766 base genre; 4767 description "Pop music"; 4768 } 4769 identity rock { 4770 base genre; 4771 description "Rock music"; 4773 } 4775 container jukebox { 4776 presence 4777 "An empty container indicates that the jukebox 4778 service is available"; 4780 description 4781 "Represents a jukebox resource, with a library, playlists, 4782 and a play operation."; 4784 container library { 4786 description "Represents the jukebox library resource."; 4788 list artist { 4789 key name; 4791 description 4792 "Represents one artist resource within the 4793 jukebox library resource."; 4795 leaf name { 4796 type string { 4797 length "1 .. max"; 4798 } 4799 description "The name of the artist."; 4800 } 4802 list album { 4803 key name; 4805 description 4806 "Represents one album resource within one 4807 artist resource, within the jukebox library."; 4809 leaf name { 4810 type string { 4811 length "1 .. max"; 4812 } 4813 description "The name of the album."; 4814 } 4816 leaf genre { 4817 type identityref { base genre; } 4818 description 4819 "The genre identifying the type of music on 4820 the album."; 4822 } 4824 leaf year { 4825 type uint16 { 4826 range "1900 .. max"; 4827 } 4828 description "The year the album was released"; 4829 } 4831 container admin { 4832 description 4833 "Administrative information for the album."; 4835 leaf label { 4836 type string; 4837 description "The label that released the album."; 4838 } 4839 leaf catalogue-number { 4840 type string; 4841 description "The album's catalogue number."; 4842 } 4843 } 4845 list song { 4846 key name; 4848 description 4849 "Represents one song resource within one 4850 album resource, within the jukebox library."; 4852 leaf name { 4853 type string { 4854 length "1 .. max"; 4855 } 4856 description "The name of the song"; 4857 } 4858 leaf location { 4859 type string; 4860 mandatory true; 4861 description 4862 "The file location string of the 4863 media file for the song"; 4864 } 4865 leaf format { 4866 type string; 4867 description 4868 "An identifier string for the media type 4869 for the file associated with the 4870 'location' leaf for this entry."; 4871 } 4872 leaf length { 4873 type uint32; 4874 units "seconds"; 4875 description 4876 "The duration of this song in seconds."; 4877 } 4878 } // end list 'song' 4879 } // end list 'album' 4880 } // end list 'artist' 4882 leaf artist-count { 4883 type uint32; 4884 units "songs"; 4885 config false; 4886 description "Number of artists in the library"; 4887 } 4888 leaf album-count { 4889 type uint32; 4890 units "albums"; 4891 config false; 4892 description "Number of albums in the library"; 4893 } 4894 leaf song-count { 4895 type uint32; 4896 units "songs"; 4897 config false; 4898 description "Number of songs in the library"; 4899 } 4900 } // end library 4902 list playlist { 4903 key name; 4905 description 4906 "Example configuration data resource"; 4908 leaf name { 4909 type string; 4910 description 4911 "The name of the playlist."; 4912 } 4913 leaf description { 4914 type string; 4915 description 4916 "A comment describing the playlist."; 4917 } 4918 list song { 4919 key index; 4920 ordered-by user; 4922 description 4923 "Example nested configuration data resource"; 4925 leaf index { // not really needed 4926 type uint32; 4927 description 4928 "An arbitrary integer index for this playlist song."; 4929 } 4930 leaf id { 4931 type leafref { 4932 path "/jbox:jukebox/jbox:library/jbox:artist/" + 4933 "jbox:album/jbox:song/jbox:name"; 4934 } 4935 mandatory true; 4936 description 4937 "Song identifier. Must identify an instance of 4938 /jukebox/library/artist/album/song/name."; 4939 } 4940 } 4941 } 4943 container player { 4944 description 4945 "Represents the jukebox player resource."; 4947 leaf gap { 4948 type decimal64 { 4949 fraction-digits 1; 4950 range "0.0 .. 2.0"; 4951 } 4952 units "tenths of seconds"; 4953 description "Time gap between each song"; 4954 } 4955 } 4956 } 4958 rpc play { 4959 description "Control function for the jukebox player"; 4960 input { 4961 leaf playlist { 4962 type string; 4963 mandatory true; 4964 description "playlist name"; 4965 } 4966 leaf song-number { 4967 type uint32; 4968 mandatory true; 4969 description "Song number in playlist to play"; 4970 } 4971 } 4972 } 4973 } 4975 Appendix D. RESTCONF Message Examples 4977 The examples within this document use the normative YANG module 4978 defined in Section 8 and the non-normative example YANG module 4979 defined in Appendix C.1. 4981 This section shows some typical RESTCONF message exchanges. 4983 D.1. Resource Retrieval Examples 4985 D.1.1. Retrieve the Top-level API Resource 4987 The client starts by retrieving the RESTCONF entry point: 4989 GET /.well-known/host-meta HTTP/1.1 4990 Host: example.com 4991 Accept: application/xrd+xml 4993 The server might respond: 4995 HTTP/1.1 200 OK 4996 Content-Type: application/xrd+xml 4997 Content-Length: nnn 4999 5000 5001 5003 The client may then retrieve the top-level API resource, using the 5004 entry point "/restconf". 5006 GET /restconf HTTP/1.1 5007 Host: example.com 5008 Accept: application/yang-data+json 5010 The server might respond as follows: 5012 [RFC Editor Note: Adjust the date (2016-04-09) for ietf-yang-library 5013 below to the date in the published ietf-yang-library YANG module, and 5014 remove this note.] 5016 HTTP/1.1 200 OK 5017 Date: Mon, 23 Apr 2012 17:01:00 GMT 5018 Server: example-server 5019 Content-Type: application/yang-data+json 5021 { 5022 "ietf-restconf:restconf": { 5023 "data" : {}, 5024 "operations" : {}, 5025 "yang-library-version" : "2016-04-09" 5026 } 5027 } 5029 To request that the response content to be encoded in XML, the 5030 "Accept" header can be used, as in this example request: 5032 GET /restconf HTTP/1.1 5033 Host: example.com 5034 Accept: application/yang-data 5036 The server will return the same response either way, which might be 5037 as follows : 5039 [RFC Editor Note: Adjust the date for ietf-yang-library below to the 5040 date in the published ietf-yang-library YANG module, and remove this 5041 note.] 5043 HTTP/1.1 200 OK 5044 Date: Mon, 23 Apr 2012 17:01:00 GMT 5045 Server: example-server 5046 Cache-Control: no-cache 5047 Content-Type: application/yang-data 5049 5050 5051 5052 2016-04-09 5053 5055 D.1.2. Retrieve The Server Module Information 5057 It is possible the YANG library module will change over time. The 5058 client can retrieve the revision date of the ietf-yang-library 5059 supported by the server from the API resource, as described in the 5060 previous section. 5062 In this example the client is retrieving the modules information from 5063 the server in JSON format: 5065 GET /restconf/data/ietf-yang-library:modules-state HTTP/1.1 5066 Host: example.com 5067 Accept: application/yang-data+json 5069 The server might respond as follows (some strings wrapped for display 5070 purposes): 5072 [RFC Editor Note: Adjust the date for ietf-yang-library below to the 5073 date in the published ietf-yang-library YANG module, and remove this 5074 note.] 5076 HTTP/1.1 200 OK 5077 Date: Mon, 23 Apr 2012 17:01:00 GMT 5078 Server: example-server 5079 Cache-Control: no-cache 5080 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 5081 Content-Type: application/yang-data+json 5083 { 5084 "ietf-yang-library:modules-state": { 5085 "module-set-id": "5479120c17a619545ea6aff7aa19838b036ebbd7", 5086 "module": [ 5087 { 5088 "name" : "foo", 5089 "revision" : "2012-01-02", 5090 "schema" : "https://example.com/modules/foo/2012-01-02", 5091 "namespace" : "http://example.com/ns/foo", 5092 "feature" : [ "feature1", "feature2" ], 5093 "deviation" : [ 5094 { 5095 "name" : "foo-dev", 5096 "revision" "2012-02-16" 5097 } 5098 ], 5099 "conformance-type" : "implement" 5100 }, 5101 { 5102 "name" : "ietf-yang-library", 5103 "revision" : "2016-04-09", 5104 "schema" : "https://example.com/modules/ietf-yang- 5105 library/2016-04-09", 5106 "namespace" : 5107 "urn:ietf:params:xml:ns:yang:ietf-yang-library", 5108 "conformance-type" : "implement" 5109 }, 5110 { 5111 "name" : "foo-types", 5112 "revision" : "2012-01-05", 5113 "schema" : 5114 "https://example.com/modules/foo-types/2012-01-05", 5115 "namespace" : "http://example.com/ns/foo-types", 5116 "conformance-type" : "import" 5117 }, 5118 { 5119 "name" : "bar", 5120 "revision" : "2012-11-05", 5121 "schema" : "https://example.com/modules/bar/2012-11-05", 5122 "namespace" : "http://example.com/ns/bar", 5123 "feature" : [ "bar-ext" ], 5124 "conformance-type" : "implement", 5125 "submodule" : [ 5126 { 5127 "name" : "bar-submod1", 5128 "revision" : "2012-11-05", 5129 "schema" : 5130 "https://example.com/modules/bar-submod1/2012-11-05" 5131 }, 5132 { 5133 "name" : "bar-submod2", 5134 "revision" : "2012-11-05", 5135 "schema" : 5136 "https://example.com/modules/bar-submod2/2012-11-05" 5137 } 5138 ] 5139 } 5140 ] 5141 } 5142 } 5144 D.1.3. Retrieve The Server Capability Information 5146 In this example the client is retrieving the capability information 5147 from the server in XML format, and the server supports all the 5148 RESTCONF query parameters, plus one vendor parameter: 5150 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 5151 capabilities HTTP/1.1 5152 Host: example.com 5153 Accept: application/yang-data 5155 The server might respond as follows. The extra whitespace in 5156 'capability' elements is for display purposes only. 5158 HTTP/1.1 200 OK 5159 Date: Mon, 23 Apr 2012 17:02:00 GMT 5160 Server: example-server 5161 Cache-Control: no-cache 5162 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 5163 Content-Type: application/yang-data 5165 5167 5168 urn:ietf:params:restconf:capability:defaults:1.0? 5169 basic-mode=explicit 5170 5171 5172 urn:ietf:params:restconf:capability:with-defaults:1.0 5173 5174 5175 urn:ietf:params:restconf:capability:depth:1.0 5176 5177 5178 urn:ietf:params:restconf:capability:fields:1.0 5179 5180 5181 urn:ietf:params:restconf:capability:filter:1.0 5182 5183 5184 urn:ietf:params:restconf:capability:start-time:1.0 5185 5186 5187 urn:ietf:params:restconf:capability:stop-time:1.0 5188 5189 5190 http://example.com/capabilities/myparam 5191 5192 5194 D.2. Edit Resource Examples 5196 D.2.1. Create New Data Resources 5197 To create a new "artist" resource within the "library" resource, the 5198 client might send the following request. 5200 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 5201 Host: example.com 5202 Content-Type: application/yang-data+json 5204 { 5205 "example-jukebox:artist" : { 5206 "name" : "Foo Fighters" 5207 } 5208 } 5210 If the resource is created, the server might respond as follows. 5211 Note that the "Location" header line is wrapped for display purposes 5212 only: 5214 HTTP/1.1 201 Created 5215 Date: Mon, 23 Apr 2012 17:02:00 GMT 5216 Server: example-server 5217 Location: https://example.com/restconf/data/ 5218 example-jukebox:jukebox/library/artist=Foo%20Fighters 5219 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 5220 ETag: "b3830f23a4c" 5222 To create a new "album" resource for this artist within the "jukebox" 5223 resource, the client might send the following request. Note that the 5224 request URI header line is wrapped for display purposes only: 5226 POST /restconf/data/example-jukebox:jukebox/ 5227 library/artist=Foo%20Fighters HTTP/1.1 5228 Host: example.com 5229 Content-Type: application/yang-data 5231 5232 Wasting Light 5233 2011 5234 5236 If the resource is created, the server might respond as follows. 5237 Note that the "Location" header line is wrapped for display purposes 5238 only: 5240 HTTP/1.1 201 Created 5241 Date: Mon, 23 Apr 2012 17:03:00 GMT 5242 Server: example-server 5243 Location: https://example.com/restconf/data/ 5244 example-jukebox:jukebox/library/artist=Foo%20Fighters/ 5245 album=Wasting%20Light 5246 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 5247 ETag: "b8389233a4c" 5249 D.2.2. Detect Resource Entity Tag Change 5251 In this example, the server just supports the datastore last-changed 5252 timestamp. The client has previously retrieved the "Last-Modified" 5253 header and has some value cached to provide in the following request 5254 to patch an "album" list entry with key value "Wasting Light". Only 5255 the "genre" field is being updated. 5257 PATCH /restconf/data/example-jukebox:jukebox/ 5258 library/artist=Foo%20Fighters/album=Wasting%20Light/genre 5259 HTTP/1.1 5260 Host: example.com 5261 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 5262 Content-Type: application/yang-data+json 5264 { "example-jukebox:genre" : "example-jukebox:alternative" } 5266 In this example the datastore resource has changed since the time 5267 specified in the "If-Unmodified-Since" header. The server might 5268 respond: 5270 HTTP/1.1 412 Precondition Failed 5271 Date: Mon, 23 Apr 2012 19:01:00 GMT 5272 Server: example-server 5273 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 5274 ETag: "b34aed893a4c" 5276 D.2.3. Edit a Datastore Resource 5278 In this example, the client modifies two different data nodes by 5279 sending a PATCH to the datastore resource: 5281 PATCH /restconf/data HTTP/1.1 5282 Host: example.com 5283 Content-Type: application/yang-data 5285 5286 5287 5288 5289 Foo Fighters 5290 5291 Wasting Light 5292 2011 5294 5295 5296 5297 Nick Cave and the Bad Seeds 5298 5299 Tender Prey 5300 1988 5301 5302 5303 5304 5305 5307 D.2.4. Edit a Data Resource 5309 In this example, the client modifies one data nodes by sending a 5310 PATCH to the data resource (URI wrapped for display purposes only): 5312 PATCH /restconf/data/example-jukebox:jukebox/library/ 5313 artist=Nick%20Cave%20and%20the%Bad%20Seeds HTTP/1.1 5314 Host: example.com 5315 Content-Type: application/yang-data 5317 5318 Nick Cave and the Bad Seeds 5319 5320 The Good Son 5321 1990 5322 5323 5325 D.3. Query Parameter Examples 5327 D.3.1. "content" Parameter 5329 The "content" parameter is used to select the type of data child 5330 resources (configuration and/or not configuration) that are returned 5331 by the server for a GET method request. 5333 In this example, a simple YANG list that has configuration and non- 5334 configuration child resources. 5336 container events 5337 list event { 5338 key name; 5339 leaf name { type string; } 5340 leaf description { type string; } 5341 leaf event-count { 5342 type uint32; 5343 config false; 5344 } 5345 } 5346 } 5348 Example 1: content=all 5350 To retrieve all the child resources, the "content" parameter is set 5351 to "all", or omitted, since this is the default value. The client 5352 might send: 5354 GET /restconf/data/example-events:events?content=all 5355 HTTP/1.1 5356 Host: example.com 5357 Accept: application/yang-data+json 5359 The server might respond: 5361 HTTP/1.1 200 OK 5362 Date: Mon, 23 Apr 2012 17:11:30 GMT 5363 Server: example-server 5364 Cache-Control: no-cache 5365 Content-Type: application/yang-data+json 5367 { 5368 "example-events:events" : { 5369 "event" : [ 5370 { 5371 "name" : "interface-up", 5372 "description" : "Interface up notification count", 5373 "event-count" : 42 5374 }, 5375 { 5376 "name" : "interface-down", 5377 "description" : "Interface down notification count", 5378 "event-count" : 4 5379 } 5380 ] 5381 } 5382 } 5384 Example 2: content=config 5386 To retrieve only the configuration child resources, the "content" 5387 parameter is set to "config". Note that the "ETag" and 5388 "Last-Modified" headers are only returned if the content parameter 5389 value is "config". 5391 GET /restconf/data/example-events:events?content=config 5392 HTTP/1.1 5393 Host: example.com 5394 Accept: application/yang-data+json 5396 The server might respond: 5398 HTTP/1.1 200 OK 5399 Date: Mon, 23 Apr 2012 17:11:30 GMT 5400 Server: example-server 5401 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5402 ETag: "eeeada438af" 5403 Cache-Control: no-cache 5404 Content-Type: application/yang-data+json 5406 { 5407 "example-events:events" : { 5408 "event" : [ 5409 { 5410 "name" : "interface-up", 5411 "description" : "Interface up notification count" 5412 }, 5413 { 5414 "name" : "interface-down", 5415 "description" : "Interface down notification count" 5416 } 5417 ] 5418 } 5419 } 5421 Example 3: content=nonconfig 5423 To retrieve only the non-configuration child resources, the "content" 5424 parameter is set to "nonconfig". Note that configuration ancestors 5425 (if any) and list key leafs (if any) are also returned. The client 5426 might send: 5428 GET /restconf/data/example-events:events?content=nonconfig 5429 HTTP/1.1 5430 Host: example.com 5431 Accept: application/yang-data+json 5433 The server might respond: 5435 HTTP/1.1 200 OK 5436 Date: Mon, 23 Apr 2012 17:11:30 GMT 5437 Server: example-server 5438 Cache-Control: no-cache 5439 Content-Type: application/yang-data+json 5441 { 5442 "example-events:events" : { 5443 "event" : [ 5444 { 5445 "name" : "interface-up", 5446 "event-count" : 42 5447 }, 5448 { 5449 "name" : "interface-down", 5450 "event-count" : 4 5451 } 5452 ] 5453 } 5454 } 5456 D.3.2. "depth" Parameter 5458 The "depth" parameter is used to limit the number of levels of child 5459 resources that are returned by the server for a GET method request. 5461 The depth parameter starts counting levels at the level of the target 5462 resource that is specified, so that a depth level of "1" includes 5463 just the target resource level itself. A depth level of "2" includes 5464 the target resource level and its child nodes. 5466 This example shows how different values of the "depth" parameter 5467 would affect the reply content for retrieval of the top-level 5468 "jukebox" data resource. 5470 Example 1: depth=unbounded 5472 To retrieve all the child resources, the "depth" parameter is not 5473 present or set to the default value "unbounded". Note that some 5474 strings are wrapped for display purposes only. 5476 GET /restconf/data/example-jukebox:jukebox?depth=unbounded 5477 HTTP/1.1 5478 Host: example.com 5479 Accept: application/yang-data+json 5481 The server might respond: 5483 HTTP/1.1 200 OK 5484 Date: Mon, 23 Apr 2012 17:11:30 GMT 5485 Server: example-server 5486 Cache-Control: no-cache 5487 Content-Type: application/yang-data+json 5489 { 5490 "example-jukebox:jukebox" : { 5491 "library" : { 5492 "artist" : [ 5493 { 5494 "name" : "Foo Fighters", 5495 "album" : [ 5496 { 5497 "name" : "Wasting Light", 5498 "genre" : "example-jukebox:alternative", 5499 "year" : 2011, 5500 "song" : [ 5501 { 5502 "name" : "Wasting Light", 5503 "location" : 5504 "/media/foo/a7/wasting-light.mp3", 5505 "format" : "MP3", 5506 "length" " 286 5507 }, 5508 { 5509 "name" : "Rope", 5510 "location" : "/media/foo/a7/rope.mp3", 5511 "format" : "MP3", 5512 "length" " 259 5513 } 5514 ] 5515 } 5516 ] 5517 } 5518 ] 5519 }, 5520 "playlist" : [ 5521 { 5522 "name" : "Foo-One", 5523 "description" : "example playlist 1", 5524 "song" : [ 5525 { 5526 "index" : 1, 5527 "id" : "https://example.com/restconf/data/ 5528 example-jukebox:jukebox/library/artist= 5529 Foo%20Fighters/album=Wasting%20Light/ 5530 song=Rope" 5531 }, 5532 { 5533 "index" : 2, 5534 "id" : "https://example.com/restconf/data/ 5535 example-jukebox:jukebox/library/artist= 5536 Foo%20Fighters/album=Wasting%20Light/song= 5537 Bridge%20Burning" 5538 } 5539 ] 5540 } 5541 ], 5542 "player" : { 5543 "gap" : 0.5 5544 } 5545 } 5546 } 5548 Example 2: depth=1 5550 To determine if 1 or more resource instances exist for a given target 5551 resource, the value "1" is used. 5553 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 5554 Host: example.com 5555 Accept: application/yang-data+json 5557 The server might respond: 5559 HTTP/1.1 200 OK 5560 Date: Mon, 23 Apr 2012 17:11:30 GMT 5561 Server: example-server 5562 Cache-Control: no-cache 5563 Content-Type: application/yang-data+json 5565 { 5566 "example-jukebox:jukebox" : {} 5567 } 5569 Example 3: depth=3 5571 To limit the depth level to the target resource plus 2 child resource 5572 layers the value "3" is used. 5574 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 5575 Host: example.com 5576 Accept: application/yang-data+json 5578 The server might respond: 5580 HTTP/1.1 200 OK 5581 Date: Mon, 23 Apr 2012 17:11:30 GMT 5582 Server: example-server 5583 Cache-Control: no-cache 5584 Content-Type: application/yang-data+json 5586 { 5587 "example-jukebox:jukebox" : { 5588 "library" : { 5589 "artist" : {} 5590 }, 5591 "playlist" : [ 5592 { 5593 "name" : "Foo-One", 5594 "description" : "example playlist 1", 5595 "song" : {} 5596 } 5597 ], 5598 "player" : { 5599 "gap" : 0.5 5600 } 5601 } 5602 } 5604 D.3.3. "fields" Parameter 5606 In this example the client is retrieving the datastore resource in 5607 JSON format, but retrieving only the "modules-state/module" list, and 5608 only the "name" and "revision" nodes from each list entry. Note that 5609 top node returned by the server matches the target resource node 5610 (which is "data" in this example). The "module-set-id" leaf is not 5611 returned because it is not selected in the fields expression. 5613 GET /restconf/data?fields=ietf-yang-library:modules-state/ 5614 module(name;revision) HTTP/1.1 5615 Host: example.com 5616 Accept: application/yang-data+json 5618 The server might respond as follows. 5620 [RFC Editor Note: Adjust the date for ietf-yang-library below to the 5621 date in the published ietf-yang-library YANG module, and remove this 5622 note.] 5624 [RFC Editor Note: Adjust the date for ietf-restconf-monitoring below 5625 to the date in the published ietf-restconf-monitoring YANG module, 5626 and remove this note.] 5628 HTTP/1.1 200 OK 5629 Date: Mon, 23 Apr 2012 17:01:00 GMT 5630 Server: example-server 5631 Content-Type: application/yang-data+json 5633 { 5634 "ietf-restconf:data" : { 5635 "ietf-yang-library:modules-state": { 5636 "module": [ 5637 { 5638 "name" : "example-jukebox", 5639 "revision" : "2015-06-04" 5640 }, 5641 { 5642 "name" : "ietf-inet-types", 5643 "revision" : "2013-07-15" 5644 }, 5645 { 5646 "name" : "ietf-restconf-monitoring", 5647 "revision" : "2016-03-16" 5648 }, 5649 { 5650 "name" : "ietf-yang-library", 5651 "revision" : "2016-04-09" 5652 }, 5653 { 5654 "name" : "ietf-yang-types", 5655 "revision" : "2013-07-15" 5656 } 5657 ] 5658 } 5659 } 5660 } 5662 D.3.4. "insert" Parameter 5664 In this example, a new first song entry in the "Foo-One" playlist is 5665 being created. 5667 Request from client: 5669 POST /restconf/data/example-jukebox:jukebox/ 5670 playlist=Foo-One?insert=first HTTP/1.1 5671 Host: example.com 5672 Content-Type: application/yang-data+json 5674 { 5675 "example-jukebox:song" : { 5676 "index" : 1, 5677 "id" : "/example-jukebox:jukebox/library/ 5678 artist=Foo%20Fighters/album=Wasting%20Light/song=Rope" 5680 } 5681 } 5683 Response from server. Note that the "Location" header line is 5684 wrapped for display purposes only: 5686 HTTP/1.1 201 Created 5687 Date: Mon, 23 Apr 2012 13:01:20 GMT 5688 Server: example-server 5689 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5690 Location: https://example.com/restconf/data/ 5691 example-jukebox:jukebox/playlist=Foo-One/song=1 5692 ETag: "eeeada438af" 5694 D.3.5. "point" Parameter 5696 In this example, the client is inserting a new "song" resource within 5697 an "album" resource after another song. The request URI is split for 5698 display purposes only. 5700 Request from client: 5702 POST /restconf/data/example-jukebox:jukebox/ 5703 library/artist=Foo%20Fighters/album=Wasting%20Light? 5704 insert=after&point=%2Fexample-jukebox%3Ajukebox%2F 5705 library%2Fartist%3DFoo%20Fighters%2Falbum%3D 5706 Wasting%20Light%2Fsong%3DBridge%20Burning HTTP/1.1 5707 Host: example.com 5708 Content-Type: application/yang-data+json 5710 { 5711 "example-jukebox:song" : { 5712 "name" : "Rope", 5713 "location" : "/media/foo/a7/rope.mp3", 5714 "format" : "MP3", 5715 "length" : 259 5716 } 5717 } 5719 Response from server: 5721 HTTP/1.1 204 No Content 5722 Date: Mon, 23 Apr 2012 13:01:20 GMT 5723 Server: example-server 5724 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5725 ETag: "abcada438af" 5727 D.3.6. "filter" Parameter 5729 The following URIs show some examples of notification filter 5730 specifications (lines wrapped for display purposes only): 5732 // filter = /event/event-class='fault' 5733 GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' 5735 // filter = /event/severity<=4 5736 GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 5738 // filter = /linkUp|/linkDown 5739 GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown 5741 // filter = /*/reporting-entity/card!='Ethernet0' 5742 GET /streams/NETCONF? 5743 filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' 5745 // filter = /*/email-addr[contains(.,'company.com')] 5746 GET /streams/critical-syslog? 5747 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 5749 // Note: the module name is used as prefix. 5750 // filter = (/example-mod:event1/name='joe' and 5751 // /example-mod:event1/status='online') 5752 GET /streams/NETCONF? 5753 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and 5754 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 5756 // To get notifications from just two modules (e.g., m1 + m2) 5757 // filter=(/m1:* or /m2:*) 5758 GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*) 5760 D.3.7. "start-time" Parameter 5762 // start-time = 2014-10-25T10:02:00Z 5763 GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z 5765 D.3.8. "stop-time" Parameter 5767 // stop-time = 2014-10-25T12:31:00Z 5768 GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z 5770 D.3.9. "with-defaults" Parameter 5772 The following YANG module is assumed for this example. 5774 module example-interface { 5775 prefix "exif"; 5776 namespace "urn:example.com:params:xml:ns:yang:example-interface"; 5778 container interfaces { 5779 list interface { 5780 key name; 5781 leaf name { type string; } 5782 leaf mtu { type uint32; } 5783 leaf status { 5784 config false; 5785 type enumeration { 5786 enum up; 5787 enum down; 5788 enum testing; 5789 } 5790 } 5791 } 5792 } 5793 } 5795 Assume the same data model as defined in Appendix A.1 of [RFC6243]. 5796 Assume the same data set as defined in Appendix A.2 of [RFC6243]. If 5797 the server defaults-uri basic-mode is "trim", the the following 5798 request for interface "eth1" might be as follows: 5800 Without query parameter: 5802 GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1 5803 Host: example.com 5804 Accept: application/yang-data+json 5806 The server might respond as follows. 5808 HTTP/1.1 200 OK 5809 Date: Mon, 23 Apr 2012 17:01:00 GMT 5810 Server: example-server 5811 Content-Type: application/yang-data+json 5813 { 5814 "example:interface": [ 5815 { 5816 "name" : "eth1", 5817 "status" : "up" 5819 } 5820 ] 5821 } 5823 Note that the "mtu" leaf is missing because it is set to the default 5824 "1500", and the server defaults handling basic-mode is "trim". 5826 With query parameter: 5828 GET /restconf/data/example:interfaces/interface=eth1 5829 ?with-defaults=report-all HTTP/1.1 5830 Host: example.com 5831 Accept: application/yang-data+json 5833 The server might respond as follows. 5835 HTTP/1.1 200 OK 5836 Date: Mon, 23 Apr 2012 17:01:00 GMT 5837 Server: example-server 5838 Content-Type: application/yang-data+json 5840 { 5841 "example:interface": [ 5842 { 5843 "name" : "eth1", 5844 "mtu" : 1500, 5845 "status" : "up" 5846 } 5847 ] 5848 } 5850 Note that the server returns the "mtu" leaf because the "report-all" 5851 mode was requested with the "with-defaults" query parameter. 5853 Authors' Addresses 5855 Andy Bierman 5856 YumaWorks 5858 Email: andy@yumaworks.com 5860 Martin Bjorklund 5861 Tail-f Systems 5863 Email: mbj@tail-f.com 5864 Kent Watsen 5865 Juniper Networks 5867 Email: kwatsen@juniper.net