idnits 2.17.1 draft-ietf-netconf-restconf-18.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 883 has weird spacing: '...version str...' == Line 2620 has weird spacing: '... method entry...' == Line 3539 has weird spacing: '...ncoding strin...' == Line 3540 has weird spacing: '...ocation inet:...' == Line 4927 has weird spacing: '...ocation str...' == (2 more instances...) -- The document date (October 27, 2016) is 2738 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 4038, 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 6536 (Obsoleted by RFC 8341) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7320 (Obsoleted by RFC 8820) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPath' == Outdated reference: A later version (-14) exists of draft-ietf-netconf-yang-patch-12 == Outdated reference: A later version (-28) exists of draft-ietf-tls-tls13-18 -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 11 errors (**), 0 flaws (~~), 10 warnings (==), 4 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: April 30, 2017 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 October 27, 2016 10 RESTCONF Protocol 11 draft-ietf-netconf-restconf-18 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 April 30, 2017. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 55 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 6 56 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 6 57 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 7 58 1.1.4. NETCONF Notifications . . . . . . . . . . . . . . . . 7 59 1.1.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . 8 60 1.1.6. URI Template and Examples . . . . . . . . . . . . . . 10 61 1.1.7. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 10 62 1.2. Subset of NETCONF Functionality . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . . . . . 15 67 2.1. Integrity and Confidentiality . . . . . . . . . . . . . . 15 68 2.2. HTTPS with X.509v3 Certificates . . . . . . . . . . . . . 15 69 2.3. Certificate Validation . . . . . . . . . . . . . . . . . 15 70 2.4. Authenticated Server Identity . . . . . . . . . . . . . . 15 71 2.5. Authenticated Client Identity . . . . . . . . . . . . . . 16 72 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 16 73 3.1. Root Resource Discovery . . . . . . . . . . . . . . . . . 17 74 3.2. RESTCONF Media Types . . . . . . . . . . . . . . . . . . 19 75 3.3. API Resource . . . . . . . . . . . . . . . . . . . . . . 19 76 3.3.1. {+restconf}/data . . . . . . . . . . . . . . . . . . 20 77 3.3.2. {+restconf}/operations . . . . . . . . . . . . . . . 20 78 3.3.3. {+restconf}/yang-library-version . . . . . . . . . . 21 79 3.4. Datastore Resource . . . . . . . . . . . . . . . . . . . 21 80 3.4.1. Edit Collision Prevention . . . . . . . . . . . . . . 22 81 3.5. Data Resource . . . . . . . . . . . . . . . . . . . . . . 23 82 3.5.1. Timestamp . . . . . . . . . . . . . . . . . . . . . . 24 83 3.5.2. Entity-Tag . . . . . . . . . . . . . . . . . . . . . 24 84 3.5.3. Encoding Data Resource Identifiers in the Request URI 24 85 3.5.4. Default Handling . . . . . . . . . . . . . . . . . . 28 86 3.6. Operation Resource . . . . . . . . . . . . . . . . . . . 28 87 3.6.1. Encoding Operation Resource Input Parameters . . . . 29 88 3.6.2. Encoding Operation Resource Output Parameters . . . . 34 89 3.6.3. Encoding Operation Resource Errors . . . . . . . . . 36 90 3.7. Schema Resource . . . . . . . . . . . . . . . . . . . . . 37 91 3.8. Event Stream Resource . . . . . . . . . . . . . . . . . . 38 92 3.9. Errors YANG Data Template . . . . . . . . . . . . . . . . 39 93 4. RESTCONF Methods . . . . . . . . . . . . . . . . . . . . . . 39 94 4.1. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 40 95 4.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . 40 96 4.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 97 4.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 42 98 4.4.1. Create Resource Mode . . . . . . . . . . . . . . . . 42 99 4.4.2. Invoke Operation Mode . . . . . . . . . . . . . . . . 44 100 4.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 101 4.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 46 102 4.6.1. Plain Patch . . . . . . . . . . . . . . . . . . . . . 47 103 4.7. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . 48 104 4.8. Query Parameters . . . . . . . . . . . . . . . . . . . . 49 105 4.8.1. The "content" Query Parameter . . . . . . . . . . . . 50 106 4.8.2. The "depth" Query Parameter . . . . . . . . . . . . . 51 107 4.8.3. The "fields" Query Parameter . . . . . . . . . . . . 51 108 4.8.4. The "filter" Query Parameter . . . . . . . . . . . . 52 109 4.8.5. The "insert" Query Parameter . . . . . . . . . . . . 53 110 4.8.6. The "point" Query Parameter . . . . . . . . . . . . . 54 111 4.8.7. The "start-time" Query Parameter . . . . . . . . . . 54 112 4.8.8. The "stop-time" Query Parameter . . . . . . . . . . . 55 113 4.8.9. The "with-defaults" Query Parameter . . . . . . . . . 55 114 5. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 57 115 5.1. Request URI Structure . . . . . . . . . . . . . . . . . . 57 116 5.2. Message Encoding . . . . . . . . . . . . . . . . . . . . 58 117 5.3. RESTCONF Metadata . . . . . . . . . . . . . . . . . . . . 59 118 5.3.1. XML Metadata Encoding Example . . . . . . . . . . . . 60 119 5.3.2. JSON Metadata Encoding Example . . . . . . . . . . . 60 120 5.4. Return Status . . . . . . . . . . . . . . . . . . . . . . 61 121 5.5. Message Caching . . . . . . . . . . . . . . . . . . . . . 61 122 6. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 62 123 6.1. Server Support . . . . . . . . . . . . . . . . . . . . . 62 124 6.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 62 125 6.3. Subscribing to Receive Notifications . . . . . . . . . . 64 126 6.3.1. NETCONF Event Stream . . . . . . . . . . . . . . . . 65 127 6.4. Receiving Event Notifications . . . . . . . . . . . . . . 65 128 7. Error Reporting . . . . . . . . . . . . . . . . . . . . . . . 67 129 7.1. Error Response Message . . . . . . . . . . . . . . . . . 68 130 8. RESTCONF Module . . . . . . . . . . . . . . . . . . . . . . . 70 131 9. RESTCONF Monitoring . . . . . . . . . . . . . . . . . . . . . 77 132 9.1. restconf-state/capabilities . . . . . . . . . . . . . . . 77 133 9.1.1. Query Parameter URIs . . . . . . . . . . . . . . . . 78 134 9.1.2. The "defaults" Protocol Capability URI . . . . . . . 78 135 9.2. restconf-state/streams . . . . . . . . . . . . . . . . . 79 136 9.3. RESTCONF Monitoring Module . . . . . . . . . . . . . . . 79 137 10. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 83 138 10.1. modules-state/module . . . . . . . . . . . . . . . . . . 83 139 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 83 140 11.1. The "restconf" Relation Type . . . . . . . . . . . . . . 84 141 11.2. YANG Module Registry . . . . . . . . . . . . . . . . . . 84 142 11.3. Media Types . . . . . . . . . . . . . . . . . . . . . . 85 143 11.3.1. Media Type application/yang-data+xml . . . . . . . . 85 144 11.3.2. Media Type application/yang-data+json . . . . . . . 86 145 11.4. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 88 146 11.5. Registration of "restconf" URN sub-namespace . . . . . . 89 147 12. Security Considerations . . . . . . . . . . . . . . . . . . . 89 148 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 90 149 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 91 150 14.1. Normative References . . . . . . . . . . . . . . . . . . 91 151 14.2. Informative References . . . . . . . . . . . . . . . . . 94 152 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 94 153 A.1. v17 to v18 . . . . . . . . . . . . . . . . . . . . . . . 94 154 A.2. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . 94 155 A.3. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . 95 156 A.4. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . 95 157 A.5. v13 - v14 . . . . . . . . . . . . . . . . . . . . . . . . 96 158 A.6. v12 - v13 . . . . . . . . . . . . . . . . . . . . . . . . 98 159 A.7. v11 - v12 . . . . . . . . . . . . . . . . . . . . . . . . 98 160 A.8. v10 - v11 . . . . . . . . . . . . . . . . . . . . . . . . 98 161 A.9. v09 - v10 . . . . . . . . . . . . . . . . . . . . . . . . 99 162 A.10. v08 - v09 . . . . . . . . . . . . . . . . . . . . . . . . 101 163 A.11. v07 - v08 . . . . . . . . . . . . . . . . . . . . . . . . 101 164 A.12. v06 - v07 . . . . . . . . . . . . . . . . . . . . . . . . 102 165 A.13. v05 - v06 . . . . . . . . . . . . . . . . . . . . . . . . 102 166 A.14. v04 - v05 . . . . . . . . . . . . . . . . . . . . . . . . 102 167 A.15. v03 - v04 . . . . . . . . . . . . . . . . . . . . . . . . 103 168 A.16. v02 - v03 . . . . . . . . . . . . . . . . . . . . . . . . 103 169 A.17. v01 - v02 . . . . . . . . . . . . . . . . . . . . . . . . 104 170 A.18. v00 - v01 . . . . . . . . . . . . . . . . . . . . . . . . 105 171 A.19. bierman:restconf-04 to ietf:restconf-00 . . . . . . . . . 106 172 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 106 173 Appendix C. Example YANG Module . . . . . . . . . . . . . . . . 106 174 C.1. example-jukebox YANG Module . . . . . . . . . . . . . . . 107 175 Appendix D. RESTCONF Message Examples . . . . . . . . . . . . . 112 176 D.1. Resource Retrieval Examples . . . . . . . . . . . . . . . 112 177 D.1.1. Retrieve the Top-level API Resource . . . . . . . . . 112 178 D.1.2. Retrieve The Server Module Information . . . . . . . 113 179 D.1.3. Retrieve The Server Capability Information . . . . . 115 180 D.2. Edit Resource Examples . . . . . . . . . . . . . . . . . 116 181 D.2.1. Create New Data Resources . . . . . . . . . . . . . . 116 182 D.2.2. Detect Resource Entity-Tag Change . . . . . . . . . . 117 183 D.2.3. Edit a Datastore Resource . . . . . . . . . . . . . . 118 184 D.2.4. Replace a Datastore Resource . . . . . . . . . . . . 119 185 D.2.5. Edit a Data Resource . . . . . . . . . . . . . . . . 120 186 D.3. Query Parameter Examples . . . . . . . . . . . . . . . . 120 187 D.3.1. "content" Parameter . . . . . . . . . . . . . . . . . 120 188 D.3.2. "depth" Parameter . . . . . . . . . . . . . . . . . . 124 189 D.3.3. "fields" Parameter . . . . . . . . . . . . . . . . . 127 190 D.3.4. "insert" Parameter . . . . . . . . . . . . . . . . . 128 191 D.3.5. "point" Parameter . . . . . . . . . . . . . . . . . . 129 192 D.3.6. "filter" Parameter . . . . . . . . . . . . . . . . . 130 193 D.3.7. "start-time" Parameter . . . . . . . . . . . . . . . 131 194 D.3.8. "stop-time" Parameter . . . . . . . . . . . . . . . . 131 195 D.3.9. "with-defaults" Parameter . . . . . . . . . . . . . . 132 196 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 133 198 1. Introduction 200 There is a need for standard mechanisms to allow Web applications to 201 access the configuration data, state data, data-model-specific RPC 202 operations, and event notifications within a networking device, in a 203 modular and extensible manner. 205 This document defines an HTTP [RFC7230] based protocol called 206 RESTCONF, for configuring data defined in YANG version 1 [RFC6020] or 207 YANG version 1.1 [RFC7950], using the datastore concepts defined in 208 NETCONF [RFC6241]. 210 NETCONF defines configuration datastores and a set of Create, 211 Retrieve, Update, Delete (CRUD) operations that can be used to access 212 these datastores. NETCONF also defines a protocol for invoking these 213 operations. The YANG language defines the syntax and semantics of 214 datastore content, configuration, state data, RPC operations, and 215 event notifications. 217 RESTCONF uses HTTP methods to provide CRUD operations on a conceptual 218 datastore containing YANG-defined data, which is compatible with a 219 server which implements NETCONF datastores. 221 If a RESTCONF server is co-located with a NETCONF server, then there 222 are protocol interactions with the NETCONF protocol, which are 223 described in Section 1.4. The RESTCONF server MAY provide access to 224 specific datastores using operation resources, as described in 225 Section 3.6. The RESTCONF protocol does not specify any mandatory 226 operation resources. The semantics of each operation resource 227 determine if and how datastores are accessed. 229 Configuration data and state data are exposed as resources that can 230 be retrieved with the GET method. Resources representing 231 configuration data can be modified with the DELETE, PATCH, POST, and 232 PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] 233 or JSON [RFC7159]. 235 Data-model-specific RPC operations defined with the YANG "rpc" or 236 "action" statements can be invoked with the POST method. Data-model- 237 specific event notifications defined with the YANG "notification" 238 statement can be accessed. 240 1.1. Terminology 242 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 243 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 244 document are to be interpreted as described in [RFC2119]. 246 1.1.1. NETCONF 248 The following terms are defined in [RFC6241]: 250 o candidate configuration datastore 252 o configuration data 254 o datastore 256 o configuration datastore 258 o running configuration datastore 260 o startup configuration datastore 262 o state data 264 o user 266 1.1.2. HTTP 268 The following terms are defined in [RFC3986]: 270 o fragment 272 o path 274 o query 276 The following terms are defined in [RFC7230]: 278 o header field 280 o message-body 282 o request-line 284 o request URI 286 o status-line 287 The following terms are defined in [RFC7231]: 289 o method 291 o request 293 o resource 295 The following terms are defined in [RFC7232]: 297 o entity-tag 299 1.1.3. YANG 301 The following terms are defined in [RFC7950]: 303 o action 305 o container 307 o data node 309 o key leaf 311 o leaf 313 o leaf-list 315 o list 317 o mandatory node 319 o ordered-by user 321 o presence container 323 o RPC operation 325 o top-level data node 327 1.1.4. NETCONF Notifications 329 The following terms are defined in [RFC5277]: 331 o notification replay 333 1.1.5. Terms 335 The following terms are used within this document: 337 o API resource: the resource that models the RESTCONF root resource 338 and the sub-resources to access YANG-defined content. It is 339 defined with the YANG data template named "yang-api" in the 340 "ietf-restconf" module. 342 o client: a RESTCONF client 344 o data resource: a resource that models a YANG data node. It is 345 defined with YANG data definition statements. 347 o datastore resource: the resource that models a programmatic 348 interface using NETCONF datastore concepts. By default, RESTCONF 349 methods access a unified view of the underlying datastore 350 implementation on the server. It is defined as a sub-resource 351 within the API resource. 353 o edit operation: a RESTCONF operation on a data resource using 354 either a POST, PUT, PATCH, or DELETE method. This is not the same 355 as the NETCONF edit operation (i.e., one of the values for the 356 "nc:operation" attribute: "create", "replace", "merge", "delete", 357 or "remove"). 359 o event stream resource: This resource represents an SSE (Server- 360 Sent Events) event stream. The content consists of text using the 361 media type "text/event-stream", as defined by the SSE 362 [W3C.REC-eventsource-20150203] specification. Event stream 363 contents are described in Section 3.8. 365 o media-type: HTTP uses Internet media types [RFC2046] in the 366 Content-Type and Accept header fields in order to provide open and 367 extensible data typing and type negotiation. 369 o NETCONF client: a client which implements the NETCONF protocol. 370 Called "client" in [RFC6241]. 372 o NETCONF server: a server which implements the NETCONF protocol. 373 Called "server" in [RFC6241]. 375 o operation: the conceptual RESTCONF operation for a message, 376 derived from the HTTP method, request URI, header fields, and 377 message-body. 379 o operation resource: a resource that models a data-model-specific 380 operation, that is defined with a YANG "rpc" or "action" 381 statement. It is invoked with the POST method. 383 o patch: a PATCH method on the target datastore or data resource. 384 The media type of the message-body content will identify the patch 385 type in use. 387 o plain patch: a specific media type for use with the PATCH method, 388 defined in Section 4.6.1, that can be used for simple merge 389 operations. It is specified by a request Content-Type of 390 "application/yang-data+xml" or "application/yang-data+json". 392 o query parameter: a parameter (and its value if any), encoded 393 within the query component of the request URI. 395 o resource type: one of the RESTCONF resource classes defined in 396 this document. One of "api", "datastore", "data", "operation", 397 "schema", or "event stream". 399 o RESTCONF capability: An optional RESTCONF protocol feature 400 supported by the server, which is identified by an IANA registered 401 NETCONF Capability URI, and advertised with an entry in the 402 "capability" leaf-list defined in Section 9.3. 404 o RESTCONF client: a client which implements the RESTCONF protocol. 406 o RESTCONF server: a server which implements the RESTCONF protocol. 408 o retrieval request: a request using the GET or HEAD methods. 410 o schema resource: a resource that used by the client to retrieve a 411 YANG schema with the GET method. It has a representation with the 412 media type "application/yang". 414 o server: a RESTCONF server 416 o stream list: the set of data resource instances that describe the 417 event stream resources available from the server. This 418 information is defined in the "ietf-restconf-monitoring" module as 419 the "stream" list. It can be retrieved using the target resource 420 "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/ 421 stream". The stream list contains information about each stream, 422 such as the URL to retrieve the event stream data. 424 o stream resource: An event stream resource. 426 o target resource: the resource that is associated with a particular 427 message, identified by the "path" component of the request URI. 429 o yang-data extension: A YANG external statement that conforms to 430 the "yang-data" extension statement found in Section 8. The yang- 431 data extension is used to define YANG data structures that are 432 meant to be used as YANG data templates. These data structures 433 are not intended to be implemented as part of a configuration 434 datastore or as operational state within the server, so normal 435 YANG data definition statements cannot be used. 437 o YANG data template: a schema for modeling protocol message 438 components as conceptual data structure using YANG. This allows 439 the messages to be defined in an encoding-independent manner. 440 Each YANG data template is defined with the "yang-data" extension, 441 found in Section 8. Representations of instances conforming to a 442 particular YANG data template can be defined for YANG. The XML 443 representation is defined in YANG version 1.1 [RFC7950], and 444 supported with the "application/yang-data+xml" media type. The 445 JSON representation is defined in JSON Encoding of Data Modeled 446 with YANG [RFC7951], and supported with the "application/ 447 yang-data+json" media type. 449 1.1.6. URI Template and Examples 451 Throughout this document, the URI template [RFC6570] syntax 452 "{+restconf}" is used to refer to the RESTCONF root resource outside 453 of an example. See Section 3.1 for details. 455 For simplicity, all of the examples in this document use "/restconf" 456 as the discovered RESTCONF API root path. Many of the examples 457 throughout the document are based on the "example-jukebox" YANG 458 module, defined in Appendix C.1. 460 Many protocol header lines and message-body text within examples 461 throughout the document are split into multiple lines for display 462 purposes only. When a line ends with backslash ('\') as the last 463 character, the line is wrapped for display purposes. It is to be 464 considered to be joined to the next line by deleting the backslash, 465 the following line break, and the leading whitespace of the next 466 line. 468 1.1.7. Tree Diagrams 470 A simplified graphical representation of the data model is used in 471 this document. The meaning of the symbols in these diagrams is as 472 follows: 474 o Brackets "[" and "]" enclose list keys. 476 o Abbreviations before data node names: "rw" means configuration 477 data (read-write), "ro" state data (read-only), and "x" operation 478 resource (executable) 480 o Symbols after data node names: "?" means an optional node, "!" 481 means a presence container, and "*" denotes a list and leaf-list. 483 o Parentheses enclose choice and case nodes, and case nodes are also 484 marked with a colon (":"). 486 o Ellipsis ("...") stands for contents of subtrees that are not 487 shown. 489 1.2. Subset of NETCONF Functionality 491 RESTCONF does not need to mirror the full functionality of the 492 NETCONF protocol, but it does need to be compatible with NETCONF. 493 RESTCONF achieves this by implementing a subset of the interaction 494 capabilities provided by the NETCONF protocol, for instance, by 495 eliminating datastores and explicit locking. 497 RESTCONF uses HTTP methods to implement the equivalent of NETCONF 498 operations, enabling basic CRUD operations on a hierarchy of 499 conceptual resources. 501 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 502 resources represented by YANG data models. These basic edit 503 operations allow the running configuration to be altered by a 504 RESTCONF client. 506 RESTCONF is not intended to replace NETCONF, but rather provide an 507 HTTP interface that follows Representational State Transfer (REST) 508 principles [rest-dissertation], and is compatible with the NETCONF 509 datastore model. 511 1.3. Data Model Driven API 513 RESTCONF combines the simplicity of the HTTP protocol with the 514 predictability and automation potential of a schema-driven API. 515 Knowing the YANG modules used by the server, a client can derive all 516 management resource URLs and the proper structure of all RESTCONF 517 requests and responses. This strategy obviates the need for 518 responses provided by the server to contain Hypermedia as the Engine 519 of Application State (HATEOAS) links, originally described in Roy 520 Fielding's doctoral dissertation [rest-dissertation], because the 521 client can determine the links it needs from the YANG modules. 523 RESTCONF utilizes the YANG Library [RFC7895] to allow a client to 524 discover the YANG module conformance information for the server, in 525 case the client wants to use it. 527 The server can optionally support retrieval of the YANG modules it 528 uses, as identified in its YANG library. See Section 3.7 for 529 details. 531 The URIs for data-model-specific RPC operations and datastore content 532 are predictable, based on the YANG module definitions. 534 The RESTCONF protocol operates on a conceptual datastore defined with 535 the YANG data modeling language. The server lists each YANG module 536 it supports using the "ietf-yang-library" YANG module, defined in 537 [RFC7895]. The server MUST implement the "ietf-yang-library" module, 538 which MUST identify all the YANG modules used by the server, in the 539 "modules-state/module" list. The conceptual datastore contents, 540 data-model-specific RPC operations and event notifications are 541 identified by this set of YANG modules. 543 The classification of data as configuration or non-configuration is 544 derived from the YANG "config" statement. Data ordering behavior is 545 derived from the YANG "ordered-by" statement. Non-configuration data 546 is also called "state data". 548 The RESTCONF datastore editing model is simple and direct, similar to 549 the behavior of the :writable-running capability in NETCONF. Each 550 RESTCONF edit of a data resource within the datastore resource is 551 activated upon successful completion of the edit. 553 1.4. Coexistence with NETCONF 555 RESTCONF can be implemented on a device that supports the NETCONF 556 protocol. 558 The following figure shows the system components if a RESTCONF server 559 is co-located with a NETCONF server: 561 +-----------+ +-----------------+ 562 | Web app | <-------> | | 563 +-----------+ RESTCONF | network device | 564 | | 565 +-----------+ | +-----------+ | 566 | NETCONF | <-------> | | datastore | | 567 | Client | NETCONF | | | | 568 +-----------+ | +-----------+ | 569 +-----------------+ 571 The following figure shows the system components if a RESTCONF server 572 is implemented in a device that does not have a NETCONF server: 574 +-----------+ +-----------------+ 575 | Web app | <-------> | | 576 +-----------+ RESTCONF | network device | 577 | | 578 +-----------------+ 580 There are interactions between the NETCONF protocol and RESTCONF 581 protocol related to edit operations. It is possible that locks are 582 in use on a RESTCONF server, even though RESTCONF cannot manipulate 583 locks. In such a case, the RESTCONF protocol will not be granted 584 write access to data resources within a datastore. 586 If the NETCONF server supports :writable-running, all edits to 587 configuration nodes in {+restconf}/data are performed in the running 588 configuration datastore. The URI template "{+restconf}" is defined 589 in Section 1.1.6. 591 Otherwise, if the device supports :candidate, all edits to 592 configuration nodes in {+restconf}/data are performed in the 593 candidate configuration datastore. The candidate MUST be 594 automatically committed to running immediately after each successful 595 edit. Any edits from other sources that are in the candidate 596 datastore will also be committed. If a confirmed commit procedure is 597 in progress by any NETCONF client, then any new commit will act as 598 the confirming commit. If the NETCONF server is expecting a 599 "persist-id" parameter to complete the confirmed commit procedure 600 then the RESTCONF edit operation MUST fail with a "409 Conflict" 601 status-line. There error-tag "in-use" is returned in this case. The 602 error-tag value "resource-denied" is used in this case. 604 If the NETCONF server supports :startup, the RESTCONF server MUST 605 automatically update the non-volatile startup configuration 606 datastore, after the running datastore has been altered as a 607 consequence of a RESTCONF edit operation. 609 If a datastore that would be modified by a RESTCONF operation has an 610 active lock from a NETCONF client, the RESTCONF edit operation MUST 611 fail with a "409 Conflict" status-line. There error-tag "in-use" is 612 returned in this case. 614 1.5. RESTCONF Extensibility 616 There are two extensibility mechanisms built into RESTCONF: 618 o protocol version 619 o optional capabilities 621 This document defines version 1 of the RESTCONF protocol. If a 622 future version of this protocol is defined, then that document will 623 specify how the new version of RESTCONF is identified. It is 624 expected that a different RESTCONF root resource will be used which 625 will be located using a different link relation (See Section 3.1). 627 The server will advertise all protocol versions that it supports in 628 its host-meta data. 630 In this example, the server supports both RESTCONF version 1 and a 631 fictitious version 2. 633 The client might send: 635 GET /.well-known/host-meta HTTP/1.1 636 Host: example.com 637 Accept: application/xrd+xml 639 The server might respond: 641 HTTP/1.1 200 OK 642 Content-Type: application/xrd+xml 643 Content-Length: nnn 645 646 647 648 650 RESTCONF also supports a server-defined list of optional 651 capabilities, which are listed by a server using the 652 "ietf-restconf-monitoring" module defined in Section 9.3. This 653 document defines several query parameters in Section 4.8. Each 654 optional parameter has a corresponding capability URI defined in 655 Section 9.1.1 that is advertised by the server if supported. 657 The "capabilities" list can identify any sort of server extension. 658 Currently this extension mechanism is used to identify optional query 659 parameters that are supported, but it is not limited to that purpose. 660 For example, the "defaults" URI defined in Section 9.1.2 specifies a 661 mandatory URI identifying server defaults handling behavior. 663 A new sub-resource type could be identified with a capability if it 664 is optional to implement. Mandatory protocol features and new 665 resource types require a new revision of the RESTCONF protocol. 667 2. Transport Protocol 669 2.1. Integrity and Confidentiality 671 HTTP [RFC7230] is an application layer protocol that may be layered 672 on any reliable transport-layer protocol. RESTCONF is defined on top 673 of HTTP, but due to the sensitive nature of the information conveyed, 674 RESTCONF requires that the transport-layer protocol provides both 675 data integrity and confidentiality. A RESTCONF server MUST support 676 the TLS protocol [RFC5246], and SHOULD adhere to [RFC7525]. The 677 RESTCONF protocol MUST NOT be used over HTTP without using the TLS 678 protocol. 680 RESTCONF does not require a specific version of HTTP. However, it is 681 RECOMMENDED that at least HTTP/1.1 [RFC7230] be supported by all 682 implementations. 684 2.2. HTTPS with X.509v3 Certificates 686 Given the nearly ubiquitous support for HTTP over TLS [RFC7230], 687 RESTCONF implementations MUST support the "https" URI scheme, which 688 has the IANA assigned default port 443. 690 RESTCONF servers MUST present an X.509v3 based certificate when 691 establishing a TLS connection with a RESTCONF client. The use of 692 X.509v3 based certificates is consistent with NETCONF over TLS 693 [RFC7589]. 695 2.3. Certificate Validation 697 The RESTCONF client MUST either use X.509 certificate path validation 698 [RFC5280] to verify the integrity of the RESTCONF server's TLS 699 certificate, or match the server's TLS certificate with a certificate 700 obtained by a trusted mechanism (e.g., a pinned certificate). If 701 X.509 certificate path validation fails, and the presented X.509 702 certificate does not match a certificate obtained by a trusted 703 mechanism, the connection MUST be terminated, as described in 704 Section 7.2.1 of [RFC5246]. 706 2.4. Authenticated Server Identity 708 The RESTCONF client MUST check the identity of the server according 709 to Section 3.1 of [RFC2818]. 711 2.5. Authenticated Client Identity 713 The RESTCONF server MUST authenticate client access to any protected 714 resource. If the RESTCONF client is not authenticated, the server 715 SHOULD send an HTTP response with "401 Unauthorized" status-line, as 716 defined in Section 3.1 of [RFC7235]. The error-tag value 717 "access-denied" is used in this case. 719 To authenticate a client, a RESTCONF server SHOULD require TLS client 720 certificate based authentication (Section 7.4.6 of [RFC5246]). If 721 certificate based authentication is not feasible (e.g., because one 722 cannot build the required PKI for clients) then an HTTP 723 authentication MAY be used. In the latter case, one of the HTTP 724 authentication schemes defined in the HTTP Authentication Scheme 725 Registry (Section 5.1 in [RFC7235]) MUST be used. 727 A server MAY also support the combination of both client certificates 728 and an HTTP client authentication scheme, with the determination of 729 how to process this combination left as an implementation decision. 731 The RESTCONF client identity derived from the authentication 732 mechanism used is hereafter known as the "RESTCONF username" and 733 subject to the NETCONF Access Control Module (NACM) [RFC6536]. When 734 a client certificate is presented, the RESTCONF username MUST be 735 derived using the algorithm defined in Section 7 of [RFC7589]. For 736 all other cases, when HTTP authentication is used, the RESTCONF 737 username MUST be provided by the HTTP authentication scheme used. 739 3. Resources 741 The RESTCONF protocol operates on a hierarchy of resources, starting 742 with the top-level API resource itself (Section 3.1). Each resource 743 represents a manageable component within the device. 745 A resource can be considered as a collection of data and the set of 746 allowed methods on that data. It can contain nested child resources. 747 The child resource types and methods allowed on them are data-model- 748 specific. 750 A resource has a representation associated with a media type 751 identifier, as represented by the "Content-Type" header field in the 752 HTTP response message. A resource has one or more representations, 753 each associated with a different media type. When a representation 754 of a resource is sent in an HTTP message, the associated media type 755 is given in the "Content-Type" header. A resource can contain zero 756 or more nested resources. A resource can be created and deleted 757 independently of its parent resource, as long as the parent resource 758 exists. 760 The RESTCONF resources are accessed via a set of URIs defined in this 761 document. The set of YANG modules supported by the server will 762 determine the data model specific RPC operations, top-level data 763 nodes, and event notification messages supported by the server. 765 The RESTCONF protocol does not include a data resource discovery 766 mechanism. Instead, the definitions within the YANG modules 767 advertised by the server are used to construct an RPC operation or 768 data resource identifier. 770 3.1. Root Resource Discovery 772 In line with the best practices defined by [RFC7320], RESTCONF 773 enables deployments to specify where the RESTCONF API is located. 774 When first connecting to a RESTCONF server, a RESTCONF client MUST 775 determine the root of the RESTCONF API. There MUST be exactly one 776 "restconf" link relation returned by the device. 778 The client discovers this by getting the "/.well-known/host-meta" 779 resource ([RFC6415]) and using the element containing the 780 "restconf" attribute : 782 Example returning /restconf: 784 The client might send: 786 GET /.well-known/host-meta HTTP/1.1 787 Host: example.com 788 Accept: application/xrd+xml 790 The server might respond: 792 HTTP/1.1 200 OK 793 Content-Type: application/xrd+xml 794 Content-Length: nnn 796 797 798 800 After discovering the RESTCONF API root, the client MUST use this 801 value as the initial part of the path in the request URI, in any 802 subsequent request for a RESTCONF resource. 804 In this example, the client would use the path "/restconf" as the 805 RESTCONF root resource. 807 Example returning /top/restconf: 809 The client might send: 811 GET /.well-known/host-meta HTTP/1.1 812 Host: example.com 813 Accept: application/xrd+xml 815 The server might respond: 817 HTTP/1.1 200 OK 818 Content-Type: application/xrd+xml 819 Content-Length: nnn 821 822 823 825 In this example, the client would use the path "/top/restconf" as the 826 RESTCONF root resource. 828 The client can now determine the operation resources supported by the 829 the server. In this example a custom "play" operation is supported: 831 The client might send: 833 GET /top/restconf/operations HTTP/1.1 834 Host: example.com 835 Accept: application/yang-data+json 837 The server might respond: 839 HTTP/1.1 200 OK 840 Date: Mon, 23 Apr 2016 17:01:00 GMT 841 Server: example-server 842 Cache-Control: no-cache 843 Last-Modified: Sun, 22 Apr 2016 01:00:14 GMT 844 Content-Type: application/yang-data+json 846 { "operations" : { "example-jukebox:play" : [null] } } 848 If the Extensible Resource Descriptor (XRD) contains more than one 849 link relation, then only the relation named "restconf" is relevant to 850 this specification. 852 Note that any given endpoint (host:port) can only support one 853 RESTCONF server, due to the root resource discovery mechanism. This 854 limits the number of RESTCONF servers that can run concurrently on a 855 host, since each server must use a different port. 857 3.2. RESTCONF Media Types 859 The RESTCONF protocol defines two application specific media types to 860 identify representations of data which conforms to the schema for a 861 particular YANG construct. 863 This document defines media types for XML and JSON serialization of 864 YANG data. Other documents MAY define other media types for 865 different serializations of YANG data. The "application/ 866 yang-data+xml" media-type is defined in Section 11.3.1. The 867 "application/yang-data+json" media-type is defined in Section 11.3.2. 869 3.3. API Resource 871 The API resource contains the RESTCONF root resource for the RESTCONF 872 datastore and operation resources. It is the top-level resource 873 located at {+restconf} and has the media type "application/ 874 yang-data+xml" or "application/yang-data+json". 876 YANG Tree Diagram for an API Resource: 878 +---- {+restconf} 879 +---- data 880 | ... 881 +---- operations? 882 | ... 883 +--ro yang-library-version string 885 The "yang-api" YANG data template is defined using the "yang-data" 886 extension in the "ietf-restconf" module, found in Section 8. It 887 specifies the structure and syntax of the conceptual child resources 888 within the API resource. 890 The API resource can be retrieved with the GET method. 892 The {+restconf} root resource name used in responses representing the 893 root of the "ietf-restconf" module MUST identify the "ietf-restconf" 894 YANG module. For example, a request to GET the root resource 895 "/restconf" in JSON format will return a representation of the API 896 resource named "ietf-restconf:restconf". 898 This resource has the following child resources: 900 +----------------------+--------------------------------+ 901 | Child Resource | Description | 902 +----------------------+--------------------------------+ 903 | data | Contains all data resources | 904 | operations | Data-model-specific operations | 905 | yang-library-version | ietf-yang-library module date | 906 +----------------------+--------------------------------+ 908 RESTCONF API Resource 910 3.3.1. {+restconf}/data 912 This mandatory resource represents the combined configuration and 913 state data resources that can be accessed by a client. It cannot be 914 created or deleted by the client. The datastore resource type is 915 defined in Section 3.4. 917 Example: 919 This example request by the client would retrieve only the non- 920 configuration data nodes that exist within the "library" resource, 921 using the "content" query parameter (see Section 4.8.1). 923 GET /restconf/data/example-jukebox:jukebox/library\ 924 ?content=nonconfig HTTP/1.1 925 Host: example.com 926 Accept: application/yang-data+xml 928 The server might respond: 930 HTTP/1.1 200 OK 931 Date: Mon, 23 Apr 2016 17:01:30 GMT 932 Server: example-server 933 Cache-Control: no-cache 934 Content-Type: application/yang-data+xml 936 937 42 938 59 939 374 940 942 3.3.2. {+restconf}/operations 944 This optional resource is a container that provides access to the 945 data-model-specific RPC operations supported by the server. The 946 server MAY omit this resource if no data-model-specific RPC 947 operations are advertised. 949 Any data-model-specific RPC operations defined in the YANG modules 950 advertised by the server MUST be available as child nodes of this 951 resource. 953 The access point for each RPC operation is represented as an empty 954 leaf. If an operation resource is retrieved, the empty leaf 955 representation is returned by the server. 957 Operation resources are defined in Section 3.6. 959 3.3.3. {+restconf}/yang-library-version 961 This mandatory leaf identifies the revision date of the 962 "ietf-yang-library" YANG module that is implemented by this server. 963 Note that the revision date for the module version found in [RFC7895] 964 is used. 966 Example: 968 GET /restconf/yang-library-version HTTP/1.1 969 Host: example.com 970 Accept: application/yang-data+xml 972 The server might respond: 974 HTTP/1.1 200 OK 975 Date: Mon, 23 Apr 2016 17:01:30 GMT 976 Server: example-server 977 Cache-Control: no-cache 978 Content-Type: application/yang-data+xml 980 \ 982 2016-06-21\ 983 985 3.4. Datastore Resource 987 The "{+restconf}/data" subtree represents the datastore resource, 988 which is a collection of configuration data and state data nodes. 990 This resource type is an abstraction of the system's underlying 991 datastore implementation. The client uses it to edit and retrieve 992 data resources, as the conceptual root of all configuration and state 993 data that is present on the device. 995 Configuration edit transaction management and configuration 996 persistence are handled by the server and not controlled by the 997 client. A datastore resource can be written directly with the POST 998 and PATCH methods. Each RESTCONF edit of a datastore resource is 999 saved to non-volatile storage by the server, if the server supports 1000 non-volatile storage of configuration data, as described in 1001 Section 1.4. 1003 If the datastore resource represented by the "{+restconf}/data" 1004 subtree is retrieved, then the datastore and its contents are 1005 returned by the server. The datastore is represented by a node named 1006 "data" in the "ietf-restconf" module namespace. 1008 3.4.1. Edit Collision Prevention 1010 Two edit collision detection and prevention mechanisms are provided 1011 in RESTCONF for the datastore resource: a timestamp and an entity- 1012 tag. Any change to configuration data resources updates the 1013 timestamp and entity tag of the datastore resource. In addition, the 1014 RESTCONF server MUST return an error if the datastore is locked by an 1015 external source (e.g., NETCONF server). 1017 3.4.1.1. Timestamp 1019 The last change time is maintained and the "Last-Modified" 1020 ([RFC7232], Section 2.2) header field is returned in the response for 1021 a retrieval request. The "If-Unmodified-Since" header field 1022 ([RFC7232], Section 3.4) can be used in edit operation requests to 1023 cause the server to reject the request if the resource has been 1024 modified since the specified timestamp. 1026 The server SHOULD maintain a last-modified timestamp for the 1027 datastore resource, defined in Section 3.4. This timestamp is only 1028 affected by configuration child data resources, and MUST NOT be 1029 updated for changes to non-configuration child data resources. Last- 1030 modified timestamps for data resources are discussed in Section 3.5. 1032 If the RESTCONF server is colocated with a NETCONF server, then the 1033 last-modified timestamp MUST be for the "running" datastore. Note 1034 that it is possible other protocols can cause the last-modified 1035 timestamp to be updated. Such mechanisms are out of scope for this 1036 document. 1038 3.4.1.2. Entity-Tag 1040 The server MUST maintain a unique opaque entity-tag for the datastore 1041 resource and MUST return it in the "ETag" ([RFC7232], Section 2.3) 1042 header in the response for a retrieval request. The client MAY use 1043 an "If-Match" header in edit operation requests to cause the server 1044 to reject the request if the resource entity-tag does not match the 1045 specified value. 1047 The server MUST maintain an entity-tag for the top-level 1048 {+restconf}/data resource. This entity-tag is only affected by 1049 configuration data resources, and MUST NOT be updated for changes to 1050 non-configuration data. Entity-tags for data resources are discussed 1051 in Section 3.5. Note that each representation (e.g., XML vs. JSON) 1052 requires a different entity-tag. 1054 If the RESTCONF server is colocated with a NETCONF server, then this 1055 entity-tag MUST be for the "running" datastore. Note that it is 1056 possible other protocols can cause the entity-tag to be updated. 1057 Such mechanisms are out of scope for this document. 1059 3.4.1.3. Update Procedure 1061 Changes to configuration data resources affect the timestamp and 1062 entity-tag for that resource, any ancestor data resources, and the 1063 datastore resource. 1065 For example, an edit to disable an interface might be done by setting 1066 the leaf "/interfaces/interface/enabled" to "false". The "enabled" 1067 data node and its ancestors (one "interface" list instance, and the 1068 "interfaces" container) are considered to be changed. The datastore 1069 is considered to be changed when any top-level configuration data 1070 node is changed (e.g., "interfaces"). 1072 3.5. Data Resource 1074 A data resource represents a YANG data node that is a descendant node 1075 of a datastore resource. Each YANG-defined data node can be uniquely 1076 targeted by the request-line of an HTTP method. Containers, leafs, 1077 leaf-list entries, list entries, anydata and anyxml nodes are data 1078 resources. 1080 The representation maintained for each data resource is the YANG 1081 defined subtree for that node. HTTP methods on a data resource 1082 affect both the targeted data node and all its descendants, if any. 1084 A data resource can be retrieved with the GET method. Data resources 1085 are accessed via the "{+restconf}/data" URI. This sub-tree is used 1086 to retrieve and edit data resources. 1088 3.5.1. Timestamp 1090 For configuration data resources, the server MAY maintain a last- 1091 modified timestamp for the resource, and return the "Last-Modified" 1092 header field when it is retrieved with the GET or HEAD methods. 1094 The "Last-Modified" header field can be used by a RESTCONF client in 1095 subsequent requests, within the "If-Modified-Since" and 1096 "If-Unmodified-Since" header fields. 1098 If maintained, the resource timestamp MUST be set to the current time 1099 whenever the resource or any configuration resource within the 1100 resource is altered. If not maintained, then the resource timestamp 1101 for the datastore MUST be used instead. If the RESTCONF server is 1102 colocated with a NETCONF server, then the last-modified timestamp for 1103 a configuration data resource MUST represent the instance within the 1104 "running" datastore. 1106 This timestamp is only affected by configuration data resources, and 1107 MUST NOT be updated for changes to non-configuration data. 1109 3.5.2. Entity-Tag 1111 For configuration data resources, the server SHOULD maintain a 1112 resource entity-tag for each resource, and return the "ETag" header 1113 field when it is retrieved as the target resource with the GET or 1114 HEAD methods. If maintained, the resource entity-tag MUST be updated 1115 whenever the resource or any configuration resource within the 1116 resource is altered. If not maintained, then the resource entity-tag 1117 for the datastore MUST be used instead. 1119 The "ETag" header field can be used by a RESTCONF client in 1120 subsequent requests, within the "If-Match" and "If-None-Match" header 1121 fields. 1123 This entity-tag is only affected by configuration data resources, and 1124 MUST NOT be updated for changes to non-configuration data. If the 1125 RESTCONF server is colocated with a NETCONF server, then the entity- 1126 tag for a configuration data resource MUST represent the instance 1127 within the "running" datastore. 1129 3.5.3. Encoding Data Resource Identifiers in the Request URI 1131 In YANG, data nodes can be identified with an absolute XPath 1132 expression, defined in [XPath], starting from the document root to 1133 the target resource. In RESTCONF, URI-encoded path expressions are 1134 used instead. 1136 A predictable location for a data resource is important, since 1137 applications will code to the YANG data model module, which uses 1138 static naming and defines an absolute path location for all data 1139 nodes. 1141 A RESTCONF data resource identifier is encoded from left to right, 1142 starting with the top-level data node, according to the "api-path" 1143 rule in Section 3.5.3.1. The node name of each ancestor of the 1144 target resource node is encoded in order, ending with the node name 1145 for the target resource. If a node in the path is defined in another 1146 module than its parent node, or its parent is the datastore, then the 1147 module name followed by a colon character (":") MUST be prepended to 1148 the node name in the resource identifier. See Section 3.5.3.1 for 1149 details. 1151 If a data node in the path expression is a YANG leaf-list node, then 1152 the leaf-list value MUST be encoded according to the following rules: 1154 o The identifier for the leaf-list MUST be encoded using one path 1155 segment [RFC3986]. 1157 o The path segment is constructed by having the leaf-list name, 1158 followed by an "=" character, followed by the leaf-list value. 1159 (e.g., /restconf/data/top-leaflist=fred). 1161 o The leaf-list value is specified as a string, using the canonical 1162 representation for the YANG data type. Any reserved characters 1163 MUST be percent-encoded, according to [RFC3986], section 2.1 and 1164 2.5. 1166 o YANG 1.1 allows duplicate leaf-list values for non-configuration 1167 data. In this case there is no mechanism to specify the exact 1168 matching leaf-list instance. 1170 o The comma (',') character is percent-encoded [RFC3986], even 1171 though multiple key values are not possible for a leaf-list. This 1172 is more consistent and avoids special processing rules. 1174 If a data node in the path expression is a YANG list node, then the 1175 key values for the list (if any) MUST be encoded according to the 1176 following rules: 1178 o The key leaf values for a data resource representing a YANG list 1179 MUST be encoded using one path segment [RFC3986]. 1181 o If there is only one key leaf value, the path segment is 1182 constructed by having the list name, followed by an "=" character, 1183 followed by the single key leaf value. 1185 o If there are multiple key leaf values, the path segment is 1186 constructed by having the list name, followed by the value of each 1187 leaf identified in the "key" statement, encoded in the order 1188 specified in the YANG "key" statement. Each key leaf value except 1189 the last one is followed by a comma character. 1191 o The key value is specified as a string, using the canonical 1192 representation for the YANG data type. Any reserved characters 1193 MUST be percent-encoded, according to [RFC3986], section 2.1 and 1194 2.5. The comma (',') character MUST be percent-encoded if it is 1195 present in the key value. 1197 o All the components in the "key" statement MUST be encoded. 1198 Partial instance identifiers are not supported. 1200 o Missing key values are not allowed, so two consecutive commas are 1201 interpreted as a comma, followed by a zero-length string, followed 1202 by a comma. For example, "list1=foo,,baz" would be interpreted as 1203 a list named "list1" with 3 key values, and the second key value 1204 is a zero-length string. 1206 o Note that non-configuration lists are not required to define keys. 1207 In this case, a single list instance cannot be accessed. 1209 o The "list-instance" ABNF rule defined in Section 3.5.3.1 1210 represents the syntax of a list instance identifier. 1212 Examples: 1214 container top { 1215 list list1 { 1216 key "key1 key2 key3"; 1217 ... 1218 list list2 { 1219 key "key4 key5"; 1220 ... 1221 leaf X { type string; } 1222 } 1223 } 1224 leaf-list Y { 1225 type uint32; 1226 } 1227 } 1229 For the above YANG definition, the container "top" is defined in the 1230 "example-top" YANG module, and a target resource URI for leaf "X" 1231 would be encoded as follows: 1233 /restconf/data/example-top:top/list1=key1,key2,key3/\ 1234 list2=key4,key5/X 1236 For the above YANG definition, a target resource URI for leaf-list 1237 "Y" would be encoded as follows: 1239 /restconf/data/example-top:top/Y=instance-value 1241 The following example shows how reserved characters are percent- 1242 encoded within a key value. The value of "key1" contains a comma, 1243 single-quote, double-quote, colon, double-quote, space, and forward 1244 slash. (,'":" /). Note that double-quote is not a reserved character 1245 and does not need to be percent-encoded. The value of "key2" is the 1246 empty string, and the value of "key3" is the string "foo". 1248 Example URL: 1250 /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo 1252 3.5.3.1. ABNF For Data Resource Identifiers 1254 The "api-path" Augmented Backus-Naur Form (ABNF) syntax is used to 1255 construct RESTCONF path identifiers. Note that this syntax is used 1256 for all resources, and the API path starts with the RESTCONF root 1257 resource. Data resources are required to be identified under the 1258 subtree "+{restconf}/data". 1260 An identifier is not allowed to start with the case-insensitive 1261 string "XML", according to YANG identifier rules. The syntax for 1262 "api-identifier" and "key-value" MUST conform to the JSON identifier 1263 encoding rules in Section 4 of [RFC7951]: The RESTCONF root resource 1264 path is required. Additional sub-resource identifiers are optional. 1265 The characters in a key value string are constrained, and some 1266 characters need to be percent-encoded, as described in Section 3.5.3. 1268 api-path = root *("/" (api-identifier / list-instance)) 1270 root = string ;; replacement string for {+restconf} 1272 api-identifier = [module-name ":"] identifier 1274 module-name = identifier 1276 list-instance = api-identifier "=" key-value *("," key-value) 1278 key-value = string ;; constrained chars are percent-encoded 1280 string = 1282 identifier = (ALPHA / "_") 1283 *(ALPHA / DIGIT / "_" / "-" / ".") 1285 3.5.4. Default Handling 1287 RESTCONF requires that a server report its default handling mode (see 1288 Section 9.1.2 for details). If the optional "with-defaults" query 1289 parameter is supported by the server, a client may use it to control 1290 retrieval of default values (see Section 4.8.9 for details). 1292 If a leaf or leaf-list is missing from the configuration and there is 1293 a YANG-defined default for that data resource, then the server MUST 1294 use the YANG-defined default as the configured value. 1296 If the target of a GET method is a data node that represents a leaf 1297 or leaf-list that has a default value, and the leaf or leaf-list has 1298 not been instantiated yet, the server MUST return the default 1299 value(s) that are in use by the server. In this case, the server 1300 MUST ignore its basic-mode, described in Section 4.8.9, and return 1301 the default value. 1303 If the target of a GET method is a data node that represents a 1304 container or list that has any child resources with default values, 1305 for the child resources that have not been given value yet, the 1306 server MAY return the default values that are in use by the server, 1307 in accordance with its reported default handing mode and query 1308 parameters passed by the client. 1310 3.6. Operation Resource 1312 An operation resource represents an RPC operation defined with the 1313 YANG "rpc" statement or a data-model-specific action defined with a 1314 YANG "action" statement. It is invoked using a POST method on the 1315 operation resource. 1317 An RPC operation is invoked as: 1319 POST {+restconf}/operations/ 1321 The field identifies the module name and rpc identifier 1322 string for the desired operation. 1324 For example, if "module-A" defined a "reset" rpc operation, then 1325 invoking the operation would be requested as follows: 1327 POST /restconf/operations/module-A:reset HTTP/1.1 1328 Server: example.com 1330 An action is invoked as: 1332 POST {+restconf}/data// 1334 where contains the path to the data node 1335 where the action is defined, and is the name of the action. 1337 For example, if "module-A" defined a "reset-all" action in the 1338 container "interfaces", then invoking this action would be requested 1339 as follows: 1341 POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1 1342 Server: example.com 1344 If the RPC operation is invoked without errors, and if the "rpc" or 1345 "action" statement has no "output" section, the response message MUST 1346 NOT include a message-body, and MUST send a "204 No Content" status- 1347 line instead. 1349 All operation resources representing RPC operations supported by the 1350 server MUST be identified in the {+restconf}/operations subtree 1351 defined in Section 3.3.2. Operation resources representing YANG 1352 actions are not identified in this subtree since they are invoked 1353 using a URI within the {+restconf}/data subtree. 1355 3.6.1. Encoding Operation Resource Input Parameters 1357 If the "rpc" or "action" statement has an "input" section then 1358 instances of these input parameters are encoded in the module 1359 namespace where the "rpc" or "action" statement is defined, in an XML 1360 element or JSON object named "input", which is in the module 1361 namespace where the "rpc" or "action" statement is defined. 1363 If the "rpc" or "action" statement has an "input" section and the 1364 "input" object tree contains any child data nodes which are 1365 considered mandatory nodes, then a message-body MUST be sent by the 1366 client in the request. 1368 If the "rpc" or "action" statement has an "input" section and the 1369 "input" object tree does not contain any child nodes which are 1370 considered mandatory nodes, then a message-body MAY be sent by the 1371 client in the request. 1373 If the "rpc" or "action" statement has no "input" section, the 1374 request message MUST NOT include a message-body. 1376 Examples: 1378 The following YANG module is used for the RPC operation examples in 1379 this section. 1381 module example-ops { 1382 namespace "https://example.com/ns/example-ops"; 1383 prefix "ops"; 1385 organization "Example, Inc."; 1386 contact "support at example.com"; 1387 description "Example Operations Data Model Module"; 1388 revision "2016-07-07" { 1389 description "Initial version."; 1390 reference "example.com document 3-3373"; 1391 } 1393 rpc reboot { 1394 input { 1395 leaf delay { 1396 units seconds; 1397 type uint32; 1398 default 0; 1399 } 1400 leaf message { type string; } 1401 leaf language { type string; } 1402 } 1403 } 1405 rpc get-reboot-info { 1406 output { 1407 leaf reboot-time { 1408 units seconds; 1409 type uint32; 1410 } 1411 leaf message { type string; } 1412 leaf language { type string; } 1413 } 1414 } 1415 } 1417 The following YANG module is used for the YANG action examples in 1418 this section. 1420 module example-actions { 1421 yang-version 1.1; 1422 namespace "https://example.com/ns/example-actions"; 1423 prefix "act"; 1424 import ietf-yang-types { prefix yang; } 1426 organization "Example, Inc."; 1427 contact "support at example.com"; 1428 description "Example Actions Data Model Module"; 1429 revision "2016-07-07" { 1430 description "Initial version."; 1431 reference "example.com document 2-9973"; 1432 } 1434 revision "2016-03-10"; 1436 container interfaces { 1437 list interface { 1438 key name; 1439 leaf name { type string; } 1441 action reset { 1442 input { 1443 leaf delay { 1444 units seconds; 1445 type uint32; 1446 default 0; 1447 } 1448 } 1449 } 1451 action get-last-reset-time { 1452 output { 1453 leaf last-reset { 1454 type yang:date-and-time; 1455 mandatory true; 1456 } 1457 } 1458 } 1459 } 1460 } 1462 } 1464 RPC Input Example: 1466 The client might send the following POST request message to invoke 1467 the "reboot" RPC operation: 1469 POST /restconf/operations/example-ops:reboot HTTP/1.1 1470 Host: example.com 1471 Content-Type: application/yang-data+xml 1473 1474 600 1475 Going down for system maintenance 1476 en-US 1477 1479 The server might respond: 1481 HTTP/1.1 204 No Content 1482 Date: Mon, 25 Apr 2016 11:01:00 GMT 1483 Server: example-server 1485 The same example request message is shown here using JSON encoding: 1487 POST /restconf/operations/example-ops:reboot HTTP/1.1 1488 Host: example.com 1489 Content-Type: application/yang-data+json 1491 { 1492 "example-ops:input" : { 1493 "delay" : 600, 1494 "message" : "Going down for system maintenance", 1495 "language" : "en-US" 1496 } 1497 } 1499 Action Input Example: 1501 The client might send the following POST request message to invoke 1502 the "reset" action: 1504 POST /restconf/data/example-actions:interfaces/\ 1505 interface=eth0/reset HTTP/1.1 1506 Host: example.com 1507 Content-Type: application/yang-data+xml 1509 1510 600 1511 1513 The server might respond: 1515 HTTP/1.1 204 No Content 1516 Date: Mon, 25 Apr 2016 11:01:00 GMT 1517 Server: example-server 1519 The same example request message is shown here using JSON encoding: 1521 POST /restconf/data/example-actions:interfaces/\ 1522 interface=eth0/reset HTTP/1.1 1523 Host: example.com 1524 Content-Type: application/yang-data+json 1526 { "example-actions:input" : { 1527 "delay" : 600 1528 } 1529 } 1531 3.6.2. Encoding Operation Resource Output Parameters 1533 If the "rpc" or "action" statement has an "output" section then 1534 instances of these output parameters are encoded in the module 1535 namespace where the "rpc" or "action" statement is defined, in an XML 1536 element or JSON object named "output", which is in the module 1537 namespace where the "rpc" or "action" statement is defined. 1539 If the RPC operation is invoked without errors, and if the "rpc" or 1540 "action" statement has an "output" section and the "output" object 1541 tree contains any child data nodes which are considered mandatory 1542 nodes, then a response message-body MUST be sent by the server in the 1543 response. 1545 If the RPC operation is invoked without errors, and if the "rpc" or 1546 "action" statement has an "output" section and the "output" object 1547 tree does not contain any child nodes which are considered mandatory 1548 nodes, then a response message-body MAY be sent by the server in the 1549 response. 1551 The request URI is not returned in the response. Knowledge of the 1552 request URI may be needed to associate the output with the specific 1553 "rpc" or "action" statement used in the request. 1555 Examples: 1557 RPC Output Example: 1559 The "example-ops" YANG module defined in Section 3.6.1 is used for 1560 this example. 1562 The client might send the following POST request message to invoke 1563 the "get-reboot-info" operation: 1565 POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1 1566 Host: example.com 1567 Accept: application/yang-data+json 1569 The server might respond: 1571 HTTP/1.1 200 OK 1572 Date: Mon, 25 Apr 2016 11:10:30 GMT 1573 Server: example-server 1574 Content-Type: application/yang-data+json 1576 { 1577 "example-ops:output" : { 1578 "reboot-time" : 30, 1579 "message" : "Going down for system maintenance", 1580 "language" : "en-US" 1581 } 1582 } 1584 The same response is shown here using XML encoding: 1586 HTTP/1.1 200 OK 1587 Date: Mon, 25 Apr 2016 11:10:30 GMT 1588 Server: example-server 1589 Content-Type: application/yang-data+xml 1591 1592 30 1593 Going down for system maintenance 1594 en-US 1595 1597 Action Output Example: 1599 The "example-actions" YANG module defined in Section 3.6.1 is used 1600 for this example. 1602 The client might send the following POST request message to invoke 1603 the "get-last-reset-time" action: 1605 POST /restconf/data/example-actions:interfaces/\ 1606 interface=eth0/get-last-reset-time HTTP/1.1 1607 Host: example.com 1608 Accept: application/yang-data+json 1610 The server might respond: 1612 HTTP/1.1 200 OK 1613 Date: Mon, 25 Apr 2016 11:10:30 GMT 1614 Server: example-server 1615 Content-Type: application/yang-data+json 1617 { 1618 "example-actions:output" : { 1619 "last-reset" : "2015-10-10T02:14:11Z" 1620 } 1621 } 1623 3.6.3. Encoding Operation Resource Errors 1625 If any errors occur while attempting to invoke the operation or 1626 action, then an "errors" media type is returned with the appropriate 1627 error status. 1629 If the RPC operation input is not valid, or the RPC operation is 1630 invoked but errors occur, then a message-body MUST be sent by the 1631 server, containing an "errors" resource, as defined in Section 3.9. 1632 A detailed example of an operation resource error response can be 1633 found in Section 3.6.3. 1635 Using the "reboot" RPC operation from the example in Section 3.6.1, 1636 the client might send the following POST request message: 1638 POST /restconf/operations/example-ops:reboot HTTP/1.1 1639 Host: example.com 1640 Content-Type: application/yang-data+xml 1642 1643 -33 1644 Going down for system maintenance 1645 en-US 1646 1648 The server might respond with an "invalid-value" error: 1650 HTTP/1.1 400 Bad Request 1651 Date: Mon, 25 Apr 2016 11:10:30 GMT 1652 Server: example-server 1653 Content-Type: application/yang-data+xml 1654 1655 1656 protocol 1657 invalid-value 1658 1659 /ops:input/ops:delay 1660 1661 Invalid input parameter 1662 1663 1665 The same response is shown here in JSON encoding: 1667 HTTP/1.1 400 Bad Request 1668 Date: Mon, 25 Apr 2016 11:10:30 GMT 1669 Server: example-server 1670 Content-Type: application/yang-data+json 1672 { "ietf-restconf:errors" : { 1673 "error" : [ 1674 { 1675 "error-type" : "protocol", 1676 "error-tag" : "invalid-value", 1677 "error-path" : "/example-ops:input/delay", 1678 "error-message" : "Invalid input parameter", 1679 } 1680 ] 1681 } 1682 } 1684 3.7. Schema Resource 1686 The server can optionally support retrieval of the YANG modules it 1687 supports. If retrieval is supported, then the "schema" leaf MUST be 1688 present in the associated "module" list entry, defined in [RFC7895]. 1690 To retrieve a YANG module, a client first needs to get the URL for 1691 retrieving the schema, which is stored in the "schema" leaf. Note 1692 that there is no required structure for this URL. The URL value 1693 shown below is just an example. 1695 The client might send the following GET request message: 1697 GET /restconf/data/ietf-yang-library:modules-state/\ 1698 module=example-jukebox,2016-08-15/schema HTTP/1.1 1699 Host: example.com 1700 Accept: application/yang-data+json 1702 The server might respond: 1704 HTTP/1.1 200 OK 1705 Date: Thu, 11 Feb 2016 11:10:30 GMT 1706 Server: example-server 1707 Content-Type: application/yang-data+json 1709 { 1710 "ietf-yang-library:schema" : 1711 "https://example.com/mymodules/example-jukebox/2016-08-15" 1712 } 1714 Next the client needs to retrieve the actual YANG schema. 1716 The client might send the following GET request message: 1718 GET https://example.com/mymodules/example-jukebox/\ 1719 2016-08-15 HTTP/1.1 1720 Host: example.com 1721 Accept: application/yang 1723 The server might respond: 1725 HTTP/1.1 200 OK 1726 Date: Thu, 11 Feb 2016 11:10:31 GMT 1727 Server: example-server 1728 Content-Type: application/yang 1730 module example-jukebox { 1732 // contents of YANG module deleted for this example... 1734 } 1736 3.8. Event Stream Resource 1738 An "event stream" resource represents a source for system generated 1739 event notifications. Each stream is created and modified by the 1740 server only. A client can retrieve a stream resource or initiate a 1741 long-poll server sent event stream, using the procedure specified in 1742 Section 6.3. 1744 An event stream functions according to the NETCONF Notifications 1745 specification [RFC5277]. The available streams can be retrieved from 1746 the stream list, which specifies the syntax and semantics of the 1747 stream resources. 1749 3.9. Errors YANG Data Template 1751 The "errors" YANG data template models a collection of error 1752 information that is sent as the message-body in a server response 1753 message, if an error occurs while processing a request message. It 1754 is not considered as a resource type because no instances can be 1755 retrieved with a GET request. 1757 The "ietf-restconf" YANG module contains the "yang-errors" YANG data 1758 template, that specifies the syntax and semantics of an "errors" 1759 container within a RESTCONF response. RESTCONF error handling 1760 behavior is defined in Section 7. 1762 4. RESTCONF Methods 1764 The RESTCONF protocol uses HTTP methods to identify the CRUD 1765 operations requested for a particular resource. 1767 The following table shows how the RESTCONF operations relate to 1768 NETCONF protocol operations and for the NETCONF 1769 operation, the "nc:operation" attribute. 1771 +----------+-----------------------------------------------+ 1772 | RESTCONF | NETCONF | 1773 +----------+-----------------------------------------------+ 1774 | OPTIONS | none | 1775 | HEAD | none | 1776 | GET | , | 1777 | POST | (nc:operation="create") | 1778 | POST | invoke an RPC operation | 1779 | PUT | (nc:operation="create/replace") | 1780 | PATCH | (nc:operation="merge") | 1781 | DELETE | (nc:operation="delete") | 1782 +----------+-----------------------------------------------+ 1784 CRUD Methods in RESTCONF 1786 The "remove" edit operation attribute for the NETCONF 1787 RPC operation is not supported by the HTTP DELETE method. The 1788 resource must exist or the DELETE method will fail. The PATCH method 1789 is equivalent to a "merge" edit operation when using a plain patch 1790 (see Section 4.6.1); other media-types may provide more granular 1791 control. 1793 Access control mechanisms are used to limit what CRUD operations can 1794 be used. In particular, RESTCONF is compatible with the NETCONF 1795 Access Control Model (NACM) [RFC6536], as there is a specific mapping 1796 between RESTCONF and NETCONF operations. The resource path needs to 1797 be converted internally by the server to the corresponding YANG 1798 instance-identifier. Using this information, the server can apply 1799 the NACM access control rules to RESTCONF messages. 1801 The server MUST NOT allow any RESTCONF operation for any resources 1802 that the client is not authorized to access. 1804 Implementation of all methods (except PATCH [RFC5789]) are defined in 1805 [RFC7231]. This section defines the RESTCONF protocol usage for each 1806 HTTP method. 1808 4.1. OPTIONS 1810 The OPTIONS method is sent by the client to discover which methods 1811 are supported by the server for a specific resource (e.g., GET, POST, 1812 DELETE, etc.). The server MUST implement this method. 1814 The "Accept-Patch" header field MUST be supported and returned in the 1815 response to the OPTIONS request, as defined in [RFC5789]. 1817 4.2. HEAD 1819 The RESTCONF server MUST support the HEAD method. The HEAD method is 1820 sent by the client to retrieve just the header fields (which contain 1821 the metadata for a resource) that would be returned for the 1822 comparable GET method, without the response message-body. It is 1823 supported for all resources that support the GET method. 1825 The request MUST contain a request URI that contains at least the 1826 root resource. The same query parameters supported by the GET method 1827 are supported by the HEAD method. 1829 The access control behavior is enforced as if the method was GET 1830 instead of HEAD. The server MUST respond the same as if the method 1831 was GET instead of HEAD, except that no response message-body is 1832 included. 1834 4.3. GET 1836 The RESTCONF server MUST support the GET method. The GET method is 1837 sent by the client to retrieve data and metadata for a resource. It 1838 is supported for all resource types, except operation resources. The 1839 request MUST contain a request URI that contains at least the root 1840 resource. 1842 The server MUST NOT return any data resources for which the user does 1843 not have read privileges. If the user is not authorized to read the 1844 target resource, an error response containing a "401 Unauthorized" 1845 status-line SHOULD be returned. The error-tag value "access-denied" 1846 is returned in this case. A server MAY return a "404 Not Found" 1847 status-line, as described in section 6.5.3 in [RFC7231]. The error- 1848 tag value "invalid-value" is returned in this case. 1850 If the user is authorized to read some but not all of the target 1851 resource, the unauthorized content is omitted from the response 1852 message-body, and the authorized content is returned to the client. 1854 If any content is returned to the client, then the server MUST send a 1855 valid response message-body. More than one element MUST NOT be 1856 returned for XML encoding. If multiple elements are sent in a JSON 1857 message-body, then they MUST be sent as a JSON array. In this case 1858 any timestamp or entity-tag returned in the response MUST be 1859 associated with the first element returned. 1861 If a retrieval request for a data resource representing a YANG leaf- 1862 list or list object identifies more than one instance, and XML 1863 encoding is used in the response, then an error response containing a 1864 "400 Bad Request" status-line MUST be returned by the server. The 1865 error-tag value "invalid-value" is used in this case. Note that a 1866 non-configuration list is not required to defined any keys. In this 1867 case, retrieval of a single list instance is not possible. 1869 If a retrieval request for a data resource represents an instance 1870 that does not exist, then an error response containing a "404 Not 1871 Found" status-line MUST be returned by the server. The error-tag 1872 value "invalid-value" is used in this case. 1874 If the target resource of a retrieval request is for an operation 1875 resource then a "405 Method Not Allowed" status-line MUST be returned 1876 by the server. The error-tag value "operation-not-supported" is used 1877 in this case. 1879 Note that the way that access control is applied to data resources 1880 may not be completely compatible with HTTP caching. The Last- 1881 Modified and ETag header fields maintained for a data resource are 1882 not affected by changes to the access control rules for that data 1883 resource. It is possible for the representation of a data resource 1884 that is visible to a particular client to be changed without 1885 detection via the Last-Modified or ETag values. 1887 Example: 1889 The client might request the response header fields for an XML 1890 representation of the a specific "album" resource: 1892 GET /restconf/data/example-jukebox:jukebox/\ 1893 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 1894 Host: example.com 1895 Accept: application/yang-data+xml 1897 The server might respond: 1899 HTTP/1.1 200 OK 1900 Date: Mon, 23 Apr 2016 17:02:40 GMT 1901 Server: example-server 1902 Content-Type: application/yang-data+xml 1903 Cache-Control: no-cache 1904 ETag: "a74eefc993a2b" 1905 Last-Modified: Mon, 23 Apr 2016 11:02:14 GMT 1907 1909 Wasting Light 1910 jbox:alternative 1911 2011 1912 1914 Refer to Appendix D.1 for more resource retrieval examples. 1916 4.4. POST 1918 The RESTCONF server MUST support the POST method. The POST method is 1919 sent by the client to create a data resource or invoke an operation 1920 resource. The server uses the target resource type to determine how 1921 to process the request. 1923 +-----------+------------------------------------------------+ 1924 | Type | Description | 1925 +-----------+------------------------------------------------+ 1926 | Datastore | Create a top-level configuration data resource | 1927 | Data | Create a configuration data child resource | 1928 | Operation | Invoke an RPC operation | 1929 +-----------+------------------------------------------------+ 1931 Resource Types that Support POST 1933 4.4.1. Create Resource Mode 1935 If the target resource type is a datastore or data resource, then the 1936 POST is treated as a request to create a top-level resource or child 1937 resource, respectively. The message-body is expected to contain the 1938 content of a child resource to create within the parent (target 1939 resource). The message-body MUST contain exactly one instance of the 1940 expected data resource. The data-model for the child tree is the 1941 subtree as defined by YANG for the child resource. 1943 The "insert" Section 4.8.5 and "point" Section 4.8.6 query parameters 1944 MUST be supported by the POST method for datastore and data 1945 resources. These parameters are only allowed if the list or leaf- 1946 list is ordered-by user. 1948 If the POST method succeeds, a "201 Created" status-line is returned 1949 and there is no response message-body. A "Location" header field 1950 identifying the child resource that was created MUST be present in 1951 the response in this case. 1953 If the data resource already exists, then the POST request MUST fail 1954 and a "409 Conflict" status-line MUST be returned. The error-tag 1955 value "resource-denied" is used in this case. 1957 If the user is not authorized to create the target resource, an error 1958 response containing a "403 Forbidden" status-line SHOULD be returned. 1959 The error-tag value "access-denied" is used in this case. A server 1960 MAY return a "404 Not Found" status-line, as described in section 1961 6.5.3 in [RFC7231]. The error-tag value "invalid-value" is used in 1962 this case. All other error responses are handled according to the 1963 procedures defined in Section 7. 1965 Example: 1967 To create a new "jukebox" resource, the client might send: 1969 POST /restconf/data HTTP/1.1 1970 Host: example.com 1971 Content-Type: application/yang-data+json 1973 { "example-jukebox:jukebox" : {} } 1975 If the resource is created, the server might respond as follows: 1977 HTTP/1.1 201 Created 1978 Date: Mon, 23 Apr 2016 17:01:00 GMT 1979 Server: example-server 1980 Location: https://example.com/restconf/data/\ 1981 example-jukebox:jukebox 1982 Last-Modified: Mon, 23 Apr 2016 17:01:00 GMT 1983 ETag: "b3a3e673be2" 1985 Refer to Appendix D.2.1 for more resource creation examples. 1987 4.4.2. Invoke Operation Mode 1989 If the target resource type is an operation resource, then the POST 1990 method is treated as a request to invoke that operation. The 1991 message-body (if any) is processed as the operation input parameters. 1992 Refer to Section 3.6 for details on operation resources. 1994 If the POST request succeeds, a "200 OK" status-line is returned if 1995 there is a response message-body, and a "204 No Content" status-line 1996 is returned if there is no response message-body. 1998 If the user is not authorized to invoke the target operation, an 1999 error response containing a "403 Forbidden" status-line SHOULD be 2000 returned. The error-tag value "access-denied" is used in this case. 2001 A server MAY return a "404 Not Found" status-line, as described in 2002 section 6.5.3 in [RFC7231]. All other error responses are handled 2003 according to the procedures defined in Section 7. 2005 Example: 2007 In this example, the client is invoking the "play" operation defined 2008 in the "example-jukebox" YANG module. 2010 A client might send a "play" request as follows: 2012 POST /restconf/operations/example-jukebox:play HTTP/1.1 2013 Host: example.com 2014 Content-Type: application/yang-data+json 2016 { 2017 "example-jukebox:input" : { 2018 "playlist" : "Foo-One", 2019 "song-number" : 2 2020 } 2021 } 2023 The server might respond: 2025 HTTP/1.1 204 No Content 2026 Date: Mon, 23 Apr 2016 17:50:00 GMT 2027 Server: example-server 2029 4.5. PUT 2031 The RESTCONF server MUST support the PUT method. The PUT method is 2032 sent by the client to create or replace the target data resource. A 2033 request message-body MUST be present, representing the new data 2034 resource, or the server MUST return "400 Bad Request" status-line. 2035 The error-tag value "invalid-value" is used in this case. 2037 Both the POST and PUT methods can be used to create data resources. 2038 The difference is that for POST, the client does not provide the 2039 resource identifier for the resource that will be created. The 2040 target resource for the POST method for resource creation is the 2041 parent of the new resource. The target resource for the PUT method 2042 for resource creation is the new resource. 2044 The PUT method MUST be supported for data and datastore resources. A 2045 PUT on the datastore resource is used to replace the entire contents 2046 of the datastore. A PUT on a data resource only replaces that data 2047 resource within the datastore. 2049 The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query 2050 parameters MUST be supported by the PUT method for data resources. 2051 These parameters are only allowed if the list or leaf-list is 2052 ordered-by user. 2054 Consistent with [RFC7231], if the PUT request creates a new resource, 2055 a "201 Created" status-line is returned. If an existing resource is 2056 modified, a "204 No Content" status-line is returned. 2058 If the user is not authorized to create or replace the target 2059 resource an error response containing a "403 Forbidden" status-line 2060 SHOULD be returned. The error-tag value "access-denied" is used in 2061 this case. 2063 A server MAY return a "404 Not Found" status-line, as 2064 described in section 6.5.3 in ^RFC7231^. 2065 The error-tag value "invalid-value" is used in this case. 2066 All other error responses are handled according to 2067 the procedures defined in ^error-reporting^. 2069 If the target resource represents a YANG leaf-list, then the PUT 2070 method MUST NOT change the value of the leaf-list instance. 2072 If the target resource represents a YANG list instance, then the key 2073 leaf values in message-body representation MUST be the same as the 2074 key leaf values in the request URI. The PUT method MUST NOT be used 2075 to change the key leaf values for a data resource instance. 2077 Example: 2079 An "album" child resource defined in the "example-jukebox" YANG 2080 module is replaced or created if it does not already exist. 2082 To replace the "album" resource contents, the client might send as 2083 follows: 2085 PUT /restconf/data/example-jukebox:jukebox/\ 2086 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2087 Host: example.com 2088 Content-Type: application/yang-data+json 2090 { 2091 "example-jukebox:album" : [ 2092 { 2093 "name" : "Wasting Light", 2094 "genre" : "example-jukebox:alternative", 2095 "year" : 2011 2096 } 2097 ] 2098 } 2100 If the resource is updated, the server might respond: 2102 HTTP/1.1 204 No Content 2103 Date: Mon, 23 Apr 2016 17:04:00 GMT 2104 Server: example-server 2105 Last-Modified: Mon, 23 Apr 2016 17:04:00 GMT 2106 ETag: "b27480aeda4c" 2108 The same request is shown here using XML encoding: 2110 PUT /restconf/data/example-jukebox:jukebox/\ 2111 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2112 Host: example.com 2113 Content-Type: application/yang-data+xml 2115 2117 Wasting Light 2118 jbox:alternative 2119 2011 2120 2122 Refer to Appendix D.2.4 for an example using the PUT method to 2123 replace the contents of the datastore resource. 2125 4.6. PATCH 2127 The RESTCONF server MUST support the PATCH method for a plain patch, 2128 and MAY support additional media types. The PATCH media types 2129 supported by a server can be discovered by the client by sending an 2130 OPTIONS request, and examining the Accept-Patch header field in the 2131 response. (see Section 4.1). 2133 RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide 2134 an extensible framework for resource patching mechanisms. Each patch 2135 mechanism needs a unique media type. 2137 This document defines one patch mechanism (Section 4.6.1). Another 2138 patch mechanism, the YANG PATCH mechanism, is defined in 2139 [I-D.ietf-netconf-yang-patch]. Other patch mechanisms may be defined 2140 by future specifications. 2142 If the target resource instance does not exist, the server MUST NOT 2143 create it. 2145 If the PATCH request succeeds, a "200 OK" status-line is returned if 2146 there is a message-body, and "204 No Content" is returned if no 2147 response message-body is sent. 2149 If the user is not authorized to alter the target resource an error 2150 response containing a "403 Forbidden" status-line SHOULD be returned. 2151 A server MAY return a "404 Not Found" status-line, as described in 2152 section 6.5.3 in [RFC7231]. The error-tag value "invalid-value" is 2153 used in this case. All other error responses are handled according 2154 to the procedures defined in Section 7. 2156 4.6.1. Plain Patch 2158 The plain patch mechanism merges the contents of the message-body 2159 with the target resource. The message-body for a plain patch MUST be 2160 present and MUST be represented by the media type "application/ 2161 yang-data+xml" or "application/yang-data+json". 2163 Plain patch can be used to create or update, but not delete, a child 2164 resource within the target resource. Please see 2165 [I-D.ietf-netconf-yang-patch] for an alternate media-type supporting 2166 the ability to delete child resources. The YANG Patch Media Type 2167 allows multiple sub-operations (e.g., merge, delete) within a single 2168 PATCH method. 2170 If the target resource represents a YANG leaf-list, then the PATCH 2171 method MUST NOT change the value of the leaf-list instance. 2173 If the target resource represents a YANG list instance, then the key 2174 leaf values in message-body representation MUST be the same as the 2175 key leaf values in the request URI. The PATCH method MUST NOT be 2176 used to change the key leaf values for a data resource instance. 2178 After the plain patch is processed by the server a response will be 2179 returned to the client, as specified in Section 4.6. 2181 Example: 2183 To replace just the "year" field in the "album" resource (instead of 2184 replacing the entire resource with the PUT method), the client might 2185 send a plain patch as follows. 2187 PATCH /restconf/data/example-jukebox:jukebox/\ 2188 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2189 Host: example.com 2190 If-Match: "b8389233a4c" 2191 Content-Type: application/yang-data+xml 2193 2194 2011 2195 2197 If the field is updated, the server might respond: 2199 HTTP/1.1 204 No Content 2200 Date: Mon, 23 Apr 2016 17:49:30 GMT 2201 Server: example-server 2202 Last-Modified: Mon, 23 Apr 2016 17:49:30 GMT 2203 ETag: "b2788923da4c" 2205 4.7. DELETE 2207 The RESTCONF server MUST support the DELETE method. The DELETE 2208 method is used to delete the target resource. If the DELETE request 2209 succeeds, a "204 No Content" status-line is returned. 2211 If the user is not authorized to delete the target resource then an 2212 error response containing a "403 Forbidden" status-line SHOULD be 2213 returned. The error-tag value "access-denied" is returned in this 2214 case. A server MAY return a "404 Not Found" status-line, as 2215 described in section 6.5.3 in [RFC7231]. The error-tag value 2216 "invalid-value" is returned in this case. All other error responses 2217 are handled according to the procedures defined in Section 7. 2219 If the target resource represents a configuration leaf-list or list 2220 data node, then it MUST represent a single YANG leaf-list or list 2221 instance. The server MUST NOT use the DELETE method to delete more 2222 than one such instance. 2224 Example: 2226 To delete the "album" resource with the key "Wasting Light", the 2227 client might send: 2229 DELETE /restconf/data/example-jukebox:jukebox/\ 2230 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 2231 Host: example.com 2233 If the resource is deleted, the server might respond: 2235 HTTP/1.1 204 No Content 2236 Date: Mon, 23 Apr 2016 17:49:40 GMT 2237 Server: example-server 2239 4.8. Query Parameters 2241 Each RESTCONF operation allows zero or more query parameters to be 2242 present in the request URI. The specific parameters that are allowed 2243 depends on the resource type, and sometimes the specific target 2244 resource used, in the request. 2246 o Query parameters can be given in any order. 2248 o Each parameter can appear at most once in a request URI. 2250 o If more than one instance of a query parameter is present, then a 2251 "400 Bad Request" status-line MUST be returned by the server. The 2252 error-tag value "invalid-value" is returned in this case. 2254 o A default value may apply if the parameter is missing. 2256 o Query parameter names and values are case-sensitive 2258 o A server MUST return an error with a '400 Bad Request' status-line 2259 if a query parameter is unexpected. The error-tag value 2260 "invalid-value" is returned in this case. 2262 +---------------+---------+-----------------------------------------+ 2263 | Name | Methods | Description | 2264 +---------------+---------+-----------------------------------------+ 2265 | content | GET, | Select config and/or non-config data | 2266 | | HEAD | resources | 2267 | depth | GET, | Request limited sub-tree depth in the | 2268 | | HEAD | reply content | 2269 | fields | GET, | Request a subset of the target resource | 2270 | | HEAD | contents | 2271 | filter | GET, | Boolean notification filter for event | 2272 | | HEAD | stream resources | 2273 | insert | POST, | Insertion mode for ordered-by user data | 2274 | | PUT | resources | 2275 | point | POST, | Insertion point for ordered-by user | 2276 | | PUT | data resources | 2277 | start-time | GET, | Replay buffer start time for event | 2278 | | HEAD | stream resources | 2279 | stop-time | GET, | Replay buffer stop time for event | 2280 | | HEAD | stream resources | 2281 | with-defaults | GET, | Control retrieval of default values | 2282 | | HEAD | | 2283 +---------------+---------+-----------------------------------------+ 2285 RESTCONF Query Parameters 2287 Refer to Appendix D.3 for examples of query parameter usage. 2289 If vendors define additional query parameters, they SHOULD use a 2290 prefix (such as the enterprise or organization name) for query 2291 parameter names in order to avoid collisions with other parameters. 2293 4.8.1. The "content" Query Parameter 2295 The "content" parameter controls how descendant nodes of the 2296 requested data nodes will be processed in the reply. 2298 The allowed values are: 2300 +-----------+-----------------------------------------------------+ 2301 | Value | Description | 2302 +-----------+-----------------------------------------------------+ 2303 | config | Return only configuration descendant data nodes | 2304 | nonconfig | Return only non-configuration descendant data nodes | 2305 | all | Return all descendant data nodes | 2306 +-----------+-----------------------------------------------------+ 2308 This parameter is only allowed for GET methods on datastore and data 2309 resources. A "400 Bad Request" status-line is returned if used for 2310 other methods or resource types. 2312 If this query parameter is not present, the default value is "all". 2313 This query parameter MUST be supported by the server. 2315 4.8.2. The "depth" Query Parameter 2317 The "depth" parameter is used to limit the depth of subtrees returned 2318 by the server. Data nodes with a depth value greater than the 2319 "depth" parameter are not returned in a response for a GET method. 2321 The requested data node has a depth level of '1'. If the "fields" 2322 parameter (Section 4.8.3) is used to select descendant data nodes, 2323 then these nodes and all their ancestor nodes have a depth value of 2324 1. (This has the effect of including the nodes specified by the 2325 fields, even if the "depth" value is less than the actual depth level 2326 of the specified fields.) Any other child node has a depth value 2327 that is 1 greater than its parent. 2329 The value of the "depth" parameter is either an integer between 1 and 2330 65535, or the string "unbounded". "unbounded" is the default. 2332 This parameter is only allowed for GET methods on API, datastore, and 2333 data resources. A "400 Bad Request" status-line is returned if it 2334 used for other methods or resource types. 2336 By default, the server will include all sub-resources within a 2337 retrieved resource, which have the same resource type as the 2338 requested resource. The exception is the datastore resource. If 2339 this resource type is retrieved then by default the datastore and all 2340 child data resources are returned. 2342 If the "depth" query parameter URI is listed in the "capability" 2343 leaf-list in Section 9.3, then the server supports the "depth" query 2344 parameter. 2346 4.8.3. The "fields" Query Parameter 2348 The "fields" query parameter is used to optionally identify data 2349 nodes within the target resource to be retrieved in a GET method. 2350 The client can use this parameter to retrieve a subset of all nodes 2351 in a resource. 2353 The server will return a message-body representing the target 2354 resource, with descendant nodes pruned as specified in the 2355 "fields-expr" value. The server does not return a set of separate 2356 sub-resources. 2358 A value of the "fields" query parameter matches the following rule: 2360 fields-expr = path '(' fields-expr ')' / 2361 path ';' fields-expr / 2362 path 2363 path = api-identifier [ '/' path ] 2365 "api-identifier" is defined in Section 3.5.3.1. 2367 ";" is used to select multiple nodes. For example, to retrieve only 2368 the "genre" and "year" of an album, use: "fields=genre;year". 2370 Parentheses are used to specify sub-selectors of a node. Note that 2371 there is no path separator character '/' between a "path" field and 2372 left parenthesis character '('. 2374 For example, assume the target resource is the "album" list. To 2375 retrieve only the "label" and "catalogue-number" of the "admin" 2376 container within an album, use: 2377 "fields=admin(label;catalogue-number)". 2379 "/" is used in a path to retrieve a child node of a node. For 2380 example, to retrieve only the "label" of an album, use: 2381 "fields=admin/label". 2383 This parameter is only allowed for GET methods on api, datastore, and 2384 data resources. A "400 Bad Request" status-line is returned if used 2385 for other methods or resource types. 2387 If the "fields" query parameter URI is listed in the "capability" 2388 leaf-list in Section 9.3, then the server supports the "fields" 2389 parameter. 2391 4.8.4. The "filter" Query Parameter 2393 The "filter" parameter is used to indicate which subset of all 2394 possible events are of interest. If not present, all events not 2395 precluded by other parameters will be sent. 2397 This parameter is only allowed for GET methods on an event stream 2398 resource. A "400 Bad Request" status-line is returned if used for 2399 other methods or resource types. 2401 The format of this parameter is an XPath 1.0 expression [XPath], and 2402 is evaluated in the following context: 2404 o The set of namespace declarations is the set of prefix and 2405 namespace pairs for all supported YANG modules, where the prefix 2406 is the YANG module name, and the namespace is as defined by the 2407 "namespace" statement in the YANG module. 2409 o The function library is the core function library defined in XPath 2410 1.0, plus any functions defined by the data model. 2412 o The set of variable bindings is empty. 2414 o The context node is the root node. 2416 The filter is used as defined in [RFC5277], Section 3.6. If the 2417 boolean result of the expression is true when applied to the 2418 conceptual "notification" document root, then the event notification 2419 is delivered to the client. 2421 If the "filter" query parameter URI is listed in the "capability" 2422 leaf-list in Section 9.3, then the server supports the "filter" query 2423 parameter. 2425 4.8.5. The "insert" Query Parameter 2427 The "insert" parameter is used to specify how a resource should be 2428 inserted within a ordered-by user list. 2430 The allowed values are: 2432 +--------+----------------------------------------------------------+ 2433 | Value | Description | 2434 +--------+----------------------------------------------------------+ 2435 | first | Insert the new data as the new first entry. | 2436 | last | Insert the new data as the new last entry. | 2437 | before | Insert the new data before the insertion point, as | 2438 | | specified by the value of the "point" parameter. | 2439 | after | Insert the new data after the insertion point, as | 2440 | | specified by the value of the "point" parameter. | 2441 +--------+----------------------------------------------------------+ 2443 The default value is "last". 2445 This parameter is only supported for the POST and PUT methods. It is 2446 also only supported if the target resource is a data resource, and 2447 that data represents a YANG list or leaf-list that is ordered-by 2448 user. 2450 If the values "before" or "after" are used, then a "point" query 2451 parameter for the insertion parameter MUST also be present, or a "400 2452 Bad Request" status-line is returned. 2454 The "insert" query parameter MUST be supported by the server. 2456 4.8.6. The "point" Query Parameter 2458 The "point" parameter is used to specify the insertion point for a 2459 data resource that is being created or moved within an ordered-by 2460 user list or leaf-list. 2462 The value of the "point" parameter is a string that identifies the 2463 path to the insertion point object. The format is the same as a 2464 target resource URI string. 2466 This parameter is only supported for the POST and PUT methods. It is 2467 also only supported if the target resource is a data resource, and 2468 that data represents a YANG list or leaf-list that is ordered-by 2469 user. 2471 If the "insert" query parameter is not present, or has a value other 2472 than "before" or "after", then a "400 Bad Request" status-line is 2473 returned. 2475 This parameter contains the instance identifier of the resource to be 2476 used as the insertion point for a POST or PUT method. 2478 The "point" query parameter MUST be supported by the server. 2480 4.8.7. The "start-time" Query Parameter 2482 The "start-time" parameter is used to trigger the notification replay 2483 feature defined in [RFC5277] and indicate that the replay should 2484 start at the time specified. If the stream does not support replay, 2485 per the "replay-support" attribute returned by stream list entry for 2486 the stream resource, then the server MUST return a "400 Bad Request" 2487 status-line. 2489 The value of the "start-time" parameter is of type "date-and-time", 2490 defined in the "ietf-yang" YANG module [RFC6991]. 2492 This parameter is only allowed for GET methods on a text/event-stream 2493 data resource. A "400 Bad Request" status-line is returned if used 2494 for other methods or resource types. 2496 If this parameter is not present, then a replay subscription is not 2497 being requested. It is not valid to specify start times that are 2498 later than the current time. If the value specified is earlier than 2499 the log can support, the replay will begin with the earliest 2500 available notification. A client can obtain a server's current time 2501 by examining the "Date" header field that the server returns in 2502 response messages, according to [RFC7231]. 2504 If this query parameter is supported by the server, then the "replay" 2505 query parameter URI MUST be listed in the "capability" leaf-list in 2506 Section 9.3, anf the "stop-time" query parameter MUST also be 2507 supported by the server. 2509 If the "replay-support" leaf has the value 'true' in the "stream" 2510 entry (defined in Section 9.3) then the server MUST support the 2511 "start-time" and "stop-time" query parameters for that stream. 2513 4.8.8. The "stop-time" Query Parameter 2515 The "stop-time" parameter is used with the replay feature to indicate 2516 the newest notifications of interest. This parameter MUST be used 2517 with and have a value later than the "start-time" parameter. 2519 The value of the "stop-time" parameter is of type "date-and-time", 2520 defined in the "ietf-yang" YANG module [RFC6991]. 2522 This parameter is only allowed for GET methods on a text/event-stream 2523 data resource. A "400 Bad Request" status-line is returned if used 2524 for other methods or resource types. 2526 If this parameter is not present, the notifications will continue 2527 until the subscription is terminated. Values in the future are 2528 valid. 2530 If this query parameter is supported by the server, then the "replay" 2531 query parameter URI MUST be listed in the "capability" leaf-list in 2532 Section 9.3, and the "start-time" query parameter MUST also be 2533 supported by the server. 2535 If the "replay-support" leaf is present in the "stream" entry 2536 (defined in Section 9.3) then the server MUST support the 2537 "start-time" and "stop-time" query parameters for that stream. 2539 4.8.9. The "with-defaults" Query Parameter 2541 The "with-defaults" parameter is used to specify how information 2542 about default data nodes should be returned in response to GET 2543 requests on data resources. 2545 If the server supports this capability, then it MUST implement the 2546 behavior in Section 4.5.1 of [RFC6243], except applied to the 2547 RESTCONF GET operation, instead of the NETCONF operations. 2549 +-------------------+-----------------------------------------------+ 2550 | Value | Description | 2551 +-------------------+-----------------------------------------------+ 2552 | report-all | All data nodes are reported | 2553 | trim | Data nodes set to the YANG default are not | 2554 | | reported | 2555 | explicit | Data nodes set to the YANG default by the | 2556 | | client are reported | 2557 | report-all-tagged | All data nodes are reported and defaults are | 2558 | | tagged | 2559 +-------------------+-----------------------------------------------+ 2561 If the "with-defaults" parameter is set to "report-all" then the 2562 server MUST adhere to the defaults reporting behavior defined in 2563 Section 3.1 of [RFC6243]. 2565 If the "with-defaults" parameter is set to "trim" then the server 2566 MUST adhere to the defaults reporting behavior defined in Section 3.2 2567 of [RFC6243]. 2569 If the "with-defaults" parameter is set to "explicit" then the server 2570 MUST adhere to the defaults reporting behavior defined in Section 3.3 2571 of [RFC6243]. 2573 If the "with-defaults" parameter is set to "report-all-tagged" then 2574 the server MUST adhere to the defaults reporting behavior defined in 2575 Section 3.4 of [RFC6243]. Metadata is reported by the server as 2576 specified in Section 5.3. The XML encoding for the "default" 2577 attribute sent by the server for default nodes is defined in section 2578 6 of [RFC6243]. The JSON encoding for the "default" attribute MUST 2579 use the same values as defined in [RFC6243], but encoded according to 2580 the rules in [RFC7952]. The module name "ietf-netconf-with-defaults" 2581 MUST be used for the "default" attribute. 2583 If the "with-defaults" parameter is not present then the server MUST 2584 adhere to the defaults reporting behavior defined in its "basic-mode" 2585 parameter for the "defaults" protocol capability URI, defined in 2586 Section 9.1.2. 2588 If the server includes the "with-defaults" query parameter URI in the 2589 "capability" leaf-list in Section 9.3, then the "with-defaults" query 2590 parameter MUST be supported. 2592 Since the server does not report the "also-supported" parameter as 2593 described in section 4.3 of [RFC6243], it is possible that some 2594 values for the "with-defaults" parameter will not be supported. If 2595 the server does not support the requested value of the 2596 "with-defaults" parameter, the server MUST return a response with a 2597 "400 Bad Request" status-line. The error-tag value "invalid-value" 2598 is used in this case. 2600 5. Messages 2602 The RESTCONF protocol uses HTTP messages. A single HTTP message 2603 corresponds to a single protocol method. Most messages can perform a 2604 single task on a single resource, such as retrieving a resource or 2605 editing a resource. The exception is the PATCH method, which allows 2606 multiple datastore edits within a single message. 2608 5.1. Request URI Structure 2610 Resources are represented with URIs following the structure for 2611 generic URIs in [RFC3986]. 2613 A RESTCONF operation is derived from the HTTP method and the request 2614 URI, using the following conceptual fields: 2616 //? 2618 ^ ^ ^ ^ 2619 | | | | 2620 method entry resource query 2622 M M O O 2624 M=mandatory, O=optional 2626 where: 2628 is the HTTP method 2629 is the RESTCONF root resource 2630 is the Target Resource URI 2631 is the query parameter list 2633 o method: the HTTP method identifying the RESTCONF operation 2634 requested by the client, to act upon the target resource specified 2635 in the request URI. RESTCONF operation details are described in 2636 Section 4. 2638 o entry: the root of the RESTCONF API configured on this HTTP 2639 server, discovered by getting the "/.well-known/host-meta" 2640 resource, as described in Section 3.1. 2642 o resource: the path expression identifying the resource that is 2643 being accessed by the RESTCONF operation. If this field is not 2644 present, then the target resource is the API itself, represented 2645 by the YANG data template named "yang-api", found in Section 8. 2647 o query: the set of parameters associated with the RESTCONF message, 2648 as defined in section 3.4 of [RFC3986]. RESTCONF parameters have 2649 the familiar form of "name=value" pairs. Most query parameters 2650 are optional to implement by the server and optional to use by the 2651 client. Each optional query parameter is identified by a URI. 2652 The server MUST list the optional query parameter URIs it supports 2653 in the "capabilities" list defined in Section 9.3. 2655 There is a specific set of parameters defined, although the server 2656 MAY choose to support query parameters not defined in this document. 2657 The contents of the any query parameter value MUST be encoded 2658 according to [RFC3986], Section 3.4. Any reserved characters MUST be 2659 percent-encoded, according to [RFC3986], section 2.1 and 2.5. 2661 Note that the fragment component not used by the RESTCONF protocol. 2662 The fragment is excluded from the target URI by a server, as 2663 described in section 5.1 of [RFC7230]. 2665 When new resources are created by the client, a "Location" header 2666 field is returned, which identifies the path of the newly created 2667 resource. The client uses this exact path identifier to access the 2668 resource once it has been created. 2670 The "target" of a RESTCONF operation is a resource. The "path" field 2671 in the request URI represents the target resource for the RESTCONF 2672 operation. 2674 Refer to Appendix D for examples of RESTCONF Request URIs. 2676 5.2. Message Encoding 2678 RESTCONF messages are encoded in HTTP according to [RFC7230]. The 2679 "utf-8" character set is used for all messages. RESTCONF message 2680 content is sent in the HTTP message-body. 2682 Content is encoded in either JSON or XML format. A server MUST 2683 support one of either XML or JSON encoding. A server MAY support 2684 both XML and JSON encoding. A client will need to support both XML 2685 and JSON to interoperate with all RESTCONF servers. 2687 XML encoding rules for data nodes are defined in [RFC7950]. The same 2688 encoding rules are used for all XML content. JSON encoding rules are 2689 defined in [RFC7951]. Additional JSON encoding rules for metadata 2690 are defined in [RFC7952]. This encoding is valid JSON, but also has 2691 special encoding rules to identify module namespaces and provide 2692 consistent type processing of YANG data. 2694 Request input content encoding format is identified with the Content- 2695 Type header field. This field MUST be present if a message-body is 2696 sent by the client. 2698 The server MUST support the "Accept" header field and "406 Not 2699 Acceptable" status-line, as defined in [RFC7231]. The response 2700 output content encoding formats that the client will accept are 2701 identified with the Accept header field in the request. If it is not 2702 specified, the request input encoding format SHOULD be used, or the 2703 server MAY choose any supported content encoding format. 2705 If there was no request input, then the default output encoding is 2706 XML or JSON, depending on server preference. File extensions encoded 2707 in the request are not used to identify format encoding. 2709 A client can determine if the RESTCONF server supports an encoding 2710 format by sending a request using a specific format in the Content- 2711 Type and/or Accept header field. If the server does not support the 2712 requested input encoding for a request, then it MUST return an error 2713 response with a '415 Unsupported Media Type' status-line. If the 2714 server does not support any of the requested output encodings for a 2715 request, then it MUST return an error response with a '406 Not 2716 Acceptable' status-line. 2718 5.3. RESTCONF Metadata 2720 The RESTCONF protocol needs to support retrieval of the same metadata 2721 that is used in the NETCONF protocol. Information about default 2722 leafs, last-modified timestamps, etc. are commonly used to annotate 2723 representations of the datastore contents. 2725 With the XML encoding, the metadata is encoded as attributes in XML, 2726 according to section 3.3 of [W3C.REC-xml-20081126]. With the JSON 2727 encoding, the metadata is encoded as specified in [RFC7952]. 2729 The following examples are based on the example in Appendix D.3.9. 2730 The "report-all-tagged" mode for the "with-defaults" query parameter 2731 requires that a "default" attribute be returned for default nodes. 2732 This example shows that attribute for the "mtu" leaf . 2734 5.3.1. XML Metadata Encoding Example 2736 GET /restconf/data/interfaces/interface=eth1 2737 ?with-defaults=report-all-tagged HTTP/1.1 2738 Host: example.com 2739 Accept: application/yang-data+xml 2741 The server might respond as follows. 2743 HTTP/1.1 200 OK 2744 Date: Mon, 23 Apr 2016 17:01:00 GMT 2745 Server: example-server 2746 Content-Type: application/yang-data+xml 2748 2750 eth1 2751 1500 2753 up 2754 2756 5.3.2. JSON Metadata Encoding Example 2758 Note that RFC 6243 defines the "default" attribute with XSD, not 2759 YANG, so the YANG module name has to be assigned instead of derived 2760 from the YANG module. The value "ietf-netconf-with-defaults" is 2761 assigned for JSON metadata encoding. 2763 GET /restconf/data/interfaces/interface=eth1\ 2764 ?with-defaults=report-all-tagged HTTP/1.1 2765 Host: example.com 2766 Accept: application/yang-data+json 2768 The server might respond as follows. 2770 HTTP/1.1 200 OK 2771 Date: Mon, 23 Apr 2016 17:01:00 GMT 2772 Server: example-server 2773 Content-Type: application/yang-data+json 2775 { 2776 "example:interface" : [ 2777 { 2778 "name" : "eth1", 2779 "mtu" : 1500, 2780 "@mtu" : { 2781 "ietf-netconf-with-defaults:default" : true 2782 }, 2783 "status" : "up" 2784 } 2785 ] 2786 } 2788 5.4. Return Status 2790 Each message represents some sort of resource access. An HTTP 2791 "status-line" header field is returned for each request. If a "4xx" 2792 range status code is returned in the status-line, then the error 2793 information SHOULD be returned in the response, according to the 2794 format defined in Section 7.1. If a "5xx" range status code is 2795 returned in the status-line, then the error information MAY be 2796 returned in the response, according to the format defined in 2797 Section 7.1. If a 1xx, 2xx, or 3xx range status code is returned in 2798 the status-line, then error information MUST NOT be returned in the 2799 response, since these ranges do not represent error conditions. 2801 5.5. Message Caching 2803 Since the datastore contents change at unpredictable times, responses 2804 from a RESTCONF server generally SHOULD NOT be cached. 2806 The server MUST include a "Cache-Control" header field in every 2807 response that specifies whether the response should be cached. 2809 Instead of relying on HTTP caching, the client SHOULD track the 2810 "ETag" and/or "Last-Modified" header fields returned by the server 2811 for the datastore resource (or data resource if the server supports 2812 it). A retrieval request for a resource can include the 2813 "If-None-Match" and/or "If-Modified-Since" header fields, which will 2814 cause the server to return a "304 Not Modified" status-line if the 2815 resource has not changed. The client MAY use the HEAD method to 2816 retrieve just the message header fields, which SHOULD include the 2817 "ETag" and "Last-Modified" header fields, if this metadata is 2818 maintained for the target resource. 2820 Note that the way that access control is applied to data resources 2821 the values in the Last-Modified and ETag headers maintained for a 2822 data resource may not be reliable, as described in Section 4.3. 2824 6. Notifications 2826 The RESTCONF protocol supports YANG-defined event notifications. The 2827 solution preserves aspects of NETCONF Event Notifications [RFC5277] 2828 while utilizing the Server-Sent Events [W3C.REC-eventsource-20150203] 2829 transport strategy. 2831 6.1. Server Support 2833 A RESTCONF server MAY support RESTCONF notifications. Clients may 2834 determine if a server supports RESTCONF notifications by using the 2835 HTTP method OPTIONS, HEAD, or GET on the stream list. The server 2836 does not support RESTCONF notifications if an HTTP error code is 2837 returned (e.g., "404 Not Found" status-line). 2839 6.2. Event Streams 2841 A RESTCONF server that supports notifications will populate a stream 2842 resource for each notification delivery service access point. A 2843 RESTCONF client can retrieve the list of supported event streams from 2844 a RESTCONF server using the GET method on the stream list. 2846 The "restconf-state/streams" container definition in the 2847 "ietf-restconf-monitoring" module (defined in Section 9.3) is used to 2848 specify the structure and syntax of the conceptual child resources 2849 within the "streams" resource. 2851 For example: 2853 The client might send the following request: 2855 GET /restconf/data/ietf-restconf-monitoring:restconf-state/\ 2856 streams HTTP/1.1 2857 Host: example.com 2858 Accept: application/yang-data+xml 2860 The server might send the following response: 2862 HTTP/1.1 200 OK 2863 Content-Type: application/yang-data+xml 2864 2866 2867 NETCONF 2868 default NETCONF event stream 2869 true 2870 \ 2871 2007-07-08T00:00:00Z\ 2872 2873 2874 xml 2875 https://example.com/streams/NETCONF\ 2876 2877 2878 2879 json 2880 https://example.com/streams/NETCONF-JSON\ 2881 2882 2883 2884 2885 SNMP 2886 SNMP notifications 2887 false 2888 2889 xml 2890 https://example.com/streams/SNMP 2891 2892 2893 2894 syslog-critical 2895 Critical and higher severity 2896 true 2897 2898 2007-07-01T00:00:00Z 2899 2900 2901 xml 2902 \ 2903 https://example.com/streams/syslog-critical\ 2904 2905 2906 2907 2909 6.3. Subscribing to Receive Notifications 2911 RESTCONF clients can determine the URL for the subscription resource 2912 (to receive notifications) by sending an HTTP GET request for the 2913 "location" leaf with the stream list entry. The value returned by 2914 the server can be used for the actual notification subscription. 2916 The client will send an HTTP GET request for the URL returned by the 2917 server with the "Accept" type "text/event-stream". 2919 The server will treat the connection as an event stream, using the 2920 Server Sent Events [W3C.REC-eventsource-20150203] transport strategy. 2922 The server MAY support query parameters for a GET method on this 2923 resource. These parameters are specific to each event stream. 2925 For example: 2927 The client might send the following request: 2929 GET /restconf/data/ietf-restconf-monitoring:restconf-state/\ 2930 streams/stream=NETCONF/access=xml/location HTTP/1.1 2931 Host: example.com 2932 Accept: application/yang-data+xml 2934 The server might send the following response: 2936 HTTP/1.1 200 OK 2937 Content-Type: application/yang-data+xml 2939 \ 2941 https://example.com/streams/NETCONF\ 2942 2944 The RESTCONF client can then use this URL value to start monitoring 2945 the event stream: 2947 GET /streams/NETCONF HTTP/1.1 2948 Host: example.com 2949 Accept: text/event-stream 2950 Cache-Control: no-cache 2951 Connection: keep-alive 2953 A RESTCONF client MAY request that the server compress the events 2954 using the HTTP header field "Accept-Encoding". For instance: 2956 GET /streams/NETCONF HTTP/1.1 2957 Host: example.com 2958 Accept: text/event-stream 2959 Cache-Control: no-cache 2960 Connection: keep-alive 2961 Accept-Encoding: gzip, deflate 2963 6.3.1. NETCONF Event Stream 2965 The server SHOULD support the "NETCONF" event stream defined in 2966 section 3.2.3 of [RFC5277]. The notification messages for this 2967 stream are encoded in XML. 2969 The server MAY support additional streams which represent the 2970 semantic content of the NETCONF event stream, but using a 2971 representation with a different media type. 2973 The server MAY support the "start-time", "stop-time", and "filter" 2974 query parameters, defined in Section 4.8. Refer to Appendix D.3.6 2975 for filter parameter examples. 2977 6.4. Receiving Event Notifications 2979 RESTCONF notifications are encoded according to the definition of the 2980 event stream. 2982 The structure of the event data is based on the "notification" 2983 element definition in Section 4 of [RFC5277]. It MUST conform to the 2984 schema for the "notification" element in Section 4 of [RFC5277] using 2985 the XML namespace as defined in the XSD as follows: 2987 urn:ietf:params:xml:ns:netconf:notification:1.0 2989 For JSON encoding purposes, the module name for the "notification" 2990 element is "ietf-restconf". 2992 Two child nodes within the "notification" container are expected, 2993 representing the event time and the event payload. The "eventTime" 2994 node is defined within the same XML namespace as the "notification" 2995 element. It is defined to be within the "ietf-restconf" module 2996 namespace for JSON encoding purposes. 2998 The name and namespace of the payload element are determined by the 2999 YANG module containing the notification-stmt representing the 3000 notification message. 3002 In the following example, the YANG module "example-mod" is used: 3004 module example-mod { 3005 namespace "http://example.com/event/1.0"; 3006 prefix ex; 3008 notification event { 3009 leaf event-class { type string; } 3010 container reporting-entity { 3011 leaf card { type string; } 3012 } 3013 leaf severity { type string; } 3014 } 3015 } 3017 An example SSE event notification encoded using XML: 3019 data: 3021 data: 2013-12-21T00:01:00Z 3022 data: 3023 data: fault 3024 data: 3025 data: Ethernet0 3026 data: 3027 data: major 3028 data: 3029 data: 3031 An example SSE event notification encoded using JSON: 3033 data: { 3034 data: "ietf-restconf:notification" : { 3035 data: "eventTime" : "2013-12-21T00:01:00Z", 3036 data: "example-mod:event" : { 3037 data: "event-class" : "fault", 3038 data: "reporting-entity" : { "card" : "Ethernet0" }, 3039 data: "severity" : "major" 3040 data: } 3041 data: } 3042 data: } 3044 Alternatively, since neither XML nor JSON are whitespace sensitive, 3045 the above messages can be encoded onto a single line. For example: 3047 For example: 3049 XML: 3051 data: 2013-12-21T00:01:00ZfaultEthernet0\ 3055 major 3057 JSON: 3059 data: {"ietf-restconf:notification":{"eventTime":"2013-12-21\ 3060 T00:01:00Z","example-mod:event":{"event-class": "fault","repor\ 3061 tingEntity":{"card":"Ethernet0"},"severity":"major"}}} 3063 The SSE specifications supports the following additional fields: 3064 event, id and retry. A RESTCONF server MAY send the "retry" field 3065 and, if it does, RESTCONF clients SHOULD use it. A RESTCONF server 3066 SHOULD NOT send the "event" or "id" fields, as there are no 3067 meaningful values that could be used for them that would not be 3068 redundant to the contents of the notification itself. RESTCONF 3069 servers that do not send the "id" field also do not need to support 3070 the HTTP header field "Last-Event-Id". RESTCONF servers that do send 3071 the "id" field SHOULD support the "start-time" query parameter as the 3072 preferred means for a client to specify where to restart the event 3073 stream. 3075 7. Error Reporting 3077 HTTP status codes are used to report success or failure for RESTCONF 3078 operations. The error information that NETCONF error responses 3079 contain in the element is adapted for use in RESTCONF, 3080 and an data tree information is returned for "4xx" and "5xx" 3081 class of status codes. 3083 Since an operation resource is defined with a YANG "rpc" statement, 3084 and an action is defined with a YANG "action" statement, a mapping 3085 from the NETCONF value to the HTTP status code is needed. 3086 The specific error-tag and response code to use are data-model- 3087 specific and might be contained in the YANG "description" statement 3088 for the "action" or "rpc" statement. 3090 +-------------------------+-----------------+ 3091 | error-tag | status code | 3092 +-------------------------+-----------------+ 3093 | in-use | 409 | 3094 | invalid-value | 400, 404 or 406 | 3095 | (request) too-big | 413 | 3096 | (response) too-big | 400 | 3097 | missing-attribute | 400 | 3098 | bad-attribute | 400 | 3099 | unknown-attribute | 400 | 3100 | bad-element | 400 | 3101 | unknown-element | 400 | 3102 | unknown-namespace | 400 | 3103 | access-denied | 401, 403 | 3104 | lock-denied | 409 | 3105 | resource-denied | 409 | 3106 | rollback-failed | 500 | 3107 | data-exists | 409 | 3108 | data-missing | 409 | 3109 | operation-not-supported | 405 or 501 | 3110 | operation-failed | 412 or 500 | 3111 | partial-operation | 500 | 3112 | malformed-message | 400 | 3113 +-------------------------+-----------------+ 3115 Mapping from error-tag to status code 3117 7.1. Error Response Message 3119 When an error occurs for a request message on any resource type, and 3120 the status code that will be returned is in the "4xx" range (except 3121 for status code "403 Forbidden"), then the server SHOULD send a 3122 response message-body containing the information described by the 3123 "yang-errors" YANG data template within the "ietf-restconf" module, 3124 found in Section 8. The Content-Type of this response message MUST 3125 be "application/yang-data", plus optionally a structured syntax name 3126 suffix. 3128 The client SHOULD specify the desired encoding(s) for response 3129 messages by specifying the appropriate media-type(s) in the Accept 3130 header. If the client did not specify an Accept header, then the 3131 same structured syntax name suffix used in the request message SHOULD 3132 be used, or the server MAY choose any supported message encoding 3133 format. If there is no request message the server MUST select 3134 "application/yang-data+xml" or "application/yang-data+json", 3135 depending on server preference. All of the examples in this 3136 document, except for the one below, assume that XML encoding will be 3137 returned if there is an error. 3139 YANG Tree Diagram for data: 3141 +---- errors 3142 +---- error* 3143 +---- error-type enumeration 3144 +---- error-tag string 3145 +---- error-app-tag? string 3146 +---- error-path? instance-identifier 3147 +---- error-message? string 3148 +---- error-info? 3150 The semantics and syntax for RESTCONF error messages are defined with 3151 the "yang-errors" YANG data template extension, found in Section 8. 3153 Examples: 3155 The following example shows an error returned for an "lock-denied" 3156 error that can occur if a NETCONF client has locked a datastore. The 3157 RESTCONF client is attempting to delete a data resource. Note that 3158 an Accept header field is used to specify the desired encoding for 3159 the error message. There would be no response message-body content 3160 if this operation was successful. 3162 DELETE /restconf/data/example-jukebox:jukebox/\ 3163 library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1 3164 Host: example.com 3165 Accept: application/yang-data+json 3167 The server might respond: 3169 HTTP/1.1 409 Conflict 3170 Date: Mon, 23 Apr 2016 17:11:00 GMT 3171 Server: example-server 3172 Content-Type: application/yang-data+json 3174 { 3175 "ietf-restconf:errors" : { 3176 "error" : [ 3177 { 3178 "error-type" : "protocol", 3179 "error-tag" : "lock-denied", 3180 "error-message" : "Lock failed, lock already held" 3181 } 3182 ] 3183 } 3184 } 3186 The following example shows an error returned for a "data-exists" 3187 error on a data resource. The "jukebox" resource already exists so 3188 it cannot be created. 3190 The client might send: 3192 POST /restconf/data/example-jukebox:jukebox HTTP/1.1 3193 Host: example.com 3195 The server might respond: 3197 HTTP/1.1 409 Conflict 3198 Date: Mon, 23 Apr 2016 17:11:00 GMT 3199 Server: example-server 3200 Content-Type: application/yang-data+xml 3202 3203 3204 protocol 3205 data-exists 3206 \ 3209 /rc:restconf/rc:data/jbox:jukebox 3210 3211 3212 Data already exists, cannot create new resource 3213 3214 3215 3217 8. RESTCONF Module 3219 The "ietf-restconf" module defines conceptual definitions within an 3220 extension and two groupings, which are not meant to be implemented as 3221 datastore contents by a server. E.g., the "restconf" container is 3222 not intended to be implemented as a top-level data node (under the 3223 "/restconf/data" URI). 3225 Note that the "ietf-restconf" module does not have any protocol- 3226 accessible objects, so no YANG tree diagram is shown. 3228 RFC Ed.: update the date below with the date of RFC publication and 3229 remove this note. 3231 file "ietf-restconf@2016-08-15.yang" 3233 module ietf-restconf { 3234 yang-version 1.1; 3235 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf"; 3236 prefix "rc"; 3238 organization 3239 "IETF NETCONF (Network Configuration) Working Group"; 3241 contact 3242 "WG Web: 3243 WG List: 3245 Author: Andy Bierman 3246 3248 Author: Martin Bjorklund 3249 3251 Author: Kent Watsen 3252 "; 3254 description 3255 "This module contains conceptual YANG specifications 3256 for basic RESTCONF media type definitions used in 3257 RESTCONF protocol messages. 3259 Note that the YANG definitions within this module do not 3260 represent configuration data of any kind. 3261 The 'restconf-media-type' YANG extension statement 3262 provides a normative syntax for XML and JSON message 3263 encoding purposes. 3265 Copyright (c) 2016 IETF Trust and the persons identified as 3266 authors of the code. All rights reserved. 3268 Redistribution and use in source and binary forms, with or 3269 without modification, is permitted pursuant to, and subject 3270 to the license terms contained in, the Simplified BSD License 3271 set forth in Section 4.c of the IETF Trust's Legal Provisions 3272 Relating to IETF Documents 3273 (http://trustee.ietf.org/license-info). 3275 This version of this YANG module is part of RFC XXXX; see 3276 the RFC itself for full legal notices."; 3278 // RFC Ed.: replace XXXX with actual RFC number and remove this 3279 // note. 3281 // RFC Ed.: remove this note 3282 // Note: extracted from draft-ietf-netconf-restconf-17.txt 3284 // RFC Ed.: update the date below with the date of RFC publication 3285 // and remove this note. 3286 revision 2016-08-15 { 3287 description 3288 "Initial revision."; 3289 reference 3290 "RFC XXXX: RESTCONF Protocol."; 3291 } 3293 extension yang-data { 3294 argument name { 3295 yin-element true; 3296 } 3297 description 3298 "This extension is used to specify a YANG data template which 3299 represents conceptual data defined in YANG. It is 3300 intended to describe hierarchical data independent of 3301 protocol context or specific message encoding format. 3302 Data definition statements within a yang-data extension 3303 specify the generic syntax for the specific YANG data 3304 template, whose name is the argument of the yang-data 3305 extension statement. 3307 Note that this extension does not define a media-type. 3308 A specification using this extension MUST specify the 3309 message encoding rules, including the content media type. 3311 The mandatory 'name' parameter value identifies the YANG 3312 data template that is being defined. It contains the 3313 template name. 3315 This extension is ignored unless it appears as a top-level 3316 statement. It MUST contain data definition statements 3317 that result in exactly one container data node definition. 3318 An instance of a YANG data template can thus be translated 3319 into an XML instance document, whose top-level element 3320 corresponds to the top-level container. 3322 The module name and namespace value for the YANG module using 3323 the extension statement is assigned to instance document data 3324 conforming to the data definition statements within 3325 this extension. 3327 The sub-statements of this extension MUST follow the 3328 'data-def-stmt' rule in the YANG ABNF. 3330 The XPath document root is the extension statement itself, 3331 such that the child nodes of the document root are 3332 represented by the data-def-stmt sub-statements within 3333 this extension. This conceptual document is the context 3334 for the following YANG statements: 3336 - must-stmt 3337 - when-stmt 3338 - path-stmt 3339 - min-elements-stmt 3340 - max-elements-stmt 3341 - mandatory-stmt 3342 - unique-stmt 3343 - ordered-by 3344 - instance-identifier data type 3346 The following data-def-stmt sub-statements are constrained 3347 when used within a yang-data-resource extension statement. 3349 - The list-stmt is not required to have a key-stmt defined. 3350 - The if-feature-stmt is ignored if present. 3351 - The config-stmt is ignored if present. 3352 - The available identity values for any 'identityref' 3353 leaf or leaf-list nodes is limited to the module 3354 containing this extension statement, and the modules 3355 imported into that module. 3356 "; 3357 } 3359 rc:yang-data yang-errors { 3360 uses errors; 3361 } 3363 rc:yang-data yang-api { 3364 uses restconf; 3365 } 3367 grouping errors { 3368 description 3369 "A grouping that contains a YANG container 3370 representing the syntax and semantics of a 3371 YANG Patch errors report within a response message."; 3373 container errors { 3374 description 3375 "Represents an error report returned by the server if 3376 a request results in an error."; 3378 list error { 3379 description 3380 "An entry containing information about one 3381 specific error that occurred while processing 3382 a RESTCONF request."; 3383 reference "RFC 6241, Section 4.3"; 3385 leaf error-type { 3386 type enumeration { 3387 enum transport { 3388 description "The transport layer"; 3389 } 3390 enum rpc { 3391 description "The rpc or notification layer"; 3392 } 3393 enum protocol { 3394 description "The protocol operation layer"; 3395 } 3396 enum application { 3397 description "The server application layer"; 3398 } 3399 } 3400 mandatory true; 3401 description 3402 "The protocol layer where the error occurred."; 3403 } 3405 leaf error-tag { 3406 type string; 3407 mandatory true; 3408 description 3409 "The enumerated error tag."; 3410 } 3412 leaf error-app-tag { 3413 type string; 3414 description 3415 "The application-specific error tag."; 3416 } 3418 leaf error-path { 3419 type instance-identifier; 3420 description 3421 "The YANG instance identifier associated 3422 with the error node."; 3423 } 3425 leaf error-message { 3426 type string; 3427 description 3428 "A message describing the error."; 3429 } 3431 anydata error-info { 3432 description 3433 "This anydata value MUST represent a container with 3434 zero or more data nodes representing additional 3435 error information."; 3436 } 3437 } 3438 } 3439 } 3441 grouping restconf { 3442 description 3443 "Conceptual grouping representing the RESTCONF 3444 root resource."; 3446 container restconf { 3447 description 3448 "Conceptual container representing the RESTCONF 3449 root resource."; 3451 container data { 3452 description 3453 "Container representing the datastore resource. 3454 Represents the conceptual root of all state data 3455 and configuration data supported by the server. 3456 The child nodes of this container can be any data 3457 resource which are defined as top-level data nodes 3458 from the YANG modules advertised by the server in 3459 the ietf-yang-library module."; 3460 } 3462 container operations { 3463 description 3464 "Container for all operation resources. 3466 Each resource is represented as an empty leaf with the 3467 name of the RPC operation from the YANG rpc statement. 3469 For example, the 'system-restart' RPC operation defined 3470 in the 'ietf-system' module would be represented as 3471 an empty leaf in the 'ietf-system' namespace. This is 3472 a conceptual leaf, and will not actually be found in 3473 the module: 3475 module ietf-system { 3476 leaf system-reset { 3477 type empty; 3478 } 3479 } 3481 To invoke the 'system-restart' RPC operation: 3483 POST /restconf/operations/ietf-system:system-restart 3485 To discover the RPC operations supported by the server: 3487 GET /restconf/operations 3489 In XML the YANG module namespace identifies the module: 3491 3494 In JSON the YANG module name identifies the module: 3496 { 'ietf-system:system-restart' : [null] } 3498 "; 3499 } 3501 leaf yang-library-version { 3502 type string { 3503 pattern '\d{4}-\d{2}-\d{2}'; 3504 } 3505 config false; 3506 mandatory true; 3507 description 3508 "Identifies the revision date of the ietf-yang-library 3509 module that is implemented by this RESTCONF server. 3510 Indicates the year, month, and day in YYYY-MM-DD 3511 numeric format."; 3512 } 3513 } 3514 } 3516 } 3518 3520 9. RESTCONF Monitoring 3522 The "ietf-restconf-monitoring" module provides information about the 3523 RESTCONF protocol capabilities and event streams available from the 3524 server. A RESTCONF server MUST implement the 3525 "ietf-restconf-monitoring" module. 3527 YANG tree diagram for "ietf-restconf-monitoring" module: 3529 +--ro restconf-state 3530 +--ro capabilities 3531 | +--ro capability* inet:uri 3532 +--ro streams 3533 +--ro stream* [name] 3534 +--ro name string 3535 +--ro description? string 3536 +--ro replay-support? boolean 3537 +--ro replay-log-creation-time? yang:date-and-time 3538 +--ro access* [encoding] 3539 +--ro encoding string 3540 +--ro location inet:uri 3542 9.1. restconf-state/capabilities 3544 This mandatory container holds the RESTCONF protocol capability URIs 3545 supported by the server. 3547 The server MAY maintain a last-modified timestamp for this container, 3548 and return the "Last-Modified" header field when this data node is 3549 retrieved with the GET or HEAD methods. Note that the last-modified 3550 timestamp for the datastore resource is not affected by changes to 3551 this subtree. 3553 The server SHOULD maintain an entity-tag for this container, and 3554 return the "ETag" header field when this data node is retrieved with 3555 the GET or HEAD methods. Note that the entity-tag for the datastore 3556 resource is not affected by changes to this subtree. 3558 The server MUST include a "capability" URI leaf-list entry for the 3559 "defaults" mode used by the server, defined in Section 9.1.2. 3561 The server MUST include a "capability" URI leaf-list entry 3562 identifying each supported optional protocol feature. This includes 3563 optional query parameters and MAY include other capability URIs 3564 defined outside this document. 3566 9.1.1. Query Parameter URIs 3568 A new set of RESTCONF Capability URIs are defined to identify the 3569 specific query parameters (defined in Section 4.8) supported by the 3570 server. 3572 The server MUST include a "capability" leaf-list entry for each 3573 optional query parameter that it supports. 3575 +------------+--------+---------------------------------------------+ 3576 | Name | Sectio | URI | 3577 | | n | | 3578 +------------+--------+---------------------------------------------+ 3579 | depth | 4.8.2 | urn:ietf:params:restconf:capability:depth:1 | 3580 | | | .0 | 3581 | fields | 4.8.3 | urn:ietf:params:restconf:capability:fields: | 3582 | | | 1.0 | 3583 | filter | 4.8.4 | urn:ietf:params:restconf:capability:filter: | 3584 | | | 1.0 | 3585 | replay | 4.8.7 | urn:ietf:params:restconf:capability:replay: | 3586 | | 4.8.8 | 1.0 | 3587 | with- | 4.8.9 | urn:ietf:params:restconf:capability:with- | 3588 | defaults | | defaults:1.0 | 3589 +------------+--------+---------------------------------------------+ 3591 RESTCONF Query Parameter URIs 3593 9.1.2. The "defaults" Protocol Capability URI 3595 This URI identifies the "basic-mode" defaults handling mode that is 3596 used by the server for processing default leafs in requests for data 3597 resources. This protocol capability URI MUST be supported by the 3598 server, and MUST be listed in the "capability" leaf-list in 3599 Section 9.3. 3601 +----------+--------------------------------------------------+ 3602 | Name | URI | 3603 +----------+--------------------------------------------------+ 3604 | defaults | urn:ietf:params:restconf:capability:defaults:1.0 | 3605 +----------+--------------------------------------------------+ 3607 RESTCONF defaults capability URI 3609 The URI MUST contain a query parameter named "basic-mode" with one of 3610 the values listed below: 3612 +------------+------------------------------------------------------+ 3613 | Value | Description | 3614 +------------+------------------------------------------------------+ 3615 | report-all | No data nodes are considered default | 3616 | trim | Values set to the YANG default-stmt value are | 3617 | | default | 3618 | explicit | Values set by the client are never considered | 3619 | | default | 3620 +------------+------------------------------------------------------+ 3622 The "basic-mode" definitions are specified in the "With-Defaults 3623 Capability for NETCONF" [RFC6243]. 3625 If the "basic-mode" is set to "report-all" then the server MUST 3626 adhere to the defaults handling behavior defined in Section 2.1 of 3627 [RFC6243]. 3629 If the "basic-mode" is set to "trim" then the server MUST adhere to 3630 the defaults handling behavior defined in Section 2.2 of [RFC6243]. 3632 If the "basic-mode" is set to "explicit" then the server MUST adhere 3633 to the defaults handling behavior defined in Section 2.3 of 3634 [RFC6243]. 3636 Example: (split for display purposes only) 3638 urn:ietf:params:restconf:capability:defaults:1.0? 3639 basic-mode=explicit 3641 9.2. restconf-state/streams 3643 This optional container provides access to the event streams 3644 supported by the server. The server MAY omit this container if no 3645 event streams are supported. 3647 The server will populate this container with a stream list entry for 3648 each stream type it supports. Each stream contains a leaf called 3649 "events" which contains a URI that represents an event stream 3650 resource. 3652 Stream resources are defined in Section 3.8. Notifications are 3653 defined in Section 6. 3655 9.3. RESTCONF Monitoring Module 3657 The "ietf-restconf-monitoring" module defines monitoring information 3658 for the RESTCONF protocol. 3660 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 3661 are used by this module for some type definitions. 3663 RFC Ed.: update the date below with the date of RFC publication and 3664 remove this note. 3666 file "ietf-restconf-monitoring@2016-08-15.yang" 3668 module ietf-restconf-monitoring { 3669 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"; 3670 prefix "rcmon"; 3672 import ietf-yang-types { prefix yang; } 3673 import ietf-inet-types { prefix inet; } 3675 organization 3676 "IETF NETCONF (Network Configuration) Working Group"; 3678 contact 3679 "WG Web: 3680 WG List: 3682 Author: Andy Bierman 3683 3685 Author: Martin Bjorklund 3686 3688 Author: Kent Watsen 3689 "; 3691 description 3692 "This module contains monitoring information for the 3693 RESTCONF protocol. 3695 Copyright (c) 2016 IETF Trust and the persons identified as 3696 authors of the code. All rights reserved. 3698 Redistribution and use in source and binary forms, with or 3699 without modification, is permitted pursuant to, and subject 3700 to the license terms contained in, the Simplified BSD License 3701 set forth in Section 4.c of the IETF Trust's Legal Provisions 3702 Relating to IETF Documents 3703 (http://trustee.ietf.org/license-info). 3705 This version of this YANG module is part of RFC XXXX; see 3706 the RFC itself for full legal notices."; 3708 // RFC Ed.: replace XXXX with actual RFC number and remove this 3709 // note. 3711 // RFC Ed.: remove this note 3712 // Note: extracted from draft-ietf-netconf-restconf-17.txt 3714 // RFC Ed.: update the date below with the date of RFC publication 3715 // and remove this note. 3716 revision 2016-08-15 { 3717 description 3718 "Initial revision."; 3719 reference 3720 "RFC XXXX: RESTCONF Protocol."; 3721 } 3723 container restconf-state { 3724 config false; 3725 description 3726 "Contains RESTCONF protocol monitoring information."; 3728 container capabilities { 3729 description 3730 "Contains a list of protocol capability URIs"; 3732 leaf-list capability { 3733 type inet:uri; 3734 description "A RESTCONF protocol capability URI."; 3735 } 3736 } 3738 container streams { 3739 description 3740 "Container representing the notification event streams 3741 supported by the server."; 3742 reference 3743 "RFC 5277, Section 3.4, element."; 3745 list stream { 3746 key name; 3747 description 3748 "Each entry describes an event stream supported by 3749 the server."; 3751 leaf name { 3752 type string; 3753 description "The stream name"; 3754 reference "RFC 5277, Section 3.4, element."; 3755 } 3756 leaf description { 3757 type string; 3758 description "Description of stream content"; 3759 reference 3760 "RFC 5277, Section 3.4, element."; 3761 } 3763 leaf replay-support { 3764 type boolean; 3765 default false; 3766 description 3767 "Indicates if replay buffer supported for this stream. 3768 If 'true', then the server MUST support the 'start-time' 3769 and 'stop-time' query parameters for this stream."; 3770 reference 3771 "RFC 5277, Section 3.4, element."; 3772 } 3774 leaf replay-log-creation-time { 3775 when "../replay-support" { 3776 description 3777 "Only present if notification replay is supported"; 3778 } 3779 type yang:date-and-time; 3780 description 3781 "Indicates the time the replay log for this stream 3782 was created."; 3783 reference 3784 "RFC 5277, Section 3.4, 3785 element."; 3786 } 3788 list access { 3789 key encoding; 3790 min-elements 1; 3791 description 3792 "The server will create an entry in this list for each 3793 encoding format that is supported for this stream. 3794 The media type 'text/event-stream' is expected 3795 for all event streams. This list identifies the 3796 sub-types supported for this stream."; 3798 leaf encoding { 3799 type string; 3800 description 3801 "This is the secondary encoding format within the 3802 'text/event-stream' encoding used by all streams. 3803 The type 'xml' is supported for XML encoding. 3805 The type 'json' is supported for JSON encoding."; 3806 } 3808 leaf location { 3809 type inet:uri; 3810 mandatory true; 3811 description 3812 "Contains a URL that represents the entry point 3813 for establishing notification delivery via server 3814 sent events."; 3815 } 3816 } 3817 } 3818 } 3819 } 3821 } 3823 3825 10. YANG Module Library 3827 The "ietf-yang-library" module defined in [RFC7895] provides 3828 information about the YANG modules and submodules used by the 3829 RESTCONF server. Implementation is mandatory for RESTCONF servers. 3830 All YANG modules and submodules used by the server MUST be identified 3831 in the YANG module library. 3833 10.1. modules-state/module 3835 This mandatory list contains one entry for each YANG data model 3836 module supported by the server. There MUST be an instance of this 3837 list for every YANG module that is used by the server. 3839 The contents of this list are defined in the "module" YANG list 3840 statement in [RFC7895]. 3842 Note that there are no protocol accessible objects in the 3843 "ietf-restconf" module to implement, but it is possible that a server 3844 will list the "ietf-restconf" module in the YANG library if it is 3845 imported (directly or indirectly) by an implemented module. 3847 11. IANA Considerations 3848 11.1. The "restconf" Relation Type 3850 This specification registers the "restconf" relation type in the Link 3851 Relation Type Registry defined by [RFC5988]: 3853 Relation Name: restconf 3855 Description: Identifies the root of RESTCONF API as configured 3856 on this HTTP server. The "restconf" relation 3857 defines the root of the API defined in RFCXXXX. 3858 Subsequent revisions of RESTCONF will use alternate 3859 relation values to support protocol versioning. 3861 Reference: RFCXXXX 3863 ` 3865 11.2. YANG Module Registry 3867 This document registers two URIs as namespaces in the IETF XML 3868 registry [RFC3688]. Following the format in RFC 3688, the following 3869 registration is requested: 3871 URI: urn:ietf:params:xml:ns:yang:ietf-restconf 3872 Registrant Contact: The NETMOD WG of the IETF. 3873 XML: N/A, the requested URI is an XML namespace. 3875 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3876 Registrant Contact: The NETMOD WG of the IETF. 3877 XML: N/A, the requested URI is an XML namespace. 3879 This document registers two YANG modules in the YANG Module Names 3880 registry [RFC6020]: 3882 name: ietf-restconf 3883 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf 3884 prefix: rc 3885 // RFC Ed.: replace XXXX with RFC number and remove this note 3886 reference: RFCXXXX 3888 name: ietf-restconf-monitoring 3889 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring 3890 prefix: rcmon 3891 // RFC Ed.: replace XXXX with RFC number and remove this note 3892 reference: RFCXXXX 3894 11.3. Media Types 3896 11.3.1. Media Type application/yang-data+xml 3898 Type name: application 3900 Subtype name: yang-data+xml 3902 Required parameters: None 3904 Optional parameters: None 3906 Encoding considerations: 8-bit 3907 Each conceptual YANG data node is encoded according to the 3908 XML Encoding Rules and Canonical Format for the specific 3909 YANG data node type defined in [RFC7950]. 3911 // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the 3912 // section number for Security Considerations 3913 // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual 3914 // RFC number, and remove this note. 3916 Security considerations: Security considerations related 3917 to the generation and consumption of RESTCONF messages 3918 are discussed in Section NN of [RFCXXXX]. 3919 Additional security considerations are specific to the 3920 semantics of particular YANG data models. Each YANG module 3921 is expected to specify security considerations for the 3922 YANG data defined in that module. 3924 // RFC Ed.: replace XXXX with actual RFC number and remove this 3925 // note. 3927 Interoperability considerations: [RFCXXXX] specifies the 3928 format of conforming messages and the interpretation 3929 thereof. 3931 // RFC Ed.: replace XXXX with actual RFC number and remove this 3932 // note. 3934 Published specification: RFC XXXX 3936 Applications that use this media type: Instance document 3937 data parsers used within a protocol or automation tool 3938 that utilize YANG defined data structures. 3940 Fragment identifier considerations: Fragment identifiers for 3941 this type are not defined. All YANG data nodes are 3942 accessible as resources using the path in the request URI. 3944 Additional information: 3946 Deprecated alias names for this type: N/A 3947 Magic number(s): N/A 3948 File extension(s): None 3949 Macintosh file type code(s): "TEXT" 3951 // RFC Ed.: replace XXXX with actual RFC number and remove this 3952 // note. 3954 Person & email address to contact for further information: See 3955 Authors' Addresses section of [RFCXXXX]. 3957 Intended usage: COMMON 3959 Restrictions on usage: N/A 3961 // RFC Ed.: replace XXXX with actual RFC number and remove this 3962 // note. 3964 Author: See Authors' Addresses section of [RFCXXXX]. 3966 Change controller: Internet Engineering Task Force 3967 (mailto:iesg&ietf.org). 3969 Provisional registration? (standards tree only): no 3971 11.3.2. Media Type application/yang-data+json 3973 Type name: application 3975 Subtype name: yang-data+json 3977 Required parameters: None 3979 Optional parameters: None 3981 Encoding considerations: 8-bit 3982 Each conceptual YANG data node is encoded according to 3983 [RFC7951]. A data annotation is encoded according to 3984 [RFC7952]. 3986 // RFC Ed.: replace 'NN' in Section NN of [RFCXXXX] with the 3987 // section number for Security Considerations 3988 // Replace 'XXXX' in Section NN of [RFCXXXX] with the actual 3989 // RFC number, and remove this note. 3991 Security considerations: Security considerations related 3992 to the generation and consumption of RESTCONF messages 3993 are discussed in Section NN of [RFCXXXX]. 3994 Additional security considerations are specific to the 3995 semantics of particular YANG data models. Each YANG module 3996 is expected to specify security considerations for the 3997 YANG data defined in that module. 3999 // RFC Ed.: replace XXXX with actual RFC number and remove this 4000 // note. 4002 Interoperability considerations: [RFCXXXX] specifies the format 4003 of conforming messages and the interpretation thereof. 4005 // RFC Ed.: replace XXXX with actual RFC number and remove this 4006 // note. 4008 Published specification: RFC XXXX 4010 Applications that use this media type: Instance document 4011 data parsers used within a protocol or automation tool 4012 that utilize YANG defined data structures. 4014 Fragment identifier considerations: The syntax and semantics 4015 of fragment identifiers are the same as specified for the 4016 "application/json" media type. 4018 Additional information: 4020 Deprecated alias names for this type: N/A 4021 Magic number(s): N/A 4022 File extension(s): None 4023 Macintosh file type code(s): "TEXT" 4025 // RFC Ed.: replace XXXX with actual RFC number and remove this 4026 // note. 4028 Person & email address to contact for further information: See 4029 Authors' Addresses section of [RFCXXXX]. 4031 Intended usage: COMMON 4033 Restrictions on usage: N/A 4035 // RFC Ed.: replace XXXX with actual RFC number and remove this 4036 // note. 4038 Author: See Authors' Addresses section of [RFCXXXX]. 4040 Change controller: Internet Engineering Task Force 4041 (mailto:iesg&ietf.org). 4043 Provisional registration? (standards tree only): no 4045 11.4. RESTCONF Capability URNs 4047 [Note to RFC Editor: 4048 The RESTCONF Protocol Capability Registry does not yet exist; 4049 Need to ask IANA to create it; remove this note for publication 4050 ] 4052 This document defines a registry for RESTCONF capability identifiers. 4053 The name of the registry is "RESTCONF Capability URNs". The review 4054 policy for this registry is "IETF Review". The registry shall record 4055 for each entry: 4057 o the name of the RESTCONF capability. By convention, this name 4058 begins with the colon ':' character. 4060 o the URN for the RESTCONF capability. 4062 This document registers several capability identifiers in "RESTCONF 4063 Capability URNs" registry: 4065 Index 4066 Capability Identifier 4067 ------------------------ 4069 :defaults 4070 urn:ietf:params:restconf:capability:defaults:1.0 4072 :depth 4073 urn:ietf:params:restconf:capability:depth:1.0 4075 :fields 4076 urn:ietf:params:restconf:capability:fields:1.0 4078 :filter 4079 urn:ietf:params:restconf:capability:filter:1.0 4081 :replay 4082 urn:ietf:params:restconf:capability:replay:1.0 4084 :with-defaults 4085 urn:ietf:params:restconf:capability:with-defaults:1.0 4087 11.5. Registration of "restconf" URN sub-namespace 4089 IANA has registered a new URN sub-namespace within the IETF URN Sub- 4090 namespace for Registered Protocol Parameter Identifiers defined in 4091 [RFC3553]. 4093 Registry Name: restconf 4095 Specification: RFC XXXX 4096 // RFC Ed.: replace XXXX with RFC number and remove this note 4098 Repository: RESTCONF Capability URNs registry (Section 11.4) 4100 Index value: Sub-parameters MUST be specified in UTF-8, using 4101 standard URI encoding where necessary. 4103 12. Security Considerations 4105 Section 2.1 states "A RESTCONF server MUST support the TLS protocol 4106 [RFC5246]". This language leaves open the possibility that a 4107 RESTCONF server might also support future versions of the TLS 4108 protocol. Of specific concern, TLS 1.3 [I-D.ietf-tls-tls13] 4109 introduces support for 0-RTT handshakes that can lead to security 4110 issues for REST APIs, as described in the Appendix of the TLS 1.3 4111 specification. It is therefore RECOMMENDED that RESTCONF servers do 4112 not support 0-RTT at all (not even for idempotent requests) until an 4113 update to this RFC guides otherwise. 4115 Section 2.5 recommends TLS client certificate based authentication, 4116 but allows the use of any authentication scheme defined in the HTTP 4117 Authentication Scheme Registry. Implementations need to be aware 4118 that the strength of these methods vary greatly, and that some may be 4119 considered experimental. Selection of any of these schemes SHOULD be 4120 performed after reading the Security Considerations section of the 4121 RFC associated with the scheme's registry entry. 4123 The "ietf-restconf-monitoring" YANG module defined in this memo is 4124 designed to be accessed via the NETCONF protocol [RFC6241]. The 4125 lowest NETCONF layer is the secure transport layer, and the 4126 mandatory-to-implement secure transport is Secure Shell (SSH) 4127 [RFC6242]. The NETCONF access control model [RFC6536] provides the 4128 means to restrict access for particular NETCONF users to a pre- 4129 configured subset of all available NETCONF protocol operations and 4130 content. 4132 The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement 4133 secure transport is TLS [RFC5246]. The RESTCONF protocol uses the 4134 NETCONF access control model [RFC6536], which provides the means to 4135 restrict access for particular RESTCONF users to a preconfigured 4136 subset of all available RESTCONF protocol operations and content. 4138 This section provides security considerations for the resources 4139 defined by the RESTCONF protocol. Security considerations for HTTPS 4140 are defined in [RFC7230]. RESTCONF does not specify which YANG 4141 modules a server needs to support, except the 4142 "ietf-restconf-monitoring" module. Security considerations for the 4143 other modules manipulated by RESTCONF can be found in the documents 4144 defining those YANG modules. 4146 Configuration information is by its very nature sensitive. Its 4147 transmission in the clear and without integrity checking leaves 4148 devices open to classic eavesdropping and false data injection 4149 attacks. Configuration information often contains passwords, user 4150 names, service descriptions, and topological information, all of 4151 which are sensitive. There are many patterns of attack that have 4152 been observed through operational practice with existing management 4153 interfaces. It would be wise for implementers to research them, and 4154 take them into account when implementing this protocol. 4156 Different environments may well allow different rights prior to and 4157 then after authentication. When a RESTCONF operation is not properly 4158 authorized, the RESTCONF server MUST return a "401 Unauthorized" 4159 status-line. Note that authorization information can be exchanged in 4160 the form of configuration information, which is all the more reason 4161 to ensure the security of the connection. Note that it is possible 4162 for a client to detect configuration changes in data resources it is 4163 not authorized to access by monitoring changes in the ETag and Last- 4164 Modified header fields returned by the server for the datastore 4165 resource. 4167 A RESTCONF server implementation SHOULD attempt to prevent system 4168 disruption due to excessive resource consumption required to fulfill 4169 edit requests via the POST, PUT, and PATCH methods. It may be 4170 possible to construct an attack on such a RESTCONF server, which 4171 attempts to consume all available memory or other resource types. 4173 13. Acknowledgements 4175 The authors would like to thank the following people for their 4176 contributions to this document: Ladislav Lhotka, Juergen 4177 Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. 4179 The authors would like to thank the following people for their 4180 excellent technical reviews of this document: Mehmet Ersue, Mahesh 4181 Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka, 4182 Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint 4183 Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise, 4184 Dale Worley, and Lionel Morand. 4186 Contributions to this material by Andy Bierman are based upon work 4187 supported by the United States Army, Space & Terrestrial 4188 Communications Directorate (S&TCD) under Contract No. W15P7T- 4189 13-C-A616. Any opinions, findings and conclusions or recommendations 4190 expressed in this material are those of the author(s) and do not 4191 necessarily reflect the views of The Space & Terrestrial 4192 Communications Directorate (S&TCD). 4194 14. References 4196 14.1. Normative References 4198 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4199 Extensions (MIME) Part Two: Media Types", RFC 2046, 4200 November 1996. 4202 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4203 Requirement Levels", BCP 14, RFC 2119, March 1997. 4205 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 4206 IETF URN Sub-namespace for Registered Protocol 4207 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 4208 2003, . 4210 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4211 January 2004. 4213 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4214 Resource Identifier (URI): Generic Syntax", STD 66, 4215 RFC 3986, January 2005. 4217 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4218 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 4220 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 4221 Notifications", RFC 5277, July 2008. 4223 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4224 Housley, R., and T. Polk, "Internet X.509 Public Key 4225 Infrastructure Certificate and Certificate Revocation List 4226 (CRL) Profile", RFC 5280, May 2008. 4228 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 4229 RFC 5789, March 2010. 4231 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 4233 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 4234 Network Configuration Protocol (NETCONF)", RFC 6020, 4235 October 2010. 4237 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 4238 and A. Bierman, Ed., "Network Configuration Protocol 4239 (NETCONF)", RFC 6241, June 2011. 4241 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 4242 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 4243 . 4245 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 4246 NETCONF", RFC 6243, June 2011. 4248 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", 4249 RFC 6415, October 2011. 4251 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 4252 Protocol (NETCONF) Access Control Model", RFC 6536, March 4253 2012. 4255 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 4256 and D. Orchard, "URI Template", RFC 6570, March 2012. 4258 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 4259 July 2013. 4261 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4262 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 4263 2014, . 4265 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4266 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 4267 2014. 4269 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4270 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 4272 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4273 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 4275 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 4276 (HTTP/1.1): Authentication", RFC 7235, June 2014. 4278 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 4279 RFC 7320, July 2014. 4281 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4282 "Recommendations for Secure Use of Transport Layer 4283 Security (TLS) and Datagram Transport Layer Security 4284 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4285 2015, . 4287 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 4288 NETCONF Protocol over Transport Layer Security (TLS) with 4289 Mutual X.509 Authentication", RFC 7589, 4290 DOI 10.17487/RFC7589, June 2015, 4291 . 4293 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 4294 Library", RFC 7895, June 2016. 4296 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4297 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4298 . 4300 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 4301 RFC 7951, DOI 10.17487/RFC7951, August 2016, 4302 . 4304 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 4305 RFC 7952, DOI 10.17487/RFC7952, August 2016, 4306 . 4308 [W3C.REC-eventsource-20150203] 4309 Hickson, I., "Server-Sent Events", World Wide Web 4310 Consortium Recommendation REC-eventsource-20150203, 4311 February 2015, 4312 . 4314 [W3C.REC-xml-20081126] 4315 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 4316 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 4317 Edition)", World Wide Web Consortium Recommendation REC- 4318 xml-20081126, November 2008, 4319 . 4321 [XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) 4322 Version 1.0", World Wide Web Consortium Recommendation 4323 REC-xpath-19991116, November 1999, 4324 . 4326 14.2. Informative References 4328 [I-D.ietf-netconf-yang-patch] 4329 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 4330 Media Type", draft-ietf-netconf-yang-patch-12 (work in 4331 progress), October 2016. 4333 [I-D.ietf-tls-tls13] 4334 Rescorla, E., "The Transport Layer Security (TLS) Protocol 4335 Version 1.3", draft-ietf-tls-tls13-18 (work in progress), 4336 October 2016. 4338 [rest-dissertation] 4339 Fielding, R., "Architectural Styles and the Design of 4340 Network-based Software Architectures", 2000. 4342 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 4344 Appendix A. Change Log 4346 -- RFC Ed.: remove this section before publication. 4348 The RESTCONF issue tracker can be found here: https://github.com/ 4349 netconf-wg/restconf/issues 4351 A.1. v17 to v18 4353 o addressed IESG review comments and clarifications 4355 o addressed Alexey's DISCUSS items 4357 o made Cache-Control MUST support, not SHOULD support 4359 o add example for PUT on a datastore 4361 o add IANA section for "restconf" URN sub-namespace 4363 o clarify media type file extensions 4365 A.2. v16 to v17 4367 o various clarifications from NETCONF WG mailing list 4369 o updated YANG 1.1 and YANG/JSON references to RFC numbers 4371 o fixed notification namespace and eventTime name bug 4372 o changed media type application/yang-data-xml to application/yang- 4373 data+xml 4375 o update fragment identifier considerations section for application/ 4376 yang-data+xml 4378 o clarify HTTP version requirements 4380 A.3. v15 to v16 4382 o changed media type application/yang-data to application/yang-data- 4383 xml 4385 o changed header to header field 4387 o added linewrap convention in terminology and applied in many 4388 examples 4390 o clarified DELETE for leaf-list and list 4392 o clarified URI format for lists without keys or duplicate leaf- 4393 lists 4395 o added 'yang-data extension' term and clarified 'YANG data 4396 template' term 4398 o clarified that the fragment component is not part of the request 4399 URI, per HTTP 4401 o clarified request URI "api-path" syntax 4403 o clarified many examples 4405 A.4. v14 to v15 4407 o added text for HTTP/2 usage 4409 o changed media type definitions per review comments 4411 o added some clarifications and typos 4413 o added error-tag mapping for 406 and 412 errors 4415 o added clarifications based on ops-dir review by Lionel Morand 4417 o clarified PUT and POST differences for creating a data resource 4419 o clarify PUT for a datastore resource 4420 o added clarifications from Gen-Art review by Robert Sparks 4422 o clarified terminology in many places 4424 A.5. v13 - v14 4426 This release addresses github issues #61, #62, #63, #65, #66, and 4427 #67. 4429 o change term 'server' to 'NETCONF server' 4431 o add term 'RESTCONF server' also called 'server' 4433 o change term 'client' to 'NETCONF client' 4435 o add term 'RESTCONF client' also called 'client' 4437 o remove unused YANG terms 4439 o clarified operation resource and schema resource terms 4441 o clarified abstract and intro: RESTCONF uses NETCONF datastore 4442 concepts 4444 o removed term 'protocol operation'; use 'RPC operation' instead 4446 o clarified edit operation from NETCONF as nc:operation 4448 o clarified retrieval of an operation resource 4450 o remove ETag and Last-Modified requirements for /modules-state and 4451 /modules-state/module objects, since these are not configuration 4452 data nodes 4454 o clarified Last-Modified and ETag requirements for datastore and 4455 data resources 4457 o clarified defaults retrieval for leaf and leaf-list target 4458 resources 4460 o clarified request message-body for operation resources 4462 o clarified query parameters for GET also allowed for HEAD 4464 o clarified error handling for query parameters 4466 o clarified XPath function library for "filter" parameter 4467 o added example for 'edit a data resource' 4469 o added term 'notification replay' from RFC 5277 4471 o clarified unsupported encoding format error handling 4473 o change term 'meta-data' to 'metadata' 4475 o clarified RESTCONF metadata definition 4477 o clarified error info not returned for 1xx, 2xx, and 3xx ranges 4479 o clarified operations description in ietf-restconf module 4481 o clarified Acknowledgements section 4483 o clarified some examples 4485 o update some references 4487 o update RFC 2119 boilerplate 4489 o remove requirements that simply restate HTTP requirements 4491 o remove Pragma: no-cache from examples since RFC 7234 says this 4492 pragma is not defined for responses 4494 o remove suggestion MAY send Pragma: no-cache in response 4496 o remove table of HTTP status codes used in RESTCONF 4498 o changed media type names so they conform to RFC 6838 4500 o clarified too-big error-tag conversion 4502 o update SSE reference 4504 o clarify leaf-list identifier encoding 4506 o removed all media types except yang-data 4508 o changed restconf-media-type extension to be more generic yang-data 4509 extension 4511 A.6. v12 - v13 4513 o fix YANG library module examples (now called module-state) 4515 o fix terminology idnit issue 4517 o removed RFC 2818 reference (changed citation to RFC 7230) 4519 A.7. v11 - v12 4521 o clarify query parameter requirements 4523 o move filter query section to match table order in sec. 4.8 4525 o clarify that depth default is entire subtree for datastore 4526 resource 4528 o change ietf-restconf to YANG 1.1 to use anydata instead of anyxml 4530 o made implementation of timestamps optional since ETags are 4531 mandatory 4533 o removed confusing text about data resource definition revision 4534 date 4536 o clarify that errors should be returned for any resource type 4538 o clarified media subtype (not type) for error response 4540 o clarified client SHOULD (not MAY) specify errors format in Accept 4541 header 4543 o clarified terminology in many sections 4545 A.8. v10 - v11 4547 o change term 'operational data' to 'state data' 4549 o clarify :startup behavior 4551 o clarify X.509 security text 4553 o change '403 Forbidden' to '401 Unauthorized' for GET error 4555 o clarify MUST have one "restconf" link relation 4557 o clarify that NV-storage is not mandatory 4558 o clarify how "Last-Modified" and "ETag" header info can be used by 4559 a client 4561 o clarify meaning of mandatory parameter 4563 o fix module name in action examples 4565 o clarify operation resource request needs to be known to parse the 4566 output 4568 o clarify ordered-by user terminology 4570 o fixed JSON example in D.1.1 4572 A.9. v09 - v10 4574 o address review comments: github issue #36 4576 o removed intro text about no knowledge of NETCONF needed 4578 o clarified candidate and confirmed-commit behavior in sec. 1.3 4580 o clarified that a RESTCONF server MUST support TLS 4582 o clarified choice of 403 or 404 error 4584 o fixed forward references to URI template (w/reference at first 4585 use) 4587 o added reference to HTML5 4589 o made error terminology more consistent 4591 o clarified that only 1 list or leaf-list instance can be returned 4592 in an XML response message-body 4594 o clarified that more than 1 instance must not be created by a POST 4595 method 4597 o clarified that PUT cannot be used to change a leaf-list value or 4598 any list key values 4600 o clarified that PATCH cannot be used to change a leaf-list value or 4601 any list key values 4603 o clarified that DELETE should not be used to delete more than one 4604 instance of a leaf-list or list 4606 o update JSON RFC reference 4608 o specified that leaf-list instances are data resources 4610 o specified how a leaf-list instance identifier is constructed 4612 o fixed get-schema example 4614 o clarified that if no Accept header the server SHOULD return the 4615 type specified in RESTCONF, but MAY return any media-type, 4616 according to HTTP rules 4618 o clarified that server SHOULD maintain timestamp and etag for data 4619 resources 4621 o clarified default for content query parameter 4623 o moved terminology section earlier in doc to avoid forward usage 4625 o clarified intro text wrt/ interactions with NETCONF and access to 4626 specific datastores 4628 o clarified server implementation requirements for YANG defaults 4630 o clarified that Errors is not a resource, just a media type 4632 o clarified that HTTP without TLS MUST NOT be used 4634 o add RESTCONF Extensibility section to make it clear how RESTCONF 4635 will be extended in the future 4637 o add text warning that NACM does not work with HTTP caching 4639 o remove sec. 5.2 Message Headers 4641 o remove 202 Accepted from list of used status-lines -- not allowed 4643 o made implementation of OPTIONS MUST instead of SHOULD 4645 o clarified that successful PUT for altering data returns 204 4647 o fixed "point" parameter example 4649 o added example of alternate value for root resource discovery 4651 o added YANG action examples 4653 o fixed some JSON examples 4654 o changed default value for content query parameter to "all" 4656 o changed empty container JSON encoding from "[null]" to "{}" 4658 o added mandatory /restconf/yang-library-version leaf to advertise 4659 revision-date of the YANG library implemented by the server 4661 o clarified URI encoding rules for leaf-list 4663 o clarified sec. 2.2 wrt/ certificates and TLS 4665 o added update procedure for entity tag and timestamp 4667 A.10. v08 - v09 4669 o fix introduction text regarding implementation requirements for 4670 the ietf-yang-library 4672 o clarified HTTP authentication requirements 4674 o fix host-meta example 4676 o changed list key encoding to clarify that quoted strings are not 4677 allowed. Percent-encoded values are used if quotes would be 4678 required. A missing key is treated as a zero-length string 4680 o Fixed example of percent-encoded string to match YANG model 4682 o Changed streams examples to align with naming already used 4684 A.11. v07 - v08 4686 o add support for YANG 1.1 action statement 4688 o changed mandatory encoding from XML to XML or JSON 4690 o fix syntax in fields parameter definition 4692 o add meta-data encoding examples for XML and JSON 4694 o remove RFC 2396 references and update with 3986 4696 o change encoding of a key so quoted string are not used, since they 4697 are already percent-encoded. A zero-length string is not encoded 4698 (/list=foo,,baz) 4700 o Add example of percent-encoded key value 4702 A.12. v06 - v07 4704 o fixed all issues identified in email from Jernej Tuljak in netconf 4705 email 2015-06-22 4707 o fixed error example bug where error-urlpath was still used. 4708 Changed to error-path. 4710 o added mention of YANG Patch and informative reference 4712 o added support for YANG 1.1, specifically support for anydata and 4713 actions 4715 o removed the special field value "*", since it is no longer needed 4717 A.13. v05 - v06 4719 o fixed RESTCONF issue #23 (ietf-restconf-monitoring bug) 4721 A.14. v04 - v05 4723 o changed term 'notification event' to 'event notification' 4725 o removed intro text about framework and meta-model 4727 o removed early mention of API resources 4729 o removed term unified datastore and cleaned up text about NETCONF 4730 datastores 4732 o removed text about not immediate persistence of edits 4734 o removed RESTCONF-specific data-resource-identifier typedef and its 4735 usage 4737 o clarified encoding of key leafs 4739 o changed several examples from JSON to XML encoding 4741 o made 'insert' and 'point' query parameters mandatory to implement 4743 o removed ":insert" capability URI 4745 o renamed stream/encoding to stream/access 4747 o renamed stream/encoding/type to stream/access/encoding 4749 o renamed stream/encoding/events to stream/access/location 4750 o changed XPath from informative to normative reference 4752 o changed rest-dissertation from normative to informative reference 4754 o changed example-jukebox playlist 'id' from a data-resource- 4755 identifier to a leafref pointing at the song name 4757 A.15. v03 - v04 4759 o renamed 'select' to 'fields' (#1) 4761 o moved collection resource and page capability to draft-ietf- 4762 netconf-restconf-collection-00 (#3) 4764 o added mandatory "defaults" protocol capability URI (#4) 4766 o added optional "with-defaults" query parameter URI (#4) 4768 o clarified authentication procedure (#9) 4770 o moved ietf-yang-library module to draft-ietf-netconf-yang- 4771 library-00 (#13) 4773 o clarified that JSON encoding of module name in a URI MUST follow 4774 the netmod-yang-json encoding rules (#14) 4776 o added restconf-media-type extension (#15) 4778 o remove "content" query parameter URI and made this parameter 4779 mandatory (#16) 4781 o clarified datastore usage 4783 o changed lock-denied error example 4785 o added with-defaults query parameter example 4787 o added term "RESTCONF Capability" 4789 o changed NETCONF Capability URI registry usage to new RESTCONF 4790 Capability URI Registry usage 4792 A.16. v02 - v03 4794 o added collection resource 4796 o added "page" query parameter capability 4797 o added "limit" and "offset" query parameters, which are available 4798 if the "page" capability is supported 4800 o added "stream list" term 4802 o fixed bugs in some examples 4804 o added "encoding" list within the "stream" list to allow different 4805 URLs for XML and JSON encoding. 4807 o made XML MUST implement and JSON MAY implement for servers 4809 o re-add JSON notification examples (previously removed) 4811 o updated JSON references 4813 A.17. v01 - v02 4815 o moved query parameter definitions from the YANG module back to the 4816 plain text sections 4818 o made all query parameters optional to implement 4820 o defined query parameter capability URI 4822 o moved 'streams' to new YANG module (ietf-restconf-monitoring) 4824 o added 'capabilities' container to new YANG module (ietf-restconf- 4825 monitoring) 4827 o moved 'modules' container to new YANG module (ietf-yang-library) 4829 o added new leaf 'module-set-id' (ietf-yang-library) 4831 o added new leaf 'conformance' (ietf-yang-library) 4833 o changed 'schema' leaf to type inet:uri that returns the location 4834 of the YANG schema (instead of returning the schema directly) 4836 o changed 'events' leaf to type inet:uri that returns the location 4837 of the event stream resource (instead of returning events 4838 directly) 4840 o changed examples for yang.api resource since the monitoring 4841 information is no longer in this resource 4843 o closed issue #1 'select parameter' since no objections to the 4844 proposed syntax 4846 o closed "encoding of list keys" issue since no objection to new 4847 encoding of list keys in a target resource URI. 4849 o moved open issues list to the issue tracker on github 4851 A.18. v00 - v01 4853 o fixed content=nonconfig example (non-config was incorrect) 4855 o closed open issue 'message-id'. There is no need for a message-id 4856 field, and RFC 2392 does not apply. 4858 o closed open issue 'server support verification'. The headers used 4859 by RESTCONF are widely supported. 4861 o removed encoding rules from section on RESTCONF Meta-Data. This 4862 is now defined in "I-D.lhotka-netmod-yang-json". 4864 o added media type application/yang.errors to map to errors YANG 4865 grouping. Updated error examples to use new media type. 4867 o closed open issue 'additional datastores'. Support may be added 4868 in the future to identify new datastores. 4870 o closed open issue 'PATCH media type discovery'. The section on 4871 PATCH has an added sentence on the Accept-Patch header. 4873 o closed open issue 'YANG to resource mapping'. Current mapping of 4874 all data nodes to resources will be used in order to allow 4875 mandatory DELETE support. The PATCH operation is optional, as 4876 well as the YANG Patch media type. 4878 o closed open issue '_self links for HATEOAS support'. It was 4879 decided that they are redundant because they can be derived from 4880 the YANG module for the specific data. 4882 o added explanatory text for the 'select' parameter. 4884 o added RESTCONF Path Resolution section for discovering the root of 4885 the RESTCONF API using the /.well-known/host-meta. 4887 o added an "error" media type to for structured error messages 4889 o added Secure Transport section requiring TLS 4891 o added Security Considerations section 4893 o removed all references to "REST-like" 4895 A.19. bierman:restconf-04 to ietf:restconf-00 4897 o updated open issues section 4899 Appendix B. Open Issues 4901 -- RFC Ed.: remove this section before publication. 4903 The RESTCONF issues are tracked on github.com: 4905 https://github.com/netconf-wg/restconf/issues 4907 Appendix C. Example YANG Module 4909 The example YANG module used in this document represents a simple 4910 media jukebox interface. 4912 YANG Tree Diagram for "example-jukebox" Module 4914 +--rw jukebox! 4915 +--rw library 4916 | +--rw artist* [name] 4917 | | +--rw name string 4918 | | +--rw album* [name] 4919 | | +--rw name string 4920 | | +--rw genre? identityref 4921 | | +--rw year? uint16 4922 | | +--rw admin 4923 | | | +--rw label? string 4924 | | | +--rw catalogue-number? string 4925 | | +--rw song* [name] 4926 | | +--rw name string 4927 | | +--rw location string 4928 | | +--rw format? string 4929 | | +--rw length? uint32 4930 | +--ro artist-count? uint32 4931 | +--ro album-count? uint32 4932 | +--ro song-count? uint32 4933 +--rw playlist* [name] 4934 | +--rw name string 4935 | +--rw description? string 4936 | +--rw song* [index] 4937 | +--rw index uint32 4938 | +--rw id instance-identifier 4939 +--rw player 4940 +--rw gap? decimal64 4942 rpcs: 4944 +---x play 4945 +--ro input 4946 +--ro playlist string 4947 +--ro song-number uint32 4949 C.1. example-jukebox YANG Module 4951 module example-jukebox { 4953 namespace "http://example.com/ns/example-jukebox"; 4954 prefix "jbox"; 4956 organization "Example, Inc."; 4957 contact "support at example.com"; 4958 description "Example Jukebox Data Model Module"; 4959 revision "2016-08-15" { 4960 description "Initial version."; 4961 reference "example.com document 1-4673"; 4962 } 4964 identity genre { 4965 description "Base for all genre types"; 4966 } 4968 // abbreviated list of genre classifications 4969 identity alternative { 4970 base genre; 4971 description "Alternative music"; 4972 } 4973 identity blues { 4974 base genre; 4975 description "Blues music"; 4976 } 4977 identity country { 4978 base genre; 4979 description "Country music"; 4980 } 4981 identity jazz { 4982 base genre; 4983 description "Jazz music"; 4984 } 4985 identity pop { 4986 base genre; 4987 description "Pop music"; 4988 } 4989 identity rock { 4990 base genre; 4991 description "Rock music"; 4993 } 4995 container jukebox { 4996 presence 4997 "An empty container indicates that the jukebox 4998 service is available"; 5000 description 5001 "Represents a jukebox resource, with a library, playlists, 5002 and a play operation."; 5004 container library { 5006 description "Represents the jukebox library resource."; 5008 list artist { 5009 key name; 5011 description 5012 "Represents one artist resource within the 5013 jukebox library resource."; 5015 leaf name { 5016 type string { 5017 length "1 .. max"; 5018 } 5019 description "The name of the artist."; 5020 } 5022 list album { 5023 key name; 5025 description 5026 "Represents one album resource within one 5027 artist resource, within the jukebox library."; 5029 leaf name { 5030 type string { 5031 length "1 .. max"; 5032 } 5033 description "The name of the album."; 5034 } 5036 leaf genre { 5037 type identityref { base genre; } 5038 description 5039 "The genre identifying the type of music on 5040 the album."; 5042 } 5044 leaf year { 5045 type uint16 { 5046 range "1900 .. max"; 5047 } 5048 description "The year the album was released"; 5049 } 5051 container admin { 5052 description 5053 "Administrative information for the album."; 5055 leaf label { 5056 type string; 5057 description "The label that released the album."; 5058 } 5059 leaf catalogue-number { 5060 type string; 5061 description "The album's catalogue number."; 5062 } 5063 } 5065 list song { 5066 key name; 5068 description 5069 "Represents one song resource within one 5070 album resource, within the jukebox library."; 5072 leaf name { 5073 type string { 5074 length "1 .. max"; 5075 } 5076 description "The name of the song"; 5077 } 5078 leaf location { 5079 type string; 5080 mandatory true; 5081 description 5082 "The file location string of the 5083 media file for the song"; 5084 } 5085 leaf format { 5086 type string; 5087 description 5088 "An identifier string for the media type 5089 for the file associated with the 5090 'location' leaf for this entry."; 5091 } 5092 leaf length { 5093 type uint32; 5094 units "seconds"; 5095 description 5096 "The duration of this song in seconds."; 5097 } 5098 } // end list 'song' 5099 } // end list 'album' 5100 } // end list 'artist' 5102 leaf artist-count { 5103 type uint32; 5104 units "songs"; 5105 config false; 5106 description "Number of artists in the library"; 5107 } 5108 leaf album-count { 5109 type uint32; 5110 units "albums"; 5111 config false; 5112 description "Number of albums in the library"; 5113 } 5114 leaf song-count { 5115 type uint32; 5116 units "songs"; 5117 config false; 5118 description "Number of songs in the library"; 5119 } 5120 } // end library 5122 list playlist { 5123 key name; 5125 description 5126 "Example configuration data resource"; 5128 leaf name { 5129 type string; 5130 description 5131 "The name of the playlist."; 5132 } 5133 leaf description { 5134 type string; 5135 description 5136 "A comment describing the playlist."; 5137 } 5138 list song { 5139 key index; 5140 ordered-by user; 5142 description 5143 "Example nested configuration data resource"; 5145 leaf index { // not really needed 5146 type uint32; 5147 description 5148 "An arbitrary integer index for this playlist song."; 5149 } 5150 leaf id { 5151 type instance-identifier; 5152 mandatory true; 5153 description 5154 "Song identifier. Must identify an instance of 5155 /jukebox/library/artist/album/song/name."; 5156 } 5157 } 5158 } 5160 container player { 5161 description 5162 "Represents the jukebox player resource."; 5164 leaf gap { 5165 type decimal64 { 5166 fraction-digits 1; 5167 range "0.0 .. 2.0"; 5168 } 5169 units "tenths of seconds"; 5170 description "Time gap between each song"; 5171 } 5172 } 5173 } 5175 rpc play { 5176 description "Control function for the jukebox player"; 5177 input { 5178 leaf playlist { 5179 type string; 5180 mandatory true; 5181 description "playlist name"; 5182 } 5183 leaf song-number { 5184 type uint32; 5185 mandatory true; 5186 description "Song number in playlist to play"; 5187 } 5188 } 5189 } 5190 } 5192 Appendix D. RESTCONF Message Examples 5194 The examples within this document use the normative YANG module 5195 "ietf-restconf" defined in Section 8 and the non-normative example 5196 YANG module "example-jukebox" defined in Appendix C.1. 5198 This section shows some typical RESTCONF message exchanges. 5200 D.1. Resource Retrieval Examples 5202 D.1.1. Retrieve the Top-level API Resource 5204 The client starts by retrieving the RESTCONF root resource: 5206 GET /.well-known/host-meta HTTP/1.1 5207 Host: example.com 5208 Accept: application/xrd+xml 5210 The server might respond: 5212 HTTP/1.1 200 OK 5213 Content-Type: application/xrd+xml 5214 Content-Length: nnn 5216 5217 5218 5220 The client may then retrieve the top-level API resource, using the 5221 root resource "/restconf". 5223 GET /restconf HTTP/1.1 5224 Host: example.com 5225 Accept: application/yang-data+json 5227 The server might respond as follows: 5229 HTTP/1.1 200 OK 5230 Date: Mon, 23 Apr 2016 17:01:00 GMT 5231 Server: example-server 5232 Content-Type: application/yang-data+json 5234 { 5235 "ietf-restconf:restconf" : { 5236 "data" : {}, 5237 "operations" : {}, 5238 "yang-library-version" : "2016-06-21" 5239 } 5240 } 5242 To request that the response content to be encoded in XML, the 5243 "Accept" header can be used, as in this example request: 5245 GET /restconf HTTP/1.1 5246 Host: example.com 5247 Accept: application/yang-data+xml 5249 The server will return the same conceptual data either way, which 5250 might be as follows : 5252 HTTP/1.1 200 OK 5253 Date: Mon, 23 Apr 2016 17:01:00 GMT 5254 Server: example-server 5255 Cache-Control: no-cache 5256 Content-Type: application/yang-data+xml 5258 5259 5260 5261 2016-06-21 5262 5264 D.1.2. Retrieve The Server Module Information 5266 It is possible the YANG library module will change over time. The 5267 client can retrieve the revision date of the ietf-yang-library 5268 supported by the server from the API resource, as described in the 5269 previous section. 5271 In this example the client is retrieving the modules information from 5272 the server in JSON format: 5274 GET /restconf/data/ietf-yang-library:modules-state HTTP/1.1 5275 Host: example.com 5276 Accept: application/yang-data+json 5278 The server might respond as follows: 5280 HTTP/1.1 200 OK 5281 Date: Mon, 23 Apr 2016 17:01:00 GMT 5282 Server: example-server 5283 Cache-Control: no-cache 5284 Last-Modified: Sun, 22 Apr 2016 01:00:14 GMT 5285 Content-Type: application/yang-data+json 5287 { 5288 "ietf-yang-library:modules-state" : { 5289 "module-set-id" : "5479120c17a619545ea6aff7aa19838b036ebbd7", 5290 "module" : [ 5291 { 5292 "name" : "foo", 5293 "revision" : "2012-01-02", 5294 "schema" : "https://example.com/modules/foo/2012-01-02", 5295 "namespace" : "http://example.com/ns/foo", 5296 "feature" : [ "feature1", "feature2" ], 5297 "deviation" : [ 5298 { 5299 "name" : "foo-dev", 5300 "revision" : "2012-02-16" 5301 } 5302 ], 5303 "conformance-type" : "implement" 5304 }, 5305 { 5306 "name" : "ietf-yang-library", 5307 "revision" : "2016-06-21", 5308 "schema" : "https://example.com/modules/\ 5309 ietf-yang-library/2016-06-21", 5310 "namespace" : 5311 "urn:ietf:params:xml:ns:yang:ietf-yang-library", 5312 "conformance-type" : "implement" 5313 }, 5314 { 5315 "name" : "foo-types", 5316 "revision" : "2012-01-05", 5317 "schema" : 5318 "https://example.com/modules/foo-types/2012-01-05", 5319 "namespace" : "http://example.com/ns/foo-types", 5320 "conformance-type" : "import" 5321 }, 5322 { 5323 "name" : "bar", 5324 "revision" : "2012-11-05", 5325 "schema" : "https://example.com/modules/bar/2012-11-05", 5326 "namespace" : "http://example.com/ns/bar", 5327 "feature" : [ "bar-ext" ], 5328 "conformance-type" : "implement", 5329 "submodule" : [ 5330 { 5331 "name" : "bar-submod1", 5332 "revision" : "2012-11-05", 5333 "schema" : 5334 "https://example.com/modules/bar-submod1/2012-11-05" 5335 }, 5336 { 5337 "name" : "bar-submod2", 5338 "revision" : "2012-11-05", 5339 "schema" : 5340 "https://example.com/modules/bar-submod2/2012-11-05" 5341 } 5342 ] 5343 } 5344 ] 5345 } 5346 } 5348 D.1.3. Retrieve The Server Capability Information 5350 In this example the client is retrieving the capability information 5351 from the server in XML format, and the server supports all the 5352 RESTCONF query parameters, plus one vendor parameter: 5354 GET /restconf/data/ietf-restconf-monitoring:restconf-state/\ 5355 capabilities HTTP/1.1 5356 Host: example.com 5357 Accept: application/yang-data+xml 5359 The server might respond as follows: 5361 HTTP/1.1 200 OK 5362 Date: Mon, 23 Apr 2016 17:02:00 GMT 5363 Server: example-server 5364 Cache-Control: no-cache 5365 Last-Modified: Sun, 22 Apr 2016 01:00:14 GMT 5366 Content-Type: application/yang-data+xml 5367 5369 \ 5370 urn:ietf:params:restconf:capability:defaults:1.0?\ 5371 basic-mode=explicit\ 5372 5373 \ 5374 urn:ietf:params:restconf:capability:with-defaults:1.0\ 5375 5376 \ 5377 urn:ietf:params:restconf:capability:depth:1.0\ 5378 5379 \ 5380 urn:ietf:params:restconf:capability:fields:1.0\ 5381 5382 \ 5383 urn:ietf:params:restconf:capability:filter:1.0\ 5384 5385 \ 5386 urn:ietf:params:restconf:capability:start-time:1.0\ 5387 5388 \ 5389 urn:ietf:params:restconf:capability:stop-time:1.0\ 5390 5391 \ 5392 http://example.com/capabilities/myparam\ 5393 5394 5396 D.2. Edit Resource Examples 5398 D.2.1. Create New Data Resources 5400 To create a new "artist" resource within the "library" resource, the 5401 client might send the following request. 5403 POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1 5404 Host: example.com 5405 Content-Type: application/yang-data+json 5407 { 5408 "example-jukebox:artist" : [ 5409 { 5410 "name" : "Foo Fighters" 5411 } 5412 ] 5413 } 5415 If the resource is created, the server might respond as follows: 5417 HTTP/1.1 201 Created 5418 Date: Mon, 23 Apr 2016 17:02:00 GMT 5419 Server: example-server 5420 Location: https://example.com/restconf/data/\ 5421 example-jukebox:jukebox/library/artist=Foo%20Fighters 5422 Last-Modified: Mon, 23 Apr 2016 17:02:00 GMT 5423 ETag: "b3830f23a4c" 5425 To create a new "album" resource for this artist within the "jukebox" 5426 resource, the client might send the following request: 5428 POST /restconf/data/example-jukebox:jukebox/\ 5429 library/artist=Foo%20Fighters HTTP/1.1 5430 Host: example.com 5431 Content-Type: application/yang-data+xml 5433 5434 Wasting Light 5435 2011 5436 5438 If the resource is created, the server might respond as follows: 5440 HTTP/1.1 201 Created 5441 Date: Mon, 23 Apr 2016 17:03:00 GMT 5442 Server: example-server 5443 Location: https://example.com/restconf/data/\ 5444 example-jukebox:jukebox/library/artist=Foo%20Fighters/\ 5445 album=Wasting%20Light 5446 Last-Modified: Mon, 23 Apr 2016 17:03:00 GMT 5447 ETag: "b8389233a4c" 5449 D.2.2. Detect Resource Entity-Tag Change 5451 In this example, the server just supports the datastore last-changed 5452 timestamp. After the previous request, the client has cached the 5453 "Last-Modified" header and the Location header from the response to 5454 provide in the following request to patch an "album" list entry with 5455 key value "Wasting Light". Only the "genre" field is being updated. 5457 PATCH /restconf/data/example-jukebox:jukebox/\ 5458 library/artist=Foo%20Fighters/album=Wasting%20Light/\ 5459 genre HTTP/1.1 5460 Host: example.com 5461 If-Unmodified-Since: Mon, 23 Apr 2016 17:03:00 GMT 5462 Content-Type: application/yang-data+json 5464 { "example-jukebox:genre" : "example-jukebox:alternative" } 5466 In this example the datastore resource has changed since the time 5467 specified in the "If-Unmodified-Since" header. The server might 5468 respond: 5470 HTTP/1.1 412 Precondition Failed 5471 Date: Mon, 23 Apr 2016 19:01:00 GMT 5472 Server: example-server 5473 Last-Modified: Mon, 23 Apr 2016 17:45:00 GMT 5474 ETag: "b34aed893a4c" 5476 D.2.3. Edit a Datastore Resource 5478 In this example, assume there is a top-level data resource named 5479 "system" from the example-system module, and this container has a 5480 child leaf called "enable-jukebox-streaming": 5482 container system { 5483 leaf enable-jukebox-streaming { 5484 type boolean; 5485 } 5486 } 5488 In this example PATCH is used by the client to modify 2 top-level 5489 resources at once, in order to enable jukebox streaming and add an 5490 "album" sub-resource to each of 2 "artist" resources: 5492 PATCH /restconf/data HTTP/1.1 5493 Host: example.com 5494 Content-Type: application/yang-data+xml 5495 5496 5497 true 5498 5499 5500 5501 5502 Foo Fighters 5503 5504 One by One 5505 2012 5506 5507 5508 5509 Nick Cave and the Bad Seeds 5510 5511 Tender Prey 5512 1988 5513 5514 5515 5516 5517 5519 D.2.4. Replace a Datastore Resource 5521 In this example, the entire configuration datastore contents are 5522 being replaced. Any child nodes not present in the element 5523 but present in the server will be deleted. 5525 PUT /restconf/data HTTP/1.1 5526 Host: example.com 5527 Content-Type: application/yang-data+xml 5528 5529 5530 5531 5532 Foo Fighters 5533 5534 One by One 5535 2012 5536 5537 5538 5539 Nick Cave and the Bad Seeds 5540 5541 Tender Prey 5542 1988 5543 5544 5545 5546 5547 5549 D.2.5. Edit a Data Resource 5551 In this example, the client modifies one data node by adding an 5552 "album" sub-resource by sending a PATCH for the data resource: 5554 PATCH /restconf/data/example-jukebox:jukebox/library/\ 5555 artist=Nick%20Cave%20and%20the%20Bad%20Seeds HTTP/1.1 5556 Host: example.com 5557 Content-Type: application/yang-data+xml 5559 5560 Nick Cave and the Bad Seeds 5561 5562 The Good Son 5563 1990 5564 5565 5567 D.3. Query Parameter Examples 5569 D.3.1. "content" Parameter 5571 The "content" parameter is used to select the type of data child 5572 resources (configuration and/or not configuration) that are returned 5573 by the server for a GET method request. 5575 In this example, a simple YANG list that has configuration and non- 5576 configuration child resources. 5578 container events 5579 list event { 5580 key name; 5581 leaf name { type string; } 5582 leaf description { type string; } 5583 leaf event-count { 5584 type uint32; 5585 config false; 5586 } 5587 } 5588 } 5590 Example 1: content=all 5592 To retrieve all the child resources, the "content" parameter is set 5593 to "all", or omitted, since this is the default value. The client 5594 might send: 5596 GET /restconf/data/example-events:events?\ 5597 content=all HTTP/1.1 5598 Host: example.com 5599 Accept: application/yang-data+json 5601 The server might respond: 5603 HTTP/1.1 200 OK 5604 Date: Mon, 23 Apr 2016 17:11:30 GMT 5605 Server: example-server 5606 Cache-Control: no-cache 5607 Content-Type: application/yang-data+json 5609 { 5610 "example-events:events" : { 5611 "event" : [ 5612 { 5613 "name" : "interface-up", 5614 "description" : "Interface up notification count", 5615 "event-count" : 42 5616 }, 5617 { 5618 "name" : "interface-down", 5619 "description" : "Interface down notification count", 5620 "event-count" : 4 5621 } 5622 ] 5623 } 5624 } 5626 Example 2: content=config 5628 To retrieve only the configuration child resources, the "content" 5629 parameter is set to "config". Note that the "ETag" and 5630 "Last-Modified" headers are only returned if the content parameter 5631 value is "config". 5633 GET /restconf/data/example-events:events?\ 5634 content=config HTTP/1.1 5635 Host: example.com 5636 Accept: application/yang-data+json 5638 The server might respond: 5640 HTTP/1.1 200 OK 5641 Date: Mon, 23 Apr 2016 17:11:30 GMT 5642 Server: example-server 5643 Last-Modified: Mon, 23 Apr 2016 13:01:20 GMT 5644 ETag: "eeeada438af" 5645 Cache-Control: no-cache 5646 Content-Type: application/yang-data+json 5648 { 5649 "example-events:events" : { 5650 "event" : [ 5651 { 5652 "name" : "interface-up", 5653 "description" : "Interface up notification count" 5654 }, 5655 { 5656 "name" : "interface-down", 5657 "description" : "Interface down notification count" 5658 } 5659 ] 5660 } 5661 } 5663 Example 3: content=nonconfig 5665 To retrieve only the non-configuration child resources, the "content" 5666 parameter is set to "nonconfig". Note that configuration ancestors 5667 (if any) and list key leafs (if any) are also returned. The client 5668 might send: 5670 GET /restconf/data/example-events:events?\ 5671 content=nonconfig HTTP/1.1 5672 Host: example.com 5673 Accept: application/yang-data+json 5675 The server might respond: 5677 HTTP/1.1 200 OK 5678 Date: Mon, 23 Apr 2016 17:11:30 GMT 5679 Server: example-server 5680 Cache-Control: no-cache 5681 Content-Type: application/yang-data+json 5683 { 5684 "example-events:events" : { 5685 "event" : [ 5686 { 5687 "name" : "interface-up", 5688 "event-count" : 42 5689 }, 5690 { 5691 "name" : "interface-down", 5692 "event-count" : 4 5693 } 5694 ] 5695 } 5696 } 5698 D.3.2. "depth" Parameter 5700 The "depth" parameter is used to limit the number of levels of child 5701 resources that are returned by the server for a GET method request. 5703 The depth parameter starts counting levels at the level of the target 5704 resource that is specified, so that a depth level of "1" includes 5705 just the target resource level itself. A depth level of "2" includes 5706 the target resource level and its child nodes. 5708 This example shows how different values of the "depth" parameter 5709 would affect the reply content for retrieval of the top-level 5710 "jukebox" data resource. 5712 Example 1: depth=unbounded 5714 To retrieve all the child resources, the "depth" parameter is not 5715 present or set to the default value "unbounded". 5717 GET /restconf/data/example-jukebox:jukebox?\ 5718 depth=unbounded HTTP/1.1 5719 Host: example.com 5720 Accept: application/yang-data+json 5722 The server might respond: 5724 HTTP/1.1 200 OK 5725 Date: Mon, 23 Apr 2016 17:11:30 GMT 5726 Server: example-server 5727 Cache-Control: no-cache 5728 Content-Type: application/yang-data+json 5730 { 5731 "example-jukebox:jukebox" : { 5732 "library" : { 5733 "artist" : [ 5734 { 5735 "name" : "Foo Fighters", 5736 "album" : [ 5737 { 5738 "name" : "Wasting Light", 5739 "genre" : "example-jukebox:alternative", 5740 "year" : 2011, 5741 "song" : [ 5742 { 5743 "name" : "Wasting Light", 5744 "location" : 5745 "/media/foo/a7/wasting-light.mp3", 5746 "format" : "MP3", 5747 "length" : 286 5748 }, 5749 { 5750 "name" : "Rope", 5751 "location" : "/media/foo/a7/rope.mp3", 5752 "format" : "MP3", 5753 "length" : 259 5754 } 5755 ] 5756 } 5757 ] 5758 } 5759 ] 5760 }, 5761 "playlist" : [ 5762 { 5763 "name" : "Foo-One", 5764 "description" : "example playlist 1", 5765 "song" : [ 5766 { 5767 "index" : 1, 5768 "id" : "/example-jukebox:jukebox/library\ 5769 /artist[name='Foo Figthers']\ 5770 /album[name='Wasting Light']\ 5771 /song[name=Rope']" 5772 }, 5773 { 5774 "index" : 2, 5775 "id" : "/example-jukebox:jukebox/library\ 5776 /artist[name='Foo Figthers']\ 5777 /album[name='Wasting Light']\ 5778 /song[name=Bridge Burning']" 5779 } 5780 ] 5781 } 5782 ], 5783 "player" : { 5784 "gap" : 0.5 5785 } 5786 } 5787 } 5789 Example 2: depth=1 5791 To determine if 1 or more resource instances exist for a given target 5792 resource, the value one is used. 5794 GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1 5795 Host: example.com 5796 Accept: application/yang-data+json 5798 The server might respond: 5800 HTTP/1.1 200 OK 5801 Date: Mon, 23 Apr 2016 17:11:30 GMT 5802 Server: example-server 5803 Cache-Control: no-cache 5804 Content-Type: application/yang-data+json 5806 { 5807 "example-jukebox:jukebox" : {} 5808 } 5810 Example 3: depth=3 5812 To limit the depth level to the target resource plus 2 child resource 5813 layers the value "3" is used. 5815 GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1 5816 Host: example.com 5817 Accept: application/yang-data+json 5819 The server might respond: 5821 HTTP/1.1 200 OK 5822 Date: Mon, 23 Apr 2016 17:11:30 GMT 5823 Server: example-server 5824 Cache-Control: no-cache 5825 Content-Type: application/yang-data+json 5827 { 5828 "example-jukebox:jukebox" : { 5829 "library" : { 5830 "artist" : {} 5831 }, 5832 "playlist" : [ 5833 { 5834 "name" : "Foo-One", 5835 "description" : "example playlist 1", 5836 "song" : {} 5837 } 5838 ], 5839 "player" : { 5840 "gap" : 0.5 5841 } 5842 } 5843 } 5845 D.3.3. "fields" Parameter 5847 In this example the client is retrieving the datastore resource in 5848 JSON format, but retrieving only the "modules-state/module" list, and 5849 only the "name" and "revision" nodes from each list entry. Note that 5850 top node returned by the server matches the target resource node 5851 (which is "data" in this example). The "module-set-id" leaf is not 5852 returned because it is not selected in the fields expression. 5854 GET /restconf/data?fields=ietf-yang-library:modules-state/\ 5855 module(name;revision) HTTP/1.1 5856 Host: example.com 5857 Accept: application/yang-data+json 5859 The server might respond as follows. 5861 [RFC Editor Note: Adjust the date for ietf-restconf-monitoring below 5862 to the date in the published ietf-restconf-monitoring YANG module, 5863 and remove this note.] 5864 HTTP/1.1 200 OK 5865 Date: Mon, 23 Apr 2016 17:01:00 GMT 5866 Server: example-server 5867 Content-Type: application/yang-data+json 5869 { 5870 "ietf-restconf:data" : { 5871 "ietf-yang-library:modules-state" : { 5872 "module" : [ 5873 { 5874 "name" : "example-jukebox", 5875 "revision" : "2015-06-04" 5876 }, 5877 { 5878 "name" : "ietf-inet-types", 5879 "revision" : "2013-07-15" 5880 }, 5881 { 5882 "name" : "ietf-restconf-monitoring", 5883 "revision" : "2016-03-16" 5884 }, 5885 { 5886 "name" : "ietf-yang-library", 5887 "revision" : "2016-06-21" 5888 }, 5889 { 5890 "name" : "ietf-yang-types", 5891 "revision" : "2013-07-15" 5892 } 5893 ] 5894 } 5895 } 5896 } 5898 D.3.4. "insert" Parameter 5900 In this example, a new first song entry in the "Foo-One" playlist is 5901 being created. 5903 Request from client: 5905 POST /restconf/data/example-jukebox:jukebox/\ 5906 playlist=Foo-One?insert=first HTTP/1.1 5907 Host: example.com 5908 Content-Type: application/yang-data+json 5910 { 5911 "example-jukebox:song" : [ 5912 { 5913 "index" : 1, 5914 "id" : "/example-jukebox:jukebox/library\ 5915 /artist[name='Foo Figthers']\ 5916 /album[name='Wasting Light']\ 5917 /song[name=Rope']" 5918 } 5919 ] 5920 } 5922 Response from server: 5924 HTTP/1.1 201 Created 5925 Date: Mon, 23 Apr 2016 13:01:20 GMT 5926 Server: example-server 5927 Last-Modified: Mon, 23 Apr 2016 13:01:20 GMT 5928 Location: https://example.com/restconf/data/\ 5929 example-jukebox:jukebox/playlist=Foo-One/song=1 5930 ETag: "eeeada438af" 5932 D.3.5. "point" Parameter 5934 In this example, the client is inserting a new song entry in the 5935 "Foo-One" playlist after the first song. 5937 Request from client: 5939 POST /restconf/data/example-jukebox:jukebox/\ 5940 playlist=Foo-One?insert=after&point=\ 5941 %2Fexample-jukebox%3Ajukebox\ 5942 %2Fplaylist%3DFoo-One%2Fsong%3D1 HTTP/1.1 5943 Host: example.com 5944 Content-Type: application/yang-data+json 5946 { 5947 "example-jukebox:song" : [ 5948 { 5949 "index" : 2, 5950 "id" : "/example-jukebox:jukebox/library\ 5951 /artist[name='Foo Figthers']\ 5952 /album[name='Wasting Light']\ 5953 /song[name=Bridge Burning']" 5954 } 5955 ] 5956 } 5958 Response from server: 5960 HTTP/1.1 201 Created 5961 Date: Mon, 23 Apr 2016 13:01:20 GMT 5962 Server: example-server 5963 Last-Modified: Mon, 23 Apr 2016 13:01:20 GMT 5964 Location: https://example.com/restconf/data/\ 5965 example-jukebox:jukebox/playlist=Foo-One/song=2 5966 ETag: "abcada438af" 5968 D.3.6. "filter" Parameter 5970 The following URIs show some examples of notification filter 5971 specifications: 5973 // filter = /event/event-class='fault' 5974 GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' 5976 // filter = /event/severity<=4 5977 GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 5979 // filter = /linkUp|/linkDown 5980 GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown 5982 // filter = /*/reporting-entity/card!='Ethernet0' 5983 GET /streams/NETCONF?\ 5984 filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' 5986 // filter = /*/email-addr[contains(.,'company.com')] 5987 GET /streams/critical-syslog?\ 5988 filter=%2F*%2Femail-addr[contains(.%2C'company.com')] 5990 // Note: the module name is used as prefix. 5991 // filter = (/example-mod:event1/name='joe' and 5992 // /example-mod:event1/status='online') 5993 GET /streams/NETCONF?\ 5994 filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and\ 5995 %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') 5997 // To get notifications from just two modules (e.g., m1 + m2) 5998 // filter=(/m1:* or /m2:*) 5999 GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*) 6001 D.3.7. "start-time" Parameter 6003 The following URI shows an example of the "start-time" query 6004 parameter: 6006 // start-time = 2014-10-25T10:02:00Z 6007 GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z 6009 D.3.8. "stop-time" Parameter 6011 The following URI shows an example of the "stop-time" query 6012 parameter: 6014 // start-time = 2014-10-25T10:02:00Z 6015 // stop-time = 2014-10-25T12:31:00Z 6016 GET /mystreams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z\ 6017 &stop-time=2014-10-25T12%3A31%3A00Z 6019 D.3.9. "with-defaults" Parameter 6021 Assume the server implements the module "example" defined in 6022 Appendix A.1 of [RFC6243]. Assume the server's datastore is as 6023 defined in Appendix A.2 of [RFC6243]. 6025 If the server defaults-uri basic-mode is "trim", the the following 6026 request for interface "eth1" might be as follows: 6028 Without query parameter: 6030 GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1 6031 Host: example.com 6032 Accept: application/yang-data+json 6034 The server might respond as follows. 6036 HTTP/1.1 200 OK 6037 Date: Mon, 23 Apr 2016 17:01:00 GMT 6038 Server: example-server 6039 Content-Type: application/yang-data+json 6041 { 6042 "example:interface" : [ 6043 { 6044 "name" : "eth1", 6045 "status" : "up" 6046 } 6047 ] 6048 } 6050 Note that the "mtu" leaf is missing because it is set to the default 6051 "1500", and the server defaults handling basic-mode is "trim". 6053 With query parameter: 6055 GET /restconf/data/example:interfaces/interface=eth1\ 6056 ?with-defaults=report-all HTTP/1.1 6057 Host: example.com 6058 Accept: application/yang-data+json 6060 The server might respond as follows. 6062 HTTP/1.1 200 OK 6063 Date: Mon, 23 Apr 2016 17:01:00 GMT 6064 Server: example-server 6065 Content-Type: application/yang-data+json 6067 { 6068 "example:interface" : [ 6069 { 6070 "name" : "eth1", 6071 "mtu" : 1500, 6072 "status" : "up" 6073 } 6074 ] 6075 } 6077 Note that the server returns the "mtu" leaf because the "report-all" 6078 mode was requested with the "with-defaults" query parameter. 6080 Authors' Addresses 6082 Andy Bierman 6083 YumaWorks 6085 Email: andy@yumaworks.com 6087 Martin Bjorklund 6088 Tail-f Systems 6090 Email: mbj@tail-f.com 6092 Kent Watsen 6093 Juniper Networks 6095 Email: kwatsen@juniper.net