idnits 2.17.00 (12 Aug 2021) /tmp/idnits46341/draft-irtf-t2trg-rest-iot-09.txt: -(1310): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 495 has weird spacing: '... query frag...' -- The document date (26 February 2022) is 77 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-05) exists of draft-ietf-core-coral-04 == Outdated reference: A later version (-10) exists of draft-ietf-core-href-09 == Outdated reference: draft-ietf-core-resource-directory has been published as RFC 9176 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-11) exists of draft-ietf-asdf-sdf-10 == Outdated reference: A later version (-10) exists of draft-ietf-core-coap-pubsub-09 Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Keranen 3 Internet-Draft Ericsson 4 Intended status: Informational M. Kovatsch 5 Expires: 30 August 2022 Huawei Technologies 6 K. Hartke 7 26 February 2022 9 Guidance on RESTful Design for Internet of Things Systems 10 draft-irtf-t2trg-rest-iot-09 12 Abstract 14 This document gives guidance for designing Internet of Things (IoT) 15 systems that follow the principles of the Representational State 16 Transfer (REST) architectural style. This document is a product of 17 the IRTF Thing-to-Thing Research Group (T2TRG). 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 30 August 2022. 36 Copyright Notice 38 Copyright (c) 2022 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Revised BSD License text as 47 described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Revised BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 3. Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 55 3.1. Architecture . . . . . . . . . . . . . . . . . . . . . . 8 56 3.2. System design . . . . . . . . . . . . . . . . . . . . . . 10 57 3.3. Uniform Resource Identifiers (URIs) . . . . . . . . . . . 11 58 3.4. Representations . . . . . . . . . . . . . . . . . . . . . 12 59 3.5. HTTP/CoAP Methods . . . . . . . . . . . . . . . . . . . . 13 60 3.5.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 14 61 3.5.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 14 62 3.5.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 15 63 3.5.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 15 64 3.5.5. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 15 65 3.5.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . 16 66 3.6. HTTP/CoAP Status/Response Codes . . . . . . . . . . . . . 16 67 4. REST Constraints . . . . . . . . . . . . . . . . . . . . . . 16 68 4.1. Client-Server . . . . . . . . . . . . . . . . . . . . . . 17 69 4.2. Stateless . . . . . . . . . . . . . . . . . . . . . . . . 17 70 4.3. Cache . . . . . . . . . . . . . . . . . . . . . . . . . . 18 71 4.4. Uniform Interface . . . . . . . . . . . . . . . . . . . . 18 72 4.5. Layered System . . . . . . . . . . . . . . . . . . . . . 19 73 4.6. Code-on-Demand . . . . . . . . . . . . . . . . . . . . . 20 74 5. Hypermedia-driven Applications . . . . . . . . . . . . . . . 20 75 5.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 21 76 5.2. Knowledge . . . . . . . . . . . . . . . . . . . . . . . . 21 77 5.3. Interaction . . . . . . . . . . . . . . . . . . . . . . . 22 78 5.4. Hypermedia-driven Design Guidance . . . . . . . . . . . . 22 79 6. Design Patterns . . . . . . . . . . . . . . . . . . . . . . . 23 80 6.1. Collections . . . . . . . . . . . . . . . . . . . . . . . 23 81 6.2. Calling a Procedure . . . . . . . . . . . . . . . . . . . 23 82 6.2.1. Instantly Returning Procedures . . . . . . . . . . . 24 83 6.2.2. Long-running Procedures . . . . . . . . . . . . . . . 24 84 6.2.3. Conversion . . . . . . . . . . . . . . . . . . . . . 24 85 6.2.4. Events as State . . . . . . . . . . . . . . . . . . . 25 86 6.3. Server Push . . . . . . . . . . . . . . . . . . . . . . . 26 87 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 88 8. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 28 89 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 90 9.1. Normative References . . . . . . . . . . . . . . . . . . 28 91 9.2. Informative References . . . . . . . . . . . . . . . . . 31 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 94 1. Introduction 96 The Representational State Transfer (REST) architectural style [REST] 97 is a set of guidelines and best practices for building distributed 98 hypermedia systems. At its core is a set of constraints, which when 99 fulfilled enable desirable properties for distributed software 100 systems such as scalability and modifiability. When REST principles 101 are applied to the design of a system, the result is often called 102 RESTful and in particular an API following these principles is called 103 a RESTful API. 105 Different protocols can be used with RESTful systems, but at the time 106 of writing the most common protocols are HTTP [RFC7230] and CoAP 107 [RFC7252]. Since RESTful APIs are often lightweight and enable loose 108 coupling of system components, they are a good fit for various 109 Internet of Things (IoT) applications, which in general aim at 110 interconnecting the physical world with the virtual world. The goal 111 of this document is to give basic guidance for designing RESTful 112 systems and APIs for IoT applications and give pointers for more 113 information. 115 Design of a good RESTful IoT system has naturally many commonalities 116 with other Web systems. Compared to other systems, the key 117 characteristics of many RESTful IoT systems include: 119 * accommodating for constrained devices [RFC7228], so with IoT, REST 120 is not only used for scaling out (large number of clients on a Web 121 server), but also for scaling down (efficient server on 122 constrained node, e.g., in energy consumption or implementation 123 complexity) 125 * facilitating efficient transfer over (often) constrained networks 126 and lightweight processing in constrained nodes through compact 127 and simple data formats 129 * minimizing or preferably avoiding the need for human interaction 130 through machine-understandable data formats and interaction 131 patterns 133 * enabling the system to evolve gradually in the field, as the 134 usually large number of endpoints can not be updated 135 simultaneously 137 * having endpoints that are both clients and servers 139 2. Terminology 141 This section explains selected terminology that is commonly used in 142 the context of RESTful design for IoT systems. For terminology of 143 constrained nodes and networks, see [RFC7228]. Terminology on 144 modeling of Things and their affordances (Properties, Actions, and 145 Events) was taken from [I-D.ietf-asdf-sdf]. 147 Action: An affordance that can potentially be used to perform a 148 named operation on a Thing. 150 Action Result: A representation sent as a response by a server that 151 does not represent resource state, but the result of the 152 interaction with the originally addressed resource. 154 Affordance: An element of an interface offered for interaction, 155 defining its possible uses or making clear how it can or should be 156 used. The term is used here for the digital interfaces of a Thing 157 only; it might also have physical affordances such as buttons, 158 dials, and displays. 160 Cache: A local store of response messages and the subsystem that 161 controls storage, retrieval, and deletion of messages in it. 163 Client: A node that sends requests to servers and receives 164 responses; it therefore has the initiative to interact. In 165 RESTful IoT systems it is common for nodes to have more than one 166 role (i.e., to be both server and client; see Section 3.1). 168 Client State: The state kept by a client between requests. This 169 typically includes the currently processed representation, the set 170 of active requests, the history of requests, bookmarks (URIs 171 stored for later retrieval), and application-specific state (e.g., 172 local variables). (Note that this is called "Application State" 173 in [REST], which has some ambiguity in modern (IoT) systems where 174 resources are highly dynamic and the overall state of the 175 distributed application (i.e., application state) is reflected in 176 the union of all Client States and Resource States of all clients 177 and servers involved.) 179 Content Type: A string that carries the media type plus potential 180 parameters for the representation format such as "text/ 181 plain;charset=UTF-8". 183 Content Negotiation: The practice of determining the "best" 184 representation for a client when examining the current state of a 185 resource. The most common forms of content negotiation are 186 Proactive Content Negotiation and Reactive Content Negotiation. 188 Dereference: To use an access mechanism (e.g., HTTP or CoAP) to 189 interact with the resource of a URI. 191 Dereferenceable URI: A URI that can be dereferenced, i.e., 192 interaction with the identified resource is possible. Not all 193 HTTP or CoAP URIs are dereferenceable, e.g., when the target 194 resource does not exist. 196 Event: An affordance that can potentially be used to (recurrently) 197 obtain information about what happened to a Thing, e.g., through 198 server push. 200 Form: A hypermedia control that enables a client to construct more 201 complex requests, e.g., to change the state of a resource or 202 perform specific queries. 204 Forward Proxy: An intermediary that is selected by a client, usually 205 via local configuration rules, and that can be tasked to make 206 requests on behalf of the client. This may be useful, for 207 example, when the client lacks the capability to make the request 208 itself or to service the response from a cache in order to reduce 209 response time, network bandwidth, and energy consumption. 211 Gateway: A reverse proxy that provides an interface to a non-RESTful 212 system such as legacy systems or alternative technologies such as 213 Bluetooth Attribute Profile (ATT) or Generic Attribute Profile 214 (GATT). See also "Reverse Proxy". 216 Hypermedia Control: Information provided by a server on how to use 217 its RESTful API; usually a URI and instructions on how to 218 dereference it for a specific interaction. Hypermedia Controls 219 are the serialized/encoded affordances of hypermedia systems. 221 Idempotent Method: A method where multiple identical requests with 222 that method lead to the same visible resource state as a single 223 such request. 225 Link: A hypermedia control that enables a client to navigate between 226 resources and thereby change the client state. 228 Link Relation Type: An identifier that describes how the link target 229 resource relates to the current resource (see [RFC8288]). 231 Media Type: An IANA-registered string such as "text/html" or 232 "application/json" that is used to label representations so that 233 it is known how the representation should be interpreted and how 234 it is encoded. 236 Method: An operation associated with a resource. Common methods 237 include GET, PUT, POST, and DELETE (see Section 3.5 for details). 239 Origin Server: A server that is the definitive source for 240 representations of its resources and the ultimate recipient of any 241 request that intends to modify its resources. In contrast, 242 intermediaries (such as proxies caching a representation) can 243 assume the role of a server, but are not the source for 244 representations as these are acquired from the origin server. 246 Proactive Content Negotiation: A content negotiation mechanism where 247 the server selects a representation based on the expressed 248 preference of the client. For example, an IoT application could 249 send a request that prefers to accept the media type "application/ 250 senml+json". 252 Property: An affordance that can potentially be used to read, write, 253 and/or observe state on a Thing. 255 Reactive Content Negotiation: A content negotiation mechanism where 256 the client selects a representation from a list of available 257 representations. The list may, for example, be included by a 258 server in an initial response. If the user agent is not satisfied 259 by the initial response representation, it can request one or more 260 of the alternative representations, selected based on metadata 261 (e.g., available media types) included in the response. 263 Representation: A serialization that represents the current or 264 intended state of a resource and that can be transferred between 265 client and server. REST requires representations to be self- 266 describing, meaning that there must be metadata that allows peers 267 to understand which representation format is used. Depending on 268 the protocol needs and capabilities, there can be additional 269 metadata that is transmitted along with the representation. 271 Representation Format: A set of rules for serializing resource 272 state. On the Web, the most prevalent representation format is 273 HTML. Other common formats include plain text and formats based 274 on JSON [RFC8259], XML, or RDF. Within IoT systems, often compact 275 formats based on JSON, CBOR [RFC8949], and EXI 276 [W3C.REC-exi-20110310] are used. 278 Representational State Transfer (REST): An architectural style for 279 Internet-scale distributed hypermedia systems. 281 Resource: An item of interest identified by a URI. Anything that 282 can be named can be a resource. A resource often encapsulates a 283 piece of state in a system. Typical resources in an IoT system 284 can be, e.g., a sensor, the current value of a sensor, the 285 location of a device, or the current state of an actuator. 287 Resource State: A model of the possible states of a resource that is 288 expressed in supported representation formats. Resources can 289 change state because of REST interactions with them, or they can 290 change state for reasons outside of the REST model, e.g., business 291 logic implemented on the server side such as sampling a sensor. 293 Resource Type: An identifier that annotates the application- 294 semantics of a resource (see Section 3.1 of [RFC6690]). 296 Reverse Proxy: An intermediary that appears as a server towards the 297 client but satisfies the requests by forwarding them to the actual 298 server (possibly via one or more other intermediaries). A reverse 299 proxy is often used to encapsulate legacy services, to improve 300 server performance through caching, and to enable load balancing 301 across multiple machines. 303 Safe Method: A method that does not result in any state change on 304 the origin server when applied to a resource. 306 Server: A node that listens for requests, performs the requested 307 operation, and sends responses back to the clients. In RESTful 308 IoT systems it is common for nodes to have more than one role 309 (i.e., to be both server and client; see Section 3.1). 311 Thing: A physical item that is made available in the Internet of 312 Things, thereby enabling digital interaction with the physical 313 world for humans, services, and/or other Things. 315 Transfer protocols: In particular in the IoT domain, protocols above 316 the transport layer that are used to transfer data objects and 317 provide semantics for operations on the data. 319 Transfer layer: Re-usable part of the application layer used to 320 transfer the application specific data items using a standard set 321 of methods that can fulfill application-specific operations. 323 Uniform Resource Identifier (URI): A global identifier for 324 resources. See Section 3.3 for more details. 326 3. Basics 327 3.1. Architecture 329 The components of a RESTful system are assigned one or both of two 330 roles: client or server. Note that the terms "client" and "server" 331 refer only to the roles that the nodes assume for a particular 332 message exchange. The same node might act as a client in some 333 communications and a server in others. Classic user agents (e.g., 334 Web browsers) are always in the client role and have the initiative 335 to issue requests. Origin servers always have the server role and 336 govern over the resources they host. Simple IoT devices, such as 337 sensors and actuators, are commonly acting as servers and exposing 338 their physical world interaction capabilities (e.g., temperature 339 measurement or door lock control capability) as resources. 341 Which resources exist and how they can be used is expressed by the 342 servers in so-called affordances, which is metadata that can be 343 included in responses (e.g., the initial response from a well-known 344 resource) or be made available out of band (e.g., through a W3C Thing 345 Description document [W3C-TD] from a directory). In RESTful systems, 346 affordances are encoded as hypermedia controls of which exist two 347 types: links that allow to navigate between resources and forms that 348 enable clients to formulate more complex requests (e.g., to modify a 349 resource or perform a query). 351 A typical IoT system client can be a cloud service that retrieves 352 data from the sensors and commands the actuators based on the sensor 353 information. Alternatively an IoT data storage system could work as 354 a server where IoT sensor devices send their data in client role. 356 ________ _________ 357 | | | | 358 | User (C)-------------------(S) Origin | 359 | Agent | | Server | 360 |________| |_________| 361 (Browser) (Web Server) 363 Figure 1: Client-Server Communication 365 Intermediaries (such as forward proxies, reverse proxies, and 366 gateways) implement both roles, but only forward requests to other 367 intermediaries or origin servers. They can also translate requests 368 to different protocols, for instance, as CoAP-HTTP cross-proxies 369 [RFC8075]. 371 ________ __________ _________ 372 | | | | | | 373 | User (C)---(S) Inter- (C)--------------------(S) Origin | 374 | Agent | | mediary | | Server | 375 |________| |__________| |_________| 376 (Browser) (Forward Proxy) (Web Server) 378 Figure 2: Communication with Forward Proxy 380 Reverse proxies are usually imposed by the origin server. In 381 addition to the features of a forward proxy, they can also provide an 382 interface for non-RESTful services such as legacy systems or 383 alternative technologies such as Bluetooth ATT/GATT. In this case, 384 reverse proxies are usually called gateways. This property is 385 enabled by the Layered System constraint of REST, which says that a 386 client cannot see beyond the server it is connected to (i.e., it is 387 left unaware of the protocol/paradigm change). 389 ________ __________ _________ 390 | | | | | | 391 | User (C)--------------------(S) Inter- (x)---(x) Origin | 392 | Agent | | mediary | | Server | 393 |________| |__________| |_________| 394 (Browser) (Gateway) (Legacy System) 396 Figure 3: Communication with Reverse Proxy 398 Nodes in IoT systems often implement both roles. Unlike 399 intermediaries, however, they can take the initiative as a client 400 (e.g., to register with a directory, such as CoRE Resource Directory 401 [I-D.ietf-core-resource-directory], or to interact with another 402 Thing) and act as origin server at the same time (e.g., to serve 403 sensor values or provide an actuator interface). 405 ________ _________ 406 | | | | 407 | Thing (C)-------------------------------------(S) Origin | 408 | (S) | Server | 409 |________| \ |_________| 410 (Sensor) \ ________ (Resource Directory) 411 \ | | 412 (C) Thing | 413 |________| 414 (Controller) 416 Figure 4: Constrained RESTful environments 418 3.2. System design 420 When designing a RESTful system, the primary effort goes into 421 modeling the application as distributed state and assigning it to the 422 different components (i.e., clients and servers). The secondary 423 effort is then selecting or designing the necessary representation 424 formats to exchange information and enable interaction between the 425 components through resources. 427 How clients can navigate through the resource space and modify state 428 to achieve their goals is encoded in hypermedia controls, that is, 429 links and forms within the representations. The concept behind 430 hypermedia controls is to provide machine-understandable 431 "affordances" [HCI], which refer to the perceived and actual 432 properties of a Thing and determine how it could possibly be used. A 433 physical door may have a door knob as affordance, indicating that the 434 door can be opened by twisting the knob; a keyhole may indicate that 435 it can be locked. For Things in the IoT, these affordances may be 436 serialized as two hypermedia forms, which include semantic 437 identifiers from a controlled vocabulary (e.g., schema.org) and the 438 instructions on how to formulate the requests for opening and 439 locking, respectively. Overall, this allows to realize a Uniform 440 Interface (see Section 4.4), which enables loose coupling between 441 clients and servers. 443 Hypermedia controls span a kind of state machine where the nodes are 444 resources (or action results) and the transitions are links or forms. 445 Clients run this distributed state machine (i.e., the application) by 446 retrieving representations, processing the data, and following the 447 included links and/or submitting forms to modify remote state. This 448 is usually done by retrieving the current state, modifying the state 449 on the client side, and transferring the new state to the server in 450 the form of new representations -- rather than calling a service and 451 modifying the state on the server side. 453 Client state encompasses the current state of the described state 454 machine and the possible next transitions derived from the hypermedia 455 controls within the currently processed representation. Furthermore, 456 clients can have part of the state of the distributed application in 457 local variables. 459 Resource state includes the more persistent data of an application 460 (i.e., independent of individual clients). This can be static data 461 such as device descriptions, persistent data such as system 462 configurations, but also dynamic data such as the current value of a 463 sensor on a Thing. 465 In the design, it is important to distinguish between "client state" 466 and "resource state", and keep them separate. Following the 467 Stateless constraint, the client state must be kept only on clients. 468 That is, there is no establishment of shared information about past 469 and future interactions between client and server (usually called a 470 session). On the one hand, this makes requests a bit more verbose 471 since every request must contain all the information necessary to 472 process it. On the other hand, this makes servers efficient and 473 scalable, since they do not have to keep any state about their 474 clients. Requests can easily be distributed over multiple worker 475 threads or server instances (cf. load balancing). For IoT systems, 476 this constraint lowers the memory requirements for server 477 implementations, which is particularly important for constrained 478 servers (e.g., sensor nodes) and servers serving large amount of 479 clients (e.g., Resource Directory). 481 3.3. Uniform Resource Identifiers (URIs) 483 An important aspect of RESTful API design is to model the system as a 484 set of resources, which potentially can be created and/or deleted 485 dynamically and whose state can be retrieved and/or modified. 487 Uniform Resource Identifiers (URIs) are used to indicate resources 488 for interaction, to reference a resource from another resource, to 489 advertise or bookmark a resource, or to index a resource by search 490 engines. 492 foo://example.com:8042/over/there?name=ferret#nose 493 \_/ \______________/\_________/ \_________/ \__/ 494 | | | | | 495 scheme authority path query fragment 497 A URI is a sequence of characters that matches the syntax defined in 498 [RFC3986]. It consists of a hierarchical sequence of five 499 components: scheme, authority, path, query, and fragment (from most 500 significant to least significant). A scheme creates a namespace for 501 resources and defines how the following components identify a 502 resource within that namespace. The authority identifies an entity 503 that governs part of the namespace, such as the server 504 "www.example.org" in the "https" scheme. A hostname (e.g., a fully 505 qualified domain name) or an IP address literal, potentially followed 506 by a transport layer port number, are usually used for the authority 507 component. The path and query contain data to identify a resource 508 within the scope of the scheme-dependent naming authority (i.e., 509 "http://www.example.org/" is a different authority than 510 "https://www.example.org"). The fragment allows referring to some 511 portion of the resource, such as a Record in a SenML Pack (Section 9 512 of [RFC8428]). However, fragments are processed only at client side 513 and not sent on the wire. [RFC8820] provides more details on URI 514 design and ownership with best current practices for establishing URI 515 structures, conventions, and formats. 517 For RESTful IoT applications, typical schemes include "https", 518 "coaps", "http", and "coap". These refer to HTTP and CoAP, with and 519 without Transport Layer Security (TLS, [RFC5246] for TLS 1.2 and 520 [RFC8446] for TLS 1.3). (CoAP uses Datagram TLS (DTLS) [RFC6347], 521 the variant of TLS for UDP.) These four schemes also provide means 522 for locating the resource; using the protocols HTTP for "http" and 523 "https" and CoAP for "coap" and "coaps". If the scheme is different 524 for two URIs (e.g., "coap" vs. "coaps"), it is important to note that 525 even if the remainder of the URI is identical, these are two 526 different resources, in two distinct namespaces. 528 Some schemes are for URIs with main purpose as identifiers, and hence 529 are not dereferenceable, e.g., the "urn" scheme can be used to 530 construct unique names in registered namespaces. In particular the 531 "urn:dev" URI [RFC9039] details multiple ways for generating and 532 representing endpoint identifiers of IoT devices. 534 The query parameters can be used to parameterize the resource. For 535 example, a GET request may use query parameters to request the server 536 to send only certain kind data of the resource (i.e., filtering the 537 response). Query parameters in PUT and POST requests do not have 538 such established semantics and are not used consistently. Whether 539 the order of the query parameters matters in URIs is unspecified; 540 they can be re-ordered, for instance by proxies. Therefore, 541 applications should not rely on their order; see Section 3.3.4 of 542 [RFC6943] for more details. 544 Due to the relatively complex processing rules and text 545 representation format, URI handling can be difficult to implement 546 correctly in constrained devices. Constrained Resource Identifiers 547 [I-D.ietf-core-href] provide a CBOR-based format of URIs that is 548 better suited also for resource constrained IoT devices. 550 3.4. Representations 552 Clients can retrieve the resource state from a server or manipulate 553 resource state on the (origin) server by transferring resource 554 representations. Resource representations must have metadata that 555 identifies the representation format used, so the representations can 556 be interpreted correctly. This is usually a simple string such as 557 the IANA-registered Internet Media Types. Typical media types for 558 IoT systems include: 560 * "text/plain" for simple UTF-8 text 561 * "application/octet-stream" for arbitrary binary data 563 * "application/json" for the JSON format [RFC8259] 565 * "application/cbor" for CBOR [RFC8949] 567 * "application/exi" for EXI [W3C.REC-exi-20110310] 569 * "application/link-format" for CoRE Link Format [RFC6690] 571 * "application/senml+json" and "application/senml+cbor" for Sensor 572 Measurement Lists (SenML) data [RFC8428] 574 A full list of registered Internet Media Types is available at the 575 IANA registry [IANA-media-types] and numerical identifiers for media 576 types, parameters, and content codings registered for use with CoAP 577 are listed at CoAP Content-Formats IANA registry [IANA-CoAP-media]. 579 The terms "media type", "content type" (media type plus potential 580 parameters), and "content format" (short identifier of content type 581 and content coding, abbreviated for historical reasons "ct") are 582 often used when referring to representation formats used with CoAP. 583 The differences between these terms are discussed in more detail in 584 [I-D.bormann-core-media-content-type-format]. 586 3.5. HTTP/CoAP Methods 588 Section 4.3 of [RFC7231] defines the set of methods in HTTP; 589 Section 5.8 of [RFC7252] defines the set of methods in CoAP. As part 590 of the Uniform Interface constraint, each method can have certain 591 properties that give guarantees to clients. 593 Safe methods do not cause any state change on the origin server when 594 applied to a resource. For example, the GET method only returns a 595 representation of the resource state but does not change the 596 resource. Thus, it is always safe for a client to retrieve a 597 representation without affecting server-side state. 599 Idempotent methods can be applied multiple times to the same resource 600 while causing the same visible resource state as a single such 601 request. For example, the PUT method replaces the state of a 602 resource with a new state; replacing the state multiple times with 603 the same new state still results in the same state for the resource. 604 However, the response from the server can be different when the same 605 idempotent method is used multiple times. For example when DELETE is 606 used twice on an existing resource, the first request would remove 607 the association and return success acknowledgement whereas the second 608 request would likely result in error response due to non-existing 609 resource. 611 The following lists the most relevant methods and gives a short 612 explanation of their semantics. 614 3.5.1. GET 616 The GET method requests a current representation for the target 617 resource, while the origin server must ensure that there are no side 618 effects on the resource state. Only the origin server needs to know 619 how each of its resource identifiers corresponds to an implementation 620 and how each implementation manages to select and send a current 621 representation of the target resource in a response to GET. 623 A payload within a GET request message has no defined semantics. 625 The GET method is safe and idempotent. 627 3.5.2. POST 629 The POST method requests that the target resource process the 630 representation enclosed in the request according to the resource's 631 own specific semantics. 633 If one or more resources has been created on the origin server as a 634 result of successfully processing a POST request, the origin server 635 sends a 201 (Created) response containing a Location header field 636 (with HTTP) or Location-Path and/or Location-Query Options (with 637 CoAP) that provide an identifier for the resource created. The 638 server also includes a representation that describes the status of 639 the request while referring to the new resource(s). 641 The POST method is not safe nor idempotent. 643 3.5.3. PUT 645 The PUT method requests that the state of the target resource be 646 created or replaced with the state defined by the representation 647 enclosed in the request message payload. A successful PUT of a given 648 representation would suggest that a subsequent GET on that same 649 target resource will result in an equivalent representation being 650 sent. A PUT request applied to the target resource can have side 651 effects on other resources. 653 The fundamental difference between the POST and PUT methods is 654 highlighted by the different intent for the enclosed representation. 655 The target resource in a POST request is intended to handle the 656 enclosed representation according to the resource's own semantics, 657 whereas the enclosed representation in a PUT request is defined as 658 replacing the state of the target resource. Hence, the intent of PUT 659 is idempotent and visible to intermediaries, even though the exact 660 effect is only known by the origin server. 662 The PUT method is not safe, but is idempotent. 664 3.5.4. DELETE 666 The DELETE method requests that the origin server remove the 667 association between the target resource and its current 668 functionality. 670 If the target resource has one or more current representations, they 671 might or might not be destroyed by the origin server, and the 672 associated storage might or might not be reclaimed, depending 673 entirely on the nature of the resource and its implementation by the 674 origin server. 676 The DELETE method is not safe, but is idempotent. 678 3.5.5. FETCH 680 The CoAP-specific FETCH method [RFC8132] requests a representation of 681 a resource parameterized by a representation enclosed in the request. 683 The fundamental difference between the GET and FETCH methods is that 684 the request parameters are included as the payload of a FETCH 685 request, while in a GET request they're typically part of the query 686 string of the request URI. 688 The FETCH method is safe and idempotent. 690 3.5.6. PATCH 692 The PATCH method [RFC5789] [RFC8132] requests that a set of changes 693 described in the request entity be applied to the target resource. 695 The PATCH method is not safe nor idempotent. 697 The CoAP-specific iPATCH method is a variant of the PATCH method that 698 is not safe, but is idempotent. 700 3.6. HTTP/CoAP Status/Response Codes 702 Section 6 of [RFC7231] defines a set of Status Codes in HTTP that are 703 used by application to indicate whether a request was understood and 704 satisfied, and how to interpret the answer. Similarly, Section 5.9 705 of [RFC7252] defines the set of Response Codes in CoAP. 707 The status codes consist of three digits (e.g., "404" with HTTP or 708 "4.04" with CoAP) where the first digit expresses the class of the 709 code. Implementations do not need to understand all status codes, 710 but the class of the code must be understood. Codes starting with 1 711 are informational; the request was received and being processed. 712 Codes starting with 2 indicate a successful request. Codes starting 713 with 3 indicate redirection; further action is needed to complete the 714 request. Codes stating with 4 and 5 indicate errors. The codes 715 starting with 4 mean client error (e.g., bad syntax in the request) 716 whereas codes starting with 5 mean server error; there was no 717 apparent problem with the request, but server was not able to fulfill 718 the request. 720 Responses may be stored in a cache to satisfy future, equivalent 721 requests. HTTP and CoAP use two different patterns to decide what 722 responses are cacheable. In HTTP, the cacheability of a response 723 depends on the request method (e.g., responses returned in reply to a 724 GET request are cacheable). In CoAP, the cacheability of a response 725 depends on the response code (e.g., responses with code 2.04 are 726 cacheable). This difference also leads to slightly different 727 semantics for the codes starting with 2; for example, CoAP does not 728 have a 2.00 response code whereas 200 ("OK") is commonly used with 729 HTTP. 731 4. REST Constraints 733 The REST architectural style defines a set of constraints for the 734 system design. When all constraints are applied correctly, REST 735 enables architectural properties of key interest [REST]: 737 * Performance 738 * Scalability 740 * Reliability 742 * Simplicity 744 * Modifiability 746 * Visibility 748 * Portability 750 The following subsections briefly summarize the REST constraints and 751 explain how they enable the listed properties. 753 4.1. Client-Server 755 As explained in the Architecture section, RESTful system components 756 have clear roles in every interaction. Clients have the initiative 757 to issue requests, intermediaries can only forward requests, and 758 servers respond requests, while origin servers are the ultimate 759 recipient of requests that intent to modify resource state. 761 This improves simplicity and visibility (also for digital forensics), 762 as it is clear which component started an interaction. Furthermore, 763 it improves modifiability through a clear separation of concerns. 765 In IoT systems, endpoints often assume both roles of client and 766 (origin) server simultaneously. When an IoT device has initiative 767 (because there is a user, e.g., pressing a button, or installed 768 rules/policies), it acts as a client. When a device offers a 769 service, it is in server role. 771 4.2. Stateless 773 The Stateless constraint requires messages to be self-contained. 774 They must contain all the information to process it, independent from 775 previous messages. This allows to strictly separate the client state 776 from the resource state. 778 This improves scalability and reliability, since servers or worker 779 threads can be replicated. It also improves visibility because 780 message traces contain all the information to understand the logged 781 interactions. Furthermore, the Stateless constraint enables caching. 783 For IoT, the scaling properties of REST become particularly 784 important. Note that being self-contained does not necessarily mean 785 that all information has to be inlined. Constrained IoT devices may 786 choose to externalize metadata and hypermedia controls using Web 787 linking, so that only the dynamic content needs to be sent and the 788 static content such as schemas or controls can be cached. 790 4.3. Cache 792 This constraint requires responses to have implicit or explicit 793 cache-control metadata. This enables clients and intermediary to 794 store responses and re-use them to locally answer future requests. 795 The cache-control metadata is necessary to decide whether the 796 information in the cached response is still fresh or stale and needs 797 to be discarded. 799 Cache improves performance, as less data needs to be transferred and 800 response times can be reduced significantly. Needing fewer transfers 801 also improves scalability, as origin servers can be protected from 802 too many requests. Local caches furthermore improve reliability, 803 since requests can be answered even if the origin server is 804 temporarily not available. 806 Caching usually only makes sense when the data is used by multiple 807 participants. In IoT systems, however, it might make sense to cache 808 also individual data to protect constrained devices and networks from 809 frequent requests of data that does not change often. Security often 810 hinders the ability to cache responses. For IoT systems, object 811 security [RFC8613] may be preferable over transport layer security, 812 as it enables intermediaries to cache responses while preserving 813 security. 815 4.4. Uniform Interface 817 All RESTful APIs use the same, uniform interface independent of the 818 application. This simple interaction model is enabled by exchanging 819 representations and modifying state locally, which simplifies the 820 interface between clients and servers to a small set of methods to 821 retrieve, update, and delete state -- which applies to all 822 applications. 824 In contrast, in a service-oriented RPC approach, all required ways to 825 modify state need to be modeled explicitly in the interface resulting 826 in a large set of methods -- which differs from application to 827 application. Moreover, it is also likely that different parties come 828 up with different ways how to modify state, including the naming of 829 the procedures, while the state within an application is a bit easier 830 to agree on. 832 A REST interface is fully defined by: 834 * URIs to identify resources 836 * representation formats to represent and manipulate resource state 838 * self-descriptive messages with a standard set of methods (e.g., 839 GET, POST, PUT, DELETE with their guaranteed properties) 841 * hypermedia controls within representations 843 The concept of hypermedia controls is also known as HATEOAS: 844 Hypermedia As The Engine Of Application State. The origin server 845 embeds controls for the interface into its representations and 846 thereby informs the client about possible next requests. The most 847 used control for RESTful systems today is Web Linking [RFC8288]. 848 Hypermedia forms are more powerful controls that describe how to 849 construct more complex requests, including representations to modify 850 resource state. 852 While this is the most complex constraints (in particular the 853 hypermedia controls), it improves many key properties. It improves 854 simplicity, as uniform interfaces are easier to understand. The 855 self-descriptive messages improve visibility. The limitation to a 856 known set of representation formats fosters portability. Most of 857 all, however, this constraint is the key to modifiability, as 858 hypermedia-driven, uniform interfaces allow clients and servers to 859 evolve independently, and hence enable a system to evolve. 861 For a large number of IoT applications, the hypermedia controls are 862 mainly used for the discovery of resources, as they often serve 863 sensor data. Such resources are "dead ends", as they usually do not 864 link any further and only have one form of interaction: fetching the 865 sensor value. For IoT, the critical parts of the Uniform Interface 866 constraint are the descriptions of messages and representation 867 formats used. Simply using, for instance, "application/json" does 868 not help machine clients to understand the semantics of the 869 representation. Yet defining very precise media types limits the re- 870 usability and interoperability. Representation formats such as SenML 871 [RFC8428] try to find a good trade-off between precision and re- 872 usability. Another approach is to combine a generic format such as 873 JSON with syntactic as well as semantic annotations (see 874 [I-D.handrews-json-schema-validation] and [W3C-TD], resp.). 876 4.5. Layered System 878 This constraint enforces that a client cannot see beyond the server 879 with which it is interacting. 881 A layered system is easier to modify, as topology changes become 882 transparent. Furthermore, this helps scalability, as intermediaries 883 such as load balancers can be introduced without changing the client 884 side. The clean separation of concerns helps with simplicity. 886 IoT systems greatly benefit from this constraint, as it allows to 887 effectively shield constrained devices behind intermediaries and is 888 also the basis for gateways, which are used to integrate other (IoT) 889 ecosystems. 891 4.6. Code-on-Demand 893 This principle enables origin servers to ship code to clients. 895 Code-on-Demand improves modifiability, since new features can be 896 deployed during runtime (e.g., support for a new representation 897 format). It also improves performance, as the server can provide 898 code for local pre-processing before transferring the data. 900 As of today, code-on-demand has not been explored much in IoT 901 systems. Aspects to consider are that either one or both nodes are 902 constrained and might not have the resources to host or dynamically 903 fetch and execute such code. Moreover, the origin server often has 904 no understanding of the actual application a mashup client realizes. 905 Still, code-on-demand can be useful for small polyfills, e.g., to 906 decode payloads, and potentially other features in the future. 908 5. Hypermedia-driven Applications 910 Hypermedia-driven applications take advantage of hypermedia controls, 911 i.e., links and forms, which are embedded in representations or 912 response message headers. A hypermedia client is a client that is 913 capable of processing these hypermedia controls. Hypermedia links 914 can be used to give additional information about a resource 915 representation (e.g., the source URI of the representation) or 916 pointing to other resources. The forms can be used to describe the 917 structure of the data that can be sent (e.g., with a POST or PUT 918 method) to a server, or how a data retrieval (e.g., GET) request for 919 a resource should be formed. In a hypermedia-driven application the 920 client interacts with the server using only the hypermedia controls, 921 instead of selecting methods and/or constructing URIs based on out- 922 of-band information, such as API documentation. The Constrained 923 RESTful Application Language (CoRAL) [I-D.ietf-core-coral] provides a 924 hypermedia-format that is suitable for constrained IoT environments. 926 5.1. Motivation 928 The advantage of this approach is increased evolvability and 929 extensibility. This is important in scenarios where servers exhibit 930 a range of feature variations, where it's expensive to keep evolving 931 client knowledge and server knowledge in sync all the time, or where 932 there are many different client and server implementations. 933 Hypermedia controls serve as indicators in capability negotiation. 934 In particular, they describe available resources and possible 935 operations on these resources using links and forms, respectively. 937 There are multiple reasons why a server might introduce new links or 938 forms: 940 * The server implements a newer version of the application. Older 941 clients ignore the new links and forms, while newer clients are 942 able to take advantage of the new features by following the new 943 links and submitting the new forms. 945 * The server offers links and forms depending on the current state. 946 The server can tell the client which operations are currently 947 valid and thus help the client navigate the application state 948 machine. The client does not have to have knowledge which 949 operations are allowed in the current state or make a request just 950 to find out that the operation is not valid. 952 * The server offers links and forms depending on the client's access 953 control rights. If the client is unauthorized to perform a 954 certain operation, then the server can simply omit the links and 955 forms for that operation. 957 5.2. Knowledge 959 A client needs to have knowledge of a couple of things for successful 960 interaction with a server. This includes what resources are 961 available, what representations of resource states are available, 962 what each representation describes, how to retrieve a representation, 963 what state changing operations on a resource are possible, how to 964 perform these operations, and so on. 966 Some part of this knowledge, such as how to retrieve the 967 representation of a resource state, is typically hard-coded in the 968 client software. For other parts, a choice can often be made between 969 hard-coding the knowledge or acquiring it on-demand. The key to 970 success in either case is the use of in-band information for 971 identifying the knowledge that is required. This enables the client 972 to verify that it has all the required knowledge or to acquire 973 missing knowledge on-demand. 975 A hypermedia-driven application typically uses the following 976 identifiers: 978 * URI schemes that identify communication protocols, 980 * Internet Media Types that identify representation formats, 982 * link relation types or resource types that identify link 983 semantics, 985 * form relation types that identify form semantics, 987 * variable names that identify the semantics of variables in 988 templated links, and 990 * form field names that identify the semantics of form fields in 991 forms. 993 The knowledge about these identifiers as well as matching 994 implementations have to be shared a priori in a RESTful system. 996 5.3. Interaction 998 A client begins interacting with an application through a GET request 999 on an entry point URI. The entry point URI is the only URI a client 1000 is expected to know before interacting with an application. From 1001 there, the client is expected to make all requests by following links 1002 and submitting forms that are provided in previous responses. The 1003 entry point URI can be obtained, for example, by manual configuration 1004 or some discovery process (e.g., DNS-SD [RFC6763] or Resource 1005 Directory [I-D.ietf-core-resource-directory]). For Constrained 1006 RESTful environments "/.well-known/core" relative URI is defined as a 1007 default entry point for requesting the links hosted by servers with 1008 known or discovered addresses [RFC6690]. 1010 5.4. Hypermedia-driven Design Guidance 1012 Assuming self-describing representation formats (i.e., human-readable 1013 with carefully chosen terms or processable by a formatting tool) and 1014 a client supporting the URI scheme used, a good rule of thumb for a 1015 good hypermedia-driven design is the following: A developer should 1016 only need an entry point URI to drive the application. All further 1017 information how to navigate through the application (links) and how 1018 to construct more complex requests (forms) are published by the 1019 server(s). There must be no need for additional, out-of-band 1020 information (e.g., API specification). 1022 For machines, a well-chosen set of information needs to be shared a 1023 priori to agree on machine-understandable semantics. Agreeing on the 1024 exact semantics of terms for relation types and data elements will of 1025 course also help the developer. [I-D.hartke-core-apps] proposes a 1026 convention for specifying the set of information in a structured way. 1028 6. Design Patterns 1030 Certain kinds of design problems are often recurring in variety of 1031 domains, and often re-usable design patterns can be applied to them. 1032 Also, some interactions with a RESTful IoT system are straightforward 1033 to design; a classic example of reading a temperature from a 1034 thermometer device is almost always implemented as a GET request to a 1035 resource that represents the current value of the thermometer. 1036 However, certain interactions, for example data conversions or event 1037 handling, do not have as straightforward and well established ways to 1038 represent the logic with resources and REST methods. 1040 The following sections describe how common design problems such as 1041 different interactions can be modeled with REST and what are the 1042 benefits of different approaches. 1044 6.1. Collections 1046 A common pattern in RESTful systems across different domains is the 1047 collection. A collection can be used to combine multiple resources 1048 together by providing resources that consist of set of (often 1049 partial) representations of resources, called items, and links to 1050 resources. The collection resource also defines hypermedia controls 1051 for managing and searching the items in the collection. 1053 Examples of the collection pattern in RESTful IoT systems are the 1054 CoRE Resource Directory [I-D.ietf-core-resource-directory], CoAP pub/ 1055 sub broker [I-D.ietf-core-coap-pubsub], and resource discovery via 1056 ".well-known/core". Collection+JSON [CollectionJSON] is an example 1057 of a generic collection Media Type. 1059 6.2. Calling a Procedure 1061 To modify resource state, clients usually use GET to retrieve a 1062 representation from the server, modify that locally, and transfer the 1063 resulting state back to the server with a PUT (see Section 4.4). 1064 Sometimes, however, the state can only be modified on the server 1065 side, for instance, because representations would be too large to 1066 transfer or part of the required information shall not be accessible 1067 to clients. In this case, resource state is modified by calling a 1068 procedure (or "function"). This is usually modeled with a POST 1069 request, as this method leaves the behavior semantics completely to 1070 the server. Procedure calls can be divided into two different 1071 classes based on how long they are expected to execute: "instantly" 1072 returning and long-running. 1074 6.2.1. Instantly Returning Procedures 1076 When the procedure can return within the expected response time of 1077 the system, the result can be directly returned in the response. The 1078 result can either be actual content or just a confirmation that the 1079 call was successful. In either case, the response does not contain a 1080 representation of the resource, but a so-called action result. 1081 Action results can still have hypermedia controls to provide the 1082 possible transitions in the application state machine. 1084 6.2.2. Long-running Procedures 1086 When the procedure takes longer than the expected response time of 1087 the system, or even longer than the response timeout, it is a good 1088 pattern to create a new resource to track the "task" execution. The 1089 server would respond instantly with a "Created" status (HTTP code 201 1090 or CoAP 2.01) and indicate the location of the task resource in the 1091 corresponding header field (or CoAP option) or as a link in the 1092 action result. The created resource can be used to monitor the 1093 progress, to potentially modify queued tasks or cancel tasks, and to 1094 eventually retrieve the result. 1096 Monitoring information would be modeled as state of the task 1097 resource, and hence be retrievable as representation. The result -- 1098 when available -- can be embedded in the representation or given as a 1099 link to another sub-resource. Modifying tasks can be modeled with 1100 forms that either update sub-resources via PUT or do a partial write 1101 using PATCH or POST. Canceling a task would be modeled with a form 1102 that uses DELETE to remove the task resource. 1104 6.2.3. Conversion 1106 A conversion service is a good example where REST resources need to 1107 behave more like a procedure call. The knowledge of converting from 1108 one representation to another is located only at the server to 1109 relieve clients from high processing or storing lots of data. There 1110 are different approaches that all depend on the particular conversion 1111 problem. 1113 As mentioned in the previous sections, POST request are a good way to 1114 model functionality that does not necessarily affect resource state. 1115 When the input data for the conversion is small and the conversion 1116 result is deterministic, however, it can be better to use a GET 1117 request with the input data in the URI query part. The query is 1118 parameterizing the conversion resource, so that it acts like a look- 1119 up table. The benefit is that results can be cached also for HTTP 1120 (where responses to POST are not cacheable). In CoAP, cacheability 1121 depends on the response code, so that also a response to a POST 1122 request can be made cacheable through a 2.05 Content code. 1124 When the input data is large or has a binary encoding, it is better 1125 to use POST requests with a proper Media Type for the input 1126 representation. A POST request is also more suitable, when the 1127 result is time-dependent and the latest result is expected (e.g., 1128 exchange rates). 1130 6.2.4. Events as State 1132 In event-centric paradigms such as pub/sub, events are usually 1133 represented by an incoming message that might even be identical for 1134 each occurrence. Since the messages are queued, the receiver is 1135 aware of each occurrence of the event and can react accordingly. For 1136 instance, in an event-centric system, ringing a doorbell would result 1137 in a message being sent that represents the event that it was rung. 1139 In resource-oriented paradigms such as REST, messages usually carry 1140 the current state of the remote resource, independent from the 1141 changes (i.e., events) that have lead to that state. In a naive yet 1142 natural design, a doorbell could be modeled as a resource that can 1143 have the states unpressed and pressed. There are, however, a few 1144 issues with this approach. Polling (i.e., periodically retrieving) 1145 the doorbell resource state is not a good option, as the client is 1146 highly unlikely to be able to observe all the changes in the pressed 1147 state with any realistic polling interval. When using CoAP Observe 1148 with Confirmable notifications, the server will usually send two 1149 notifications for the event that the doorbell was pressed: 1150 notification for changing from unpressed to pressed and another one 1151 for changing back to unpressed. If the time between the state 1152 changes is very short, the server might drop the first notification, 1153 as Observe only guarantees eventual consistency (see Section 1.3 of 1154 [RFC7641]). 1156 The solution is to pick a state model that fits better to the 1157 application. In the case of the doorbell -- and many other event- 1158 driven resources -- the solution could be a counter that counts how 1159 often the bell was pressed. The corresponding action is taken each 1160 time the client observes a change in the received representation. In 1161 the case of a network outage, this could lead to a ringing sound long 1162 after the bell was rung. Also including a timestamp of the last 1163 counter increment in the state can help to suppress ringing a sound 1164 when the event has become obsolete. Another solution would be to 1165 change the client/server roles of the doorbell button and the ringer, 1166 as described in Section 6.3. 1168 6.3. Server Push 1170 Overall, a universal mechanism for server push, that is, change-of- 1171 state notifications and stand-alone event notifications, is still an 1172 open issue that is being discussed in the Thing-to-Thing Research 1173 Group. It is connected to the state-event duality problem and 1174 custody transfer, that is, the transfer of the responsibility that a 1175 message (e.g., event) is delivered successfully. 1177 A proficient mechanism for change-of-state notifications is currently 1178 only available for CoAP: Observing resources [RFC7641]. The CoAP 1179 Observe mechanism offers eventual consistency, which guarantees "that 1180 if the resource does not undergo a new change in state, eventually 1181 all registered observers will have a current representation of the 1182 latest resource state". It intrinsically deals with the challenges 1183 of lossy networks, where notifications might be lost, and constrained 1184 networks, where there might not be enough bandwidth to propagate all 1185 changes. 1187 For stand-alone event notifications, that is, where every single 1188 notification contains an identifiable event that must not be lost, 1189 observing resources is not a good fit. A better strategy is to model 1190 each event as a new resource, whose existence is notified through 1191 change-of-state notifications of an index resource (cf. Collection 1192 pattern). Large numbers of events will cause the notification to 1193 grow large, as it needs to contain a large number of Web links. 1194 Block-wise transfers [RFC7959] can help here. When the links are 1195 ordered by freshness of the events, the first block can already 1196 contain all links to new events. Then, observers do not need to 1197 retrieve the remaining blocks from the server, but only the 1198 representations of the new event resources. 1200 An alternative pattern is to exploit the dual roles of IoT devices, 1201 in particular when using CoAP: they are usually client and server at 1202 the same time. An endpoint interested in observing the events would 1203 subscribe to them by registering a callback URI at the origin server, 1204 e.g., using a POST request with the URI or a hypermedia document in 1205 the payload, and receiving the location of a temporary "subscription 1206 resource" as handle in the response. The origin server would then 1207 publish events by sending requests containing the event data to the 1208 observer's callback URI; here POST can be used to add events to a 1209 collection located at the callback URI or PUT can be used when the 1210 event data is a new state that shall replace the outdated state at 1211 the callback URI. The cancellation can be modeled through deleting 1212 the subscription resource. This pattern makes the origin server 1213 responsible for delivering the event notifications. This goes beyond 1214 retransmissions of messages; the origin server is usually supposed to 1215 queue all undelivered events and to retry until successful delivery 1216 or explicit cancellation. In HTTP, this pattern is known as REST 1217 Hooks. 1219 Methods for configuring server push and notification conditions with 1220 CoAP are provided by the CoRE Dynamic Resource Linking specification 1221 [I-D.ietf-core-dynlink]. 1223 In HTTP, there exist a number of workarounds to enable server push, 1224 e.g., long polling and streaming [RFC6202] or server-sent events 1225 [W3C.REC-html5-20141028]. In IoT systems, long polling can introduce 1226 a considerable overhead, as the request has to be repeated for each 1227 notification. Streaming and server-sent events (the latter is 1228 actually an evolution of the former) are more efficient, as only one 1229 request is sent. However, there is only one response header and 1230 subsequent notifications can only have content. Individual status 1231 and metadata needs to be included in the content message. This 1232 reduces HTTP again to a pure transport, as its status signaling and 1233 metadata capabilities cannot be used. 1235 7. Security Considerations 1237 This document does not define new functionality and therefore does 1238 not introduce new security concerns. We assume that system designers 1239 apply classic Web security on top of the basic RESTful guidance given 1240 in this document. Thus, security protocols and considerations from 1241 related specifications apply to RESTful IoT design. These include: 1243 * Transport Layer Security (TLS): [RFC8446], [RFC5246], and 1244 [RFC6347] 1246 * Internet X.509 Public Key Infrastructure: [RFC5280] 1248 * HTTP security: Section 9 of [RFC7230], Section 9 of [RFC7231], 1249 etc. 1251 * CoAP security: Section 11 of [RFC7252] 1252 * URI security: Section 7 of [RFC3986] 1254 IoT-specific security is active area of standardization at the time 1255 of writing. First finalized specifications include: 1257 * (D)TLS Profiles for the Internet of Things: [RFC7925] 1259 * CBOR Object Signing and Encryption (COSE) [RFC8152] 1261 * CBOR Web Token [RFC8392] 1263 * Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs) 1264 [RFC8747] 1266 * Object Security for Constrained RESTful Environments (OSCORE) 1267 [RFC8613] 1269 * Authentication and Authorization for Constrained Environments 1270 (ACE) using the OAuth 2.0 Framework [I-D.ietf-ace-oauth-authz] 1272 * ACE profiles for DTLS [I-D.ietf-ace-dtls-authorize] and OSCORE 1273 [I-D.ietf-ace-oscore-profile] 1275 Further IoT security considerations are available in [RFC8576]. 1277 8. Acknowledgement 1279 The authors would like to thank Mike Amundsen, Heidi-Maria Back, 1280 Carsten Bormann, Tero Kauppinen, Michael Koster, Mert Ocak, Robby 1281 Simpson, Ravi Subramaniam, Dave Thaler, Niklas Widell, and Erik Wilde 1282 for the reviews and feedback. 1284 9. References 1286 9.1. Normative References 1288 [I-D.ietf-core-coral] 1289 Amsüss, C. and T. Fossati, "The Constrained RESTful 1290 Application Language (CoRAL)", Work in Progress, Internet- 1291 Draft, draft-ietf-core-coral-04, 25 October 2021, 1292 . 1295 [I-D.ietf-core-dynlink] 1296 Koster, M. and B. Silverajan, "Dynamic Resource Linking 1297 for Constrained RESTful Environments", Work in Progress, 1298 Internet-Draft, draft-ietf-core-dynlink-14, 12 July 2021, 1299 . 1302 [I-D.ietf-core-href] 1303 Bormann, C. and H. Birkholz, "Constrained Resource 1304 Identifiers", Work in Progress, Internet-Draft, draft- 1305 ietf-core-href-09, 15 January 2022, 1306 . 1309 [I-D.ietf-core-resource-directory] 1310 Amsüss, C., Shelby, Z., Koster, M., Bormann, C., and P. V. 1311 D. Stok, "CoRE Resource Directory", Work in Progress, 1312 Internet-Draft, draft-ietf-core-resource-directory-28, 7 1313 March 2021, . 1316 [REST] Fielding, R., "Architectural Styles and the Design of 1317 Network-based Software Architectures", Ph.D. Dissertation, 1318 University of California, Irvine , 2000. 1320 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1321 Resource Identifier (URI): Generic Syntax", STD 66, 1322 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1323 . 1325 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1326 (TLS) Protocol Version 1.2", RFC 5246, 1327 DOI 10.17487/RFC5246, August 2008, 1328 . 1330 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1331 Housley, R., and W. Polk, "Internet X.509 Public Key 1332 Infrastructure Certificate and Certificate Revocation List 1333 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1334 . 1336 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 1337 "Known Issues and Best Practices for the Use of Long 1338 Polling and Streaming in Bidirectional HTTP", RFC 6202, 1339 DOI 10.17487/RFC6202, April 2011, 1340 . 1342 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1343 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1344 January 2012, . 1346 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1347 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1348 . 1350 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1351 Protocol (HTTP/1.1): Message Syntax and Routing", 1352 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1353 . 1355 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1356 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1357 DOI 10.17487/RFC7231, June 2014, 1358 . 1360 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1361 Application Protocol (CoAP)", RFC 7641, 1362 DOI 10.17487/RFC7641, September 2015, 1363 . 1365 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1366 the Constrained Application Protocol (CoAP)", RFC 7959, 1367 DOI 10.17487/RFC7959, August 2016, 1368 . 1370 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 1371 DOI 10.17487/RFC8288, October 2017, 1372 . 1374 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1375 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1376 . 1378 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1379 "Object Security for Constrained RESTful Environments 1380 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 1381 . 1383 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1384 Representation (CBOR)", STD 94, RFC 8949, 1385 DOI 10.17487/RFC8949, December 2020, 1386 . 1388 [RFC9039] Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource 1389 Names for Device Identifiers", RFC 9039, 1390 DOI 10.17487/RFC9039, June 2021, 1391 . 1393 [W3C.REC-exi-20110310] 1394 Schneider, J. and T. Kamiya, "Efficient XML Interchange 1395 (EXI) Format 1.0", World Wide Web Consortium 1396 Recommendation REC-exi-20110310, 10 March 2011, 1397 . 1399 [W3C.REC-html5-20141028] 1400 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 1401 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 1402 World Wide Web Consortium Recommendation REC- 1403 html5-20141028, 28 October 2014, 1404 . 1406 9.2. Informative References 1408 [CollectionJSON] 1409 Amundsen, M., "Collection+JSON - Document Format", 1410 February 2013, 1411 . 1413 [HCI] Interaction Design Foundation, "The Encyclopedia of Human- 1414 Computer Interaction", 2nd Ed., 2013, 1415 . 1418 [I-D.bormann-core-media-content-type-format] 1419 Bormann, C. and H. Birkholz, "On Media-Types, Content- 1420 Types, and related terminology", Work in Progress, 1421 Internet-Draft, draft-bormann-core-media-content-type- 1422 format-04, 22 February 2021, 1423 . 1426 [I-D.handrews-json-schema-validation] 1427 Wright, A., Andrews, H., and B. Hutton, "JSON Schema 1428 Validation: A Vocabulary for Structural Validation of 1429 JSON", Work in Progress, Internet-Draft, draft-handrews- 1430 json-schema-validation-02, 17 September 2019, 1431 . 1434 [I-D.hartke-core-apps] 1435 Hartke, K., "CoRE Applications", Work in Progress, 1436 Internet-Draft, draft-hartke-core-apps-08, 22 October 1437 2018, . 1440 [I-D.ietf-ace-dtls-authorize] 1441 Gerdes, S., Bergmann, O., Bormann, C., Selander, G., and 1442 L. Seitz, "Datagram Transport Layer Security (DTLS) 1443 Profile for Authentication and Authorization for 1444 Constrained Environments (ACE)", Work in Progress, 1445 Internet-Draft, draft-ietf-ace-dtls-authorize-18, 4 June 1446 2021, . 1449 [I-D.ietf-ace-oauth-authz] 1450 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1451 H. Tschofenig, "Authentication and Authorization for 1452 Constrained Environments (ACE) using the OAuth 2.0 1453 Framework (ACE-OAuth)", Work in Progress, Internet-Draft, 1454 draft-ietf-ace-oauth-authz-46, 8 November 2021, 1455 . 1458 [I-D.ietf-ace-oscore-profile] 1459 Palombini, F., Seitz, L., Selander, G., and M. Gunnarsson, 1460 "OSCORE Profile of the Authentication and Authorization 1461 for Constrained Environments Framework", Work in Progress, 1462 Internet-Draft, draft-ietf-ace-oscore-profile-19, 6 May 1463 2021, . 1466 [I-D.ietf-asdf-sdf] 1467 Koster, M. and C. Bormann, "Semantic Definition Format 1468 (SDF) for Data and Interactions of Things", Work in 1469 Progress, Internet-Draft, draft-ietf-asdf-sdf-10, 16 1470 January 2022, . 1473 [I-D.ietf-core-coap-pubsub] 1474 Koster, M., Keranen, A., and J. Jimenez, "Publish- 1475 Subscribe Broker for the Constrained Application Protocol 1476 (CoAP)", Work in Progress, Internet-Draft, draft-ietf- 1477 core-coap-pubsub-09, 30 September 2019, 1478 . 1481 [IANA-CoAP-media] 1482 "CoAP Content-Formats", n.d., 1483 . 1486 [IANA-media-types] 1487 "Media Types", n.d., . 1490 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1491 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1492 . 1494 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 1495 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 1496 . 1498 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1499 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1500 2013, . 1502 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1503 Constrained-Node Networks", RFC 7228, 1504 DOI 10.17487/RFC7228, May 2014, 1505 . 1507 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1508 Application Protocol (CoAP)", RFC 7252, 1509 DOI 10.17487/RFC7252, June 2014, 1510 . 1512 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1513 Security (TLS) / Datagram Transport Layer Security (DTLS) 1514 Profiles for the Internet of Things", RFC 7925, 1515 DOI 10.17487/RFC7925, July 2016, 1516 . 1518 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 1519 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 1520 the Constrained Application Protocol (CoAP)", RFC 8075, 1521 DOI 10.17487/RFC8075, February 2017, 1522 . 1524 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1525 FETCH Methods for the Constrained Application Protocol 1526 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1527 . 1529 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1530 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1531 . 1533 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1534 Interchange Format", STD 90, RFC 8259, 1535 DOI 10.17487/RFC8259, December 2017, 1536 . 1538 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, 1539 "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, 1540 May 2018, . 1542 [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 1543 Bormann, "Sensor Measurement Lists (SenML)", RFC 8428, 1544 DOI 10.17487/RFC8428, August 2018, 1545 . 1547 [RFC8576] Garcia-Morchon, O., Kumar, S., and M. Sethi, "Internet of 1548 Things (IoT) Security: State of the Art and Challenges", 1549 RFC 8576, DOI 10.17487/RFC8576, April 2019, 1550 . 1552 [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. 1553 Tschofenig, "Proof-of-Possession Key Semantics for CBOR 1554 Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March 1555 2020, . 1557 [RFC8820] Nottingham, M., "URI Design and Ownership", BCP 190, 1558 RFC 8820, DOI 10.17487/RFC8820, June 2020, 1559 . 1561 [W3C-TD] Kaebisch, S., Kamiya, T., McCool, M., Charpenay, V., and 1562 M. Kovatsch, "Web of Things (WoT) Thing Description", 1563 April 2020, 1564 . 1566 Authors' Addresses 1568 Ari Keranen 1569 Ericsson 1570 FI-02420 Jorvas 1571 Finland 1572 Email: ari.keranen@ericsson.com 1573 Matthias Kovatsch 1574 Huawei Technologies 1575 Riesstr. 25 1576 D-80992 Munich 1577 Germany 1578 Email: matthias.kovatsch@huawei.com 1580 Klaus Hartke 1581 Email: hartke@projectcool.de