idnits 2.17.1 draft-groves-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 (July 6, 2016) is 2850 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 Z. Shelby 3 Internet-Draft ARM 4 Intended status: Informational M. Vial 5 Expires: January 7, 2017 Schneider-Electric 6 M. Koster 7 SmartThings 8 C. Groves 9 Huawei 10 July 6, 2016 12 Dynamic Resource Linking for Constrained RESTful Environments 13 draft-groves-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 January 7, 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 . . . . . . . . . . . . . . . . . . . 7 65 4.1. Binding . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 67 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 68 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 69 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 71 9.1. Normative References . . . . . . . . . . . . . . . . . . 9 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", "MAY", and "OPTIONAL" in this 102 document are to be interpreted as described in [RFC2119]. 104 This specification requires readers to be familiar with all the terms 105 and concepts that are discussed in [RFC5988] and [RFC6690]. This 106 specification makes use of the following additional terminology: 108 Link Binding: A unidirectional logical link between a source 109 resource and a destination resource, over which state information 110 is synchronized. 112 3. Link Bindings and Observe Attributes 114 In a M2M RESTful environment, endpoints may directly exchange the 115 content of their resources to operate the distributed system. For 116 example, a light switch may supply on-off control information that 117 may be sent directly to a light resource for on-off control. 118 Beforehand, a configuration phase is necessary to determine how the 119 resources of the different endpoints are related to each other. This 120 can be done either automatically using discovery mechanisms or by 121 means of human intervention and a so-called commissioning tool. In 122 this document the abstract relationship between two resources is 123 called a link Binding. The configuration phase necessitates the 124 exchange of binding information so a format recognized by all CoRE 125 endpoints is essential. This document defines a format based on the 126 CoRE Link-Format to represent binding information along with the 127 rules to define a binding method which is a specialized relationship 128 between two resources. The purpose of a binding is to synchronize 129 the content between a source resource and a destination resource. 130 The destination resource MAY be a group resource if the authority 131 component of the destination URI contains a group address (either a 132 multicast address or a name that resolves to a multicast address). 133 Since a binding is unidirectional, the binding entry defining a 134 relationship is present only on one endpoint. The binding entry may 135 be located either on the source or the destination endpoint depending 136 on the binding method. The following table gives a summary of the 137 binding methods described in more detail in Section 3.2. 139 +---------+------------+-------------+---------------+ 140 | Name | Identifier | Location | Method | 141 +---------+------------+-------------+---------------+ 142 | Polling | poll | Destination | GET | 143 | Observe | obs | Destination | GET + Observe | 144 | Push | push | Source | PUT | 145 +---------+------------+-------------+---------------+ 147 3.1. Format 149 Since Binding involves the creation of a link between two resources, 150 Web Linking and the CoRE Link-Format are a natural way to represent 151 binding information. This involves the creation of a new relation 152 type, purposely named "boundto". In a Web link with this relation 153 type, the target URI contains the location of the source resource and 154 the context URI points to the destination resource. The Web link 155 attributes allow a fine-grained control of the type of 156 synchronization exchange along with the conditions that trigger an 157 update. This specification defines the attributes below: 159 +--------------------+-----------+------------------+ 160 | Attribute | Parameter | Value | 161 +--------------------+-----------+------------------+ 162 | Binding method | bind | xsd:string | 163 | Minimum Period (s) | pmin | xsd:integer (>0) | 164 | Maximum Period (s) | pmax | xsd:integer (>0) | 165 | Change Step | st | xsd:decimal (>0) | 166 | Greater Than | gt | xsd:decimal | 167 | Less Than | lt | xsd:decimal | 168 +--------------------+-----------+------------------+ 170 Bind Method: This is the identifier of a binding method which 171 defines the rules to synchronize the destination resource. This 172 attribute is mandatory. 174 Minimum Period: When present, the minimum period indicates the 175 minimum time to wait (in seconds) before sending a new 176 synchronization message (even if it has changed). In the absence 177 of this parameter, the minimum period is up to the notifier. 179 Maximum Period: When present, the maximum period indicates the 180 maximum time in seconds between two consecutive state 181 synchronization messages (regardless if it has changed). In the 182 absence of this parameter, the maximum period is up to the 183 notifier. The maximum period MUST be greater than the minimum 184 period parameter (if present). 186 Change Step: When present, the change step indicates how much the 187 value of a resource SHOULD change before sending a new 188 notification (compared to the value of the last notification). 189 This parameter has lower priority than the period parameters, thus 190 even if the change step has been fulfilled, the time since the 191 last notification SHOULD be between pmin and pmax. 193 Greater Than: When present, Greater Than indicates the upper limit 194 value the resource value SHOULD cross before sending a new 195 notification. This parameter has lower priority than the period 196 parameters, thus even if the Greater Than limit has been crossed, 197 the time since the last notification SHOULD be between pmin and 198 pmax. 200 Less Than: When present, Less Than indicates the lower limit value 201 the resource value SHOULD cross before sending a new notification. 202 This parameter has lower priority than the period parameters, thus 203 even if the Less Than limit has been crossed, the time since the 204 last notification SHOULD be between pmin and pmax. 206 3.2. Binding methods 208 A binding method defines the rules to generate the web-transfer 209 exchanges that will effectively send content from the source resource 210 to the destination resource. The description of a binding method 211 must define the following aspects: 213 Identifier: This is value of the "bind" attribute used to identify 214 the method. 216 Location: This information indicates whether the binding entry is 217 stored on the source or on the destination endpoint. 219 REST Method: This is the REST method used in the Request/Response 220 exchanges. 222 Conditions: A binding method definition must state how the condition 223 attributes of the abstract binding definition are actually used in 224 this specialized binding. 226 This specification supports 3 binding methods described below. 228 Polling: The Polling method consists of sending periodic GET 229 requests from the destination endpoint to the source resource and 230 copying the content to the destination resource. The binding 231 entry for this method MUST be stored on the destination endpoint. 232 The destination endpoint MUST ensure that the polling frequency 233 does not exceed the limits defined by the pmin and pmax attributes 234 of the binding entry. The copying process MAY filter out content 235 from the GET requests using value-based conditions (e.g Change 236 Step, Less Than, Greater Than). 238 Observe: The Observe method creates an observation relationship 239 between the destination endpoint and the source resource. On each 240 notification the content from the source resource is copied to the 241 destination resource. The creation of the observation 242 relationship requires the CoAP Observation mechanism [RFC7641] 243 hence this method is only permitted when the resources are made 244 available over CoAP. The binding entry for this method MUST be 245 stored on the destination endpoint. The binding conditions are 246 mapped as query string parameters (see Section 3.4). 248 Push: When the Push method is assigned to a binding, the source 249 endpoint sends PUT requests to the destination resource when the 250 binding condition attributes are satisfied for the source 251 resource. The source endpoint MUST only send a notification 252 request if the binding conditions are met. The binding entry for 253 this method MUST be stored on the source endpoint. 255 3.3. Binding table 257 The binding table is a special resource that gives access to the 258 bindings on a endpoint. A binding table resource MUST support the 259 Binding interface defined in Section 4.1. A profile SHOULD allow 260 only one resource table per endpoint. 262 3.4. Resource Observation Attributes 264 When resource interfaces following this specification are made 265 available over CoAP, the CoAP Observation mechanism [RFC7641] MAY be 266 used to observe any changes in a resource, and receive asynchronous 267 notifications as a result. In addition, a set of query string 268 parameters are defined here to allow a client to control how often a 269 client is interested in receiving notifications and how much a 270 resource value should change for the new representation to be 271 interesting. These query parameters are described in the following 272 table. A resource using an interface description defined in this 273 specification and marked as Observable in its link description SHOULD 274 support these observation parameters. The Change Step parameter can 275 only be supported on resources with an atomic numeric value. 277 These query parameters MUST be treated as resources that are read 278 using GET and updated using PUT, and MUST NOT be included in the 279 Observe request. Multiple parameters MAY be updated at the same time 280 by including the values in the query string of a PUT. Before being 281 updated, these parameters have no default value. 283 +----------------+------------------+------------------+ 284 | Resource | Parameter | Data Format | 285 +----------------+------------------+------------------+ 286 | Minimum Period | /{resource}?pmin | xsd:integer (>0) | 287 | Maximum Period | /{resource}?pmax | xsd:integer (>0) | 288 | Change Step | /{resource}?st | xsd:decimal (>0) | 289 | Less Than | /{resource}?lt | xsd:decimal | 290 | Greater Than | /{resource}?gt | xsd:decimal | 291 +----------------+------------------+------------------+ 293 Minimum Period: When present, the minimum period indicates the 294 minimum time to wait (in seconds) before sending a new 295 synchronization message (even if it has changed). In the absence 296 of this parameter, the minimum period is up to the notifier. 298 Maximum Period: When present, the maximum period indicates the 299 maximum time in seconds between two consecutive state 300 synchronization messages (regardless if it has changed). In the 301 absence of this parameter, the maximum period is up to the 302 notifier. The maximum period MUST be greater than the minimum 303 period parameter (if present). 305 Change Step: When present, the change step indicates how much the 306 value of a resource SHOULD change before sending a new 307 notification (compared to the value of the last notification). 308 This parameter has lower priority than the period parameters, thus 309 even if the change step has been fulfilled, the time since the 310 last notification SHOULD be between pmin and pmax. 312 Greater Than: When present, Greater Than indicates the upper limit 313 value the resource value SHOULD cross before sending a new 314 notification. This parameter has lower priority than the period 315 parameters, thus even if the Greater Than limit has been crossed, 316 the time since the last notification SHOULD be between pmin and 317 pmax. 319 Less Than: When present, Less Than indicates the lower limit value 320 the resource value SHOULD cross before sending a new notification. 321 This parameter has lower priority than the period parameters, thus 322 even if the Less Than limit has been crossed, the time since the 323 last notification SHOULD be between pmin and pmax. 325 4. Interface Descriptions 327 This section defines REST interfaces for Binding table resources. 328 The interface supports the link-format type. 330 The if= column defines the Interface Description (if=) attribute 331 value to be used in the CoRE Link Format for a resource conforming to 332 that interface. When this value appears in the if= attribute of a 333 link, the resource MUST support the corresponding REST interface 334 described in this section. The resource MAY support additional 335 functionality, which is out of scope for this specification. 336 Although this interface descriptions is intended to be used with the 337 CoRE Link Format, it is applicable for use in any REST interface 338 definition. 340 The Methods column defines the methods supported by that interface, 341 which are described in more detail below. 343 +-----------+----------+-------------------+-----------------+ 344 | Interface | if= | Methods | Content-Formats | 345 +-----------+----------+-------------------+-----------------+ 346 | Binding | core.bnd | GET, POST, DELETE | link-format | 347 +-----------+----------+-------------------+-----------------+ 349 4.1. Binding 351 The Binding interface is used to manipulate a binding table. A 352 request with a POST method and a content format of application/link- 353 format simply appends new bindings to the table. All links in the 354 payload MUST have a relation type "boundTo". A GET request simply 355 returns the current state of a binding table whereas a DELETE request 356 empties the table. 358 The following example shows requests for adding, retrieving and 359 deleting bindings in a binding table. 361 Req: POST /bnd/ (Content-Format: application/link-format) 362 ; 363 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 364 Res: 2.04 Changed 366 Req: GET /bnd/ 367 Res: 2.05 Content (application/link-format) 368 ; 369 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 371 Req: DELETE /bnd/ 372 Res: 2.04 Changed 374 5. Security Considerations 376 An implementation of a client needs to be prepared to deal with 377 responses to a request that differ from what is specified in this 378 document. A server implementing what the client thinks is a resource 379 with one of these interface descriptions could return malformed 380 representations and response codes either by accident or maliciously. 381 A server sending maliciously malformed responses could attempt to 382 take advantage of a poorly implemented client for example to crash 383 the node or perform denial of service. 385 6. IANA Considerations 387 The "binding" interface description types requires registration. 389 The new link relations type "boundto" requires registration. 391 7. Acknowledgments 393 Acknowledgement is given to colleagues from the SENSEI project who 394 were critical in the initial development of the well-known REST 395 interface concept, to members of the IPSO Alliance where further 396 requirements for interface types have been discussed, and to Szymon 397 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 398 provided useful discussion and input to the concepts in this 399 document. 401 8. Changelog 403 Initial Version 00 405 o This initial version is based on the text regarding the dynamic 406 linking functionality in I.D.ietf-core-interfaces-05. 408 o The WADL description has been dropped in favour of a thorough 409 textual description of the REST API. 411 9. References 413 9.1. Normative References 415 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 416 Requirement Levels", BCP 14, RFC 2119, 417 DOI 10.17487/RFC2119, March 1997, 418 . 420 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 421 DOI 10.17487/RFC5988, October 2010, 422 . 424 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 425 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 426 . 428 9.2. Informative References 430 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 431 Application Protocol (CoAP)", RFC 7252, 432 DOI 10.17487/RFC7252, June 2014, 433 . 435 [RFC7641] Hartke, K., "Observing Resources in the Constrained 436 Application Protocol (CoAP)", RFC 7641, 437 DOI 10.17487/RFC7641, September 2015, 438 . 440 Authors' Addresses 442 Zach Shelby 443 ARM 444 150 Rose Orchard 445 San Jose 95134 446 FINLAND 448 Phone: +1-408-203-9434 449 Email: zach.shelby@arm.com 451 Matthieu Vial 452 Schneider-Electric 453 Grenoble 454 FRANCE 456 Phone: +33 (0)47657 6522 457 Email: matthieu.vial@schneider-electric.com 459 Michael Koster 460 SmartThings 461 665 Clyde Avenue 462 Mountain View 94043 463 USA 465 Email: michael.koster@smartthings.com 466 Christian Groves 467 Huawei 468 Australia 470 Email: Christian.Groves@nteczone.com