idnits 2.17.1 draft-ietf-core-dynlink-00.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 date (October 19, 2016) is 2743 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 (~~), 1 warning (==), 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 Z. Vial 5 Expires: April 22, 2017 Schneider-Electric 6 M. Koster 7 SmartThings 8 C. Groves 9 Huawei 10 October 19, 2016 12 Dynamic Resource Linking for Constrained RESTful Environments 13 draft-ietf-core-dynlink-00 15 Abstract 17 For CoAP [RFC7252] Dynamic linking of state updates between 18 resources, either on an endpoint or between endpoints, is defined 19 with the concept of Link Bindings. This document defines conditional 20 observation attributes that work with Link Bindings or with simple 21 CoAP Observe [RFC7641]. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on April 22, 2017. 40 Copyright Notice 42 Copyright (c) 2016 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 3. Link Bindings and Observe Attributes . . . . . . . . . . . . 3 60 3.1. Format . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3.2. Binding Methods . . . . . . . . . . . . . . . . . . . . . 5 62 3.3. Binding Table . . . . . . . . . . . . . . . . . . . . . . 6 63 3.4. Resource Observation Attributes . . . . . . . . . . . . . 6 64 4. Interface Descriptions . . . . . . . . . . . . . . . . . . . 8 65 4.1. Binding . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 67 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 68 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 69 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 72 9.2. Informative References . . . . . . . . . . . . . . . . . 10 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 75 1. Introduction 77 IETF Standards for machine to machine communication in constrained 78 environments describe a REST protocol and a set of related 79 information standards that may be used to represent machine data and 80 machine metadata in REST interfaces. CoRE Link-format is a standard 81 for doing Web Linking [RFC5988] in constrained environments. 83 This document introduces the concept of a Link Binding, which defines 84 a new link relation type to create a dynamic link between resources 85 over which to exchange state updates. Specifically, a Link Binding 86 is a link for binding the state of 2 resources together such that 87 updates to one are sent over the link to the other. CoRE Link Format 88 representations are used to configure, inspect, and maintain Link 89 Bindings. This document additionally defines a set of conditional 90 Observe Attributes for use with Link Bindings and with the standalone 91 CoRE Observe [RFC7641] method. 93 Editor's note: This initial version is based on the text of I.D.ietf- 94 core-interfaces-04. Further work is needed around link bindings and 95 extending the obeserve attributes with another use case that requires 96 3 new optional attributes. 98 2. Terminology 100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 102 "OPTIONAL" in this document are to be interpreted as described in 103 [RFC2119]. 105 This specification requires readers to be familiar with all the terms 106 and concepts that are discussed in [RFC5988] and [RFC6690]. This 107 specification makes use of the following additional terminology: 109 Link Binding: A unidirectional logical link between a source 110 resource and a destination resource, over which state information 111 is synchronized. 113 3. Link Bindings and Observe Attributes 115 In a M2M RESTful environment, endpoints may directly exchange the 116 content of their resources to operate the distributed system. For 117 example, a light switch may supply on-off control information that 118 may be sent directly to a light resource for on-off control. 119 Beforehand, a configuration phase is necessary to determine how the 120 resources of the different endpoints are related to each other. This 121 can be done either automatically using discovery mechanisms or by 122 means of human intervention and a so-called commissioning tool. In 123 this document the abstract relationship between two resources is 124 called a link Binding. The configuration phase necessitates the 125 exchange of binding information so a format recognized by all CoRE 126 endpoints is essential. This document defines a format based on the 127 CoRE Link-Format to represent binding information along with the 128 rules to define a binding method which is a specialized relationship 129 between two resources. The purpose of a binding is to synchronize 130 the content between a source resource and a destination resource. 131 The destination resource MAY be a group resource if the authority 132 component of the destination URI contains a group address (either a 133 multicast address or a name that resolves to a multicast address). 134 Since a binding is unidirectional, the binding entry defining a 135 relationship is present only on one endpoint. The binding entry may 136 be located either on the source or the destination endpoint depending 137 on the binding method. The following table gives a summary of the 138 binding methods described in more detail in Section 3.2 139 +---------+------------+-------------+---------------+ 140 | Name | Identifier | Location | Method | 141 +---------+------------+-------------+---------------+ 142 | Polling | poll | Destination | GET | 143 | | | | | 144 | Observe | obs | Destination | GET + Observe | 145 | | | | | 146 | Push | push | Source | PUT | 147 +---------+------------+-------------+---------------+ 149 Table 1: Binding Method Summary 151 3.1. Format 153 Since Binding involves the creation of a link between two resources, 154 Web Linking and the CoRE Link-Format are a natural way to represent 155 binding information. This involves the creation of a new relation 156 type, purposely named "boundto". In a Web link with this relation 157 type, the target URI contains the location of the source resource and 158 the context URI points to the destination resource. The Web link 159 attributes allow a fine-grained control of the type of 160 synchronization exchange along with the conditions that trigger an 161 update. This specification defines the attributes below: 163 +--------------------+-----------+------------------+ 164 | Attribute | Parameter | Value | 165 +--------------------+-----------+------------------+ 166 | Binding method | bind | xsd:string | 167 | | | | 168 | Minimum Period (s) | pmin | xsd:integer (>0) | 169 | | | | 170 | Maximum Period (s) | pmax | xsd:integer (>0) | 171 | | | | 172 | Change Step | st | xsd:decimal (>0) | 173 | | | | 174 | Greater Than | gt | xsd:decimal | 175 | | | | 176 | Less Than | lt | xsd:decimal | 177 +--------------------+-----------+------------------+ 179 Table 2: Binding Attributes Summary 181 Bind Method: This is the identifier of a binding method which 182 defines the rules to synchronize the destination resource. This 183 attribute is mandatory. 185 Minimum Period: When present, the minimum period indicates the 186 minimum time to wait (in seconds) before sending a new 187 synchronization message (even if it has changed). In the absence 188 of this parameter, the minimum period is up to the notifier. 190 Maximum Period: When present, the maximum period indicates the 191 maximum time in seconds between two consecutive state 192 synchronization messages (regardless if it has changed). In the 193 absence of this parameter, the maximum period is up to the 194 notifier. The maximum period MUST be greater than the minimum 195 period parameter (if present). 197 Change Step: When present, the change step indicates how much the 198 value of a resource SHOULD change before sending a new 199 notification (compared to the value of the last notification). 200 This parameter has lower priority than the period parameters, thus 201 even if the change step has been fulfilled, the time since the 202 last notification SHOULD be between pmin and pmax. 204 Greater Than: When present, Greater Than indicates the upper limit 205 value the resource value SHOULD cross before sending a new 206 notification. This parameter has lower priority than the period 207 parameters, thus even if the Greater Than limit has been crossed, 208 the time since the last notification SHOULD be between pmin and 209 pmax. 211 Less Than: When present, Less Than indicates the lower limit value 212 the resource value SHOULD cross before sending a new notification. 213 This parameter has lower priority than the period parameters, thus 214 even if the Less Than limit has been crossed, the time since the 215 last notification SHOULD be between pmin and pmax. 217 3.2. Binding Methods 219 A binding method defines the rules to generate the web-transfer 220 exchanges that will effectively send content from the source resource 221 to the destination resource. The description of a binding method 222 must define the following aspects: 224 Identifier: This is value of the "bind" attribute used to identify 225 the method. 227 Location: This information indicates whether the binding entry is 228 stored on the source or on the destination endpoint. 230 REST Method: This is the REST method used in the Request/Response 231 exchanges. 233 Conditions: A binding method definition must state how the condition 234 attributes of the abstract binding definition are actually used in 235 this specialized binding. 237 This specification supports 3 binding methods described below: 239 Polling: The Polling method consists of sending periodic GET 240 requests from the destination endpoint to the source resource and 241 copying the content to the destination resource. The binding 242 entry for this method MUST be stored on the destination endpoint. 243 The destination endpoint MUST ensure that the polling frequency 244 does not exceed the limits defined by the pmin and pmax attributes 245 of the binding entry. The copying process MAY filter out content 246 from the GET requests using value-based conditions (e.g Change 247 Step, Less Than, Greater Than). 249 Observe: The Observe method creates an observation relationship 250 between the destination endpoint and the source resource. On each 251 notification the content from the source resource is copied to the 252 destination resource. The creation of the observation 253 relationship requires the CoAP Observation mechanism [RFC7641] 254 hence this method is only permitted when the resources are made 255 available over CoAP. The binding entry for this method MUST be 256 stored on the destination endpoint. The binding conditions are 257 mapped as query string parameters (see Section 3.4). 259 Push: When the Push method is assigned to a binding, the source 260 endpoint sends PUT requests to the destination resource when the 261 binding condition attributes are satisfied for the source 262 resource. The source endpoint MUST only send a notification 263 request if the binding conditions are met. The binding entry for 264 this method MUST be stored on the source endpoint. 266 3.3. Binding Table 268 The binding table is a special resource that gives access to the 269 bindings on a endpoint. A binding table resource MUST support the 270 Binding interface defined in Section 4.1. A profile SHOULD allow 271 only one resource table per endpoint. 273 3.4. Resource Observation Attributes 275 When resource interfaces following this specification are made 276 available over CoAP, the CoAP Observation mechanism [RFC7641] MAY be 277 used to observe any changes in a resource, and receive asynchronous 278 notifications as a result. In addition, a set of query string 279 parameters are defined here to allow a client to control how often a 280 client is interested in receiving notifications and how much a 281 resource value should change for the new representation to be 282 interesting. These query parameters are described in the following 283 table. A resource using an interface description defined in this 284 specification and marked as Observable in its link description SHOULD 285 support these observation parameters. The Change Step parameter can 286 only be supported on resources with an atomic numeric value. 288 These query parameters MUST be treated as resources that are read 289 using GET and updated using PUT, and MUST NOT be included in the 290 Observe request. Multiple parameters MAY be updated at the same time 291 by including the values in the query string of a PUT. Before being 292 updated, these parameters have no default value. 294 +----------------+------------------+------------------+ 295 | Resource | Parameter | Data Format | 296 +----------------+------------------+------------------+ 297 | Minimum Period | /{resource}?pmin | xsd:integer (>0) | 298 | | | | 299 | Maximum Period | /{resource}?pmax | xsd:integer (>0) | 300 | | | | 301 | Change Step | /{resource}?st | xsd:decimal (>0) | 302 | | | | 303 | Less Than | /{resource}?lt | xsd:decimal | 304 | | | | 305 | Greater Than | /{resource}?gt | xsd:decimal | 306 +----------------+------------------+------------------+ 308 Table 3: Resource Observation Attribute Summary 310 Minimum Period: When present, the minimum period indicates the 311 minimum time to wait (in seconds) before sending a new 312 synchronization message (even if it has changed). In the absence 313 of this parameter, the minimum period is up to the notifier. 315 Maximum Period: When present, the maximum period indicates the 316 maximum time in seconds between two consecutive state 317 synchronization messages (regardless if it has changed). In the 318 absence of this parameter, the maximum period is up to the 319 notifier. The maximum period MUST be greater than the minimum 320 period parameter (if present). 322 Change Step: When present, the change step indicates how much the 323 value of a resource SHOULD change before sending a new 324 notification (compared to the value of the last notification). 325 This parameter has lower priority than the period parameters, thus 326 even if the change step has been fulfilled, the time since the 327 last notification SHOULD be between pmin and pmax. 329 Greater Than: When present, Greater Than indicates the upper limit 330 value the resource value SHOULD cross before sending a new 331 notification. This parameter has lower priority than the period 332 parameters, thus even if the Greater Than limit has been crossed, 333 the time since the last notification SHOULD be between pmin and 334 pmax. 336 Less Than: When present, Less Than indicates the lower limit value 337 the resource value SHOULD cross before sending a new notification. 338 This parameter has lower priority than the period parameters, thus 339 even if the Less Than limit has been crossed, the time since the 340 last notification SHOULD be between pmin and pmax. 342 4. Interface Descriptions 344 This section defines REST interfaces for Binding table resources. 345 The interface supports the link-format type. 347 The if= column defines the Interface Description (if=) attribute 348 value to be used in the CoRE Link Format for a resource conforming to 349 that interface. When this value appears in the if= attribute of a 350 link, the resource MUST support the corresponding REST interface 351 described in this section. The resource MAY support additional 352 functionality, which is out of scope for this specification. 353 Although this interface descriptions is intended to be used with the 354 CoRE Link Format, it is applicable for use in any REST interface 355 definition. 357 The Methods column defines the methods supported by that interface, 358 which are described in more detail below. 360 +-----------+----------+-------------------+-----------------+ 361 | Interface | if= | Methods | Content-Formats | 362 +-----------+----------+-------------------+-----------------+ 363 | Binding | core.bnd | GET, POST, DELETE | link-format | 364 +-----------+----------+-------------------+-----------------+ 366 Table 4: Inteface Description 368 4.1. Binding 370 The Binding interface is used to manipulate a binding table. A 371 request with a POST method and a content format of application/link- 372 format simply appends new bindings to the table. All links in the 373 payload MUST have a relation type "boundTo". A GET request simply 374 returns the current state of a binding table whereas a DELETE request 375 empties the table. 377 The following example shows requests for adding, retrieving and 378 deleting bindings in a binding table. 380 Req: POST /bnd/ (Content-Format: application/link-format) 381 ; 382 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 383 Res: 2.04 Changed 385 Req: GET /bnd/ 386 Res: 2.05 Content (application/link-format) 387 ; 388 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 390 Req: DELETE /bnd/ 391 Res: 2.04 Changed 393 Figure 1: Binding Interface Example 395 5. Security Considerations 397 An implementation of a client needs to be prepared to deal with 398 responses to a request that differ from what is specified in this 399 document. A server implementing what the client thinks is a resource 400 with one of these interface descriptions could return malformed 401 representations and response codes either by accident or maliciously. 402 A server sending maliciously malformed responses could attempt to 403 take advantage of a poorly implemented client for example to crash 404 the node or perform denial of service. 406 6. IANA Considerations 408 The "binding" interface description types requires registration 410 The new link relations type "boundto" requires registration. 412 7. Acknowledgements 414 Acknowledgement is given to colleagues from the SENSEI project who 415 were critical in the initial development of the well-known REST 416 interface concept, to members of the IPSO Alliance where further 417 requirements for interface types have been discussed, and to Szymon 418 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 419 provided useful discussion and input to the concepts in this 420 document. 422 8. Changelog 424 draft-ietf-core-dynlink Initial Version 00: 426 o This is a copy of draft-groves-core-dynlink-00 428 draft-groves-core-dynlink Draft Initial Version 00: 430 o This initial version is based on the text regarding the dynamic 431 linking functionality in I.D.ietf-core-interfaces-05. 433 o The WADL description has been dropped in favour of a thorough 434 textual description of the REST API. 436 9. References 438 9.1. Normative References 440 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 441 Requirement Levels", BCP 14, RFC 2119, 442 DOI 10.17487/RFC2119, March 1997, 443 . 445 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 446 DOI 10.17487/RFC5988, October 2010, 447 . 449 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 450 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 451 . 453 9.2. Informative References 455 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 456 Application Protocol (CoAP)", RFC 7252, 457 DOI 10.17487/RFC7252, June 2014, 458 . 460 [RFC7641] Hartke, K., "Observing Resources in the Constrained 461 Application Protocol (CoAP)", RFC 7641, 462 DOI 10.17487/RFC7641, September 2015, 463 . 465 Authors' Addresses 466 Zach Shelby 467 ARM 468 150 Rose Orchard 469 San Jose 95134 470 FINLAND 472 Phone: +1-408-203-9434 473 Email: zach.shelby@arm.com 475 Matthieu Vial 476 Schneider-Electric 477 Grenoble 478 FRANCE 480 Phone: +33 (0)47657 6522 481 Email: matthieu.vial@schneider-electric.com 483 Michael Koster 484 SmartThings 485 665 Clyde Avenue 486 Mountain View 94043 487 USA 489 Email: michael.koster@smartthings.com 491 Christian Groves 492 Huawei 493 Australia 495 Email: Christian.Groves@nteczone.com