idnits 2.17.1 draft-ietf-core-interfaces-03.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 6, 2015) is 3210 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'REF' is mentioned on line 177, but not defined ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-03 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 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, 2016 Schneider-Electric 6 M. Koster 7 ARM 8 July 6, 2015 10 CoRE Interfaces 11 draft-ietf-core-interfaces-03 13 Abstract 15 This document defines well-known REST interface descriptions for 16 Batch, Sensor, Parameter and Actuator types for use in contrained web 17 servers using the CoRE Link Format. A short reference is provided 18 for each type that can be efficiently included in the interface 19 description attribute of the CoRE Link Format. These descriptions 20 are intended to be for general use in resource designs or for 21 inclusion in more specific interface profiles. In addition, this 22 document defines the concepts of Function Set and Binding. The 23 former is the basis element to create RESTful profiles and the latter 24 helps the configuration of links between resources located on one or 25 more endpoints. 27 Status of this Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on January 7, 2016. 44 Copyright Notice 46 Copyright (c) 2015 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 3. Function Set . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3.1. Defining a Function Set . . . . . . . . . . . . . . . . . 4 65 3.1.1. Path template . . . . . . . . . . . . . . . . . . . . 5 66 3.1.2. Resource Type . . . . . . . . . . . . . . . . . . . . 5 67 3.1.3. Interface Description . . . . . . . . . . . . . . . . 5 68 3.1.4. Data type . . . . . . . . . . . . . . . . . . . . . . 6 69 3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 6 70 3.3. Versioning . . . . . . . . . . . . . . . . . . . . . . . . 6 71 4. Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 72 4.1. Format . . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 4.2. Binding methods . . . . . . . . . . . . . . . . . . . . . 8 74 4.3. Binding table . . . . . . . . . . . . . . . . . . . . . . 9 75 5. Interface Descriptions . . . . . . . . . . . . . . . . . . . . 10 76 5.1. Link List . . . . . . . . . . . . . . . . . . . . . . . . 11 77 5.2. Batch . . . . . . . . . . . . . . . . . . . . . . . . . . 11 78 5.3. Linked Batch . . . . . . . . . . . . . . . . . . . . . . . 12 79 5.4. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . 13 80 5.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 14 81 5.6. Read-only Parameter . . . . . . . . . . . . . . . . . . . 14 82 5.7. Actuator . . . . . . . . . . . . . . . . . . . . . . . . . 15 83 5.8. Binding . . . . . . . . . . . . . . . . . . . . . . . . . 15 84 5.9. Resource Observation Attributes . . . . . . . . . . . . . 16 85 5.10. Future Interfaces . . . . . . . . . . . . . . . . . . . . 17 86 5.11. WADL Description . . . . . . . . . . . . . . . . . . . . . 17 87 6. Security Considerations . . . . . . . . . . . . . . . . . . . 23 88 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 89 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 90 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 23 91 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 92 10.1. Normative References . . . . . . . . . . . . . . . . . . . 25 93 10.2. Informative References . . . . . . . . . . . . . . . . . . 25 94 Appendix A. Profile example . . . . . . . . . . . . . . . . . . . 25 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26 97 1. Introduction 99 The Constrained RESTful Environments (CoRE) working group aims at 100 realizing the REST architecture in a suitable form for the most 101 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 102 ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to- 103 machine (M2M) applications such as smart energy and building 104 automation. 106 The discovery of resources offered by a constrained server is very 107 important in machine-to-machine applications where there are no 108 humans in the loop and static interfaces result in fragility. The 109 discovery of resources provided by an HTTP Web Server is typically 110 called Web Linking [RFC5988]. The use of Web Linking for the 111 description and discovery of resources hosted by constrained web 112 servers is specified by the CoRE Link Format [RFC6690] and can be 113 used by CoAP [RFC7252] or HTTP servers. The CoRE Link Format defines 114 an attribute that can be used to describe the REST interface of a 115 resource, and may include a link to a description document. This 116 memo describes how other specifications can combine resources with a 117 well-known interface to create new CoRE RESTful profiles. A CoRE 118 profile is based on the concept of Function Set, which is a group of 119 REST resources providing a service in a distributed system. In 120 addition, the notion of Binding is introduced in order to create a 121 synchronization link between two resources. This document also 122 defines well-known interface descriptions for Batch, Sensor, 123 Parameter and Actuator types to compose new Function Sets or for 124 standalone use in a constrained web server. A short reference is 125 provided for each type that can be efficiently included in the 126 interface description (if=) attribute of the CoRE Link Format. 128 2. Terminology 130 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 131 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 132 document are to be interpreted as described in [RFC2119]. 134 This specification requires readers to be familiar with all the terms 135 and concepts that are discussed in [RFC5988] and [RFC6690]. This 136 specification makes use of the following additional terminology: 138 Function Set: A group of well-known REST resources that provides a 139 particular service. 141 Profile: A group of well-known Function Sets defined by a 142 specification. 144 Device: An IP smart object running a web server that hosts a group 145 of Function Set instances from a profile. 147 Service Discovery: The process making it possible for a web client 148 to automatically detect devices and Function Sets offered by these 149 devices on a CoRE network. 151 Resource Discovery: The process allowing a web client to identify 152 resources being hosted on a web server. 154 Gradual Reveal: A REST design where resources are discovered 155 progressively using Web Linking. 157 Binding: A unidirectional logical link between a source resource and 158 a destination resource. 160 3. Function Set 162 This section defines how a set of REST resources can be created 163 called a function set. A Function Set is similar to a function block 164 in the sense that it consists of input, output and parameter 165 resources and contains internal logic. A Function Set can have a 166 subset of mandatory inputs, outputs and parameters to provide minimum 167 interoperability. It can also be extended with manufacturer/ 168 user-specific resources. A device is composed of one or more 169 Function Set instances. 171 An example of function sets can be found from the CoRE Resource 172 Directory specification that defines REST interfaces for 173 registration, group and lookup [I-D.ietf-core-resource-directory]. 174 The OMA Lightweight M2M standard [REF] also defines a function set 175 structure called an Objects that use integer path, instance and 176 resource URI segments. OMA Objects can be defined and then 177 registered with an OMA maintained registry [REF]. This section is 178 simply meant as a guideline for the definition of other such REST 179 interfaces, either custom or part of other specifications. 181 3.1. Defining a Function Set 183 In a Function Set, types of resources are defined. Each type 184 includes a human readable name, a path template, a Resource Type for 185 discovery, the Interface Definition and the data type and allowed 186 values. A Function Set definition may also include a field 187 indicating if a sub-resource is mandatory or optional. 189 3.1.1. Path template 191 A Function Set is a container resource under which its sub-resources 192 are organized. The profile defines the path to each resource of a 193 Function Set in a path template. The template can contain either 194 relative paths or absolute paths depending on the profile needs. An 195 absolute Function Set should be located at its recommended root path 196 on a web server, however it can be located under an alternative path 197 if necessary (for example multi-purpose devices, gateways etc.). A 198 relative Function Set can be instantiated as many times as needed on 199 a web server with an arbitrary root path. However some Function Sets 200 (e.g. device description) only make sense as singletons. 202 The path template includes a possible index {#} parameter, and 203 possible fixed path segments. The index {#} allows for multiple 204 instances of this type of resource, and can be any string. The root 205 path and the indexes are the only variable elements in a path 206 template. All other path segments should be fixed. 208 3.1.2. Resource Type 210 Each root resource of a Function Set is assigned a Resource Type 211 parameter, therefore making it possible to discover it. Each sub- 212 resource of a Function Set is also assigned a Resource Type 213 parameter. This Resource Type is used for resource discovery and is 214 usually necessary to discover optional resources supported on a 215 specific device. The Resource Type of a Function Set may also be 216 used for service discovery and can be exported to DNS-SD [RFC6763] 217 for example. 219 The Resource Type parameter defines the value that should be included 220 in the rt= field of the CoRE Link Format when describing a link to 221 this resource. The value SHOULD be in the form "namespace.type" for 222 root resources and "namespace.type.subtype" for sub-resources. This 223 naming convention facilitates resource type filtering with the 224 /.well-known/core resource. However a profile could allow mixing in 225 foreign namespace references within a Function Set to import external 226 references from other object models (e.g. SenML and UCUM). 228 3.1.3. Interface Description 230 The Interface Description parameter defines the REST interface for 231 that type of resource. Several base interfaces are defined in 232 Section 5 of this document. For a given profile, the Interface 233 Description may be inferred from the Resource Type. In that case the 234 Interface Description MAY be elided from link descriptions of 235 resource types defined in the profile, but should be included for 236 custom extensions to the profile. 238 The root resource of a Function Set should provide a list of links to 239 its sub-resources in order to offer gradual reveal of resources. The 240 CoRE Link List interface defined in Section 5.1 offers this 241 functionality so a root resource should support this interface or a 242 derived interface like CoRE Batch (See Section 5.2). 244 3.1.4. Data type 246 The Data Type field defines the type of value (and possible range) 247 that is returned in response to a GET for that resource or accepted 248 with a PUT. The interfaces defined in Section 5 make use of plain 249 text and SenML Media types for the actual format of this data. A 250 profile may restrict the list of supported content types for the CoRE 251 interfaces or define new interfaces with new content types. 253 3.2. Discovery 255 A device conforming to a profile SHOULD make its resources 256 discoverable by providing links to the resources on the path /.well- 257 known/core as defined in [RFC6690]. All resources hosted on a device 258 SHOULD be discoverable either with a direct link in /.well-known/core 259 or by following successive links starting from /.well-known/core. 261 The root path of a Function Set instance SHOULD be directly 262 referenced in /.well-known/core in order to offer discovery at the 263 first discovery stage. A device with more than 10 individual 264 resources SHOULD only expose Function Set instances in /.well-known/ 265 core to limit the size of this resource. 267 In addition, a device MAY register its resources to a Resource 268 Directory using the registration interface defined in 269 [I-D.ietf-core-resource-directory] if such a directory is available. 271 3.3. Versioning 273 A profile should track Function Set changes to avoid incompatibility 274 issues. Evolutions in a Function Set SHOULD be backward compatible. 276 4. Bindings 278 In a M2M RESTful environment, endpoints exchange the content of their 279 resources to operate the distributed system. Beforehand, a 280 configuration phase is necessary to determine how the resources of 281 the different endpoints are related to each other. This can be done 282 either automatically using discovery mechanisms or by means of human 283 intervention and a so-called commissioning tool. In this document 284 the abstract relationship between two resources is called a Binding. 286 The configuration phase necessitates the exchange of binding 287 information so a format recognized by all CoRE endpoints is 288 essential. This document defines a format based on the CoRE Link- 289 Format to represent binding information along with the rules to 290 define a binding method which is a specialized relationship between 291 two resources. The purpose of a binding is to synchronize the 292 content between a source resource and a destination resource. The 293 destination resource MAY be a group resource if the authority 294 component of the destination URI contains a group address (either a 295 multicast address or a name that resolves to a multicast address). 296 Since a binding is unidirectional, the binding entry defining a 297 relationship is present only on one endpoint. The binding entry may 298 be located either on the source or the destination endpoint depending 299 on the binding method. The following table gives a summary of the 300 binding methods described in more detail in Section 4.2. 302 +---------+------------+-------------+---------------+ 303 | Name | Identifier | Location | Method | 304 +---------+------------+-------------+---------------+ 305 | Polling | poll | Destination | GET | 306 | Observe | obs | Destination | GET + Observe | 307 | Push | push | Source | PUT | 308 +---------+------------+-------------+---------------+ 310 4.1. Format 312 Since Binding lies in the creation of a link between two resources, 313 Web Linking and the CoRE Link-Format are a natural way to represent 314 binding information. This involves the creation of a new relation 315 type, purposely named "boundto". In a Web link with this relation 316 type, the target URI contains the location of the source resource and 317 the context URI points to the destination resource. The Web link 318 attributes allow a fine-grained control of the type of 319 synchronization exchange along with the conditions that trigger an 320 update. This specification defines the attributes below: 322 +--------------------+-----------+------------------+ 323 | Attribute | Parameter | Value | 324 +--------------------+-----------+------------------+ 325 | Binding method | bind | xsd:string | 326 | Minimum Period (s) | pmin | xsd:integer (>0) | 327 | Maximum Period (s) | pmax | xsd:integer (>0) | 328 | Change Step | st | xsd:decimal (>0) | 329 | Greater Than | gt | xsd:decimal | 330 | Less Than | lt | xsd:decimal | 331 +--------------------+-----------+------------------+ 333 Bind Method: This is the identifier of a binding method which 334 defines the rules to synchronize the destination resource. This 335 attribute is mandatory. 337 Minimum Period: When present, the minimum period indicates the 338 minimum time to wait (in seconds) before sending a new 339 synchronization message (even if it has changed). In the absence 340 of this parameter, the minimum period is up to the notifier. 342 Maximum Period: When present, the maximum period indicates the 343 maximum time in seconds between two consecutive syncronization 344 messages (regardless if it has changed). In the absence of this 345 parameter, the maximum period is up to the notifier. The maximum 346 period MUST be greater than the minimum period parameter (if 347 present). 349 Change Step: When present, the change step indicates how much the 350 value of a resource SHOULD change before sending a new 351 notification (compared to the value of the last notification). 352 This parameter has lower priority than the period parameters, thus 353 even if the change step has been fulfilled, the time since the 354 last notification SHOULD be between pmin and pmax. 356 Greater Than: When present, Greater Than indicates the upper limit 357 value the resource value SHOULD cross before sending a new 358 notification. This parameter has lower priority than the period 359 parameters, thus even if the Greater Than limit has been crossed, 360 the time since the last notification SHOULD be between pmin and 361 pmax. 363 Less Than: When present, Less Than indicates the lower limit value 364 the resource value SHOULD cross before sending a new notification. 365 This parameter has lower priority than the period parameters, thus 366 even if the Less Than limit has been crossed, the time since the 367 last notification SHOULD be between pmin and pmax. 369 4.2. Binding methods 371 A binding method defines the rules to generate the web-transfer 372 exchanges that will effectively send content from the source resource 373 to the destination resource. The description of a binding method 374 must define the following aspects: 376 Identifier: This is value of the "bind" attribute used to identify 377 the method. 379 Location: This information indicates whether the binding entry is 380 stored on the source or on the destination endpoint. 382 REST Method: This is the REST method used in the Request/Response 383 exchanges. 385 Conditions: A binding method definition must state how the condition 386 attributes of the abstract binding definition are actually used in 387 this specialized binding. 389 This specification supports 3 binding methods described below. 391 Polling: The Polling method consists of sending periodic GET 392 requests from the destination endpoint to the source resource and 393 copying the content to the destination resource. The binding 394 entry for this method MUST be stored on the destination endpoint. 395 The destination endpoint MUST ensure that the polling frequency 396 does not exceed the limits defined by the pmin and pmax attributes 397 of the binding entry. The copying process MAY filter out content 398 from the GET requests using value-based conditions (e.g Change 399 Step, Less Than, Greater Than). 401 Observe: The Observe method relies on the Publish/Subscribe pattern 402 thus an observation relationship is created between the 403 destination endpoint and the source resource. On each 404 notification the content from the source resource is copied to the 405 destination resource. The creation of the observation 406 relationship requires the CoAP Observation mechanism 407 [I-D.ietf-core-observe] hence this method is only permitted when 408 the resources are made available over CoAP. The binding entry for 409 this method MUST be stored on the destination endpoint. The 410 binding conditions are mapped as query string parameters (see 411 Section 5.9). 413 Push: When the Push method is assigned to a binding, the source 414 endpoint sends PUT requests to the destination resource when the 415 binding condition attributes are satisfied for the source 416 resource. The source endpoint MUST only send a notification 417 request if the binding conditions are met. The binding entry for 418 this method MUST be stored on the source endpoint. 420 4.3. Binding table 422 The binding table is a special resource that gives access to the 423 bindings on a endpoint. A binding table resource MUST support the 424 Binding interface defined in Section 5.8. A profile SHOULD allow 425 only one resource table per endpoint. 427 5. Interface Descriptions 429 This section defines REST interfaces for Link List, Batch, Sensor, 430 Parameter, Actuator and Binding table resources. Variants such as 431 Linked Batch or Read-Only Parameter are also presented. Each type is 432 described along with its Interface Description attribute value and 433 valid methods. These are defined for each interface in the table 434 below. These interfaces can support plain text and/or SenML Media 435 types. 437 The if= column defines the Interface Description (if=) attribute 438 value to be used in the CoRE Link Format for a resource conforming to 439 that interface. When this value appears in the if= attribute of a 440 link, the resource MUST support the corresponding REST interface 441 described in this section. The resource MAY support additional 442 functionality, which is out of scope for this specification. 443 Although these interface descriptions are intended to be used with 444 the CoRE Link Format, they are applicable for use in any REST 445 interface definition. 447 The Methods column defines the methods supported by that interface, 448 which are described in more detail below. 450 +-------------------+----------+------------------------------------+ 451 | Interface | if= | Methods | 452 +-------------------+----------+------------------------------------+ 453 | Link List | core.ll | GET | 454 | Batch | core.b | GET, PUT, POST (where applicable) | 455 | Linked Batch | core.lb | GET, PUT, POST, DELETE (where | 456 | | | applicable) | 457 | Sensor | core.s | GET | 458 | Parameter | core.p | GET, PUT | 459 | Read-only | core.rp | GET | 460 | Parameter | | | 461 | Actuator | core.a | GET, PUT, POST | 462 | Binding | core.bnd | GET, POST, DELETE | 463 +-------------------+----------+------------------------------------+ 465 The following is an example of links in the CoRE Link Format using 466 these interface descriptions. The resource hierarchy is based on a 467 simple profile defined in Appendix A. These links are used in the 468 subsequent examples below. 470 Req: GET /.well-known/core 471 Res: 2.05 Content (application/link-format) 472 ;rt="simple.sen";if="core.b", 473 ;rt="simple.sen.lt";if="core.s", 474 ;rt="simple.sen.tmp";if="core.s";obs, 475 ;rt="simple.sen.hum";if="core.s", 476 ;rt="simple.act";if="core.b", 477 ;rt="simple.act.led";if="core.a", 478 ;rt="simple.act.led";if="core.a", 479 ;rt="simple.dev";if="core.ll", 480 ;if="core.lb", 482 5.1. Link List 484 The Link List interface is used to retrieve (GET) a list of resources 485 on a web server. The GET request SHOULD contain an Accept option 486 with the application/link-format content type, however if the 487 resource does not support any other form of GET methods the Accept 488 option MAY be elided. The Accept option SHOULD only include the 489 application/link-format content type. The request returns a list of 490 URI references with absolute paths to the resources as defined in 491 CoRE Link Format. This interface is typically used with a parent 492 resource to enumerate sub-resources but may be used to reference any 493 resource on a web server. 495 Link List is the base interface to provide gradual reveal of 496 resources on a CoRE web server, hence the root resource of a Function 497 Set SHOULD implement this interface or an extension of this 498 interface. 500 The following example interacts with a Link List /d containing 501 Parameter sub-resources /d/name, /d/model. 503 Req: GET /d (Accept:application/link-format) 504 Res: 2.05 Content (application/link-format) 505 ;rt="simple.dev.n";if="core.p", 506 ;rt="simple.dev.mdl";if="core.rp" 508 5.2. Batch 510 The Batch interface is used to manipulate a collection of sub- 511 resources at the same time. The Batch interface type supports the 512 same methods as its sub-resources, and can be used to read (GET), set 513 (PUT) or toggle (POST) the values of those sub-resource with a single 514 resource representation. The sub-resources of a Batch MAY be 515 heterogeneous, a method used on the Batch only applies to sub- 516 resources that support it. For example Sensor interfaces do not 517 support PUT, and thus a PUT request to a Sensor member of that Batch 518 would be ignored. A batch requires the use of SenML Media types in 519 order to support multiple sub-resources. 521 In addition, The Batch interface is an extension of the Link List 522 interface and in consequence MUST support the same methods. 524 The following example interacts with a Batch /s with Sensor sub- 525 resources /s/light, /s/temp and /s/humidity. 527 Req: GET /s 528 Res: 2.05 Content (application/senml+json) 529 {"e":[ 530 { "n": "light", "v": 123, "u": "lx" }, 531 { "n": "temp", "v": 27.2, "u": "degC" }, 532 { "n": "humidity", "v": 80, "u": "%RH" }], 533 } 535 5.3. Linked Batch 537 The Linked Batch interface is an extension of the Batch interface. 538 Contrary to the basic Batch which is a collection statically defined 539 by the web server, a Linked Batch is dynamically controlled by a web 540 client. A Linked Batch resource has no sub-resources. Instead the 541 resources forming the batch are referenced using Web Linking 542 [RFC5988] and the CoRE Link Format [RFC6690]. A request with a POST 543 method and a content type of application/link-format simply appends 544 new resources to the collection. The links in the payload MUST 545 reference a resource on the web server with an absolute path. A 546 DELETE request empties the current collection of links. All other 547 requests available for a basic Batch are still valid for a Linked 548 Batch. 550 The following example interacts with a Linked Batch /l and creates a 551 collection containing /s/light, /s/temp and /s/humidity in 2 steps. 553 Req: POST /l (Content-type: application/link-format) 554 , 555 Res: 2.04 Changed 557 Req: GET /l 558 Res: 2.05 Content (application/senml+json) 559 {"e":[ 560 { "n": "/s/light", "v": 123, "u": "lx" }, 561 { "n": "/s/temp", "v": 27.2, "u": "degC" }, 562 } 564 Req: POST /l (Content-type: application/link-format) 565 566 Res: 2.04 Changed 568 Req: GET /l (Accept: application/link-format) 569 Res: 2.05 Content (application/link-format) 570 ,, 572 Req: GET /l 573 Res: 2.05 Content (application/senml+json) 574 {"e":[ 575 { "n": "/s/light", "v": 123, "u": "lx" }, 576 { "n": "/s/temp", "v": 27.2, "u": "degC" }, 577 { "n": "/s/humidity", "v": 80, "u": "%RH" }], 578 } 580 Req: DELETE /l 581 Res: 2.04 Changed 583 5.4. Sensor 585 The Sensor interface allows the value of a sensor resource to be read 586 (GET). The Media type of the resource can be either plain text or 587 SenML. Plain text MAY be used for a single measurement that does not 588 require meta-data. For a measurement with meta-data such as a unit 589 or time stamp, SenML SHOULD be used. A resource with this interface 590 MAY use SenML to return multiple measurements in the same 591 representation, for example a list of recent measurements. 593 The following are examples of Sensor interface requests in both text/ 594 plain and application/senml+json. 596 Req: GET /s/humidity (Accept: text/plain) 597 Res: 2.05 Content (text/plain) 598 80 600 Req: GET /s/humidity (Accept: application/senml+json) 601 Res: 2.05 Content (application/senml+json) 602 {"e":[ 603 { "n": "humidity", "v": 80, "u": "%RH" }], 604 } 606 5.5. Parameter 608 The Parameter interface allows configurable parameters and other 609 information to be modeled as a resource. The value of the parameter 610 can be read (GET) or set (PUT). Plain text or SenML Media types MAY 611 be returned from this type of interface. 613 The following example shows request for reading and setting a 614 parameter. 616 Req: GET /d/name 617 Res: 2.05 Content (text/plain) 618 node5 620 Req: PUT /d/name (text/plain) 621 outdoor 622 Res: 2.04 Changed 624 5.6. Read-only Parameter 626 The Read-only Parameter interface allows configuration parameters to 627 be read (GET) but not set. Plain text or SenML Media types MAY be 628 returned from this type of interface. 630 The following example shows request for reading such a parameter. 632 Req: GET /d/model 633 Res: 2.05 Content (text/plain) 634 SuperNode200 636 5.7. Actuator 638 The Actuator interface is used by resources that model different 639 kinds of actuators (changing its value has an effect on its 640 environment). Examples of actuators include for example LEDs, 641 relays, motor controllers and light dimmers. The current value of 642 the actuator can be read (GET) or a new actuator value set (PUT). In 643 addition, this interface defines the use of POST (with no body) to 644 toggle an actuator between its possible values. Plain text or SenML 645 Media types MAY be returned from this type of interface. A resource 646 with this interface MAY use SenML to include multiple measurements in 647 the same representation, for example a list of recent actuator values 648 or a list of values to set. 650 The following example shows requests for reading, setting and 651 toggling an actuator (turning on a led). 653 Req: GET /a/1/led 654 Res: 2.05 Content (text/plain) 655 0 657 Req: PUT /a/1/led (text/plain) 658 1 659 Res: 2.04 Changed 661 Req: POST /a/1/led (text/plain) 662 Res: 2.04 Changed 664 Req: GET /a/1/led 665 Res: 2.05 Content (text/plain) 666 0 668 5.8. Binding 670 The Binding interface is used to manipulate a binding table. A 671 request with a POST method and a content type of application/ 672 link-format simply appends new bindings to the table. All links in 673 the payload MUST have a relation type "boundTo". A GET request 674 simply returns the current state of a binding table whereas a DELETE 675 request empties the table. 677 The following example shows requests for adding, retrieving and 678 deleting bindings in a binding table. 680 Req: POST /bnd (Content-type: application/link-format) 681 ; 682 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 683 Res: 2.04 Changed 685 Req: GET /bnd 686 Res: 2.05 Content (application/link-format) 687 ; 688 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 690 Req: DELETE /bnd 691 Res: 2.04 Changed 693 5.9. Resource Observation Attributes 695 When resource interfaces following this specification are made 696 available over CoAP, the CoAP Observation mechanism 697 [I-D.ietf-core-observe] MAY be used to observe any changes in a 698 resource, and receive asynchronous notifications as a result. In 699 addition, a set of query string parameters are defined here to allow 700 a client to control how often a client is interested in receiving 701 notifications and how much a resource value should change for the new 702 representation to be interesting. These query parameters are 703 described in the following table. A resource using an interface 704 description defined in this specification and marked as Observable in 705 its link description SHOULD support these observation parameters. 706 The Change Step parameter can only be supported on resources with an 707 atomic numeric value. 709 These query parameters MUST be treated as resources that are read 710 using GET and set using PUT, and MUST NOT be included in the Observe 711 request. Multiple parameters MAY be set at the same time by 712 including the values in the query string of a PUT. Before being set, 713 these parameters have no default value. 715 +----------------+------------------+------------------+ 716 | Resource | Parameter | Data Format | 717 +----------------+------------------+------------------+ 718 | Minimum Period | /{resource}?pmin | xsd:integer (>0) | 719 | Maximum Period | /{resource}?pmax | xsd:integer (>0) | 720 | Change Step | /{resource}?st | xsd:decimal (>0) | 721 | Less Than | /{resource}?lt | xsd:decimal | 722 | Greater Than | /{resource}?gt | xsd:decimal | 723 +----------------+------------------+------------------+ 725 Minimum Period: When present, the minimum period indicates the 726 minimum time to wait (in seconds) before sending a new 727 synchronization message (even if it has changed). In the absence 728 of this parameter, the minimum period is up to the notifier. 730 Maximum Period: When present, the maximum period indicates the 731 maximum time in seconds between two consecutive syncronization 732 messages (regardless if it has changed). In the absence of this 733 parameter, the maximum period is up to the notifier. The maximum 734 period MUST be greater than the minimum period parameter (if 735 present). 737 Change Step: When present, the change step indicates how much the 738 value of a resource SHOULD change before sending a new 739 notification (compared to the value of the last notification). 740 This parameter has lower priority than the period parameters, thus 741 even if the change step has been fulfilled, the time since the 742 last notification SHOULD be between pmin and pmax. 744 Greater Than: When present, Greater Than indicates the upper limit 745 value the resource value SHOULD cross before sending a new 746 notification. This parameter has lower priority than the period 747 parameters, thus even if the Greater Than limit has been crossed, 748 the time since the last notification SHOULD be between pmin and 749 pmax. 751 Less Than: When present, Less Than indicates the lower limit value 752 the resource value SHOULD cross before sending a new notification. 753 This parameter has lower priority than the period parameters, thus 754 even if the Less Than limit has been crossed, the time since the 755 last notification SHOULD be between pmin and pmax. 757 5.10. Future Interfaces 759 It is expected that further interface descriptions will be defined in 760 this and other specifications. Potential interfaces to be considered 761 for this specifications include: 763 Collection: This resource would be a container that allows sub- 764 resources to be added or removed. 766 5.11. WADL Description 768 This section defines the formal Web Application Description Langauge 769 (WADL) definition of these CoRE interface descriptions. 771 772 776 777 778 780 782 783 784 785 786 787 788 789 791 792 793 794 795 796 797 798 799 801 802 803 804 805 806 807 808 810 811 812 813 814 815 816 817 818 819 820 821 822 823 825 826 The methods read, 827 observe, update and toggle are applied to each sub- 828 resource of the requested resource that supports it. Mixed 829 sub-resource types can be supported. 830 831 832 833 834 835 836 837 838 840 841 . The methods read, 842 obervableRead, update and toggle are applied to each linked 843 resource of the requested resource that supports it. Mixed 844 linked resource types can be supported. 845 846 847 848 849 850 851 852 853 854 856 857 A modifiable list of 858 links. Each link MUST have the relation type "boundTo". 859 860 861 862 864 865 Retrieve the value of a sensor, an actuator or a parameter. 866 Both HTTP and CoAP support this method. 867 868 869 870 871 872 873 874 875 876 878 879 880 881 882 884 885 Observe the value of a sensor, an actuator or a parameter. 886 Only CoAP supports this method since it requires the CoRE 887 Observe mechanism. 888 889 890 893 894 895 896 897 898 899 901 902 Cancel observation in progress. 903 Only CoAP supports this method since it requires the CoRE 904 Observe mechanism. 905 906 907 910 911 912 913 914 915 917 919 920 Control the actuator or update a parameter with a new value 921 or command. Both HTTP and CoAP support this method. 922 923 924 925 926 927 928 929 930 932 933 Retrieve the observe attributes associated with a resource. 934 Both HTTP and CoAP support this method. 935 936 This request MUST contain an Accept option with 937 application/link-format when the resource supports 938 other GET methods. 939 940 941 942 943 944 945 946 947 949 950 Set the values of some or all of the observe attributes 951 associated with a resource. 952 Both HTTP and CoAP support this method. 953 954 955 956 957 958 959 960 961 962 963 964 965 966 Toggle the values of actuator resources. Both HTTP and CoAP 967 support this method. 968 969 The toggle function is only applicable if the request 970 is empty. 971 972 973 974 976 977 Retrieve the list of Web links associated to a resource. 978 Both HTTP and CoAP support this method. 979 980 This request MUST contain an Accept option with 981 application/link-format when the resource supports 982 other GET methods. 983 984 985 986 987 988 989 990 992 993 Append new Web links to a resource which is a collection 994 of links. Both HTTP and CoAP support this method. 995 996 997 998 999 1000 1002 1003 Clear all Web Links in a resource which is a collection 1004 of links. Both HTTP and CoAP support this method. 1005 1006 1007 1008 1009 1011 1013 6. Security Considerations 1015 An implementation of a client needs to be prepared to deal with 1016 responses to a request that differ from what is specified in this 1017 document. A server implementing what the client thinks is a resource 1018 with one of these interface descriptions could return malformed 1019 representations and response codes either by accident or maliciously. 1020 A server sending maliciously malformed responses could attempt to 1021 take advantage of a poorly implemented client for example to crash 1022 the node or perform denial of service. 1024 7. IANA Considerations 1026 The interface description types defined require registration. 1028 The new link relation type "boundto" requires registration. 1030 8. Acknowledgments 1032 Acknowledgement is given to colleagues from the SENSEI project who 1033 were critical in the initial development of the well-known REST 1034 interface concept, to members of the IPSO Alliance where further 1035 requirements for interface types have been discussed, and to Szymon 1036 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 1037 provided useful discussion and input to the concepts in this 1038 document. 1040 9. Changelog 1042 Changes from -02 to -03 1044 o Added lt and gt to binding format section. 1046 o Added pmin and pmax observe parameters to Observation Attributes 1048 o Changed the definition of lt and gt to limit crossing. 1050 o Added definitions for getattr and setattr to WADL. 1052 o Added getattr and setattr to observable interfaces. 1054 o Removed query parameters from Observe definition. 1056 o Added observe-cancel definition to WADL and to observable 1057 interfaces. 1059 Changes from -01 to -02 1061 o Updated the date and version, fixed references. 1063 o Removed pmin and pmax observe parameters [Ticket #336] 1065 Changes from -00 to WG Document -01 1067 o Improvements to the Function Set section. 1069 Changes from -05 to WG Document -00 1071 o Updated the date and version. 1073 Changes from -04 to -05 1075 o Made the Observation control parameters to be treated as resources 1076 rather than Observe query parameters. Added Less Than and Greater 1077 Than parameters. 1079 Changes from -03 to -04 1081 o Draft refresh 1083 Changes from -02 to -03 1085 o Added Bindings 1087 o Updated all rt= and if= for the new Link Format IANA rules 1089 Changes from -01 to -02 1091 o Defined a Function Set and its guidelines. 1093 o Added the Link List interface. 1095 o Added the Linked Batch interface. 1097 o Improved the WADL interface definition. 1099 o Added a simple profile example. 1101 10. References 1102 10.1. Normative References 1104 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1105 Requirement Levels", BCP 14, RFC 2119, March 1997. 1107 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1109 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1110 Format", RFC 6690, August 2012. 1112 10.2. Informative References 1114 [I-D.ietf-core-observe] 1115 Hartke, K., "Observing Resources in CoAP", 1116 draft-ietf-core-observe-16 (work in progress), 1117 December 2014. 1119 [I-D.ietf-core-resource-directory] 1120 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 1121 Resource Directory", draft-ietf-core-resource-directory-03 1122 (work in progress), June 2015. 1124 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 1125 Discovery", RFC 6763, February 2013. 1127 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1128 Application Protocol (CoAP)", RFC 7252, June 2014. 1130 Appendix A. Profile example 1132 The following is a short definition of simple profile. This 1133 simplistic profile is for use in the examples of this document. 1135 +--------------------+-----------+------------+---------+ 1136 | Function Set | Root Path | RT | IF | 1137 +--------------------+-----------+------------+---------+ 1138 | Device Description | /d | simple.dev | core.ll | 1139 | Sensors | /s | simple.sen | core.b | 1140 | Actuators | /a | simple.act | core.b | 1141 +--------------------+-----------+------------+---------+ 1143 List of Function Sets 1145 +-------+----------+----------------+---------+------------+ 1146 | Type | Path | RT | IF | Data Type | 1147 +-------+----------+----------------+---------+------------+ 1148 | Name | /d/name | simple.dev.n | core.p | xsd:string | 1149 | Model | /d/model | simple.dev.mdl | core.rp | xsd:string | 1150 +-------+----------+----------------+---------+------------+ 1152 Device Description Function Set 1154 +-------------+-------------+----------------+--------+-------------+ 1155 | Type | Path | RT | IF | Data Type | 1156 +-------------+-------------+----------------+--------+-------------+ 1157 | Light | /s/light | simple.sen.lt | core.s | xsd:decimal | 1158 | | | | | (lux) | 1159 | Humidity | /s/humidity | simple.sen.hum | core.s | xsd:decimal | 1160 | | | | | (%RH) | 1161 | Temperature | /s/temp | simple.sen.tmp | core.s | xsd:decimal | 1162 | | | | | (degC) | 1163 +-------------+-------------+----------------+--------+-------------+ 1165 Sensors Function Set 1167 +------+------------+----------------+--------+-------------+ 1168 | Type | Path | RT | IF | Data Type | 1169 +------+------------+----------------+--------+-------------+ 1170 | LED | /a/{#}/led | simple.act.led | core.a | xsd:boolean | 1171 +------+------------+----------------+--------+-------------+ 1173 Actuators Function Set 1175 Authors' Addresses 1177 Zach Shelby 1178 ARM 1179 150 Rose Orchard 1180 San Jose 95134 1181 FINLAND 1183 Phone: +1-408-203-9434 1184 Email: zach.shelby@arm.com 1185 Matthieu Vial 1186 Schneider-Electric 1187 Grenoble, 1188 FRANCE 1190 Phone: +33 (0)47657 6522 1191 Email: matthieu.vial@schneider-electric.com 1193 Michael Koster 1194 ARM 1195 150 Rose Orchard 1196 San Jose 95134 1197 FINLAND 1199 Phone: 1200 Email: michael.koster@arm.com