idnits 2.17.1 draft-ietf-core-interfaces-04.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 : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 49 characters in excess of 72. ** The abstract seems to contain references ([RFC7641], [RFC6690]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 19, 2015) is 3111 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'REF' is mentioned on line 1384, but not defined == Unused Reference: 'I-D.jennings-core-senml' is defined on line 1623, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-04 == Outdated reference: A later version (-06) exists of draft-jennings-core-senml-01 Summary: 3 errors (**), 0 flaws (~~), 5 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: April 21, 2016 Schneider-Electric 6 M. Koster 7 ARM 8 October 19, 2015 10 Reusable Interface Definitions for Constrained RESTful Environments 11 draft-ietf-core-interfaces-04 13 Abstract 15 This document defines a set of reusable REST resource design patterns 16 suitable for use in constrained environments, based on IETF CoRE 17 standards for information representation and information exchange. 19 Interface types for Sensors, Actuators, Parameters, and resource 20 Collections are defined using the "if" link attribute defined by CoRE 21 Link Format [RFC6690]. Clients may use the "if" attribute to 22 determine how to consume resources. 24 Dynamic linking of state updates between resources, either on an 25 endpoint or between endpoints, is defined with the concept of Link 26 Bindings. We also define conditional observation attributes that 27 work with Link Bindings or with simple CoAP Observe [RFC7641]. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on April 21, 2016. 46 Internet-DrafReusable Interface Definitions for Constrained October 2015 48 Copyright Notice 50 Copyright (c) 2015 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. Interface Types . . . . . . . . . . . . . . . . . . . . . . . 5 68 4. Collections . . . . . . . . . . . . . . . . . . . . . . . . . 5 69 4.1. Introduction to Collections . . . . . . . . . . . . . . . 5 70 4.2. Use Cases for Collections . . . . . . . . . . . . . . . . 6 71 4.3. Content-Formats for Collections . . . . . . . . . . . . . 7 72 4.4. Links and Items in Collections . . . . . . . . . . . . . 7 73 4.5. Queries on Collections . . . . . . . . . . . . . . . . . 9 74 4.6. Observing Collections . . . . . . . . . . . . . . . . . . 9 75 4.7. Hypermedia Controls on Collections . . . . . . . . . . . 9 76 4.8. Collection Types . . . . . . . . . . . . . . . . . . . . 10 77 4.9. The collection+senml+json Content-Format . . . . . . . . 10 78 5. Link Bindings and Observe Attributes . . . . . . . . . . . . 11 79 5.1. Format . . . . . . . . . . . . . . . . . . . . . . . . . 12 80 5.2. Binding methods . . . . . . . . . . . . . . . . . . . . . 13 81 5.3. Binding table . . . . . . . . . . . . . . . . . . . . . . 14 82 5.4. Resource Observation Attributes . . . . . . . . . . . . . 14 83 6. Interface Descriptions . . . . . . . . . . . . . . . . . . . 15 84 6.1. Link List . . . . . . . . . . . . . . . . . . . . . . . . 17 85 6.2. Batch . . . . . . . . . . . . . . . . . . . . . . . . . . 17 86 6.3. Linked Batch . . . . . . . . . . . . . . . . . . . . . . 18 87 6.4. Hypermedia Collection . . . . . . . . . . . . . . . . . . 19 88 6.5. Sensor . . . . . . . . . . . . . . . . . . . . . . . . . 20 89 6.6. Parameter . . . . . . . . . . . . . . . . . . . . . . . . 21 90 6.7. Read-only Parameter . . . . . . . . . . . . . . . . . . . 21 91 6.8. Actuator . . . . . . . . . . . . . . . . . . . . . . . . 21 92 6.9. Binding . . . . . . . . . . . . . . . . . . . . . . . . . 22 93 6.10. Future Interfaces . . . . . . . . . . . . . . . . . . . . 23 94 6.11. WADL Description . . . . . . . . . . . . . . . . . . . . 23 95 7. Function Sets and Profiles . . . . . . . . . . . . . . . . . 29 97 Internet-DrafReusable Interface Definitions for Constrained October 2015 99 7.1. Defining a Function Set . . . . . . . . . . . . . . . . . 29 100 7.1.1. Path template . . . . . . . . . . . . . . . . . . . . 30 101 7.1.2. Resource Type . . . . . . . . . . . . . . . . . . . . 30 102 7.1.3. Interface Description . . . . . . . . . . . . . . . . 30 103 7.1.4. Data type . . . . . . . . . . . . . . . . . . . . . . 31 104 7.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 31 105 7.3. Versioning . . . . . . . . . . . . . . . . . . . . . . . 31 106 8. Security Considerations . . . . . . . . . . . . . . . . . . . 31 107 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 108 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 32 109 11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 32 110 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 111 12.1. Normative References . . . . . . . . . . . . . . . . . . 34 112 12.2. Informative References . . . . . . . . . . . . . . . . . 34 113 Appendix A. Profile example . . . . . . . . . . . . . . . . . . 35 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 116 1. Introduction 118 IETF Standards for machine to machine communication in constrained 119 environments describe a REST protocol and a set of related 120 information standards that may be used to represent machine data and 121 machine metadata in REST interfaces.. CoRE Link-format is a standard 122 for doing Web Linking [RFC5988] in constrained environments. SenML 123 is a simple data model and representation format for composite and 124 complex structured resources. CoRE Link-Format and SenML can be used 125 by CoAP [RFC7252] or HTTP servers. 127 The discovery of resources offered by a constrained server is very 128 important in machine-to-machine applications where there are no 129 humans in the loop. Machine application clients must be able to 130 adapt to different resource organizations without advance knowledge 131 of the specific data structures hosted by each connected thing. The 132 use of Web Linking for the description and discovery of resources 133 hosted by constrained web servers is specified by CoRE Link Format 134 [RFC6690]. CoRE Link Format additionally defines a link attribute 135 for Interface Type ("if") that can be used to describe the REST 136 interface of a resource, and may include a link to a description 137 document. 139 This document defines a set of Link Format compatible Interface Types 140 for some common design patterns that enable the server side 141 composition and organization, and client side discovery and 142 consumption, of machine resources using Web Linking. An Interface 143 Type may describe a resource in terms of it's associated content 144 formats, data types, URI templates, REST methods, parameters, and 145 responses. Basic interface types are defined for sensors, actuators, 146 and properties. A set of collection types is defined for organizing 148 Internet-DrafReusable Interface Definitions for Constrained October 2015 150 resources for discovery, and for various forms of bulk interaction 151 with resource sets using typed embedding links. 153 This document introduces the concept of a Link Binding, which defines 154 a new link relation type to create a dynamic link between resources 155 over which to exchange state updates. Specifically, a Link Binding 156 is a link for binding the state of 2 resources together such that 157 updates to one are sent over the link to the other. CoRE Link Format 158 representations are used to configure, inspect, and maintain Link 159 Bindings. This document additionally defines a set of conditional 160 Observe Attributes for use with Link Bindings and with the standalone 161 CoRE Observe [RFC7641] method. 163 Interface Types may be used in the composition of Function Sets and 164 Profiles. Function Sets and Profiles are described and an example is 165 given of a sensor and actuator device profile using Function Sets 166 composed from the Interface Types described in this document. 168 This document describes a set of Interface Types which are referenced 169 by the "if" link attribute and used to implement reusable design 170 patterns and functional abstractions. A client discovering the "if" 171 link attribute will be able to consume resources based on its 172 knowledge of the expected interface types. In this sense the 173 Interface Type acts in a similar way as a Content-Format, but as a 174 selector for a high level functional abstraction. Interface types 175 may also be provided with hypermedia controls and affordances to 176 drive client interaction using the principles of HATEOAS. In this 177 case, the Interface Types serve as constructor templates for resource 178 organization and hypermedia annotation. 180 2. Terminology 182 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 183 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 184 document are to be interpreted as described in [RFC2119]. 186 This specification requires readers to be familiar with all the terms 187 and concepts that are discussed in [RFC5988] and [RFC6690]. This 188 specification makes use of the following additional terminology: 190 Interface Type: A resource attribute which describes the interface 191 exposed by the resource in terms of content formats, REST methods, 192 parameters, and other related characteristics. 194 Collection: A resource which contains set of related resources, 195 referenced by a list of links and optionally consisting of 196 subresources. 198 Internet-DrafReusable Interface Definitions for Constrained October 2015 200 Link Binding: A unidirectional logical link between a source 201 resource and a destination resource, over which state information 202 is synchronized. 204 Resource Discovery: The process allowing a web client to identify 205 resources being hosted on a web server. 207 Gradual Reveal: A REST design where resources are discovered 208 progressively using Web Linking. 210 Function Set: A group of well-known REST resources that provides a 211 particular service. 213 Profile: A group of well-known Function Sets defined by a 214 specification. 216 Device: An IP smart object running a web server that hosts a group 217 of Function Set instances from a profile. 219 Service Discovery: The process making it possible for a web client 220 to automatically detect devices and Function Sets offered by these 221 devices on a CoRE network. 223 3. Interface Types 225 An Interface Type definition may describe a resource in terms of it's 226 associated content formats, data types, URI templates, REST methods, 227 parameters, and responses. 229 4. Collections 231 4.1. Introduction to Collections 233 A Collection is a resource which represents one or more related 234 resources. Within this document, a collection refers to a collection 235 with characteristics defined in this document. A Collection 236 Interface Type consists of a set of links and a set of items pointed 237 to by the links which may be sub-resources of the collection 238 resource. The collection types described in this document are Link 239 List, Batch, Linked Batch, and Hypermedia Collection. 241 The links in a collection are represented in CoRE Link-Format 242 Content-Formats including JSON and CBOR variants, and the items in 243 the collection may be represented by senml, including JSON and CBOR 244 variants. In general, a collection may support items of any 245 available Content-Format. 247 Internet-DrafReusable Interface Definitions for Constrained October 2015 249 A particular resource item may be a member of more than one 250 collection at a time by being linked to, but may only be a 251 subresource of one collection. 253 Some collections may have pre-configured items and links, and some 254 collections may support dynamic creation and removal of items and 255 links. Likewise, modification of items in some collections may be 256 permitted, and not in others. 258 Collections may support link embedding, which is analogous to an 259 image tag (link) causing the image to display inline in a browser 260 window. Resources pointed to by embedded links in collections may be 261 interacted with using bulk operations on the collection resource. 262 For example, performing a GET on a collection resource may return a 263 single representation containing all of the linked resources. 265 Links in collections may be selected for processing by a particular 266 request by using Query Filtering as described in CoRE Link-Format 267 [RFC6690]. 269 4.2. Use Cases for Collections 271 Collections may be used to provide gradual reveal of resources on an 272 endpoint. There may be a small set of links at the .well-known/core 273 location, which may in turn point to other collections of resources 274 that represent device information, device configuration, device 275 management, and various functional clusters of resources on the 276 device. 278 A collection may provide resource encapsulation, where link embedding 279 may be used to provide a single resource with which a client may 280 interact to obtain a set of related resource values. For example, a 281 collection for manufacturer parameters may consist of manufacturer 282 name, date of manufacture, location of manufacture, and serial number 283 resources which can be read as a single senml data object. 285 A collection may be used to group a set of like resources for bulk 286 state update or actuation. For example, the brightness control 287 resources of a number of luminaries may be grouped by linking to them 288 in a collection. The collection type may support receiving a single 289 update form a client and sending that update to each resource item in 290 the collection. 292 Items may be sub-resources of the collection resource. This enables 293 updates to to multiple items in the collection to be processed 294 together within the context of the collection resource. 296 Internet-DrafReusable Interface Definitions for Constrained October 2015 298 Items may be dynamically created in a collection along with their 299 hyperlinks. This provides an "item factory" pattern which can serve 300 as a resource creation mechanism for dynamic resources. This pattern 301 is also useful for creating temporary resources for the 302 implementation of dynamic phenomena like commands, actions, and 303 events using REST design patterns. Item creation uses the collection 304 Content-Format which allows specification of links and item state in 305 a single representation. 307 4.3. Content-Formats for Collections 309 The collection interfaces by default use CoRE Link-Format for the 310 link representations and SenML or text/plain for representations of 311 items. The examples given are for collections that expose resources 312 and links in these formats. In addition, a new "collection" Content- 313 Format is defined based on the SenML framework which represents both 314 links and items in the collection. 316 The choice of whether to return a representation of the links or of 317 the items or of the collection format is determined by the accepts 318 header option in the request. Likewise, the choice of updating link 319 metadata or item data or the collection resource itself is determined 320 by the Content-Format option in the header of the update request 321 operation. 323 The default Content-Formats for collection types described in this 324 document are: 326 Links: application/link-format, application/link-format+json 328 Items: application/senml+json, text/plain 330 Collection: application/collection+senml+json 332 4.4. Links and Items in Collections 334 Links use CoRE Link-Format representation by default and may point to 335 any resource reachable from the context of the collection. This 336 includes absolute links and links that point to other network 337 locations if the context of the collection allows. Links to sub- 338 resources in the collection MUST have a path-element starting with 339 the resource name, as per RFC3986 [RFC3986]. Links to resources in 340 the global context MUST start with a root path identifier 341 [RFC5988].Links to other collections are formed per RFC3986. 343 Examples of links: 345 Internet-DrafReusable Interface Definitions for Constrained October 2015 347 ;if="core.lb" : Link to the /sen/ collection describing it as 348 a core.lb type collection (Linked Batch) 350 ;rel="grp" : Link to the /sen/ collection indicating that 351 /sen/ is a member of a group in the collection in which the link 352 appears. 354 <"/sen/temp">;rt="temperature" : An absolute link to the resource at 355 the path /sen/temp 357 ;rt="temperature" : Link to the temp subresource of the 358 collection in which this link appears. 360 ;anchor="/sen/" : A link to the temp subresource of the 361 collection /sen/ which is assumed not to be a subresource of the 362 collection in which the link appears ,but is expected to be 363 identified in the collection by resource name. 365 Links in the collection MAY be Read, Updated, Added, or Removed using 366 the CoRE Link-Format or JSON Merge-Patch Content-Formats on the 367 collection resource. Reading links uses the GET method and returns 368 an array or list containing the link-values of all selected links. 369 Links may be added to the collection using POST or PATCH methods. 370 Updates to links MUST use the PATCH method and MAY use query 371 filtering to select links for updating. The PATCH method on links 372 MUST use the JSON Merge-Patch Content-Format (application/merge- 373 patch+json) specified in RFC7396 [RFC7396] . 375 Items in the collection SHOULD be represented using the SenML 376 (application/senml+json) or plain text (text/plain) Content-Formats, 377 depending on whether the representation is of a single data point or 378 multiple data points. Items MAY be represented using any supported 379 Content-Format. 381 Link Embedding enables the bulk processing of items in the collection 382 using a single operation targeting the collection resource. A subset 383 of resources in the collection may be selected for operation using 384 Query Filtering. Bulk Read operations using GET return a SenML 385 representation of all selected resources. Bulk item Update 386 operations using PUT or POST apply the payload document to all 387 selected resource items in the collection, using a either a Batch or 388 Group update policy. A Batch update is performed by applying the 389 resource values in the payload document to all resources in the 390 collection that match any resource name in the payload document. 391 Group updates are performed by applying the payload document to each 392 item in the collection. Group updates are indicated by the link 393 relation type rel="grp" in the link. 395 Internet-DrafReusable Interface Definitions for Constrained October 2015 397 The collection resource SHOULD represented using the 398 collection+senml+json Content-Format. The Hypermedia Collection type 399 is the only collection type which supports this representation. 400 Reading a collection using this content-format returns a 401 representation of the links and the items in the collection. 402 Performing a POST operation using this Content-Format MAY create one 403 or more new item(s) and their corresponding links in the collection. 404 Performing a PUT operation on this resource replaces the entire set 405 of links and items with the payload. This Content-Format is 406 described in section Section 4.9. Implementations MAY provide an 407 alternate method using POST in a Content-Format used by the items in 408 the collection which creates a default link-value and system-assigned 409 resource name. Such implementations MAY create sub-resources of the 410 collection resource. 412 4.5. Queries on Collections 414 Collections MAY support query filtering as defined in CoRE Link- 415 Format [RFC6690]. Operations targeting either the links or the items 416 MAY select a subset of links and items in the collection by using 417 query filtering. The Content-Format specified in the request header 418 selects whether links or items are targeted by the operation. 420 4.6. Observing Collections 422 Resource Observation using CoAP [RFC7252] MAY be supported on items 423 in a collection. A subset of the conditional observe parameters MAY 424 be specified to apply. In most cases pmin and pmax are useful. 425 Resource observation on a collection's items resource MAY report any 426 changes of resource state in any item in the collection. Observation 427 Responses, or notifications, SHOULD provide representations of the 428 resources that have changed in SenML Content-Format. Notifications 429 MAY include multiple observations of a particular resource, with 430 SenML time stamps indicating the observation times. 432 4.7. Hypermedia Controls on Collections 434 Additional Hypermedia controls may be defined to enable clients to 435 automatically consume the collection resources. Typically, the 436 developer may map application level semantics onto collection 437 operations. For example, invoking an Action on an actuator may be 438 defined as creating an Action item resource in a collection of 439 Actions associated with the actuator, each item in the collection 440 representing a past, current, or future action to be processed by the 441 actuator. Removing the item could cancel any pending or curent long- 442 running action, and removing a completed action could free up 443 resources for new actions to be invoked. A Hypermedia control for 444 this pattern might provide a semantic name for the action, for 446 Internet-DrafReusable Interface Definitions for Constrained October 2015 448 example "Change Brightness", and might direct the client to supply a 449 SenML representation of parameters for the action as well as provide 450 instructions on what method (POST) to use and how to construct the 451 URI (the collection URI in this case) if required. An example of 452 this hypermedia control is shown below. 454 4.8. Collection Types 456 There are four collection types defined in this document: 458 +---------------------+----------+----------------------------------+ 459 | Collection Type | if= | Content-Formats | 460 +---------------------+----------+----------------------------------+ 461 | Link List | core.ll | link-format | 462 | Batch | core.b | link-format, senml | 463 | Linked Batch | core.lb | link-format, senml | 464 | Hypermedia | core.hc | link-format, senml, | 465 | Collection | | collection+senml | 466 | Binding | core.bnd | link-format | 467 +---------------------+----------+----------------------------------+ 469 Each collection type MAY support a subset of the methods and 470 functions described above. For the first three collection types, the 471 methods and functions are defined in the corresponding Interface 472 Description. The Hypermedia Collection SHOULD expose hypermedia 473 controls to applications to indicate which methods and functions are 474 supported. 476 4.9. The collection+senml+json Content-Format 478 The collection+senml+json Content-Format is used to represent all of 479 the attributes and resources of a collection in a single format. 480 This is accomplished by extending the SenmL format by adding a links 481 element "l". The links element is formatted as an array of links in 482 the application/link-format+json Content-Format with the tag "l" 483 which follows the structure of the "e" element. An example of this 484 format is given below. 486 Internet-DrafReusable Interface Definitions for Constrained October 2015 488 { 489 "bn":"/ep/sen/" 490 "e":[ 491 { "n": "light", "v": 123, "u": "lx" }, 492 { "n": "temp", "v": 27.2, "u": "degC" }, 493 { "n": "humidity", "v": 80, "u": "%RH" }], 494 "l":[ 495 { "href":"/ep/sen/", "rel":"self", "if": "core.hc", "rt": "ms" }, 496 { "href":"light", "rt":"core.s" }, 497 { "href":"temp", "rt":"core.s" }, 498 { "href":"humidity", "rt":"core.s" }] 499 } 501 5. Link Bindings and Observe Attributes 503 In a M2M RESTful environment, endpoints may directly exchange the 504 content of their resources to operate the distributed system. For 505 example, a light switch may supply on-off control information that 506 may be sent directly to a light resource for on-off control. 507 Beforehand, a configuration phase is necessary to determine how the 508 resources of the different endpoints are related to each other. This 509 can be done either automatically using discovery mechanisms or by 510 means of human intervention and a so-called commissioning tool. In 511 this document the abstract relationship between two resources is 512 called a link Binding. The configuration phase necessitates the 513 exchange of binding information so a format recognized by all CoRE 514 endpoints is essential. This document defines a format based on the 515 CoRE Link-Format to represent binding information along with the 516 rules to define a binding method which is a specialized relationship 517 between two resources. The purpose of a binding is to synchronize 518 the content between a source resource and a destination resource. 519 The destination resource MAY be a group resource if the authority 520 component of the destination URI contains a group address (either a 521 multicast address or a name that resolves to a multicast address). 522 Since a binding is unidirectional, the binding entry defining a 523 relationship is present only on one endpoint. The binding entry may 524 be located either on the source or the destination endpoint depending 525 on the binding method. The following table gives a summary of the 526 binding methods described in more detail in Section 5.2. 528 +---------+------------+-------------+---------------+ 529 | Name | Identifier | Location | Method | 530 +---------+------------+-------------+---------------+ 531 | Polling | poll | Destination | GET | 532 | Observe | obs | Destination | GET + Observe | 533 | Push | push | Source | PUT | 534 +---------+------------+-------------+---------------+ 536 Internet-DrafReusable Interface Definitions for Constrained October 2015 538 5.1. Format 540 Since Binding involves the creation of a link between two resources, 541 Web Linking and the CoRE Link-Format are a natural way to represent 542 binding information. This involves the creation of a new relation 543 type, purposely named "boundto". In a Web link with this relation 544 type, the target URI contains the location of the source resource and 545 the context URI points to the destination resource. The Web link 546 attributes allow a fine-grained control of the type of 547 synchronization exchange along with the conditions that trigger an 548 update. This specification defines the attributes below: 550 +--------------------+-----------+------------------+ 551 | Attribute | Parameter | Value | 552 +--------------------+-----------+------------------+ 553 | Binding method | bind | xsd:string | 554 | Minimum Period (s) | pmin | xsd:integer (>0) | 555 | Maximum Period (s) | pmax | xsd:integer (>0) | 556 | Change Step | st | xsd:decimal (>0) | 557 | Greater Than | gt | xsd:decimal | 558 | Less Than | lt | xsd:decimal | 559 +--------------------+-----------+------------------+ 561 Bind Method: This is the identifier of a binding method which 562 defines the rules to synchronize the destination resource. This 563 attribute is mandatory. 565 Minimum Period: When present, the minimum period indicates the 566 minimum time to wait (in seconds) before sending a new 567 synchronization message (even if it has changed). In the absence 568 of this parameter, the minimum period is up to the notifier. 570 Maximum Period: When present, the maximum period indicates the 571 maximum time in seconds between two consecutive state 572 synchronization messages (regardless if it has changed). In the 573 absence of this parameter, the maximum period is up to the 574 notifier. The maximum period MUST be greater than the minimum 575 period parameter (if present). 577 Change Step: When present, the change step indicates how much the 578 value of a resource SHOULD change before sending a new 579 notification (compared to the value of the last notification). 580 This parameter has lower priority than the period parameters, thus 581 even if the change step has been fulfilled, the time since the 582 last notification SHOULD be between pmin and pmax. 584 Greater Than: When present, Greater Than indicates the upper limit 585 value the resource value SHOULD cross before sending a new 587 Internet-DrafReusable Interface Definitions for Constrained October 2015 589 notification. This parameter has lower priority than the period 590 parameters, thus even if the Greater Than limit has been crossed, 591 the time since the last notification SHOULD be between pmin and 592 pmax. 594 Less Than: When present, Less Than indicates the lower limit value 595 the resource value SHOULD cross before sending a new notification. 596 This parameter has lower priority than the period parameters, thus 597 even if the Less Than limit has been crossed, the time since the 598 last notification SHOULD be between pmin and pmax. 600 5.2. Binding methods 602 A binding method defines the rules to generate the web-transfer 603 exchanges that will effectively send content from the source resource 604 to the destination resource. The description of a binding method 605 must define the following aspects: 607 Identifier: This is value of the "bind" attribute used to identify 608 the method. 610 Location: This information indicates whether the binding entry is 611 stored on the source or on the destination endpoint. 613 REST Method: This is the REST method used in the Request/Response 614 exchanges. 616 Conditions: A binding method definition must state how the condition 617 attributes of the abstract binding definition are actually used in 618 this specialized binding. 620 This specification supports 3 binding methods described below. 622 Polling: The Polling method consists of sending periodic GET 623 requests from the destination endpoint to the source resource and 624 copying the content to the destination resource. The binding 625 entry for this method MUST be stored on the destination endpoint. 626 The destination endpoint MUST ensure that the polling frequency 627 does not exceed the limits defined by the pmin and pmax attributes 628 of the binding entry. The copying process MAY filter out content 629 from the GET requests using value-based conditions (e.g Change 630 Step, Less Than, Greater Than). 632 Observe: The Observe method creates an observation relationship 633 between the destination endpoint and the source resource. On each 634 notification the content from the source resource is copied to the 635 destination resource. The creation of the observation 636 relationship requires the CoAP Observation mechanism [RFC7641] 638 Internet-DrafReusable Interface Definitions for Constrained October 2015 640 hence this method is only permitted when the resources are made 641 available over CoAP. The binding entry for this method MUST be 642 stored on the destination endpoint. The binding conditions are 643 mapped as query string parameters (see Section 5.4). 645 Push: When the Push method is assigned to a binding, the source 646 endpoint sends PUT requests to the destination resource when the 647 binding condition attributes are satisfied for the source 648 resource. The source endpoint MUST only send a notification 649 request if the binding conditions are met. The binding entry for 650 this method MUST be stored on the source endpoint. 652 5.3. Binding table 654 The binding table is a special resource that gives access to the 655 bindings on a endpoint. A binding table resource MUST support the 656 Binding interface defined in Section 6.9. A profile SHOULD allow 657 only one resource table per endpoint. 659 5.4. Resource Observation Attributes 661 When resource interfaces following this specification are made 662 available over CoAP, the CoAP Observation mechanism [RFC7641] MAY be 663 used to observe any changes in a resource, and receive asynchronous 664 notifications as a result. In addition, a set of query string 665 parameters are defined here to allow a client to control how often a 666 client is interested in receiving notifications and how much a 667 resource value should change for the new representation to be 668 interesting. These query parameters are described in the following 669 table. A resource using an interface description defined in this 670 specification and marked as Observable in its link description SHOULD 671 support these observation parameters. The Change Step parameter can 672 only be supported on resources with an atomic numeric value. 674 These query parameters MUST be treated as resources that are read 675 using GET and updated using PUT, and MUST NOT be included in the 676 Observe request. Multiple parameters MAY be updated at the same time 677 by including the values in the query string of a PUT. Before being 678 updated, these parameters have no default value. 680 Internet-DrafReusable Interface Definitions for Constrained October 2015 682 +----------------+------------------+------------------+ 683 | Resource | Parameter | Data Format | 684 +----------------+------------------+------------------+ 685 | Minimum Period | /{resource}?pmin | xsd:integer (>0) | 686 | Maximum Period | /{resource}?pmax | xsd:integer (>0) | 687 | Change Step | /{resource}?st | xsd:decimal (>0) | 688 | Less Than | /{resource}?lt | xsd:decimal | 689 | Greater Than | /{resource}?gt | xsd:decimal | 690 +----------------+------------------+------------------+ 692 Minimum Period: When present, the minimum period indicates the 693 minimum time to wait (in seconds) before sending a new 694 synchronization message (even if it has changed). In the absence 695 of this parameter, the minimum period is up to the notifier. 697 Maximum Period: When present, the maximum period indicates the 698 maximum time in seconds between two consecutive state 699 synchronization messages (regardless if it has changed). In the 700 absence of this parameter, the maximum period is up to the 701 notifier. The maximum period MUST be greater than the minimum 702 period parameter (if present). 704 Change Step: When present, the change step indicates how much the 705 value of a resource SHOULD change before sending a new 706 notification (compared to the value of the last notification). 707 This parameter has lower priority than the period parameters, thus 708 even if the change step has been fulfilled, the time since the 709 last notification SHOULD be between pmin and pmax. 711 Greater Than: When present, Greater Than indicates the upper limit 712 value the resource value SHOULD cross before sending a new 713 notification. This parameter has lower priority than the period 714 parameters, thus even if the Greater Than limit has been crossed, 715 the time since the last notification SHOULD be between pmin and 716 pmax. 718 Less Than: When present, Less Than indicates the lower limit value 719 the resource value SHOULD cross before sending a new notification. 720 This parameter has lower priority than the period parameters, thus 721 even if the Less Than limit has been crossed, the time since the 722 last notification SHOULD be between pmin and pmax. 724 6. Interface Descriptions 726 This section defines REST interfaces for Link List, Batch, Sensor, 727 Parameter, Actuator and Binding table resources. Variants such as 728 Linked Batch or Read-Only Parameter are also presented. Each type is 729 described along with its Interface Description attribute value and 731 Internet-DrafReusable Interface Definitions for Constrained October 2015 733 valid methods. These are defined for each interface in the table 734 below. These interfaces can support plain text and/or SenML Media 735 types. 737 The if= column defines the Interface Description (if=) attribute 738 value to be used in the CoRE Link Format for a resource conforming to 739 that interface. When this value appears in the if= attribute of a 740 link, the resource MUST support the corresponding REST interface 741 described in this section. The resource MAY support additional 742 functionality, which is out of scope for this specification. 743 Although these interface descriptions are intended to be used with 744 the CoRE Link Format, they are applicable for use in any REST 745 interface definition. 747 The Methods column defines the methods supported by that interface, 748 which are described in more detail below. 750 +-----------------+----------+-----------------+--------------------+ 751 | Interface | if= | Methods | Content-Formats | 752 +-----------------+----------+-----------------+--------------------+ 753 | Link List | core.ll | GET | link-format | 754 | Batch | core.b | GET, PUT, POST | link-format, senml | 755 | Linked Batch | core.lb | GET, PUT, POST, | link-format, senml | 756 | | | DELETE | | 757 | Sensor | core.s | GET | link-format, | 758 | | | | text/plain | 759 | Parameter | core.p | GET, PUT | link-format, | 760 | | | | text/plain | 761 | Read-only | core.rp | GET | link-format, | 762 | Parameter | | | text/plain | 763 | Actuator | core.a | GET, PUT, POST | link-format, | 764 | | | | text/plain | 765 | Binding | core.bnd | GET, POST, | link-format | 766 | | | DELETE | | 767 +-----------------+----------+-----------------+--------------------+ 769 The following is an example of links in the CoRE Link Format using 770 these interface descriptions. The resource hierarchy is based on a 771 simple profile defined in Appendix A. These links are used in the 772 subsequent examples below. 774 Internet-DrafReusable Interface Definitions for Constrained October 2015 776 Req: GET /.well-known/core 777 Res: 2.05 Content (application/link-format) 778 ;rt="simple.sen";if="core.b", 779 ;rt="simple.sen.lt";if="core.s", 780 ;rt="simple.sen.tmp";if="core.s";obs, 781 ;rt="simple.sen.hum";if="core.s", 782 ;rt="simple.act";if="core.b", 783 ;rt="simple.act.led";if="core.a", 784 ;rt="simple.act.led";if="core.a", 785 ;rt="simple.dev";if="core.ll", 786 ;if="core.lb", 788 6.1. Link List 790 The Link List interface is used to retrieve (GET) a list of resources 791 on a web server. The GET request SHOULD contain an Accept option 792 with the application/link-format content format; however if the 793 resource does not support any other form of GET methods the Accept 794 option MAY be elided. The Accept option SHOULD only include the 795 application/link-format content format. The request returns a list 796 of URI references with absolute paths to the resources as defined in 797 CoRE Link Format. This interface is typically used with a parent 798 resource to enumerate sub-resources but may be used to reference any 799 resource on a web server. 801 Link List is the base interface to provide gradual reveal of 802 resources on a CoRE web server, hence the root resource of a Function 803 Set SHOULD implement this interface or an extension of this 804 interface. 806 The following example interacts with a Link List /d containing 807 Parameter sub-resources /d/name, /d/model. 809 Req: GET /d/ (Accept:application/link-format) 810 Res: 2.05 Content (application/link-format) 811 ;rt="simple.dev.n";if="core.p", 812 ;rt="simple.dev.mdl";if="core.rp" 814 6.2. Batch 816 The Batch interface is used to manipulate a collection of sub- 817 resources at the same time. The Batch interface type supports the 818 same methods as its sub-resources, and can be used to read (GET), 819 update (PUT) or apply (POST) the values of those sub-resource with a 820 single resource representation. The sub-resources of a Batch MAY be 821 heterogeneous, a method used on the Batch only applies to sub- 823 Internet-DrafReusable Interface Definitions for Constrained October 2015 825 resources that support it. For example Sensor interfaces do not 826 support PUT, and thus a PUT request to a Sensor member of that Batch 827 would be ignored. A batch requires the use of SenML Media types in 828 order to support multiple sub-resources. 830 In addition, The Batch interface is an extension of the Link List 831 interface and in consequence MUST support the same methods. 833 The following example interacts with a Batch /s/ with Sensor sub- 834 resources /s/light, /s/temp and /s/humidity. 836 Req: GET /s/ 837 Res: 2.05 Content (application/senml+json) 838 {"e":[ 839 { "n": "light", "v": 123, "u": "lx" }, 840 { "n": "temp", "v": 27.2, "u": "degC" }, 841 { "n": "humidity", "v": 80, "u": "%RH" }], 842 } 844 6.3. Linked Batch 846 The Linked Batch interface is an extension of the Batch interface. 847 Contrary to the basic Batch which is a collection statically defined 848 by the web server, a Linked Batch is dynamically controlled by a web 849 client. A Linked Batch resource has no sub-resources. Instead the 850 resources forming the batch are referenced using Web Linking 851 [RFC5988] and the CoRE Link Format [RFC6690]. A request with a POST 852 method and a content format of application/link-format simply appends 853 new resource links to the collection. The links in the payload MUST 854 reference a resource on the web server with an absolute path. A 855 DELETE request removes the entire collection. All other requests 856 available for a basic Batch are still valid for a Linked Batch. 858 The following example interacts with a Linked Batch /l/ and creates a 859 collection containing /s/light, /s/temp and /s/humidity in 2 steps. 861 Internet-DrafReusable Interface Definitions for Constrained October 2015 863 Req: POST /l/ (Content-Format: application/link-format) 864 , 865 Res: 2.04 Changed 867 Req: GET /l/ 868 Res: 2.05 Content (application/senml+json) 869 {"e":[ 870 { "n": "/s/light", "v": 123, "u": "lx" }, 871 { "n": "/s/temp", "v": 27.2, "u": "degC" }, 872 } 874 Req: POST /l/ (Content-Format: application/link-format) 875 876 Res: 2.04 Changed 878 Req: GET /l/ (Accept: application/link-format) 879 Res: 2.05 Content (application/link-format) 880 ,, 882 Req: GET /l/ 883 Res: 2.05 Content (application/senml+json) 884 {"e":[ 885 { "n": "/s/light", "v": 123, "u": "lx" }, 886 { "n": "/s/temp", "v": 27.2, "u": "degC" }, 887 { "n": "/s/humidity", "v": 80, "u": "%RH" }], 888 } 890 Req: DELETE /l/ 891 Res: 2.02 Deleted 893 6.4. Hypermedia Collection 895 The Hypermedia Collection interface MAY provide a full set of the 896 methods and link relation types described in section Section 4 of 897 this document. 899 The following example interacts with a Hypermedia Collection at 900 /act1/actions/ by creating a new resource with Parameter sub- 901 resources newVal, tTime. The example depicts an actuation operation 902 with a new actuator value of 86.3% and a transition time of 10 903 seconds. The returned location of the created resource is then read, 904 and a response is returned which includes the remaining time for the 905 operation to complete "rTime". Then, the operation is cancelled by 906 sending a DELETE operation to the location of the created resource 907 that represents the running action. 909 Internet-DrafReusable Interface Definitions for Constrained October 2015 911 Req: POST /Act1/Actions/ 912 Content-Format: application/collection+senml_json 913 Pl: [{"n":newVal", "v":86.3}, {"n":tTime", "v":10}] 914 Res: 2.01 Created 915 Location: Action1234 917 Req: GET /Act1/Actions/Action1234 918 Accepts: application/senml+json 919 Res: 2.05 Content 920 Pl: [{"n":newVal", "v":86.3}, 921 {"n":tTime", "v":10}, 922 {"n":"rTime", "v":"8.87"}] 924 Req: DELETE /Act1/Actions/Action1234 925 Res: 2.02 Deleted 927 Req: GET /Act1/Actions/Action1234 928 Res: 4.04 Not Found 930 6.5. Sensor 932 The Sensor interface allows the value of a sensor resource to be read 933 (GET). The Media type of the resource can be either plain text or 934 SenML. Plain text MAY be used for a single measurement that does not 935 require meta-data. For a measurement with meta-data such as a unit 936 or time stamp, SenML SHOULD be used. A resource with this interface 937 MAY use SenML to return multiple measurements in the same 938 representation, for example a list of recent measurements. 940 The following are examples of Sensor interface requests in both text/ 941 plain and application/senml+json. 943 Req: GET /s/humidity (Accept: text/plain) 944 Res: 2.05 Content (text/plain) 945 80 947 Req: GET /s/humidity (Accept: application/senml+json) 948 Res: 2.05 Content (application/senml+json) 949 {"e":[ 950 { "n": "humidity", "v": 80, "u": "%RH" }], 951 } 953 Internet-DrafReusable Interface Definitions for Constrained October 2015 955 6.6. Parameter 957 The Parameter interface allows configurable parameters and other 958 information to be modeled as a resource. The value of the parameter 959 can be read (GET) or update (PUT). Plain text or SenML Media types 960 MAY be returned from this type of interface. 962 The following example shows request for reading and updating a 963 parameter. 965 Req: GET /d/name 966 Res: 2.05 Content (text/plain) 967 node5 969 Req: PUT /d/name (text/plain) 970 outdoor 971 Res: 2.04 Changed 973 6.7. Read-only Parameter 975 The Read-only Parameter interface allows configuration parameters to 976 be read (GET) but not updated. Plain text or SenML Media types MAY 977 be returned from this type of interface. 979 The following example shows request for reading such a parameter. 981 Req: GET /d/model 982 Res: 2.05 Content (text/plain) 983 SuperNode200 985 6.8. Actuator 987 The Actuator interface is used by resources that model different 988 kinds of actuators (changing its value has an effect on its 989 environment). Examples of actuators include for example LEDs, 990 relays, motor controllers and light dimmers. The current value of 991 the actuator can be read (GET) or the actuator value can be updated 992 (PUT). In addition, this interface allows the use of POST to change 993 the state of an actuator, for example to toggle between its possible 994 values. Plain text or SenML Media types MAY be returned from this 995 type of interface. A resource with this interface MAY use SenML to 996 include multiple measurements in the same representation, for example 997 a list of recent actuator values or a list of values to updated. 999 Internet-DrafReusable Interface Definitions for Constrained October 2015 1001 The following example shows requests for reading, setting and 1002 toggling an actuator (turning on a led). 1004 Req: GET /a/1/led 1005 Res: 2.05 Content (text/plain) 1006 0 1008 Req: PUT /a/1/led (text/plain) 1009 1 1010 Res: 2.04 Changed 1012 Req: POST /a/1/led (text/plain) 1013 Res: 2.04 Changed 1015 Req: GET /a/1/led 1016 Res: 2.05 Content (text/plain) 1017 0 1019 6.9. Binding 1021 The Binding interface is used to manipulate a binding table. A 1022 request with a POST method and a content format of application/link- 1023 format simply appends new bindings to the table. All links in the 1024 payload MUST have a relation type "boundTo". A GET request simply 1025 returns the current state of a binding table whereas a DELETE request 1026 empties the table. 1028 The following example shows requests for adding, retrieving and 1029 deleting bindings in a binding table. 1031 Req: POST /bnd/ (Content-Format: application/link-format) 1032 ; 1033 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 1034 Res: 2.04 Changed 1036 Req: GET /bnd/ 1037 Res: 2.05 Content (application/link-format) 1038 ; 1039 rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" 1041 Req: DELETE /bnd/ 1042 Res: 2.04 Changed 1044 Internet-DrafReusable Interface Definitions for Constrained October 2015 1046 6.10. Future Interfaces 1048 It is expected that further interface descriptions will be defined in 1049 this and other specifications. 1051 6.11. WADL Description 1053 This section defines the formal Web Application Description Langauge 1054 (WADL) definition of these CoRE interface descriptions. 1056 1058 1062 1063 1064 1066 1068 1069 1070 1071 1072 1073 1074 1075 1077 1078 1079 1080 1081 1082 1083 1084 1085 1087 1088 1089 1090 1091 1092 1094 Internet-DrafReusable Interface Definitions for Constrained October 2015 1096 1097 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1110 1111 1112 1113 1115 1116 The methods read, 1117 observe, update and apply are applied to each sub- 1118 resource of the requested resource that supports it. Mixed 1119 sub-resource types can be supported. 1120 1121 1122 1123 1124 1125 1126 1127 1128 1130 1131 . The methods read, 1132 obervableRead, update and apply are applied to each linked 1133 resource of the requested resource that supports it. Mixed 1134 linked resource types can be supported. 1135 1136 1137 1138 1139 1140 1141 1142 1143 1145 Internet-DrafReusable Interface Definitions for Constrained October 2015 1147 1148 1150 1151 . 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1167 1168 A modifiable list of 1169 links. Each link MUST have the relation type "boundTo". 1170 1171 1172 1173 1175 1176 Retrieve the value of a sensor, an actuator or a parameter. 1177 Both HTTP and CoAP support this method. 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1189 1190 1191 1192 1193 1195 Internet-DrafReusable Interface Definitions for Constrained October 2015 1197 1198 Observe the value of a sensor, an actuator or a parameter. 1199 Only CoAP supports this method since it requires the CoRE 1200 Observe mechanism. 1201 1202 1203 1206 1207 1208 1209 1210 1211 1212 1214 1215 Cancel observation in progress. 1216 Only CoAP supports this method since it requires the CoRE 1217 Observe mechanism. 1218 1219 1220 1223 1224 1225 1226 1227 1228 1229 1231 1232 Control the actuator or update a parameter with a new value 1233 or command. Both HTTP and CoAP support this method. 1234 1235 1236 1237 1238 1239 1240 1241 1242 1244 1246 Internet-DrafReusable Interface Definitions for Constrained October 2015 1248 Retrieve the observe attributes associated with a resource. 1249 Both HTTP and CoAP support this method. 1250 1251 This request MUST contain an Accept option with 1252 application/link-format when the resource supports 1253 other GET methods. 1254 1255 1256 1257 1258 1259 1260 1261 1262 1264 1265 Set the values of some or all of the observe attributes 1266 associated with a resource. 1267 Both HTTP and CoAP support this method. 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1281 1282 Apply the value, if supplied, to resources. Both HTTP and CoAP 1283 support this method. 1284 1285 The apply function may contain a payload to be applied. 1286 1287 1288 1289 1291 1292 Retrieve the list of Web links associated to a resource. 1293 Both HTTP and CoAP support this method. 1294 1295 This request MUST contain an Accept option with 1297 Internet-DrafReusable Interface Definitions for Constrained October 2015 1299 application/link-format when the resource supports 1300 other GET methods. 1301 1302 1303 1304 1305 1306 1307 1308 1310 1311 Append new Web links to a resource which is a collection 1312 of links. Both HTTP and CoAP support this method. 1313 1314 1315 1316 1317 1318 1320 1321 Clear all Web Links in a resource which is a collection 1322 of links. Both HTTP and CoAP support this method. 1323 1324 1325 1326 1327 1329 1330 Update all Web Links in a resource which is a collection 1331 of links. Both HTTP and CoAP support this method. 1332 This request MUST contain a Content-Format option with 1333 application/merge-patch+json. 1334 1335 1336 1337 1338 1340 1341 Add zero or more items to the collection with their links. Both HTTP and CoAP support this method. 1342 This request MAY contain a Content-Format option with 1343 application/collection+senml+json. 1344 This request MAY contain a Content-Format option with 1345 application/senml+json. 1346 1348 Internet-DrafReusable Interface Definitions for Constrained October 2015 1350 1351 1352 1353 1355 1356 REturn a representation of both links and items in the collection. Both HTTP and CoAP support this method. 1357 This request MUST contain an Accepts option with 1358 application/collection+senml+json. 1359 1360 1361 1362 1363 1365 1367 7. Function Sets and Profiles 1369 This section defines how a set of REST resources can be created 1370 called a function set. A Function Set is similar to a function block 1371 in the sense that it consists of input, output and parameter 1372 resources and contains internal logic. A Function Set can have a 1373 subset of mandatory inputs, outputs and parameters to provide minimum 1374 interoperability. It can also be extended with manufacturer/user- 1375 specific resources. A device is composed of one or more Function Set 1376 instances. 1378 An example of function sets can be found from the CoRE Resource 1379 Directory specification that defines REST interfaces for 1380 registration, group and lookup [I-D.ietf-core-resource-directory]. 1381 The OMA Lightweight M2M standard [REF] also defines a function set 1382 structure called an Objects that use integer path, instance and 1383 resource URI segments. OMA Objects can be defined and then 1384 registered with an OMA maintained registry [REF]. This section is 1385 simply meant as a guideline for the definition of other such REST 1386 interfaces, either custom or part of other specifications. 1388 7.1. Defining a Function Set 1390 In a Function Set, types of resources are defined. Each type 1391 includes a human readable name, a path template, a Resource Type for 1392 discovery, the Interface Definition and the data type and allowed 1393 values. A Function Set definition may also include a field 1394 indicating if a sub-resource is mandatory or optional. 1396 Internet-DrafReusable Interface Definitions for Constrained October 2015 1398 7.1.1. Path template 1400 A Function Set is a container resource under which its sub-resources 1401 are organized. The profile defines the path to each resource of a 1402 Function Set in a path template. The template can contain either 1403 relative paths or absolute paths depending on the profile needs. An 1404 absolute Function Set should be located at its recommended root path 1405 on a web server, however it can be located under an alternative path 1406 if necessary (for example multi-purpose devices, gateways etc.). A 1407 relative Function Set can be instantiated as many times as needed on 1408 a web server with an arbitrary root path. However some Function Sets 1409 (e.g. device description) only make sense as singletons. 1411 The path template includes a possible index {#} parameter, and 1412 possible fixed path segments. The index {#} allows for multiple 1413 instances of this type of resource, and can be any string. The root 1414 path and the indexes are the only variable elements in a path 1415 template. All other path segments should be fixed. 1417 7.1.2. Resource Type 1419 Each root resource of a Function Set is assigned a Resource Type 1420 parameter, therefore making it possible to discover it. Each sub- 1421 resource of a Function Set is also assigned a Resource Type 1422 parameter. This Resource Type is used for resource discovery and is 1423 usually necessary to discover optional resources supported on a 1424 specific device. The Resource Type of a Function Set may also be 1425 used for service discovery and can be exported to DNS-SD [RFC6763] 1426 for example. 1428 The Resource Type parameter defines the value that should be included 1429 in the rt= field of the CoRE Link Format when describing a link to 1430 this resource. The value SHOULD be in the form "namespace.type" for 1431 root resources and "namespace.type.subtype" for sub-resources. This 1432 naming convention facilitates resource type filtering with the 1433 /.well-known/core resource. However a profile could allow mixing in 1434 foreign namespace references within a Function Set to import external 1435 references from other object models (e.g. SenML and UCUM). 1437 7.1.3. Interface Description 1439 The Interface Description parameter defines the REST interface for 1440 that type of resource. Several base interfaces are defined in 1441 Section 6 of this document. For a given profile, the Interface 1442 Description may be inferred from the Resource Type. In that case the 1443 Interface Description MAY be elided from link descriptions of 1444 resource types defined in the profile, but should be included for 1445 custom extensions to the profile. 1447 Internet-DrafReusable Interface Definitions for Constrained October 2015 1449 The root resource of a Function Set should provide a list of links to 1450 its sub-resources in order to offer gradual reveal of resources. The 1451 CoRE Link List interface defined in Section 6.1 offers this 1452 functionality so a root resource should support this interface or a 1453 derived interface like CoRE Batch (See Section 6.2). 1455 7.1.4. Data type 1457 The Data Type field defines the type of value (and possible range) 1458 that is returned in response to a GET for that resource or accepted 1459 with a PUT. The interfaces defined in Section 6 make use of plain 1460 text and SenML Media types for the actual format of this data. A 1461 profile may restrict the list of supported content formats for the 1462 CoRE interfaces or define new interfaces with new content types. 1464 7.2. Discovery 1466 A device conforming to a profile SHOULD make its resources 1467 discoverable by providing links to the resources on the path /.well- 1468 known/core as defined in [RFC6690]. All resources hosted on a device 1469 SHOULD be discoverable either with a direct link in /.well-known/core 1470 or by following successive links starting from /.well-known/core. 1472 The root path of a Function Set instance SHOULD be directly 1473 referenced in /.well-known/core in order to offer discovery at the 1474 first discovery stage. A device with more than 10 individual 1475 resources SHOULD only expose Function Set instances in /.well-known/ 1476 core to limit the size of this resource. 1478 In addition, a device MAY register its resources to a Resource 1479 Directory using the registration interface defined in 1480 [I-D.ietf-core-resource-directory] if such a directory is available. 1482 7.3. Versioning 1484 A profile should track Function Set changes to avoid incompatibility 1485 issues. Evolutions in a Function Set SHOULD be backward compatible. 1487 8. Security Considerations 1489 An implementation of a client needs to be prepared to deal with 1490 responses to a request that differ from what is specified in this 1491 document. A server implementing what the client thinks is a resource 1492 with one of these interface descriptions could return malformed 1493 representations and response codes either by accident or maliciously. 1494 A server sending maliciously malformed responses could attempt to 1495 take advantage of a poorly implemented client for example to crash 1496 the node or perform denial of service. 1498 Internet-DrafReusable Interface Definitions for Constrained October 2015 1500 9. IANA Considerations 1502 The interface description types defined require registration. 1504 The new link relations type "boundto" and "grp" require registration. 1506 10. Acknowledgments 1508 Acknowledgement is given to colleagues from the SENSEI project who 1509 were critical in the initial development of the well-known REST 1510 interface concept, to members of the IPSO Alliance where further 1511 requirements for interface types have been discussed, and to Szymon 1512 Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have 1513 provided useful discussion and input to the concepts in this 1514 document. 1516 11. Changelog 1518 Changes from -03 to -04 1520 o Fixed tickets #385 and #386 1522 o Changed abstract and into to better describe content 1524 o Focus on Interface and not function set/profiles in intro 1526 o Changed references from draft-core-observe to RFC7641 1528 o Moved Function sets and Profiles to section after Interfaces 1530 o Moved Observe Attributes to the Link Binding section 1532 o Add a Collection section to describe the collection types 1534 o Add the Hypermedia Collection Interface Description 1536 Changes from -02 to -03 1538 o Added lt and gt to binding format section. 1540 o Added pmin and pmax observe parameters to Observation Attributes 1542 o Changed the definition of lt and gt to limit crossing. 1544 o Added definitions for getattr and setattr to WADL. 1546 o Added getattr and setattr to observable interfaces. 1548 Internet-DrafReusable Interface Definitions for Constrained October 2015 1550 o Removed query parameters from Observe definition. 1552 o Added observe-cancel definition to WADL and to observable 1553 interfaces. 1555 Changes from -01 to -02 1557 o Updated the date and version, fixed references. 1559 o Removed pmin and pmax observe parameters [Ticket #336] 1561 Changes from -00 to WG Document -01 1563 o Improvements to the Function Set section. 1565 Changes from -05 to WG Document -00 1567 o Updated the date and version. 1569 Changes from -04 to -05 1571 o Made the Observation control parameters to be treated as resources 1572 rather than Observe query parameters. Added Less Than and Greater 1573 Than parameters. 1575 Changes from -03 to -04 1577 o Draft refresh 1579 Changes from -02 to -03 1581 o Added Bindings 1583 o Updated all rt= and if= for the new Link Format IANA rules 1585 Changes from -01 to -02 1587 o Defined a Function Set and its guidelines. 1589 o Added the Link List interface. 1591 o Added the Linked Batch interface. 1593 o Improved the WADL interface definition. 1595 o Added a simple profile example. 1597 Internet-DrafReusable Interface Definitions for Constrained October 2015 1599 12. References 1601 12.1. Normative References 1603 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1604 Requirement Levels", BCP 14, RFC 2119, 1605 DOI 10.17487/RFC2119, March 1997, 1606 . 1608 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1609 DOI 10.17487/RFC5988, October 2010, 1610 . 1612 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1613 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1614 . 1616 12.2. Informative References 1618 [I-D.ietf-core-resource-directory] 1619 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 1620 Resource Directory", draft-ietf-core-resource-directory-04 1621 (work in progress), July 2015. 1623 [I-D.jennings-core-senml] 1624 Jennings, C., Shelby, Z., Arkko, J., and A. Keranen, 1625 "Media Types for Sensor Markup Language (SENML)", draft- 1626 jennings-core-senml-01 (work in progress), July 2015. 1628 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1629 Resource Identifier (URI): Generic Syntax", STD 66, 1630 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1631 . 1633 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 1634 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 1635 . 1637 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1638 Application Protocol (CoAP)", RFC 7252, 1639 DOI 10.17487/RFC7252, June 2014, 1640 . 1642 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 1643 DOI 10.17487/RFC7396, October 2014, 1644 . 1646 Internet-DrafReusable Interface Definitions for Constrained October 2015 1648 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1649 Application Protocol (CoAP)", RFC 7641, 1650 DOI 10.17487/RFC7641, September 2015, 1651 . 1653 Appendix A. Profile example 1655 The following is a short definition of simple profile. This 1656 simplistic profile is for use in the examples of this document. 1658 +--------------------+-----------+------------+---------+ 1659 | Function Set | Root Path | RT | IF | 1660 +--------------------+-----------+------------+---------+ 1661 | Device Description | /d | simple.dev | core.ll | 1662 | Sensors | /s | simple.sen | core.b | 1663 | Actuators | /a | simple.act | core.b | 1664 +--------------------+-----------+------------+---------+ 1666 List of Function Sets 1668 +-------+----------+----------------+---------+------------+ 1669 | Type | Path | RT | IF | Data Type | 1670 +-------+----------+----------------+---------+------------+ 1671 | Name | /d/name | simple.dev.n | core.p | xsd:string | 1672 | Model | /d/model | simple.dev.mdl | core.rp | xsd:string | 1673 +-------+----------+----------------+---------+------------+ 1675 Device Description Function Set 1677 +-------------+-------------+----------------+--------+-------------+ 1678 | Type | Path | RT | IF | Data Type | 1679 +-------------+-------------+----------------+--------+-------------+ 1680 | Light | /s/light | simple.sen.lt | core.s | xsd:decimal | 1681 | | | | | (lux) | 1682 | Humidity | /s/humidity | simple.sen.hum | core.s | xsd:decimal | 1683 | | | | | (%RH) | 1684 | Temperature | /s/temp | simple.sen.tmp | core.s | xsd:decimal | 1685 | | | | | (degC) | 1686 +-------------+-------------+----------------+--------+-------------+ 1688 Sensors Function Set 1690 Internet-DrafReusable Interface Definitions for Constrained October 2015 1692 +------+------------+----------------+--------+-------------+ 1693 | Type | Path | RT | IF | Data Type | 1694 +------+------------+----------------+--------+-------------+ 1695 | LED | /a/{#}/led | simple.act.led | core.a | xsd:boolean | 1696 +------+------------+----------------+--------+-------------+ 1698 Actuators Function Set 1700 Authors' Addresses 1702 Zach Shelby 1703 ARM 1704 150 Rose Orchard 1705 San Jose 95134 1706 FINLAND 1708 Phone: +1-408-203-9434 1709 Email: zach.shelby@arm.com 1711 Matthieu Vial 1712 Schneider-Electric 1713 Grenoble 1714 FRANCE 1716 Phone: +33 (0)47657 6522 1717 Email: matthieu.vial@schneider-electric.com 1719 Michael Koster 1720 ARM 1721 150 Rose Orchard 1722 San Jose 95134 1723 USA 1725 Email: michael.koster@arm.com