idnits 2.17.1 draft-shelby-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 11, 2012) is 4278 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-10 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-05 == Outdated reference: A later version (-05) exists of draft-shelby-core-resource-directory-03 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 Sensinode 4 Intended status: Standards Track M. Vial 5 Expires: January 12, 2013 Schneider-Electric 6 July 11, 2012 8 CoRE Interfaces 9 draft-shelby-core-interfaces-03 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 January 12, 2013. 42 Copyright Notice 44 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . . . . . . . 16 83 5.10. Future Interfaces . . . . . . . . . . . . . . . . . . . . 17 84 5.11. WADL Description . . . . . . . . . . . . . . . . . . . . . 17 85 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 86 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 87 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 88 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 22 89 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 90 10.1. Normative References . . . . . . . . . . . . . . . . . . . 22 91 10.2. Informative References . . . . . . . . . . . . . . . . . . 22 92 Appendix A. Profile example . . . . . . . . . . . . . . . . . . . 23 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 24 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 specification can organize REST resources 163 to create a new profile. A profile is structured into groups of 164 resource types called Function Sets. A Function Set is similar to a 165 function block in the sense that it consists of input, output and 166 parameter resources and contains internal logic. A Function Set MAY 167 have a subset of mandatory inputs, outputs and parameters to provide 168 minimum interoperability. It MAY also be extended with manufacturer/ 169 user-specific resources. Other specifications defines the list of 170 function sets available within a given profile. A device is composed 171 of one or more Function Set instances. A profile specification MAY 172 specify device profiles with mandatory function sets. 174 3.1. Defining a Function Set 176 In a Function Set, types of resources are defined. Each type 177 includes a human readable name, a path template, a Resource Type for 178 discovery, the Interface Definition and the data type and allowed 179 values. A Function Set definition may also include a field 180 indicating if a sub-resource is mandatory or optional. 182 3.1.1. Path template 184 A Function Set is a container resource under which its sub-resources 185 are organized. The profile defines the path to each resource of a 186 Function Set in a path template. The template can contain either 187 relative paths or absolute paths depending on the profile needs. An 188 absolute Function Set SHOULD be located at its recommended root path 189 on a web server, however it MAY be located under an alternative path 190 if necessary (for example multi-purpose devices, gateways etc.). A 191 relative Function Set can be instantiated as many times as needed on 192 a web server with an arbitrary root path. However some Function Sets 193 (e.g. device description) only make sense as singletons. 195 The path template includes a possible index {#} parameter, and 196 possible fixed path segments. The index {#} allows for multiple 197 instances of this type of resource, and can be any string. The root 198 path and the indexes are the only variable elements in a path 199 template. All other path segments MUST be fixed. 201 3.1.2. Resource Type 203 Each root resource of a Function Set is assigned a Resource Type 204 parameter, therefore making it possible to discover it. Each sub- 205 resource of a Function Set is also assigned a Resource Type 206 parameter. This Resource Type is used for resource discovery and is 207 usually necessary to discover optional resources supported on a 208 specific device. The Resource Type of a Function Set may also be 209 used for service discovery and MAY be exported to DNS-SD 210 [I-D.cheshire-dnsext-dns-sd] for example. 212 The Resource Type parameter defines the value that MUST be included 213 in the rt= field of the CoRE Link Format when describing a link to 214 this resource. The value SHOULD be in the form "namespace.type" for 215 root resources and "namespace.type.subtype" for sub-resources. This 216 naming convention facilitates resource type filtering with the 217 /.well-known/core resource. However a profile MAY allow mixing in 218 foreign namespace references within a Function Set to import external 219 references from other object models (e.g. SenML and UCUM). 221 3.1.3. Interface Description 223 The Interface Description parameter defines the REST interface for 224 that type of resource. Several base interfaces are defined in 225 Section 5 of this document. For a given profile, the Interface 226 Description may be inferred from the Resource Type. In that case the 227 Interface Description MAY be elided from link descriptions of 228 resource types defined in the profile, but SHOULD be included for 229 custom extensions to the profile. 231 The root resource of a Function Set should provide a list of links to 232 its sub-resources in order to offer gradual reveal of resources. The 233 CoRE Link List interface defined in Section 5.1 offers this 234 functionality so a root resource SHOULD support this interface or a 235 derived interface like CoRE Batch (See Section 5.2). 237 3.1.4. Data type 239 The Data Type field defines the type of value (and possible range) 240 that is returned in response to a GET for that resource or accepted 241 with a PUT. The interfaces defined in Section 5 make use of plain 242 text and SenML Media types for the actual format of this data. A 243 profile may restrict the list of supported content types for the CoRE 244 interfaces or define new interfaces with new content types. 246 3.2. Discovery 248 A device conforming to a profile SHOULD make its resources 249 discoverable by providing links to the resources on the path /.well- 250 known/core as defined in [I-D.ietf-core-link-format]. All resources 251 hosted on a device SHOULD be discoverable either with a direct link 252 in /.well-known/core or by following successive links starting from 253 /.well-known/core. 255 The root path of a Function Set instance SHOULD be directly 256 referenced in /.well-known/core in order to offer discovery at the 257 first discovery stage. A device with more than 10 individual 258 resources SHOULD only expose Function Set instances in /.well-known/ 259 core to limit the size of this resource. 261 In addition, a device MAY register its resources to a Resource 262 Directory using the registration interface defined in 263 [I-D.shelby-core-resource-directory] if such a directory is 264 available. 266 3.3. Versioning 268 A profile should track Function Set changes to avoid incompatibility 269 issues. Evolutions in a Function Set SHOULD be backward compatible. 271 4. Bindings 273 In a M2M RESTful environment, endpoints exchange the content of their 274 resources to operate the distributed system. Beforehand, a 275 configuration phase is necessary to determine how the resources of 276 the different endpoints are related to each other. This can be done 277 either automatically using discovery mechanisms or by means of human 278 intervention and a so-called commissioning tool. In this document 279 the abstract relationship between two resources is called a Binding. 280 The configuration phase necessitates the exchange of binding 281 information so a format recognized by all CoRE endpoints is 282 essential. This document defines a format based on the CoRE Link- 283 Format to represent binding information along with the rules to 284 define a binding method which is a specialized relationship between 285 two resources. The purpose of a binding is to synchronize the 286 content between a source resource and a destination resource. The 287 destination resource MAY be a group resource if the authority 288 component of the destination URI contains a group address (either a 289 multicast address or a name that resolves to a multicast address). 290 Since a binding is unidirectional, the binding entry defining a 291 relationship is present only on one endpoint. The binding entry may 292 be located either on the source or the destination endpoint depending 293 on the binding method. The following table gives a summary of the 294 binding methods described in more detail in Section 4.2. 296 +---------+------------+-------------+---------------+ 297 | Name | Identifier | Location | Method | 298 +---------+------------+-------------+---------------+ 299 | Polling | poll | Destination | GET | 300 | Observe | obs | Destination | GET + Observe | 301 | Push | push | Source | PUT | 302 +---------+------------+-------------+---------------+ 304 4.1. Format 306 Since Binding lies in the creation of a link between two resources, 307 Web Linking and the CoRE Link-Format are a natural way to represent 308 binding information. This involves the creation of a new relation 309 type, purposely named "boundto". In a Web link with this relation 310 type, the target URI contains the location of the source resource and 311 the context URI points to the destination resource. The Web link 312 attributes allow a fine-grained control of the type of 313 synchronization exchange along with the conditions that trigger an 314 update. This specification defines the attributes below: 316 +--------------------+-----------+------------------+ 317 | Attribute | Parameter | Value | 318 +--------------------+-----------+------------------+ 319 | Binding method | bind | xsd:string | 320 | Minimum Period (s) | pmin | xsd:integer (>0) | 321 | Maximum Period (s) | pmax | xsd:integer (>0) | 322 | Change Step | st | xsd:decimal (>0) | 323 +--------------------+-----------+------------------+ 325 Bind Method: This is the identifier of a binding method which 326 defines the rules to synchronize the destination resource. This 327 attribute is mandatory. 329 Minimum Period: When present, the minimum period indicates the 330 minimum time to wait (in seconds) before sending a new 331 synchronization message (even if it has changed). In the absence 332 of this parameter, the minimum period is up to the notifier. 334 Maximum Period: When present, the maximum period indicates the 335 maximum time in seconds between two consecutive syncronization 336 messages (regardless if it has changed). In the absence of this 337 parameter, the maximum period is up to the notifier. The maximum 338 period MUST be greater than the minimum period parameter (if 339 present). 341 Change Step: When present, the change step indicates how much the 342 value of a resource SHOULD change before sending a new 343 notification (compared to the value of the last notification). 344 This parameter has lower priority than the period parameters, thus 345 even if the change step has been fulfilled, the time since the 346 last notification SHOULD be between pmin and pmax. 348 4.2. Binding methods 350 A binding method defines the rules to generate the web-transfer 351 exchanges that will effectively send content from the source resource 352 to the destination resource. The description of a binding method 353 must define the following aspects: 355 Identifier: This is value of the "bind" attribute used to identify 356 the method. 358 Location: This information indicates whether the binding entry is 359 stored on the source or on the destination endpoint. 361 REST Method: This is the REST method used in the Request/Response 362 exchanges. 364 Conditions: A binding method definition must state how the condition 365 attributes of the abstract binding definition are actually used in 366 this specialized binding. 368 This specification supports 3 binding methods described below. 370 Polling: The Polling method consists of sending periodic GET 371 requests from the destination endpoint to the source resource and 372 copying the content to the destination resource. The binding 373 entry for this method MUST be stored on the destination endpoint. 374 The destination endpoint MUST ensure that the polling frequency 375 does not exceed the limits defined by the pmin and pmax attributes 376 of the binding entry. The copying process MAY filter out content 377 from the GET requests using value-based conditions (e.g Change 378 Step). 380 Observe: The Observe method relies on the Publish/Subscribe pattern 381 thus an observation relationship is created between the 382 destination endpoint and the source resource. On each 383 notification the content from the source resource is copied to the 384 destination resource. The creation of the observation 385 relationship requires the CoAP Observation mechanism 386 [I-D.ietf-core-observe] hence this method is only permitted when 387 the resources are made available over CoAP. The binding entry for 388 this method MUST be stored on the destination endpoint. The 389 binding conditions are mapped as query string parameters (see 390 Section 5.9). 392 Push: When the Push method is assigned to a binding, the source 393 endpoint sends PUT requests to the destination resource upon 394 change of the source resource. The source endpoint MUST only send 395 a notification request if the binding conditions are met. The 396 binding entry for this method MUST be stored on the source 397 endpoint. 399 4.3. Binding table 401 The binding table is a special resource that gives access to the 402 bindings on a endpoint. A binding table resource MUST support the 403 Binding interface defined in Section 5.8. A profile SHOULD allow 404 only one resource table per endpoint. 406 5. Interface Descriptions 408 This section defines REST interfaces for Link List, Batch, Sensor, 409 Parameter, Actuator and Binding table resources. Variants such as 410 Linked Batch or Read-Only Parameter are also presented. Each type is 411 described along with its Interface Description attribute value and 412 valid methods. These are defined for each interface in the table 413 below. These interfaces can support plain text and/or SenML Media 414 types. 416 The if= column defines the Interface Description (if=) attribute 417 value to be used in the CoRE Link Format for a resource conforming to 418 that interface. When this value appears in the if= attribute of a 419 link, the resource MUST support the corresponding REST interface 420 described in this section. The resource MAY support additional 421 functionality, which is out of scope for this specification. 422 Although these interface descriptions are intended to be used with 423 the CoRE Link Format, they are applicable for use in any REST 424 interface definition. 426 The Methods column defines the methods supported by that interface, 427 which are described in more detail below. 429 +-------------------+----------+------------------------------------+ 430 | Interface | if= | Methods | 431 +-------------------+----------+------------------------------------+ 432 | Link List | core.ll | GET | 433 | Batch | core.b | GET, PUT, POST (where applicable) | 434 | Linked Batch | core.lb | GET, PUT, POST, DELETE (where | 435 | | | applicable) | 436 | Sensor | core.s | GET | 437 | Parameter | core.p | GET, PUT | 438 | Read-only | core.rp | GET | 439 | Parameter | | | 440 | Actuator | core.a | GET, PUT, POST | 441 | Binding | core.bnd | GET, POST, DELETE | 442 +-------------------+----------+------------------------------------+ 444 The following is an example of links in the CoRE Link Format using 445 these interface descriptions. The resource hierarchy is based on a 446 simple profile defined in Appendix A. These links are used in the 447 subsequent examples below. 449 Req: GET /.well-known/core 450 Res: 2.05 Content (application/link-format) 451 ;rt="simple.sen";if="core.b", 452 ;rt="simple.sen.lt";if="core.s", 453 ;rt="simple.sen.tmp";if="core.s";obs, 454 ;rt="simple.sen.hum";if="core.s", 455 ;rt="simple.act";if="core.b", 456 ;rt="simple.act.led";if="core.a", 457 ;rt="simple.act.led";if="core.a", 458 ;rt="simple.dev";if="core.ll", 459 ;if="core.lb", 461 5.1. Link List 463 The Link List interface is used to retrieve (GET) a list of resources 464 on a web server. The GET request SHOULD contain an Accept option 465 with the application/link-format content type, however if the 466 resource does not support any other form of GET methods the Accept 467 option MAY be elided. The Accept option SHOULD only include the 468 application/link-format content type. The request returns a list of 469 URI references with absolute paths to the resources as defined in 470 CoRE Link Format. This interface is typically used with a parent 471 resource to enumerate sub-resources but may be used to reference any 472 resource on a web server. 474 Link List is the base interface to provide gradual reveal of 475 resources on a CoRE web server, hence the root resource of a Function 476 Set SHOULD implement this interface or an extension of this 477 interface. 479 The following example interacts with a Link List /d containing 480 Parameter sub-resources /d/name, /d/model. 482 Req: GET /d (Accept:application/link-format) 483 Res: 2.05 Content (application/link-format) 484 ;rt="simple.dev.n";if="core.p", 485 ;rt="simple.dev.mdl";if="core.rp" 487 5.2. Batch 489 The Batch interface is used to manipulate a collection of sub- 490 resources at the same time. The Batch interface type supports the 491 same methods as its sub-resources, and can be used to read (GET), set 492 (PUT) or toggle (POST) the values of those sub-resource with a single 493 resource representation. The sub-resources of a Batch MAY be 494 heterogeneous, a method used on the Batch only applies to sub- 495 resources that support it. For example Sensor interfaces do not 496 support PUT, and thus a PUT request to a Sensor member of that Batch 497 would be ignored. A batch requires the use of SenML Media types in 498 order to support multiple sub-resources. 500 In addition, The Batch interface is an extension of the Link List 501 interface and in consequence MUST support the same methods. 503 The following example interacts with a Batch /s with Sensor sub- 504 resources /s/light, /s/temp and /s/humidity. 506 Req: GET /s 507 Res: 2.05 Content (application/senml+json) 508 {"e":[ 509 { "n": "light", "v": 123, "u": "lx" }, 510 { "n": "temp", "v": 27.2, "u": "degC" }, 511 { "n": "humidity", "v": 80, "u": "%RH" }], 512 } 514 5.3. Linked Batch 516 The Linked Batch interface is an extension of the Batch interface. 517 Contrary to the basic Batch which is a collection statically defined 518 by the web server, a Linked Batch is dynamically controlled by a web 519 client. A Linked Batch resource has no sub-resources. Instead the 520 resources forming the batch are referenced using Web Linking 521 [RFC5988] and the CoRE Link Format [I-D.ietf-core-link-format]. A 522 request with a POST method and a content type of application/ 523 link-format simply appends new resources to the collection. The 524 links in the payload MUST reference a resource on the web server with 525 an absolute path. A DELETE request empties the current collection of 526 links. All other requests available for a basic Batch are still 527 valid for a Linked Batch. 529 The following example interacts with a Linked Batch /l and creates a 530 collection containing /s/light, /s/temp and /s/humidity in 2 steps. 532 Req: POST /l (Content-type: application/link-format) 533 , 534 Res: 2.04 Changed 536 Req: GET /l 537 Res: 2.05 Content (application/senml+json) 538 {"e":[ 539 { "n": "/s/light", "v": 123, "u": "lx" }, 540 { "n": "/s/temp", "v": 27.2, "u": "degC" }, 541 } 543 Req: POST /l (Content-type: application/link-format) 544 545 Res: 2.04 Changed 547 Req: GET /l (Accept: application/link-format) 548 Res: 2.05 Content (application/link-format) 549 ,, 551 Req: GET /l 552 Res: 2.05 Content (application/senml+json) 553 {"e":[ 554 { "n": "/s/light", "v": 123, "u": "lx" }, 555 { "n": "/s/temp", "v": 27.2, "u": "degC" }, 556 { "n": "/s/humidity", "v": 80, "u": "%RH" }], 557 } 559 Req: DELETE /l 560 Res: 2.04 Changed 562 5.4. Sensor 564 The Sensor interface allows the value of a sensor resource to be read 565 (GET). The Media type of the resource can be either plain text or 566 SenML. Plain text MAY be used for a single measurement that does not 567 require meta-data. For a measurement with meta-data such as a unit 568 or time stamp, SenML SHOULD be used. A resource with this interface 569 MAY use SenML to return multiple measurements in the same 570 representation, for example a list of recent measurements. 572 The following are examples of Sensor interface requests in both text/ 573 plain and application/senml+json. 575 Req: GET /s/humidity (Accept: text/plain) 576 Res: 2.05 Content (text/plain) 577 80 579 Req: GET /s/humidity (Accept: application/senml+json) 580 Res: 2.05 Content (application/senml+json) 581 {"e":[ 582 { "n": "humidity", "v": 80, "u": "%RH" }], 583 } 585 5.5. Parameter 587 The Parameter interface allows configurable parameters and other 588 information to be modeled as a resource. The value of the parameter 589 can be read (GET) or set (PUT). Plain text or SenML Media types MAY 590 be returned from this type of interface. 592 The following example shows request for reading and setting a 593 parameter. 595 Req: GET /d/name 596 Res: 2.05 Content (text/plain) 597 node5 599 Req: PUT /d/name (text/plain) 600 outdoor 601 Res: 2.04 Changed 603 5.6. Read-only Parameter 605 The Read-only Parameter interface allows configuration parameters to 606 be read (GET) but not set. Plain text or SenML Media types MAY be 607 returned from this type of interface. 609 The following example shows request for reading such a parameter. 611 Req: GET /d/model 612 Res: 2.05 Content (text/plain) 613 SuperNode200 615 5.7. Actuator 617 The Actuator interface is used by resources that model different 618 kinds of actuators (changing its value has an effect on its 619 environment). Examples of actuators include for example LEDs, 620 relays, motor controllers and light dimmers. The current value of 621 the actuator can be read (GET) or a new actuator value set (PUT). In 622 addition, this interface defines the use of POST (with no body) to 623 toggle an actuator between its possible values. Plain text or SenML 624 Media types MAY be returned from this type of interface. A resource 625 with this interface MAY use SenML to include multiple measurements in 626 the same representation, for example a list of recent actuator values 627 or a list of values to set. 629 The following example shows requests for reading, setting and 630 toggling an actuator (turning on a led). 632 Req: GET /a/1/led 633 Res: 2.05 Content (text/plain) 634 0 636 Req: PUT /a/1/led (text/plain) 637 1 638 Res: 2.04 Changed 640 Req: POST /a/1/led (text/plain) 641 Res: 2.04 Changed 643 Req: GET /a/1/led 644 Res: 2.05 Content (text/plain) 645 0 647 5.8. Binding 649 The Binding interface is used to manipulate a binding table. A 650 request with a POST method and a content type of application/ 651 link-format simply appends new bindings to the table. All links in 652 the payload MUST have a relation type "boundTo". A GET request 653 simply returns the current state of a binding table whereas a DELETE 654 request empties the table. 656 The following example shows requests for adding, retrieving and 657 deleting bindings in a binding table. 659 Req: POST /bnd (Content-type: application/link-format) 660 ; 661 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 662 Res: 2.04 Changed 664 Req: GET /bnd 665 Res: 2.05 Content (application/senml+json) 666 ; 667 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 669 Req: DELETE /bnd 670 Res: 2.04 Changed 672 5.9. Resource Observation 674 When resource interfaces following this specification are made 675 available over CoAP, the CoAP Observation mechanism 676 [I-D.ietf-core-observe] MAY be used to observe any changes in a 677 resource, and receive asynchronous notifications as a result. In 678 addition, a set of query string parameters are defined here to allow 679 a client to request how often a client is interested in receiving 680 notifications and how much a resource should change for the new 681 representation to be interesting. These query parameters are 682 described in the following table. A resource using an interface 683 description defined in this specification and marked as Observable in 684 its link description SHOULD support these observation parameters. 685 The Change Step parameter can only be supported on resources with an 686 atomic numeric value. 688 +--------------------+-----------+------------------+ 689 | Query | Parameter | Value | 690 +--------------------+-----------+------------------+ 691 | Minimum Period (s) | pmin | xsd:integer (>0) | 692 | Maximum Period (s) | pmax | xsd:integer (>0) | 693 | Change Step | st | xsd:decimal (>0) | 694 +--------------------+-----------+------------------+ 696 Minimum Period: When present, the minimum period indicates the 697 minimum time in seconds the server SHOULD wait between sending 698 notifications. In the absence of this parameter, the minimum 699 period is up to the server. 701 Maximum Period: When present, the maximum period indicated the 702 maximum time in seconds the server SHOULD wait between sending 703 notifications (regardless if it has changed). In the absence of 704 this parameter, the maximum period is up to the server. The 705 maximum period MUST be greater than the minimum period parameter 706 (if present). 708 Change Step: When present, the change step indicates how much the 709 value of a resource SHOULD change before sending a new 710 notification (compared to the value of the last notification). 711 This parameter has lower priority than the period parameters, thus 712 even if the change step has been fulfilled, the time since the 713 last notification SHOULD be between pmin and pmax. 715 The following example shows an Observation request using these query 716 parameters. Here the value of Observe indicates the number of 717 seconds since the observation was made to show the time. 719 Req: GET Observe /s/temp?pmin=10&pmax=60&st=1 720 Res: 2.05 Content Observe:0 (text/plain) 721 23.2 723 Res: 2.05 Content Observe:60 (text/plain) 724 23.0 726 Res: 2.05 Content Observe:80 (text/plain) 727 22.0 729 Res: 2.05 Content Observe:140 (text/plain) 730 21.8 732 5.10. Future Interfaces 734 It is expected that further interface descriptions will be defined in 735 this and other specifications. Potential interfaces to be considered 736 for this specifications include: 738 Collection: This resource would be a container that allows sub- 739 resources to be added or removed. 741 5.11. WADL Description 743 This section defines the formal Web Application Description Langauge 744 (WADL) definition of these CoRE interface descriptions. 746 748 752 753 754 756 758 759 760 761 762 764 765 766 767 768 769 771 772 773 774 775 777 778 779 780 781 782 783 785 786 787 788 790 791 The methods read, 792 observe, update and toggle are applied to each sub- 793 resource of the requested resource that supports it. Mixed 794 sub-resource types can be supported. 795 796 797 798 799 801 803 804 . The methods read, 805 obervableRead, update and toggle are applied to each linked 806 resource of the requested resource that supports it. Mixed 807 linked resource types can be supported. 808 809 810 811 812 813 814 816 817 A modifiable list of links. 818 Each link MUST have the relation type "boundTo". 819 820 821 822 824 825 Retrieve the value of a sensor, an actuator or a parameter. 826 Both HTTP and CoAP support this method. 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 843 844 Observe the value of a sensor, an actuator or a parameter. 845 Only CoAP supports this method since it requires the CoRE 846 Observe mechanism. 847 848 849 850 851 852 853 854 855 856 857 858 860 861 Control the actuator or update a parameter with a new value 862 or command. Both HTTP and CoAP support this method. 863 864 865 866 867 868 869 870 871 873 874 Toggle the values of actuator resources. Both HTTP and CoAP 875 support this method. 876 877 The toggle function is only applicable if the request 878 is empty. 879 880 881 882 884 885 Retrieve the list of Web links associated to a resource. 886 Both HTTP and CoAP support this method. 887 888 This request MUST contain an Accept option with 889 application/link-format when the resource supports 890 other GET methods. 891 892 893 894 895 896 898 899 901 902 Append new Web links to a resource which is a collection 903 of links. Both HTTP and CoAP support this method. 904 905 906 907 908 909 911 912 Clear all Web Links in a resource which is a collection 913 of links. Both HTTP and CoAP support this method. 914 915 916 917 918 920 922 6. Security Considerations 924 An implementation of a client needs to be prepared to deal with 925 responses to a request that differ from what is specified in this 926 document. A server implementing what the client thinks is a resource 927 with one of these interface descriptions could return malformed 928 representations and response codes either by accident or maliciously. 929 A server sending maliciously malformed responses could attempt to 930 take advantage of a poorly implemented client for example to crash 931 the node or perform denial of service. 933 7. IANA Considerations 935 The interface description types defined require registration. 937 The new link relation type "boundto" requires registration. 939 8. Acknowledgments 941 Acknowledgement is given to colleagues from the SENSEI project who 942 were critical in the initial development of the well-known REST 943 interface concept, to members of the IPSO Alliance where further 944 requirements for interface types have been discussed, and to Szymon 945 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 946 provided useful discussion and input to the concepts in this 947 document. 949 9. Changelog 951 Changes from -02 to -03 953 o Added Bindings 955 o Updated all rt= and if= for the new Link Format IANA rules 957 Changes from -01 to -02 959 o Defined a Function Set and its guidelines. 961 o Added the Link List interface. 963 o Added the Linked Batch interface. 965 o Improved the WADL interface definition. 967 o Added a simple profile example. 969 10. References 971 10.1. Normative References 973 [I-D.ietf-core-link-format] 974 Shelby, Z., "CoRE Link Format", 975 draft-ietf-core-link-format-14 (work in progress), 976 June 2012. 978 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 979 Requirement Levels", BCP 14, RFC 2119, March 1997. 981 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 983 10.2. Informative References 985 [I-D.cheshire-dnsext-dns-sd] 986 Cheshire, S. and M. Krochmal, "DNS-Based Service 987 Discovery", draft-cheshire-dnsext-dns-sd-11 (work in 988 progress), December 2011. 990 [I-D.ietf-core-coap] 991 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 992 "Constrained Application Protocol (CoAP)", 993 draft-ietf-core-coap-10 (work in progress), June 2012. 995 [I-D.ietf-core-observe] 996 Hartke, K., "Observing Resources in CoAP", 997 draft-ietf-core-observe-05 (work in progress), March 2012. 999 [I-D.shelby-core-resource-directory] 1000 Shelby, Z. and S. Krco, "CoRE Resource Directory", 1001 draft-shelby-core-resource-directory-03 (work in 1002 progress), May 2012. 1004 Appendix A. Profile example 1006 The following is a short definition of simple profile. This 1007 simplistic profile is for use in the examples of this document. 1009 +--------------------+-----------+------------+---------+ 1010 | Function Set | Root Path | RT | IF | 1011 +--------------------+-----------+------------+---------+ 1012 | Device Description | /d | simple.dev | core.ll | 1013 | Sensors | /s | simple.sen | core.b | 1014 | Actuators | /a | simple.act | core.b | 1015 +--------------------+-----------+------------+---------+ 1017 List of Function Sets 1019 +-------+----------+----------------+---------+------------+ 1020 | Type | Path | RT | IF | Data Type | 1021 +-------+----------+----------------+---------+------------+ 1022 | Name | /d/name | simple.dev.n | core.p | xsd:string | 1023 | Model | /d/model | simple.dev.mdl | core.rp | xsd:string | 1024 +-------+----------+----------------+---------+------------+ 1026 Device Description Function Set 1028 +-------------+-------------+----------------+--------+-------------+ 1029 | Type | Path | RT | IF | Data Type | 1030 +-------------+-------------+----------------+--------+-------------+ 1031 | Light | /s/light | simple.sen.lt | core.s | xsd:decimal | 1032 | | | | | (lux) | 1033 | Humidity | /s/humidity | simple.sen.hum | core.s | xsd:decimal | 1034 | | | | | (%RH) | 1035 | Temperature | /s/temp | simple.sen.tmp | core.s | xsd:decimal | 1036 | | | | | (degC) | 1037 +-------------+-------------+----------------+--------+-------------+ 1039 Sensors Function Set 1041 +------+------------+----------------+--------+-------------+ 1042 | Type | Path | RT | IF | Data Type | 1043 +------+------------+----------------+--------+-------------+ 1044 | LED | /a/{#}/led | simple.act.led | core.a | xsd:boolean | 1045 +------+------------+----------------+--------+-------------+ 1047 Actuators Function Set 1049 Authors' Addresses 1051 Zach Shelby 1052 Sensinode 1053 Kidekuja 2 1054 Vuokatti 88600 1055 FINLAND 1057 Phone: +358407796297 1058 Email: zach@sensinode.com 1060 Matthieu Vial 1061 Schneider-Electric 1062 Grenoble, 1063 FRANCE 1065 Phone: +33 (0)47657 6522 1066 Email: matthieu.vial@schneider-electric.com