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