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