idnits 2.17.1 draft-bierman-netconf-yang-patch-00.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 260 has weird spacing: '...eration enu...' == Line 875 has weird spacing: '...ocation str...' == Line 885 has weird spacing: '...w index uin...' == Line 895 has weird spacing: '...-number uin...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (December 21, 2013) is 3778 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-04) exists of draft-bierman-netconf-restconf-03 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). 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: June 24, 2014 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 R. Fernando 9 Cisco 10 December 21, 2013 12 YANG Patch Media Type 13 draft-bierman-netconf-yang-patch-00 15 Abstract 17 This document describes a method for applying patches to NETCONF 18 datastores using data defined with the YANG data modeling language. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on June 24, 2014. 37 Copyright Notice 39 Copyright (c) 2013 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 1.1.4. Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 60 1.1.5. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 5 61 2. YANG Patch . . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.1. Target Resource . . . . . . . . . . . . . . . . . . . . . 6 63 2.2. yang-patch Input . . . . . . . . . . . . . . . . . . . . . 6 64 2.3. yang-patch-status Output . . . . . . . . . . . . . . . . . 7 65 2.4. Target Data Node . . . . . . . . . . . . . . . . . . . . . 7 66 2.5. Edit Operations . . . . . . . . . . . . . . . . . . . . . 7 67 2.6. Error Handling . . . . . . . . . . . . . . . . . . . . . . 8 68 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 9 69 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 70 4.1. YANG Module Registry . . . . . . . . . . . . . . . . . . . 18 71 4.2. application/yang.patch Media Types . . . . . . . . . . . . 18 72 4.3. application/yang.patch-status Media Types . . . . . . . . 18 73 5. Security Considerations . . . . . . . . . . . . . . . . . . . 20 74 6. Normative References . . . . . . . . . . . . . . . . . . . . . 21 75 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 22 76 A.1. RESTCONF-02 to YANG-PATCH-00 . . . . . . . . . . . . . . . 22 77 Appendix B. Example YANG Module . . . . . . . . . . . . . . . . . 23 78 B.1. YANG Patch Examples . . . . . . . . . . . . . . . . . . . 23 79 B.1.1. Patch an Existing Data Resource . . . . . . . . . . . 24 80 B.1.2. Add Resources: Error . . . . . . . . . . . . . . . . . 24 81 B.1.3. Add Resources: Success . . . . . . . . . . . . . . . . 26 82 B.1.4. Move list entry example . . . . . . . . . . . . . . . 28 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 85 1. Introduction 87 There is a need for standard mechanisms to patch NETCONF [RFC6241] 88 datastores which contain conceptual data that conforms to schema 89 specified with YANG [RFC6020]. An "ordered edit list" approach is 90 needed to provide client developers with a simpler edit request 91 format that can be more efficient and also allow more precise client 92 control of the transaction procedure than existing mechanisms. 94 This document defines a media type for a YANG-based editing mechanism 95 that can be used with the HTTP PATCH method [RFC5789] or custom 96 NETCONF operations (defined with the YANG rpc-stmt). 98 YANG Patch is designed to support multiple protocols with the same 99 mechanisms. The RESTCONF [RESTCONF] protocol utilizes YANG Patch 100 with the HTTP PATCH method. A new RPC operation can be defined to 101 utilize YANG Patch in the NETCONF protocol. Both the RESTCONF and 102 NETCONF protocols are designed to utilize the YANG data modeling 103 language to specify content schema modules. 105 1.1. Terminology 107 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 109 "OPTIONAL" in this document are to be interpreted as described in BCP 110 14, [RFC2119]. 112 1.1.1. NETCONF 114 The following terms are defined in [RFC6241]: 116 o candidate configuration datastore 118 o client 120 o configuration data 122 o datastore 124 o configuration datastore 126 o protocol operation 128 o running configuration datastore 130 o server 131 o startup configuration datastore 133 o state data 135 o user 137 1.1.2. HTTP 139 The following terms are defined in [RFC2616]: 141 o entity tag 143 o fragment 145 o header line 147 o message body 149 o method 151 o path 153 o query 155 o request URI 157 o response body 159 1.1.3. YANG 161 The following terms are defined in [RFC6020]: 163 o container 165 o data node 167 o key leaf 169 o leaf 171 o leaf-list 173 o list 175 o presence container (or P-container) 177 o RPC operation (now called protocol operation) 178 o non-presence container (or NP-container) 180 o ordered-by system 182 o ordered-by user 184 1.1.4. Terms 186 The following terms are used within this document: 188 o YANG Patch: a conceptual edit request using the "yang-patch" YANG 189 container, defined in Section 3. In HTTP, refers to a PATCH 190 method where the media type is "application/yang.patch+xml" or 191 "application/yang.patch+json". 193 o YANG Patch Status: a conceptual edit status response using the 194 YANG "yang-patch-status" container, defined in Section 3. In 195 HTTP, refers to a response message for a PATCH method, where the 196 message body is identified by the media type "application/ 197 yang.patch-status+xml" or "application/yang.patch-status+json". 199 1.1.5. Tree Diagrams 201 A simplified graphical representation of the data model is used in 202 this document. The meaning of the symbols in these diagrams is as 203 follows: 205 o Brackets "[" and "]" enclose list keys. 207 o Abbreviations before data node names: "rw" means configuration 208 (read-write) and "ro" state data (read-only). 210 o Symbols after data node names: "?" means an optional node and "*" 211 denotes a "list" and "leaf-list". 213 o Parentheses enclose choice and case nodes, and case nodes are also 214 marked with a colon (":"). 216 o Ellipsis ("...") stands for contents of subtrees that are not 217 shown. 219 2. YANG Patch 221 A "YANG Patch" is an ordered list of edits that are applied to the 222 target datastore by the server. The specific fields are defined with 223 the 'yang-patch' container definition in the YANG module Section 3. 225 For RESTCONF, the YANG Patch operation is invoked by the client by 226 sending a PATCH method request with the YANG Patch media type. A 227 message body representing the YANG Patch input parameters MUST be 228 provided. 230 For NETCONF, a YANG "rpc" statement must be defined. The 231 "yang-patch" grouping MUST be included in the input parameters and 232 the "yang-patch-status" grouping MUST be included in the output 233 parameters. 235 2.1. Target Resource 237 The YANG Patch operation uses a conceptual root within a NETCONF 238 configuration datastore to identity the patch point for the edit 239 operation. This root can be the datastore itself, or 1 or more data 240 nodes within the datastore. 242 For RESTCONF, the target resource is derived from the request URI. 244 For NETCONF, the target resource MUST be defined as an input 245 parameter in the YANG "rpc" statement. 247 2.2. yang-patch Input 249 A data element representing the YANG Patch is sent by the client to 250 specify the edit operation request. When used with the HTTP PATCH 251 method, this data is identified by the YANG Patch media type. 253 YANG Tree Diagram For "yang-patch" Container 255 +--rw yang-patch 256 +--rw patch-id? string 257 +--rw comment? string 258 +--rw edit [edit-id] 259 +--rw edit-id string 260 +--rw operation enumeration 261 +--rw target target-resource-offset 262 +--rw point? target-resource-offset 263 +--rw where? enumeration 264 +--rw value 266 2.3. yang-patch-status Output 268 A data element representing the YANG Patch Status is returned to the 269 client to report the detailed status of the edit operation. When 270 used with the HTTP PATCH method, this data is identified by the YANG 271 Patch Status media type. 273 YANG Tree Diagram For "yang-patch-status" Container: 275 +--rw yang-patch-status 276 +--rw patch-id? string 277 +--rw (global-status)? 278 | +--:(global-errors) 279 | | +--ro errors 280 | | 281 | +--:(ok) 282 | +--rw ok? empty 283 +--rw edit-status 284 +--rw edit [edit-id] 285 +--rw edit-id string 286 +--rw (edit-status-choice)? 287 +--:(ok) 288 | +--rw ok? empty 289 +--:(location) 290 | +--rw location? inet:uri 291 +--:(errors) 292 +--ro errors 294 2.4. Target Data Node 296 The target data node for each edit operation is determined by the 297 value of the target resource in the request and the "target" leaf 298 within each "edit" entry. 300 If the target resource specified in the request URI identifies a 301 datastore resource, then the path string in the "target" leaf is an 302 absolute path expression. The first node specified in the "target" 303 leaf is a top-level data node defined within a YANG module. 305 If the target resource specified in the request URI identifies a data 306 resource, then the path string in the "target" leaf is a relative 307 path expression. The first node specified in the "target" leaf is a 308 child node of the data node associated with the target resource. 310 2.5. Edit Operations 312 Each YANG patch edit specifies one edit operation on the target data 313 node. The set of operations is aligned with the NETCONF edit 314 operations, but also includes some new operations. 316 +-----------+-------------------------------------------------------+ 317 | Operation | Description | 318 +-----------+-------------------------------------------------------+ 319 | create | create a new data resource if it does not already | 320 | | exist or error | 321 | delete | delete a data resource if it already exists or error | 322 | insert | insert a new user-ordered data resource | 323 | merge | merge the edit value with the target data resource; | 324 | | create if it does not already exist | 325 | move | re-order the target data resource | 326 | replace | replace the target data resource with the edit value | 327 | remove | remove a data resource if it already exists or no | 328 | | error | 329 +-----------+-------------------------------------------------------+ 331 YANG Patch Edit Operations 333 2.6. Error Handling 335 If a well-formed, schema-valid YANG Patch message is received, then 336 then the server will process the supplied edits in ascending order. 337 The following error modes apply to the processing of this edit list: 339 All the specified edits MUST be applied or the target datastore 340 contents SHOULD be returned to its original state before the PATCH 341 method started. The server MAY fail to restore the contents of the 342 target datastore completely and with certainty. It is possible for a 343 rollback to fail or an "undo" operation to fail. 345 The server will save the running datastore to non-volatile storage if 346 it has changed, after the edits have been attempted. 348 3. YANG Module 350 The "ietf-yang-patch" module defines conceptual definitions within 351 groupings, which are not meant to be implemented as datastore 352 contents by a server. 354 The "ietf-yang-types" and "ietf-inet_types" modules from [RFC6991] 355 are used by this module for some type definitions. 357 The "ietf-restconf" module from [RESTCONF] is used by this module for 358 a grouping definition. 360 RFC Ed.: update the date below with the date of RFC publication and 361 remove this note. 363 file "ietf-yang-patch@2013-12-21.yang" 365 module ietf-yang-patch { 366 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-patch"; 367 prefix "ypatch"; 369 import ietf-inet-types { prefix inet; } 370 import ietf-restconf { prefix rc; } 372 organization 373 "IETF NETCONF (Network Configuration) Working Group"; 375 contact 376 "WG Web: 377 WG List: 379 WG Chair: Bert Wijnen 380 382 WG Chair: Mehmet Ersue 383 385 Editor: Andy Bierman 386 388 Editor: Martin Bjorklund 389 391 Editor: Kent Watsen 392 394 Editor: Rex Fernando 395 "; 397 description 398 "This module contains conceptual YANG specifications 399 for the YANG Patch and YANG Patch Status data structures. 401 Note that the YANG definitions within this module do not 402 represent configuration data of any kind. 403 The YANG grouping statements provide a normative syntax 404 for XML and JSON message encoding purposes. 406 Copyright (c) 2013 IETF Trust and the persons identified as 407 authors of the code. All rights reserved. 409 Redistribution and use in source and binary forms, with or 410 without modification, is permitted pursuant to, and subject 411 to the license terms contained in, the Simplified BSD License 412 set forth in Section 4.c of the IETF Trust's Legal Provisions 413 Relating to IETF Documents 414 (http://trustee.ietf.org/license-info). 416 This version of this YANG module is part of RFC XXXX; see 417 the RFC itself for full legal notices."; 419 // RFC Ed.: replace XXXX with actual RFC number and remove this 420 // note. 422 // RFC Ed.: remove this note 423 // Note: extracted from draft-bierman-netconf-yang-patch-00.txt 425 // RFC Ed.: update the date below with the date of RFC publication 426 // and remove this note. 427 revision 2013-12-21 { 428 description 429 "Initial revision."; 430 reference 431 "RFC XXXX: YANG Patch"; 432 } 434 typedef target-resource-offset { 435 type string { 436 length "1 .. max"; 437 } 438 description 439 "Contains a relative Data Resource Identifier formatted string 440 to identify a specific data sub-resource instance. 441 The document root for all data resources is a 442 target data resource that is specified in the 443 object definition using this data type."; 444 } 445 grouping yang-patch { 447 description 448 "A grouping that contains a YANG container 449 representing the syntax and semantics of a 450 YANG Patch edit request message."; 452 container yang-patch { 453 description 454 "Represents a conceptual sequence of datastore edits, 455 called a patch. Each patch is given a client-assigned 456 patch identifier. Each edit MUST be applied 457 in ascending order, and all edits MUST be applied. 458 If any errors occur, then the target datastore MUST NOT 459 be changed by the patch operation. 461 A patch MUST be validated by the server to be a 462 well-formed message before any of the patch edits 463 are validated or attempted. 465 YANG datastore validation (defined in RFC 6020, section 466 8.3.3) is performed after all edits have been 467 individually validated. 469 It is possible for a datastore constraint violation to occur 470 due to any node in the datastore, including nodes not 471 included in the edit list. Any validation errors MUST 472 be reported in the reply message."; 474 reference 475 "RFC 6020, section 8.3."; 477 leaf patch-id { 478 type string; 479 description 480 "An arbitrary string provided by the client to identify 481 the entire patch. This value SHOULD be present in any 482 audit logging records generated by the server for the 483 patch. Error messages returned by the server pertaining 484 to this patch will be identified by this patch-id value."; 485 } 487 leaf comment { 488 type string { 489 length "0 .. 1024"; 490 } 491 description 492 "An arbitrary string provided by the client to describe 493 the entire patch. This value SHOULD be present in any 494 audit logging records generated by the server for the 495 patch."; 496 } 498 list edit { 499 key edit-id; 500 ordered-by user; 502 description 503 "Represents one edit within the YANG Patch 504 request message."; 506 leaf edit-id { 507 type string; 508 description 509 "Arbitrary string index for the edit. 510 Error messages returned by the server pertaining 511 to a specific edit will be identified by this 512 value."; 513 } 515 leaf operation { 516 type enumeration { 517 enum create { 518 description 519 "The target data node is created using the 520 supplied value, only if it does not already 521 exist."; 522 } 523 enum delete { 524 description 525 "Delete the target node, only if the data resource 526 currently exists, otherwise return an error."; 527 } 528 enum insert { 529 description 530 "Insert the supplied value into a user-ordered 531 list or leaf-list entry. The target node must 532 represent a new data resource."; 533 } 534 enum merge { 535 description 536 "The supplied value is merged with the target data 537 node."; 538 } 539 enum move { 540 description 541 "Move the target node. Reorder a user-ordered 542 list or leaf-list. The target node must represent 543 an existing data resource."; 544 } 545 enum replace { 546 description 547 "The supplied value is used to replace the target 548 data node."; 549 } 550 enum remove { 551 description 552 "Delete the target node if it currently exists."; 553 } 554 } 555 mandatory true; 556 description 557 "The datastore operation requested for the associated 558 edit entry"; 559 } 561 leaf target { 562 type target-resource-offset; 563 mandatory true; 564 description 565 "Identifies the target data resource for the edit 566 operation."; 567 } 569 leaf point { 570 when "(../operation = 'insert' or " + 571 "../operation = 'move') and " + 572 "(../where = 'before' or ../where = 'after')" { 573 description 574 "Point leaf only applies for insert or move 575 operations, before or after an existing entry."; 576 } 577 type target-resource-offset; 578 description 579 "The absolute URL path for the data node that is being 580 used as the insertion point or move point for the 581 target of this edit entry."; 582 } 584 leaf where { 585 when "../operation = 'insert' or ../operation = 'move'" { 586 description 587 "Where leaf only applies for insert or move 588 operations."; 590 } 591 type enumeration { 592 enum before { 593 description 594 "Insert or move a data node before the data resource 595 identified by the 'point' parameter."; 596 } 597 enum after { 598 description 599 "Insert or move a data node after the data resource 600 identified by the 'point' parameter."; 601 } 602 enum first { 603 description 604 "Insert or move a data node so it becomes ordered 605 as the first entry."; 606 } 607 enum last { 608 description 609 "Insert or move a data node so it becomes ordered 610 as the last entry."; 611 } 613 } 614 default last; 615 description 616 "Identifies where a data resource will be inserted or 617 moved. YANG only allows these operations for 618 list and leaf-list data nodes that are ordered-by 619 user."; 620 } 622 anyxml value { 623 when "(../operation = 'create' or " + 624 "../operation = 'merge' " + 625 "or ../operation = 'replace' or " + 626 "../operation = 'insert')" { 627 description 628 "Value node only used for create, merge, 629 replace, and insert operations"; 630 } 631 description 632 "Value used for this edit operation."; 633 } 634 } 635 } 637 } // grouping yang-patch 638 grouping yang-patch-status { 640 description 641 "A grouping that contains a YANG container 642 representing the syntax and semantics of 643 YANG Patch status response message."; 645 container yang-patch-status { 646 description 647 "A container representing the response message 648 sent by the server after a YANG Patch edit 649 request message has been processed."; 651 leaf patch-id { 652 type string; 653 description 654 "The patch-id value used in the request"; 655 } 657 choice global-status { 658 description 659 "Report global errors or complete success. 660 If there is no case selected then errors 661 are reported in the edit-status container."; 663 case global-errors { 664 uses rc:errors; 665 description 666 "This container will be present if global 667 errors unrelated to a specific edit occurred."; 668 } 669 leaf ok { 670 type empty; 671 description 672 "This leaf will be present if the request succeeded 673 and there are no errors reported in the edit-status 674 container."; 675 } 676 } 678 container edit-status { 679 description 680 "This container will be present if there are 681 edit-specific status responses to report."; 683 list edit { 684 key edit-id; 685 description 686 "Represents a list of status responses, 687 corresponding to edits in the YANG Patch 688 request message. If an edit entry was 689 skipped or not reached by the server, 690 then this list will not contain a corresponding 691 entry for that edit."; 693 leaf edit-id { 694 type string; 695 description 696 "Response status is for the edit list entry 697 with this edit-id value."; 698 } 699 choice edit-status-choice { 700 description 701 "A choice between different types of status 702 responses for each edit entry."; 703 leaf ok { 704 type empty; 705 description 706 "This edit entry was invoked without any 707 errors detected by the server associated 708 with this edit."; 709 } 710 leaf location { 711 type inet:uri; 712 description 713 "Contains the Location header value that would be 714 returned if this edit causes a new resource to be 715 created. If the edit identified by the same edit-id 716 value was successfully invoked and a new resource 717 was created, then this field will be returned 718 instead of 'ok'."; 719 } 720 case errors { 721 uses rc:errors; 722 description 723 "The server detected errors associated with the 724 edit identified by the same edit-id value."; 725 } 726 } 727 } 728 } 729 } 730 } // grouping yang-patch-status 732 } 733 735 4. IANA Considerations 737 4.1. YANG Module Registry 739 This document registers one URI in the IETF XML registry [RFC3688]. 740 Following the format in RFC 3688, the following registration is 741 requested to be made. 743 URI: urn:ietf:params:xml:ns:yang:ietf-yang-patch 744 Registrant Contact: The NETMOD WG of the IETF. 745 XML: N/A, the requested URI is an XML namespace. 747 This document registers one YANG module in the YANG Module Names 748 registry [RFC6020]. 750 name: ietf-yang-patch 751 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-patch 752 prefix: ypatch 753 // RFC Ed.: replace XXXX with RFC number and remove this note 754 reference: RFC XXXX 756 4.2. application/yang.patch Media Types 758 The MIME media type for a YANG Patch document is application/ 759 yang.patch. 761 Type name: application 763 Subtype name: yang.patch 765 Required parameters: TBD 767 Optional parameters: TBD 769 Encoding considerations: TBD 771 Security considerations: TBD 773 Interoperability considerations: TBD 775 // RFC Ed.: replace XXXX with RFC number and remove this note 776 Published specification: RFC XXXX 778 4.3. application/yang.patch-status Media Types 780 The MIME media type for a YANG Patch status document is application/ 781 yang.patch-status. 783 Type name: application 785 Subtype name: yang.patch-status 787 Required parameters: TBD 789 Optional parameters: TBD 791 Encoding considerations: TBD 793 Security considerations: TBD 795 Interoperability considerations: TBD 797 // RFC Ed.: replace XXXX with RFC number and remove this note 798 Published specification: RFC XXXX 800 5. Security Considerations 802 TBD 804 6. Normative References 806 [JSON] Bray, T., Ed., "The JSON Data Interchange Format", 807 draft-ietf-json-rfc4627bis-10 (work in progress), 808 December 2013. 810 [RESTCONF] 811 Bierman, A., Bjorklund, M., Watsen, K., and R. Fernando, 812 "RESTCONF Protocol", draft-bierman-netconf-restconf-03 813 (work in progress), December 2013. 815 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 816 Requirement Levels", BCP 14, RFC 2119, March 1997. 818 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 819 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 820 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 822 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 823 January 2004. 825 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 826 RFC 5789, March 2010. 828 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 829 Network Configuration Protocol (NETCONF)", RFC 6020, 830 October 2010. 832 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 833 and A. Bierman, Ed., "Network Configuration Protocol 834 (NETCONF)", RFC 6241, June 2011. 836 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 837 July 2013. 839 [W3C.REC-xml-20081126] 840 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 841 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 842 Edition)", World Wide Web Consortium Recommendation REC- 843 xml-20081126, November 2008, 844 . 846 Appendix A. Change Log 848 -- RFC Ed.: remove this section before publication. 850 A.1. RESTCONF-02 to YANG-PATCH-00 852 o Split out from RESTCONF draft 854 o Rewrite HTTP sections to be more generic and apply to NETCONF as 855 well 857 Appendix B. Example YANG Module 859 The example YANG module used in this document represents a simple 860 media jukebox interface. The "example-jukebox" YANG module is 861 defined in [RESTCONF]. 863 YANG Tree Diagram for "example-jukebox" Module: 865 +--rw jukebox? 866 +--rw library 867 | +--rw artist [name] 868 | | +--rw name string 869 | | +--rw album [name] 870 | | +--rw name string 871 | | +--rw genre? identityref 872 | | +--rw year? uint16 873 | | +--rw song [name] 874 | | +--rw name string 875 | | +--rw location string 876 | | +--rw format? string 877 | | +--rw length? uint32 878 | +--ro artist-count? uint32 879 | +--ro album-count? uint32 880 | +--rw song-count? uint32 881 +--rw playlist [name] 882 | +--rw name string 883 | +--rw description? string 884 | +--rw song [index] 885 | +--rw index uint32 886 | +--rw id instance-identifier 887 +--rw player 888 +--rw gap? decimal64 890 rpcs: 892 +---x play 893 +--ro input 894 +--ro playlist string 895 +--ro song-number uint32 897 B.1. YANG Patch Examples 899 This section includes RESTCONF examples. NETCONF examples are TBD. 900 Most examples are shown in JSON encoding [JSON], and some are shown 901 in XML encoding [W3C.REC-xml-20081126]. 903 B.1.1. Patch an Existing Data Resource 905 To replace just the "year" field in the "album" resource (instead of 906 replacing the entire resource), the client might send a plain patch 907 as follows. Note that the request URI header line is wrapped for 908 display purposes only: 910 PATCH /restconf/data/example-jukebox:jukebox/ 911 library/artist/Foo%20Fighters/album/Wasting%20Light HTTP/1.1 912 Host: example.com 913 If-Match: b8389233a4c 914 Content-Type: application/yang.data+json 916 { "example-jukebox:year" : 2011 } 918 If the field is updated, the server might respond: 920 HTTP/1.1 204 No Content 921 Date: Mon, 23 Apr 2012 17:49:30 GMT 922 Server: example-server 923 Last-Modified: Mon, 23 Apr 2012 17:49:30 GMT 924 ETag: b2788923da4c 926 The XML encoding for the same request might be: 928 PATCH /restconf/data/example-jukebox:jukebox/ 929 library/artist/Foo%20Fighters/album/Wasting%20Light HTTP/1.1 930 Host: example.com 931 If-Match: b8389233a4c 932 Content-Type: application/yang.data+xml 934 2011 936 B.1.2. Add Resources: Error 938 The following example shows several songs being added to an existing 939 album. Each edit contains one song. The first song already exists, 940 so an error will be reported for that edit. The rest of the edits 941 were not attempted, since the first edit failed. 943 Request from client: 945 PATCH /restconf/data/example-jukebox:jukebox/ 946 library/artist/Foo%20Fighters/album/Wasting%20Light HTTP/1.1 947 Host: example.com 948 Accept: application/yang.patch-status+json 949 Content-Type: application/yang.patch+json 950 { 951 "ietf-restconf:yang-patch" : { 952 "patch-id" : "add-songs-patch", 953 "edit" : [ 954 { 955 "edit-id" : 1, 956 "operation" : "create", 957 "target" : "/song", 958 "value" : { 959 "song" : { 960 "name" : "Bridge Burning", 961 "location" : "/media/bridge_burning.mp3", 962 "format" : "MP3", 963 "length" : 288 964 } 965 } 966 }, 967 { 968 "edit-id" : 2, 969 "operation" : "create", 970 "target" : "/song", 971 "value" : { 972 "song" : { 973 "name" : "Rope", 974 "location" : "/media/rope.mp3", 975 "format" : "MP3", 976 "length" : 259 977 } 978 } 979 }, 980 { 981 "edit-id" : 3, 982 "operation" : "create", 983 "target" : "/song", 984 "value" : { 985 "song" : { 986 "name" : "Dear Rosemary", 987 "location" : "/media/dear_rosemary.mp3", 988 "format" : "MP3", 989 "length" : 269 990 } 991 } 992 } 993 ] 994 } 995 } 997 Response from server: 999 HTTP/1.1 409 Conflict 1000 Date: Mon, 23 Apr 2012 13:01:20 GMT 1001 Server: example-server 1002 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1003 Content-Type: application/yang.patch-status+json 1005 { 1006 "ietf-restconf:yang-patch-status" : { 1007 "patch-id" : "add-songs-patch", 1008 "edit-status" : { 1009 "edit" : [ 1010 { 1011 "edit-id" : 1, 1012 "errors" : { 1013 "error" : [ 1014 { 1015 "error-type": "application", 1016 "error-tag": "data-exists", 1017 "error-path": "/example-jukebox:jukebox/library 1018 /artist/Foo%20Fighters/album/Wasting%20Light 1019 /song/Burning%20Light", 1020 "error-message": 1021 "Data already exists, cannot be created" 1022 } 1023 ] 1024 } 1025 } 1026 ] 1027 } 1028 } 1029 } 1031 B.1.3. Add Resources: Success 1033 The following example shows several songs being added to an existing 1034 album. 1036 o Each of 2 edits contains one song. 1038 o Both edits succeed and new sub-resources are created 1040 Request from client: 1042 PATCH /restconf/data/example-jukebox:jukebox/ 1043 library/artist/Foo%20Fighters/album/Wasting%20Light 1044 HTTP/1.1 1045 Host: example.com 1046 Accept: application/yang.patch-status+json 1047 Content-Type: application/yang.patch+json 1049 { 1050 "ietf-restconf:yang-patch" : { 1051 "patch-id" : "add-songs-patch-2", 1052 "edit" : [ 1053 { 1054 "edit-id" : 1, 1055 "operation" : "create", 1056 "target" : "/song", 1057 "value" : { 1058 "song" : { 1059 "name" : "Rope", 1060 "location" : "/media/rope.mp3", 1061 "format" : "MP3", 1062 "length" : 259 1063 } 1064 } 1065 }, 1066 { 1067 "edit-id" : 2, 1068 "operation" : "create", 1069 "target" : "/song", 1070 "value" : { 1071 "song" : { 1072 "name" : "Dear Rosemary", 1073 "location" : "/media/dear_rosemary.mp3", 1074 "format" : "MP3", 1075 "length" : 269 1076 } 1077 } 1078 } 1079 ] 1080 } 1081 } 1083 Response from server: 1085 HTTP/1.1 409 Conflict 1086 Date: Mon, 23 Apr 2012 13:01:20 GMT 1087 Server: example-server 1088 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1089 Content-Type: application/yang.patch-status+json 1091 { 1092 "ietf-restconf:yang-patch-status" : { 1093 "patch-id" : "add-songs-patch-2", 1094 "ok" : [null], 1095 "edit-status" : { 1096 "edit" : [ 1097 { 1098 "edit-id" : 1, 1099 "location" : "http://example.com/restconf/ 1100 data/example-jukebox:jukebox/library/artist/ 1101 Foo%20Fighters/album/Wasting%20Light/song/Rope" 1102 }, 1103 { 1104 "edit-id" : 2, 1105 "location" : "http://example.com/restconf/ 1106 data/example-jukebox:jukebox/library/artist/ 1107 Foo%20Fighters/album/Wasting%20Light/song/ 1108 Dear%20Rosemary" 1109 } 1110 ] 1111 } 1112 } 1113 } 1115 B.1.4. Move list entry example 1117 The following example shows a song being moved within an existing 1118 playlist. Song "1" in playlist "Foo-One" is being moved after song 1119 "3" in the playlist. The operation succeeds, so a non-error reply 1120 example can be shown. 1122 Request from client: 1124 PATCH /restconf/data/example-jukebox:jukebox/ 1125 playlist/Foo-One HTTP/1.1 1126 Host: example.com 1127 Accept: application/yang.patch-status+json 1128 Content-Type: application/yang.patch+json 1130 { 1131 "ietf-restconf:yang-patch" : { 1132 "patch-id" : "move-song-patch", 1133 "comment" : "Move song 1 after song 3", 1134 "edit" : [ 1135 { 1136 "edit-id" : 1, 1137 "operation" : "move", 1138 "target" : "/song/1", 1139 "point" : "/song3", 1140 "where" : "after" 1141 } 1142 ] 1143 } 1144 } 1146 Response from server: 1148 HTTP/1.1 400 OK 1149 Date: Mon, 23 Apr 2012 13:01:20 GMT 1150 Server: example-server 1151 Last-Modified: Mon, 23 Apr 2012 13:01:20 GMT 1152 Content-Type: application/yang.patch-status+json 1154 { 1155 "ietf-restconf:yang-patch-status" : { 1156 "patch-id" : "move-song-patch", 1157 "ok" : [null], 1158 "edit-status" : { 1159 "edit" : [ 1160 { 1161 "edit-id" : 1, 1162 "ok" : [ null ] 1163 } 1164 ] 1165 } 1166 } 1167 } 1169 Authors' Addresses 1171 Andy Bierman 1172 YumaWorks 1174 Email: andy@yumaworks.com 1176 Martin Bjorklund 1177 Tail-f Systems 1179 Email: mbj@tail-f.com 1181 Kent Watsen 1182 Juniper Networks 1184 Email: kwatsen@juniper.net 1186 Rex Fernando 1187 Cisco 1189 Email: rex@cisco.com