idnits 2.17.1 draft-ietf-core-interfaces-02.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 (November 9, 2014) is 3455 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'REF' is mentioned on line 175, but not defined ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-15 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-01 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: May 13, 2015 Schneider-Electric 6 November 9, 2014 8 CoRE Interfaces 9 draft-ietf-core-interfaces-02 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 May 13, 2015. 42 Copyright Notice 44 Copyright (c) 2014 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 Attributes . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 21 89 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 90 10.1. Normative References . . . . . . . . . . . . . . . . . . . 22 91 10.2. Informative References . . . . . . . . . . . . . . . . . . 23 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 [RFC6690] and can be 111 used by CoAP [RFC7252] or HTTP servers. The CoRE Link Format defines 112 an attribute that can be used to describe the REST interface of a 113 resource, and may include a link to a description document. This 114 memo describes how other specifications can combine resources with a 115 well-known interface to create new CoRE RESTful profiles. A CoRE 116 profile is based on the concept of Function Set, which is a group of 117 REST resources providing a service in a distributed system. In 118 addition, the notion of Binding is introduced in order to create a 119 synchronization link between two resources. This document also 120 defines well-known interface descriptions for Batch, Sensor, 121 Parameter and Actuator types to compose new Function Sets or for 122 standalone use in a constrained web server. A short reference is 123 provided for each type that can be efficiently included in the 124 interface description (if=) attribute of the CoRE Link Format. 126 2. Terminology 128 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 129 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 130 document are to be interpreted as described in [RFC2119]. 132 This specification requires readers to be familiar with all the terms 133 and concepts that are discussed in [RFC5988] and [RFC6690]. This 134 specification makes use of the following additional terminology: 136 Function Set: A group of well-known REST resources that provides a 137 particular service. 139 Profile: A group of well-known Function Sets defined by a 140 specification. 142 Device: An IP smart object running a web server that hosts a group 143 of Function Set instances from a profile. 145 Service Discovery: The process making it possible for a web client 146 to automatically detect devices and Function Sets offered by these 147 devices on a CoRE network. 149 Resource Discovery: The process allowing a web client to identify 150 resources being hosted on a web server. 152 Gradual Reveal: A REST design where resources are discovered 153 progressively using Web Linking. 155 Binding: A unidirectional logical link between a source resource and 156 a destination resource. 158 3. Function Set 160 This section defines how a set of REST resources can be created 161 called a function set. A Function Set is similar to a function block 162 in the sense that it consists of input, output and parameter 163 resources and contains internal logic. A Function Set can have a 164 subset of mandatory inputs, outputs and parameters to provide minimum 165 interoperability. It can also be extended with manufacturer/ 166 user-specific resources. A device is composed of one or more 167 Function Set instances. 169 An example of function sets can be found from the CoRE Resource 170 Directory specification that defines REST interfaces for 171 registration, group and lookup [I-D.ietf-core-resource-directory]. 172 The OMA Lightweight M2M standard [REF] also defines a function set 173 structure called an Objects that use integer path, instance and 174 resource URI segments. OMA Objects can be defined and then 175 registered with an OMA maintained registry [REF]. This section is 176 simply meant as a guideline for the definition of other such REST 177 interfaces, either custom or part of other specifications. 179 3.1. Defining a Function Set 181 In a Function Set, types of resources are defined. Each type 182 includes a human readable name, a path template, a Resource Type for 183 discovery, the Interface Definition and the data type and allowed 184 values. A Function Set definition may also include a field 185 indicating if a sub-resource is mandatory or optional. 187 3.1.1. Path template 189 A Function Set is a container resource under which its sub-resources 190 are organized. The profile defines the path to each resource of a 191 Function Set in a path template. The template can contain either 192 relative paths or absolute paths depending on the profile needs. An 193 absolute Function Set should be located at its recommended root path 194 on a web server, however it can be located under an alternative path 195 if necessary (for example multi-purpose devices, gateways etc.). A 196 relative Function Set can be instantiated as many times as needed on 197 a web server with an arbitrary root path. However some Function Sets 198 (e.g. device description) only make sense as singletons. 200 The path template includes a possible index {#} parameter, and 201 possible fixed path segments. The index {#} allows for multiple 202 instances of this type of resource, and can be any string. The root 203 path and the indexes are the only variable elements in a path 204 template. All other path segments should be fixed. 206 3.1.2. Resource Type 208 Each root resource of a Function Set is assigned a Resource Type 209 parameter, therefore making it possible to discover it. Each sub- 210 resource of a Function Set is also assigned a Resource Type 211 parameter. This Resource Type is used for resource discovery and is 212 usually necessary to discover optional resources supported on a 213 specific device. The Resource Type of a Function Set may also be 214 used for service discovery and can be exported to DNS-SD [RFC6763] 215 for example. 217 The Resource Type parameter defines the value that should be included 218 in the rt= field of the CoRE Link Format when describing a link to 219 this resource. The value SHOULD be in the form "namespace.type" for 220 root resources and "namespace.type.subtype" for sub-resources. This 221 naming convention facilitates resource type filtering with the 222 /.well-known/core resource. However a profile could allow mixing in 223 foreign namespace references within a Function Set to import external 224 references from other object models (e.g. SenML and UCUM). 226 3.1.3. Interface Description 228 The Interface Description parameter defines the REST interface for 229 that type of resource. Several base interfaces are defined in 230 Section 5 of this document. For a given profile, the Interface 231 Description may be inferred from the Resource Type. In that case the 232 Interface Description MAY be elided from link descriptions of 233 resource types defined in the profile, but should be included for 234 custom extensions to the profile. 236 The root resource of a Function Set should provide a list of links to 237 its sub-resources in order to offer gradual reveal of resources. The 238 CoRE Link List interface defined in Section 5.1 offers this 239 functionality so a root resource should support this interface or a 240 derived interface like CoRE Batch (See Section 5.2). 242 3.1.4. Data type 244 The Data Type field defines the type of value (and possible range) 245 that is returned in response to a GET for that resource or accepted 246 with a PUT. The interfaces defined in Section 5 make use of plain 247 text and SenML Media types for the actual format of this data. A 248 profile may restrict the list of supported content types for the CoRE 249 interfaces or define new interfaces with new content types. 251 3.2. Discovery 253 A device conforming to a profile SHOULD make its resources 254 discoverable by providing links to the resources on the path /.well- 255 known/core as defined in [RFC6690]. All resources hosted on a device 256 SHOULD be discoverable either with a direct link in /.well-known/core 257 or by following successive links starting from /.well-known/core. 259 The root path of a Function Set instance SHOULD be directly 260 referenced in /.well-known/core in order to offer discovery at the 261 first discovery stage. A device with more than 10 individual 262 resources SHOULD only expose Function Set instances in /.well-known/ 263 core to limit the size of this resource. 265 In addition, a device MAY register its resources to a Resource 266 Directory using the registration interface defined in 267 [I-D.ietf-core-resource-directory] if such a directory is available. 269 3.3. Versioning 271 A profile should track Function Set changes to avoid incompatibility 272 issues. Evolutions in a Function Set SHOULD be backward compatible. 274 4. Bindings 276 In a M2M RESTful environment, endpoints exchange the content of their 277 resources to operate the distributed system. Beforehand, a 278 configuration phase is necessary to determine how the resources of 279 the different endpoints are related to each other. This can be done 280 either automatically using discovery mechanisms or by means of human 281 intervention and a so-called commissioning tool. In this document 282 the abstract relationship between two resources is called a Binding. 284 The configuration phase necessitates the exchange of binding 285 information so a format recognized by all CoRE endpoints is 286 essential. This document defines a format based on the CoRE Link- 287 Format to represent binding information along with the rules to 288 define a binding method which is a specialized relationship between 289 two resources. The purpose of a binding is to synchronize the 290 content between a source resource and a destination resource. The 291 destination resource MAY be a group resource if the authority 292 component of the destination URI contains a group address (either a 293 multicast address or a name that resolves to a multicast address). 294 Since a binding is unidirectional, the binding entry defining a 295 relationship is present only on one endpoint. The binding entry may 296 be located either on the source or the destination endpoint depending 297 on the binding method. The following table gives a summary of the 298 binding methods described in more detail in Section 4.2. 300 +---------+------------+-------------+---------------+ 301 | Name | Identifier | Location | Method | 302 +---------+------------+-------------+---------------+ 303 | Polling | poll | Destination | GET | 304 | Observe | obs | Destination | GET + Observe | 305 | Push | push | Source | PUT | 306 +---------+------------+-------------+---------------+ 308 4.1. Format 310 Since Binding lies in the creation of a link between two resources, 311 Web Linking and the CoRE Link-Format are a natural way to represent 312 binding information. This involves the creation of a new relation 313 type, purposely named "boundto". In a Web link with this relation 314 type, the target URI contains the location of the source resource and 315 the context URI points to the destination resource. The Web link 316 attributes allow a fine-grained control of the type of 317 synchronization exchange along with the conditions that trigger an 318 update. This specification defines the attributes below: 320 +--------------------+-----------+------------------+ 321 | Attribute | Parameter | Value | 322 +--------------------+-----------+------------------+ 323 | Binding method | bind | xsd:string | 324 | Minimum Period (s) | pmin | xsd:integer (>0) | 325 | Maximum Period (s) | pmax | xsd:integer (>0) | 326 | Change Step | st | xsd:decimal (>0) | 327 +--------------------+-----------+------------------+ 329 Bind Method: This is the identifier of a binding method which 330 defines the rules to synchronize the destination resource. This 331 attribute is mandatory. 333 Minimum Period: When present, the minimum period indicates the 334 minimum time to wait (in seconds) before sending a new 335 synchronization message (even if it has changed). In the absence 336 of this parameter, the minimum period is up to the notifier. 338 Maximum Period: When present, the maximum period indicates the 339 maximum time in seconds between two consecutive syncronization 340 messages (regardless if it has changed). In the absence of this 341 parameter, the maximum period is up to the notifier. The maximum 342 period MUST be greater than the minimum period parameter (if 343 present). 345 Change Step: When present, the change step indicates how much the 346 value of a resource SHOULD change before sending a new 347 notification (compared to the value of the last notification). 348 This parameter has lower priority than the period parameters, thus 349 even if the change step has been fulfilled, the time since the 350 last notification SHOULD be between pmin and pmax. 352 4.2. Binding methods 354 A binding method defines the rules to generate the web-transfer 355 exchanges that will effectively send content from the source resource 356 to the destination resource. The description of a binding method 357 must define the following aspects: 359 Identifier: This is value of the "bind" attribute used to identify 360 the method. 362 Location: This information indicates whether the binding entry is 363 stored on the source or on the destination endpoint. 365 REST Method: This is the REST method used in the Request/Response 366 exchanges. 368 Conditions: A binding method definition must state how the condition 369 attributes of the abstract binding definition are actually used in 370 this specialized binding. 372 This specification supports 3 binding methods described below. 374 Polling: The Polling method consists of sending periodic GET 375 requests from the destination endpoint to the source resource and 376 copying the content to the destination resource. The binding 377 entry for this method MUST be stored on the destination endpoint. 378 The destination endpoint MUST ensure that the polling frequency 379 does not exceed the limits defined by the pmin and pmax attributes 380 of the binding entry. The copying process MAY filter out content 381 from the GET requests using value-based conditions (e.g Change 382 Step). 384 Observe: The Observe method relies on the Publish/Subscribe pattern 385 thus an observation relationship is created between the 386 destination endpoint and the source resource. On each 387 notification the content from the source resource is copied to the 388 destination resource. The creation of the observation 389 relationship requires the CoAP Observation mechanism 390 [I-D.ietf-core-observe] hence this method is only permitted when 391 the resources are made available over CoAP. The binding entry for 392 this method MUST be stored on the destination endpoint. The 393 binding conditions are mapped as query string parameters (see 394 Section 5.9). 396 Push: When the Push method is assigned to a binding, the source 397 endpoint sends PUT requests to the destination resource upon 398 change of the source resource. The source endpoint MUST only send 399 a notification request if the binding conditions are met. The 400 binding entry for this method MUST be stored on the source 401 endpoint. 403 4.3. Binding table 405 The binding table is a special resource that gives access to the 406 bindings on a endpoint. A binding table resource MUST support the 407 Binding interface defined in Section 5.8. A profile SHOULD allow 408 only one resource table per endpoint. 410 5. Interface Descriptions 412 This section defines REST interfaces for Link List, Batch, Sensor, 413 Parameter, Actuator and Binding table resources. Variants such as 414 Linked Batch or Read-Only Parameter are also presented. Each type is 415 described along with its Interface Description attribute value and 416 valid methods. These are defined for each interface in the table 417 below. These interfaces can support plain text and/or SenML Media 418 types. 420 The if= column defines the Interface Description (if=) attribute 421 value to be used in the CoRE Link Format for a resource conforming to 422 that interface. When this value appears in the if= attribute of a 423 link, the resource MUST support the corresponding REST interface 424 described in this section. The resource MAY support additional 425 functionality, which is out of scope for this specification. 426 Although these interface descriptions are intended to be used with 427 the CoRE Link Format, they are applicable for use in any REST 428 interface definition. 430 The Methods column defines the methods supported by that interface, 431 which are described in more detail below. 433 +-------------------+----------+------------------------------------+ 434 | Interface | if= | Methods | 435 +-------------------+----------+------------------------------------+ 436 | Link List | core.ll | GET | 437 | Batch | core.b | GET, PUT, POST (where applicable) | 438 | Linked Batch | core.lb | GET, PUT, POST, DELETE (where | 439 | | | applicable) | 440 | Sensor | core.s | GET | 441 | Parameter | core.p | GET, PUT | 442 | Read-only | core.rp | GET | 443 | Parameter | | | 444 | Actuator | core.a | GET, PUT, POST | 445 | Binding | core.bnd | GET, POST, DELETE | 446 +-------------------+----------+------------------------------------+ 448 The following is an example of links in the CoRE Link Format using 449 these interface descriptions. The resource hierarchy is based on a 450 simple profile defined in Appendix A. These links are used in the 451 subsequent examples below. 453 Req: GET /.well-known/core 454 Res: 2.05 Content (application/link-format) 455 ;rt="simple.sen";if="core.b", 456 ;rt="simple.sen.lt";if="core.s", 457 ;rt="simple.sen.tmp";if="core.s";obs, 458 ;rt="simple.sen.hum";if="core.s", 459 ;rt="simple.act";if="core.b", 460 ;rt="simple.act.led";if="core.a", 461 ;rt="simple.act.led";if="core.a", 462 ;rt="simple.dev";if="core.ll", 463 ;if="core.lb", 465 5.1. Link List 467 The Link List interface is used to retrieve (GET) a list of resources 468 on a web server. The GET request SHOULD contain an Accept option 469 with the application/link-format content type, however if the 470 resource does not support any other form of GET methods the Accept 471 option MAY be elided. The Accept option SHOULD only include the 472 application/link-format content type. The request returns a list of 473 URI references with absolute paths to the resources as defined in 474 CoRE Link Format. This interface is typically used with a parent 475 resource to enumerate sub-resources but may be used to reference any 476 resource on a web server. 478 Link List is the base interface to provide gradual reveal of 479 resources on a CoRE web server, hence the root resource of a Function 480 Set SHOULD implement this interface or an extension of this 481 interface. 483 The following example interacts with a Link List /d containing 484 Parameter sub-resources /d/name, /d/model. 486 Req: GET /d (Accept:application/link-format) 487 Res: 2.05 Content (application/link-format) 488 ;rt="simple.dev.n";if="core.p", 489 ;rt="simple.dev.mdl";if="core.rp" 491 5.2. Batch 493 The Batch interface is used to manipulate a collection of sub- 494 resources at the same time. The Batch interface type supports the 495 same methods as its sub-resources, and can be used to read (GET), set 496 (PUT) or toggle (POST) the values of those sub-resource with a single 497 resource representation. The sub-resources of a Batch MAY be 498 heterogeneous, a method used on the Batch only applies to sub- 499 resources that support it. For example Sensor interfaces do not 500 support PUT, and thus a PUT request to a Sensor member of that Batch 501 would be ignored. A batch requires the use of SenML Media types in 502 order to support multiple sub-resources. 504 In addition, The Batch interface is an extension of the Link List 505 interface and in consequence MUST support the same methods. 507 The following example interacts with a Batch /s with Sensor sub- 508 resources /s/light, /s/temp and /s/humidity. 510 Req: GET /s 511 Res: 2.05 Content (application/senml+json) 512 {"e":[ 513 { "n": "light", "v": 123, "u": "lx" }, 514 { "n": "temp", "v": 27.2, "u": "degC" }, 515 { "n": "humidity", "v": 80, "u": "%RH" }], 516 } 518 5.3. Linked Batch 520 The Linked Batch interface is an extension of the Batch interface. 521 Contrary to the basic Batch which is a collection statically defined 522 by the web server, a Linked Batch is dynamically controlled by a web 523 client. A Linked Batch resource has no sub-resources. Instead the 524 resources forming the batch are referenced using Web Linking 525 [RFC5988] and the CoRE Link Format [RFC6690]. A request with a POST 526 method and a content type of application/link-format simply appends 527 new resources to the collection. The links in the payload MUST 528 reference a resource on the web server with an absolute path. A 529 DELETE request empties the current collection of links. All other 530 requests available for a basic Batch are still valid for a Linked 531 Batch. 533 The following example interacts with a Linked Batch /l and creates a 534 collection containing /s/light, /s/temp and /s/humidity in 2 steps. 536 Req: POST /l (Content-type: application/link-format) 537 , 538 Res: 2.04 Changed 540 Req: GET /l 541 Res: 2.05 Content (application/senml+json) 542 {"e":[ 543 { "n": "/s/light", "v": 123, "u": "lx" }, 544 { "n": "/s/temp", "v": 27.2, "u": "degC" }, 545 } 547 Req: POST /l (Content-type: application/link-format) 548 549 Res: 2.04 Changed 551 Req: GET /l (Accept: application/link-format) 552 Res: 2.05 Content (application/link-format) 553 ,, 555 Req: GET /l 556 Res: 2.05 Content (application/senml+json) 557 {"e":[ 558 { "n": "/s/light", "v": 123, "u": "lx" }, 559 { "n": "/s/temp", "v": 27.2, "u": "degC" }, 560 { "n": "/s/humidity", "v": 80, "u": "%RH" }], 561 } 563 Req: DELETE /l 564 Res: 2.04 Changed 566 5.4. Sensor 568 The Sensor interface allows the value of a sensor resource to be read 569 (GET). The Media type of the resource can be either plain text or 570 SenML. Plain text MAY be used for a single measurement that does not 571 require meta-data. For a measurement with meta-data such as a unit 572 or time stamp, SenML SHOULD be used. A resource with this interface 573 MAY use SenML to return multiple measurements in the same 574 representation, for example a list of recent measurements. 576 The following are examples of Sensor interface requests in both text/ 577 plain and application/senml+json. 579 Req: GET /s/humidity (Accept: text/plain) 580 Res: 2.05 Content (text/plain) 581 80 583 Req: GET /s/humidity (Accept: application/senml+json) 584 Res: 2.05 Content (application/senml+json) 585 {"e":[ 586 { "n": "humidity", "v": 80, "u": "%RH" }], 587 } 589 5.5. Parameter 591 The Parameter interface allows configurable parameters and other 592 information to be modeled as a resource. The value of the parameter 593 can be read (GET) or set (PUT). Plain text or SenML Media types MAY 594 be returned from this type of interface. 596 The following example shows request for reading and setting a 597 parameter. 599 Req: GET /d/name 600 Res: 2.05 Content (text/plain) 601 node5 603 Req: PUT /d/name (text/plain) 604 outdoor 605 Res: 2.04 Changed 607 5.6. Read-only Parameter 609 The Read-only Parameter interface allows configuration parameters to 610 be read (GET) but not set. Plain text or SenML Media types MAY be 611 returned from this type of interface. 613 The following example shows request for reading such a parameter. 615 Req: GET /d/model 616 Res: 2.05 Content (text/plain) 617 SuperNode200 619 5.7. Actuator 621 The Actuator interface is used by resources that model different 622 kinds of actuators (changing its value has an effect on its 623 environment). Examples of actuators include for example LEDs, 624 relays, motor controllers and light dimmers. The current value of 625 the actuator can be read (GET) or a new actuator value set (PUT). In 626 addition, this interface defines the use of POST (with no body) to 627 toggle an actuator between its possible values. Plain text or SenML 628 Media types MAY be returned from this type of interface. A resource 629 with this interface MAY use SenML to include multiple measurements in 630 the same representation, for example a list of recent actuator values 631 or a list of values to set. 633 The following example shows requests for reading, setting and 634 toggling an actuator (turning on a led). 636 Req: GET /a/1/led 637 Res: 2.05 Content (text/plain) 638 0 640 Req: PUT /a/1/led (text/plain) 641 1 642 Res: 2.04 Changed 644 Req: POST /a/1/led (text/plain) 645 Res: 2.04 Changed 647 Req: GET /a/1/led 648 Res: 2.05 Content (text/plain) 649 0 651 5.8. Binding 653 The Binding interface is used to manipulate a binding table. A 654 request with a POST method and a content type of application/ 655 link-format simply appends new bindings to the table. All links in 656 the payload MUST have a relation type "boundTo". A GET request 657 simply returns the current state of a binding table whereas a DELETE 658 request empties the table. 660 The following example shows requests for adding, retrieving and 661 deleting bindings in a binding table. 663 Req: POST /bnd (Content-type: application/link-format) 664 ; 665 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 666 Res: 2.04 Changed 668 Req: GET /bnd 669 Res: 2.05 Content (application/link-format) 670 ; 671 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 673 Req: DELETE /bnd 674 Res: 2.04 Changed 676 5.9. Resource Observation Attributes 678 When resource interfaces following this specification are made 679 available over CoAP, the CoAP Observation mechanism 680 [I-D.ietf-core-observe] MAY be used to observe any changes in a 681 resource, and receive asynchronous notifications as a result. In 682 addition, a set of query string parameters are defined here to allow 683 a client to control how often a client is interested in receiving 684 notifications and how much a resource value should change for the new 685 representation to be interesting. These query parameters are 686 described in the following table. A resource using an interface 687 description defined in this specification and marked as Observable in 688 its link description SHOULD support these observation parameters. 689 The Change Step parameter can only be supported on resources with an 690 atomic numeric value. 692 These query parameters MUST be treated as resources that are read 693 using GET and set using PUT, and MUST NOT be included in the Observe 694 request. Multiple parameters MAY be set at the same time by 695 including the values in the query string of a PUT. Before being set, 696 these parameters have no default value. 698 +--------------+----------------+------------------+ 699 | Resource | Parameter | Data Format | 700 +--------------+----------------+------------------+ 701 | Change Step | /{resource}?st | xsd:decimal (>0) | 702 | Less Than | /{resource}?lt | xsd:decimal | 703 | Greater Than | /{resource}?gt | xsd:decimal | 704 +--------------+----------------+------------------+ 706 Change Step: When set, the change step indicates how much the value 707 of a resource SHOULD change before sending a new notification 708 (compared to the value of the last notification). This parameter 709 has lower priority than the period parameters, thus even if the 710 change step has been fulfilled, the time since the last 711 notification SHOULD be between pmin and pmax. 713 Less Than: When set, the value of the resource MUST be less than 714 this parameter in order to send a new notification. This 715 parameter has lower priority than the period parameters. 717 Greater Than: When set, the value of the resource MUST be greater 718 than this parameter in order to send a new notification. This 719 parameter has lower priority than the period parameters. 721 5.10. Future Interfaces 723 It is expected that further interface descriptions will be defined in 724 this and other specifications. Potential interfaces to be considered 725 for this specifications include: 727 Collection: This resource would be a container that allows sub- 728 resources to be added or removed. 730 5.11. WADL Description 732 This section defines the formal Web Application Description Langauge 733 (WADL) definition of these CoRE interface descriptions. 735 737 741 742 743 745 747 748 749 750 751 752 753 754 755 756 757 759 760 761 762 763 765 766 767 768 769 770 771 773 774 775 776 778 779 The methods read, 780 observe, update and toggle are applied to each sub- 781 resource of the requested resource that supports it. Mixed 782 sub-resource types can be supported. 783 784 785 786 787 788 790 791 . The methods read, 792 obervableRead, update and toggle are applied to each linked 793 resource of the requested resource that supports it. Mixed 794 linked resource types can be supported. 795 796 797 798 799 800 801 803 804 A modifiable list of 805 links. Each link MUST have the relation type "boundTo". 806 807 808 809 811 812 Retrieve the value of a sensor, an actuator or a parameter. 813 Both HTTP and CoAP support this method. 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 830 831 Observe the value of a sensor, an actuator or a parameter. 832 Only CoAP supports this method since it requires the CoRE 833 Observe mechanism. 834 835 836 837 838 839 840 841 842 843 844 845 847 848 Control the actuator or update a parameter with a new value 849 or command. Both HTTP and CoAP support this method. 850 851 852 853 854 855 856 857 858 860 861 Toggle the values of actuator resources. Both HTTP and CoAP 862 support this method. 863 864 The toggle function is only applicable if the request 865 is empty. 866 867 868 869 871 872 Retrieve the list of Web links associated to a resource. 873 Both HTTP and CoAP support this method. 874 875 This request MUST contain an Accept option with 876 application/link-format when the resource supports 877 other GET methods. 878 879 880 881 882 883 884 885 887 888 Append new Web links to a resource which is a collection 889 of links. Both HTTP and CoAP support this method. 890 891 892 893 894 895 896 897 Clear all Web Links in a resource which is a collection 898 of links. Both HTTP and CoAP support this method. 899 900 901 902 903 905 907 6. Security Considerations 909 An implementation of a client needs to be prepared to deal with 910 responses to a request that differ from what is specified in this 911 document. A server implementing what the client thinks is a resource 912 with one of these interface descriptions could return malformed 913 representations and response codes either by accident or maliciously. 914 A server sending maliciously malformed responses could attempt to 915 take advantage of a poorly implemented client for example to crash 916 the node or perform denial of service. 918 7. IANA Considerations 920 The interface description types defined require registration. 922 The new link relation type "boundto" requires registration. 924 8. Acknowledgments 926 Acknowledgement is given to colleagues from the SENSEI project who 927 were critical in the initial development of the well-known REST 928 interface concept, to members of the IPSO Alliance where further 929 requirements for interface types have been discussed, and to Szymon 930 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 931 provided useful discussion and input to the concepts in this 932 document. 934 9. Changelog 936 Changes from -01 to -02 937 o Updated the date and version, fixed references. 939 o Removed pmin and pmax observe parameters [Ticket #336] 941 Changes from -00 to WG Document -01 943 o Improvements to the Function Set section. 945 Changes from -05 to WG Document -00 947 o Updated the date and version. 949 Changes from -04 to -05 951 o Made the Observation control parameters to be treated as resources 952 rather than Observe query parameters. Added Less Than and Greater 953 Than parameters. 955 Changes from -03 to -04 957 o Draft refresh 959 Changes from -02 to -03 961 o Added Bindings 963 o Updated all rt= and if= for the new Link Format IANA rules 965 Changes from -01 to -02 967 o Defined a Function Set and its guidelines. 969 o Added the Link List interface. 971 o Added the Linked Batch interface. 973 o Improved the WADL interface definition. 975 o Added a simple profile example. 977 10. References 979 10.1. Normative References 981 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 982 Requirement Levels", BCP 14, RFC 2119, March 1997. 984 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 986 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 987 Format", RFC 6690, August 2012. 989 10.2. Informative References 991 [I-D.ietf-core-observe] 992 Hartke, K., "Observing Resources in CoAP", 993 draft-ietf-core-observe-15 (work in progress), 994 October 2014. 996 [I-D.ietf-core-resource-directory] 997 Shelby, Z., Bormann, C., and S. Krco, "CoRE Resource 998 Directory", draft-ietf-core-resource-directory-01 (work in 999 progress), December 2013. 1001 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 1002 Discovery", RFC 6763, February 2013. 1004 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1005 Application Protocol (CoAP)", RFC 7252, June 2014. 1007 Appendix A. Profile example 1009 The following is a short definition of simple profile. This 1010 simplistic profile is for use in the examples of this document. 1012 +--------------------+-----------+------------+---------+ 1013 | Function Set | Root Path | RT | IF | 1014 +--------------------+-----------+------------+---------+ 1015 | Device Description | /d | simple.dev | core.ll | 1016 | Sensors | /s | simple.sen | core.b | 1017 | Actuators | /a | simple.act | core.b | 1018 +--------------------+-----------+------------+---------+ 1020 List of Function Sets 1022 +-------+----------+----------------+---------+------------+ 1023 | Type | Path | RT | IF | Data Type | 1024 +-------+----------+----------------+---------+------------+ 1025 | Name | /d/name | simple.dev.n | core.p | xsd:string | 1026 | Model | /d/model | simple.dev.mdl | core.rp | xsd:string | 1027 +-------+----------+----------------+---------+------------+ 1029 Device Description Function Set 1031 +-------------+-------------+----------------+--------+-------------+ 1032 | Type | Path | RT | IF | Data Type | 1033 +-------------+-------------+----------------+--------+-------------+ 1034 | Light | /s/light | simple.sen.lt | core.s | xsd:decimal | 1035 | | | | | (lux) | 1036 | Humidity | /s/humidity | simple.sen.hum | core.s | xsd:decimal | 1037 | | | | | (%RH) | 1038 | Temperature | /s/temp | simple.sen.tmp | core.s | xsd:decimal | 1039 | | | | | (degC) | 1040 +-------------+-------------+----------------+--------+-------------+ 1042 Sensors Function Set 1044 +------+------------+----------------+--------+-------------+ 1045 | Type | Path | RT | IF | Data Type | 1046 +------+------------+----------------+--------+-------------+ 1047 | LED | /a/{#}/led | simple.act.led | core.a | xsd:boolean | 1048 +------+------------+----------------+--------+-------------+ 1050 Actuators Function Set 1052 Authors' Addresses 1054 Zach Shelby 1055 ARM 1056 150 Rose Orchard 1057 San Jose 95134 1058 FINLAND 1060 Phone: +1-408-203-9434 1061 Email: zach.shelby@arm.com 1063 Matthieu Vial 1064 Schneider-Electric 1065 Grenoble, 1066 FRANCE 1068 Phone: +33 (0)47657 6522 1069 Email: matthieu.vial@schneider-electric.com