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