idnits 2.17.1 draft-ietf-core-dynlink-05.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC7252], [RFC7641]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 18, 2018) is 2229 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). 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. Vial 5 Expires: September 19, 2018 Schneider-Electric 6 M. Koster 7 SmartThings 8 C. Groves 9 J. Zhu 10 Huawei 11 B. Silverajan, Ed. 12 Tampere University of Technology 13 March 18, 2018 15 Dynamic Resource Linking for Constrained RESTful Environments 16 draft-ietf-core-dynlink-05 18 Abstract 20 For CoAP [RFC7252] Dynamic linking of state updates between 21 resources, either on an endpoint or between endpoints, is defined 22 with the concept of Link Bindings. This specification defines 23 conditional observation attributes that work with Link Bindings or 24 with CoAP Observe [RFC7641]. 26 Editor's note: 28 o The git repository for the draft is found at https://github.com/ 29 core-wg/dynlink 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on September 19, 2018. 48 Copyright Notice 50 Copyright (c) 2018 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (https://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 67 3. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 4 68 3.1. Binding Methods . . . . . . . . . . . . . . . . . . . . . 4 69 3.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 5 70 3.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 5 71 3.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 5 72 3.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 6 73 3.3. Binding Attributes . . . . . . . . . . . . . . . . . . . 6 74 3.3.1. Bind Method (bind) . . . . . . . . . . . . . . . . . 6 75 3.3.2. Minimum Period (pmin) . . . . . . . . . . . . . . . . 6 76 3.3.3. Maximum Period (pmax) . . . . . . . . . . . . . . . . 7 77 3.3.4. Change Step (st) . . . . . . . . . . . . . . . . . . 7 78 3.3.5. Greater Than (gt) . . . . . . . . . . . . . . . . . . 7 79 3.3.6. Less Than (lt) . . . . . . . . . . . . . . . . . . . 8 80 3.3.7. Notification Band (band) . . . . . . . . . . . . . . 8 81 3.3.8. Attribute Interactions . . . . . . . . . . . . . . . 9 82 4. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 10 83 4.1. Binding Interface Description . . . . . . . . . . . . . . 10 84 4.2. Resource Observation Attributes . . . . . . . . . . . . . 11 85 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 86 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 87 6.1. Interface Description . . . . . . . . . . . . . . . . . . 13 88 6.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 13 89 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 90 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 14 91 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 92 9.1. Normative References . . . . . . . . . . . . . . . . . . 15 93 9.2. Informative References . . . . . . . . . . . . . . . . . 15 94 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 16 95 A.1. Greater Than (gt) example . . . . . . . . . . . . . . . . 16 96 A.2. Greater Than (gt) and Period Max (pmax) example . . . . . 16 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 99 1. Introduction 101 IETF Standards for machine to machine communication in constrained 102 environments describe a REST protocol and a set of related 103 information standards that may be used to represent machine data and 104 machine metadata in REST interfaces. CoRE Link-format is a standard 105 for doing Web Linking [RFC5988] in constrained environments. 107 This specification introduces the concept of a Link Binding, which 108 defines a new link relation type to create a dynamic link between 109 resources over which to exchange state updates. Specifically, a Link 110 Binding is a link for binding the state of 2 resources together such 111 that updates to one are sent over the link to the other. CoRE Link 112 Format representations are used to configure, inspect, and maintain 113 Link 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 specification are to be interpreted as described 122 in [RFC2119]. 124 This specification requires readers to be familiar with all the terms 125 and concepts that are discussed in [RFC5988] and [RFC6690]. This 126 specification makes use of the following additional terminology: 128 Link Binding: A unidirectional logical link between a source 129 resource and a destination resource, over which state information 130 is synchronized. 132 State Synchronization: Depending on the binding method (Polling, 133 Observe, Push) different REST methods may be used to synchronize 134 the resource values between a source and a destination. The 135 process of using a REST method to achieve this is defined as 136 "State Synchronization". The endpoint triggering the state 137 synchronization is the synchronization initiator. 139 Notification Band: A resource value range that results in state 140 sychronization. The value range may be bounded by a minimum and 141 maximum value or may be unbounded having either a minimum or 142 maximum value. 144 3. Link Bindings 146 In a M2M RESTful environment, endpoints may directly exchange the 147 content of their resources to operate the distributed system. For 148 example, a light switch may supply on-off control information that 149 may be sent directly to a light resource for on-off control. 150 Beforehand, a configuration phase is necessary to determine how the 151 resources of the different endpoints are related to each other. This 152 can be done either automatically using discovery mechanisms or by 153 means of human intervention and a so-called commissioning tool. In 154 this specification the abstract relationship between two resources is 155 called a link Binding. The configuration phase necessitates the 156 exchange of binding information so a format recognized by all CoRE 157 endpoints is essential. This specification defines a format based on 158 the CoRE Link-Format to represent binding information along with the 159 rules to define a binding method which is a specialized relationship 160 between two resources. The purpose of a binding is to synchronize 161 the content between a source resource and a destination resource. 162 The destination resource MAY be a group resource if the authority 163 component of the destination URI contains a group address (either a 164 multicast address or a name that resolves to a multicast address). 165 Since a binding is unidirectional, the binding entry defining a 166 relationship is present only on one endpoint. The binding entry may 167 be located either on the source or the destination endpoint depending 168 on the binding method. 170 3.1. Binding Methods 172 A binding method defines the rules to generate the web-transfer 173 exchanges that synchronize state between source and destination 174 resources. By using REST methods content is sent from the source 175 resource to the destination resource. 177 The following table gives a summary of the binding methods defined in 178 this specification. 180 +---------+------------+-------------+---------------+ 181 | Name | Identifier | Location | Method | 182 +---------+------------+-------------+---------------+ 183 | Polling | poll | Destination | GET | 184 | | | | | 185 | Observe | obs | Destination | GET + Observe | 186 | | | | | 187 | Push | push | Source | PUT | 188 +---------+------------+-------------+---------------+ 190 Table 1: Binding Method Summary 192 The description of a binding method must define the following 193 aspects: 195 Identifier: This is the value of the "bind" attribute used to 196 identify the method. 198 Location: This information indicates whether the binding entry is 199 stored on the source or on the destination endpoint. 201 REST Method: This is the REST method used in the Request/Response 202 exchanges. 204 Conditions: A binding method definition must state how the condition 205 attributes of the abstract binding definition are actually used in 206 this specialized binding. 208 The binding methods are described in more detail below. 210 3.1.1. Polling 212 The Polling method consists of sending periodic GET requests from the 213 destination endpoint to the source resource and copying the content 214 to the destination resource. The binding entry for this method MUST 215 be stored on the destination endpoint. The destination endpoint MUST 216 ensure that the polling frequency does not exceed the limits defined 217 by the pmin and pmax attributes of the binding entry. The copying 218 process MAY filter out content from the GET requests using value- 219 based conditions (e.g based on the Change Step, Less Than, Greater 220 Than attributes). 222 3.1.2. Observe 224 The Observe method creates an observation relationship between the 225 destination endpoint and the source resource. On each notification 226 the content from the source resource is copied to the destination 227 resource. The creation of the observation relationship requires the 228 CoAP Observation mechanism [RFC7641] hence this method is only 229 permitted when the resources are made available over CoAP. The 230 binding entry for this method MUST be stored on the destination 231 endpoint. The binding conditions are mapped as query string 232 parameters (see Section 4.2). 234 3.1.3. Push 236 When the Push method is assigned to a binding, the source endpoint 237 sends PUT requests to the destination resource when the binding 238 condition attributes are satisfied for the source resource. The 239 source endpoint MUST only send a notification request if the binding 240 conditions are met. The binding entry for this method MUST be stored 241 on the source endpoint. 243 3.2. Link Relation 245 Since Binding involves the creation of a link between two resources, 246 Web Linking and the CoRE Link-Format are a natural way to represent 247 binding information. This involves the creation of a new relation 248 type, named "boundto". In a Web link with this relation type, the 249 target URI contains the location of the source resource and the 250 context URI points to the destination resource. 252 3.3. Binding Attributes 254 Web link attributes allow a fine-grained control of the type of state 255 synchronization along with the conditions that trigger an update. 256 This specification defines the attributes below: 258 +--------------------+-----------+------------------+ 259 | Attribute | Parameter | Value | 260 +--------------------+-----------+------------------+ 261 | Binding method | bind | xsd:string | 262 | | | | 263 | Minimum Period (s) | pmin | xsd:integer (>0) | 264 | | | | 265 | Maximum Period (s) | pmax | xsd:integer (>0) | 266 | | | | 267 | Change Step | st | xsd:decimal (>0) | 268 | | | | 269 | Greater Than | gt | xsd:decimal | 270 | | | | 271 | Less Than | lt | xsd:decimal | 272 | | | | 273 | Notification Band | band | xsd:boolean | 274 +--------------------+-----------+------------------+ 276 Table 2: Binding Attributes Summary 278 3.3.1. Bind Method (bind) 280 This is the identifier of a binding method which defines the rules to 281 synchronize the destination resource. This attribute is mandatory. 283 3.3.2. Minimum Period (pmin) 285 When present, the minimum period indicates the minimum time to wait 286 (in seconds) before triggering a new state synchronization (even if 287 it has changed). In the absence of this parameter, the minimum 288 period is up to the synchronization initiator. The minimum period 289 MUST be greater than zero otherwise the receiver MUST return a CoAP 290 error code 4.00 "Bad Request" (or equivalent). 292 3.3.3. Maximum Period (pmax) 294 When present, the maximum period indicates the maximum time in 295 seconds between two consecutive state synchronizations (regardless if 296 it has changed). In the absence of this parameter, the maximum 297 period is up to the synchronization initiator. The maximum period 298 MUST be greater than zero and MUST be greater than the minimum period 299 parameter (if present) otherwise the receiver MUST return a CoAP 300 error code 4.00 "Bad Request" (or equivalent). 302 3.3.4. Change Step (st) 304 When present, the change step indicates how much the value of a 305 resource SHOULD change before triggering a new state synchronization 306 (compared to the value of the previous synchronization). Upon 307 reception of a query including the st attribute the current value 308 (CurrVal) of the resource is set as the initial value (STinit). Once 309 the resource value differs from the STinit value (i.e. CurrVal >= 310 STinit + ST or CurrVal <= STint - ST) then a new state 311 synchronization occurs. STinit is then set to the state 312 synchronization value and new state synchronizations are based on a 313 change step against this value. The change step MUST be greater than 314 zero otherwise the receiver MUST return a CoAP error code 4.00 "Bad 315 Request" (or equivalent). 317 Note: Due to the state synchronization based update of STint it may 318 result in that resource value received in two sequential state 319 synchronizations differs by more than st. 321 3.3.5. Greater Than (gt) 323 When present, Greater Than indicates the upper limit value the 324 resource value SHOULD cross before triggering a new state 325 synchronization. State synchronization only occurs when the resource 326 value exceeds the specified upper limit value. The actual resource 327 value is used for the synchronization rather than the gt value. If 328 the value continues to rise, no new state synchronizations are 329 generated as a result of gt. If the value drops below the upper 330 limit value and then exceeds the upper limit then a new state 331 synchronization is generated. 333 3.3.6. Less Than (lt) 335 When present, Less Than indicates the lower limit value the resource 336 value SHOULD cross before triggering a new state synchronization. 337 State synchronization only occurs when the resource value is less 338 than the specified lower limit value. The actual resource value is 339 used for the synchronization rather than the lt value. If the value 340 continues to fall no new state synchronizations are generated as a 341 result of lt. If the value rises above the lower limit value and 342 then drops below the lower limit then a new state synchronization is 343 generated. 345 3.3.7. Notification Band (band) 347 The notification band attribute allows a bounded or unbounded (based 348 on a minimum or maximum) value range that may trigger multiple state 349 synchronizations. This enables use cases where different ranges 350 results in differing behaviour. For example: monitoring the 351 temperature of machinery. Whilst the temperature is in the normal 352 operating range only periodic observations are needed. However as 353 the temperature moves to more abnormal ranges more frequent 354 synchronization/reporting may be needed. 356 Without a notification band, a transition across a less than (lt), or 357 greater than (gt) limit only generates one notification. This means 358 that it is not possible to describe a case where multiple 359 notifications are sent so long as the limit is exceeded. 361 The band attribute works as a modifier to the behaviour of gt and lt. 362 Therefore, if band is present in a query, gt, lt or both, MUST be 363 included. 365 When band is present with the lt attribute, it defines the lower 366 bound for the notification band (notification band minimum). State 367 synchronization occurs when the resource value is equal to or above 368 the notification band minimum. If lt is not present there is no 369 minimum value for the band. 371 When band is present with the gt attribute, it defines the upper 372 bound for the notification band (notification band maximum). State 373 synchronization occurs when the resource value is equal to or below 374 the notification band maximum. If gt is not present there is no 375 maximum value for the band. 377 3.3.8. Attribute Interactions 379 Pmin, pmax, st, gt and lt may be present in the same query. 381 If pmin and pmax are present in a query then they take precedence 382 over the other parameters. Thus even if st, gt or lt are met, if 383 pmin has not been exceeded then no state synchronization occurs. 384 Likewise if st, gt or lt have not been met and pmax time has expired 385 then state synchronization occurs. The current value of the resource 386 is used for the synchronization. If pmin time is exceeded and st, gt 387 or lt are met then the current value of the resource is synchronized. 388 If st is also included, a state synchronization resulting from pmin 389 or pmax updates STinit with the synchronized value. 391 If gt and lt are included gt MUST be greater than lt otherwise an 392 error CoAP error code 4.00 "Bad Request" (or equivalent) MUST be 393 returned. 395 If st is included in a query with a gt or lt attribute then state 396 synchronizations occur only when the conditions described by st AND 397 gt or st AND lt are met. 399 To enable an notification band at least the notification band minimum 400 or maximum MUST be set. If both the notification band minimum and 401 maximum are set then a finite band is specified. State 402 synchronization occurs whenever the resource value is between the 403 notification band minimum and maximum or is equal to the notification 404 band minimum or maximum. If only the notification band minimum or 405 maximum is set then the band has an open bound. That is all values 406 above the notification band minimum or all values below the 407 notification band maximum will be synchronized. 409 When using multiple resource bindings (e.g. multiple Observations of 410 resource) with different bands, consideration should be given to the 411 resolution of the resource value when setting sequential bands. For 412 example: Given BandA (Abmn=10, Bbmx=20) and BandB (Bbmn=21, Bbmx=30). 413 If the resource value returns an integer then notifications for 414 values between and inclusive of 10 and 30 will be triggered. Whereas 415 if the resolution is to one decimal point (0.1) then notifications 416 for values 20.1 to 20.9 will not be triggered. 418 Note: The use of the notification band minimum and maximum allow for 419 a synchronization whenever a change in the resource value occurs. 420 Theoretically this could occur in-line with the server internal 421 sample period for the determining the resource value. Implementors 422 SHOULD consider the resolution needed before updating the resource, 423 e.g. updating the resource when a temperature sensor value changes by 424 0.001 degree versus 1 degree. 426 If pmin and pmax are present in a query then they take precedence 427 over the other parameters. Thus even if the notification band 428 minimum and maximum are met if pmin has not been exceeded then no 429 state synchronization occurs. Likewise if the notification band 430 minimum and maximum have not been met and pmax time has expired then 431 state synchronization occurs. The current value of the resource is 432 used for the synchronization. If pmin time is exceeded and the 433 notification band minimum and maximum are met then the current value 434 of the resource is synchronized. If st is also included, a state 435 synchronization resulting from pmin or pmax updates STinit with the 436 synchronized value. If change step (st) is included in a query with 437 the notification band minimum or maximum then state synchronization 438 will occur whilst the resource value is in the notification band AND 439 the resource value differs from STinit by the change step. 441 4. Binding Table 443 The binding table is a special resource that gives access to the 444 bindings on a endpoint. A binding table resource MUST support the 445 Binding interface defined below. A profile SHOULD allow only one 446 resource table per endpoint. 448 4.1. Binding Interface Description 450 This section defines a REST interface for Binding table resources. 451 The interface supports the link-format type. 453 The if= column defines the Interface Description (if=) attribute 454 value to be used in the CoRE Link Format for a resource conforming to 455 that interface. When this value appears in the if= attribute of a 456 link, the resource MUST support the corresponding REST interface 457 described in this section. The resource MAY support additional 458 functionality, which is out of scope for this specification. 459 Although this interface description is intended to be used with the 460 CoRE Link Format, it is applicable for use in any REST interface 461 definition. 463 The Methods column defines the REST methods supported by the 464 interface, which are described in more detail below. 466 +-----------+----------+-------------------+-----------------+ 467 | Interface | if= | Methods | Content-Formats | 468 +-----------+----------+-------------------+-----------------+ 469 | Binding | core.bnd | GET, POST, DELETE | link-format | 470 +-----------+----------+-------------------+-----------------+ 472 Table 3: Binding Interface Description 474 The Binding interface is used to manipulate a binding table. A 475 request with a POST method and a content format of application/link- 476 format simply appends new bindings to the table. All links in the 477 payload MUST have a relation type "boundTo". A GET request simply 478 returns the current state of a binding table whereas a DELETE request 479 empties the table. Individual entries may be deleted from the table 480 by specifying the resource path in a DELETE request. 482 The following example shows requests for adding, retrieving and 483 deleting bindings in a binding table. 485 Req: POST /bnd/ (Content-Format: application/link-format) 486 ; 487 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 488 Res: 2.04 Changed 490 Req: GET /bnd/ 491 Res: 2.05 Content (application/link-format) 492 ; 493 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 495 Req: DELETE /bnd/a/light 496 Res: 2.04 Changed 498 Req: DELETE /bnd/ 499 Res: 2.04 Changed 501 Figure 1: Binding Interface Example 503 4.2. Resource Observation Attributes 505 When resource interfaces following this specification are made 506 available over CoAP, the CoAP Observation mechanism [RFC7641] MAY be 507 used to observe any changes in a resource, and receive asynchronous 508 notifications as a result. In addition, a set of query string 509 parameters are defined here to allow a client to control how often a 510 client is interested in receiving notifications and how much a 511 resource value should change for the new representation to be 512 interesting. These query parameters are described in the following 513 table. A resource using an interface description defined in this 514 specification and marked as Observable in its link description SHOULD 515 support these observation parameters. The Change Step parameter can 516 only be supported on resources with an atomic numeric value. 518 These query parameters MUST be treated as resources that are read 519 using GET and updated using PUT, and MUST NOT be included in the 520 Observe request. Multiple parameters MAY be updated at the same time 521 by including the values in the query string of a PUT. Before being 522 updated, these parameters have no default value. 524 +-------------------+------------------+------------------+ 525 | Attribute Name | Parameter | Data Format | 526 +-------------------+------------------+------------------+ 527 | Minimum Period | /{resource}?pmin | xsd:integer (>0) | 528 | | | | 529 | Maximum Period | /{resource}?pmax | xsd:integer (>0) | 530 | | | | 531 | Change Step | /{resource}?st | xsd:decimal (>0) | 532 | | | | 533 | Less Than | /{resource}?lt | xsd:decimal | 534 | | | | 535 | Greater Than | /{resource}?gt | xsd:decimal | 536 | | | | 537 | Notification Band | /{resource}?band | xsd:boolean | 538 +-------------------+------------------+------------------+ 540 Table 4: Resource Observation Attribute Summary 542 Minimum Period: As per Section 3.3.2 544 Maximum Period: As per Section 3.3.3 546 Change Step: As per Section 3.3.4 548 Greater Than: As per Section 3.3.5 550 Less Than: As per Section 3.3.6 552 Notification Band: As per Section 3.3.7 554 5. Security Considerations 556 An implementation of a client needs to be prepared to deal with 557 responses to a request that differ from what is specified in this 558 specification. A server implementing what the client thinks is a 559 resource with one of these interface descriptions could return 560 malformed representations and response codes either by accident or 561 maliciously. A server sending maliciously malformed responses could 562 attempt to take advantage of a poorly implemented client for example 563 to crash the node or perform denial of service. 565 6. IANA Considerations 567 6.1. Interface Description 569 The specification registers the "binding" CoRE interface description 570 link target attribute value as per [RFC6690]. 572 Attribute Value: core.binding 574 Description: The binding interface is used to manipulate a binding 575 table which describes the link bindings between source and 576 destination resources for the purposes of synchronizing their 577 content. 579 Reference: This specification. Note to RFC editor: please insert the 580 RFC of this specification. 582 Notes: None 584 6.2. Link Relation Type 586 This specification registers the new "boundto" link relation type as 587 per [RFC5988]. 589 Relation Name: boundto 591 Description: The purpose of a boundto relation type is to indicate 592 that there is a binding between a source resource and a 593 destination resource for the purposes of synchronizing their 594 content. 596 Reference: This specification. Note to RFC editor: please insert 597 the RFC of this specification. 599 Notes: None 601 Application Data: None 603 7. Acknowledgements 605 Acknowledgement is given to colleagues from the SENSEI project who 606 were critical in the initial development of the well-known REST 607 interface concept, to members of the IPSO Alliance where further 608 requirements for interface types have been discussed, and to Szymon 609 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 610 provided useful discussion and input to the concepts in this 611 specification. 613 8. Changelog 615 draft-ietf-core-dynlink-05 617 o Addition of a band modifier for gt and lt, adapted from draft- 618 groves-core-obsattr 620 o Removed statement prescribing gt MUST be greater than lt 622 draft-ietf-core-dynlink-03 624 o General: Reverted to using "gt" and "lt" from "gth" and "lth" for 625 this draft owing to concerns raised that the attributes are 626 already used in LwM2M with the original names "gt" and "lt". 628 o New author and editor added. 630 draft-ietf-core-dynlink-02 632 o General: Changed the name of the greater than attribute "gt" to 633 "gth" and the name of the less than attribute "lt" to "lth" due to 634 conlict with the core resource directory draft lifetime "lt" 635 attribute. 637 o Clause 6.1: Addressed the editor's note by changing the link 638 target attribute to "core.binding". 640 o Added Appendix A for examples. 642 draft-ietf-core-dynlink-01 644 o General: The term state synchronization has been introduced to 645 describe the process of synchronization between destination and 646 source resources. 648 o General: The document has been restructured the make the 649 information flow better. 651 o Clause 3.1: The descriptions of the binding attributes have been 652 updated to clarify their usage. 654 o Clause 3.1: A new clause has been added to discuss the 655 interactions between the resources. 657 o Clause 3.4: Has been simplified to refer to the descriptions in 658 3.1. As the text was largely duplicated. 660 o Clause 4.1: Added a clarification that individual resources may be 661 removed from the binding table. 663 o Clause 6: Formailised the IANA considerations. 665 draft-ietf-core-dynlink Initial Version 00: 667 o This is a copy of draft-groves-core-dynlink-00 669 draft-groves-core-dynlink Draft Initial Version 00: 671 o This initial version is based on the text regarding the dynamic 672 linking functionality in I.D.ietf-core-interfaces-05. 674 o The WADL description has been dropped in favour of a thorough 675 textual description of the REST API. 677 9. References 679 9.1. Normative References 681 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 682 Requirement Levels", BCP 14, RFC 2119, 683 DOI 10.17487/RFC2119, March 1997, 684 . 686 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 687 DOI 10.17487/RFC5988, October 2010, 688 . 690 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 691 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 692 . 694 9.2. Informative References 696 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 697 Application Protocol (CoAP)", RFC 7252, 698 DOI 10.17487/RFC7252, June 2014, 699 . 701 [RFC7641] Hartke, K., "Observing Resources in the Constrained 702 Application Protocol (CoAP)", RFC 7641, 703 DOI 10.17487/RFC7641, September 2015, 704 . 706 Appendix A. Examples 708 This appendix provides some examples of the use of binding attribute 709 / observe attributes. 711 Note: For brevity the only the method or response code is shown in 712 the header field. 714 A.1. Greater Than (gt) example 716 Observed CLIENT SERVER Actual 717 t State | | State 718 ____________ | | ____________ 719 1 | | 720 2 unknown | | 18.5 Cel 721 3 +----->| Header: GET 722 4 | GET | Token: 0x4a 723 5 | | Uri-Path: temperature 724 6 | | Uri-Query: gt="25" 725 7 | | Observe: 0 (register) 726 8 | | 727 9 ____________ |<-----+ Header: 2.05 728 10 | 2.05 | Token: 0x4a 729 11 18.5 Cel | | Observe: 9 730 12 | | Payload: "18.5 Cel" 731 13 | | 732 14 | | 733 15 | | ____________ 734 16 ____________ |<-----+ Header: 2.05 735 17 | 2.05 | 26 Cel Token: 0x4a 736 18 26 Cel | | Observe: 16 737 29 | | Payload: "26 Cel" 738 20 | | 739 21 | | 741 Figure 2: Client Registers and Receives one Notification of the 742 Current State and One of a New State when it passes through the 743 greather than threshold of 25. 745 A.2. Greater Than (gt) and Period Max (pmax) example 747 Observed CLIENT SERVER Actual 748 t State | | State 749 ____________ | | ____________ 750 1 | | 751 2 unknown | | 18.5 Cel 752 3 +----->| Header: GET 753 4 | GET | Token: 0x4a 754 5 | | Uri-Path: temperature 755 6 | | Uri-Query: pmax="20";gt="25" 756 7 | | Observe: 0 (register) 757 8 | | 758 9 ____________ |<-----+ Header: 2.05 759 10 | 2.05 | Token: 0x4a 760 11 18.5 Cel | | Observe: 9 761 12 | | Payload: "18.5 Cel" 762 13 | | 763 14 | | 764 15 | | 765 16 | | 766 17 | | 767 18 | | 768 19 | | 769 20 | | 770 21 | | 771 22 | | 772 23 | | 773 24 | | 774 25 | | 775 26 | | 776 27 | | 777 28 | | 778 29 | | ____________ 779 30 ____________ |<-----+ Header: 2.05 780 31 | 2.05 | 23 Cel Token: 0x4a 781 32 23 Cel | | Observe: 30 782 33 | | Payload: "23 Cel" 783 34 | | 784 35 | | 785 36 | | ____________ 786 37 ____________ |<-----+ Header: 2.05 787 38 | 2.05 | 26 Cel Token: 0x4a 788 39 26 Cel | | Observe: 37 789 40 | | Payload: "26 Cel" 790 41 | | 791 42 | | 793 Figure 3: Client Registers and Receives one Notification of the 794 Current State, one when pmax time expires and one of a new State when 795 it passes through the greather than threshold of 25. 797 Authors' Addresses 798 Zach Shelby 799 ARM 800 150 Rose Orchard 801 San Jose 95134 802 FINLAND 804 Phone: +1-408-203-9434 805 Email: zach.shelby@arm.com 807 Matthieu Vial 808 Schneider-Electric 809 Grenoble 810 FRANCE 812 Phone: +33 (0)47657 6522 813 Email: matthieu.vial@schneider-electric.com 815 Michael Koster 816 SmartThings 817 665 Clyde Avenue 818 Mountain View 94043 819 USA 821 Email: michael.koster@smartthings.com 823 Christian Groves 824 Huawei 825 Australia 827 Email: cngroves.std@gmail.com 829 Jintao Zhu 830 Huawei 831 No.127 Jinye Road, Huawei Base, High-Tech Development District 832 Xi'an, Shaanxi Province 833 China 835 Email: jintao.zhu@huawei.com 836 Bilhanan Silverajan (editor) 837 Tampere University of Technology 838 Korkeakoulunkatu 10 839 Tampere FI-33720 840 Finland 842 Email: bilhanan.silverajan@tut.fi