idnits 2.17.1 draft-ietf-core-dynlink-11.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 60 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 13, 2020) is 1382 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: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-13) exists of draft-irtf-t2trg-rest-iot-06 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). 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 14, 2021 Tampere University 6 July 13, 2020 8 Dynamic Resource Linking for Constrained RESTful Environments 9 draft-ietf-core-dynlink-11 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). This 16 specification also defines Conditional Notification Attributes that 17 work with Link Bindings or with CoAP Observe (RFC7641). 19 Editor note 21 The git repository for the draft is found at https://github.com/core- 22 wg/dynlink 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on January 14, 2021. 41 Copyright Notice 43 Copyright (c) 2020 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Conditional Notification Attributes . . . . . . . . . . . . . 4 61 3.1. Attribute Definitions . . . . . . . . . . . . . . . . . . 4 62 3.1.1. Minimum Period (pmin) . . . . . . . . . . . . . . . . 5 63 3.1.2. Maximum Period (pmax) . . . . . . . . . . . . . . . . 5 64 3.1.3. Change Step (st) . . . . . . . . . . . . . . . . . . 5 65 3.1.4. Greater Than (gt) . . . . . . . . . . . . . . . . . . 6 66 3.1.5. Less Than (lt) . . . . . . . . . . . . . . . . . . . 6 67 3.1.6. Notification Band (band) . . . . . . . . . . . . . . 6 68 3.2. Server processing of Conditional Notification Attributes 8 69 4. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 8 70 4.1. The "bind" attribute and Binding Methods . . . . . . . . 9 71 4.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 10 72 4.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 10 73 4.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 11 74 4.1.4. Execute . . . . . . . . . . . . . . . . . . . . . . . 11 75 4.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 11 76 5. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 12 77 6. Implementation Considerations . . . . . . . . . . . . . . . . 13 78 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 80 8.1. Resource Type value 'core.bnd' . . . . . . . . . . . . . 14 81 8.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 14 82 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 15 83 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 15 84 11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 16 85 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 86 12.1. Normative References . . . . . . . . . . . . . . . . . . 18 87 12.2. Informative References . . . . . . . . . . . . . . . . . 18 88 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 19 89 A.1. Minimum Period (pmin) example . . . . . . . . . . . . . . 19 90 A.2. Maximum Period (pmax) example . . . . . . . . . . . . . . 20 91 A.3. Greater Than (gt) example . . . . . . . . . . . . . . . . 21 92 A.4. Greater Than (gt) and Period Max (pmax) example . . . . . 22 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 95 1. Introduction 97 IETF Standards for machine to machine communication in constrained 98 environments describe a REST protocol [RFC7252] and a set of related 99 information standards that may be used to represent machine data and 100 machine metadata in REST interfaces. CoRE Link-format [RFC6690] is a 101 standard for doing Web Linking [RFC8288] in constrained environments. 103 This specification introduces the concept of a Link Binding, which 104 defines a new link relation type to create a dynamic link between 105 resources over which state updates are conveyed. Specifically, a 106 Link Binding is a unidirectional link for binding the states of 107 source and destination resources together such that updates to one 108 are sent over the link to the other. CoRE Link Format 109 representations are used to configure, inspect, and maintain Link 110 Bindings. This specification additionally defines Conditional 111 Notification Attributes for use with Link Bindings and with CoRE 112 Observe [RFC7641]. 114 2. Terminology 116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 118 "OPTIONAL" in this document are to be interpreted as described in 119 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 120 capitals, as shown here. 122 This specification requires readers to be familiar with all the terms 123 and concepts that are discussed in [RFC8288] and [RFC6690]. This 124 specification makes use of the following additional terminology: 126 Link Binding: A unidirectional logical link between a source 127 resource and a destination resource, over which state information 128 is synchronized. 130 State Synchronization: Depending on the binding method (Polling, 131 Observe, Push) different REST methods may be used to synchronize 132 the resource values between a source and a destination. The 133 process of using a REST method to achieve this is defined as 134 "State Synchronization". The endpoint triggering the state 135 synchronization is the synchronization initiator. 137 Notification Band: A resource value range that results in state 138 sychronization. The value range may be bounded by a minimum and 139 maximum value or may be unbounded having either a minimum or 140 maximum value. 142 3. Conditional Notification Attributes 144 3.1. Attribute Definitions 146 This specification defines Conditional Notification Attributes, which 147 provide for fine-grained control of notification and state 148 synchronization when using CoRE Observe [RFC7641] or Link Bindings 149 (see Section 4). Conditional Notification Attributes define the 150 conditions that trigger a notification. 152 When resource interfaces following this specification are made 153 available over CoAP, the CoAP Observation mechanism [RFC7641] MAY 154 also be used to observe any changes in a resource, and receive 155 asynchronous notifications as a result. A resource marked as 156 Observable in its link description SHOULD support these Conditional 157 Notification Attributes. 159 The set of parameters defined here allow a client to control how 160 often a client is interested in receiving notifications and how much 161 a resource value should change for the new representation to be 162 interesting. 164 One or more Notification Attributes MAY be included as query 165 parameters in an Observe request. 167 These attributes are defined below: 169 +--------------------+-----------+-----------------+ 170 | Attribute | Parameter | Value | 171 +--------------------+-----------+-----------------+ 172 | Minimum Period (s) | pmin | xs:decimal (>0) | 173 | | | | 174 | Maximum Period (s) | pmax | xs:decimal (>0) | 175 | | | | 176 | Change Step | st | xs:decimal (>0) | 177 | | | | 178 | Greater Than | gt | xs:decimal | 179 | | | | 180 | Less Than | lt | xs:decimal | 181 | | | | 182 | Notification Band | band | xs:boolean | 183 +--------------------+-----------+-----------------+ 185 Table 1: Conditional Notification Attributes 187 Conditional Notification Attributes SHOULD be evaluated on all 188 potential notifications from a resource, whether resulting from an 189 internal server-driven sampling process or from external update 190 requests to the server. 192 Note: In this draft, we assume that there are finite quantization 193 effects in the internal or external updates to the value of a 194 resource; specifically, that a resource may be updated at any time 195 with any valid value. We therefore avoid any continuous-time 196 assumptions in the description of the Conditional Notification 197 Attributes and instead use the phrase "sampled value" to refer to a 198 member of a sequence of values that may be internally observed from 199 the resource state over time. 201 3.1.1. Minimum Period (pmin) 203 When present, the minimum period indicates the minimum time, in 204 seconds, between two consecutive notifications (whether or not the 205 resource value has changed). In the absence of this parameter, the 206 minimum period is up to the server. The minimum period MUST be 207 greater than zero otherwise the receiver MUST return a CoAP error 208 code 4.00 "Bad Request" (or equivalent). 210 A server MAY report the last sampled value that occured during the 211 pmin interval, after the pmin interval expires. 213 Note: Due to finite quantization effects, the time between 214 notifications may be greater than pmin even when the sampled value 215 changes within the pmin interval. Pmin may or may not be used to 216 drive the internal sampling process. 218 3.1.2. Maximum Period (pmax) 220 When present, the maximum period indicates the maximum time, in 221 seconds, between two consecutive notifications (whether or not the 222 resource value has changed). In the absence of this parameter, the 223 maximum period is up to the server. The maximum period MUST be 224 greater than zero and MUST be greater than the minimum period 225 parameter (if present) otherwise the receiver MUST return a CoAP 226 error code 4.00 "Bad Request" (or equivalent). 228 3.1.3. Change Step (st) 230 When present, the change step indicates how much the value of a 231 resource SHOULD change before triggering a notification, compared to 232 the value of the previous notification. Upon reception of a query 233 including the st attribute, the most recently sampled value of the 234 resource is reported, and then set as the last reported value 235 (last_rep_v). When a subsequent sample or update of the resource 236 value differs from the last reported value by an amount, positive or 237 negative, greater than or equal to st, and the time for pmin has 238 elapsed since the last notification, a notification is sent and the 239 last reported value is updated to the value sent in the notification. 240 The change step MUST be greater than zero otherwise the receiver MUST 241 return a CoAP error code 4.00 "Bad Request" (or equivalent). 243 The Change Step parameter can only be supported on resources with a 244 scalar numeric value. 246 Note: Due to sampling and other constraints, e.g. pmin, the resource 247 value received in two sequential notifications may differ by more 248 than st. 250 3.1.4. Greater Than (gt) 252 When present, Greater Than indicates the upper limit value the 253 sampled value SHOULD cross before triggering a notification. A 254 notification is sent whenever the sampled value crosses the specified 255 upper limit value, relative to the last reported value, and the time 256 fpr pmin has elapsed since the last notification. The sampled value 257 is sent in the notification. If the value continues to rise, no 258 notifications are generated as a result of gt. If the value drops 259 below the upper limit value then a notification is sent, subject 260 again to the pmin time. 262 The Greater Than parameter can only be supported on resources with a 263 scalar numeric value. 265 3.1.5. Less Than (lt) 267 When present, Less Than indicates the lower limit value the resource 268 value SHOULD cross before triggering a notification. A notification 269 is sent when the samples value crosses the specified lower limit 270 value, relative to the last reported value, and the time fpr pmin has 271 elapsed since the last notification. The sampled value is sent in 272 the notification. If the value continues to fall no notifications 273 are generated as a result of lt. If the value rises above the lower 274 limit value then a new notification is sent, subject to the pmin 275 time.. 277 The Less Than parameter can only be supported on resources with a 278 scalar numeric value. 280 3.1.6. Notification Band (band) 282 The notification band attribute allows a bounded or unbounded (based 283 on a minimum or maximum) value range that may trigger multiple 284 notifications. This enables use cases where different ranges results 285 in differing behaviour. For example: monitoring the temperature of 286 machinery. Whilst the temperature is in the normal operating range 287 only periodic observations are needed. However as the temperature 288 moves to more abnormal ranges more frequent synchronization/reporting 289 may be needed. 291 Without a notification band, a transition across a less than (lt), or 292 greater than (gt) limit only generates one notification. This means 293 that it is not possible to describe a case where multiple 294 notifications are sent so long as the limit is exceeded. 296 The band attribute works as a modifier to the behaviour of gt and lt. 297 Therefore, if band is present in a query, gt, lt or both, MUST be 298 included. 300 When band is present with the lt attribute, it defines the lower 301 bound for the notification band (notification band minimum). 302 Notifications occur when the resource value is equal to or above the 303 notification band minimum. If lt is not present there is no minimum 304 value for the band. 306 When band is present with the gt attribute, it defines the upper 307 bound for the notification band (notification band maximum). 308 Notifications occur when the resource value is equal to or below the 309 notification band maximum. If gt is not present there is no maximum 310 value for the band. 312 If band is present with both the gt and lt attributes, notification 313 occurs when the resource value is greater than or equal to gt or when 314 the resource value is less than or equal to lt. 316 If a band is specified in which the value of gt is less than that of 317 lt, in-band notification occurs. That is, notification occurs 318 whenever the resource value is between the gt and lt values, 319 including equal to gt or lt. 321 If the band is specified in which the value of gt is greater than 322 that of lt, out-of-band notification occurs. That is, notification 323 occurs when the resource value not between the gt and lt values, 324 excluding equal to gt and lt. 326 The Notification Band parameter can only be supported on resources 327 with a scalar numeric value. 329 3.2. Server processing of Conditional Notification Attributes 331 Pmin, pmax, st, gt, lt and band may be present in the same query. 332 Howver, they are not defined at multiple prioritization levels. The 333 server sends a notification whenever any of the parameter conditions 334 are met, upon which it updates its last notification value and time 335 to prepare for the next notification. Only one notification occurs 336 when there are multiple conditions being met at the same time. The 337 reference code below illustrates the logic to determine when a 338 notification is to be sent. 340 bool notifiable( Resource * r ) { 342 #define BAND r->band 343 #define SCALAR_TYPE ( num_type == r->type ) 344 #define STRING_TYPE ( str_type == r->type ) 345 #define BOOLEAN_TYPE ( bool_type == r->type ) 346 #define PMIN_EX ( r->last_sample_time - r->last_rep_time >= r->pmin ) 347 #define PMAX_EX ( r->last_sample_time - r->last_rep_time > r->pmax ) 348 #define LT_EX ( r->v < r->lt ^ r->last_rep_v < r->lt ) 349 #define GT_EX ( r->v > r->gt ^ r->last_rep_v > r->gt ) 350 #define ST_EX ( abs( r->v - r->last_rep_v ) >= r->st ) 351 #define IN_BAND ( ( r->gt <= r->v && r->v <= r->lt ) || ( r->lt <= r->gt && r->gt <= r->v ) || ( r->v <= r->lt && r->lt <= r->gt ) ) 352 #define VB_CHANGE ( r->vb != r->last_rep_vb ) 353 #define VS_CHANGE ( r->vs != r->last_rep_vs ) 355 return ( 356 PMIN_EX && 357 ( SCALAR_TYPE ? 358 ( ( !BAND && ( GT_EX || LT_EX || ST_EX || PMAX_EX ) ) || 359 ( BAND && IN_BAND && ( ST_EX || PMAX_EX) ) ) 360 : STRING_TYPE ? 361 ( VS_CHANGE || PMAX_EX ) 362 : BOOLEAN_TYPE ? 363 ( VB_CHANGE || PMAX_EX ) 364 : false ) 365 ); 366 } 368 Figure 1: Code logic for conditional notification attribute 369 interactions 371 4. Link Bindings 373 In a M2M RESTful environment, endpoints may directly exchange the 374 content of their resources to operate the distributed system. For 375 example, a light switch may supply on-off control information that 376 may be sent directly to a light resource for on-off control. 378 Beforehand, a configuration phase is necessary to determine how the 379 resources of the different endpoints are related to each other. This 380 can be done either automatically using discovery mechanisms or by 381 means of human intervention and a so-called commissioning tool. 383 In this specification such an abstract relationship between two 384 resources is defined, called a Link Binding. The configuration phase 385 necessitates the exchange of binding information, so a format 386 recognized by all CoRE endpoints is essential. This specification 387 defines a format based on the CoRE Link-Format to represent binding 388 information along with the rules to define a binding method which is 389 a specialized relationship between two resources. 391 The purpose of such a binding is to synchronize content updates 392 between a source resource and a destination resource. The 393 destination resource MAY be a group resource if the authority 394 component of the destination URI contains a group address (either a 395 multicast address or a name that resolves to a multicast address). 396 Since a binding is unidirectional, the binding entry defining a 397 relationship is present only on one endpoint. The binding entry may 398 be located either on the source or the destination endpoint depending 399 on the binding method. 401 Conditional Notification Attributes defined in Section 3 can be used 402 with Link Bindings in order to customize the notification behavior 403 and timing. 405 4.1. The "bind" attribute and Binding Methods 407 A binding method defines the rules to generate the network-transfer 408 exchanges that synchronize state between source and destination 409 resources. By using REST methods content is sent from the source 410 resource to the destination resource. 412 This specification defines a new CoRE link attribute "bind". This is 413 the identifier for a binding method which defines the rules to 414 synchronize the destination resource. This attribute is mandatory. 416 +----------------+-----------+-----------+ 417 | Attribute | Parameter | Value | 418 +----------------+-----------+-----------+ 419 | Binding method | bind | xs:string | 420 +----------------+-----------+-----------+ 422 Table 2: The bind attribute 424 The following table gives a summary of the binding methods defined in 425 this specification. 427 +---------+------------+-------------+---------------+ 428 | Name | Identifier | Location | Method | 429 +---------+------------+-------------+---------------+ 430 | Polling | poll | Destination | GET | 431 | | | | | 432 | Observe | obs | Destination | GET + Observe | 433 | | | | | 434 | Push | push | Source | PUT | 435 | | | | | 436 | Execute | exec | Source | POST | 437 +---------+------------+-------------+---------------+ 439 Table 3: Binding Method Summary 441 The description of a binding method defines the following aspects: 443 Identifier: This is the value of the "bind" attribute used to 444 identify the method. 446 Location: This information indicates whether the binding entry is 447 stored on the source or on the destination endpoint. 449 REST Method: This is the REST method used in the Request/Response 450 exchanges. 452 Conditional Notification: How Conditional Notification Attributes 453 are used in the binding. 455 The binding methods are described in more detail below. 457 4.1.1. Polling 459 The Polling method consists of sending periodic GET requests from the 460 destination endpoint to the source resource and copying the content 461 to the destination resource. The binding entry for this method MUST 462 be stored on the destination endpoint. The destination endpoint MUST 463 ensure that the polling frequency does not exceed the limits defined 464 by the pmin and pmax attributes of the binding entry. The copying 465 process MAY filter out content from the GET requests using value- 466 based conditions (e.g based on the Change Step, Less Than, Greater 467 Than attributes). 469 4.1.2. Observe 471 The Observe method creates an observation relationship between the 472 destination endpoint and the source resource. On each notification 473 the content from the source resource is copied to the destination 474 resource. The creation of the observation relationship requires the 475 CoAP Observation mechanism [RFC7641] hence this method is only 476 permitted when the resources are made available over CoAP. The 477 binding entry for this method MUST be stored on the destination 478 endpoint. The binding conditions are mapped as query parameters in 479 the Observe request (see Section 3). 481 4.1.3. Push 483 The Push method can be used to allow a source endpoint to replace an 484 outdated resource state at the destination with a newer 485 representation. When the Push method is assigned to a binding, the 486 source endpoint sends PUT requests to the destination resource when 487 the Conditional Notification Attributes are satisfied for the source 488 resource. The source endpoint SHOULD only send a notification 489 request if any included Conditional Notification Attributes are met. 490 The binding entry for this method MUST be stored on the source 491 endpoint. 493 4.1.4. Execute 495 An alternative means for a source endpoint to deliver change-of-state 496 notifications to a destination resource is to use the Execute Method. 497 While the Push method simply updates the state of the destination 498 resource with the representation of the source resource, Execute can 499 be used when the destination endpoint wishes to receive all state 500 changes from a source. This allows, for example, the existence of a 501 resource collection consisting of all the state changes at the 502 destination endpoint. When the Execute method is assigned to a 503 binding, the source endpoint sends POST requests to the destination 504 resource when the Conditional Notification Attributes are satisfied 505 for the source resource. The source endpoint SHOULD only send a 506 notification request if any included Conditional Notification 507 Attributes are met. The binding entry for this method MUST be stored 508 on the source endpoint. 510 Note: Both the Push and the Execute methods are examples of Server 511 Push mechanisms that are being researched in the Thing-to-Thing 512 Research Group (T2TRG) [I-D.irtf-t2trg-rest-iot]. 514 4.2. Link Relation 516 Since Binding involves the creation of a link between two resources, 517 Web Linking and the CoRE Link-Format used to represent binding 518 information. This involves the creation of a new relation type, 519 "boundto". In a Web link with this relation type, the target URI 520 contains the location of the source resource and the context URI 521 points to the destination resource. 523 5. Binding Table 525 The Binding Table is a special resource that describes the bindings 526 on an endpoint. An endpoint offering a representation of the Binding 527 Table resource SHOULD indicate its presence and enable its discovery 528 by advertising a link at "/.well-known/core" [RFC6690]. If so, the 529 Binding Table resource MUST be discoverable by using the Resource 530 Type (rt) 'core.bnd'. 532 The Methods column defines the REST methods supported by the Binding 533 Table, which are described in more detail below. 535 +---------------+----------+----------+----------------+ 536 | Resource | rt= | Methods | Content-Format | 537 +---------------+----------+----------+----------------+ 538 | Binding Table | core.bnd | GET, PUT | link-format | 539 +---------------+----------+----------+----------------+ 541 Table 4: Binding Table Description 543 The REST methods GET and PUT are used to manipulate a Binding Table. 544 A GET request simply returns the current state of a Binding Table. A 545 request with a PUT method and a content format of application/link- 546 format is used to clear the bindings to the table or replaces its 547 entire contents. All links in the payload of a PUT rquest MUST have 548 a relation type "boundto". 550 The following example shows requests for discovering, retrieving and 551 replacing bindings in a binding table. 553 Req: GET /.well-known/core?rt=core.bnd (application/link-format) 554 Res: 2.05 Content (application/link-format) 555 ;rt=core.bnd;ct=40 557 Req: GET /bnd/ 558 Res: 2.05 Content (application/link-format) 559 ; 560 rel=boundto;anchor=/a/fan,;bind="obs", 561 ; 562 rel=boundto;anchor=/a/light;bind="obs" 564 Req: PUT /bnd/ (Content-Format: application/link-format) 565 ; 566 rel="boundto";anchor="/a/light";bind="obs";pmin=10;pmax=60 567 Res: 2.04 Changed 569 Req: GET /bnd/ 570 Res: 2.05 Content (application/link-format) 571 ; 572 rel="boundto";anchor="/a/light";bind="obs";pmin=10;pmax=60 574 Figure 2: Binding Table Example 576 Additional operations on the Binding Table can be specified in future 577 documents. Such operations can include, for example, the usage of 578 the iPATCH or PATCH methods [RFC8132] for fine-grained addition and 579 removal of individual bindings or binding subsets. 581 6. Implementation Considerations 583 When using multiple resource bindings (e.g. multiple Observations of 584 resource) with different bands, consideration should be given to the 585 resolution of the resource value when setting sequential bands. For 586 example: Given BandA (Abmn=10, Bbmx=20) and BandB (Bbmn=21, Bbmx=30). 587 If the resource value returns an integer then notifications for 588 values between and inclusive of 10 and 30 will be triggered. Whereas 589 if the resolution is to one decimal point (0.1) then notifications 590 for values 20.1 to 20.9 will not be triggered. 592 The use of the notification band minimum and maximum allow for a 593 synchronization whenever a change in the resource value occurs. 594 Theoretically this could occur in-line with the server internal 595 sample period for the determining the resource value. Implementors 596 SHOULD consider the resolution needed before updating the resource, 597 e.g. updating the resource when a temperature sensor value changes by 598 0.001 degree versus 1 degree. 600 The initiation of a Link Binding can be delegated from a client to a 601 link state machine implementation, which can be an embedded client or 602 a configuration tool. Implementation considerations have to be given 603 to how to monitor transactions made by the configuration tool with 604 regards to Link Bindings, as well as any errors that may arise with 605 establishing Link Bindings in addition to established Link Bindings. 607 7. Security Considerations 609 Consideration has to be given to what kinds of security credentials 610 the state machine of a configuration tool or an embedded client needs 611 to be configured with, and what kinds of access control lists client 612 implementations should possess, so that transactions on creating Link 613 Bindings and handling error conditions can be processed by the state 614 machine. 616 8. IANA Considerations 618 8.1. Resource Type value 'core.bnd' 620 This specification registers a new Resource Type Link Target 621 Attribute 'core.bnd' in the Resource Type (rt=) registry established 622 as per [RFC6690]. 624 Attribute Value: core.bnd 626 Description: See Section 5. This attribute value is used to discover 627 the resource representing a binding table, which describes the link 628 bindings between source and destination resources for the purposes of 629 synchronizing their content. 631 Reference: This specification. Note to RFC editor: please insert the 632 RFC of this specification. 634 Notes: None 636 8.2. Link Relation Type 638 This specification registers the new "boundto" link relation type as 639 per [RFC8288]. 641 Relation Name: boundto 643 Description: The purpose of a boundto relation type is to indicate 644 that there is a binding between a source resource and a 645 destination resource for the purposes of synchronizing their 646 content. 648 Reference: This specification. Note to RFC editor: please insert 649 the RFC of this specification. 651 Notes: None 653 Application Data: None 655 9. Acknowledgements 657 Acknowledgement is given to colleagues from the SENSEI project who 658 were critical in the initial development of the well-known REST 659 interface concept, to members of the IPSO Alliance where further 660 requirements for interface types have been discussed, and to Szymon 661 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 662 provided useful discussion and input to the concepts in this 663 specification. Christian Amsuss supplied a comprehensive review of 664 draft -06. Hannes Tschofenig and Mert Ocak highlighted syntactical 665 corrections in the usage of pmax and pmin in a query. Discussions 666 with Ari Keraenen led to the addition of an extra binding method 667 supporting POST operations. 669 10. Contributors 671 Christian Groves 672 Australia 673 email: cngroves.std@gmail.com 675 Zach Shelby 676 ARM 677 Vuokatti 678 FINLAND 679 phone: +358 40 7796297 680 email: zach.shelby@arm.com 682 Matthieu Vial 683 Schneider-Electric 684 Grenoble 685 France 686 phone: +33 (0)47657 6522 687 eMail: matthieu.vial@schneider-electric.com 689 Jintao Zhu 690 Huawei 691 Xi'an, Shaanxi Province 692 China 693 email: jintao.zhu@huawei.com 695 11. Changelog 697 draft-ietf-core-dynlink-11 699 o Updates to author list 701 draft-ietf-core-dynlink-10 703 o Binding methods now support both POST and PUT operations for 704 server push. 706 draft-ietf-core-dynlink-09 708 o Corrections in Table 1, Table 2, Figure 2. 710 o Clarifications for additional operations to binding table added in 711 section 5 713 o Additional examples in Appendix A 715 draft-ietf-core-dynlink-08 717 o Reorganize the draft to introduce Conditional Notification 718 Attributes at the beginning 720 o Made pmin and pmax type xs:decimal to accommodate fractional 721 second timing 723 o updated the attribute descriptions. lt and gt notify on all 724 crossings, both directions 726 o updated Binding Table description, removed interface description 727 but introduced core.bnd rt attribute value 729 draft-ietf-core-dynlink-07 731 o Added reference code to illustrate attribute interactions for 732 observations 734 draft-ietf-core-dynlink-06 736 o Document restructure and refactoring into three main sections 738 o Clarifications on band usage 740 o Implementation considerations introduced 742 o Additional text on security considerations 743 o Addition of a band modifier for gt and lt, adapted from draft- 744 groves-core-obsattr 746 o Removed statement prescribing gt MUST be greater than lt 748 draft-ietf-core-dynlink-03 750 o General: Reverted to using "gt" and "lt" from "gth" and "lth" for 751 this draft owing to concerns raised that the attributes are 752 already used in LwM2M with the original names "gt" and "lt". 754 o New author and editor added. 756 draft-ietf-core-dynlink-02 758 o General: Changed the name of the greater than attribute "gt" to 759 "gth" and the name of the less than attribute "lt" to "lth" due to 760 conlict with the core resource directory draft lifetime "lt" 761 attribute. 763 o Clause 6.1: Addressed the editor's note by changing the link 764 target attribute to "core.binding". 766 o Added Appendix A for examples. 768 draft-ietf-core-dynlink-01 770 o General: The term state synchronization has been introduced to 771 describe the process of synchronization between destination and 772 source resources. 774 o General: The document has been restructured the make the 775 information flow better. 777 o Clause 3.1: The descriptions of the binding attributes have been 778 updated to clarify their usage. 780 o Clause 3.1: A new clause has been added to discuss the 781 interactions between the resources. 783 o Clause 3.4: Has been simplified to refer to the descriptions in 784 3.1. As the text was largely duplicated. 786 o Clause 4.1: Added a clarification that individual resources may be 787 removed from the binding table. 789 o Clause 6: Formailised the IANA considerations. 791 draft-ietf-core-dynlink Initial Version 00: 793 o This is a copy of draft-groves-core-dynlink-00 795 draft-groves-core-dynlink Draft Initial Version 00: 797 o This initial version is based on the text regarding the dynamic 798 linking functionality in I.D.ietf-core-interfaces-05. 800 o The WADL description has been dropped in favour of a thorough 801 textual description of the REST API. 803 12. References 805 12.1. Normative References 807 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 808 Requirement Levels", BCP 14, RFC 2119, 809 DOI 10.17487/RFC2119, March 1997, 810 . 812 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 813 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 814 . 816 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 817 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 818 May 2017, . 820 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 821 DOI 10.17487/RFC8288, October 2017, 822 . 824 12.2. Informative References 826 [I-D.irtf-t2trg-rest-iot] 827 Keranen, A., Kovatsch, M., and K. Hartke, "RESTful Design 828 for Internet of Things Systems", draft-irtf-t2trg-rest- 829 iot-06 (work in progress), May 2020. 831 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 832 Application Protocol (CoAP)", RFC 7252, 833 DOI 10.17487/RFC7252, June 2014, 834 . 836 [RFC7641] Hartke, K., "Observing Resources in the Constrained 837 Application Protocol (CoAP)", RFC 7641, 838 DOI 10.17487/RFC7641, September 2015, 839 . 841 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 842 FETCH Methods for the Constrained Application Protocol 843 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 844 . 846 Appendix A. Examples 848 This appendix provides some examples of the use of binding attribute 849 / observe attributes. 851 Note: For brevity the only the method or response code is shown in 852 the header field. 854 A.1. Minimum Period (pmin) example 855 Observed CLIENT SERVER Actual 856 t State | | State 857 ____________ | | ____________ 858 1 | | 859 2 unknown | | 18.5 Cel 860 3 +----->| Header: GET 861 4 | GET | Token: 0x4a 862 5 | | Uri-Path: temperature 863 6 | | Uri-Query: pmin="10" 864 7 | | Observe: 0 (register) 865 8 | | 866 9 ____________ |<-----+ Header: 2.05 867 10 | 2.05 | Token: 0x4a 868 11 18.5 Cel | | Observe: 9 869 12 | | Payload: "18.5 Cel" 870 13 | | ____________ 871 14 | | 872 15 | | 23 Cel 873 16 | | 874 17 | | 875 18 | | 876 19 | | ____________ 877 20 ____________ |<-----+ Header: 2.05 878 21 | 2.05 | 26 Cel Token: 0x4a 879 22 26 Cel | | Observe: 20 880 23 | | Payload: "26 Cel" 881 24 | | 882 25 | | 884 Figure 3: Client registers and receives one notification of the 885 current state and one of a new state state when pmin time expires. 887 A.2. Maximum Period (pmax) example 889 Observed CLIENT SERVER Actual 890 t State | | State 891 ____________ | | ____________ 892 1 | | 893 2 unknown | | 18.5 Cel 894 3 +----->| Header: GET 895 4 | GET | Token: 0x4a 896 5 | | Uri-Path: temperature 897 6 | | Uri-Query: pmax="20" 898 7 | | Observe: 0 (register) 899 8 | | 900 9 ____________ |<-----+ Header: 2.05 901 10 | 2.05 | Token: 0x4a 902 11 18.5 Cel | | Observe: 9 903 12 | | Payload: "18.5 Cel" 904 13 | | 905 14 | | 906 15 | | ____________ 907 16 ____________ |<-----+ Header: 2.05 908 17 | 2.05 | 23 Cel Token: 0x4a 909 18 23 Cel | | Observe: 16 910 19 | | Payload: "23 Cel" 911 20 | | 912 21 | | 913 22 | | 914 23 | | 915 24 | | 916 25 | | 917 26 | | 918 27 | | 919 28 | | 920 29 | | 921 30 | | 922 31 | | 923 32 | | 924 33 | | 925 34 | | 926 35 | | 927 36 | | ____________ 928 37 ____________ |<-----+ Header: 2.05 929 38 | 2.05 | 23 Cel Token: 0x4a 930 39 23 Cel | | Observe: 37 931 40 | | Payload: "23 Cel" 932 41 | | 933 42 | | 935 Figure 4: Client registers and receives one notification of the 936 current state, one of a new state and one of an unchanged state when 937 pmax time expires. 939 A.3. Greater Than (gt) example 940 Observed CLIENT SERVER Actual 941 t State | | State 942 ____________ | | ____________ 943 1 | | 944 2 unknown | | 18.5 Cel 945 3 +----->| Header: GET 946 4 | GET | Token: 0x4a 947 5 | | Uri-Path: temperature 948 6 | | Uri-Query: gt=25 949 7 | | Observe: 0 (register) 950 8 | | 951 9 ____________ |<-----+ Header: 2.05 952 10 | 2.05 | Token: 0x4a 953 11 18.5 Cel | | Observe: 9 954 12 | | Payload: "18.5 Cel" 955 13 | | 956 14 | | 957 15 | | ____________ 958 16 ____________ |<-----+ Header: 2.05 959 17 | 2.05 | 26 Cel Token: 0x4a 960 18 26 Cel | | Observe: 16 961 29 | | Payload: "26 Cel" 962 20 | | 963 21 | | 965 Figure 5: Client registers and receives one notification of the 966 current state and one of a new state when it passes through the 967 greater than threshold of 25. 969 A.4. Greater Than (gt) and Period Max (pmax) example 971 Observed CLIENT SERVER Actual 972 t State | | State 973 ____________ | | ____________ 974 1 | | 975 2 unknown | | 18.5 Cel 976 3 +----->| Header: GET 977 4 | GET | Token: 0x4a 978 5 | | Uri-Path: temperature 979 6 | | Uri-Query: pmax=20;gt=25 980 7 | | Observe: 0 (register) 981 8 | | 982 9 ____________ |<-----+ Header: 2.05 983 10 | 2.05 | Token: 0x4a 984 11 18.5 Cel | | Observe: 9 985 12 | | Payload: "18.5 Cel" 986 13 | | 987 14 | | 988 15 | | 989 16 | | 990 17 | | 991 18 | | 992 19 | | 993 20 | | 994 21 | | 995 22 | | 996 23 | | 997 24 | | 998 25 | | 999 26 | | 1000 27 | | 1001 28 | | 1002 29 | | ____________ 1003 30 ____________ |<-----+ Header: 2.05 1004 31 | 2.05 | 23 Cel Token: 0x4a 1005 32 23 Cel | | Observe: 30 1006 33 | | Payload: "23 Cel" 1007 34 | | 1008 35 | | 1009 36 | | ____________ 1010 37 ____________ |<-----+ Header: 2.05 1011 38 | 2.05 | 26 Cel Token: 0x4a 1012 39 26 Cel | | Observe: 37 1013 40 | | Payload: "26 Cel" 1014 41 | | 1015 42 | | 1017 Figure 6: Client registers and receives one notification of the 1018 current state, one when pmax time expires and one of a new state when 1019 it passes through the greater than threshold of 25. 1021 Authors' Addresses 1023 Michael Koster 1024 SmartThings 1025 665 Clyde Avenue 1026 Mountain View 94043 1027 USA 1029 Email: michael.koster@smartthings.com 1030 Bilhanan Silverajan (editor) 1031 Tampere University 1032 Kalevantie 4 1033 Tampere FI-33100 1034 Finland 1036 Email: bilhanan.silverajan@tuni.fi