idnits 2.17.1 draft-ietf-core-interfaces-01.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 (December 11, 2013) is 3782 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 (-16) exists of draft-ietf-core-observe-11 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-00 Summary: 1 error (**), 0 flaws (~~), 4 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: June 14, 2014 Schneider-Electric 6 December 11, 2013 8 CoRE Interfaces 9 draft-ietf-core-interfaces-01 11 Abstract 13 This document defines well-known REST interface descriptions for 14 Batch, Sensor, Parameter and Actuator types for use in contrained web 15 servers using the CoRE Link Format. A short reference is provided 16 for each type that can be efficiently included in the interface 17 description attribute of the CoRE Link Format. These descriptions 18 are intended to be for general use in resource designs or for 19 inclusion in more specific interface profiles. In addition, this 20 document defines the concepts of Function Set and Binding. The 21 former is the basis element to create RESTful profiles and the latter 22 helps the configuration of links between resources located on one or 23 more endpoints. 25 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on June 14, 2014. 42 Copyright Notice 44 Copyright (c) 2013 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3. Function Set . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 3.1. Defining a Function Set . . . . . . . . . . . . . . . . . 4 63 3.1.1. Path template . . . . . . . . . . . . . . . . . . . . 5 64 3.1.2. Resource Type . . . . . . . . . . . . . . . . . . . . 5 65 3.1.3. Interface Description . . . . . . . . . . . . . . . . 5 66 3.1.4. Data type . . . . . . . . . . . . . . . . . . . . . . 6 67 3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 6 68 3.3. Versioning . . . . . . . . . . . . . . . . . . . . . . . . 6 69 4. Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 70 4.1. Format . . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 4.2. Binding methods . . . . . . . . . . . . . . . . . . . . . 8 72 4.3. Binding table . . . . . . . . . . . . . . . . . . . . . . 9 73 5. Interface Descriptions . . . . . . . . . . . . . . . . . . . . 10 74 5.1. Link List . . . . . . . . . . . . . . . . . . . . . . . . 11 75 5.2. Batch . . . . . . . . . . . . . . . . . . . . . . . . . . 11 76 5.3. Linked Batch . . . . . . . . . . . . . . . . . . . . . . . 12 77 5.4. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . 13 78 5.5. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 14 79 5.6. Read-only Parameter . . . . . . . . . . . . . . . . . . . 14 80 5.7. Actuator . . . . . . . . . . . . . . . . . . . . . . . . . 15 81 5.8. Binding . . . . . . . . . . . . . . . . . . . . . . . . . 15 82 5.9. Resource Observation Attributes . . . . . . . . . . . . . 16 83 5.10. Future Interfaces . . . . . . . . . . . . . . . . . . . . 18 84 5.11. WADL Description . . . . . . . . . . . . . . . . . . . . . 18 85 6. Security Considerations . . . . . . . . . . . . . . . . . . . 22 86 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 87 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 88 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 22 89 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 90 10.1. Normative References . . . . . . . . . . . . . . . . . . . 23 91 10.2. Informative References . . . . . . . . . . . . . . . . . . 23 92 Appendix A. Profile example . . . . . . . . . . . . . . . . . . . 24 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 95 1. Introduction 97 The Constrained RESTful Environments (CoRE) working group aims at 98 realizing the REST architecture in a suitable form for the most 99 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 100 ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to- 101 machine (M2M) applications such as smart energy and building 102 automation. 104 The discovery of resources offered by a constrained server is very 105 important in machine-to-machine applications where there are no 106 humans in the loop and static interfaces result in fragility. The 107 discovery of resources provided by an HTTP Web Server is typically 108 called Web Linking [RFC5988]. The use of Web Linking for the 109 description and discovery of resources hosted by constrained web 110 servers is specified by the CoRE Link Format 111 [I-D.ietf-core-link-format] and can be used by CoAP 112 [I-D.ietf-core-coap] or HTTP servers. The CoRE Link Format defines 113 an attribute that can be used to describe the REST interface of a 114 resource, and may include a link to a description document. This 115 memo describes how other specifications can combine resources with a 116 well-known interface to create new CoRE RESTful profiles. A CoRE 117 profile is based on the concept of Function Set, which is a group of 118 REST resources providing a service in a distributed system. In 119 addition, the notion of Binding is introduced in order to create a 120 synchronization link between two resources. This document also 121 defines well-known interface descriptions for Batch, Sensor, 122 Parameter and Actuator types to compose new Function Sets or for 123 standalone use in a constrained web server. A short reference is 124 provided for each type that can be efficiently included in the 125 interface description (if=) attribute of the CoRE Link Format. 127 2. Terminology 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [RFC2119]. 133 This specification requires readers to be familiar with all the terms 134 and concepts that are discussed in [RFC5988] and 135 [I-D.ietf-core-link-format]. This specification makes use of the 136 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 217 [I-D.cheshire-dnsext-dns-sd] 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 [I-D.ietf-core-link-format]. All resources 258 hosted on a device SHOULD be discoverable either with a direct link 259 in /.well-known/core or by following successive links starting from 260 /.well-known/core. 262 The root path of a Function Set instance SHOULD be directly 263 referenced in /.well-known/core in order to offer discovery at the 264 first discovery stage. A device with more than 10 individual 265 resources SHOULD only expose Function Set instances in /.well-known/ 266 core to limit the size of this resource. 268 In addition, a device MAY register its resources to a Resource 269 Directory using the registration interface defined in 270 [I-D.ietf-core-resource-directory] if such a directory is available. 272 3.3. Versioning 274 A profile should track Function Set changes to avoid incompatibility 275 issues. Evolutions in a Function Set SHOULD be backward compatible. 277 4. Bindings 279 In a M2M RESTful environment, endpoints exchange the content of their 280 resources to operate the distributed system. Beforehand, a 281 configuration phase is necessary to determine how the resources of 282 the different endpoints are related to each other. This can be done 283 either automatically using discovery mechanisms or by means of human 284 intervention and a so-called commissioning tool. In this document 285 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 +--------------------+-----------+------------------+ 331 Bind Method: This is the identifier of a binding method which 332 defines the rules to synchronize the destination resource. This 333 attribute is mandatory. 335 Minimum Period: When present, the minimum period indicates the 336 minimum time to wait (in seconds) before sending a new 337 synchronization message (even if it has changed). In the absence 338 of this parameter, the minimum period is up to the notifier. 340 Maximum Period: When present, the maximum period indicates the 341 maximum time in seconds between two consecutive syncronization 342 messages (regardless if it has changed). In the absence of this 343 parameter, the maximum period is up to the notifier. The maximum 344 period MUST be greater than the minimum period parameter (if 345 present). 347 Change Step: When present, the change step indicates how much the 348 value of a resource SHOULD change before sending a new 349 notification (compared to the value of the last notification). 350 This parameter has lower priority than the period parameters, thus 351 even if the change step has been fulfilled, the time since the 352 last notification SHOULD be between pmin and pmax. 354 4.2. Binding methods 356 A binding method defines the rules to generate the web-transfer 357 exchanges that will effectively send content from the source resource 358 to the destination resource. The description of a binding method 359 must define the following aspects: 361 Identifier: This is value of the "bind" attribute used to identify 362 the method. 364 Location: This information indicates whether the binding entry is 365 stored on the source or on the destination endpoint. 367 REST Method: This is the REST method used in the Request/Response 368 exchanges. 370 Conditions: A binding method definition must state how the condition 371 attributes of the abstract binding definition are actually used in 372 this specialized binding. 374 This specification supports 3 binding methods described below. 376 Polling: The Polling method consists of sending periodic GET 377 requests from the destination endpoint to the source resource and 378 copying the content to the destination resource. The binding 379 entry for this method MUST be stored on the destination endpoint. 380 The destination endpoint MUST ensure that the polling frequency 381 does not exceed the limits defined by the pmin and pmax attributes 382 of the binding entry. The copying process MAY filter out content 383 from the GET requests using value-based conditions (e.g Change 384 Step). 386 Observe: The Observe method relies on the Publish/Subscribe pattern 387 thus an observation relationship is created between the 388 destination endpoint and the source resource. On each 389 notification the content from the source resource is copied to the 390 destination resource. The creation of the observation 391 relationship requires the CoAP Observation mechanism 392 [I-D.ietf-core-observe] hence this method is only permitted when 393 the resources are made available over CoAP. The binding entry for 394 this method MUST be stored on the destination endpoint. The 395 binding conditions are mapped as query string parameters (see 396 Section 5.9). 398 Push: When the Push method is assigned to a binding, the source 399 endpoint sends PUT requests to the destination resource upon 400 change of the source resource. The source endpoint MUST only send 401 a notification request if the binding conditions are met. The 402 binding entry for this method MUST be stored on the source 403 endpoint. 405 4.3. Binding table 407 The binding table is a special resource that gives access to the 408 bindings on a endpoint. A binding table resource MUST support the 409 Binding interface defined in Section 5.8. A profile SHOULD allow 410 only one resource table per endpoint. 412 5. Interface Descriptions 414 This section defines REST interfaces for Link List, Batch, Sensor, 415 Parameter, Actuator and Binding table resources. Variants such as 416 Linked Batch or Read-Only Parameter are also presented. Each type is 417 described along with its Interface Description attribute value and 418 valid methods. These are defined for each interface in the table 419 below. These interfaces can support plain text and/or SenML Media 420 types. 422 The if= column defines the Interface Description (if=) attribute 423 value to be used in the CoRE Link Format for a resource conforming to 424 that interface. When this value appears in the if= attribute of a 425 link, the resource MUST support the corresponding REST interface 426 described in this section. The resource MAY support additional 427 functionality, which is out of scope for this specification. 428 Although these interface descriptions are intended to be used with 429 the CoRE Link Format, they are applicable for use in any REST 430 interface definition. 432 The Methods column defines the methods supported by that interface, 433 which are described in more detail below. 435 +-------------------+----------+------------------------------------+ 436 | Interface | if= | Methods | 437 +-------------------+----------+------------------------------------+ 438 | Link List | core.ll | GET | 439 | Batch | core.b | GET, PUT, POST (where applicable) | 440 | Linked Batch | core.lb | GET, PUT, POST, DELETE (where | 441 | | | applicable) | 442 | Sensor | core.s | GET | 443 | Parameter | core.p | GET, PUT | 444 | Read-only | core.rp | GET | 445 | Parameter | | | 446 | Actuator | core.a | GET, PUT, POST | 447 | Binding | core.bnd | GET, POST, DELETE | 448 +-------------------+----------+------------------------------------+ 450 The following is an example of links in the CoRE Link Format using 451 these interface descriptions. The resource hierarchy is based on a 452 simple profile defined in Appendix A. These links are used in the 453 subsequent examples below. 455 Req: GET /.well-known/core 456 Res: 2.05 Content (application/link-format) 457 ;rt="simple.sen";if="core.b", 458 ;rt="simple.sen.lt";if="core.s", 459 ;rt="simple.sen.tmp";if="core.s";obs, 460 ;rt="simple.sen.hum";if="core.s", 461 ;rt="simple.act";if="core.b", 462 ;rt="simple.act.led";if="core.a", 463 ;rt="simple.act.led";if="core.a", 464 ;rt="simple.dev";if="core.ll", 465 ;if="core.lb", 467 5.1. Link List 469 The Link List interface is used to retrieve (GET) a list of resources 470 on a web server. The GET request SHOULD contain an Accept option 471 with the application/link-format content type, however if the 472 resource does not support any other form of GET methods the Accept 473 option MAY be elided. The Accept option SHOULD only include the 474 application/link-format content type. The request returns a list of 475 URI references with absolute paths to the resources as defined in 476 CoRE Link Format. This interface is typically used with a parent 477 resource to enumerate sub-resources but may be used to reference any 478 resource on a web server. 480 Link List is the base interface to provide gradual reveal of 481 resources on a CoRE web server, hence the root resource of a Function 482 Set SHOULD implement this interface or an extension of this 483 interface. 485 The following example interacts with a Link List /d containing 486 Parameter sub-resources /d/name, /d/model. 488 Req: GET /d (Accept:application/link-format) 489 Res: 2.05 Content (application/link-format) 490 ;rt="simple.dev.n";if="core.p", 491 ;rt="simple.dev.mdl";if="core.rp" 493 5.2. Batch 495 The Batch interface is used to manipulate a collection of sub- 496 resources at the same time. The Batch interface type supports the 497 same methods as its sub-resources, and can be used to read (GET), set 498 (PUT) or toggle (POST) the values of those sub-resource with a single 499 resource representation. The sub-resources of a Batch MAY be 500 heterogeneous, a method used on the Batch only applies to sub- 501 resources that support it. For example Sensor interfaces do not 502 support PUT, and thus a PUT request to a Sensor member of that Batch 503 would be ignored. A batch requires the use of SenML Media types in 504 order to support multiple sub-resources. 506 In addition, The Batch interface is an extension of the Link List 507 interface and in consequence MUST support the same methods. 509 The following example interacts with a Batch /s with Sensor sub- 510 resources /s/light, /s/temp and /s/humidity. 512 Req: GET /s 513 Res: 2.05 Content (application/senml+json) 514 {"e":[ 515 { "n": "light", "v": 123, "u": "lx" }, 516 { "n": "temp", "v": 27.2, "u": "degC" }, 517 { "n": "humidity", "v": 80, "u": "%RH" }], 518 } 520 5.3. Linked Batch 522 The Linked Batch interface is an extension of the Batch interface. 523 Contrary to the basic Batch which is a collection statically defined 524 by the web server, a Linked Batch is dynamically controlled by a web 525 client. A Linked Batch resource has no sub-resources. Instead the 526 resources forming the batch are referenced using Web Linking 527 [RFC5988] and the CoRE Link Format [I-D.ietf-core-link-format]. A 528 request with a POST method and a content type of application/ 529 link-format simply appends new resources to the collection. The 530 links in the payload MUST reference a resource on the web server with 531 an absolute path. A DELETE request empties the current collection of 532 links. All other requests available for a basic Batch are still 533 valid for a Linked Batch. 535 The following example interacts with a Linked Batch /l and creates a 536 collection containing /s/light, /s/temp and /s/humidity in 2 steps. 538 Req: POST /l (Content-type: application/link-format) 539 , 540 Res: 2.04 Changed 542 Req: GET /l 543 Res: 2.05 Content (application/senml+json) 544 {"e":[ 545 { "n": "/s/light", "v": 123, "u": "lx" }, 546 { "n": "/s/temp", "v": 27.2, "u": "degC" }, 547 } 549 Req: POST /l (Content-type: application/link-format) 550 551 Res: 2.04 Changed 553 Req: GET /l (Accept: application/link-format) 554 Res: 2.05 Content (application/link-format) 555 ,, 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 { "n": "/s/humidity", "v": 80, "u": "%RH" }], 563 } 565 Req: DELETE /l 566 Res: 2.04 Changed 568 5.4. Sensor 570 The Sensor interface allows the value of a sensor resource to be read 571 (GET). The Media type of the resource can be either plain text or 572 SenML. Plain text MAY be used for a single measurement that does not 573 require meta-data. For a measurement with meta-data such as a unit 574 or time stamp, SenML SHOULD be used. A resource with this interface 575 MAY use SenML to return multiple measurements in the same 576 representation, for example a list of recent measurements. 578 The following are examples of Sensor interface requests in both text/ 579 plain and application/senml+json. 581 Req: GET /s/humidity (Accept: text/plain) 582 Res: 2.05 Content (text/plain) 583 80 585 Req: GET /s/humidity (Accept: application/senml+json) 586 Res: 2.05 Content (application/senml+json) 587 {"e":[ 588 { "n": "humidity", "v": 80, "u": "%RH" }], 589 } 591 5.5. Parameter 593 The Parameter interface allows configurable parameters and other 594 information to be modeled as a resource. The value of the parameter 595 can be read (GET) or set (PUT). Plain text or SenML Media types MAY 596 be returned from this type of interface. 598 The following example shows request for reading and setting a 599 parameter. 601 Req: GET /d/name 602 Res: 2.05 Content (text/plain) 603 node5 605 Req: PUT /d/name (text/plain) 606 outdoor 607 Res: 2.04 Changed 609 5.6. Read-only Parameter 611 The Read-only Parameter interface allows configuration parameters to 612 be read (GET) but not set. Plain text or SenML Media types MAY be 613 returned from this type of interface. 615 The following example shows request for reading such a parameter. 617 Req: GET /d/model 618 Res: 2.05 Content (text/plain) 619 SuperNode200 621 5.7. Actuator 623 The Actuator interface is used by resources that model different 624 kinds of actuators (changing its value has an effect on its 625 environment). Examples of actuators include for example LEDs, 626 relays, motor controllers and light dimmers. The current value of 627 the actuator can be read (GET) or a new actuator value set (PUT). In 628 addition, this interface defines the use of POST (with no body) to 629 toggle an actuator between its possible values. Plain text or SenML 630 Media types MAY be returned from this type of interface. A resource 631 with this interface MAY use SenML to include multiple measurements in 632 the same representation, for example a list of recent actuator values 633 or a list of values to set. 635 The following example shows requests for reading, setting and 636 toggling an actuator (turning on a led). 638 Req: GET /a/1/led 639 Res: 2.05 Content (text/plain) 640 0 642 Req: PUT /a/1/led (text/plain) 643 1 644 Res: 2.04 Changed 646 Req: POST /a/1/led (text/plain) 647 Res: 2.04 Changed 649 Req: GET /a/1/led 650 Res: 2.05 Content (text/plain) 651 0 653 5.8. Binding 655 The Binding interface is used to manipulate a binding table. A 656 request with a POST method and a content type of application/ 657 link-format simply appends new bindings to the table. All links in 658 the payload MUST have a relation type "boundTo". A GET request 659 simply returns the current state of a binding table whereas a DELETE 660 request empties the table. 662 The following example shows requests for adding, retrieving and 663 deleting bindings in a binding table. 665 Req: POST /bnd (Content-type: application/link-format) 666 ; 667 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 668 Res: 2.04 Changed 670 Req: GET /bnd 671 Res: 2.05 Content (application/link-format) 672 ; 673 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 675 Req: DELETE /bnd 676 Res: 2.04 Changed 678 5.9. Resource Observation Attributes 680 When resource interfaces following this specification are made 681 available over CoAP, the CoAP Observation mechanism 682 [I-D.ietf-core-observe] MAY be used to observe any changes in a 683 resource, and receive asynchronous notifications as a result. In 684 addition, a set of query string parameters are defined here to allow 685 a client to control how often a client is interested in receiving 686 notifications and how much a resource value should change for the new 687 representation to be interesting. These query parameters are 688 described in the following table. A resource using an interface 689 description defined in this specification and marked as Observable in 690 its link description SHOULD support these observation parameters. 691 The Change Step parameter can only be supported on resources with an 692 atomic numeric value. 694 These query parameters MUST be treated as resources that are read 695 using GET and set using PUT, and MUST NOT be included in the Observe 696 request. Multiple parameters MAY be set at the same time by 697 including the values in the query string of a PUT. Before being set, 698 these parameters have no default value. 700 +--------------------+------------------+------------------+ 701 | Resource | Parameter | Data Format | 702 +--------------------+------------------+------------------+ 703 | Minimum Period (s) | /{resource}?pmin | xsd:integer (>0) | 704 | Maximum Period (s) | /{resource}?pmax | xsd:integer (>0) | 705 | Change Step | /{resource}?st | xsd:decimal (>0) | 706 | Less Than | /{resource}?lt | xsd:decimal | 707 | Greater Than | /{resource}?gt | xsd:decimal | 708 +--------------------+------------------+------------------+ 710 Minimum Period: When set, the minimum period indicates the minimum 711 time in seconds the server SHOULD wait between sending 712 notifications. In the absence of this parameter, the minimum 713 period is up to the server. 715 Maximum Period: When set, the maximum period indicated the maximum 716 time in seconds the server SHOULD wait between sending 717 notifications (regardless if it has changed). In the absence of 718 this parameter, the maximum period is up to the server. The 719 maximum period MUST be greater than the minimum period parameter 720 (if present). 722 Change Step: When set, the change step indicates how much the value 723 of a resource SHOULD change before sending a new notification 724 (compared to the value of the last notification). This parameter 725 has lower priority than the period parameters, thus even if the 726 change step has been fulfilled, the time since the last 727 notification SHOULD be between pmin and pmax. 729 Less Than: When set, the value of the resource MUST be less than 730 this parameter in order to send a new notification. This 731 parameter has lower priority than the period parameters. 733 Greater Than: When set, the value of the resource MUST be greater 734 than this parameter in order to send a new notification. This 735 parameter has lower priority than the period parameters. 737 The following example shows an Observation request using these query 738 parameters. Here the value of Observe indicates the number of 739 seconds since the observation was made to show the time. 741 Req PUT /s/temp?pmin=10&pmax=60&st=1 742 Res: 2.04 Changed 744 Req: GET Observe /s/temp 745 Res: 2.05 Content Observe:0 (text/plain) 746 23.2 748 Res: 2.05 Content Observe:60 (text/plain) 749 23.0 751 Res: 2.05 Content Observe:80 (text/plain) 752 22.0 754 Res: 2.05 Content Observe:140 (text/plain) 755 21.8 756 The following example shows a request to check the current value of 757 the pmin attribute of the Observable resource from the last example. 759 Req: GET /s/temp?pmin 760 Res: 2.05 Content (text/plain) 761 10 763 5.10. Future Interfaces 765 It is expected that further interface descriptions will be defined in 766 this and other specifications. Potential interfaces to be considered 767 for this specifications include: 769 Collection: This resource would be a container that allows sub- 770 resources to be added or removed. 772 5.11. WADL Description 774 This section defines the formal Web Application Description Langauge 775 (WADL) definition of these CoRE interface descriptions. 777 779 783 784 785 787 789 790 791 792 793 795 796 797 798 799 800 801 802 803 804 805 807 808 809 810 811 812 813 815 816 817 818 820 821 The methods read, 822 observe, update and toggle are applied to each sub- 823 resource of the requested resource that supports it. Mixed 824 sub-resource types can be supported. 825 826 827 828 829 830 832 833 . The methods read, 834 obervableRead, update and toggle are applied to each linked 835 resource of the requested resource that supports it. Mixed 836 linked resource types can be supported. 837 838 839 840 841 842 843 845 846 A modifiable list of 847 links. Each link MUST have the relation type "boundTo". 848 849 850 851 853 854 Retrieve the value of a sensor, an actuator or a parameter. 855 Both HTTP and CoAP support this method. 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 872 873 Observe the value of a sensor, an actuator or a parameter. 874 Only CoAP supports this method since it requires the CoRE 875 Observe mechanism. 876 877 878 879 880 881 882 883 884 885 886 887 889 890 Control the actuator or update a parameter with a new value 891 or command. Both HTTP and CoAP support this method. 892 893 894 895 896 898 899 900 901 903 904 Toggle the values of actuator resources. Both HTTP and CoAP 905 support this method. 906 907 The toggle function is only applicable if the request 908 is empty. 909 910 911 912 914 915 Retrieve the list of Web links associated to a resource. 916 Both HTTP and CoAP support this method. 917 918 This request MUST contain an Accept option with 919 application/link-format when the resource supports 920 other GET methods. 921 922 923 924 925 926 927 928 930 931 Append new Web links to a resource which is a collection 932 of links. Both HTTP and CoAP support this method. 933 934 935 936 937 938 940 941 Clear all Web Links in a resource which is a collection 942 of links. Both HTTP and CoAP support this method. 943 944 945 946 947 949 951 6. Security Considerations 953 An implementation of a client needs to be prepared to deal with 954 responses to a request that differ from what is specified in this 955 document. A server implementing what the client thinks is a resource 956 with one of these interface descriptions could return malformed 957 representations and response codes either by accident or maliciously. 958 A server sending maliciously malformed responses could attempt to 959 take advantage of a poorly implemented client for example to crash 960 the node or perform denial of service. 962 7. IANA Considerations 964 The interface description types defined require registration. 966 The new link relation type "boundto" requires registration. 968 8. Acknowledgments 970 Acknowledgement is given to colleagues from the SENSEI project who 971 were critical in the initial development of the well-known REST 972 interface concept, to members of the IPSO Alliance where further 973 requirements for interface types have been discussed, and to Szymon 974 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 975 provided useful discussion and input to the concepts in this 976 document. 978 9. Changelog 980 Changes from -00 to WG Document -01 982 o Improvements to the Function Set section. 984 Changes from -05 to WG Document -00 986 o Updated the date and version. 988 Changes from -04 to -05 989 o Made the Observation control parameters to be treated as resources 990 rather than Observe query parameters. Added Less Than and Greater 991 Than parameters. 993 Changes from -03 to -04 995 o Draft refresh 997 Changes from -02 to -03 999 o Added Bindings 1001 o Updated all rt= and if= for the new Link Format IANA rules 1003 Changes from -01 to -02 1005 o Defined a Function Set and its guidelines. 1007 o Added the Link List interface. 1009 o Added the Linked Batch interface. 1011 o Improved the WADL interface definition. 1013 o Added a simple profile example. 1015 10. References 1017 10.1. Normative References 1019 [I-D.ietf-core-link-format] 1020 Shelby, Z., "CoRE Link Format", 1021 draft-ietf-core-link-format-14 (work in progress), 1022 June 2012. 1024 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1025 Requirement Levels", BCP 14, RFC 2119, March 1997. 1027 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1029 10.2. Informative References 1031 [I-D.cheshire-dnsext-dns-sd] 1032 Cheshire, S. and M. Krochmal, "DNS-Based Service 1033 Discovery", draft-cheshire-dnsext-dns-sd-11 (work in 1034 progress), December 2011. 1036 [I-D.ietf-core-coap] 1037 Shelby, Z., Hartke, K., and C. Bormann, "Constrained 1038 Application Protocol (CoAP)", draft-ietf-core-coap-18 1039 (work in progress), June 2013. 1041 [I-D.ietf-core-observe] 1042 Hartke, K., "Observing Resources in CoAP", 1043 draft-ietf-core-observe-11 (work in progress), 1044 October 2013. 1046 [I-D.ietf-core-resource-directory] 1047 Shelby, Z., Krco, S., and C. Bormann, "CoRE Resource 1048 Directory", draft-ietf-core-resource-directory-00 (work in 1049 progress), June 2013. 1051 Appendix A. Profile example 1053 The following is a short definition of simple profile. This 1054 simplistic profile is for use in the examples of this document. 1056 +--------------------+-----------+------------+---------+ 1057 | Function Set | Root Path | RT | IF | 1058 +--------------------+-----------+------------+---------+ 1059 | Device Description | /d | simple.dev | core.ll | 1060 | Sensors | /s | simple.sen | core.b | 1061 | Actuators | /a | simple.act | core.b | 1062 +--------------------+-----------+------------+---------+ 1064 List of Function Sets 1066 +-------+----------+----------------+---------+------------+ 1067 | Type | Path | RT | IF | Data Type | 1068 +-------+----------+----------------+---------+------------+ 1069 | Name | /d/name | simple.dev.n | core.p | xsd:string | 1070 | Model | /d/model | simple.dev.mdl | core.rp | xsd:string | 1071 +-------+----------+----------------+---------+------------+ 1073 Device Description Function Set 1075 +-------------+-------------+----------------+--------+-------------+ 1076 | Type | Path | RT | IF | Data Type | 1077 +-------------+-------------+----------------+--------+-------------+ 1078 | Light | /s/light | simple.sen.lt | core.s | xsd:decimal | 1079 | | | | | (lux) | 1080 | Humidity | /s/humidity | simple.sen.hum | core.s | xsd:decimal | 1081 | | | | | (%RH) | 1082 | Temperature | /s/temp | simple.sen.tmp | core.s | xsd:decimal | 1083 | | | | | (degC) | 1084 +-------------+-------------+----------------+--------+-------------+ 1086 Sensors Function Set 1088 +------+------------+----------------+--------+-------------+ 1089 | Type | Path | RT | IF | Data Type | 1090 +------+------------+----------------+--------+-------------+ 1091 | LED | /a/{#}/led | simple.act.led | core.a | xsd:boolean | 1092 +------+------------+----------------+--------+-------------+ 1094 Actuators Function Set 1096 Authors' Addresses 1098 Zach Shelby 1099 ARM 1100 150 Rose Orchard 1101 San Jose 95134 1102 FINLAND 1104 Phone: +1-408-203-9434 1105 Email: zach.shelby@arm.com 1107 Matthieu Vial 1108 Schneider-Electric 1109 Grenoble, 1110 FRANCE 1112 Phone: +33 (0)47657 6522 1113 Email: matthieu.vial@schneider-electric.com