idnits 2.17.1 draft-ietf-core-dynlink-07.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 (October 22, 2018) is 2006 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 ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group Z. Shelby 3 Internet-Draft ARM 4 Intended status: Informational M. Koster 5 Expires: April 25, 2019 SmartThings 6 C. Groves 8 J. Zhu 9 Huawei 10 B. Silverajan, Ed. 11 Tampere University of Technology 12 October 22, 2018 14 Dynamic Resource Linking for Constrained RESTful Environments 15 draft-ietf-core-dynlink-07 17 Abstract 19 For CoAP (RFC7252), Dynamic linking of state updates between 20 resources, either on an endpoint or between endpoints, is defined 21 with the concept of Link Bindings. This specification defines 22 conditional observation attributes that work with Link Bindings or 23 with CoAP Observe (RFC7641). 25 Editor note 27 The git repository for the draft is found at https://github.com/core- 28 wg/dynlink 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on April 25, 2019. 47 Copyright Notice 49 Copyright (c) 2018 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 66 3. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3.1. The "bind" attribute and Binding Methods . . . . . . . . 4 68 3.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 5 69 3.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 5 70 3.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 6 71 3.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 6 72 4. Binding and Resource Observation Attributes . . . . . . . . . 6 73 4.1. Minimum Period (pmin) . . . . . . . . . . . . . . . . . . 7 74 4.2. Maximum Period (pmax) . . . . . . . . . . . . . . . . . . 7 75 4.3. Change Step (st) . . . . . . . . . . . . . . . . . . . . 7 76 4.4. Greater Than (gt) . . . . . . . . . . . . . . . . . . . . 8 77 4.5. Less Than (lt) . . . . . . . . . . . . . . . . . . . . . 8 78 4.6. Notification Band (band) . . . . . . . . . . . . . . . . 8 79 4.7. Attribute Interactions . . . . . . . . . . . . . . . . . 9 80 5. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 10 81 6. Implementation Considerations . . . . . . . . . . . . . . . . 11 82 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 83 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 84 8.1. Interface Description . . . . . . . . . . . . . . . . . . 12 85 8.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 13 86 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 87 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 13 88 11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 13 89 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 90 12.1. Normative References . . . . . . . . . . . . . . . . . . 15 91 12.2. Informative References . . . . . . . . . . . . . . . . . 16 92 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 16 93 A.1. Greater Than (gt) example . . . . . . . . . . . . . . . . 16 94 A.2. Greater Than (gt) and Period Max (pmax) example . . . . . 17 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 98 1. Introduction 100 IETF Standards for machine to machine communication in constrained 101 environments describe a REST protocol [RFC7252] and a set of related 102 information standards that may be used to represent machine data and 103 machine metadata in REST interfaces. CoRE Link-format [RFC6690] is a 104 standard for doing Web Linking [RFC8288] in constrained environments. 106 This specification introduces the concept of a Link Binding, which 107 defines a new link relation type to create a dynamic link between 108 resources over which state updates are conveyed. Specifically, a 109 Link Binding is a unidirectional link for binding the states of 110 source and destination resources together such that updates to one 111 are sent over the link to the other. CoRE Link Format 112 representations are used to configure, inspect, and maintain Link 113 Bindings. This specification additionally defines a set of 114 conditional Observe Attributes for use with Link Bindings and with 115 the standalone CoRE Observe [RFC7641] method. 117 2. Terminology 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 121 "OPTIONAL" in this document are to be interpreted as described in BCP 122 14 [RFC2119] [RFC8174] when, and only when, they appear in all 123 capitals, as shown here. 125 This specification requires readers to be familiar with all the terms 126 and concepts that are discussed in [RFC8288] and [RFC6690]. This 127 specification makes use of the following additional terminology: 129 Link Binding: A unidirectional logical link between a source 130 resource and a destination resource, over which state information 131 is synchronized. 133 State Synchronization: Depending on the binding method (Polling, 134 Observe, Push) different REST methods may be used to synchronize 135 the resource values between a source and a destination. The 136 process of using a REST method to achieve this is defined as 137 "State Synchronization". The endpoint triggering the state 138 synchronization is the synchronization initiator. 140 Notification Band: A resource value range that results in state 141 sychronization. The value range may be bounded by a minimum and 142 maximum value or may be unbounded having either a minimum or 143 maximum value. 145 3. Link Bindings 147 In a M2M RESTful environment, endpoints may directly exchange the 148 content of their resources to operate the distributed system. For 149 example, a light switch may supply on-off control information that 150 may be sent directly to a light resource for on-off control. 151 Beforehand, a configuration phase is necessary to determine how the 152 resources of the different endpoints are related to each other. This 153 can be done either automatically using discovery mechanisms or by 154 means of human intervention and a so-called commissioning tool. In 155 this specification such an abstract relationship between two 156 resources is defined, called a link Binding. The configuration phase 157 necessitates the exchange of binding information so a format 158 recognized by all CoRE endpoints is essential. This specification 159 defines a format based on the CoRE Link-Format to represent binding 160 information along with the rules to define a binding method which is 161 a specialized relationship between two resources. The purpose of 162 such a binding is to synchronize the content between a source 163 resource and a destination resource. The destination resource MAY be 164 a group resource if the authority component of the destination URI 165 contains a group address (either a multicast address or a name that 166 resolves to a multicast address). Since a binding is unidirectional, 167 the binding entry defining a relationship is present only on one 168 endpoint. The binding entry may be located either on the source or 169 the destination endpoint depending on the binding method. 171 3.1. The "bind" attribute and Binding Methods 173 A binding method defines the rules to generate the web-transfer 174 exchanges that synchronize state between source and destination 175 resources. By using REST methods content is sent from the source 176 resource to the destination resource. 178 In order to use binding methods, this specification defines a special 179 CoRE link attribute "bind". This is the identifier of a binding 180 method which defines the rules to synchronize the destination 181 resource. This attribute is mandatory. 183 +----------------+-----------+------------+ 184 | Attribute | Parameter | Value | 185 +----------------+-----------+------------+ 186 | Binding method | bind | xsd:string | 187 +----------------+-----------+------------+ 189 Table 1: The bind attribute 191 The following table gives a summary of the binding methods defined in 192 this specification. 194 +---------+------------+-------------+---------------+ 195 | Name | Identifier | Location | Method | 196 +---------+------------+-------------+---------------+ 197 | Polling | poll | Destination | GET | 198 | | | | | 199 | Observe | obs | Destination | GET + Observe | 200 | | | | | 201 | Push | push | Source | PUT | 202 +---------+------------+-------------+---------------+ 204 Table 2: Binding Method Summary 206 The description of a binding method must define the following 207 aspects: 209 Identifier: This is the value of the "bind" attribute used to 210 identify the method. 212 Location: This information indicates whether the binding entry is 213 stored on the source or on the destination endpoint. 215 REST Method: This is the REST method used in the Request/Response 216 exchanges. 218 Conditions: A binding method definition must state how the condition 219 attributes of the abstract binding definition are actually used in 220 this specialized binding. 222 The binding methods are described in more detail below. 224 3.1.1. Polling 226 The Polling method consists of sending periodic GET requests from the 227 destination endpoint to the source resource and copying the content 228 to the destination resource. The binding entry for this method MUST 229 be stored on the destination endpoint. The destination endpoint MUST 230 ensure that the polling frequency does not exceed the limits defined 231 by the pmin and pmax attributes of the binding entry. The copying 232 process MAY filter out content from the GET requests using value- 233 based conditions (e.g based on the Change Step, Less Than, Greater 234 Than attributes). 236 3.1.2. Observe 238 The Observe method creates an observation relationship between the 239 destination endpoint and the source resource. On each notification 240 the content from the source resource is copied to the destination 241 resource. The creation of the observation relationship requires the 242 CoAP Observation mechanism [RFC7641] hence this method is only 243 permitted when the resources are made available over CoAP. The 244 binding entry for this method MUST be stored on the destination 245 endpoint. The binding conditions are mapped as query string 246 parameters (see Section 4). 248 3.1.3. Push 250 When the Push method is assigned to a binding, the source endpoint 251 sends PUT requests to the destination resource when the binding 252 condition attributes are satisfied for the source resource. The 253 source endpoint MUST only send a notification request if the binding 254 conditions are met. The binding entry for this method MUST be stored 255 on the source endpoint. 257 3.2. Link Relation 259 Since Binding involves the creation of a link between two resources, 260 Web Linking and the CoRE Link-Format are a natural way to represent 261 binding information. This involves the creation of a new relation 262 type, named "boundto". In a Web link with this relation type, the 263 target URI contains the location of the source resource and the 264 context URI points to the destination resource. 266 4. Binding and Resource Observation Attributes 268 In addition to "bind", this specification further defines Web link 269 attributes allowing a fine-grained control of the type of state 270 synchronization along with the conditions that trigger an update. 272 When resource interfaces following this specification are made 273 available over CoAP, the CoAP Observation mechanism [RFC7641] MAY 274 also be used to observe any changes in a resource, and receive 275 asynchronous notifications as a result. A resource using an 276 interface description defined in this specification and marked as 277 Observable in its link description SHOULD support these observation 278 parameters. 280 In addition, the set of parameters are defined here allow a client to 281 control how often a client is interested in receiving notifications 282 and how much a resource value should change for the new 283 representation to be interesting, as query parameters. 285 These query parameters MUST be treated as resources that are read 286 using GET and updated using PUT, and MUST NOT be included in the 287 Observe request. Multiple parameters MAY be updated at the same time 288 by including the values in the query string of a PUT. Before being 289 updated, these parameters have no default value. 291 These attributes are defined below: 293 +--------------------+-----------+------------------+ 294 | Attribute | Parameter | Value | 295 +--------------------+-----------+------------------+ 296 | Minimum Period (s) | pmin | xsd:integer (>0) | 297 | | | | 298 | Maximum Period (s) | pmax | xsd:integer (>0) | 299 | | | | 300 | Change Step | st | xsd:decimal (>0) | 301 | | | | 302 | Greater Than | gt | xsd:decimal | 303 | | | | 304 | Less Than | lt | xsd:decimal | 305 | | | | 306 | Notification Band | band | xsd:boolean | 307 +--------------------+-----------+------------------+ 309 Table 3: Binding Attributes Summary 311 4.1. Minimum Period (pmin) 313 When present, the minimum period indicates the minimum time to wait 314 (in seconds) before triggering a new state synchronization (even if 315 it has changed). In the absence of this parameter, the minimum 316 period is up to the synchronization initiator. The minimum period 317 MUST be greater than zero otherwise the receiver MUST return a CoAP 318 error code 4.00 "Bad Request" (or equivalent). 320 4.2. Maximum Period (pmax) 322 When present, the maximum period indicates the maximum time in 323 seconds between two consecutive state synchronizations (regardless if 324 it has changed). In the absence of this parameter, the maximum 325 period is up to the synchronization initiator. The maximum period 326 MUST be greater than zero and MUST be greater than the minimum period 327 parameter (if present) otherwise the receiver MUST return a CoAP 328 error code 4.00 "Bad Request" (or equivalent). 330 4.3. Change Step (st) 332 When present, the change step indicates how much the value of a 333 resource SHOULD change before triggering a new state synchronization 334 (compared to the value of the previous synchronization). Upon 335 reception of a query including the st attribute the current value 336 (CurrVal) of the resource is set as the initial value (STinit). Once 337 the resource value differs from the STinit value (i.e. CurrVal >= 338 STinit + ST or CurrVal <= STint - ST) then a new state 339 synchronization occurs. STinit is then set to the state 340 synchronization value and new state synchronizations are based on a 341 change step against this value. The change step MUST be greater than 342 zero otherwise the receiver MUST return a CoAP error code 4.00 "Bad 343 Request" (or equivalent). 345 The Change Step parameter can only be supported on resources with an 346 atomic numeric value. 348 Note: Due to the state synchronization based update of STint it may 349 result in that resource value received in two sequential state 350 synchronizations differs by more than st. 352 4.4. Greater Than (gt) 354 When present, Greater Than indicates the upper limit value the 355 resource value SHOULD cross before triggering a new state 356 synchronization. State synchronization only occurs when the resource 357 value exceeds the specified upper limit value. The actual resource 358 value is used for the synchronization rather than the gt value. If 359 the value continues to rise, no new state synchronizations are 360 generated as a result of gt. If the value drops below the upper 361 limit value and then exceeds the upper limit then a new state 362 synchronization is generated. 364 4.5. Less Than (lt) 366 When present, Less Than indicates the lower limit value the resource 367 value SHOULD cross before triggering a new state synchronization. 368 State synchronization only occurs when the resource value is less 369 than the specified lower limit value. The actual resource value is 370 used for the synchronization rather than the lt value. If the value 371 continues to fall no new state synchronizations are generated as a 372 result of lt. If the value rises above the lower limit value and 373 then drops below the lower limit then a new state synchronization is 374 generated. 376 4.6. Notification Band (band) 378 The notification band attribute allows a bounded or unbounded (based 379 on a minimum or maximum) value range that may trigger multiple state 380 synchronizations. This enables use cases where different ranges 381 results in differing behaviour. For example: monitoring the 382 temperature of machinery. Whilst the temperature is in the normal 383 operating range only periodic observations are needed. However as 384 the temperature moves to more abnormal ranges more frequent 385 synchronization/reporting may be needed. 387 Without a notification band, a transition across a less than (lt), or 388 greater than (gt) limit only generates one notification. This means 389 that it is not possible to describe a case where multiple 390 notifications are sent so long as the limit is exceeded. 392 The band attribute works as a modifier to the behaviour of gt and lt. 393 Therefore, if band is present in a query, gt, lt or both, MUST be 394 included. 396 When band is present with the lt attribute, it defines the lower 397 bound for the notification band (notification band minimum). State 398 synchronization occurs when the resource value is equal to or above 399 the notification band minimum. If lt is not present there is no 400 minimum value for the band. 402 When band is present with the gt attribute, it defines the upper 403 bound for the notification band (notification band maximum). State 404 synchronization occurs when the resource value is equal to or below 405 the notification band maximum. If gt is not present there is no 406 maximum value for the band. 408 If band is present with both the gt and lt attributes, two kinds of 409 signaling bands are specified. 411 If a band is specified in which the value of gt is less than that of 412 lt, in-band signaling occurs. State synchronization occurs whenever 413 the resource value is between the notification band minimum and 414 maximum or is equal to the notification band minimum or maximum. 416 On the other hand if the band is specified in which the value of gt 417 is greater than that of lt, out-of-band signaling occurs. State 418 synchronization occurs whenever the resource value is outside the 419 notification band minimum and maximum or is equal to the notification 420 band minimum or maximum. 422 4.7. Attribute Interactions 424 Pmin, pmax, st, gt and lt may be present in the same query. 425 Parameters are not defined at multiple prioritization levels. 426 Instead, the server state machine generates a notification whenever 427 any of the parameter conditions are met, after which it performs a 428 reset on all the requested conditions. State synchronization also 429 occurs only once even if there are multiple conditions being met at 430 the same time. The reference code below illustrates how 431 notifications are generated. 433 bool notifiable( Resource * r ) { 435 #define BAND r->band 436 #define SCALAR_TYPE ( num_type == r->type ) 437 #define STRING_TYPE ( str_type == r->type ) 438 #define BOOLEAN_TYPE ( bool_type == r->type ) 439 #define PMIN_EX ( r->last_sample_time - r->last_rep_time >= r->pmin ) 440 #define PMAX_EX ( r->last_sample_time - r->last_rep_time > r->pmax ) 441 #define LT_EX ( r->v < r->lt ^ r->last_rep_v < r->lt ) 442 #define GT_EX ( r->v > r->gt ^ r->last_rep_v > r->gt ) 443 #define ST_EX ( abs( r->v - r->last_rep_v ) >= r->st ) 444 #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 ) ) 445 #define VB_CHANGE ( r->vb != r->last_rep_vb ) 446 #define VS_CHANGE ( r->vs != r->last_rep_vs ) 448 return ( 449 PMIN_EX && 450 ( SCALAR_TYPE ? 451 ( ( !BAND && ( GT_EX || LT_EX || ST_EX || PMAX_EX ) ) || 452 ( BAND && IN_BAND && ( ST_EX || PMAX_EX) ) ) 453 : STRING_TYPE ? 454 ( VS_CHANGE || PMAX_EX ) 455 : BOOLEAN_TYPE ? 456 ( VB_CHANGE || PMAX_EX ) 457 : false ) 458 ); 459 } 461 Figure 1: Code logic for attribute interactions for observe 462 notification 464 5. Binding Table 466 The Binding table is a special resource that gives access to the 467 bindings on a endpoint. This section defines a REST interface for 468 Binding table resources. The Binding table resource MUST support the 469 Binding interface defined below. The interface supports the link- 470 format type. 472 The if= column defines the Interface Description (if=) attribute 473 value to be used in the CoRE Link Format for a resource conforming to 474 that interface. When this value appears in the if= attribute of a 475 link, the resource MUST support the corresponding REST interface 476 described in this section. The resource MAY support additional 477 functionality, which is out of scope for this specification. 478 Although this interface description is intended to be used with the 479 CoRE Link Format, it is applicable for use in any REST interface 480 definition. 482 The Methods column defines the REST methods supported by the 483 interface, which are described in more detail below. 485 +-----------+----------+-------------------+-----------------+ 486 | Interface | if= | Methods | Content-Formats | 487 +-----------+----------+-------------------+-----------------+ 488 | Binding | core.bnd | GET, POST, DELETE | link-format | 489 +-----------+----------+-------------------+-----------------+ 491 Table 4: Binding Interface Description 493 The Binding interface is used to manipulate a binding table. A 494 request with a POST method and a content format of application/link- 495 format simply appends new bindings to the table. All links in the 496 payload MUST have a relation type "boundto". A GET request simply 497 returns the current state of a binding table whereas a DELETE request 498 empties the table. Individual entries may be deleted from the table 499 by specifying the resource path in a DELETE request. 501 The following example shows requests for adding, retrieving and 502 deleting bindings in a binding table. 504 Req: POST /bnd/ (Content-Format: application/link-format) 505 ; 506 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 507 Res: 2.04 Changed 509 Req: GET /bnd/ 510 Res: 2.05 Content (application/link-format) 511 ; 512 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 514 Req: DELETE /bnd/a/light 515 Res: 2.04 Changed 517 Req: DELETE /bnd/ 518 Res: 2.04 Changed 520 Figure 2: Binding Interface Example 522 6. Implementation Considerations 524 When using multiple resource bindings (e.g. multiple Observations of 525 resource) with different bands, consideration should be given to the 526 resolution of the resource value when setting sequential bands. For 527 example: Given BandA (Abmn=10, Bbmx=20) and BandB (Bbmn=21, Bbmx=30). 528 If the resource value returns an integer then notifications for 529 values between and inclusive of 10 and 30 will be triggered. Whereas 530 if the resolution is to one decimal point (0.1) then notifications 531 for values 20.1 to 20.9 will not be triggered. 533 The use of the notification band minimum and maximum allow for a 534 synchronization whenever a change in the resource value occurs. 535 Theoretically this could occur in-line with the server internal 536 sample period for the determining the resource value. Implementors 537 SHOULD consider the resolution needed before updating the resource, 538 e.g. updating the resource when a temperature sensor value changes by 539 0.001 degree versus 1 degree. 541 The initiation of a link binding can be delegated from a client to a 542 link state machine implementation, which can be an embedded client or 543 a configuration tool. Implementation considerations have to be given 544 to how to monitor transactions made by the configuration tool with 545 regards to link bindings, as well as any errors that may arise with 546 establishing link bindings as well as with established link bindings. 548 7. Security Considerations 550 Consideration has to be given to what kinds of security credentials 551 the state machine of a configuration tool or an embedded client needs 552 to be configured with, and what kinds of access control lists client 553 implementations should possess, so that transactions on creating link 554 bindings and handling error conditions can be processed by the state 555 machine. 557 8. IANA Considerations 559 8.1. Interface Description 561 The specification registers the "binding" CoRE interface description 562 link target attribute value as per [RFC6690]. 564 Attribute Value: core.bnd 566 Description: The binding interface is used to manipulate a binding 567 table which describes the link bindings between source and 568 destination resources for the purposes of synchronizing their 569 content. 571 Reference: This specification. Note to RFC editor: please insert the 572 RFC of this specification. 574 Notes: None 576 8.2. Link Relation Type 578 This specification registers the new "boundto" link relation type as 579 per [RFC8288]. 581 Relation Name: boundto 583 Description: The purpose of a boundto relation type is to indicate 584 that there is a binding between a source resource and a 585 destination resource for the purposes of synchronizing their 586 content. 588 Reference: This specification. Note to RFC editor: please insert 589 the RFC of this specification. 591 Notes: None 593 Application Data: None 595 9. Acknowledgements 597 Acknowledgement is given to colleagues from the SENSEI project who 598 were critical in the initial development of the well-known REST 599 interface concept, to members of the IPSO Alliance where further 600 requirements for interface types have been discussed, and to Szymon 601 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 602 provided useful discussion and input to the concepts in this 603 specification. Christian Amsuss supplied a comprehensive review of 604 draft -06. 606 10. Contributors 608 Matthieu Vial 609 Schneider-Electric 610 Grenoble 611 France 613 Phone: +33 (0)47657 6522 614 EMail: matthieu.vial@schneider-electric.com 616 11. Changelog 618 draft-ietf-core-dynlink-07 620 o Added reference code to illustrate attribute interactions for 621 observations 623 draft-ietf-core-dynlink-06 624 o Document restructure and refactoring into three main sections 626 o Clarifications on band usage 628 o Implementation considerations introduced 630 o Additional text on security considerations 632 draft-ietf-core-dynlink-05 634 o Addition of a band modifier for gt and lt, adapted from draft- 635 groves-core-obsattr 637 o Removed statement prescribing gt MUST be greater than lt 639 draft-ietf-core-dynlink-03 641 o General: Reverted to using "gt" and "lt" from "gth" and "lth" for 642 this draft owing to concerns raised that the attributes are 643 already used in LwM2M with the original names "gt" and "lt". 645 o New author and editor added. 647 draft-ietf-core-dynlink-02 649 o General: Changed the name of the greater than attribute "gt" to 650 "gth" and the name of the less than attribute "lt" to "lth" due to 651 conlict with the core resource directory draft lifetime "lt" 652 attribute. 654 o Clause 6.1: Addressed the editor's note by changing the link 655 target attribute to "core.binding". 657 o Added Appendix A for examples. 659 draft-ietf-core-dynlink-01 661 o General: The term state synchronization has been introduced to 662 describe the process of synchronization between destination and 663 source resources. 665 o General: The document has been restructured the make the 666 information flow better. 668 o Clause 3.1: The descriptions of the binding attributes have been 669 updated to clarify their usage. 671 o Clause 3.1: A new clause has been added to discuss the 672 interactions between the resources. 674 o Clause 3.4: Has been simplified to refer to the descriptions in 675 3.1. As the text was largely duplicated. 677 o Clause 4.1: Added a clarification that individual resources may be 678 removed from the binding table. 680 o Clause 6: Formailised the IANA considerations. 682 draft-ietf-core-dynlink Initial Version 00: 684 o This is a copy of draft-groves-core-dynlink-00 686 draft-groves-core-dynlink Draft Initial Version 00: 688 o This initial version is based on the text regarding the dynamic 689 linking functionality in I.D.ietf-core-interfaces-05. 691 o The WADL description has been dropped in favour of a thorough 692 textual description of the REST API. 694 12. References 696 12.1. Normative References 698 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 699 Requirement Levels", BCP 14, RFC 2119, 700 DOI 10.17487/RFC2119, March 1997, 701 . 703 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 704 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 705 . 707 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 708 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 709 May 2017, . 711 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 712 DOI 10.17487/RFC8288, October 2017, 713 . 715 12.2. Informative References 717 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 718 Application Protocol (CoAP)", RFC 7252, 719 DOI 10.17487/RFC7252, June 2014, 720 . 722 [RFC7641] Hartke, K., "Observing Resources in the Constrained 723 Application Protocol (CoAP)", RFC 7641, 724 DOI 10.17487/RFC7641, September 2015, 725 . 727 Appendix A. Examples 729 This appendix provides some examples of the use of binding attribute 730 / observe attributes. 732 Note: For brevity the only the method or response code is shown in 733 the header field. 735 A.1. Greater Than (gt) example 736 Observed CLIENT SERVER Actual 737 t State | | State 738 ____________ | | ____________ 739 1 | | 740 2 unknown | | 18.5 Cel 741 3 +----->| Header: GET 742 4 | GET | Token: 0x4a 743 5 | | Uri-Path: temperature 744 6 | | Uri-Query: gt="25" 745 7 | | Observe: 0 (register) 746 8 | | 747 9 ____________ |<-----+ Header: 2.05 748 10 | 2.05 | Token: 0x4a 749 11 18.5 Cel | | Observe: 9 750 12 | | Payload: "18.5 Cel" 751 13 | | 752 14 | | 753 15 | | ____________ 754 16 ____________ |<-----+ Header: 2.05 755 17 | 2.05 | 26 Cel Token: 0x4a 756 18 26 Cel | | Observe: 16 757 29 | | Payload: "26 Cel" 758 20 | | 759 21 | | 761 Figure 3: Client Registers and Receives one Notification of the 762 Current State and One of a New State when it passes through the 763 greather than threshold of 25. 765 A.2. Greater Than (gt) and Period Max (pmax) example 767 Observed CLIENT SERVER Actual 768 t State | | State 769 ____________ | | ____________ 770 1 | | 771 2 unknown | | 18.5 Cel 772 3 +----->| Header: GET 773 4 | GET | Token: 0x4a 774 5 | | Uri-Path: temperature 775 6 | | Uri-Query: pmax="20";gt="25" 776 7 | | Observe: 0 (register) 777 8 | | 778 9 ____________ |<-----+ Header: 2.05 779 10 | 2.05 | Token: 0x4a 780 11 18.5 Cel | | Observe: 9 781 12 | | Payload: "18.5 Cel" 782 13 | | 783 14 | | 784 15 | | 785 16 | | 786 17 | | 787 18 | | 788 19 | | 789 20 | | 790 21 | | 791 22 | | 792 23 | | 793 24 | | 794 25 | | 795 26 | | 796 27 | | 797 28 | | 798 29 | | ____________ 799 30 ____________ |<-----+ Header: 2.05 800 31 | 2.05 | 23 Cel Token: 0x4a 801 32 23 Cel | | Observe: 30 802 33 | | Payload: "23 Cel" 803 34 | | 804 35 | | 805 36 | | ____________ 806 37 ____________ |<-----+ Header: 2.05 807 38 | 2.05 | 26 Cel Token: 0x4a 808 39 26 Cel | | Observe: 37 809 40 | | Payload: "26 Cel" 810 41 | | 811 42 | | 813 Figure 4: Client Registers and Receives one Notification of the 814 Current State, one when pmax time expires and one of a new State when 815 it passes through the greather than threshold of 25. 817 Authors' Addresses 819 Zach Shelby 820 ARM 821 Kidekuja 2 822 Vuokatti 88600 823 FINLAND 825 Phone: +358407796297 826 Email: zach.shelby@arm.com 827 Michael Koster 828 SmartThings 829 665 Clyde Avenue 830 Mountain View 94043 831 USA 833 Email: michael.koster@smartthings.com 835 Christian Groves 836 Australia 838 Email: cngroves.std@gmail.com 840 Jintao Zhu 841 Huawei 842 No.127 Jinye Road, Huawei Base, High-Tech Development District 843 Xi'an, Shaanxi Province 844 China 846 Email: jintao.zhu@huawei.com 848 Bilhanan Silverajan (editor) 849 Tampere University of Technology 850 Korkeakoulunkatu 10 851 Tampere FI-33720 852 Finland 854 Email: bilhanan.silverajan@tut.fi