idnits 2.17.1 draft-ietf-core-dynlink-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 12, 2021) is 1012 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-06) exists of draft-ietf-core-conditional-attributes-00 == Outdated reference: A later version (-13) exists of draft-irtf-t2trg-rest-iot-07 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group M. Koster 3 Internet-Draft SmartThings 4 Intended status: Informational B. Silverajan, Ed. 5 Expires: January 13, 2022 Tampere University 6 July 12, 2021 8 Dynamic Resource Linking for Constrained RESTful Environments 9 draft-ietf-core-dynlink-14 11 Abstract 13 This specification defines Link Bindings, which provide dynamic 14 linking of state updates between resources, either on an endpoint or 15 between endpoints, for systems using CoAP (RFC7252). 17 Editor note 19 The git repository for the draft is found at https://github.com/core- 20 wg/dynlink 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on January 13, 2022. 39 Copyright Notice 41 Copyright (c) 2021 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 3 59 3.1. The "bind" attribute and Binding Methods . . . . . . . . 4 60 3.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 5 61 3.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 5 63 3.1.4. Execute . . . . . . . . . . . . . . . . . . . . . . . 6 64 3.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 6 65 4. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 6 66 5. Implementation Considerations . . . . . . . . . . . . . . . . 8 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 69 7.1. Resource Type value 'core.bnd' . . . . . . . . . . . . . 8 70 7.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 8 71 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 72 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 9 73 10. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 10 74 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 75 11.1. Normative References . . . . . . . . . . . . . . . . . . 12 76 11.2. Informative References . . . . . . . . . . . . . . . . . 13 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 79 1. Introduction 81 IETF Standards for machine to machine communication in constrained 82 environments describe a REST protocol [RFC7252] and a set of related 83 information standards that may be used to represent machine data and 84 machine metadata in REST interfaces. CoRE Link-format [RFC6690] is a 85 standard for doing Web Linking [RFC8288] in constrained environments. 87 This specification introduces the concept of a Link Binding, which 88 defines a new link relation type to create a dynamic link between 89 resources over which state updates are conveyed. Specifically, a 90 Link Binding is a unidirectional link for binding the states of 91 source and destination resources together such that updates to one 92 are sent over the link to the other. CoRE Link Format 93 representations are used to configure, inspect, and maintain Link 94 Bindings. 96 2. Terminology 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 100 "OPTIONAL" in this document are to be interpreted as described in 101 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 102 capitals, as shown here. 104 This specification requires readers to be familiar with all the terms 105 and concepts that are discussed in [RFC8288], [RFC6690] and 106 [RFC7641]. This specification makes use of the following additional 107 terminology: 109 Link Binding: A unidirectional logical link between a source 110 resource and a destination resource, over which state information 111 is synchronized. 113 State Synchronization: Depending on the binding method (Polling, 114 Observe, Push) different REST methods may be used to synchronize 115 the resource values between a source and a destination. The 116 process of using a REST method to achieve this is defined as 117 "State Synchronization". The endpoint triggering the state 118 synchronization is the synchronization initiator. 120 3. Link Bindings 122 In a M2M RESTful environment, endpoints may directly exchange the 123 content of their resources to operate the distributed system. For 124 example, a light switch may supply on-off control information that 125 may be sent directly to a light resource for on-off control. 126 Beforehand, a configuration phase is necessary to determine how the 127 resources of the different endpoints are related to each other. This 128 can be done either automatically using discovery mechanisms or by 129 means of human intervention and a so-called commissioning tool. 131 In this specification such an abstract relationship between two 132 resources is defined, called a Link Binding. The configuration phase 133 necessitates the exchange of binding information, so a format 134 recognized by all CoRE endpoints is essential. This specification 135 defines a format based on the CoRE Link-Format to represent binding 136 information along with the rules to define a binding method which is 137 a specialized relationship between two resources. 139 The purpose of such a binding is to synchronize content updates 140 between a source resource and a destination resource. The 141 destination resource MAY be a group resource if the authority 142 component of the destination URI contains a group address (either a 143 multicast address or a name that resolves to a multicast address). 145 Since a binding is unidirectional, the binding entry defining a 146 relationship is present only on one endpoint. The binding entry may 147 be located either on the source or the destination endpoint depending 148 on the binding method. 150 Conditional Notification Attributes defined in 151 [I-D.ietf-core-conditional-attributes] can be used with Link Bindings 152 in order to customize the notification behavior and timing. 154 3.1. The "bind" attribute and Binding Methods 156 A binding method defines the rules to generate the network-transfer 157 exchanges that synchronize state between source and destination 158 resources. By using REST methods content is sent from the source 159 resource to the destination resource. 161 This specification defines a new CoRE link attribute "bind". This is 162 the identifier for a binding method which defines the rules to 163 synchronize the destination resource. This attribute is mandatory. 165 +----------------+-----------+-----------+ 166 | Attribute | Parameter | Value | 167 +----------------+-----------+-----------+ 168 | Binding method | bind | xs:string | 169 +----------------+-----------+-----------+ 171 Table 1: The bind attribute 173 The following table gives a summary of the binding methods defined in 174 this specification. 176 +---------+------------+-------------+---------------+ 177 | Name | Identifier | Location | Method | 178 +---------+------------+-------------+---------------+ 179 | Polling | poll | Destination | GET | 180 | | | | | 181 | Observe | obs | Destination | GET + Observe | 182 | | | | | 183 | Push | push | Source | PUT | 184 | | | | | 185 | Execute | exec | Source | POST | 186 +---------+------------+-------------+---------------+ 188 Table 2: Binding Method Summary 190 The description of a binding method defines the following aspects: 192 Identifier: This is the value of the "bind" attribute used to 193 identify the method. 195 Location: This information indicates whether the binding entry is 196 stored on the source or on the destination endpoint. 198 REST Method: This is the REST method used in the Request/Response 199 exchanges. 201 Conditional Notification: How Conditional Notification Attributes 202 defined in [I-D.ietf-core-conditional-attributes] are used in the 203 binding. 205 The binding methods are described in more detail below. 207 3.1.1. Polling 209 The Polling method consists of sending periodic GET requests from the 210 destination endpoint to the source resource and copying the content 211 to the destination resource. The binding entry for this method MUST 212 be stored on the destination endpoint. The destination endpoint MUST 213 ensure that the polling frequency does not exceed the limits defined 214 by the pmin and pmax attributes of the binding entry. The copying 215 process MAY filter out content from the GET requests using value- 216 based conditions (e.g based on the Change Step, Less Than, Greater 217 Than attributes defined in [I-D.ietf-core-conditional-attributes]). 219 3.1.2. Observe 221 The Observe method creates an observation relationship between the 222 destination endpoint and the source resource. On each notification 223 the content from the source resource is copied to the destination 224 resource. The creation of the observation relationship requires the 225 CoAP Observation mechanism [RFC7641] hence this method is only 226 permitted when the resources are made available over CoAP. The 227 binding entry for this method MUST be stored on the destination 228 endpoint. The binding conditions are mapped as query parameters in 229 the Observe request (see [I-D.ietf-core-conditional-attributes]). 231 3.1.3. Push 233 The Push method can be used to allow a source endpoint to replace an 234 outdated resource state at the destination with a newer 235 representation. When the Push method is assigned to a binding, the 236 source endpoint sends PUT requests to the destination resource when 237 the Conditional Notification Attributes are satisfied for the source 238 resource. The source endpoint SHOULD only send a notification 239 request if any included Conditional Notification Attributes are met. 241 The binding entry for this method MUST be stored on the source 242 endpoint. 244 3.1.4. Execute 246 An alternative means for a source endpoint to deliver change-of-state 247 notifications to a destination resource is to use the Execute Method. 248 While the Push method simply updates the state of the destination 249 resource with the representation of the source resource, Execute can 250 be used when the destination endpoint wishes to receive all state 251 changes from a source. This allows, for example, the existence of a 252 resource collection consisting of all the state changes at the 253 destination endpoint. When the Execute method is assigned to a 254 binding, the source endpoint sends POST requests to the destination 255 resource when the Conditional Notification Attributes are satisfied 256 for the source resource. The source endpoint SHOULD only send a 257 notification request if any included Conditional Notification 258 Attributes are met. The binding entry for this method MUST be stored 259 on the source endpoint. 261 Note: Both the Push and the Execute methods are examples of Server 262 Push mechanisms that are being researched in the Thing-to-Thing 263 Research Group (T2TRG) [I-D.irtf-t2trg-rest-iot]. 265 3.2. Link Relation 267 Since Binding involves the creation of a link between two resources, 268 Web Linking and the CoRE Link-Format used to represent binding 269 information. This involves the creation of a new relation type, 270 "boundto". In a Web link with this relation type, the target URI 271 contains the location of the source resource and the context URI 272 points to the destination resource. 274 4. Binding Table 276 The Binding Table is a special resource that describes the bindings 277 on an endpoint. An endpoint offering a representation of the Binding 278 Table resource SHOULD indicate its presence and enable its discovery 279 by advertising a link at "/.well-known/core" [RFC6690]. If so, the 280 Binding Table resource MUST be discoverable by using the Resource 281 Type (rt) 'core.bnd'. 283 The Methods column defines the REST methods supported by the Binding 284 Table, which are described in more detail below. 286 +---------------+----------+----------+----------------+ 287 | Resource | rt= | Methods | Content-Format | 288 +---------------+----------+----------+----------------+ 289 | Binding Table | core.bnd | GET, PUT | link-format | 290 +---------------+----------+----------+----------------+ 292 Table 3: Binding Table Description 294 The REST methods GET and PUT are used to manipulate a Binding Table. 295 A GET request simply returns the current state of a Binding Table. A 296 request with a PUT method and a content format of application/link- 297 format is used to clear the bindings to the table or replaces its 298 entire contents. All links in the payload of a PUT rquest MUST have 299 a relation type "boundto". 301 The following example shows requests for discovering, retrieving and 302 replacing bindings in a binding table. 304 Req: GET /.well-known/core?rt=core.bnd (application/link-format) 305 Res: 2.05 Content (application/link-format) 306 ;rt=core.bnd;ct=40 308 Req: GET /bnd/ 309 Res: 2.05 Content (application/link-format) 310 ; 311 rel=boundto;anchor=/a/fan,;bind="obs", 312 ; 313 rel=boundto;anchor=/a/light;bind="obs" 315 Req: PUT /bnd/ (Content-Format: application/link-format) 316 ; 317 rel="boundto";anchor="/a/light";bind="obs";pmin=10;pmax=60 318 Res: 2.04 Changed 320 Req: GET /bnd/ 321 Res: 2.05 Content (application/link-format) 322 ; 323 rel="boundto";anchor="/a/light";bind="obs";pmin=10;pmax=60 325 Figure 1: Binding Table Example 327 Additional operations on the Binding Table can be specified in future 328 documents. Such operations can include, for example, the usage of 329 the iPATCH or PATCH methods [RFC8132] for fine-grained addition and 330 removal of individual bindings or binding subsets. 332 5. Implementation Considerations 334 The initiation of a Link Binding can be delegated from a client to a 335 link state machine implementation, which can be an embedded client or 336 a configuration tool. Implementation considerations have to be given 337 to how to monitor transactions made by the configuration tool with 338 regards to Link Bindings, as well as any errors that may arise with 339 establishing Link Bindings in addition to established Link Bindings. 341 6. Security Considerations 343 Consideration has to be given to what kinds of security credentials 344 the state machine of a configuration tool or an embedded client needs 345 to be configured with, and what kinds of access control lists client 346 implementations should possess, so that transactions on creating Link 347 Bindings and handling error conditions can be processed by the state 348 machine. 350 7. IANA Considerations 352 7.1. Resource Type value 'core.bnd' 354 This specification registers a new Resource Type Link Target 355 Attribute 'core.bnd' in the Resource Type (rt=) registry established 356 as per [RFC6690]. 358 Attribute Value: core.bnd 360 Description: See Section 4. This attribute value is used to discover 361 the resource representing a binding table, which describes the link 362 bindings between source and destination resources for the purposes of 363 synchronizing their content. 365 Reference: This specification. Note to RFC editor: please insert the 366 RFC of this specification. 368 Notes: None 370 7.2. Link Relation Type 372 This specification registers the new "boundto" link relation type as 373 per [RFC8288]. 375 Relation Name: boundto 377 Description: The purpose of a boundto relation type is to indicate 378 that there is a binding between a source resource and a 379 destination resource for the purposes of synchronizing their 380 content. 382 Reference: This specification. Note to RFC editor: please insert 383 the RFC of this specification. 385 Notes: None 387 Application Data: None 389 8. Acknowledgements 391 Acknowledgement is given to colleagues from the SENSEI project who 392 were critical in the initial development of the well-known REST 393 interface concept, to members of the IPSO Alliance where further 394 requirements for interface types have been discussed, and to Szymon 395 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 396 provided useful discussion and input to the concepts in this 397 specification. Christian Amsuss supplied a comprehensive review of 398 draft -06. Discussions with Ari Keraenen led to the addition of an 399 extra binding method supporting POST operations. 401 9. Contributors 403 Christian Groves 404 Australia 405 email: cngroves.std@gmail.com 407 Zach Shelby 408 ARM 409 Vuokatti 410 FINLAND 411 phone: +358 40 7796297 412 email: zach.shelby@arm.com 414 Matthieu Vial 415 Schneider-Electric 416 Grenoble 417 France 418 phone: +33 (0)47657 6522 419 eMail: matthieu.vial@schneider-electric.com 421 Jintao Zhu 422 Huawei 423 Xi'an, Shaanxi Province 424 China 425 email: jintao.zhu@huawei.com 427 10. Changelog 429 draft-ietf-core-dynlink-14 431 o Conditional Atttributes section removed and submitted as draft- 432 ietf-core-conditional-attributes-00 434 draft-ietf-core-dynlink-13 436 o Conditional Atttributes section restructured 438 o "edge" and "con" attributes added 440 o Implementation considerations, clarifications added when pmax == 441 pmin 443 o rewritten to remove talk of server reporting values to clients 445 draft-ietf-core-dynlink-12 447 o Attributes epmin and epmax included 449 o pmax now can be equal to pmin 451 draft-ietf-core-dynlink-11 453 o Updates to author list 455 draft-ietf-core-dynlink-10 457 o Binding methods now support both POST and PUT operations for 458 server push. 460 draft-ietf-core-dynlink-09 462 o Corrections in Table 1, Table 2, Figure 2. 464 o Clarifications for additional operations to binding table added in 465 section 5 467 o Additional examples in Appendix A 469 draft-ietf-core-dynlink-08 471 o Reorganize the draft to introduce Conditional Notification 472 Attributes at the beginning 474 o Made pmin and pmax type xs:decimal to accommodate fractional 475 second timing 477 o updated the attribute descriptions. lt and gt notify on all 478 crossings, both directions 480 o updated Binding Table description, removed interface description 481 but introduced core.bnd rt attribute value 483 draft-ietf-core-dynlink-07 485 o Added reference code to illustrate attribute interactions for 486 observations 488 draft-ietf-core-dynlink-06 490 o Document restructure and refactoring into three main sections 492 o Clarifications on band usage 494 o Implementation considerations introduced 496 o Additional text on security considerations 498 draft-ietf-core-dynlink-05 500 o Addition of a band modifier for gt and lt, adapted from draft- 501 groves-core-obsattr 503 o Removed statement prescribing gt MUST be greater than lt 505 draft-ietf-core-dynlink-03 507 o General: Reverted to using "gt" and "lt" from "gth" and "lth" for 508 this draft owing to concerns raised that the attributes are 509 already used in LwM2M with the original names "gt" and "lt". 511 o New author and editor added. 513 draft-ietf-core-dynlink-02 515 o General: Changed the name of the greater than attribute "gt" to 516 "gth" and the name of the less than attribute "lt" to "lth" due to 517 conlict with the core resource directory draft lifetime "lt" 518 attribute. 520 o Clause 6.1: Addressed the editor's note by changing the link 521 target attribute to "core.binding". 523 o Added Appendix A for examples. 525 draft-ietf-core-dynlink-01 527 o General: The term state synchronization has been introduced to 528 describe the process of synchronization between destination and 529 source resources. 531 o General: The document has been restructured the make the 532 information flow better. 534 o Clause 3.1: The descriptions of the binding attributes have been 535 updated to clarify their usage. 537 o Clause 3.1: A new clause has been added to discuss the 538 interactions between the resources. 540 o Clause 3.4: Has been simplified to refer to the descriptions in 541 3.1. As the text was largely duplicated. 543 o Clause 4.1: Added a clarification that individual resources may be 544 removed from the binding table. 546 o Clause 6: Formailised the IANA considerations. 548 draft-ietf-core-dynlink Initial Version 00: 550 o This is a copy of draft-groves-core-dynlink-00 552 draft-groves-core-dynlink Draft Initial Version 00: 554 o This initial version is based on the text regarding the dynamic 555 linking functionality in I.D.ietf-core-interfaces-05. 557 o The WADL description has been dropped in favour of a thorough 558 textual description of the REST API. 560 11. References 562 11.1. Normative References 564 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 565 Requirement Levels", BCP 14, RFC 2119, 566 DOI 10.17487/RFC2119, March 1997, 567 . 569 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 570 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 571 . 573 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 574 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 575 May 2017, . 577 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 578 DOI 10.17487/RFC8288, October 2017, 579 . 581 11.2. Informative References 583 [I-D.ietf-core-conditional-attributes] 584 Koster, M. and B. Silverajan, "Conditional Attributes for 585 Constrained RESTful Environments", draft-ietf-core- 586 conditional-attributes-00 (work in progress), July 2021. 588 [I-D.irtf-t2trg-rest-iot] 589 Keranen, A., Kovatsch, M., and K. Hartke, "RESTful Design 590 for Internet of Things Systems", draft-irtf-t2trg-rest- 591 iot-07 (work in progress), February 2021. 593 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 594 Application Protocol (CoAP)", RFC 7252, 595 DOI 10.17487/RFC7252, June 2014, 596 . 598 [RFC7641] Hartke, K., "Observing Resources in the Constrained 599 Application Protocol (CoAP)", RFC 7641, 600 DOI 10.17487/RFC7641, September 2015, 601 . 603 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 604 FETCH Methods for the Constrained Application Protocol 605 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 606 . 608 Authors' Addresses 610 Michael Koster 611 SmartThings 612 665 Clyde Avenue 613 Mountain View 94043 614 USA 616 Email: michael.koster@smartthings.com 617 Bilhanan Silverajan (editor) 618 Tampere University 619 Kalevantie 4 620 Tampere FI-33100 621 Finland 623 Email: bilhanan.silverajan@tuni.fi