idnits 2.17.1 draft-ietf-netconf-restconf-14.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 2467 has weird spacing: '... method entry...' == Line 3386 has weird spacing: '...ncoding strin...' == Line 3387 has weird spacing: '...ocation inet:...' == Line 4667 has weird spacing: '...ocation str...' == Line 4677 has weird spacing: '...w index uin...' == (1 more instance...) -- The document date (June 28, 2016) is 2857 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 3899, 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPath' == Outdated reference: A later version (-14) exists of draft-ietf-netconf-yang-patch-08 Summary: 10 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: December 30, 2016 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 June 28, 2016 10 RESTCONF Protocol 11 draft-ietf-netconf-restconf-14 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 December 30, 2016. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 55 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . . 14 71 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . . . . 18 77 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 19 78 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 19 79 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 20 80 3.4.1. Edit Collision Detection . . . . . . . . . . . . . . 20 81 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 21 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 . . . . . . . . . . . . . . . . . . . 26 87 3.6.1. Encoding Operation Resource Input Parameters . . . . 28 88 3.6.2. Encoding Operation Resource Output Parameters . . . . 31 89 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 33 90 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 34 91 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 35 92 3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 36 93 4. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 36 94 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 37 95 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 37 96 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 97 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 39 98 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 39 99 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 40 100 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 101 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 43 102 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 43 103 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 44 104 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 45 105 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 46 106 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 47 107 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 47 108 4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 48 109 4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 49 110 4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 50 111 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 50 112 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 51 113 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 51 114 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 52 115 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 52 116 5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 54 117 5.3. RESTCONF Metadata . . . . . . . . . . . . . . . . . . . . 55 118 5.3.1. XML MetaData Encoding Example . . . . . . . . . . . . 55 119 5.3.2. JSON MetaData Encoding Example . . . . . . . . . . . 56 120 5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 56 121 5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 56 122 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 57 123 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 57 124 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 57 125 6.3. Subscribing to Receive Notifications . . . . . . . . . . 59 126 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 60 127 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 60 128 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 62 129 7.1. Error Response Message . . . . . . . . . . . . . . . . . 63 130 8. RESTCONF module . . . . . . . . . . . . . . . . . . . . . . . 65 131 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 72 132 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 72 133 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 73 134 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 73 135 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 74 136 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 74 138 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 78 139 10.1. modules-state . . . . . . . . . . . . . . . . . . . . . 78 140 10.1.1. modules-state/module . . . . . . . . . . . . . . . . 78 141 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78 142 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 78 143 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 79 144 11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 79 145 11.3.1. Media Type application/yang-data+xml . . . . . . . . 79 146 11.3.2. Media Type application/yang-data+json . . . . . . . 81 147 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 83 148 12. Security Considerations . . . . . . . . . . . . . . . . . . . 84 149 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 85 150 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 85 151 14.1. Normative References . . . . . . . . . . . . . . . . . . 85 152 14.2. Informative References . . . . . . . . . . . . . . . . . 88 153 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 88 154 A.1. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 88 155 A.2. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 90 156 A.3. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 90 157 A.4. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 91 158 A.5. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 91 159 A.6. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 93 160 A.7. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 94 161 A.8. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 94 162 A.9. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 94 163 A.10. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 94 164 A.11. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 95 165 A.12. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 96 166 A.13. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 96 167 A.14. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 97 168 A.15. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 98 169 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 98 170 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 98 171 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 99 172 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 104 173 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 104 174 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 104 175 D.1.2. Retrieve The Server Module Information . . . . . . . 106 176 D.1.3. Retrieve The Server Capability Information . . . . . 108 177 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 109 178 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 109 179 D.2.2. Detect Resource Entity Tag Change . . . . . . . . . . 110 180 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 111 181 D.2.4. Edit a Data Resource . . . . . . . . . . . . . . . . 111 182 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 112 183 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 112 184 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 114 185 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 117 186 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 119 187 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 119 188 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 120 189 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 121 190 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 121 191 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 121 192 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 123 194 1. Introduction 196 There is a need for standard mechanisms to allow Web applications to 197 access the configuration data, state data, data-model specific RPC 198 operations, and event notifications within a networking device, in a 199 modular and extensible manner. 201 This document defines an HTTP [RFC7230] based protocol called 202 RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or 203 YANG version 1.1 [I-D.ietf-netmod-rfc6020bis], using the datastore 204 concepts defined in NETCONF [RFC6241]. 206 NETCONF defines configuration datastores and a set of Create, 207 Retrieve, Update, Delete (CRUD) operations that can be used to access 208 these datastores. The YANG language defines the syntax and semantics 209 of datastore content, configuration, state data, RPC operations, and 210 event notifications. 212 RESTCONF uses HTTP methods to provide CRUD operations on a conceptual 213 datastore containing YANG-defined data, which is compatible with a 214 server which implements NETCONF datastores. 216 If a RESTCONF server is co-located with a NETCONF server, then there 217 are protocol interactions to be considered, as described in 218 Section 1.4. The RESTCONF server MAY provide access to specific 219 datastores using operation resources, as described in Section 3.6. 221 Configuration data and state data are exposed as resources that can 222 be retrieved with the GET method. Resources representing 223 configuration data can be modified with the DELETE, PATCH, POST, and 224 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 225 or JSON [RFC7159]. 227 Data-model specific RPC operations defined with the YANG "rpc" or 228 "action" statements can be invoked with the POST method. Data-model 229 specific event notifications defined with the YANG "notification" 230 statement can be accessed. 232 1.1. Terminology 233 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 234 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 235 document are to be interpreted as described in [RFC2119]. 237 1.1.1. NETCONF 239 The following terms are defined in [RFC6241]: 241 o candidate configuration datastore 243 o configuration data 245 o datastore 247 o configuration datastore 249 o running configuration datastore 251 o startup configuration datastore 253 o state data 255 o user 257 1.1.2. HTTP 259 The following terms are defined in [RFC3986]: 261 o fragment 263 o path 265 o query 267 The following terms are defined in [RFC7230]: 269 o header 271 o message-body 273 o request-line 275 o request URI 277 o status-line 279 The following terms are defined in [RFC7231]: 281 o method 283 o request 285 o resource 287 The following terms are defined in [RFC7232]: 289 o entity tag 291 1.1.3. YANG 293 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 295 o action 297 o container 299 o data node 301 o key leaf 303 o leaf 305 o leaf-list 307 o list 309 o mandatory node 311 o ordered-by user 313 o presence container 315 o RPC operation 317 o top-level data node 319 1.1.4. NETCONF Notifications 321 The following terms are defined in [RFC5277]: 323 o notification replay 325 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/ 385 yang-data+xml" 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+xml" or 422 "application/yang-data+json". 424 1.1.6. URI Template and Examples 425 Throughout this document, the URI template [RFC6570] syntax 426 "{+restconf}" is used to refer to the RESTCONF API entry point 427 outside of an example. See Section 3.1 for details. 429 For simplicity, all of the examples in this document assume "/ 430 restconf" as the discovered RESTCONF API root path. 432 Many of the examples throughout the document are based on the 433 "example-jukebox" YANG module, defined in Appendix C.1. 435 1.1.7. Tree Diagrams 437 A simplified graphical representation of the data model is used in 438 this document. The meaning of the symbols in these diagrams is as 439 follows: 441 o Brackets "[" and "]" enclose list keys. 443 o Abbreviations before data node names: "rw" means configuration 444 data (read-write) and "ro" state data (read-only). 446 o Symbols after data node names: "?" means an optional node, "!" 447 means a presence container, and "*" denotes a list and leaf-list. 449 o Parentheses enclose choice and case nodes, and case nodes are also 450 marked with a colon (":"). 452 o Ellipsis ("...") stands for contents of subtrees that are not 453 shown. 455 1.2. Subset of NETCONF Functionality 457 RESTCONF does not need to mirror the full functionality of the 458 NETCONF protocol, but it does need to be compatible with NETCONF. 459 RESTCONF achieves this by implementing a subset of the interaction 460 capabilities provided by the NETCONF protocol, for instance, by 461 eliminating datastores and explicit locking. 463 RESTCONF uses HTTP methods to implement the equivalent of NETCONF 464 operations, enabling basic CRUD operations on a hierarchy of 465 conceptual resources. 467 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 468 resources represented by YANG data models. These basic edit 469 operations allow the running configuration to be altered in an all- 470 or-none fashion. 472 RESTCONF is not intended to replace NETCONF, but rather provide an 473 additional interface that follows Representational State Transfer 474 (REST) principles [rest-dissertation], and is compatible with a 475 resource-oriented device abstraction. 477 The following figure shows the system components if a RESTCONF server 478 is co-located with a NETCONF server: 480 +-----------+ +-----------------+ 481 | Web app | <-------> | | 482 +-----------+ HTTP | network device | 483 | | 484 +-----------+ | +-----------+ | 485 | NMS app | <-------> | | datastore | | 486 +-----------+ NETCONF | +-----------+ | 487 +-----------------+ 489 The following figure shows the system components if a RESTCONF server 490 is implemented in a device that does not have a NETCONF server: 492 +-----------+ +-----------------+ 493 | Web app | <-------> | | 494 +-----------+ HTTP | network device | 495 | | 496 +-----------------+ 498 1.3. Data Model Driven API 500 RESTCONF combines the simplicity of the HTTP protocol with the 501 predictability and automation potential of a schema-driven API. 502 Using YANG, a client can predict all management resources, much like 503 using URI Templates [RFC6570], but in a more holistic manner. This 504 strategy obviates the need for responses provided by the server to 505 contain Hypermedia as the Engine of Application State (HATEOAS) 506 links, originally described in Roy Fielding's doctoral dissertation 507 [rest-dissertation], because the client can determine the links it 508 needs from the YANG modules. 510 RESTCONF provides the YANG module capability information supported by 511 the server, in case the client wants to use it. The URIs for data- 512 model specific RPC operations and datastore content are predictable, 513 based on the YANG module definitions. 515 The RESTCONF protocol operates on a conceptual datastore defined with 516 the YANG data modeling language. The server lists each YANG module 517 it supports using the "ietf-yang-library" YANG module, defined in 518 [I-D.ietf-netconf-yang-library]. The server MUST implement the 519 "ietf-yang-library" module, which MUST identify all the YANG modules 520 used by the server. 522 The conceptual datastore contents, data-model-specific operations and 523 event notifications are identified by this set of YANG modules. 525 The classification of data as configuration or non-configuration is 526 derived from the YANG "config" statement. Data ordering behavior is 527 derived from the YANG "ordered-by" statement. 529 The RESTCONF datastore editing model is simple and direct, similar to 530 the behavior of the :writable-running capability in NETCONF. Each 531 RESTCONF edit of a datastore resource is activated upon successful 532 completion of the transaction. 534 1.4. Coexistence with NETCONF 536 RESTCONF can be implemented on a device that supports NETCONF. 538 If the device supports :writable-running, all edits to configuration 539 nodes in {+restconf}/data are performed in the running configuration 540 datastore. The URI template "{+restconf}" is defined in 541 Section 1.1.6. 543 Otherwise, if the device supports :candidate, all edits to 544 configuration nodes in {+restconf}/data are performed in the 545 candidate configuration datastore. The candidate MUST be 546 automatically committed to running immediately after each successful 547 edit. Any edits from other sources that are in the candidate 548 datastore will also be committed. If a confirmed-commit procedure is 549 in progress, then this commit will act as the confirming commit. If 550 the server is expecting a "persist-id" parameter to complete the 551 confirmed commit procedure then the RESTCONF edit operation MUST fail 552 with a "409 Conflict" status-line. 554 If the device supports :startup, the device MUST automatically update 555 the non-volatile "startup datastore", after the running datastore has 556 been updated as a consequence of a RESTCONF edit operation. 558 If a datastore that would be modified by a RESTCONF operation has an 559 active lock from a NETCONF client, the RESTCONF edit operation MUST 560 fail with a "409 Conflict" status-line. 562 1.5. RESTCONF Extensibility 564 There are two extensibility mechanisms built into RESTCONF: 566 o protocol version 568 o optional capabilities 570 This document defines version 1 of the RESTCONF protocol. If a 571 future version of this protocol is defined, then that document will 572 specify how the new version of RESTCONF is identified. It is 573 expected that a different entry point {+restconf2} would be defined. 574 The server will advertise all protocol versions that it supports in 575 its host-meta data. 577 In this example, the server supports both RESTCONF version 1 and a 578 fictitious version 2. 580 Request 581 ------- 582 GET /.well-known/host-meta HTTP/1.1 583 Host: example.com 584 Accept: application/xrd+xml 586 Response 587 -------- 588 HTTP/1.1 200 OK 589 Content-Type: application/xrd+xml 590 Content-Length: nnn 592 593 594 595 597 RESTCONF also supports a server-defined list of optional 598 capabilities, which are listed by a server using the 599 "ietf-restconf-monitoring" module defined in Section 9.3. This 600 document defines several query parameters in Section 4.8. Each 601 optional parameter has a corresponding capability URI defined in 602 Section 9.1.1 that is advertised by the server if supported. 604 The "capabilities" list can identify any sort of server extension. 605 Typically this extension mechanism is used to identify optional query 606 parameters but it is not limited to that purpose. For example, the 607 "defaults" URI defined in Section 9.1.2 specifies a mandatory URI 608 identifying server defaults handling behavior. 610 A new sub-resource type could be identified with a capability if it 611 is optional to implement. Mandatory protocol features and new 612 resource types require a new revision of the RESTCONF protocol. 614 2. Transport Protocol Requirements 616 2.1. Integrity and Confidentiality 618 HTTP [RFC7230] is an application layer protocol that may be layered 619 on any reliable transport-layer protocol. RESTCONF is defined on top 620 of HTTP, but due to the sensitive nature of the information conveyed, 621 RESTCONF requires that the transport-layer protocol provides both 622 data integrity and confidentiality. A RESTCONF server MUST support 623 the TLS protocol [RFC5246]. The RESTCONF protocol MUST NOT be used 624 over HTTP without using the TLS protocol. 626 2.2. HTTPS with X.509v3 Certificates 628 Given the nearly ubiquitous support for HTTP over TLS [RFC7230], 629 RESTCONF implementations MUST support the "https" URI scheme, which 630 has the IANA assigned default port 443. 632 RESTCONF servers MUST present an X.509v3 based certificate when 633 establishing a TLS connection with a RESTCONF client. The use the 634 X.509v3 based certificates is consistent with NETCONF over TLS 635 [RFC7589]. 637 2.3. Certificate Validation 639 The RESTCONF client MUST either use X.509 certificate path validation 640 [RFC5280] to verify the integrity of the RESTCONF server's TLS 641 certificate, or match the presented X.509 certificate with locally 642 configured certificate fingerprints. 644 The presented X.509 certificate MUST also be considered valid if it 645 matches a locally configured certificate fingerprint. If X.509 646 certificate path validation fails and the presented X.509 certificate 647 does not match a locally configured certificate fingerprint, the 648 connection MUST be terminated as defined in [RFC5246]. 650 2.4. Authenticated Server Identity 652 The RESTCONF client MUST check the identity of the server according 653 to Section 6 of [RFC6125], including processing the outcome as 654 described in Section 6.6 of [RFC6125]. 656 2.5. Authenticated Client Identity 657 The RESTCONF server MUST authenticate client access to any protected 658 resource. If the RESTCONF client is not authenticated, the server 659 SHOULD send an HTTP response with "401 Unauthorized" status-line, as 660 defined in Section 3.1 of [RFC7235]. 662 To authenticate a client, a RESTCONF server MUST use TLS based client 663 certificates (Section 7.4.6 of [RFC5246]), or MUST use any HTTP 664 authentication scheme defined in the HTTP Authentication Scheme 665 Registry (Section 5.1 in [RFC7235]). A server MAY also support the 666 combination of both client certificates and an HTTP client 667 authentication scheme, with the determination of how to process this 668 combination left as an implementation decision. 670 The RESTCONF client identity derived from the authentication 671 mechanism used is hereafter known as the "RESTCONF username" and 672 subject to the NETCONF Access Control Module (NACM) [RFC6536]. When 673 a client certificate is presented, the RESTCONF username MUST be 674 derived using the algorithm defined in Section 7 of [RFC7589]. For 675 all other cases, when HTTP authentication is used, the RESTCONF 676 username MUST be provided by the HTTP authentication scheme used. 678 3. Resources 680 The RESTCONF protocol operates on a hierarchy of resources, starting 681 with the top-level API resource itself (Section 3.1). Each resource 682 represents a manageable component within the device. 684 A resource can be considered a collection of data and the set of 685 allowed methods on that data. It can contain nested child resources. 686 The child resource types and methods allowed on them are data-model 687 specific. 689 A resource has a representation associated with a media type 690 identifier, as represented by the "Content-Type" header in the HTTP 691 response message. A resource can contain zero or more nested 692 resources. A resource can be created and deleted independently of 693 its parent resource, as long as the parent resource exists. 695 All RESTCONF resource types are defined in this document except 696 specific datastore contents, RPC operations, and event notifications. 697 The syntax and semantics for these resource types are defined in YANG 698 modules. 700 The RESTCONF resources are accessed via a set of URIs defined in this 701 document. The set of YANG modules supported by the server will 702 determine the data model specific RPC operations, top-level data 703 nodes, and event notification messages supported by the server. 705 The RESTCONF protocol does not include a data resource discovery 706 mechanism. Instead, the definitions within the YANG modules 707 advertised by the server are used to construct a predictable 708 operation or data resource identifier. 710 3.1. Root Resource Discovery 712 In line with the best practices defined by [RFC7320], RESTCONF 713 enables deployments to specify where the RESTCONF API is located. 714 When first connecting to a RESTCONF server, a RESTCONF client MUST 715 determine the root of the RESTCONF API. There MUST be exactly one 716 "restconf" link relation returned by the device. 718 The client discovers this by getting the "/.well-known/host-meta" 719 resource ([RFC6415]) and using the element containing the 720 "restconf" attribute : 722 Example returning /restconf: 724 Request 725 ------- 726 GET /.well-known/host-meta HTTP/1.1 727 Host: example.com 728 Accept: application/xrd+xml 730 Response 731 -------- 732 HTTP/1.1 200 OK 733 Content-Type: application/xrd+xml 734 Content-Length: nnn 736 737 738 740 After discovering the RESTCONF API root, the client MUST prepend it 741 to any subsequent request to a RESTCONF resource. In this example, 742 the client would use the path "/restconf" as the RESTCONF entry 743 point. 745 Example returning /top/restconf: 747 Request 748 ------- 749 GET /.well-known/host-meta HTTP/1.1 750 Host: example.com 751 Accept: application/xrd+xml 752 Response 753 -------- 754 HTTP/1.1 200 OK 755 Content-Type: application/xrd+xml 756 Content-Length: nnn 758 759 760 762 In this example, the client would use the path "/top/restconf" as the 763 RESTCONF entry point. 765 The client can now determine the operation resources supported by the 766 the server. In this example a custom "play" operation is supported: 768 Request 769 ------- 770 GET /top/restconf/operations HTTP/1.1 771 Host: example.com 772 Accept: application/yang-data+json 774 Response 775 -------- 776 HTTP/1.1 200 OK 777 Date: Mon, 23 Apr 2012 17:01:00 GMT 778 Server: example-server 779 Cache-Control: no-cache 780 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 781 Content-Type: application/yang-data+json 783 { "operations" : { "example-jukebox:play" : [null] } } 785 If the XRD contains more than one link relation, then only the 786 relation named "restconf" is relevant to this specification. 788 3.2. RESTCONF Media Types 790 The RESTCONF protocol defines two application specific media types to 791 identify representations of data which conforms to the schema for a 792 particular YANG construct. 794 This document defines media types for XML and JSON serialization of 795 YANG data. Other documents MAY define other media types for 796 different serializations of YANG data. The "application/ 797 yang-data+xml" media-type is defined in Section 11.3.1. The 798 "application/yang-data+json" media-type is defined in Section 11.3.2. 800 3.3. API Resource 802 The API resource contains the entry points for the RESTCONF datastore 803 and operation resources. It is the top-level resource located at 804 {+restconf} and has the media type "application/yang-data+xml" or 805 "application/yang-data+json". 807 YANG Tree Diagram for an API Resource: 809 +--rw restconf 810 +--rw data 811 +--rw operations 812 +--ro yang-library-version 814 The "yang-api" YANG data template is defined with the "yang-data" 815 extension in the "ietf-restconf" module, found in Section 8. It is 816 used to specify the structure and syntax of the conceptual child 817 resources within the API resource. 819 The API resource can be retrieved with the GET method. 821 The {+restconf} entry point resource name used in responses MUST 822 identify the "ietf-restconf" YANG module. For example, a request to 823 GET the entry point "/restconf" in JSON format will return a 824 representation of the API resource named "ietf-restconf:restconf". 826 This resource has the following child resources: 828 +----------------------+--------------------------------+ 829 | Child Resource | Description | 830 +----------------------+--------------------------------+ 831 | data | Contains all data resources | 832 | operations | Data-model specific operations | 833 | yang-library-version | ietf-yang-library module date | 834 +----------------------+--------------------------------+ 836 RESTCONF API Resource 838 3.3.1. {+restconf}/data 840 This mandatory resource represents the combined configuration and 841 state data resources that can be accessed by a client. It cannot be 842 created or deleted by the client. The datastore resource type is 843 defined in Section 3.4. 845 Example: 847 This example request by the client would retrieve only the non- 848 configuration data nodes that exist within the "library" resource, 849 using the "content" query parameter (see Section 4.8.1). 851 GET /restconf/data/example-jukebox:jukebox/library 852 ?content=nonconfig HTTP/1.1 853 Host: example.com 854 Accept: application/yang-data+xml 856 The server might respond: 858 HTTP/1.1 200 OK 859 Date: Mon, 23 Apr 2012 17:01:30 GMT 860 Server: example-server 861 Cache-Control: no-cache 862 Content-Type: application/yang-data+xml 864 865 42 866 59 867 374 868 870 3.3.2. {+restconf}/operations 872 This optional resource is a container that provides access to the 873 data-model specific RPC operations supported by the server. The 874 server MAY omit this resource if no data-model specific operations 875 are advertised. 877 Any data-model specific RPC operations defined in the YANG modules 878 advertised by the server MUST be available as child nodes of this 879 resource. 881 The entry point for each RPC operation is represented as an empty 882 leaf. If an operation resource is retrieved, the empty leaf 883 representation is returned by the server. 885 Operation resources are defined in Section 3.6. 887 3.3.3. {+restconf}/yang-library-version 889 This mandatory leaf identifies the revision date of the 890 "ietf-yang-library" YANG module that is implemented by this server. 892 [RFC Editor Note: Adjust the date for ietf-yang-library below to the 893 date in the published ietf-yang-library YANG module, and remove this 894 note.] 895 Example: 897 GET /restconf/yang-library-version HTTP/1.1 898 Host: example.com 899 Accept: application/yang-data+xml 901 The server might respond (response wrapped for display purposes): 903 HTTP/1.1 200 OK 904 Date: Mon, 23 Apr 2012 17:01:30 GMT 905 Server: example-server 906 Cache-Control: no-cache 907 Content-Type: application/yang-data+xml 909 911 2016-04-09 912 914 3.4. Datastore Resource 916 The "{+restconf}/data" subtree represents the datastore resource 917 type, which is a collection of configuration data and state data 918 nodes. The fragment field in the request URI has no defined purpose 919 if the target resource is a datastore resource. 921 This resource type is an abstraction of the system's underlying 922 datastore implementation. It is used to simplify resource editing 923 for the client. The RESTCONF datastore resource is a conceptual 924 collection of all configuration and state data that is present on the 925 device. 927 Configuration edit transaction management and configuration 928 persistence are handled by the server and not controlled by the 929 client. A datastore resource can be written directly with the POST 930 and PATCH methods. Each RESTCONF edit of a datastore resource is 931 saved to non-volatile storage by the server, if the server supports 932 non-volatile storage of configuration data. 934 If the datastore resource represented by the "{+restconf}/data" 935 subtree is retrieved, then the datastore and its contents are 936 returned by the server. The datastore is represented by a node named 937 "data" in the "ietf-restconf" module namespace. 939 3.4.1. Edit Collision Detection 941 Two "edit collision detection" mechanisms are provided in RESTCONF, 942 for datastore and data resources. 944 3.4.1.1. Timestamp 946 The last change time is maintained and the "Last-Modified" 947 ([RFC7232], Section 2.2) header is returned in the response for a 948 retrieval request. The "If-Unmodified-Since" header can be used in 949 edit operation requests to cause the server to reject the request if 950 the resource has been modified since the specified timestamp. 952 The server SHOULD maintain a last-modified timestamp for the 953 datastore resource. This timestamp is only affected by configuration 954 child data resources, and MUST NOT be updated for changes to non- 955 configuration child data resources. 957 If the RESTCONF server is colocated with a NETCONF server, then the 958 last-modified timestamp MUST represent the "running" datastore. 960 3.4.1.2. Entity tag 962 A unique opaque string is maintained and the "ETag" ([RFC7232], 963 Section 2.3) header is returned in the response for a retrieval 964 request. The "If-Match" header can be used in edit operation 965 requests to cause the server to reject the request if the resource 966 entity tag does not match the specified value. 968 The server MUST maintain an entity tag for the top-level {+restconf}/ 969 data resource. This entity tag is only affected by configuration 970 data resources, and MUST NOT be updated for changes to non- 971 configuration data. 973 If the RESTCONF server is colocated with a NETCONF server, then this 974 entity tag MUST represent the "running" datastore. 976 3.4.1.3. Update Procedure 978 Changes to configuration data resources affect the timestamp and 979 entity tag to that resource, any ancestor data resources, and the 980 datastore resource. 982 For example, an edit to disable an interface might be done by setting 983 the leaf "/interfaces/interface/enabled" to "false". The "enabled" 984 data node and its ancestors (one "interface" list instance, and the 985 "interfaces" container) are considered to be changed. The datastore 986 is considered to be changed when any top-level configuration data 987 node is changed (e.g., "interfaces"). 989 3.5. Data Resource 990 A data resource represents a YANG data node that is a descendant node 991 of a datastore resource. Each YANG-defined data node can be uniquely 992 targeted by the request-line of an HTTP method. Containers, leafs, 993 leaf-list entries, list entries, anydata and anyxml nodes are data 994 resources. 996 The representation maintained for each data resource is the YANG 997 defined subtree for that node. HTTP methods on a data resource 998 affect both the targeted data node and all its descendants, if any. 1000 A data resource can be retrieved with the GET method. Data resources 1001 are accessed via the "{+restconf}/data" entry point. This sub-tree 1002 is used to retrieve and edit data resources. The fragment field in 1003 the request URI has no defined purpose if the target resource is a 1004 data resource. 1006 A configuration data resource can be altered by the client with some 1007 or all of the edit operations, depending on the target resource and 1008 the specific operation. Refer to Section 4 for more details on edit 1009 operations. 1011 3.5.1. Timestamp 1013 For configuration data resources, the server MAY maintain a last- 1014 modified timestamp for the resource, and return the "Last-Modified" 1015 header when it is retrieved with the GET or HEAD methods. 1017 The "Last-Modified" header information can be used by a RESTCONF 1018 client in subsequent requests, within the "If-Modified-Since" and 1019 "If-Unmodified-Since" headers. 1021 If maintained, the resource timestamp MUST be set to the current time 1022 whenever the resource or any configuration resource within the 1023 resource is altered. If not maintained, then the resource timestamp 1024 for the datastore MUST be used instead. If the RESTCONF server is 1025 colocated with a NETCONF server, then the last-modified timestamp for 1026 a configuration data resource MUST represent the instance within the 1027 "running" datastore. 1029 This timestamp is only affected by configuration data resources, and 1030 MUST NOT be updated for changes to non-configuration data. 1032 For non-configuration data resources, the server MAY maintain a last- 1033 modified timestamp for the resource, and return the "Last-Modified" 1034 header when it is retrieved with the GET or HEAD methods. The 1035 timestamps for non-configuration data resources are updated in an 1036 implementation-specific manner. 1038 3.5.2. Entity tag 1040 For configuration data resources, the server SHOULD maintain a 1041 resource entity tag for each resource, and return the "ETag" header 1042 when it is retrieved as the target resource with the GET or HEAD 1043 methods. If maintained, the resource entity tag MUST be updated 1044 whenever the resource or any configuration resource within the 1045 resource is altered. If not maintained, then the resource entity tag 1046 for the datastore MUST be used instead. 1048 The "ETag" header information can be used by a RESTCONF client in 1049 subsequent requests, within the "If-Match" and "If-None-Match" 1050 headers. 1052 This entity tag is only affected by configuration data resources, and 1053 MUST NOT be updated for changes to non-configuration data. If the 1054 RESTCONF server is colocated with a NETCONF server, then the entity 1055 tag for a configuration data resource MUST represent the instance 1056 within the "running" datastore. 1058 For non-configuration data resources, the server MAY maintain an 1059 entity tag for each resource, and return the "ETag" header when it is 1060 retrieved with the GET or HEAD methods. The entity tags for non- 1061 configuration data resources are updated in an implementation- 1062 specific manner. 1064 3.5.3. Encoding Data Resource Identifiers in the Request URI 1066 In YANG, data nodes are identified with an absolute XPath expression, 1067 defined in [XPath], starting from the document root to the target 1068 resource. In RESTCONF, URI-encoded path expressions are used 1069 instead. 1071 A predictable location for a data resource is important, since 1072 applications will code to the YANG data model module, which uses 1073 static naming and defines an absolute path location for all data 1074 nodes. 1076 A RESTCONF data resource identifier is not an XPath expression. It 1077 is encoded from left to right, starting with the top-level data node, 1078 according to the "api-path" rule in Section 3.5.3.1. The node name 1079 of each ancestor of the target resource node is encoded in order, 1080 ending with the node name for the target resource. If a node in the 1081 path is defined in another module than its parent node, then module 1082 name followed by a colon character (":") is prepended to the node 1083 name in the resource identifier. See Section 3.5.3.1 for details. 1085 If a data node in the path expression is a YANG leaf-list node, then 1086 the leaf-list value MUST be encoded according to the following rules: 1088 o The identifier for the leaf-list MUST be encoded using one path 1089 segment [RFC3986]. 1091 o The path segment is constructed by having the leaf-list name, 1092 followed by an "=" character, followed by the leaf-list value. 1093 (e.g., /restconf/data/top-leaflist=fred). 1095 If a data node in the path expression is a YANG list node, then the 1096 key values for the list (if any) MUST be encoded according to the 1097 following rules: 1099 o The key leaf values for a data resource representing a YANG list 1100 MUST be encoded using one path segment [RFC3986]. 1102 o If there is only one key leaf value, the path segment is 1103 constructed by having the list name, followed by an "=" character, 1104 followed by the single key leaf value. 1106 o If there are multiple key leaf values, the path segment is 1107 constructed by having the list name, followed by the value of each 1108 leaf identified in the "key" statement, encoded in the order 1109 specified in the YANG "key" statement. Each key leaf value except 1110 the last one is followed by a comma character. 1112 o The key value is specified as a string, using the canonical 1113 representation for the YANG data type. Any reserved characters 1114 MUST be percent-encoded, according to [RFC3986], section 2.1. 1116 o All the components in the "key" statement MUST be encoded. 1117 Partial instance identifiers are not supported. 1119 o Since missing key values are not allowed, two consecutive commas 1120 are interpreted as a zero-length string. (example: 1121 list=foo,,baz). 1123 o The "list-instance" ABNF rule defined in Section 3.5.3.1 1124 represents the syntax of a list instance identifier. 1126 Resource URI values returned in Location headers for data resources 1127 MUST identify the module name as specified in 1128 [I-D.ietf-netmod-yang-json], even if there are no conflicting local 1129 names when the resource is created. This ensures the correct 1130 resource will be identified even if the server loads a new module 1131 that the old client does not know about. 1133 Examples: 1135 container top { 1136 list list1 { 1137 key "key1 key2 key3"; 1138 ... 1139 list list2 { 1140 key "key4 key5"; 1141 ... 1142 leaf X { type string; } 1143 } 1144 } 1145 leaf-list Y { 1146 type uint32; 1147 } 1148 } 1150 For the above YANG definition, the container "top" is defined in the 1151 "example-top" YANG module, and a target resource URI for leaf "X" 1152 would be encoded as follows (line wrapped for display purposes only): 1154 /restconf/data/example-top:top/list1=key1,key2,key3/ 1155 list2=key4,key5/X 1157 For the above YANG definition, a target resource URI for leaf-list 1158 "Y" would be encoded as follows: 1160 /restconf/data/example-top:top/Y=instance-value 1162 The following example shows how reserved characters are percent- 1163 encoded within a key value. The value of "key1" contains a comma, 1164 single-quote, double-quote, colon, double-quote, space, and forward 1165 slash. (,'":" /). Note that double-quote is not a reserved 1166 characters and does not need to be percent-encoded. The value of 1167 "key2" is the empty string, and the value of "key3" is the string 1168 "foo". 1170 Example URL: 1172 /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo 1174 3.5.3.1. ABNF For Data Resource Identifiers 1176 The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to 1177 construct RESTCONF path identifiers: 1179 api-path = "/" | 1180 ("/" api-identifier 1181 0*("/" (api-identifier | list-instance ))) 1183 api-identifier = [module-name ":"] identifier ;; note 1 1185 module-name = identifier 1187 list-instance = api-identifier "=" key-value ["," key-value]* 1189 key-value = string ;; note 1 1191 string = 1193 ;; An identifier MUST NOT start with 1194 ;; (('X'|'x') ('M'|'m') ('L'|'l')) 1195 identifier = (ALPHA / "_") 1196 *(ALPHA / DIGIT / "_" / "-" / ".") 1198 Note 1: The syntax for "api-identifier" and "key-value" MUST conform 1199 to the JSON identifier encoding rules in Section 4 of 1200 [I-D.ietf-netmod-yang-json]. 1202 3.5.4. Defaults Handling 1204 RESTCONF requires that a server report its default handling mode (see 1205 Section 9.1.2 for details). If the optional "with-defaults" query 1206 parameter is supported by the server, a client may use it to control 1207 retrieval of default values (see Section 4.8.9 for details). 1209 If a leaf or leaf-list is missing from the configuration and there is 1210 a YANG-defined default for that data resource, then the server MUST 1211 use the YANG-defined default as the configured value. 1213 If the target of a GET method is a data node that represents a leaf 1214 or leaf-list that has a default value, and the leaf or leaf-list has 1215 not been instantiated yet, the server MUST return the default 1216 value(s) that are in use by the server. In this case, the server 1217 MUST ignore its basic-mode, described in Section 4.8.9, and return 1218 the default value. 1220 If the target of a GET method is a data node that represents a 1221 container or list that has any child resources with default values, 1222 for the child resources that have not been given value yet, the 1223 server MAY return the default values that are in use by the server, 1224 in accordance with its reported default handing mode and query 1225 parameters passed by the client. 1227 3.6. Operation Resource 1228 An operation resource represents an RPC operation defined with the 1229 YANG "rpc" statement or a data-model specific action defined with a 1230 YANG "action" statement. It is invoked using a POST method on the 1231 operation resource. The fragment field in the request URI has no 1232 defined purpose if the target resource is an operation resource. 1234 An RPC operation is invoked as: 1236 POST {+restconf}/operations/ 1238 The field identifies the module name and rpc identifier 1239 string for the desired operation. 1241 For example, if "module-A" defined a "reset" rpc operation, then 1242 invoking the operation from "module-A" would be requested as follows: 1244 POST /restconf/operations/module-A:reset HTTP/1.1 1245 Server: example.com 1247 An action is invoked as: 1249 POST {+restconf}/data// 1251 where contains the path to the data node 1252 where the action is defined, and is the name of the action. 1254 For example, if "module-A" defined a "reset-all" action in the 1255 container "interfaces", then invoking this action would be requested 1256 as follows: 1258 POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 1259 Server: example.com 1261 If the "rpc" or "action" statement has an "input" section then 1262 instances of these input parameters are encoded in the module 1263 namespace where the "rpc" or "action" statement is defined, in an XML 1264 element or JSON object named "input". 1266 If the "rpc" or "action" statement has an "input" section and the 1267 "input" object tree contains any child data nodes which are 1268 considered mandatory nodes, then a message-body MUST be sent by the 1269 client in the request. 1271 If the "rpc" or "action" statement has an "input" section and the 1272 "input" object tree does not contain any child nodes which are 1273 considered mandatory nodes, then a message-body MAY be sent by the 1274 client in the request. 1276 If the "rpc" or "action" statement has no "input" section, the 1277 request message MUST NOT include a message-body. 1279 If the "rpc" or "action" statement has an "output" section then 1280 instances of these input parameters are encoded in the module 1281 namespace where the "rpc" or "action" statement is defined, in an XML 1282 element or JSON object named "output". 1284 If the RPC operation is invoked without errors, and if the "rpc" or 1285 "action" statement has an "output" section and the "output" object 1286 tree contains any child data nodes which are considered mandatory 1287 nodes, then a response message-body MUST be sent by the server in the 1288 response. 1290 If the RPC operation is invoked without errors, and if the "rpc" or 1291 "action" statement has an "output" section and the "output" object 1292 tree does not contain any child nodes which are considered mandatory 1293 nodes, then a response message-body MAY be sent by the server in the 1294 response. 1296 If the RPC operation is invoked without errors, and if the "rpc" or 1297 "action" statement has no "output" section, the response message MUST 1298 NOT include a message-body, and MUST send a "204 No Content" status- 1299 line instead. 1301 If the RPC operation input is not valid, or the RPC operation is 1302 invoked but errors occur, then a message-body MUST be sent by the 1303 server, containing an "errors" resource, as defined in Section 3.9. 1304 A detailed example of an operation resource error response can be 1305 found in Section 3.6.3. 1307 All operation resources representing RPC operations supported by the 1308 server MUST be identified in the {+restconf}/operations subtree 1309 defined in Section 3.3.2. Operation resources representing YANG 1310 actions are not identified in this subtree since they are invoked 1311 using a URI within the {+restconf}/data subtree. 1313 3.6.1. Encoding Operation Resource Input Parameters 1315 If the "rpc" or "action" statement has an "input" section, then the 1316 "input" node is provided in the message-body, corresponding to the 1317 YANG data definition statements within the "input" section. 1319 Examples: 1321 The following YANG module is used for the RPC operation examples in 1322 this section. 1324 module example-ops { 1325 namespace "https://example.com/ns/example-ops"; 1326 prefix "ops"; 1327 revision "2016-03-10"; 1329 rpc reboot { 1330 input { 1331 leaf delay { 1332 units seconds; 1333 type uint32; 1334 default 0; 1335 } 1336 leaf message { type string; } 1337 leaf language { type string; } 1338 } 1339 } 1341 rpc get-reboot-info { 1342 output { 1343 leaf reboot-time { 1344 units seconds; 1345 type uint32; 1346 } 1347 leaf message { type string; } 1348 leaf language { type string; } 1349 } 1350 } 1351 } 1353 The following YANG module is used for the YANG action examples in 1354 this section. 1356 module example-actions { 1357 yang-version 1.1; 1358 namespace "https://example.com/ns/example-actions"; 1359 prefix "act"; 1360 import ietf-yang-types { prefix yang; } 1361 revision "2016-03-10"; 1363 container interfaces { 1364 list interface { 1365 key name; 1366 leaf name { type string; } 1368 action reset { 1369 input { 1370 leaf delay { 1371 units seconds; 1372 type uint32; 1373 default 0; 1374 } 1375 } 1376 } 1378 action get-last-reset-time { 1379 output { 1380 leaf last-reset { 1381 type yang:date-and-time; 1382 mandatory true; 1383 } 1384 } 1385 } 1386 } 1387 } 1389 } 1391 RPC Input Example: 1393 The client might send the following POST request message to invoke 1394 the "reboot" RPC operation: 1396 POST /restconf/operations/example-ops:reboot HTTP/1.1 1397 Host: example.com 1398 Content-Type: application/yang-data+xml 1400 1401 600 1402 Going down for system maintenance 1403 en-US 1404 1406 The server might respond: 1408 HTTP/1.1 204 No Content 1409 Date: Mon, 25 Apr 2012 11:01:00 GMT 1410 Server: example-server 1412 The same example request message is shown here using JSON encoding: 1414 POST /restconf/operations/example-ops:reboot HTTP/1.1 1415 Host: example.com 1416 Content-Type: application/yang-data+json 1417 { 1418 "example-ops:input" : { 1419 "delay" : 600, 1420 "message" : "Going down for system maintenance", 1421 "language" : "en-US" 1422 } 1423 } 1425 Action Input Example: 1427 The client might send the following POST request message to invoke 1428 the "reset" action (text wrap for display purposes): 1430 POST /restconf/data/example-actions:interfaces/interface=eth0 1431 /reset HTTP/1.1 1432 Host: example.com 1433 Content-Type: application/yang-data+xml 1435 1436 600 1437 1439 The server might respond: 1441 HTTP/1.1 204 No Content 1442 Date: Mon, 25 Apr 2012 11:01:00 GMT 1443 Server: example-server 1445 The same example request message is shown here using JSON encoding 1446 (text wrap for display purposes): 1448 POST /restconf/data/example-actions:interfaces/interface=eth0 1449 /reset HTTP/1.1 1450 Host: example.com 1451 Content-Type: application/yang-data+json 1453 { "example-actions:input" : { 1454 "delay" : 600 1455 } 1456 } 1458 3.6.2. Encoding Operation Resource Output Parameters 1460 If the "rpc" or "action" statement has an "output" section, then the 1461 "output" node is provided in the message-body, corresponding to the 1462 YANG data definition statements within the "output" section. 1464 The request URI is not returned in the response. This URI might have 1465 context information required to associate the output to the specific 1466 "rpc" or "action" statement used in the request. 1468 Examples: 1470 RPC Output Example: 1472 The "example-ops" YANG module defined in Section 3.6.1 is used for 1473 this example. 1475 The client might send the following POST request message to invoke 1476 the "get-reboot-info" operation: 1478 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 1479 Host: example.com 1480 Accept: application/yang-data+json 1482 The server might respond: 1484 HTTP/1.1 200 OK 1485 Date: Mon, 25 Apr 2012 11:10:30 GMT 1486 Server: example-server 1487 Content-Type: application/yang-data+json 1489 { 1490 "example-ops:output" : { 1491 "reboot-time" : 30, 1492 "message" : "Going down for system maintenance", 1493 "language" : "en-US" 1494 } 1495 } 1497 The same response is shown here using XML encoding: 1499 HTTP/1.1 200 OK 1500 Date: Mon, 25 Apr 2012 11:10:30 GMT 1501 Server: example-server 1502 Content-Type: application/yang-data+xml 1504 1505 30 1506 Going down for system maintenance 1507 en-US 1508 1510 Action Output Example: 1512 The "example-actions" YANG module defined in Section 3.6.1 is used 1513 for this example. 1515 The client might send the following POST request message to invoke 1516 the "get-last-reset-time" action: 1518 POST /restconf/data/example-actions:interfaces/interface=eth0 1519 /get-last-reset-time HTTP/1.1 1520 Host: example.com 1521 Accept: application/yang-data+json 1523 The server might respond: 1525 HTTP/1.1 200 OK 1526 Date: Mon, 25 Apr 2012 11:10:30 GMT 1527 Server: example-server 1528 Content-Type: application/yang-data+json 1530 { 1531 "example-actions:output" : { 1532 "last-reset" : "2015-10-10T02:14:11Z" 1533 } 1534 } 1536 3.6.3. Encoding Operation Resource Errors 1538 If any errors occur while attempting to invoke the operation or 1539 action, then an "errors" media type is returned with the appropriate 1540 error status. 1542 Using the "reboot" RPC operation from the example in Section 3.6.1, 1543 the client might send the following POST request message: 1545 POST /restconf/operations/example-ops:reboot HTTP/1.1 1546 Host: example.com 1547 Content-Type: application/yang-data+xml 1549 1550 -33 1551 Going down for system maintenance 1552 en-US 1553 1555 The server might respond with an "invalid-value" error: 1557 HTTP/1.1 400 Bad Request 1558 Date: Mon, 25 Apr 2012 11:10:30 GMT 1559 Server: example-server 1560 Content-Type: application/yang-data+xml 1562 1563 1564 protocol 1565 invalid-value 1566 1567 /ops:input/ops:delay 1568 1569 Invalid input parameter 1570 1571 1573 The same response is shown here in JSON encoding: 1575 HTTP/1.1 400 Bad Request 1576 Date: Mon, 25 Apr 2012 11:10:30 GMT 1577 Server: example-server 1578 Content-Type: application/yang-data+json 1580 { "ietf-restconf:errors" : { 1581 "error" : [ 1582 { 1583 "error-type" : "protocol", 1584 "error-tag" : "invalid-value", 1585 "error-path" : "/example-ops:input/delay", 1586 "error-message" : "Invalid input parameter", 1587 } 1588 ] 1589 } 1590 } 1592 3.7. Schema Resource 1594 The server can optionally support retrieval of the YANG modules it 1595 supports. If retrieval is supported, then the "schema" leaf MUST be 1596 present in the associated "module" list entry, defined in 1597 [I-D.ietf-netconf-yang-library]. 1599 To retrieve a YANG module, a client first needs to get the URL for 1600 retrieving the schema, which is stored in the "schema" leaf. Note 1601 that there is no required structure for this URL. The URL value 1602 shown below is just an example. 1604 The client might send the following GET request message: 1606 GET /restconf/data/ietf-yang-library:modules-state/module= 1607 example-jukebox,2015-04-04/schema HTTP/1.1 1608 Host: example.com 1609 Accept: application/yang-data+json 1611 The server might respond: 1613 HTTP/1.1 200 OK 1614 Date: Thu, 11 Feb 2016 11:10:30 GMT 1615 Server: example-server 1616 Content-Type: application/yang-data+json 1618 { 1619 "ietf-yang-library:schema": 1620 "https://example.com/mymodules/example-jukebox/2015-04-04" 1621 } 1623 Next the client needs to retrieve the actual YANG schema. 1625 The client might send the following GET request message: 1627 GET https://example.com/mymodules/example-jukebox/2015-04-04 1628 HTTP/1.1 1629 Host: example.com 1630 Accept: application/yang 1632 The server might respond: 1634 HTTP/1.1 200 OK 1635 Date: Thu, 11 Feb 2016 11:10:31 GMT 1636 Server: example-server 1637 Content-Type: application/yang 1639 module example-jukebox { 1641 // contents of YANG module deleted for this example... 1643 } 1645 3.8. Event Stream Resource 1647 An "event stream" resource represents a source for system generated 1648 event notifications. Each stream is created and modified by the 1649 server only. A client can retrieve a stream resource or initiate a 1650 long-poll server sent event stream, using the procedure specified in 1651 Section 6.3. 1653 A notification stream functions according to the NETCONF 1654 Notifications specification [RFC5277]. The available streams can be 1655 retrieved from the stream list, which specifies the syntax and 1656 semantics of a stream resource. 1658 The fragment field in the request URI has no defined purpose if the 1659 target resource is an event stream resource. 1661 3.9. Errors YANG Data Template 1663 An "errors" YANG data template models a collection of error 1664 information that is sent as the message-body in a server response 1665 message, if an error occurs while processing a request message. It 1666 is not considered a resource type because no instances can be 1667 retrieved with a GET request. 1669 The "ietf-restconf" YANG module contains the "yang-errors" YANG data 1670 template, that specifies the syntax and semantics of an "errors" 1671 container within a RESTCONF response. RESTCONF error handling 1672 behavior is defined in Section 7. 1674 4. Operations 1676 The RESTCONF protocol uses HTTP methods to identify the CRUD 1677 operation requested for a particular resource. 1679 The following table shows how the RESTCONF operations relate to 1680 NETCONF protocol operations and edit operations, which are identified 1681 with the NETCONF "nc:operation" attribute. 1683 +----------+-----------------------------------------------+ 1684 | RESTCONF | NETCONF | 1685 +----------+-----------------------------------------------+ 1686 | OPTIONS | none | 1687 | HEAD | none | 1688 | GET | , | 1689 | POST | (nc:operation="create") | 1690 | POST | invoke an RPC operation | 1691 | PUT | (nc:operation="create/replace") | 1692 | PATCH | (nc:operation="merge") | 1693 | DELETE | (nc:operation="delete") | 1694 +----------+-----------------------------------------------+ 1696 CRUD Methods in RESTCONF 1698 The "remove" operation attribute for the NETCONF 1699 operation is not supported by the HTTP DELETE method. The resource 1700 must exist or the DELETE method will fail. The PATCH method is 1701 equivalent to a "merge" operation when using a plain patch (see 1702 Section 4.6.1); other media-types may provide more granular control. 1704 Access control mechanisms MUST be used to limit what operations can 1705 be used. In particular, RESTCONF is compatible with the NETCONF 1706 Access Control Model (NACM) [RFC6536], as there is a specific mapping 1707 between RESTCONF and NETCONF operations, defined in Section 4. The 1708 resource path needs to be converted internally by the server to the 1709 corresponding YANG instance-identifier. Using this information, the 1710 server can apply the NACM access control rules to RESTCONF messages. 1712 The server MUST NOT allow any operation to any resources that the 1713 client is not authorized to access. 1715 Implementation of all methods (except PATCH) are defined in 1716 [RFC7231]. This section defines the RESTCONF protocol usage for each 1717 HTTP method. 1719 4.1. OPTIONS 1721 The OPTIONS method is sent by the client to discover which methods 1722 are supported by the server for a specific resource (e.g., GET, POST, 1723 DELETE, etc.). The server MUST implement this method. 1725 If the PATCH method is supported, then the "Accept-Patch" header MUST 1726 be supported and returned in the response to the OPTIONS request, as 1727 defined in [RFC5789]. 1729 4.2. HEAD 1731 The HEAD method is sent by the client to retrieve just the headers 1732 that would be returned for the comparable GET method, without the 1733 response message-body. It is supported for all resource types, 1734 except operation resources. 1736 The request MUST contain a request URI that contains at least the 1737 entry point. The same query parameters supported by the GET method 1738 are supported by the HEAD method. 1740 The access control behavior is enforced as if the method was GET 1741 instead of HEAD. The server MUST respond the same as if the method 1742 was GET instead of HEAD, except that no response message-body is 1743 included. 1745 4.3. GET 1747 The GET method is sent by the client to retrieve data and metadata 1748 for a resource. It is supported for all resource types, except 1749 operation resources. The request MUST contain a request URI that 1750 contains at least the entry point. 1752 The server MUST NOT return any data resources for which the user does 1753 not have read privileges. If the user is not authorized to read the 1754 target resource, an error response containing a "401 Unauthorized" 1755 status-line SHOULD be returned. A server MAY return a "404 Not 1756 Found" status-line, as described in section 6.5.3 in [RFC7231]. 1758 If the user is authorized to read some but not all of the target 1759 resource, the unauthorized content is omitted from the response 1760 message-body, and the authorized content is returned to the client. 1762 If any content is returned to the client, then the server MUST send a 1763 valid response message-body. More than one element MUST NOT be 1764 returned for XML encoding. 1766 If a retrieval request for a data resource representing a YANG leaf- 1767 list or list object identifies more than one instance, and XML 1768 encoding is used in the response, then an error response containing a 1769 "400 Bad Request" status-line MUST be returned by the server. 1771 If a retrieval request for a data resource represents an instance 1772 that does not exist, then an error response containing a "404 Not 1773 Found" status-line MUST be returned by the server. 1775 If the target resource of a retrieval request is for an operation 1776 resource then a "405 Method Not Allowed" status-line MUST be returned 1777 by the server. 1779 Note that the way that access control is applied to data resources 1780 may not be completely compatible with HTTP caching. The Last- 1781 Modified and ETag headers maintained for a data resource are not 1782 affected by changes to the access control rules for that data 1783 resource. It is possible for the representation of a data resource 1784 that is visible to a particular client to be changed without 1785 detection via the Last-Modified or ETag values. 1787 Example: 1789 The client might request the response headers for an XML 1790 representation of the a specific "album" resource: 1792 GET /restconf/data/example-jukebox:jukebox/ 1793 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1794 Host: example.com 1795 Accept: application/yang-data+xml 1796 The server might respond: 1798 HTTP/1.1 200 OK 1799 Date: Mon, 23 Apr 2012 17:02:40 GMT 1800 Server: example-server 1801 Content-Type: application/yang-data+xml 1802 Cache-Control: no-cache 1803 ETag: "a74eefc993a2b" 1804 Last-Modified: Mon, 23 Apr 2012 11:02:14 GMT 1806 1808 Wasting Light 1809 jbox:alternative 1810 2011 1811 1813 4.4. POST 1815 The POST method is sent by the client to create a data resource or 1816 invoke an operation resource. The server uses the target resource 1817 media type to determine how to process the request. 1819 +-----------+------------------------------------------------+ 1820 | Type | Description | 1821 +-----------+------------------------------------------------+ 1822 | Datastore | Create a top-level configuration data resource | 1823 | Data | Create a configuration data child resource | 1824 | Operation | Invoke an RPC operation | 1825 +-----------+------------------------------------------------+ 1827 Resource Types that Support POST 1829 4.4.1. Create Resource Mode 1831 If the target resource type is a datastore or data resource, then the 1832 POST is treated as a request to create a top-level resource or child 1833 resource, respectively. The message-body is expected to contain the 1834 content of a child resource to create within the parent (target 1835 resource). The message-body MUST contain exactly one instance of the 1836 expected data resource. The data-model for the child tree is the 1837 subtree as defined by YANG for the child resource. 1839 The "insert" Section 4.8.5 and "point" Section 4.8.6 query parameters 1840 MUST be supported by the POST method for datastore and data 1841 resources. These parameters are only allowed if the list or leaf- 1842 list is ordered-by user. 1844 If the POST method succeeds, a "201 Created" status-line is returned 1845 and there is no response message-body. A "Location" header 1846 identifying the child resource that was created MUST be present in 1847 the response in this case. 1849 If the data resource already exists, then the POST request MUST fail 1850 and a "409 Conflict" status-line MUST be returned. 1852 If the user is not authorized to create the target resource, an error 1853 response containing a "403 Forbidden" status-line SHOULD be returned. 1854 A server MAY return a "404 Not Found" status-line, as described in 1855 section 6.5.3 in [RFC7231]. All other error responses are handled 1856 according to the procedures defined in Section 7. 1858 Example: 1860 To create a new "jukebox" resource, the client might send: 1862 POST /restconf/data HTTP/1.1 1863 Host: example.com 1864 Content-Type: application/yang-data+json 1866 { "example-jukebox:jukebox" : {} } 1868 If the resource is created, the server might respond as follows. 1869 Note that the "Location" header line is wrapped for display purposes 1870 only: 1872 HTTP/1.1 201 Created 1873 Date: Mon, 23 Apr 2012 17:01:00 GMT 1874 Server: example-server 1875 Location: https://example.com/restconf/data/ 1876 example-jukebox:jukebox 1877 Last-Modified: Mon, 23 Apr 2012 17:01:00 GMT 1878 ETag: "b3a3e673be2" 1880 Refer to Appendix D.2.1 for more resource creation examples. 1882 4.4.2. Invoke Operation Mode 1884 If the target resource type is an operation resource, then the POST 1885 method is treated as a request to invoke that operation. The 1886 message-body (if any) is processed as the operation input parameters. 1887 Refer to Section 3.6 for details on operation resources. 1889 If the POST request succeeds, a "200 OK" status-line is returned if 1890 there is a response message-body, and a "204 No Content" status-line 1891 is returned if there is no response message-body. 1893 If the user is not authorized to invoke the target operation, an 1894 error response containing a "403 Forbidden" status-line is returned 1895 to the client. All other error responses are handled according to 1896 the procedures defined in Section 7. 1898 Example: 1900 In this example, the client is invoking the "play" operation defined 1901 in the "example-jukebox" YANG module. 1903 A client might send a "play" request as follows: 1905 POST /restconf/operations/example-jukebox:play HTTP/1.1 1906 Host: example.com 1907 Content-Type: application/yang-data+json 1909 { 1910 "example-jukebox:input" : { 1911 "playlist" : "Foo-One", 1912 "song-number" : 2 1913 } 1914 } 1916 The server might respond: 1918 HTTP/1.1 204 No Content 1919 Date: Mon, 23 Apr 2012 17:50:00 GMT 1920 Server: example-server 1922 4.5. PUT 1924 The PUT method is sent by the client to create or replace the target 1925 data resource. A request message-body MUST be present, representing 1926 the new data resource, or the server MUST return "400 Bad Request" 1927 status-line. 1929 The only target resource media type that supports PUT is the data 1930 resource. The message-body is expected to contain the content used 1931 to create or replace the target resource. 1933 The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query 1934 parameters MUST be supported by the PUT method for data resources. 1935 These parameters are only allowed if the list or leaf-list is 1936 ordered-by user. 1938 Consistent with [RFC7231], if the PUT request creates a new resource, 1939 a "201 Created" status-line is returned. If an existing resource is 1940 modified, a "204 No Content" status-line is returned. 1942 If the user is not authorized to create or replace the target 1943 resource an error response containing a "403 Forbidden" status-line 1944 SHOULD be returned. A server MAY return a "404 Not Found" status- 1945 line, as described in section 6.5.3 in [RFC7231]. All other error 1946 responses are handled according to the procedures defined in 1947 Section 7. 1949 If the target resource represents a YANG leaf-list, then the PUT 1950 method MUST NOT change the value of the leaf-list instance. 1952 If the target resource represents a YANG list instance, then the PUT 1953 method MUST NOT change any key leaf values in the message-body 1954 representation. 1956 Example: 1958 An "album" child resource defined in the "example-jukebox" YANG 1959 module is replaced or created if it does not already exist. 1961 To replace the "album" resource contents, the client might send as 1962 follows. Note that the request-line is wrapped for display purposes 1963 only: 1965 PUT /restconf/data/example-jukebox:jukebox/ 1966 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1967 Host: example.com 1968 Content-Type: application/yang-data+json 1970 { 1971 "example-jukebox:album" : [ 1972 { 1973 "name" : "Wasting Light", 1974 "genre" : "example-jukebox:alternative", 1975 "year" : 2011 1976 } 1977 ] 1978 } 1980 If the resource is updated, the server might respond: 1982 HTTP/1.1 204 No Content 1983 Date: Mon, 23 Apr 2012 17:04:00 GMT 1984 Server: example-server 1985 Last-Modified: Mon, 23 Apr 2012 17:04:00 GMT 1986 ETag: "b27480aeda4c" 1988 The same request is shown here using XML encoding: 1990 PUT /restconf/data/example-jukebox:jukebox/ 1991 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1992 Host: example.com 1993 Content-Type: application/yang-data+xml 1995 1997 Wasting Light 1998 jbox:alternative 1999 2011 2000 2002 4.6. PATCH 2004 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 2005 an extensible framework for resource patching mechanisms. It is 2006 optional to implement by the server. Each patch mechanism needs a 2007 unique media type. Zero or more patch media types MAY be supported 2008 by the server. The media types supported by a server can be 2009 discovered by the client by sending an OPTIONS request (see 2010 Section 4.1). 2012 This document defines one patch mechanism (Section 4.6.1). Another 2013 patch mechanism, the YANG PATCH mechanism, is defined in 2014 [I-D.ietf-netconf-yang-patch]. Other patch mechanisms may be defined 2015 by future specifications. 2017 If the target resource instance does not exist, the server MUST NOT 2018 create it. 2020 If the PATCH request succeeds, a "200 OK" status-line is returned if 2021 there is a message-body, and "204 No Content" is returned if no 2022 response message-body is sent. 2024 If the user is not authorized to alter the target resource an error 2025 response containing a "403 Forbidden" status-line SHOULD be returned. 2026 A server MAY return a "404 Not Found" status-line, as described in 2027 section 6.5.3 in [RFC7231]. All other error responses are handled 2028 according to the procedures defined in Section 7. 2030 4.6.1. Plain Patch 2032 The plain patch mechanism merges the contents of the message-body 2033 with the target resource. The message-body for a plain patch MUST be 2034 present and MUST be represented by the media type "application/ 2035 yang-data+xml" or "application/yang-data+json". 2037 Plain patch can be used to create or update, but not delete, a child 2038 resource within the target resource. Please see 2039 [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting 2040 the ability to delete child resources. The YANG Patch Media Type 2041 allows multiple sub-operations (e.g., merge, delete) within a single 2042 PATCH operation. 2044 If the target resource represents a YANG leaf-list, then the PATCH 2045 method MUST NOT change the value of the leaf-list instance. 2047 If the target resource represents a YANG list instance, then the 2048 PATCH method MUST NOT change any key leaf values in the message-body 2049 representation. 2051 Example: 2053 To replace just the "year" field in the "album" resource (instead of 2054 replacing the entire resource with the PUT method), the client might 2055 send a plain patch as follows. Note that the request-line is wrapped 2056 for display purposes only: 2058 PATCH /restconf/data/example-jukebox:jukebox/ 2059 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2060 Host: example.com 2061 If-Match: "b8389233a4c" 2062 Content-Type: application/yang-data+xml 2064 2065 2011 2066 2068 If the field is updated, the server might respond: 2070 HTTP/1.1 204 No Content 2071 Date: Mon, 23 Apr 2012 17:49:30 GMT 2072 Server: example-server 2073 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 2074 ETag: "b2788923da4c" 2076 4.7. DELETE 2078 The DELETE method is used to delete the target resource. If the 2079 DELETE request succeeds, a "204 No Content" status-line is returned. 2081 If the user is not authorized to delete the target resource then an 2082 error response containing a "403 Forbidden" status-line SHOULD be 2083 returned. A server MAY return a "404 Not Found" status-line, as 2084 described in section 6.5.3 in [RFC7231]. All other error responses 2085 are handled according to the procedures defined in Section 7. 2087 If the target resource represents a YANG leaf-list or list, then the 2088 DELETE method SHOULD NOT delete more than one such instance. The 2089 server MAY delete more than one instance if a query parameter is used 2090 requesting this behavior. (Definition of this query parameter is 2091 outside the scope of this document.) 2093 Example: 2095 To delete a resource such as the "album" resource, the client might 2096 send: 2098 DELETE /restconf/data/example-jukebox:jukebox/ 2099 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2100 Host: example.com 2102 If the resource is deleted, the server might respond: 2104 HTTP/1.1 204 No Content 2105 Date: Mon, 23 Apr 2012 17:49:40 GMT 2106 Server: example-server 2108 4.8. Query Parameters 2110 Each RESTCONF operation allows zero or more query parameters to be 2111 present in the request URI. The specific parameters that are allowed 2112 depends on the resource type, and sometimes the specific target 2113 resource used, in the request. 2115 o Query parameters can be given in any order. 2117 o Each parameter can appear at most once in a request URI. 2119 o If more than one instance of a query parameter is present, then a 2120 "400 Bad Request" status-line MUST be returned by the server. 2122 o A default value may apply if the parameter is missing. 2124 o Query parameter names and values are case-sensitive 2126 o A server MUST return an error with a '400 Bad Request' status-line 2127 if a query parameter is unexpected. 2129 +-------------------+-------------+---------------------------------+ 2130 | Name | Methods | Description | 2131 +-------------------+-------------+---------------------------------+ 2132 | content | GET, HEAD | Select config and/or non-config | 2133 | | | data resources | 2134 | depth | GET, HEAD | Request limited sub-tree depth | 2135 | | | in the reply content | 2136 | fields | GET, HEAD | Request a subset of the target | 2137 | | | resource contents | 2138 | filter | GET, HEAD | Boolean notification filter for | 2139 | | | event stream resources | 2140 | insert | POST, PUT | Insertion mode for ordered-by | 2141 | | | user data resources | 2142 | point | POST, PUT | Insertion point for ordered-by | 2143 | | | user data resources | 2144 | start-time | GET, HEAD | Replay buffer start time for | 2145 | | | event stream resources | 2146 | stop-time | GET, HEAD | Replay buffer stop time for | 2147 | | | event stream resources | 2148 | with-defaults | GET, HEAD | Control retrieval of default | 2149 | | | values | 2150 +-------------------+-------------+---------------------------------+ 2152 RESTCONF Query Parameters 2154 Refer to Appendix D.3 for examples of query parameter usage. 2156 If vendors define additional query parameters, they SHOULD use a 2157 prefix (such as the enterprise or organization name) for query 2158 parameter names in order to avoid collisions with other parameters. 2160 4.8.1. The "content" Query Parameter 2162 The "content" parameter controls how descendant nodes of the 2163 requested data nodes will be processed in the reply. 2165 The allowed values are: 2167 +-----------+-----------------------------------------------------+ 2168 | Value | Description | 2169 +-----------+-----------------------------------------------------+ 2170 | config | Return only configuration descendant data nodes | 2171 | nonconfig | Return only non-configuration descendant data nodes | 2172 | all | Return all descendant data nodes | 2173 +-----------+-----------------------------------------------------+ 2175 This parameter is only allowed for GET methods on datastore and data 2176 resources. A "400 Bad Request" status-line is returned if used for 2177 other methods or resource types. 2179 If this query parameter is not present, the default value is "all". 2180 This query parameter MUST be supported by the server. 2182 4.8.2. The "depth" Query Parameter 2184 The "depth" parameter is used to specify the number of nest levels 2185 returned in a response for a GET method. The first nest-level 2186 consists of the requested data node itself. If the "fields" 2187 parameter (Section 4.8.3) is used to select descendant data nodes, 2188 these nodes all have a depth value of 1. This has the effect of 2189 including the nodes specified by the fields, even if the "depth" 2190 value is less than the actual depth level of the specified fields. 2191 Any child nodes which are contained within a parent node have a depth 2192 value that is 1 greater than its parent. 2194 The value of the "depth" parameter is either an integer between 1 and 2195 65535, or the string "unbounded". "unbounded" is the default. 2197 This parameter is only allowed for GET methods on API, datastore, and 2198 data resources. A "400 Bad Request" status-line is returned if it 2199 used for other methods or resource types. 2201 By default, the server will include all sub-resources within a 2202 retrieved resource, which have the same resource type as the 2203 requested resource. Only one level of sub-resources with a different 2204 media type than the target resource will be returned. The exception 2205 is the datastore resource. If this resource type is retrieved then 2206 by default the datastore and all child data resources are returned. 2208 If the "depth" query parameter URI is listed in the "capability" 2209 leaf-list in Section 9.3, then the server supports the "depth" query 2210 parameter. 2212 4.8.3. The "fields" Query Parameter 2214 The "fields" query parameter is used to optionally identify data 2215 nodes within the target resource to be retrieved in a GET method. 2216 The client can use this parameter to retrieve a subset of all nodes 2217 in a resource. 2219 A value of the "fields" query parameter matches the following rule: 2221 fields-expr = path '(' fields-expr ')' / 2222 path ';' fields-expr / 2223 path 2224 path = api-identifier [ '/' path ] 2226 "api-identifier" is defined in Section 3.5.3.1. 2228 ";" is used to select multiple nodes. For example, to retrieve only 2229 the "genre" and "year" of an album, use: "fields=genre;year". 2231 Parentheses are used to specify sub-selectors of a node. Note that 2232 there is no path separator character '/' between a "path" field and 2233 left parenthesis character '('. 2235 For example, assume the target resource is the "album" list. To 2236 retrieve only the "label" and "catalogue-number" of the "admin" 2237 container within an album, use: 2238 "fields=admin(label;catalogue-number)". 2240 "/" is used in a path to retrieve a child node of a node. For 2241 example, to retrieve only the "label" of an album, use: "fields=admin 2242 /label". 2244 This parameter is only allowed for GET methods on api, datastore, and 2245 data resources. A "400 Bad Request" status-line is returned if used 2246 for other methods or resource types. 2248 If the "fields" query parameter URI is listed in the "capability" 2249 leaf-list in Section 9.3, then the server supports the "fields" 2250 parameter. 2252 4.8.4. The "filter" Query Parameter 2254 The "filter" parameter is used to indicate which subset of all 2255 possible events are of interest. If not present, all events not 2256 precluded by other parameters will be sent. 2258 This parameter is only allowed for GET methods on a text/event-stream 2259 data resource. A "400 Bad Request" status-line is returned if used 2260 for other methods or resource types. 2262 The format of this parameter is an XPath 1.0 expression, and is 2263 evaluated in the following context: 2265 o The set of namespace declarations is the set of prefix and 2266 namespace pairs for all supported YANG modules, where the prefix 2267 is the YANG module name, and the namespace is as defined by the 2268 "namespace" statement in the YANG module. 2270 o The function library is the core function library defined in XPath 2271 1.0, plus any functions defined by the data model. 2273 o The set of variable bindings is empty. 2275 o The context node is the root node. 2277 The filter is used as defined in [RFC5277], Section 3.6. If the 2278 boolean result of the expression is true when applied to the 2279 conceptual "notification" document root, then the event notification 2280 is delivered to the client. 2282 If the "filter" query parameter URI is listed in the "capability" 2283 leaf-list in Section 9.3, then the server supports the "filter" query 2284 parameter. 2286 4.8.5. The "insert" Query Parameter 2288 The "insert" parameter is used to specify how a resource should be 2289 inserted within a ordered-by user list. 2291 The allowed values are: 2293 +-----------+-------------------------------------------------------+ 2294 | Value | Description | 2295 +-----------+-------------------------------------------------------+ 2296 | first | Insert the new data as the new first entry. | 2297 | last | Insert the new data as the new last entry. | 2298 | before | Insert the new data before the insertion point, as | 2299 | | specified by the value of the "point" parameter. | 2300 | after | Insert the new data after the insertion point, as | 2301 | | specified by the value of the "point" parameter. | 2302 +-----------+-------------------------------------------------------+ 2304 The default value is "last". 2306 This parameter is only supported for the POST and PUT methods. It is 2307 also only supported if the target resource is a data resource, and 2308 that data represents a YANG list or leaf-list that is ordered-by 2309 user. 2311 If the values "before" or "after" are used, then a "point" query 2312 parameter for the insertion parameter MUST also be present, or a "400 2313 Bad Request" status-line is returned. 2315 The "insert" query parameter MUST be supported by the server. 2317 4.8.6. The "point" Query Parameter 2319 The "point" parameter is used to specify the insertion point for a 2320 data resource that is being created or moved within an ordered-by 2321 user list or leaf-list. 2323 The value of the "point" parameter is a string that identifies the 2324 path to the insertion point object. The format is the same as a 2325 target resource URI string. 2327 This parameter is only supported for the POST and PUT methods. It is 2328 also only supported if the target resource is a data resource, and 2329 that data represents a YANG list or leaf-list that is ordered-by 2330 user. 2332 If the "insert" query parameter is not present, or has a value other 2333 than "before" or "after", then a "400 Bad Request" status-line is 2334 returned. 2336 This parameter contains the instance identifier of the resource to be 2337 used as the insertion point for a POST or PUT method. 2339 The "point" query parameter MUST be supported by the server. 2341 4.8.7. The "start-time" Query Parameter 2343 The "start-time" parameter is used to trigger the notification replay 2344 feature defined in [RFC5277] and indicate that the replay should 2345 start at the time specified. If the stream does not support replay, 2346 per the "replay-support" attribute returned by stream list entry for 2347 the stream resource, then the server MUST return a "400 Bad Request" 2348 status-line. 2350 The value of the "start-time" parameter is of type "date-and-time", 2351 defined in the "ietf-yang" YANG module [RFC6991]. 2353 This parameter is only allowed for GET methods on a text/event-stream 2354 data resource. A "400 Bad Request" status-line is returned if used 2355 for other methods or resource types. 2357 If this parameter is not present, then a replay subscription is not 2358 being requested. It is not valid to specify start times that are 2359 later than the current time. If the value specified is earlier than 2360 the log can support, the replay will begin with the earliest 2361 available notification. A client can obtain a server's current time 2362 by examining the "Date" header field that the server returns in 2363 response messages, according to [RFC7231]. 2365 If this query parameter is supported by the server, then the "replay" 2366 query parameter URI MUST be listed in the "capability" leaf-list in 2367 Section 9.3. The "stop-time" query parameter MUST also be supported 2368 by the server. 2370 If the "replay-support" leaf has the value 'true' in the "stream" 2371 entry (defined in Section 9.3) then the server MUST support the 2372 "start-time" and "stop-time" query parameters for that stream. 2374 4.8.8. The "stop-time" Query Parameter 2376 The "stop-time" parameter is used with the replay feature to indicate 2377 the newest notifications of interest. This parameter MUST be used 2378 with and have a value later than the "start-time" parameter. 2380 The value of the "stop-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, the notifications will continue 2388 until the subscription is terminated. Values in the future are 2389 valid. 2391 If this query parameter is supported by the server, then the "replay" 2392 query parameter URI MUST be listed in the "capability" leaf-list in 2393 Section 9.3. The "start-time" query parameter MUST also be supported 2394 by the server. 2396 If the "replay-support" leaf is present in the "stream" entry 2397 (defined in Section 9.3) then the server MUST support the 2398 "start-time" and "stop-time" query parameters for that stream. 2400 4.8.9. The "with-defaults" Query Parameter 2402 The "with-defaults" parameter is used to specify how information 2403 about default data nodes should be returned in response to GET 2404 requests on data resources. 2406 If the server supports this capability, then it MUST implement the 2407 behavior in Section 4.5.1 of [RFC6243], except applied to the 2408 RESTCONF GET operation, instead of the NETCONF operations. 2410 +---------------------------+---------------------------------------+ 2411 | Value | Description | 2412 +---------------------------+---------------------------------------+ 2413 | report-all | All data nodes are reported | 2414 | trim | Data nodes set to the YANG default | 2415 | | are not reported | 2416 | explicit | Data nodes set to the YANG default by | 2417 | | the client are reported | 2418 | report-all-tagged | All data nodes are reported and | 2419 | | defaults are tagged | 2420 +---------------------------+---------------------------------------+ 2422 If the "with-defaults" parameter is set to "report-all" then the 2423 server MUST adhere to the defaults reporting behavior defined in 2424 Section 3.1 of [RFC6243]. 2426 If the "with-defaults" parameter is set to "trim" then the server 2427 MUST adhere to the defaults reporting behavior defined in Section 3.2 2428 of [RFC6243]. 2430 If the "with-defaults" parameter is set to "explicit" then the server 2431 MUST adhere to the defaults reporting behavior defined in Section 3.3 2432 of [RFC6243]. 2434 If the "with-defaults" parameter is set to "report-all-tagged" then 2435 the server MUST adhere to the defaults reporting behavior defined in 2436 Section 3.4 of [RFC6243]. 2438 If the "with-defaults" parameter is not present then the server MUST 2439 adhere to the defaults reporting behavior defined in its "basic-mode" 2440 parameter for the "defaults" protocol capability URI, defined in 2441 Section 9.1.2. 2443 If the server includes the "with-defaults" query parameter URI in the 2444 "capability" leaf-list in Section 9.3, then the "with-defaults" query 2445 parameter MUST be supported. 2447 5. Messages 2449 The RESTCONF protocol uses HTTP entities for messages. A single HTTP 2450 message corresponds to a single protocol method. Most messages can 2451 perform a single task on a single resource, such as retrieving a 2452 resource or editing a resource. The exception is the PATCH method, 2453 which allows multiple datastore edits within a single message. 2455 5.1. Request URI Structure 2457 Resources are represented with URIs following the structure for 2458 generic URIs in [RFC3986]. 2460 A RESTCONF operation is derived from the HTTP method and the request 2461 URI, using the following conceptual fields: 2463 //?# 2465 ^ ^ ^ ^ ^ 2466 | | | | | 2467 method entry resource query fragment 2469 M M O O I 2471 M=mandatory, O=optional, I=ignored 2473 where: 2475 is the HTTP method 2476 is the RESTCONF entry point 2477 is the Target Resource URI 2478 is the query parameter list 2479 is not used in RESTCONF 2481 o method: the HTTP method identifying the RESTCONF operation 2482 requested by the client, to act upon the target resource specified 2483 in the request URI. RESTCONF operation details are described in 2484 Section 4. 2486 o entry: the root of the RESTCONF API configured on this HTTP 2487 server, discovered by getting the "/.well-known/host-meta" 2488 resource, as described in Section 3.1. 2490 o resource: the path expression identifying the resource that is 2491 being accessed by the operation. If this field is not present, 2492 then the target resource is the API itself, represented by the 2493 YANG data template named "yang-api", found in Section 8. 2495 o query: the set of parameters associated with the RESTCONF message, 2496 as defined in section 3.4 of [RFC3986]. RESTCONF parameters have 2497 the familiar form of "name=value" pairs. Most query parameters 2498 are optional to implement by the server and optional to use by the 2499 client. Each optional query parameter is identified by a URI. 2500 The server MUST list the optional query parameter URIs it supports 2501 in the "capabilities" list defined in Section 9.3. 2503 There is a specific set of parameters defined, although the server 2504 MAY choose to support query parameters not defined in this document. 2505 The contents of the any query parameter value MUST be encoded 2506 according to [RFC3986], Section 3.4. Any reserved characters MUST be 2507 percent-encoded, according to [RFC3986], section 2.1. 2509 o fragment: This field is not used by the RESTCONF protocol. 2511 When new resources are created by the client, a "Location" header is 2512 returned, which identifies the path of the newly created resource. 2513 The client uses this exact path identifier to access the resource 2514 once it has been created. 2516 The "target" of an operation is a resource. The "path" field in the 2517 request URI represents the target resource for the operation. 2519 Refer to Appendix D for examples of RESTCONF Request URIs. 2521 5.2. Message Encoding 2523 RESTCONF messages are encoded in HTTP according to [RFC7230]. The 2524 "utf-8" character set is used for all messages. RESTCONF message 2525 content is sent in the HTTP message-body. 2527 Content is encoded in either JSON or XML format. A server MUST 2528 support XML or JSON encoding. XML encoding rules for data nodes are 2529 defined in [I-D.ietf-netmod-rfc6020bis]. The same encoding rules are 2530 used for all XML content. JSON encoding rules are defined in 2531 [I-D.ietf-netmod-yang-json]. JSON encoding of metadata is defined in 2532 [I-D.ietf-netmod-yang-metadata]. This encoding is valid JSON, but 2533 also has special encoding rules to identify module namespaces and 2534 provide consistent type processing of YANG data. 2536 Request input content encoding format is identified with the Content- 2537 Type header. This field MUST be present if a message-body is sent by 2538 the client. 2540 The server MUST support the "Accept" header and "406 Not Acceptable" 2541 status-line, as defined in [RFC7231]. Response output content 2542 encoding format is identified with the Accept header in the request. 2543 If it is not specified, the request input encoding format SHOULD be 2544 used, or the server MAY choose any supported content encoding format. 2546 If there was no request input, then the default output encoding is 2547 XML or JSON, depending on server preference. File extensions encoded 2548 in the request are not used to identify format encoding. 2550 A client can determine if the RESTCONF server supports an encoding 2551 format by sending a request using a specific format in the Content- 2552 Type and/or Accept header. If the server does not support the 2553 requested input encoding for a request, then it MUST return an error 2554 response with a '415 Unsupported Media Type' status-line. If the 2555 server does not support any of the requested output encodings for a 2556 request, then it MUST return an error response with a '406 Not 2557 Acceptable' status-line. 2559 5.3. RESTCONF Metadata 2561 The RESTCONF protocol needs to retrieve the same metadata that is 2562 used in the NETCONF protocol. Information about default leafs, last- 2563 modified timestamps, etc. are commonly used to annotate 2564 representations of the datastore contents. 2566 With the XML encoding, the metadata is encoded as attributes in XML. 2567 With the JSON encoding, the metadata is encoded as specified in 2568 [I-D.ietf-netmod-yang-metadata]. 2570 The following examples are based on the example in Appendix D.3.9. 2571 The "report-all-tagged" mode for the "with-defaults" query parameter 2572 requires that a "default" attribute be returned for default nodes. 2573 This example shows that attribute for the "mtu" leaf . 2575 5.3.1. XML MetaData Encoding Example 2577 GET /restconf/data/interfaces/interface=eth1 2578 ?with-defaults=report-all-tagged HTTP/1.1 2579 Host: example.com 2580 Accept: application/yang-data+xml 2582 The server might respond as follows. 2584 HTTP/1.1 200 OK 2585 Date: Mon, 23 Apr 2012 17:01:00 GMT 2586 Server: example-server 2587 Content-Type: application/yang-data+xml 2589 2591 eth1 2592 1500 2594 up 2595 2597 5.3.2. JSON MetaData Encoding Example 2599 Note that RFC 6243 defines the "default" attribute with XSD, not 2600 YANG, so the YANG module name has to be assigned manually. The value 2601 "ietf-netconf-with-defaults" is assigned for JSON metadata encoding. 2603 GET /restconf/data/interfaces/interface=eth1 2604 ?with-defaults=report-all-tagged HTTP/1.1 2605 Host: example.com 2606 Accept: application/yang-data+json 2608 The server might respond as follows. 2610 HTTP/1.1 200 OK 2611 Date: Mon, 23 Apr 2012 17:01:00 GMT 2612 Server: example-server 2613 Content-Type: application/yang-data+json 2615 { 2616 "example:interface": [ 2617 { 2618 "name" : "eth1", 2619 "mtu" : 1500, 2620 "@mtu": { 2621 "ietf-netconf-with-defaults:default" : true 2622 }, 2623 "status" : "up" 2624 } 2625 ] 2626 } 2628 5.4. Return Status 2630 Each message represents some sort of resource access. An HTTP 2631 "status-line" header line is returned for each request. If a "4xx" 2632 range status code is returned in the status-line, then the error 2633 information SHOULD be returned in the response, according to the 2634 format defined in Section 7.1. If a "5xx" range status code is 2635 returned in the status-line, then the error information MAY be 2636 returned in the response, according to the format defined in 2637 Section 7.1. If a 1xx, 2xx, or 3xx range status code is returned in 2638 the status-line, then error information MUST NOT be returned in the 2639 response, since these ranges do not represent error conditions. 2641 5.5. Message Caching 2643 Since the datastore contents change at unpredictable times, responses 2644 from a RESTCONF server generally SHOULD NOT be cached. 2646 The server SHOULD include a "Cache-Control" header in every response 2647 that specifies whether the response should be cached. 2649 Instead of relying on HTTP caching, the client SHOULD track the 2650 "ETag" and/or "Last-Modified" headers returned by the server for the 2651 datastore resource (or data resource if the server supports it). A 2652 retrieval request for a resource can include the "If-None-Match" and/ 2653 or "If-Modified-Since" headers, which will cause the server to return 2654 a "304 Not Modified" status-line if the resource has not changed. 2655 The client MAY use the HEAD method to retrieve just the message 2656 headers, which SHOULD include the "ETag" and "Last-Modified" headers, 2657 if this metadata is maintained for the target resource. 2659 6. Notifications 2661 The RESTCONF protocol supports YANG-defined event notifications. The 2662 solution preserves aspects of NETCONF Event Notifications [RFC5277] 2663 while utilizing the Server-Sent Events [W3C.REC-eventsource-20150203] 2664 transport strategy. 2666 6.1. Server Support 2668 A RESTCONF server MAY support RESTCONF notifications. Clients may 2669 determine if a server supports RESTCONF notifications by using the 2670 HTTP operation OPTIONS, HEAD, or GET on the stream list. The server 2671 does not support RESTCONF notifications if an HTTP error code is 2672 returned (e.g., "404 Not Found" status-line). 2674 6.2. Event Streams 2676 A RESTCONF server that supports notifications will populate a stream 2677 resource for each notification delivery service access point. A 2678 RESTCONF client can retrieve the list of supported event streams from 2679 a RESTCONF server using the GET operation on the stream list. 2681 The "restconf-state/streams" container definition in the 2682 "ietf-restconf-monitoring" module (defined in Section 9.3) is used to 2683 specify the structure and syntax of the conceptual child resources 2684 within the "streams" resource. 2686 For example: 2688 The client might send the following request: 2690 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2691 streams HTTP/1.1 2692 Host: example.com 2693 Accept: application/yang-data+xml 2694 The server might send the following response: 2696 HTTP/1.1 200 OK 2697 Content-Type: application/yang-data+xml 2699 2701 2702 NETCONF 2703 default NETCONF event stream 2704 2705 true 2706 2707 2007-07-08T00:00:00Z 2708 2709 2710 xml 2711 https://example.com/streams/NETCONF 2712 2713 2714 2715 json 2716 https://example.com/streams/NETCONF-JSON 2717 2718 2719 2720 2721 SNMP 2722 SNMP notifications 2723 false 2724 2725 xml 2726 https://example.com/streams/SNMP 2727 2728 2729 2730 syslog-critical 2731 Critical and higher severity 2732 2733 true 2734 2735 2007-07-01T00:00:00Z 2736 2737 2738 xml 2739 2740 https://example.com/streams/syslog-critical 2741 2743 2744 2745 2747 6.3. Subscribing to Receive Notifications 2749 RESTCONF clients can determine the URL for the subscription resource 2750 (to receive notifications) by sending an HTTP GET request for the 2751 "location" leaf with the stream list entry. The value returned by 2752 the server can be used for the actual notification subscription. 2754 The client will send an HTTP GET request for the URL returned by the 2755 server with the "Accept" type "text/event-stream". 2757 The server will treat the connection as an event stream, using the 2758 Server Sent Events [W3C.REC-eventsource-20150203] transport strategy. 2760 The server MAY support query parameters for a GET method on this 2761 resource. These parameters are specific to each notification stream. 2763 For example: 2765 The client might send the following request: 2767 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 2768 streams/stream=NETCONF/access=xml/location HTTP/1.1 2769 Host: example.com 2770 Accept: application/yang-data+xml 2772 The server might send the following response: 2774 HTTP/1.1 200 OK 2775 Content-Type: application/yang-data+xml 2777 2779 https://example.com/streams/NETCONF 2780 2782 The RESTCONF client can then use this URL value to start monitoring 2783 the event stream: 2785 GET /streams/NETCONF HTTP/1.1 2786 Host: example.com 2787 Accept: text/event-stream 2788 Cache-Control: no-cache 2789 Connection: keep-alive 2790 A RESTCONF client MAY request that the server compress the events 2791 using the HTTP header field "Accept-Encoding". For instance: 2793 GET /streams/NETCONF HTTP/1.1 2794 Host: example.com 2795 Accept: text/event-stream 2796 Cache-Control: no-cache 2797 Connection: keep-alive 2798 Accept-Encoding: gzip, deflate 2800 6.3.1. NETCONF Event Stream 2802 The server SHOULD support the "NETCONF" notification stream defined 2803 in [RFC5277]. For this stream, RESTCONF notification subscription 2804 requests MAY specify parameters indicating the events it wishes to 2805 receive. These query parameters are optional to implement, and only 2806 available if the server supports them. 2808 +------------+---------+-------------------------+ 2809 | Name | Section | Description | 2810 +------------+---------+-------------------------+ 2811 | start-time | 4.8.7 | replay event start time | 2812 | stop-time | 4.8.8 | replay event stop time | 2813 | filter | 4.8.4 | boolean content filter | 2814 +------------+---------+-------------------------+ 2816 NETCONF Stream Query Parameters 2818 The semantics and syntax for these query parameters are defined in 2819 the sections listed above. The YANG definition MUST be converted to 2820 a URI-encoded string for use in the request URI. 2822 Refer to Appendix D.3.6 for filter parameter examples. 2824 6.4. Receiving Event Notifications 2826 RESTCONF notifications are encoded according to the definition of the 2827 event stream. The NETCONF stream defined in [RFC5277] is encoded in 2828 XML format. 2830 The structure of the event data is based on the "notification" 2831 element definition in Section 4 of [RFC5277]. It MUST conform to the 2832 schema for the "notification" element in Section 4 of [RFC5277], 2833 except the XML namespace for this element is defined as: 2835 urn:ietf:params:xml:ns:yang:ietf-restconf 2836 For JSON encoding purposes, the module name for the "notification" 2837 element is "ietf-restconf". 2839 Two child nodes within the "notification" container are expected, 2840 representing the event time and the event payload. The "event-time" 2841 node is defined within the "ietf-restconf" module namespace. The 2842 name and namespace of the payload element are determined by the YANG 2843 module containing the notification-stmt. 2845 In the following example, the YANG module "example-mod" is used: 2847 module example-mod { 2848 namespace "http://example.com/event/1.0"; 2849 prefix ex; 2851 notification event { 2852 leaf event-class { type string; } 2853 container reporting-entity { 2854 leaf card { type string; } 2855 } 2856 leaf severity { type string; } 2857 } 2858 } 2860 An example SSE event notification encoded using XML: 2862 data: 2864 data: 2013-12-21T00:01:00Z 2865 data: 2866 data: fault 2867 data: 2868 data: Ethernet0 2869 data: 2870 data: major 2871 data: 2872 data: 2874 An example SSE event notification encoded using JSON: 2876 data: { 2877 data: "ietf-restconf:notification": { 2878 data: "event-time": "2013-12-21T00:01:00Z", 2879 data: "example-mod:event": { 2880 data: "event-class": "fault", 2881 data: "reporting-entity": { "card": "Ethernet0" }, 2882 data: "severity": "major" 2883 data: } 2884 data: } 2885 data: } 2887 Alternatively, since neither XML nor JSON are whitespace sensitive, 2888 the above messages can be encoded onto a single line. For example: 2890 For example: ('\' line wrapping added for formatting only) 2892 XML: 2894 data: 2013-12-21T00:01:00ZfaultEthernet0\ 2898 major 2900 JSON: 2902 data: {"ietf-restconf:notification":{"event-time":"2013-12-21\ 2903 T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ 2904 tingEntity":{"card":"Ethernet0"},"severity":"major"}}} 2906 The SSE specifications supports the following additional fields: 2907 event, id and retry. A RESTCONF server MAY send the "retry" field 2908 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 2909 SHOULD NOT send the "event" or "id" fields, as there are no 2910 meaningful values that could be used for them that would not be 2911 redundant to the contents of the notification itself. RESTCONF 2912 servers that do not send the "id" field also do not need to support 2913 the HTTP header "Last-Event-Id". RESTCONF servers that do send the 2914 "id" field MUST still support the "startTime" query parameter as the 2915 preferred means for a client to specify where to restart the event 2916 stream. 2918 7. Error Reporting 2920 HTTP status codes are used to report success or failure for RESTCONF 2921 operations. The element returned in NETCONF error 2922 responses contains some useful information. This error information 2923 is adapted for use in RESTCONF, and error information is returned for 2924 "4xx" and "5xx" class of status codes. 2926 Since an operation resource is defined with a YANG "rpc" statement, 2927 and an action is defined with a YANG "action" statement, a mapping 2928 between the NETCONF value and the HTTP status code is 2929 needed. The specific error-tag and response code to use are data- 2930 model specific and might be contained in the YANG "description" 2931 statement for the "action" or "rpc" statement. 2933 +-------------------------+-------------+ 2934 | error-tag | status code | 2935 +-------------------------+-------------+ 2936 | in-use | 409 | 2937 | invalid-value | 400 | 2938 | (request) too-big | 413 | 2939 | (response) too-big | 400 | 2940 | missing-attribute | 400 | 2941 | bad-attribute | 400 | 2942 | unknown-attribute | 400 | 2943 | bad-element | 400 | 2944 | unknown-element | 400 | 2945 | unknown-namespace | 400 | 2946 | access-denied | 403 | 2947 | lock-denied | 409 | 2948 | resource-denied | 409 | 2949 | rollback-failed | 500 | 2950 | data-exists | 409 | 2951 | data-missing | 409 | 2952 | operation-not-supported | 501 | 2953 | operation-failed | 500 | 2954 | partial-operation | 500 | 2955 | malformed-message | 400 | 2956 +-------------------------+-------------+ 2958 Mapping from error-tag to status code 2960 7.1. Error Response Message 2962 When an error occurs for a request message on any resource type, and 2963 the status code that will be returned is in the "4xx" range (except 2964 for status code "403 Forbidden"), then the server SHOULD send a 2965 response message-body containing the information described by the 2966 "yang-errors" YANG template definition within the "ietf-restconf" 2967 module, found in Section 8. The Content-Type of this response 2968 message MUST be a subtype of application/yang-data (see example 2969 below). 2971 The client SHOULD specify the desired encoding for error messages by 2972 specifying the appropriate media-type in the Accept header. If no 2973 error media is specified, then the media subtype (e.g., XML or JSON) 2974 of the request message SHOULD be used, or the server MAY choose any 2975 supported message encoding format. If there is no request message 2976 the server MUST select "application/yang-data+xml" or "application/ 2977 yang-data+json", depending on server preference. All of the examples 2978 in this document, except for the one below, assume that XML encoding 2979 will be returned if there is an error. 2981 YANG Tree Diagram for data: 2983 +--ro errors 2984 +--ro error* 2985 +--ro error-type enumeration 2986 +--ro error-tag string 2987 +--ro error-app-tag? string 2988 +--ro error-path? instance-identifier 2989 +--ro error-message? string 2990 +--ro error-info 2992 The semantics and syntax for RESTCONF error messages are defined with 2993 the "yang-errors" YANG data template extension, found in Section 8. 2995 Examples: 2997 The following example shows an error returned for an "lock-denied" 2998 error that can occur if a NETCONF client has locked a datastore. The 2999 RESTCONF client is attempting to delete a data resource. Note that 3000 an Accept header is used to specify the desired encoding for the 3001 error message. No response message-body content is expected by the 3002 client in this example. 3004 DELETE /restconf/data/example-jukebox:jukebox/ 3005 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 3006 Host: example.com 3007 Accept: application/yang-data+json 3009 The server might respond: 3011 HTTP/1.1 409 Conflict 3012 Date: Mon, 23 Apr 2012 17:11:00 GMT 3013 Server: example-server 3014 Content-Type: application/yang-data+json 3016 { 3017 "ietf-restconf:errors": { 3018 "error": [ 3019 { 3020 "error-type": "protocol", 3021 "error-tag": "lock-denied", 3022 "error-message": "Lock failed, lock already held" 3023 } 3024 ] 3025 } 3026 } 3028 The following example shows an error returned for a "data-exists" 3029 error on a data resource. The "jukebox" resource already exists so 3030 it cannot be created. 3032 The client might send: 3034 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 3035 Host: example.com 3037 The server might respond (some lines wrapped for display purposes): 3039 HTTP/1.1 409 Conflict 3040 Date: Mon, 23 Apr 2012 17:11:00 GMT 3041 Server: example-server 3042 Content-Type: application/yang-data+xml 3044 3045 3046 protocol 3047 data-exists 3048 3051 /rc:restconf/rc:data/jbox:jukebox 3052 3053 3054 Data already exists, cannot create new resource 3055 3056 3057 3059 8. RESTCONF module 3061 The "ietf-restconf" module defines conceptual definitions within an 3062 extension and two groupings, which are not meant to be implemented as 3063 datastore contents by a server. E.g., the "restconf" container is 3064 not intended to be implemented as a top-level data node (under the "/ 3065 restconf/data" entry point). 3067 Note that the "ietf-restconf" module does not have any protocol- 3068 accessible objects, so no YANG tree diagram is shown. 3070 RFC Ed.: update the date below with the date of RFC publication and 3071 remove this note. 3073 file "ietf-restconf@2016-06-28.yang" 3075 module ietf-restconf { 3076 yang-version 1.1; 3077 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 3078 prefix "rc"; 3080 organization 3081 "IETF NETCONF (Network Configuration) Working Group"; 3083 contact 3084 "WG Web: 3085 WG List: 3087 WG Chair: Mehmet Ersue 3088 3090 WG Chair: Mahesh Jethanandani 3091 3093 Editor: Andy Bierman 3094 3096 Editor: Martin Bjorklund 3097 3099 Editor: Kent Watsen 3100 "; 3102 description 3103 "This module contains conceptual YANG specifications 3104 for basic RESTCONF media type definitions used in 3105 RESTCONF protocol messages. 3107 Note that the YANG definitions within this module do not 3108 represent configuration data of any kind. 3109 The 'restconf-media-type' YANG extension statement 3110 provides a normative syntax for XML and JSON message 3111 encoding purposes. 3113 Copyright (c) 2016 IETF Trust and the persons identified as 3114 authors of the code. All rights reserved. 3116 Redistribution and use in source and binary forms, with or 3117 without modification, is permitted pursuant to, and subject 3118 to the license terms contained in, the Simplified BSD License 3119 set forth in Section 4.c of the IETF Trust's Legal Provisions 3120 Relating to IETF Documents 3121 (http://trustee.ietf.org/license-info). 3123 This version of this YANG module is part of RFC XXXX; see 3124 the RFC itself for full legal notices."; 3126 // RFC Ed.: replace XXXX with actual RFC number and remove this 3127 // note. 3129 // RFC Ed.: remove this note 3130 // Note: extracted from draft-ietf-netconf-restconf-14.txt 3132 // RFC Ed.: update the date below with the date of RFC publication 3133 // and remove this note. 3134 revision 2016-06-28 { 3135 description 3136 "Initial revision."; 3137 reference 3138 "RFC XXXX: RESTCONF Protocol."; 3139 } 3141 extension yang-data { 3142 argument name { 3143 yin-element true; 3144 } 3145 description 3146 "This extension is used to specify a YANG data template which 3147 represents conceptual data defined in YANG. It is 3148 intended to describe hierarchical data independent of 3149 protocol context or specific message encoding format. 3150 Data definition statements within this extension specify 3151 the generic syntax for the specific YANG data template. 3153 Note that this extension does not define a media-type. 3154 A specification using this extension MUST specify the 3155 message encoding rules, including the content media type. 3157 The mandatory 'name' parameter value identifies the YANG 3158 data template that is being defined. It contains the 3159 template name. 3161 This extension is ignored unless it appears as a top-level 3162 statement. It SHOULD contain data definition statements 3163 that result in exactly one container data node definition. 3164 This allows compliant translation to an XML instance 3165 document for each YANG data template. 3167 The module name and namespace value for the YANG module using 3168 the extension statement is assigned to instance document data 3169 conforming to the data definition statements within 3170 this extension. 3172 The sub-statements of this extension MUST follow the 3173 'data-def-stmt' rule in the YANG ABNF. 3175 The XPath document root is the extension statement itself, 3176 such that the child nodes of the document root are 3177 represented by the data-def-stmt sub-statements within 3178 this extension. This conceptual document is the context 3179 for the following YANG statements: 3181 - must-stmt 3182 - when-stmt 3183 - path-stmt 3184 - min-elements-stmt 3185 - max-elements-stmt 3186 - mandatory-stmt 3187 - unique-stmt 3188 - ordered-by 3189 - instance-identifier data type 3191 The following data-def-stmt sub-statements have special 3192 meaning when used within a yang-data-resource extension 3193 statement. 3195 - The list-stmt is not required to have a key-stmt defined. 3196 - The if-feature-stmt is ignored if present. 3197 - The config-stmt is ignored if present. 3198 - The available identity values for any 'identityref' 3199 leaf or leaf-list nodes is limited to the module 3200 containing this extension statement, and the modules 3201 imported into that module. 3202 "; 3203 } 3205 rc:yang-data yang-errors { 3206 uses errors; 3207 } 3209 rc:yang-data yang-api { 3210 uses restconf; 3211 } 3213 grouping errors { 3214 description 3215 "A grouping that contains a YANG container 3216 representing the syntax and semantics of a 3217 YANG Patch errors report within a response message."; 3219 container errors { 3220 description 3221 "Represents an error report returned by the server if 3222 a request results in an error."; 3224 list error { 3225 description 3226 "An entry containing information about one 3227 specific error that occurred while processing 3228 a RESTCONF request."; 3229 reference "RFC 6241, Section 4.3"; 3231 leaf error-type { 3232 type enumeration { 3233 enum transport { 3234 description "The transport layer"; 3235 } 3236 enum rpc { 3237 description "The rpc or notification layer"; 3238 } 3239 enum protocol { 3240 description "The protocol operation layer"; 3241 } 3242 enum application { 3243 description "The server application layer"; 3244 } 3245 } 3246 mandatory true; 3247 description 3248 "The protocol layer where the error occurred."; 3249 } 3251 leaf error-tag { 3252 type string; 3253 mandatory true; 3254 description 3255 "The enumerated error tag."; 3256 } 3258 leaf error-app-tag { 3259 type string; 3260 description 3261 "The application-specific error tag."; 3262 } 3264 leaf error-path { 3265 type instance-identifier; 3266 description 3267 "The YANG instance identifier associated 3268 with the error node."; 3269 } 3271 leaf error-message { 3272 type string; 3273 description 3274 "A message describing the error."; 3275 } 3277 anydata error-info { 3278 description 3279 "This anydata value MUST represent a container with 3280 zero or more data nodes representing additional 3281 error information."; 3282 } 3283 } 3284 } 3285 } 3287 grouping restconf { 3288 description 3289 "Conceptual container representing the 3290 application/yang-api resource type."; 3292 container restconf { 3293 description 3294 "Conceptual container representing the 3295 application/yang-api resource type."; 3297 container data { 3298 description 3299 "Container representing the application/yang-datastore 3300 resource type. Represents the conceptual root of all 3301 state data and configuration data supported by 3302 the server. The child nodes of this container can be 3303 any data resource (application/yang-data), which are 3304 defined as top-level data nodes from the YANG modules 3305 advertised by the server in the ietf-restconf-monitoring 3306 module."; 3307 } 3309 container operations { 3310 description 3311 "Container for all operation resources 3312 (application/yang-operation), 3314 Each resource is represented as an empty leaf with the 3315 name of the RPC operation from the YANG rpc statement. 3317 For example, the 'system-restart' RPC operation defined 3318 in the 'ietf-system' module would be represented as 3319 an empty leaf in the 'ietf-system' namespace. This is 3320 a conceptual leaf, and will not actually be found in 3321 the module: 3323 module ietf-system { 3324 leaf system-reset { 3325 type empty; 3326 } 3327 } 3329 To invoke the 'system-restart' RPC operation: 3331 POST /restconf/operations/ietf-system:system-restart 3333 To discover the RPC operations supported by the server: 3335 GET /restconf/operations 3337 In XML the YANG module namespace identifies the module: 3339 3342 In JSON the YANG module name identifies the module: 3344 { 'ietf-system:system-restart' : [null] } 3346 "; 3347 } 3349 leaf yang-library-version { 3350 type string { 3351 pattern '\d{4}-\d{2}-\d{2}'; 3352 } 3353 config false; 3354 mandatory true; 3355 description 3356 "Identifies the revision date of the ietf-yang-library 3357 module that is implemented by this RESTCONF server. 3358 Indicates the year, month, and day in YYYY-MM-DD 3359 numeric format."; 3360 } 3361 } 3362 } 3364 } 3365 3367 9. RESTCONF Monitoring 3369 The "ietf-restconf-monitoring" module provides information about the 3370 RESTCONF protocol capabilities and event notification streams 3371 available from the server. A RESTCONF server MUST implement the "/ 3372 restconf-state/capabilities" container in this module. 3374 YANG Tree Diagram for "ietf-restconf-monitoring" module: 3376 +--ro restconf-state 3377 +--ro capabilities 3378 | +--ro capability* inet:uri 3379 +--ro streams 3380 +--ro stream* [name] 3381 +--ro name string 3382 +--ro description? string 3383 +--ro replay-support? boolean 3384 +--ro replay-log-creation-time? yang:date-and-time 3385 +--ro access* [encoding] 3386 +--ro encoding string 3387 +--ro location inet:uri 3389 9.1. restconf-state/capabilities 3391 This mandatory container holds the RESTCONF protocol capability URIs 3392 supported by the server. 3394 The server MAY maintain a last-modified timestamp for this container, 3395 and return the "Last-Modified" header when this data node is 3396 retrieved with the GET or HEAD methods. Note that the last-modified 3397 timestamp for the datastore resource is not affected by changes this 3398 subtree. 3400 The server SHOULD maintain an entity-tag for this container, and 3401 return the "ETag" header when this data node is retrieved with the 3402 GET or HEAD methods. Note that the entity-tag for the datastore 3403 resource is not affected by changes this subtree. 3405 The server MUST include a "capability" URI leaf-list entry for the 3406 "defaults" mode used by the server, defined in Section 9.1.2. 3408 The server MUST include a "capability" URI leaf-list entry 3409 identifying each supported optional protocol feature. This includes 3410 optional query parameters and MAY include other capability URIs 3411 defined outside this document. 3413 9.1.1. Query Parameter URIs 3415 A new set of RESTCONF Capability URIs are defined to identify the 3416 specific query parameters (defined in Section 4.8) supported by the 3417 server. 3419 The server MUST include a "capability" leaf-list entry for each 3420 optional query parameter that it supports. 3422 +-------------+-------+---------------------------------------------+ 3423 | Name | Secti | URI | 3424 | | on | | 3425 +-------------+-------+---------------------------------------------+ 3426 | depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 | 3427 | | | .0 | 3428 | fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: | 3429 | | | 1.0 | 3430 | filter | 4.8.4 | urn:ietf:params:restconf:capability:filter: | 3431 | | | 1.0 | 3432 | replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: | 3433 | | 4.8.8 | 1.0 | 3434 | with- | 4.8.9 | urn:ietf:params:restconf:capability:with- | 3435 | defaults | | defaults:1.0 | 3436 +-------------+-------+---------------------------------------------+ 3438 RESTCONF Query Parameter URIs 3440 9.1.2. The "defaults" Protocol Capability URI 3442 This URI identifies the defaults handling mode that is used by the 3443 server for processing default leafs in requests for data resources. 3444 A parameter named "basic-mode" is required for this capability URI. 3445 The "basic-mode" definitions are specified in the "With-Defaults 3446 Capability for NETCONF" [RFC6243]. 3448 +----------+--------------------------------------------------+ 3449 | Name | URI | 3450 +----------+--------------------------------------------------+ 3451 | defaults | urn:ietf:params:restconf:capability:defaults:1.0 | 3452 +----------+--------------------------------------------------+ 3454 RESTCONF defaults capability URI 3456 This protocol capability URI MUST be supported by the server, and 3457 MUST be listed in the "capability" leaf-list in Section 9.3. 3459 +------------------+------------------------------------------------+ 3460 | Value | Description | 3461 +------------------+------------------------------------------------+ 3462 | report-all | No data nodes are considered default | 3463 | trim | Values set to the YANG default-stmt value are | 3464 | | default | 3465 | explicit | Values set by the client are never considered | 3466 | | default | 3467 +------------------+------------------------------------------------+ 3469 If the "basic-mode" is set to "report-all" then the server MUST 3470 adhere to the defaults handling behavior defined in Section 2.1 of 3471 [RFC6243]. 3473 If the "basic-mode" is set to "trim" then the server MUST adhere to 3474 the defaults handling behavior defined in Section 2.2 of [RFC6243]. 3476 If the "basic-mode" is set to "explicit" then the server MUST adhere 3477 to the defaults handling behavior defined in Section 2.3 of 3478 [RFC6243]. 3480 Example: (split for display purposes only) 3482 urn:ietf:params:restconf:capability:defaults:1.0? 3483 basic-mode=explicit 3485 9.2. restconf-state/streams 3487 This optional container provides access to the event notification 3488 streams supported by the server. The server MAY omit this container 3489 if no event notification streams are supported. 3491 The server will populate this container with a stream list entry for 3492 each stream type it supports. Each stream contains a leaf called 3493 "events" which contains a URI that represents an event stream 3494 resource. 3496 Stream resources are defined in Section 3.8. Notifications are 3497 defined in Section 6. 3499 9.3. RESTCONF Monitoring Module 3501 The "ietf-restconf-monitoring" module defines monitoring information 3502 for the RESTCONF protocol. 3504 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 3505 are used by this module for some type definitions. 3507 RFC Ed.: update the date below with the date of RFC publication and 3508 remove this note. 3510 file "ietf-restconf-monitoring@2016-06-28.yang" 3512 module ietf-restconf-monitoring { 3513 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; 3514 prefix "rcmon"; 3516 import ietf-yang-types { prefix yang; } 3517 import ietf-inet-types { prefix inet; } 3519 organization 3520 "IETF NETCONF (Network Configuration) Working Group"; 3522 contact 3523 "WG Web: 3524 WG List: 3526 WG Chair: Mehmet Ersue 3527 3529 WG Chair: Mahesh Jethanandani 3530 3532 Editor: Andy Bierman 3533 3535 Editor: Martin Bjorklund 3536 3538 Editor: Kent Watsen 3539 "; 3541 description 3542 "This module contains monitoring information for the 3543 RESTCONF protocol. 3545 Copyright (c) 2016 IETF Trust and the persons identified as 3546 authors of the code. All rights reserved. 3548 Redistribution and use in source and binary forms, with or 3549 without modification, is permitted pursuant to, and subject 3550 to the license terms contained in, the Simplified BSD License 3551 set forth in Section 4.c of the IETF Trust's Legal Provisions 3552 Relating to IETF Documents 3553 (http://trustee.ietf.org/license-info). 3555 This version of this YANG module is part of RFC XXXX; see 3556 the RFC itself for full legal notices."; 3558 // RFC Ed.: replace XXXX with actual RFC number and remove this 3559 // note. 3561 // RFC Ed.: remove this note 3562 // Note: extracted from draft-ietf-netconf-restconf-14.txt 3564 // RFC Ed.: update the date below with the date of RFC publication 3565 // and remove this note. 3566 revision 2016-06-28 { 3567 description 3568 "Initial revision."; 3569 reference 3570 "RFC XXXX: RESTCONF Protocol."; 3571 } 3573 container restconf-state { 3574 config false; 3575 description 3576 "Contains RESTCONF protocol monitoring information."; 3578 container capabilities { 3579 description 3580 "Contains a list of protocol capability URIs"; 3582 leaf-list capability { 3583 type inet:uri; 3584 description "A RESTCONF protocol capability URI."; 3585 } 3586 } 3588 container streams { 3589 description 3590 "Container representing the notification event streams 3591 supported by the server."; 3592 reference 3593 "RFC 5277, Section 3.4, element."; 3595 list stream { 3596 key name; 3597 description 3598 "Each entry describes an event stream supported by 3599 the server."; 3601 leaf name { 3602 type string; 3603 description "The stream name"; 3604 reference "RFC 5277, Section 3.4, element."; 3605 } 3606 leaf description { 3607 type string; 3608 description "Description of stream content"; 3609 reference 3610 "RFC 5277, Section 3.4, element."; 3611 } 3613 leaf replay-support { 3614 type boolean; 3615 description 3616 "Indicates if replay buffer supported for this stream. 3617 If 'true', then the server MUST support the 'start-time' 3618 and 'stop-time' query parameters for this stream."; 3619 reference 3620 "RFC 5277, Section 3.4, element."; 3621 } 3623 leaf replay-log-creation-time { 3624 when "../replay-support" { 3625 description 3626 "Only present if notification replay is supported"; 3627 } 3628 type yang:date-and-time; 3629 description 3630 "Indicates the time the replay log for this stream 3631 was created."; 3632 reference 3633 "RFC 5277, Section 3.4, 3634 element."; 3635 } 3637 list access { 3638 key encoding; 3639 min-elements 1; 3640 description 3641 "The server will create an entry in this list for each 3642 encoding format that is supported for this stream. 3643 The media type 'application/yang-stream' is expected 3644 for all event streams. This list identifies the 3645 sub-types supported for this stream."; 3647 leaf encoding { 3648 type string; 3649 description 3650 "This is the secondary encoding format within the 3651 'text/event-stream' encoding used by all streams. 3652 The type 'xml' is supported for the media type 3653 'application/yang-stream+xml'. The type 'json' 3654 is supported for the media type 3655 'application/yang-stream+json'."; 3657 } 3659 leaf location { 3660 type inet:uri; 3661 mandatory true; 3662 description 3663 "Contains a URL that represents the entry point 3664 for establishing notification delivery via server 3665 sent events."; 3666 } 3667 } 3668 } 3669 } 3670 } 3672 } 3674 3676 10. YANG Module Library 3678 The "ietf-yang-library" module defined in 3679 [I-D.ietf-netconf-yang-library] provides information about the YANG 3680 modules and submodules used by the RESTCONF server. Implementation 3681 is mandatory for RESTCONF servers. All YANG modules and submodules 3682 used by the server MUST be identified in the YANG module library. 3684 10.1. modules-state 3686 This mandatory container holds the identifiers for the YANG data 3687 model modules supported by the server. 3689 10.1.1. modules-state/module 3691 This mandatory list contains one entry for each YANG data model 3692 module supported by the server. There MUST be an instance of this 3693 list for every YANG module that is used by the server. 3695 The contents of this list are defined in the "module" YANG list 3696 statement in [I-D.ietf-netconf-yang-library]. 3698 11. IANA Considerations 3700 11.1. The "restconf" Relation Type 3701 This specification registers the "restconf" relation type in the Link 3702 Relation Type Registry defined by [RFC5988]: 3704 Relation Name: restconf 3706 Description: Identifies the root of RESTCONF API as configured 3707 on this HTTP server. The "restconf" relation 3708 defines the root of the API defined in RFCXXXX. 3709 Subsequent revisions of RESTCONF will use alternate 3710 relation values to support protocol versioning. 3712 Reference: RFCXXXX 3714 ` 3716 11.2. YANG Module Registry 3718 This document registers two URIs as namesapces in the IETF XML 3719 registry [RFC3688]. Following the format in RFC 3688, the following 3720 registration is requested: 3722 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 3723 Registrant Contact: The NETMOD WG of the IETF. 3724 XML: N/A, the requested URI is an XML namespace. 3726 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3727 Registrant Contact: The NETMOD WG of the IETF. 3728 XML: N/A, the requested URI is an XML namespace. 3730 This document registers two YANG modules in the YANG Module Names 3731 registry [RFC6020]: 3733 name: ietf-restconf 3734 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3735 prefix: rc 3736 // RFC Ed.: replace XXXX with RFC number and remove this note 3737 reference: RFCXXXX 3739 name: ietf-restconf-monitoring 3740 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3741 prefix: rcmon 3742 // RFC Ed.: replace XXXX with RFC number and remove this note 3743 reference: RFCXXXX 3745 11.3. Media Types 3747 11.3.1. Media Type application/yang-data+xml 3748 Type name: application 3750 Subtype name: yang-data+xml 3752 Required parameters: none 3754 Optional parameters: none 3756 // RFC Ed.: replace draft-ietf-netmod-rfc6020bis with 3757 // the actual RFC reference for YANG 1.1, and remove this note. 3759 Encoding considerations: 8-bit 3760 Each conceptual YANG data node is encoded according to 3761 XML Encoding Rules and Canonical Format for the specific 3762 YANG data node type defined in [draft-ietf-netmod-rfc6020bis]. 3764 // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the 3765 // section number for Security Considerations 3766 // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual 3767 // RFC number, and remove this note. 3769 Security considerations: Security considerations related 3770 to the generation and consumption of RESTCONF messages 3771 are discussed in Section NN of [RFCXXXX]. 3772 Additional security considerations are specific to the 3773 semantics of particular YANG data models. Each YANG module 3774 is expected to specify security considerations for the 3775 YANG data defined in that module. 3777 // RFC Ed.: replace XXXX with actual RFC number and remove this 3778 // note. 3780 Interoperability considerations: [RFCXXXX] specifies format of 3781 conforming messages and the interpretation thereof. 3783 // RFC Ed.: replace XXXX with actual RFC number and remove this 3784 // note. 3786 Published specification: RFC XXXX 3788 Applications that use this media type: Instance document 3789 data parsers used within a protocol or automation tool 3790 that utilizes YANG defined data structures. 3792 Fragment identifier considerations: The fragment field in the 3793 request URI has no defined purpose. 3795 Additional information: 3797 Deprecated alias names for this type: n/a 3798 Magic number(s): n/a 3799 File extension(s): .xml 3800 Macintosh file type code(s): "TEXT" 3802 // RFC Ed.: replace XXXX with actual RFC number and remove this 3803 // note. 3805 Person & email address to contact for further information: See 3806 Authors' Addresses section of [RFCXXXX]. 3808 Intended usage: COMMON 3810 (One of COMMON, LIMITED USE, or OBSOLETE.) 3812 Restrictions on usage: n/a 3814 // RFC Ed.: replace XXXX with actual RFC number and remove this 3815 // note. 3817 Author: See Authors' Addresses section of [RFCXXXX]. 3819 Change controller: Internet Engineering Task Force 3820 (mailto:iesg&ietf.org). 3822 Provisional registration? (standards tree only): no 3824 11.3.2. Media Type application/yang-data+json 3826 Type name: application 3828 Subtype name: yang-data+json 3830 Required parameters: none 3832 Optional parameters: none 3834 // RFC Ed.: replace draft-ietf-netmod-yang-json with 3835 // the actual RFC reference for JSON Encoding of YANG Data, 3836 // and remove this note. 3838 // RFC Ed.: replace draft-ietf-netmod-yang-metadata with 3839 // the actual RFC reference for JSON Encoding of YANG Data, 3840 // and remove this note. 3842 Encoding considerations: 8-bit 3843 Each conceptual YANG data node is encoded according to 3844 [draft-ietf-netmod-yang-json]. A data annotation is 3845 encoded according to [draft-ietf-netmod-yang-metadata] 3847 // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the 3848 // section number for Security Considerations 3849 // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual 3850 // RFC number, and remove this note. 3852 Security considerations: Security considerations related 3853 to the generation and consumption of RESTCONF messages 3854 are discussed in Section NN of [RFCXXXX]. 3855 Additional security considerations are specific to the 3856 semantics of particular YANG data models. Each YANG module 3857 is expected to specify security considerations for the 3858 YANG data defined in that module. 3860 // RFC Ed.: replace XXXX with actual RFC number and remove this 3861 // note. 3863 Interoperability considerations: [RFCXXXX] specifies format of 3864 conforming messages and the interpretation thereof. 3866 // RFC Ed.: replace XXXX with actual RFC number and remove this 3867 // note. 3869 Published specification: RFC XXXX 3871 Applications that use this media type: Instance document 3872 data parsers used within a protocol or automation tool 3873 that utilizes YANG defined data structures. 3875 Fragment identifier considerations: The fragment field in the 3876 request URI has no defined purpose. 3878 Additional information: 3880 Deprecated alias names for this type: n/a 3881 Magic number(s): n/a 3882 File extension(s): .json 3883 Macintosh file type code(s): "TEXT" 3885 // RFC Ed.: replace XXXX with actual RFC number and remove this 3886 // note. 3888 Person & email address to contact for further information: See 3889 Authors' Addresses section of [RFCXXXX]. 3891 Intended usage: COMMON 3892 (One of COMMON, LIMITED USE, or OBSOLETE.) 3894 Restrictions on usage: n/a 3896 // RFC Ed.: replace XXXX with actual RFC number and remove this 3897 // note. 3899 Author: See Authors' Addresses section of [RFCXXXX]. 3901 Change controller: Internet Engineering Task Force 3902 (mailto:iesg&ietf.org). 3904 Provisional registration? (standards tree only): no 3906 11.4. RESTCONF Capability URNs 3908 [Note to RFC Editor: 3909 The RESTCONF Protocol Capability Registry does not yet exist; 3910 Need to ask IANA to create it; remove this note for publication 3911 ] 3913 This document defines a registry for RESTCONF capability identifiers. 3914 The name of the registry is "RESTCONF Capability URNs". The review 3915 policy for this registry is "IETF Review". The registry shall record 3916 for each entry: 3918 o the name of the RESTCONF capability. By convention, this name 3919 begins with the colon ':' character. 3921 o the URN for the RESTCONF capability. 3923 This document registers several capability identifiers in "RESTCONF 3924 Capability URNs" registry: 3926 Index 3927 Capability Identifier 3928 ------------------------ 3930 :defaults 3931 urn:ietf:params:restconf:capability:defaults:1.0 3933 :depth 3934 urn:ietf:params:restconf:capability:depth:1.0 3936 :fields 3937 urn:ietf:params:restconf:capability:fields:1.0 3939 :filter 3940 urn:ietf:params:restconf:capability:filter:1.0 3942 :replay 3943 urn:ietf:params:restconf:capability:replay:1.0 3945 :with-defaults 3946 urn:ietf:params:restconf:capability:with-defaults:1.0 3948 12. Security Considerations 3950 The "ietf-restconf-monitoring" YANG module defined in this memo is 3951 designed to be accessed via the NETCONF protocol [RFC6241]. 3953 The lowest NETCONF layer is the secure transport layer, 3954 and the mandatory-to-implement secure transport is Secure Shell 3955 (SSH) ^RFC6242^. The NETCONF access control model ^RFC6536^ 3956 provides the means to restrict access for particular NETCONF users 3957 to a pre-configured subset of all available NETCONF protocol 3958 operations and content. 3960 This section provides security considerations for the resources 3961 defined by the RESTCONF protocol. Security considerations for HTTPS 3962 are defined in [RFC7230]. RESTCONF does not specify which YANG 3963 modules a server needs to support. Security considerations for the 3964 YANG-defined content manipulated by RESTCONF can be found in the 3965 documents defining those YANG modules. 3967 This document does not require use of a specific client 3968 authentication mechanism or authorization model, but it does require 3969 that a client authentication mechanism and authorization model is 3970 used whenever a client accesses a protected resource. Client 3971 authentication MUST be implemented using client certificates or MUST 3972 be implemented using an HTTP authentication scheme. Client 3973 authorization MAY be configured using the NETCONF Access Control 3974 Model (NACM) [RFC6536]. 3976 Configuration information is by its very nature sensitive. Its 3977 transmission in the clear and without integrity checking leaves 3978 devices open to classic eavesdropping and false data injection 3979 attacks. Configuration information often contains passwords, user 3980 names, service descriptions, and topological information, all of 3981 which are sensitive. Because of this, this protocol SHOULD be 3982 implemented carefully with adequate attention to all manner of attack 3983 one might expect to experience with other management interfaces. 3985 Different environments may well allow different rights prior to and 3986 then after authentication. When an operation is not properly 3987 authorized, the RESTCONF server MUST return a "401 Unauthorized" 3988 status-line. Note that authorization information can be exchanged in 3989 the form of configuration information, which is all the more reason 3990 to ensure the security of the connection. 3992 13. Acknowledgements 3994 The authors would like to thank the following people for their 3995 contributions to this document: Ladislav Lhotka, Juergen 3996 Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. 3998 The authors would like to thank the following people for their 3999 excellent technical reviews of this document: Mehmet Ersue, Mahesh 4000 Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka, 4001 Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint 4002 Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise, and 4003 Dale Worley. 4005 Contributions to this material by Andy Bierman are based upon work 4006 supported by the The Space & Terrestrial Communications Directorate 4007 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 4008 and conclusions or recommendations expressed in this material are 4009 those of the author(s) and do not necessarily reflect the views of 4010 The Space & Terrestrial Communications Directorate (S&TCD). 4012 14. References 4014 14.1. Normative References 4016 [I-D.ietf-netconf-yang-library] 4017 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 4018 Library", draft-ietf-netconf-yang-library-06 (work in 4019 progress), April 2016. 4021 [I-D.ietf-netmod-rfc6020bis] 4022 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 4023 draft-ietf-netmod-rfc6020bis-14 (work in progress), June 4024 2016. 4026 [I-D.ietf-netmod-yang-json] 4027 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 4028 draft-ietf-netmod-yang-json-10 (work in progress), March 4029 2016. 4031 [I-D.ietf-netmod-yang-metadata] 4032 Lhotka, L., "Defining and Using Metadata with YANG", 4033 draft-ietf-netmod-yang-metadata-07 (work in progress), 4034 March 2016. 4036 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4037 Extensions (MIME) Part Two: Media Types", RFC 2046, 4038 November 1996. 4040 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4041 Requirement Levels", BCP 14, RFC 2119, March 1997. 4043 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4044 January 2004. 4046 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4047 Resource Identifier (URI): Generic Syntax", STD 66, RFC 4048 3986, January 2005. 4050 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4051 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 4053 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 4054 Notifications", RFC 5277, July 2008. 4056 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4057 Housley, R., and T. Polk, "Internet X.509 Public Key 4058 Infrastructure Certificate and Certificate Revocation List 4059 (CRL) Profile", RFC 5280, May 2008. 4061 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 4062 5789, March 2010. 4064 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 4066 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 4067 Network Configuration Protocol (NETCONF)", RFC 6020, 4068 October 2010. 4070 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4071 Verification of Domain-Based Application Service Identity 4072 within Internet Public Key Infrastructure Using X.509 4073 (PKIX) Certificates in the Context of Transport Layer 4074 Security (TLS)", RFC 6125, March 2011. 4076 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 4077 and A. Bierman, Ed., "Network Configuration Protocol 4078 (NETCONF)", RFC 6241, June 2011. 4080 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 4081 NETCONF", RFC 6243, June 2011. 4083 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 4084 6415, October 2011. 4086 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 4087 Protocol (NETCONF) Access Control Model", RFC 6536, March 4088 2012. 4090 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 4091 and D. Orchard, "URI Template", RFC 6570, March 2012. 4093 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 4094 July 2013. 4096 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4097 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 4098 2014, . 4100 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4101 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 4102 2014. 4104 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4105 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 4107 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4108 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 4110 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4111 (HTTP/1.1): Authentication", RFC 7235, June 2014. 4113 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 4114 7320, July 2014. 4116 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 4117 NETCONF Protocol over Transport Layer Security (TLS) with 4118 Mutual X.509 Authentication", RFC 7589, DOI 10.17487/ 4119 RFC7589, June 2015, 4120 . 4122 [W3C.REC-eventsource-20150203] 4123 Hickson, I., "Server-Sent Events", World Wide Web 4124 Consortium Recommendation REC-eventsource-20150203, 4125 February 2015, 4126 . 4128 [W3C.REC-html5-20141028] 4129 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 4130 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", World 4131 Wide Web Consortium Recommendation REC-html5-20141028, 4132 October 2014, 4133 . 4135 [W3C.REC-xml-20081126] 4136 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 4137 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 4138 Edition)", World Wide Web Consortium Recommendation REC- 4139 xml-20081126, November 2008, 4140 . 4142 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 4143 Version 1.0", World Wide Web Consortium Recommendation 4144 REC-xpath-19991116, November 1999, 4145 . 4147 14.2. Informative References 4149 [I-D.ietf-netconf-yang-patch] 4150 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 4151 Media Type", draft-ietf-netconf-yang-patch-08 (work in 4152 progress), March 2016. 4154 [rest-dissertation] 4155 Fielding, R., "Architectural Styles and the Design of 4156 Network-based Software Architectures", 2000. 4158 Appendix A. Change Log 4160 -- RFC Ed.: remove this section before publication. 4162 The RESTCONF issue tracker can be found here: https://github.com/ 4163 netconf-wg/restconf/issues 4165 A.1. v13 - v14 4167 This release addresses github issues #61, #62, #63, #65, #66, and 4168 #67. 4170 o change term 'server' to 'NETCONF server' 4172 o add term 'RESTCONF server' also called 'server' 4174 o change term 'client' to 'NETCONF client' 4176 o add term 'RESTCONF client' also called 'client' 4178 o remove unused YANG terms 4179 o clarified operation resource and schema resource terms 4181 o clarified abstract and intro: RESTCONF uses NETCONF datastore 4182 concepts 4184 o removed term 'protocol operation'; use 'RPC operation' instead 4186 o clarified edit operation from NETCONF as nc:operation 4188 o clarified retrieval of an operation resource 4190 o remove ETag and Last-Modified requirements for /modules-state and 4191 /modules-state/module objects, since these are not configuration 4192 data nodes 4194 o clarified Last-Modified and ETag requirements for datastore and 4195 data resources 4197 o clarified defaults retrieval for leaf and leaf-list target 4198 resources 4200 o clarified request message-body for operation resources 4202 o clarified query parameters for GET also allowed for HEAD 4204 o clarified error handling for query parameters 4206 o clarified XPath function library for "filter" parameter 4208 o added example for 'edit a data resource' 4210 o added term 'notification replay' from RFC 5277 4212 o clarified unsupported encoding format error handling 4214 o change term 'meta-data' to 'metadata' 4216 o clarified RESTCONF metadata definition 4218 o clarified error info not returned for 1xx, 2xx, and 3xx ranges 4220 o clarified operations description in ietf-restconf module 4222 o clarified Acknowledgements section 4224 o clarified some examples 4226 o update some references 4227 o update RFC 2119 boilerplace 4229 o remove requirements that simply restate HTTP requirements 4231 o remove Pragma: no-cache from examples since RFC 7234 says this 4232 pragma is not defined for responses 4234 o remove suggestion MAY send Pragma: no-cache in response 4236 o remove table of HTTP status codes used in RESTCONF 4238 o changed media type names so they conform to RFC 6838 4240 o clarified too-big error-tag conversion 4242 o update SSE reference 4244 o clarify leaf-list identifier encoding 4246 o removed all media types except yang-data 4248 o changed restconf-media-type extension to be more generic yang-data 4249 extension 4251 A.2. v12 - v13 4253 o fix YANG library module examples (now called module-state) 4255 o fix terminology idnit issue 4257 o removed RFC 2818 reference (changed citation to RFC 7230) 4259 A.3. v11 - v12 4261 o clarify query parameter requirements 4263 o move filter query section to match table order in sec. 4.8 4265 o clarify that depth default is entire subtree for datastore 4266 resource 4268 o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml 4270 o made implementation of timestamps optional since ETags are 4271 mandatory 4273 o removed confusing text about data resource definition revision 4274 date 4276 o clarify that errors should be returned for any resource type 4278 o clarified media subtype (not type) for error response 4280 o clarified client SHOULD (not MAY) specify errors format in Accept 4281 header 4283 o clarified terminology in many sections 4285 A.4. v10 - v11 4287 o change term 'operational data' to 'state data' 4289 o clarify :startup behavior 4291 o clarify X.509 security text 4293 o change '403 Forbidden' to '401 Unauthorized' for GET error 4295 o clarify MUST have one "restconf" link relation 4297 o clarify that NV-storage is not mandatory 4299 o clarify how "Last-Modified" and "ETag" header info can be used by 4300 a client 4302 o clarify meaning of mandatory parameter 4304 o fix module name in action examples 4306 o clarify operation resource request needs to be known to parse the 4307 output 4309 o clarify ordered-by user terminology 4311 o fixed JSON example in D.1.1 4313 A.5. v09 - v10 4315 o address review comments: github issue #36 4317 o removed intro text about no knowledge of NETCONF needed 4319 o clarified candidate and confirmed-commit behavior in sec. 1.3 4321 o clarified that a RESTCONF server MUST support TLS 4323 o clarified choice of 403 or 404 error 4324 o fixed forward references to URI template (w/reference at first 4325 use) 4327 o added reference to HTML5 4329 o made error terminology more consistent 4331 o clarified that only 1 list or leaf-list instance can be returned 4332 in an XML response message-body 4334 o clarified that more than 1 instance must not be created by a POST 4335 method 4337 o clarified that PUT cannot be used to change a leaf-list value or 4338 any list key values 4340 o clarified that PATCH cannot be used to change a leaf-list value or 4341 any list key values 4343 o clarified that DELETE should not be used to delete more than one 4344 instance of a leaf-list or list 4346 o update JSON RFC reference 4348 o specified that leaf-list instances are data resources 4350 o specified how a leaf-list instance identifier is constructed 4352 o fixed get-schema example 4354 o clarified that if no Accept header the server SHOULD return the 4355 type specified in RESTCONF, but MAY return any media-type, 4356 according to HTTP rules 4358 o clarified that server SHOULD maintain timestamp and etag for data 4359 resources 4361 o clarified default for content query parameter 4363 o moved terminology section earlier in doc to avoid forward usage 4365 o clarified intro text wrt/ interactions with NETCONF and access to 4366 specific datastores 4368 o clarified server implementation requirements for YANG defaults 4370 o clarified that Errors is not a resource, just a media type 4371 o clarified that HTTP without TLS MUST NOT be used 4373 o add RESTCONF Extensibility section to make it clear how RESTCONF 4374 will be extended in the future 4376 o add text warning that NACM does not work with HTTP caching 4378 o remove sec. 5.2 Message Headers 4380 o remove 202 Accepted from list of used status-lines -- not allowed 4382 o made implementation of OPTIONS MUST instead of SHOULD 4384 o clarified that successful PUT for altering data returns 204 4386 o fixed "point" parameter example 4388 o added example of alternate value for root resource discovery 4390 o added YANG action examples 4392 o fixed some JSON examples 4394 o changed default value for content query parameter to "all" 4396 o changed empty container JSON encoding from "[null]" to "{}" 4398 o added mandatory /restconf/yang-library-version leaf to advertise 4399 revision-date of the YANG library implemented by the server 4401 o clarified URI encoding rules for leaf-list 4403 o clarified sec. 2.2 wrt/ certificates and TLS 4405 o added update procedure for entity tag and timestamp 4407 A.6. v08 - v09 4409 o fix introduction text regarding implementation requirements for 4410 the ietf-yang-library 4412 o clarified HTTP authentication requirements 4414 o fix host-meta example 4416 o changed list key encoding to clarify that quoted strings are not 4417 allowed. Percent-encoded values are used if quotes would be 4418 required. A missing key is treated as a zero-length string 4420 o Fixed example of percent-encoded string to match YANG model 4422 o Changed streams examples to align with naming already used 4424 A.7. v07 - v08 4426 o add support for YANG 1.1 action statement 4428 o changed mandatory encoding from XML to XML or JSON 4430 o fix syntax in fields parameter definition 4432 o add meta-data encoding examples for XML and JSON 4434 o remove RFC 2396 references and update with 3986 4436 o change encoding of a key so quoted string are not used, since they 4437 are already percent-encoded. A zero-length string is not encoded 4438 (/list=foo,,baz) 4440 o Add example of percent-encoded key value 4442 A.8. v06 - v07 4444 o fixed all issues identified in email from Jernej Tuljak in netconf 4445 email 2015-06-22 4447 o fixed error example bug where error-urlpath was still used. 4448 Changed to error-path. 4450 o added mention of YANG Patch and informative reference 4452 o added support for YANG 1.1, specifically support for anydata and 4453 actions 4455 o removed the special field value "*", since it is no longer needed 4457 A.9. v05 - v06 4459 o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) 4461 A.10. v04 - v05 4463 o changed term 'notification event' to 'event notification' 4465 o removed intro text about framework and meta-model 4467 o removed early mention of API resources 4468 o removed term unified datastore and cleaned up text about NETCONF 4469 datastores 4471 o removed text about not immediate persistence of edits 4473 o removed RESTCONF-specific data-resource-identifier typedef and its 4474 usage 4476 o clarified encoding of key leafs 4478 o changed several examples from JSON to XML encoding 4480 o made 'insert' and 'point' query parameters mandatory to implement 4482 o removed ":insert" capability URI 4484 o renamed stream/encoding to stream/access 4486 o renamed stream/encoding/type to stream/access/encoding 4488 o renamed stream/encoding/events to stream/access/location 4490 o changed XPath from informative to normative reference 4492 o changed rest-dissertation from normative to informative reference 4494 o changed example-jukebox playlist 'id' from a data-resource- 4495 identifier to a leafref pointing at the song name 4497 A.11. v03 - v04 4499 o renamed 'select' to 'fields' (#1) 4501 o moved collection resource and page capability to draft-ietf- 4502 netconf-restconf-collection-00 (#3) 4504 o added mandatory "defaults" protocol capability URI (#4) 4506 o added optional "with-defaults" query parameter URI (#4) 4508 o clarified authentication procedure (#9) 4510 o moved ietf-yang-library module to draft-ietf-netconf-yang- 4511 library-00 (#13) 4513 o clarified that JSON encoding of module name in a URI MUST follow 4514 the netmod-yang-json encoding rules (#14) 4516 o added restconf-media-type extension (#15) 4518 o remove "content" query parameter URI and made this parameter 4519 mandatory (#16) 4521 o clarified datastore usage 4523 o changed lock-denied error example 4525 o added with-defaults query parameter example 4527 o added term "RESTCONF Capability" 4529 o changed NETCONF Capability URI registry usage to new RESTCONF 4530 Capability URI Registry usage 4532 A.12. v02 - v03 4534 o added collection resource 4536 o added "page" query parameter capability 4538 o added "limit" and "offset" query parameters, which are available 4539 if the "page" capability is supported 4541 o added "stream list" term 4543 o fixed bugs in some examples 4545 o added "encoding" list within the "stream" list to allow different 4546 URLs for XML and JSON encoding. 4548 o made XML MUST implement and JSON MAY implement for servers 4550 o re-add JSON notification examples (previously removed) 4552 o updated JSON references 4554 A.13. v01 - v02 4556 o moved query parameter definitions from the YANG module back to the 4557 plain text sections 4559 o made all query parameters optional to implement 4561 o defined query parameter capability URI 4563 o moved 'streams' to new YANG module (ietf-restconf-monitoring) 4564 o added 'capabilities' container to new YANG module (ietf-restconf- 4565 monitoring) 4567 o moved 'modules' container to new YANG module (ietf-yang-library) 4569 o added new leaf 'module-set-id' (ietf-yang-library) 4571 o added new leaf 'conformance' (ietf-yang-library) 4573 o changed 'schema' leaf to type inet:uri that returns the location 4574 of the YANG schema (instead of returning the schema directly) 4576 o changed 'events' leaf to type inet:uri that returns the location 4577 of the event stream resource (instead of returning events 4578 directly) 4580 o changed examples for yang.api resource since the monitoring 4581 information is no longer in this resource 4583 o closed issue #1 'select parameter' since no objections to the 4584 proposed syntax 4586 o closed "encoding of list keys" issue since no objection to new 4587 encoding of list keys in a target resource URI. 4589 o moved open issues list to the issue tracker on github 4591 A.14. v00 - v01 4593 o fixed content=nonconfig example (non-config was incorrect) 4595 o closed open issue 'message-id'. There is no need for a message-id 4596 field, and RFC 2392 does not apply. 4598 o closed open issue 'server support verification'. The headers used 4599 by RESTCONF are widely supported. 4601 o removed encoding rules from section on RESTCONF Meta-Data. This 4602 is now defined in "I-D.lhotka-netmod-yang-json". 4604 o added media type application/yang.errors to map to errors YANG 4605 grouping. Updated error examples to use new media type. 4607 o closed open issue 'additional datastores'. Support may be added 4608 in the future to identify new datastores. 4610 o closed open issue 'PATCH media type discovery'. The section on 4611 PATCH has an added sentence on the Accept-Patch header. 4613 o closed open issue 'YANG to resource mapping'. Current mapping of 4614 all data nodes to resources will be used in order to allow 4615 mandatory DELETE support. The PATCH operation is optional, as 4616 well as the YANG Patch media type. 4618 o closed open issue '_self links for HATEOAS support'. It was 4619 decided that they are redundant because they can be derived from 4620 the YANG module for the specific data. 4622 o added explanatory text for the 'select' parameter. 4624 o added RESTCONF Path Resolution section for discovering the root of 4625 the RESTCONF API using the /.well-known/host-meta. 4627 o added an "error" media type to for structured error messages 4629 o added Secure Transport section requiring TLS 4631 o added Security Considerations section 4633 o removed all references to "REST-like" 4635 A.15. bierman:restconf-04 to ietf:restconf-00 4637 o updated open issues section 4639 Appendix B. Open Issues 4641 -- RFC Ed.: remove this section before publication. 4643 The RESTCONF issues are tracked on github.com: 4645 https://github.com/netconf-wg/restconf/issues 4647 Appendix C. Example YANG Module 4649 The example YANG module used in this document represents a simple 4650 media jukebox interface. 4652 YANG Tree Diagram for "example-jukebox" Module 4654 +--rw jukebox! 4655 +--rw library 4656 | +--rw artist* [name] 4657 | | +--rw name string 4658 | | +--rw album* [name] 4659 | | +--rw name string 4660 | | +--rw genre? identityref 4661 | | +--rw year? uint16 4662 | | +--rw admin 4663 | | | +--rw label? string 4664 | | | +--rw catalogue-number? string 4665 | | +--rw song* [name] 4666 | | +--rw name string 4667 | | +--rw location string 4668 | | +--rw format? string 4669 | | +--rw length? uint32 4670 | +--ro artist-count? uint32 4671 | +--ro album-count? uint32 4672 | +--ro song-count? uint32 4673 +--rw playlist* [name] 4674 | +--rw name string 4675 | +--rw description? string 4676 | +--rw song* [index] 4677 | +--rw index uint32 4678 | +--rw id leafref 4679 +--rw player 4680 +--rw gap? decimal64 4682 rpcs: 4684 +---x play 4685 +--ro input 4686 +--ro playlist string 4687 +--ro song-number uint32 4689 C.1. example-jukebox YANG Module 4691 module example-jukebox { 4693 namespace "http://example.com/ns/example-jukebox"; 4694 prefix "jbox"; 4696 organization "Example, Inc."; 4697 contact "support at example.com"; 4698 description "Example Jukebox Data Model Module"; 4699 revision "2015-04-04" { 4700 description "Initial version."; 4701 reference "example.com document 1-4673"; 4702 } 4704 identity genre { 4705 description "Base for all genre types"; 4706 } 4708 // abbreviated list of genre classifications 4709 identity alternative { 4710 base genre; 4711 description "Alternative music"; 4712 } 4713 identity blues { 4714 base genre; 4715 description "Blues music"; 4716 } 4717 identity country { 4718 base genre; 4719 description "Country music"; 4720 } 4721 identity jazz { 4722 base genre; 4723 description "Jazz music"; 4724 } 4725 identity pop { 4726 base genre; 4727 description "Pop music"; 4728 } 4729 identity rock { 4730 base genre; 4731 description "Rock music"; 4732 } 4734 container jukebox { 4735 presence 4736 "An empty container indicates that the jukebox 4737 service is available"; 4739 description 4740 "Represents a jukebox resource, with a library, playlists, 4741 and a play operation."; 4743 container library { 4745 description "Represents the jukebox library resource."; 4747 list artist { 4748 key name; 4750 description 4751 "Represents one artist resource within the 4752 jukebox library resource."; 4754 leaf name { 4755 type string { 4756 length "1 .. max"; 4758 } 4759 description "The name of the artist."; 4760 } 4762 list album { 4763 key name; 4765 description 4766 "Represents one album resource within one 4767 artist resource, within the jukebox library."; 4769 leaf name { 4770 type string { 4771 length "1 .. max"; 4772 } 4773 description "The name of the album."; 4774 } 4776 leaf genre { 4777 type identityref { base genre; } 4778 description 4779 "The genre identifying the type of music on 4780 the album."; 4781 } 4783 leaf year { 4784 type uint16 { 4785 range "1900 .. max"; 4786 } 4787 description "The year the album was released"; 4788 } 4790 container admin { 4791 description 4792 "Administrative information for the album."; 4794 leaf label { 4795 type string; 4796 description "The label that released the album."; 4797 } 4798 leaf catalogue-number { 4799 type string; 4800 description "The album's catalogue number."; 4801 } 4802 } 4804 list song { 4805 key name; 4806 description 4807 "Represents one song resource within one 4808 album resource, within the jukebox library."; 4810 leaf name { 4811 type string { 4812 length "1 .. max"; 4813 } 4814 description "The name of the song"; 4815 } 4816 leaf location { 4817 type string; 4818 mandatory true; 4819 description 4820 "The file location string of the 4821 media file for the song"; 4822 } 4823 leaf format { 4824 type string; 4825 description 4826 "An identifier string for the media type 4827 for the file associated with the 4828 'location' leaf for this entry."; 4829 } 4830 leaf length { 4831 type uint32; 4832 units "seconds"; 4833 description 4834 "The duration of this song in seconds."; 4835 } 4836 } // end list 'song' 4837 } // end list 'album' 4838 } // end list 'artist' 4840 leaf artist-count { 4841 type uint32; 4842 units "songs"; 4843 config false; 4844 description "Number of artists in the library"; 4845 } 4846 leaf album-count { 4847 type uint32; 4848 units "albums"; 4849 config false; 4850 description "Number of albums in the library"; 4851 } 4852 leaf song-count { 4853 type uint32; 4854 units "songs"; 4855 config false; 4856 description "Number of songs in the library"; 4857 } 4858 } // end library 4860 list playlist { 4861 key name; 4863 description 4864 "Example configuration data resource"; 4866 leaf name { 4867 type string; 4868 description 4869 "The name of the playlist."; 4870 } 4871 leaf description { 4872 type string; 4873 description 4874 "A comment describing the playlist."; 4875 } 4876 list song { 4877 key index; 4878 ordered-by user; 4880 description 4881 "Example nested configuration data resource"; 4883 leaf index { // not really needed 4884 type uint32; 4885 description 4886 "An arbitrary integer index for this playlist song."; 4887 } 4888 leaf id { 4889 type leafref { 4890 path "/jbox:jukebox/jbox:library/jbox:artist/" + 4891 "jbox:album/jbox:song/jbox:name"; 4892 } 4893 mandatory true; 4894 description 4895 "Song identifier. Must identify an instance of 4896 /jukebox/library/artist/album/song/name."; 4897 } 4898 } 4899 } 4901 container player { 4902 description 4903 "Represents the jukebox player resource."; 4905 leaf gap { 4906 type decimal64 { 4907 fraction-digits 1; 4908 range "0.0 .. 2.0"; 4909 } 4910 units "tenths of seconds"; 4911 description "Time gap between each song"; 4912 } 4913 } 4914 } 4916 rpc play { 4917 description "Control function for the jukebox player"; 4918 input { 4919 leaf playlist { 4920 type string; 4921 mandatory true; 4922 description "playlist name"; 4923 } 4924 leaf song-number { 4925 type uint32; 4926 mandatory true; 4927 description "Song number in playlist to play"; 4928 } 4929 } 4930 } 4931 } 4933 Appendix D. RESTCONF Message Examples 4935 The examples within this document use the normative YANG module 4936 defined in Section 8 and the non-normative example YANG module 4937 defined in Appendix C.1. 4939 This section shows some typical RESTCONF message exchanges. 4941 D.1. Resource Retrieval Examples 4943 D.1.1. Retrieve the Top-level API Resource 4945 The client starts by retrieving the RESTCONF entry point: 4947 GET /.well-known/host-meta HTTP/1.1 4948 Host: example.com 4949 Accept: application/xrd+xml 4951 The server might respond: 4953 HTTP/1.1 200 OK 4954 Content-Type: application/xrd+xml 4955 Content-Length: nnn 4957 4958 4959 4961 The client may then retrieve the top-level API resource, using the 4962 entry point "/restconf". 4964 GET /restconf HTTP/1.1 4965 Host: example.com 4966 Accept: application/yang-data+json 4968 The server might respond as follows: 4970 [RFC Editor Note: Adjust the date (2016-04-09) for ietf-yang-library 4971 below to the date in the published ietf-yang-library YANG module, and 4972 remove this note.] 4974 HTTP/1.1 200 OK 4975 Date: Mon, 23 Apr 2012 17:01:00 GMT 4976 Server: example-server 4977 Content-Type: application/yang-data+json 4979 { 4980 "ietf-restconf:restconf": { 4981 "data" : {}, 4982 "operations" : {}, 4983 "yang-library-version" : "2016-04-09" 4984 } 4985 } 4987 To request that the response content to be encoded in XML, the 4988 "Accept" header can be used, as in this example request: 4990 GET /restconf HTTP/1.1 4991 Host: example.com 4992 Accept: application/yang-data+xml 4993 The server will return the same response either way, which might be 4994 as follows : 4996 [RFC Editor Note: Adjust the date for ietf-yang-library below to the 4997 date in the published ietf-yang-library YANG module, and remove this 4998 note.] 5000 HTTP/1.1 200 OK 5001 Date: Mon, 23 Apr 2012 17:01:00 GMT 5002 Server: example-server 5003 Cache-Control: no-cache 5004 Content-Type: application/yang-data+xml 5006 5007 5008 5009 2016-04-09 5010 5012 D.1.2. Retrieve The Server Module Information 5014 It is possible the YANG library module will change over time. The 5015 client can retrieve the revision date of the ietf-yang-library 5016 supported by the server from the API resource, as described in the 5017 previous section. 5019 In this example the client is retrieving the modules information from 5020 the server in JSON format: 5022 GET /restconf/data/ietf-yang-library:modules-state HTTP/1.1 5023 Host: example.com 5024 Accept: application/yang-data+json 5026 The server might respond as follows (some strings wrapped for display 5027 purposes): 5029 [RFC Editor Note: Adjust the date for ietf-yang-library below to the 5030 date in the published ietf-yang-library YANG module, and remove this 5031 note.] 5033 HTTP/1.1 200 OK 5034 Date: Mon, 23 Apr 2012 17:01:00 GMT 5035 Server: example-server 5036 Cache-Control: no-cache 5037 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 5038 Content-Type: application/yang-data+json 5040 { 5041 "ietf-yang-library:modules-state": { 5042 "module-set-id": "5479120c17a619545ea6aff7aa19838b036ebbd7", 5043 "module": [ 5044 { 5045 "name" : "foo", 5046 "revision" : "2012-01-02", 5047 "schema" : "https://example.com/modules/foo/2012-01-02", 5048 "namespace" : "http://example.com/ns/foo", 5049 "feature" : [ "feature1", "feature2" ], 5050 "deviation" : [ 5051 { 5052 "name" : "foo-dev", 5053 "revision" "2012-02-16" 5054 } 5055 ], 5056 "conformance-type" : "implement" 5057 }, 5058 { 5059 "name" : "ietf-yang-library", 5060 "revision" : "2016-04-09", 5061 "schema" : "https://example.com/modules/ietf-yang- 5062 library/2016-04-09", 5063 "namespace" : 5064 "urn:ietf:params:xml:ns:yang:ietf-yang-library", 5065 "conformance-type" : "implement" 5066 }, 5067 { 5068 "name" : "foo-types", 5069 "revision" : "2012-01-05", 5070 "schema" : 5071 "https://example.com/modules/foo-types/2012-01-05", 5072 "namespace" : "http://example.com/ns/foo-types", 5073 "conformance-type" : "import" 5074 }, 5075 { 5076 "name" : "bar", 5077 "revision" : "2012-11-05", 5078 "schema" : "https://example.com/modules/bar/2012-11-05", 5079 "namespace" : "http://example.com/ns/bar", 5080 "feature" : [ "bar-ext" ], 5081 "conformance-type" : "implement", 5082 "submodule" : [ 5083 { 5084 "name" : "bar-submod1", 5085 "revision" : "2012-11-05", 5086 "schema" : 5087 "https://example.com/modules/bar-submod1/2012-11-05" 5088 }, 5089 { 5090 "name" : "bar-submod2", 5091 "revision" : "2012-11-05", 5092 "schema" : 5093 "https://example.com/modules/bar-submod2/2012-11-05" 5094 } 5095 ] 5096 } 5097 ] 5098 } 5099 } 5101 D.1.3. Retrieve The Server Capability Information 5103 In this example the client is retrieving the capability information 5104 from the server in XML format, and the server supports all the 5105 RESTCONF query parameters, plus one vendor parameter: 5107 GET /restconf/data/ietf-restconf-monitoring:restconf-state/ 5108 capabilities HTTP/1.1 5109 Host: example.com 5110 Accept: application/yang-data+xml 5112 The server might respond as follows. The extra whitespace in 5113 'capability' elements is for display purposes only. 5115 HTTP/1.1 200 OK 5116 Date: Mon, 23 Apr 2012 17:02:00 GMT 5117 Server: example-server 5118 Cache-Control: no-cache 5119 Last-Modified: Sun, 22 Apr 2012 01:00:14 GMT 5120 Content-Type: application/yang-data+xml 5122 5124 5125 urn:ietf:params:restconf:capability:defaults:1.0? 5126 basic-mode=explicit 5127 5128 5129 urn:ietf:params:restconf:capability:with-defaults:1.0 5130 5131 5132 urn:ietf:params:restconf:capability:depth:1.0 5133 5134 5135 urn:ietf:params:restconf:capability:fields:1.0 5136 5137 5138 urn:ietf:params:restconf:capability:filter:1.0 5139 5140 5141 urn:ietf:params:restconf:capability:start-time:1.0 5142 5143 5144 urn:ietf:params:restconf:capability:stop-time:1.0 5145 5146 5147 http://example.com/capabilities/myparam 5148 5149 5151 D.2. Edit Resource Examples 5153 D.2.1. Create New Data Resources 5155 To create a new "artist" resource within the "library" resource, the 5156 client might send the following request. 5158 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 5159 Host: example.com 5160 Content-Type: application/yang-data+json 5162 { 5163 "example-jukebox:artist" : { 5164 "name" : "Foo Fighters" 5165 } 5166 } 5168 If the resource is created, the server might respond as follows. 5169 Note that the "Location" header line is wrapped for display purposes 5170 only: 5172 HTTP/1.1 201 Created 5173 Date: Mon, 23 Apr 2012 17:02:00 GMT 5174 Server: example-server 5175 Location: https://example.com/restconf/data/ 5176 example-jukebox:jukebox/library/artist=Foo%20Fighters 5177 Last-Modified: Mon, 23 Apr 2012 17:02:00 GMT 5178 ETag: "b3830f23a4c" 5180 To create a new "album" resource for this artist within the "jukebox" 5181 resource, the client might send the following request. Note that the 5182 request URI header line is wrapped for display purposes only: 5184 POST /restconf/data/example-jukebox:jukebox/ 5185 library/artist=Foo%20Fighters HTTP/1.1 5186 Host: example.com 5187 Content-Type: application/yang-data+xml 5189 5190 Wasting Light 5191 2011 5192 5194 If the resource is created, the server might respond as follows. 5195 Note that the "Location" header line is wrapped for display purposes 5196 only: 5198 HTTP/1.1 201 Created 5199 Date: Mon, 23 Apr 2012 17:03:00 GMT 5200 Server: example-server 5201 Location: https://example.com/restconf/data/ 5202 example-jukebox:jukebox/library/artist=Foo%20Fighters/ 5203 album=Wasting%20Light 5204 Last-Modified: Mon, 23 Apr 2012 17:03:00 GMT 5205 ETag: "b8389233a4c" 5207 D.2.2. Detect Resource Entity Tag Change 5209 In this example, the server just supports the mandatory datastore 5210 last-changed timestamp. The client has previously retrieved the 5211 "Last-Modified" header and has some value cached to provide in the 5212 following request to patch an "album" list entry with key value 5213 "Wasting Light". Only the "genre" field is being updated. 5215 PATCH /restconf/data/example-jukebox:jukebox/ 5216 library/artist=Foo%20Fighters/album=Wasting%20Light/genre 5217 HTTP/1.1 5218 Host: example.com 5219 If-Unmodified-Since: Mon, 23 Apr 2012 17:01:00 GMT 5220 Content-Type: application/yang-data+json 5222 { "example-jukebox:genre" : "example-jukebox:alternative" } 5224 In this example the datastore resource has changed since the time 5225 specified in the "If-Unmodified-Since" header. The server might 5226 respond: 5228 HTTP/1.1 412 Precondition Failed 5229 Date: Mon, 23 Apr 2012 19:01:00 GMT 5230 Server: example-server 5231 Last-Modified: Mon, 23 Apr 2012 17:45:00 GMT 5232 ETag: "b34aed893a4c" 5234 D.2.3. Edit a Datastore Resource 5236 In this example, the client modifies two different data nodes by 5237 sending a PATCH to the datastore resource: 5239 PATCH /restconf/data HTTP/1.1 5240 Host: example.com 5241 Content-Type: application/yang-data+xml 5243 5244 5245 5246 5247 Foo Fighters 5248 5249 Wasting Light 5250 2011 5251 5252 5253 5254 Nick Cave and the Bad Seeds 5255 5256 Tender Prey 5257 1988 5258 5259 5260 5261 5262 5264 D.2.4. Edit a Data Resource 5266 In this example, the client modifies one data nodes by sending a 5267 PATCH to the data resource (URI wrapped for display purposes only): 5269 PATCH /restconf/data/example-jukebox:jukebox/library/ 5270 artist=Nick%20Cave%20and%20the%Bad%20Seeds HTTP/1.1 5271 Host: example.com 5272 Content-Type: application/yang-data+xml 5274 5275 Nick Cave and the Bad Seeds 5276 5277 The Good Son 5278 1990 5279 5280 5282 D.3. Query Parameter Examples 5284 D.3.1. "content" Parameter 5286 The "content" parameter is used to select the type of data child 5287 resources (configuration and/or not configuration) that are returned 5288 by the server for a GET method request. 5290 In this example, a simple YANG list that has configuration and non- 5291 configuration child resources. 5293 container events 5294 list event { 5295 key name; 5296 leaf name { type string; } 5297 leaf description { type string; } 5298 leaf event-count { 5299 type uint32; 5300 config false; 5301 } 5302 } 5303 } 5305 Example 1: content=all 5307 To retrieve all the child resources, the "content" parameter is set 5308 to "all", or omitted, since this is the default value. The client 5309 might send: 5311 GET /restconf/data/example-events:events?content=all 5312 HTTP/1.1 5313 Host: example.com 5314 Accept: application/yang-data+json 5316 The server might respond: 5318 HTTP/1.1 200 OK 5319 Date: Mon, 23 Apr 2012 17:11:30 GMT 5320 Server: example-server 5321 Cache-Control: no-cache 5322 Content-Type: application/yang-data+json 5323 { 5324 "example-events:events" : { 5325 "event" : [ 5326 { 5327 "name" : "interface-up", 5328 "description" : "Interface up notification count", 5329 "event-count" : 42 5330 }, 5331 { 5332 "name" : "interface-down", 5333 "description" : "Interface down notification count", 5334 "event-count" : 4 5335 } 5336 ] 5337 } 5338 } 5340 Example 2: content=config 5342 To retrieve only the configuration child resources, the "content" 5343 parameter is set to "config". Note that the "ETag" and 5344 "Last-Modified" headers are only returned if the content parameter 5345 value is "config". 5347 GET /restconf/data/example-events:events?content=config 5348 HTTP/1.1 5349 Host: example.com 5350 Accept: application/yang-data+json 5352 The server might respond: 5354 HTTP/1.1 200 OK 5355 Date: Mon, 23 Apr 2012 17:11:30 GMT 5356 Server: example-server 5357 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5358 ETag: "eeeada438af" 5359 Cache-Control: no-cache 5360 Content-Type: application/yang-data+json 5362 { 5363 "example-events:events" : { 5364 "event" : [ 5365 { 5366 "name" : "interface-up", 5367 "description" : "Interface up notification count" 5368 }, 5369 { 5370 "name" : "interface-down", 5371 "description" : "Interface down notification count" 5372 } 5373 ] 5374 } 5375 } 5377 Example 3: content=nonconfig 5379 To retrieve only the non-configuration child resources, the "content" 5380 parameter is set to "nonconfig". Note that configuration ancestors 5381 (if any) and list key leafs (if any) are also returned. The client 5382 might send: 5384 GET /restconf/data/example-events:events?content=nonconfig 5385 HTTP/1.1 5386 Host: example.com 5387 Accept: application/yang-data+json 5389 The server might respond: 5391 HTTP/1.1 200 OK 5392 Date: Mon, 23 Apr 2012 17:11:30 GMT 5393 Server: example-server 5394 Cache-Control: no-cache 5395 Content-Type: application/yang-data+json 5397 { 5398 "example-events:events" : { 5399 "event" : [ 5400 { 5401 "name" : "interface-up", 5402 "event-count" : 42 5403 }, 5404 { 5405 "name" : "interface-down", 5406 "event-count" : 4 5407 } 5408 ] 5409 } 5410 } 5412 D.3.2. "depth" Parameter 5414 The "depth" parameter is used to limit the number of levels of child 5415 resources that are returned by the server for a GET method request. 5417 The depth parameter starts counting levels at the level of the target 5418 resource that is specified, so that a depth level of "1" includes 5419 just the target resource level itself. A depth level of "2" includes 5420 the target resource level and its child nodes. 5422 This example shows how different values of the "depth" parameter 5423 would affect the reply content for retrieval of the top-level 5424 "jukebox" data resource. 5426 Example 1: depth=unbounded 5428 To retrieve all the child resources, the "depth" parameter is not 5429 present or set to the default value "unbounded". Note that some 5430 strings are wrapped for display purposes only. 5432 GET /restconf/data/example-jukebox:jukebox?depth=unbounded 5433 HTTP/1.1 5434 Host: example.com 5435 Accept: application/yang-data+json 5437 The server might respond: 5439 HTTP/1.1 200 OK 5440 Date: Mon, 23 Apr 2012 17:11:30 GMT 5441 Server: example-server 5442 Cache-Control: no-cache 5443 Content-Type: application/yang-data+json 5445 { 5446 "example-jukebox:jukebox" : { 5447 "library" : { 5448 "artist" : [ 5449 { 5450 "name" : "Foo Fighters", 5451 "album" : [ 5452 { 5453 "name" : "Wasting Light", 5454 "genre" : "example-jukebox:alternative", 5455 "year" : 2011, 5456 "song" : [ 5457 { 5458 "name" : "Wasting Light", 5459 "location" : 5460 "/media/foo/a7/wasting-light.mp3", 5461 "format" : "MP3", 5462 "length" " 286 5463 }, 5464 { 5465 "name" : "Rope", 5466 "location" : "/media/foo/a7/rope.mp3", 5467 "format" : "MP3", 5468 "length" " 259 5469 } 5470 ] 5471 } 5472 ] 5473 } 5474 ] 5475 }, 5476 "playlist" : [ 5477 { 5478 "name" : "Foo-One", 5479 "description" : "example playlist 1", 5480 "song" : [ 5481 { 5482 "index" : 1, 5483 "id" : "https://example.com/restconf/data/ 5484 example-jukebox:jukebox/library/artist= 5485 Foo%20Fighters/album=Wasting%20Light/ 5486 song=Rope" 5487 }, 5488 { 5489 "index" : 2, 5490 "id" : "https://example.com/restconf/data/ 5491 example-jukebox:jukebox/library/artist= 5492 Foo%20Fighters/album=Wasting%20Light/song= 5493 Bridge%20Burning" 5494 } 5495 ] 5496 } 5497 ], 5498 "player" : { 5499 "gap" : 0.5 5500 } 5501 } 5502 } 5504 Example 2: depth=1 5506 To determine if 1 or more resource instances exist for a given target 5507 resource, the value "1" is used. 5509 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 5510 Host: example.com 5511 Accept: application/yang-data+json 5513 The server might respond: 5515 HTTP/1.1 200 OK 5516 Date: Mon, 23 Apr 2012 17:11:30 GMT 5517 Server: example-server 5518 Cache-Control: no-cache 5519 Content-Type: application/yang-data+json 5521 { 5522 "example-jukebox:jukebox" : {} 5523 } 5525 Example 3: depth=3 5527 To limit the depth level to the target resource plus 2 child resource 5528 layers the value "3" is used. 5530 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 5531 Host: example.com 5532 Accept: application/yang-data+json 5534 The server might respond: 5536 HTTP/1.1 200 OK 5537 Date: Mon, 23 Apr 2012 17:11:30 GMT 5538 Server: example-server 5539 Cache-Control: no-cache 5540 Content-Type: application/yang-data+json 5542 { 5543 "example-jukebox:jukebox" : { 5544 "library" : { 5545 "artist" : {} 5546 }, 5547 "playlist" : [ 5548 { 5549 "name" : "Foo-One", 5550 "description" : "example playlist 1", 5551 "song" : {} 5552 } 5553 ], 5554 "player" : { 5555 "gap" : 0.5 5556 } 5557 } 5558 } 5560 D.3.3. "fields" Parameter 5561 In this example the client is retrieving the datastore resource in 5562 JSON format, but retrieving only the "modules-state/module" list, and 5563 only the "name" and "revision" nodes from each list entry. Note that 5564 top node returned by the server matches the target resource node 5565 (which is "data" in this example). The "module-set-id" leaf is not 5566 returned because it is not selected in the fields expression. 5568 GET /restconf/data?fields=ietf-yang-library:modules-state/ 5569 module(name;revision) HTTP/1.1 5570 Host: example.com 5571 Accept: application/yang-data+json 5573 The server might respond as follows. 5575 [RFC Editor Note: Adjust the date for ietf-yang-library below to the 5576 date in the published ietf-yang-library YANG module, and remove this 5577 note.] 5579 [RFC Editor Note: Adjust the date for ietf-restconf-monitoring below 5580 to the date in the published ietf-restconf-monitoring YANG module, 5581 and remove this note.] 5583 HTTP/1.1 200 OK 5584 Date: Mon, 23 Apr 2012 17:01:00 GMT 5585 Server: example-server 5586 Content-Type: application/yang-data+json 5588 { 5589 "ietf-restconf:data" : { 5590 "ietf-yang-library:modules-state": { 5591 "module": [ 5592 { 5593 "name" : "example-jukebox", 5594 "revision" : "2015-06-04" 5595 }, 5596 { 5597 "name" : "ietf-inet-types", 5598 "revision" : "2013-07-15" 5599 }, 5600 { 5601 "name" : "ietf-restconf-monitoring", 5602 "revision" : "2016-03-16" 5603 }, 5604 { 5605 "name" : "ietf-yang-library", 5606 "revision" : "2016-04-09" 5607 }, 5608 { 5609 "name" : "ietf-yang-types", 5610 "revision" : "2013-07-15" 5611 } 5612 ] 5613 } 5614 } 5615 } 5617 D.3.4. "insert" Parameter 5619 In this example, a new first song entry in the "Foo-One" playlist is 5620 being created. 5622 Request from client: 5624 POST /restconf/data/example-jukebox:jukebox/ 5625 playlist=Foo-One?insert=first HTTP/1.1 5626 Host: example.com 5627 Content-Type: application/yang-data+json 5629 { 5630 "example-jukebox:song" : { 5631 "index" : 1, 5632 "id" : "/example-jukebox:jukebox/library/ 5633 artist=Foo%20Fighters/album=Wasting%20Light/song=Rope" 5634 } 5635 } 5637 Response from server. Note that the "Location" header line is 5638 wrapped for display purposes only: 5640 HTTP/1.1 201 Created 5641 Date: Mon, 23 Apr 2012 13:01:20 GMT 5642 Server: example-server 5643 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5644 Location: https://example.com/restconf/data/ 5645 example-jukebox:jukebox/playlist=Foo-One/song=1 5646 ETag: "eeeada438af" 5648 D.3.5. "point" Parameter 5650 In this example, the client is inserting a new "song" resource within 5651 an "album" resource after another song. The request URI is split for 5652 display purposes only. 5654 Request from client: 5656 POST /restconf/data/example-jukebox:jukebox/ 5657 library/artist=Foo%20Fighters/album=Wasting%20Light? 5658 insert=after&point=%2Fexample-jukebox%3Ajukebox%2F 5659 library%2Fartist%3DFoo%20Fighters%2Falbum%3D 5660 Wasting%20Light%2Fsong%3DBridge%20Burning HTTP/1.1 5661 Host: example.com 5662 Content-Type: application/yang-data+json 5664 { 5665 "example-jukebox:song" : { 5666 "name" : "Rope", 5667 "location" : "/media/foo/a7/rope.mp3", 5668 "format" : "MP3", 5669 "length" : 259 5670 } 5671 } 5673 Response from server: 5675 HTTP/1.1 204 No Content 5676 Date: Mon, 23 Apr 2012 13:01:20 GMT 5677 Server: example-server 5678 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 5679 ETag: "abcada438af" 5681 D.3.6. "filter" Parameter 5683 The following URIs show some examples of notification filter 5684 specifications (lines wrapped for display purposes only): 5686 // filter = /event/event-class='fault' 5687 GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' 5689 // filter = /event/severity<=4 5690 GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 5692 // filter = /linkUp|/linkDown 5693 GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown 5695 // filter = /*/reporting-entity/card!='Ethernet0' 5696 GET /streams/NETCONF? 5697 filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' 5699 // filter = /*/email-addr[contains(.,'company.com')] 5700 GET /streams/critical-syslog? 5701 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 5703 // Note: the module name is used as prefix. 5705 // filter = (/example-mod:event1/name='joe' and 5706 // /example-mod:event1/status='online') 5707 GET /streams/NETCONF? 5708 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and 5709 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 5711 // To get notifications from just two modules (e.g., m1 + m2) 5712 // filter=(/m1:* or /m2:*) 5713 GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*) 5715 D.3.7. "start-time" Parameter 5717 // start-time = 2014-10-25T10:02:00Z 5718 GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z 5720 D.3.8. "stop-time" Parameter 5722 // stop-time = 2014-10-25T12:31:00Z 5723 GET /mystreams/NETCONF?stop-time=2014-10-25T12%3A31%3A00Z 5725 D.3.9. "with-defaults" Parameter 5727 The following YANG module is assumed for this example. 5729 module example-interface { 5730 prefix "exif"; 5731 namespace "urn:example.com:params:xml:ns:yang:example-interface"; 5733 container interfaces { 5734 list interface { 5735 key name; 5736 leaf name { type string; } 5737 leaf mtu { type uint32; } 5738 leaf status { 5739 config false; 5740 type enumeration { 5741 enum up; 5742 enum down; 5743 enum testing; 5744 } 5745 } 5746 } 5747 } 5748 } 5750 Assume the same data model as defined in Appendix A.1 of [RFC6243]. 5751 Assume the same data set as defined in Appendix A.2 of [RFC6243]. If 5752 the server defaults-uri basic-mode is "trim", the the following 5753 request for interface "eth1" might be as follows: 5755 Without query parameter: 5757 GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1 5758 Host: example.com 5759 Accept: application/yang-data+json 5761 The server might respond as follows. 5763 HTTP/1.1 200 OK 5764 Date: Mon, 23 Apr 2012 17:01:00 GMT 5765 Server: example-server 5766 Content-Type: application/yang-data+json 5768 { 5769 "example:interface": [ 5770 { 5771 "name" : "eth1", 5772 "status" : "up" 5773 } 5774 ] 5775 } 5777 Note that the "mtu" leaf is missing because it is set to the default 5778 "1500", and the server defaults handling basic-mode is "trim". 5780 With query parameter: 5782 GET /restconf/data/example:interfaces/interface=eth1 5783 ?with-defaults=report-all HTTP/1.1 5784 Host: example.com 5785 Accept: application/yang-data+json 5787 The server might respond as follows. 5789 HTTP/1.1 200 OK 5790 Date: Mon, 23 Apr 2012 17:01:00 GMT 5791 Server: example-server 5792 Content-Type: application/yang-data+json 5794 { 5795 "example:interface": [ 5796 { 5797 "name" : "eth1", 5798 "mtu" : 1500, 5799 "status" : "up" 5800 } 5801 ] 5802 } 5804 Note that the server returns the "mtu" leaf because the "report-all" 5805 mode was requested with the "with-defaults" query parameter. 5807 Authors' Addresses 5809 Andy Bierman 5810 YumaWorks 5812 Email: andy@yumaworks.com 5814 Martin Bjorklund 5815 Tail-f Systems 5817 Email: mbj@tail-f.com 5819 Kent Watsen 5820 Juniper Networks 5822 Email: kwatsen@juniper.net