idnits 2.17.1 draft-irtf-t2trg-rest-iot-03.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 426 has weird spacing: '... query frag...' -- The document date (April 19, 2019) is 1827 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'I-D.ietf-core-object-security' is defined on line 1178, but no explicit reference was found in the text == Outdated reference: A later version (-11) exists of draft-ietf-core-dev-urn-03 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-20 ** 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 (-02) exists of draft-handrews-json-schema-validation-01 == Outdated reference: A later version (-14) exists of draft-ietf-core-coap-pubsub-08 -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7320 (Obsoleted by RFC 8820) Summary: 7 errors (**), 0 flaws (~~), 7 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: October 21, 2019 Siemens AG 6 K. Hartke 7 Ericsson 8 April 19, 2019 10 RESTful Design for Internet of Things Systems 11 draft-irtf-t2trg-rest-iot-03 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 October 21, 2019. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 57 3.1. Architecture . . . . . . . . . . . . . . . . . . . . . . 7 58 3.2. System design . . . . . . . . . . . . . . . . . . . . . . 8 59 3.3. Uniform Resource Identifiers (URIs) . . . . . . . . . . . 9 60 3.4. Representations . . . . . . . . . . . . . . . . . . . . . 11 61 3.5. HTTP/CoAP Methods . . . . . . . . . . . . . . . . . . . . 11 62 3.5.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 12 63 3.5.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 12 64 3.5.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 12 65 3.5.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 13 66 3.5.5. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 13 67 3.5.6. PATCH . . . . . . . . . . . . . . . . . . . . . . . . 13 68 3.6. HTTP/CoAP Status/Response Codes . . . . . . . . . . . . . 14 69 4. REST Constraints . . . . . . . . . . . . . . . . . . . . . . 14 70 4.1. Client-Server . . . . . . . . . . . . . . . . . . . . . . 15 71 4.2. Stateless . . . . . . . . . . . . . . . . . . . . . . . . 15 72 4.3. Cache . . . . . . . . . . . . . . . . . . . . . . . . . . 15 73 4.4. Uniform Interface . . . . . . . . . . . . . . . . . . . . 16 74 4.5. Layered System . . . . . . . . . . . . . . . . . . . . . 17 75 4.6. Code-on-Demand . . . . . . . . . . . . . . . . . . . . . 18 76 5. Hypermedia-driven Applications . . . . . . . . . . . . . . . 18 77 5.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 18 78 5.2. Knowledge . . . . . . . . . . . . . . . . . . . . . . . . 19 79 5.3. Interaction . . . . . . . . . . . . . . . . . . . . . . . 20 80 5.4. Hypermedia-driven Design Guidance . . . . . . . . . . . . 20 81 6. Design Patterns . . . . . . . . . . . . . . . . . . . . . . . 20 82 6.1. Collections . . . . . . . . . . . . . . . . . . . . . . . 21 83 6.2. Calling a Procedure . . . . . . . . . . . . . . . . . . . 21 84 6.2.1. Instantly Returning Procedures . . . . . . . . . . . 21 85 6.2.2. Long-running Procedures . . . . . . . . . . . . . . . 22 86 6.2.3. Conversion . . . . . . . . . . . . . . . . . . . . . 22 87 6.2.4. Events as State . . . . . . . . . . . . . . . . . . . 23 88 6.3. Server Push . . . . . . . . . . . . . . . . . . . . . . . 23 89 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 90 8. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 25 91 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 92 9.1. Normative References . . . . . . . . . . . . . . . . . . 25 93 9.2. Informative References . . . . . . . . . . . . . . . . . 27 94 Appendix A. Future Work . . . . . . . . . . . . . . . . . . . . 29 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 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 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 preference for compact and simple data formats to facilitate 128 efficient transfer over (often) constrained networks and 129 lightweight processing in constrained nodes 131 o the usually large number of endpoints can not be updated 132 simultaneously, yet the system needs to be able to evolve in the 133 field without long downtimes 135 2. Terminology 137 This section explains some of the common terminology that is used in 138 the context of RESTful design for IoT systems. For terminology of 139 constrained nodes and networks, see [RFC7228]. 141 Cache: A local store of response messages and the subsystem that 142 controls storage, retrieval, and deletion of messages in it. 144 Client: A node that sends requests to servers and receives 145 responses. In RESTful IoT systems it's common for nodes to have 146 more than one role (e.g., both server and client; see 147 Section 3.1). 149 Client State: The state kept by a client between requests. This 150 typically includes the currently processed representation, the set 151 of active requests, the history of requests, bookmarks (URIs 152 stored for later retrieval), and application-specific state (e.g., 153 local variables). (Note that this is called "Application State" 154 in [REST], which has some ambiguity in modern (IoT) systems where 155 the overall state of the distributed application (i.e., 156 application state) is reflected in the union of all Client States 157 and Resource States of all clients and servers involved.) 159 Content Negotiation: The practice of determining the "best" 160 representation for a client when examining the current state of a 161 resource. The most common forms of content negotiation are 162 Proactive Content Negotiation and Reactive Content Negotiation. 164 Dereference: To use an access mechanism (e.g., HTTP or CoAP) to 165 perform an action on a URI's resource. 167 Dereferencable URI: A URI that can be dereferenced, i.e., an action 168 can be performed on the identified resource. Not all HTTP or CoAP 169 URIs are dereferencable, e.g., when the target resource does not 170 exist. 172 Form: A hypermedia control that enables a client to change the state 173 of a resource or to construct a query locally. 175 Forward Proxy: An intermediary that is selected by a client, usually 176 via local configuration rules, and that can be tasked to make 177 requests on behalf of the client. This may be useful, for 178 example, when the client lacks the capability to make the request 179 itself or to service the response from a cache in order to reduce 180 response time, network bandwidth, and energy consumption. 182 Gateway: A reverse proxy that provides an interface to a non-RESTful 183 system such as legacy systems or alternative technologies such as 184 Bluetooth ATT/GATT. See also "Reverse Proxy". 186 Hypermedia Control: A component, such as a link or a form, embedded 187 in a representation that identifies a resource for future 188 hypermedia interactions. If the client engages in an interaction 189 with the identified resource, the result may be a change to 190 resource state and/or client state. 192 Idempotent Method: A method where multiple identical requests with 193 that method lead to the same visible resource state as a single 194 such request. 196 Link: A hypermedia control that enables a client to navigate between 197 resources and thereby change the client state. 199 Link Relation Type: An identifier that describes how the link target 200 resource relates to the current resource (see [RFC5988]). 202 Media Type: A string such as "text/html" or "application/json" that 203 is used to label representations so that it is known how the 204 representation should be interpreted and how it is encoded. 206 Method: An operation associated with a resource. Common methods 207 include GET, PUT, POST, and DELETE (see Section 3.5 for details). 209 Origin Server: A server that is the definitive source for 210 representations of its resources and the ultimate recipient of any 211 request that intends to modify its resources. In contrast, 212 intermediaries (such as proxies caching a representation) can 213 assume the role of a server, but are not the source for 214 representations as these are acquired from the origin server. 216 Proactive Content Negotiation: A content negotiation mechanism where 217 the server selects a representation based on the expressed 218 preference of the client. For example, an IoT application could 219 send a request to a sensor with preferred media type "application/ 220 senml+json". 222 Reactive Content Negotiation: A content negotiation mechanism where 223 the client selects a representation from a list of available 224 representations. The list may, for example, be included by a 225 server in an initial response. If the user agent is not satisfied 226 by the initial response representation, it can request one or more 227 of the alternative representations, selected based on metadata 228 (e.g., available media types) included in the response. 230 Representation: A serialization that represents the current or 231 intended state of a resource and that can be transferred between 232 clients and servers. REST requires representations to be self- 233 describing, meaning that there must be metadata that allows peers 234 to understand which representation format is used. Depending on 235 the protocol needs and capabilities, there can be additional 236 metadata that is transmitted along with the representation. 238 Representation Format: A set of rules for serializing resource 239 state. On the Web, the most prevalent representation format is 240 HTML. Other common formats include plain text and formats based 241 on JSON [RFC7159], XML, or RDF. Within IoT systems, often compact 242 formats based on JSON, CBOR [RFC7049], and EXI 243 [W3C.REC-exi-20110310] are used. 245 Representational State Transfer (REST): An architectural style for 246 Internet-scale distributed hypermedia systems. 248 Resource: An item of interest identified by a URI. Anything that 249 can be named can be a resource. A resource often encapsulates a 250 piece of state in a system. Typical resources in an IoT system 251 can be, e.g., a sensor, the current value of a sensor, the 252 location of a device, or the current state of an actuator. 254 Resource State: A model of a resource's possible states that is 255 represented in a supported representation type, typically a media 256 type. Resources can change state because of REST interactions 257 with them, or they can change state for reasons outside of the 258 REST model. 260 Resource Type: An identifier that annotates the application- 261 semantics of a resource (see Section 3.1 of [RFC6690]). 263 Reverse Proxy: An intermediary that appears as a server towards the 264 client but satisfies the requests by forwarding them to the actual 265 server (possibly via one or more other intermediaries). A reverse 266 proxy is often used to encapsulate legacy services, to improve 267 server performance through caching, and to enable load balancing 268 across multiple machines. 270 Safe Method: A method that does not result in any state change on 271 the origin server when applied to a resource. 273 Server: A node that listens for requests, performs the requested 274 operation and sends responses back to the clients. 276 Transfer protocols: In particular in IoT domain, protocols above 277 transport layer that are used to transfer data objects and provide 278 semantics for operations on the data. 280 Transfer layer: Re-usable part of the application layer used to 281 transfer the application specific data items using a standard set 282 of methods that can fulfill application-specific operations. 284 Uniform Resource Identifier (URI): A global identifier for 285 resources. See Section 3.3 for more details. 287 3. Basics 289 3.1. Architecture 291 The components of a RESTful system are assigned one or both of two 292 roles: client or server. Note that the terms "client" and "server" 293 refer only to the roles that the nodes assume for a particular 294 message exchange. The same node might act as a client in some 295 communications and a server in others. Classic user agents (e.g., 296 Web browsers) are always in the client role and have the initiative 297 to issue requests. Origin servers always have the server role and 298 govern over the resources they host. Simple IoT devices, such as 299 sensors and actuators, are commonly acting as servers and exposing 300 their physical world interaction capabilities (e.g., temperature 301 measurement or door lock control capability) as resources. Typical 302 IoT system client can be a cloud service that retrieves data from the 303 sensors and commands the actuators based on the sensor information. 304 Alternatively an IoT data storage system could work as a server where 305 IoT sensor devices send data, in client role. 307 ________ _________ 308 | | | | 309 | User (C)-------------------(S) Origin | 310 | Agent | | Server | 311 |________| |_________| 312 (Browser) (Web Server) 314 Figure 1: Client-Server Communication 316 Intermediaries (such as forward proxies, reverse proxies, and 317 gateways) implement both roles, but only forward requests to other 318 intermediaries or origin servers. They can also translate requests 319 to different protocols, for instance, as CoAP-HTTP cross-proxies. 321 ________ __________ _________ 322 | | | | | | 323 | User (C)---(S) Inter- (C)--------------------(S) Origin | 324 | Agent | | mediary | | Server | 325 |________| |__________| |_________| 326 (Browser) (Forward Proxy) (Web Server) 328 Figure 2: Communication with Forward Proxy 330 Reverse proxies are usually imposed by the origin server. In 331 addition to the features of a forward proxy, they can also provide an 332 interface for non-RESTful services such as legacy systems or 333 alternative technologies such as Bluetooth ATT/GATT. In this case, 334 reverse proxies are usually called gateways. This property is 335 enabled by the Layered System constraint of REST, which says that a 336 client cannot see beyond the server it is connected to (i.e., it is 337 left unaware of the protocol/paradigm change). 339 ________ __________ _________ 340 | | | | | | 341 | User (C)--------------------(S) Inter- (x)---(x) Origin | 342 | Agent | | mediary | | Server | 343 |________| |__________| |_________| 344 (Browser) (Gateway) (Legacy System) 346 Figure 3: Communication with Reverse Proxy 348 Nodes in IoT systems often implement both roles. Unlike 349 intermediaries, however, they can take the initiative as a client 350 (e.g., to register with a directory, such as CoRE Resource Directory 351 [I-D.ietf-core-resource-directory], or to interact with another 352 thing) and act as origin server at the same time (e.g., to serve 353 sensor values or provide an actuator interface). 355 ________ _________ 356 | | | | 357 | Thing (C)-------------------------------------(S) Origin | 358 | (S) | Server | 359 |________| \ |_________| 360 (Sensor) \ ________ (Resource Directory) 361 \ | | 362 (C) Thing | 363 |________| 364 (Controller) 366 Figure 4: Constrained RESTful environments 368 3.2. System design 370 When designing a RESTful system, the primary effort goes into 371 modeling the state of the distributed application and assigning it to 372 the different components (i.e., clients and servers). How clients 373 can navigate through the resources and modify state to achieve their 374 goals is defined through hypermedia controls, that is, links and 375 forms. Hypermedia controls span a kind of a state machine where the 376 nodes are resources and the transitions are links or forms. Clients 377 run this state machine (i.e., the application) by retrieving 378 representations, processing the data, and following the included 379 hypermedia controls. In REST, remote state is changed by submitting 380 forms. This is usually done by retrieving the current state, 381 modifying the state on the client side, and transferring the new 382 state to the server in the form of new representations - rather than 383 calling a service and modifying the state on the server side. 385 Client state encompasses the current state of the described state 386 machine and the possible next transitions derived from the hypermedia 387 controls within the currently processed representation (see 388 Section 2). Furthermore, clients can have part of the state of the 389 distributed application in local variables. 391 Resource state includes the more persistent data of an application 392 (i.e., independent of individual clients). This can be static data 393 such as device descriptions, persistent data such as system 394 configurations, but also dynamic data such as the current value of a 395 sensor on a thing. 397 It is important to distinguish between "client state" and "resource 398 state" and keep them separate. Following the Stateless constraint, 399 the client state must be kept only on clients. That is, there is no 400 establishment of shared information about past and future 401 interactions between client and server (usually called a session). 402 On the one hand, this makes requests a bit more verbose since every 403 request must contain all the information necessary to process it. On 404 the other hand, this makes servers efficient and scalable, since they 405 do not have to keep any state about their clients. Requests can 406 easily be distributed over multiple worker threads or server 407 instances. For IoT systems, this constraint lowers the memory 408 requirements for server implementations, which is particularly 409 important for constrained servers (e.g., sensor nodes) and servers 410 serving large amount of clients (e.g., Resource Directory). 412 3.3. Uniform Resource Identifiers (URIs) 414 An important part of RESTful API design is to model the system as a 415 set of resources whose state can be retrieved and/or modified and 416 where resources can be potentially also created and/or deleted. 418 Uniform Resource Identifiers (URIs) are used to indicate a resource 419 for interaction, to reference a resource from another resource, to 420 advertise or bookmark a resource, or to index a resource by search 421 engines. 423 foo://example.com:8042/over/there?name=ferret#nose 424 \_/ \______________/\_________/ \_________/ \__/ 425 | | | | | 426 scheme authority path query fragment 428 A URI is a sequence of characters that matches the syntax defined in 429 [RFC3986]. It consists of a hierarchical sequence of five 430 components: scheme, authority, path, query, and fragment (from most 431 significant to least significant). A scheme creates a namespace for 432 resources and defines how the following components identify a 433 resource within that namespace. The authority identifies an entity 434 that governs part of the namespace, such as the server 435 "www.example.org" in the "http" scheme. A host name (e.g., a fully 436 qualified domain name) or an IP address, potentially followed by a 437 transport layer port number, are usually used in the authority 438 component for the "http" and "coap" schemes. The path and query 439 contain data to identify a resource within the scope of the URI's 440 scheme and naming authority. The fragment allows to refer to some 441 portion of the resource, such as a Record in a SenML Pack. However, 442 fragments are processed only at client side and not sent on the wire. 443 [RFC7320] provides more details on URI design and ownership with best 444 current practices for establishing URI structures, conventions, and 445 formats. 447 For RESTful IoT applications, typical schemes include "https", 448 "coaps", "http", and "coap". These refer to HTTP and CoAP, with and 449 without Transport Layer Security (TLS) [RFC5246]. (CoAP uses 450 Datagram TLS (DTLS) [RFC6347], the variant of TLS for UDP.) These 451 four schemes also provide means for locating the resource; using the 452 HTTP protocol for "http" and "https", and with the CoAP protocol for 453 "coap" and "coaps". If the scheme is different for two URIs (e.g., 454 "coap" vs. "coaps"), it is important to note that even if the rest of 455 the URI is identical, these are two different resources, in two 456 distinct namespaces. 458 Some schemes are for URIs with main purpose as identifiers and hence 459 are not dereferencable, e.g., the "urn" scheme can be used to 460 construct unique names in registered namespaces. In particular the 461 "urn:dev" [I-D.ietf-core-dev-urn] details multiple ways for 462 generating and representing endpoint identifiers of IoT devices. 464 The query parameters can be used to parametrize the resource. For 465 example, a GET request may use query parameters to request the server 466 to send only certain kind data of the resource (i.e., filtering the 467 response). Query parameters in PUT and POST requests do not have 468 such established semantics and are not commonly used. Whether the 469 order of the query parameters matters in URIs is unspecified and they 470 can be re-ordered e.g., by proxies. Therefore applications should 471 not rely on their order; see Section 3.3 of [RFC6943] for more 472 details. 474 3.4. Representations 476 Clients can retrieve the resource state from an origin server or 477 manipulate resource state on the origin server by transferring 478 resource representations. Resource representations have a media type 479 that tells how the representation should be interpreted by 480 identifying the representation format used. 482 Typical media types for IoT systems include: 484 o "text/plain" for simple UTF-8 text 486 o "application/octet-stream" for arbitrary binary data 488 o "application/json" for the JSON format [RFC7159] 490 o "application/cbor" for CBOR [RFC7049] 492 o "application/exi" for EXI [W3C.REC-exi-20110310] 494 o "application/senml+json" and "application/senml+cbor" for Sensor 495 Measurement Lists (SenML) data [RFC8428] 497 A full list of registered Internet Media Types is available at the 498 IANA registry [IANA-media-types] and numerical media types registered 499 for use with CoAP are listed at CoAP Content-Formats IANA registry 500 [IANA-CoAP-media]. 502 3.5. HTTP/CoAP Methods 504 Section 4.3 of [RFC7231] defines the set of methods in HTTP; 505 Section 5.8 of [RFC7252] defines the set of methods in CoAP. As part 506 of the Uniform Interface constraint, each method can have certain 507 properties that give guarantees to clients. 509 Safe methods do not cause any state change on the origin server when 510 applied to a resource. For example, the GET method only returns a 511 representation of the resource state but does not change the 512 resource. Thus, it is always safe for a client to retrieve a 513 representation without affecting server-side state. 515 Idempotent methods can be applied multiple times to the same resource 516 while causing the same visible resource state as a single such 517 request. For example, the PUT method replaces the state of a 518 resource with a new state; replacing the state multiple times with 519 the same new state still results in the same state for the resource. 520 However, the response from the server can be different when the same 521 idempotent method is used multiple times. For example when DELETE is 522 used twice on an existing resource, the first request would remove 523 the association and return success acknowledgement whereas the second 524 request would likely result in error response due to non-existing 525 resource. 527 The following lists the most relevant methods and gives a short 528 explanation of their semantics. 530 3.5.1. GET 532 The GET method requests a current representation for the target 533 resource, while the origin server must ensure that there are no side- 534 effects on the resource state. Only the origin server needs to know 535 how each of its resource identifiers corresponds to an implementation 536 and how each implementation manages to select and send a current 537 representation of the target resource in a response to GET. 539 A payload within a GET request message has no defined semantics. 541 The GET method is safe and idempotent. 543 3.5.2. POST 545 The POST method requests that the target resource process the 546 representation enclosed in the request according to the resource's 547 own specific semantics. 549 If one or more resources has been created on the origin server as a 550 result of successfully processing a POST request, the origin server 551 sends a 201 (Created) response containing a Location header field 552 (with HTTP) or Location-Path and/or Location-Query Options (with 553 CoAP) that provide an identifier for the resource created. The 554 server also includes a representation that describes the status of 555 the request while referring to the new resource(s). 557 The POST method is not safe nor idempotent. 559 3.5.3. PUT 561 The PUT method requests that the state of the target resource be 562 created or replaced with the state defined by the representation 563 enclosed in the request message payload. A successful PUT of a given 564 representation would suggest that a subsequent GET on that same 565 target resource will result in an equivalent representation being 566 sent. 568 The fundamental difference between the POST and PUT methods is 569 highlighted by the different intent for the enclosed representation. 571 The target resource in a POST request is intended to handle the 572 enclosed representation according to the resource's own semantics, 573 whereas the enclosed representation in a PUT request is defined as 574 replacing the state of the target resource. Hence, the intent of PUT 575 is idempotent and visible to intermediaries, even though the exact 576 effect is only known by the origin server. 578 The PUT method is not safe, but is idempotent. 580 3.5.4. DELETE 582 The DELETE method requests that the origin server remove the 583 association between the target resource and its current 584 functionality. 586 If the target resource has one or more current representations, they 587 might or might not be destroyed by the origin server, and the 588 associated storage might or might not be reclaimed, depending 589 entirely on the nature of the resource and its implementation by the 590 origin server. 592 The DELETE method is not safe, but is idempotent. 594 3.5.5. FETCH 596 The CoAP-specific FETCH method [RFC8132] requests a representation of 597 a resource parameterized by a representation enclosed in the request. 599 The fundamental difference between the GET and FETCH methods is that 600 the request parameters are included as the payload of a FETCH 601 request, while in a GET request they're typically part of the query 602 string of the request URI. 604 The FETCH method is safe and idempotent. 606 3.5.6. PATCH 608 The PATCH method [RFC5789] [RFC8132] requests that a set of changes 609 described in the request entity be applied to the target resource. 611 The PATCH method is not safe nor idempotent. 613 The CoAP-specific iPATCH method is a variant of the PATCH method that 614 is not safe, but is idempotent. 616 3.6. HTTP/CoAP Status/Response Codes 618 Section 6 of [RFC7231] defines a set of Status Codes in HTTP that are 619 used by application to indicate whether a request was understood and 620 satisfied, and how to interpret the answer. Similarly, Section 5.9 621 of [RFC7252] defines the set of Response Codes in CoAP. 623 The status codes consist of three digits (e.g., "404" with HTTP or 624 "4.04" with CoAP) where the first digit expresses the class of the 625 code. Implementations do not need to understand all status codes, 626 but the class of the code must be understood. Codes starting with 1 627 are informational; the request was received and being processed. 628 Codes starting with 2 indicate a successful request. Codes starting 629 with 3 indicate redirection; further action is needed to complete the 630 request. Codes stating with 4 and 5 indicate errors. The codes 631 starting with 4 mean client error (e.g., bad syntax in the request) 632 whereas codes starting with 5 mean server error; there was no 633 apparent problem with the request, but server was not able to fulfill 634 the request. 636 Responses may be stored in a cache to satisfy future, equivalent 637 requests. HTTP and CoAP use two different patterns to decide what 638 responses are cacheable. In HTTP, the cacheability of a response 639 depends on the request method (e.g., responses returned in reply to a 640 GET request are cacheable). In CoAP, the cacheability of a response 641 depends on the response code (e.g., responses with code 2.04 are 642 cacheable). This difference also leads to slightly different 643 semantics for the codes starting with 2; for example, CoAP does not 644 have a 2.00 response code whereas 200 ("OK") is commonly used with 645 HTTP. 647 4. REST Constraints 649 The REST architectural style defines a set of constraints for the 650 system design. When all constraints are applied correctly, REST 651 enables architectural properties of key interest [REST]: 653 o Performance 655 o Scalability 657 o Reliability 659 o Simplicity 661 o Modifiability 663 o Visibility 664 o Portability 666 The following sub-sections briefly summarize the REST constraints and 667 explain how they enable the listed properties. 669 4.1. Client-Server 671 As explained in the Architecture section, RESTful system components 672 have clear roles in every interaction. Clients have the initiative 673 to issue requests, intermediaries can only forward requests, and 674 servers respond requests, while origin servers are the ultimate 675 recipient of requests that intent to modify resource state. 677 This improves simplicity and visibility (also for digital forensics), 678 as it is clear which component started an interaction. Furthermore, 679 it improves modifiability through a clear separation of concerns. 681 In IoT systems, endpoints often assume both roles of client and 682 (origin) server simultaneously. When an IoT device has initiative 683 (because there is a user, e.g., pressing a button, or installed 684 rules/policies), it acts as a client. When a device offers a 685 service, it is in server role. 687 4.2. Stateless 689 The Stateless constraint requires messages to be self-contained. 690 They must contain all the information to process it, independent from 691 previous messages. This allows to strictly separate the client state 692 from the resource state. 694 This improves scalability and reliability, since servers or worker 695 threads can be replicated. It also improves visibility because 696 message traces contain all the information to understand the logged 697 interactions. Furthermore, the Stateless constraint enables caching. 699 For IoT, the scaling properties of REST become particularly 700 important. Note that being self-contained does not necessarily mean 701 that all information has to be inlined. Constrained IoT devices may 702 choose to externalize metadata and hypermedia controls using Web 703 linking, so that only the dynamic content needs to be sent and the 704 static content such as schemas or controls can be cached. 706 4.3. Cache 708 This constraint requires responses to have implicit or explicit 709 cache-control metadata. This enables clients and intermediary to 710 store responses and re-use them to locally answer future requests. 711 The cache-control metadata is necessary to decide whether the 712 information in the cached response is still fresh or stale and needs 713 to be discarded. 715 Cache improves performance, as less data needs to be transferred and 716 response times can be reduced significantly. Less transfers also 717 improves scalability, as origin servers can be protected from too 718 many requests. Local caches furthermore improve reliability, since 719 requests can be answered even if the origin server is temporarily not 720 available. 722 Caching usually only makes sense when the data is used by multiple 723 participants. In the IoT, however, it might make sense to cache also 724 individual data to protect constrained devices from frequent requests 725 of data that does not change often. Security often hinders the 726 ability to cache responses. For IoT systems, object security may be 727 preferable over transport layer security, as it enables 728 intermediaries to cache responses while preserving security. 730 4.4. Uniform Interface 732 All RESTful APIs use the same, uniform interface independent of the 733 application. This simple interaction model is enabled by exchanging 734 representations and modifying state locally, which simplifies the 735 interface between clients and servers to a small set of methods to 736 retrieve, update, and delete state - which applies to all 737 applications. 739 In contrast, in a service-oriented RPC approach, all required ways to 740 modify state need to be modeled explicitly in the interface resulting 741 in a large set of methods - which differs from application to 742 application. Moreover, it is also likely that different parties come 743 up with different ways how to modify state, including the naming of 744 the procedures, while the state within an application is a bit easier 745 to agree on. 747 A REST interface is fully defined by: 749 o URIs to identify resources 751 o representation formats to represent and manipulate resource state 753 o self-descriptive messages with a standard set of methods (e.g., 754 GET, POST, PUT, DELETE with their guaranteed properties) 756 o hypermedia controls within representations 758 The concept of hypermedia controls is also known as HATEOAS: 759 Hypermedia As The Engine Of Application State. The origin server 760 embeds controls for the interface into its representations and 761 thereby informs the client about possible next requests. The mostly 762 used control for RESTful systems is Web Linking [RFC5590]. 763 Hypermedia forms are more powerful controls that describe how to 764 construct more complex requests, including representations to modify 765 resource state. 767 While this is the most complex constraints (in particular the 768 hypermedia controls), it improves many different key properties. It 769 improves simplicity, as uniform interfaces are easier to understand. 770 The self-descriptive messages improve visibility. The limitation to 771 a known set of representation formats fosters portability. Most of 772 all, however, this constraint is the key to modifiability, as 773 hypermedia-driven, uniform interfaces allow clients and servers to 774 evolve independently, and hence enable a system to evolve. 776 For a large number of IoT applications, the hypermedia controls are 777 mainly used for the discovery of resources, as they often serve 778 sensor data. Such resources are "dead ends", as they usually do not 779 link any further and only have one form of interaction: fetching the 780 sensor value. For IoT, the critical parts of the Uniform Interface 781 constraint are the descriptions of messages and representation 782 formats used. Simply using, for instance, "application/json" does 783 not help machine clients to understand the semantics of the 784 representation. Yet defining very precise media types limits the re- 785 usability and interoperability. Representation formats such as SenML 786 [RFC8428] try to find a good trade-off between precision and re- 787 usability. Another approach is to combine a generic format such as 788 JSON with syntactic as well as semantic annotations (see 789 [I-D.handrews-json-schema-validation] and [W3C-TD], resp.). 791 4.5. Layered System 793 This constraint enforces that a client cannot see beyond the server 794 with which it is interacting. 796 A layered system is easier to modify, as topology changes become 797 transparent. Furthermore, this helps scalability, as intermediaries 798 such as load balancers can be introduced without changing the client 799 side. The clean separation of concerns helps with simplicity. 801 IoT systems greatly benefit from this constraint, as it allows to 802 effectively shield constrained devices behind intermediaries and is 803 also the basis for gateways, which are used to integrate other (IoT) 804 ecosystems. 806 4.6. Code-on-Demand 808 This principle enables origin servers to ship code to clients. 810 Code-on-Demand improves modifiability, since new features can be 811 deployed during runtime (e.g., support for a new representation 812 format). It also improves performance, as the server can provide 813 code for local pre-processing before transferring the data. 815 As of today, code-on-demand has not been explored much in IoT 816 systems. Aspects to consider are that either one or both nodes are 817 constrained and might not have the resources to host or dynamically 818 fetch and execute such code. Moreover, the origin server often has 819 no understanding of the actual application a mashup client realizes. 820 Still, code-on-demand can be useful for small polyfills, e.g., to 821 decode payloads, and potentially other features in the future. 823 5. Hypermedia-driven Applications 825 Hypermedia-driven applications take advantage of hypermedia controls, 826 i.e., links and forms, embedded in the resource representations. A 827 hypermedia client is a client that is capable of processing these 828 hypermedia controls. Hypermedia links can be used to give additional 829 information about a resource representation (e.g., the source URI of 830 the representation) or pointing to other resources. The forms can be 831 used to describe the structure of the data that can be sent (e.g., 832 with a POST or PUT method) to a server, or how a data retrieval 833 (e.g., GET) request for a resource should be formed. In a 834 hypermedia-driven application the client interacts with the server 835 using only the hypermedia controls, instead of selecting methods and/ 836 or constructing URIs based on out-of-band information, such as API 837 documentation. 839 5.1. Motivation 841 The advantage of this approach is increased evolvability and 842 extensibility. This is important in scenarios where servers exhibit 843 a range of feature variations, where it's expensive to keep evolving 844 client knowledge and server knowledge in sync all the time, or where 845 there are many different client and server implementations. 846 Hypermedia controls serve as indicators in capability negotiation. 847 In particular, they describe available resources and possible 848 operations on these resources using links and forms, respectively. 850 There are multiple reasons why a server might introduce new links or 851 forms: 853 o The server implements a newer version of the application. Older 854 clients ignore the new links and forms, while newer clients are 855 able to take advantage of the new features by following the new 856 links and submitting the new forms. 858 o The server offers links and forms depending on the current state. 859 The server can tell the client which operations are currently 860 valid and thus help the client navigate the application state 861 machine. The client does not have to have knowledge which 862 operations are allowed in the current state or make a request just 863 to find out that the operation is not valid. 865 o The server offers links and forms depending on the client's access 866 control rights. If the client is unauthorized to perform a 867 certain operation, then the server can simply omit the links and 868 forms for that operation. 870 5.2. Knowledge 872 A client needs to have knowledge of a couple of things for successful 873 interaction with a server. This includes what resources are 874 available, what representations of resource states are available, 875 what each representation describes, how to retrieve a representation, 876 what state changing operations on a resource are possible, how to 877 perform these operations, and so on. 879 Some part of this knowledge, such as how to retrieve the 880 representation of a resource state, is typically hard-coded in the 881 client software. For other parts, a choice can often be made between 882 hard-coding the knowledge or acquiring it on-demand. The key to 883 success in either case is the use in-band information for identifying 884 the knowledge that is required. This enables the client to verify 885 that is has all required knowledge and to acquire missing knowledge 886 on-demand. 888 A hypermedia-driven application typically uses the following 889 identifiers: 891 o URI schemes that identify communication protocols, 893 o Internet Media Types that identify representation formats, 895 o link relation types or resource types that identify link 896 semantics, 898 o form relation types that identify form semantics, 899 o variable names that identify the semantics of variables in 900 templated links, and 902 o form field names that identify the semantics of form fields in 903 forms. 905 The knowledge about these identifiers as well as matching 906 implementations have to be shared a priori in a RESTful system. 908 5.3. Interaction 910 A client begins interacting with an application through a GET request 911 on an entry point URI. The entry point URI is the only URI a client 912 is expected to know before interacting with an application. From 913 there, the client is expected to make all requests by following links 914 and submitting forms that are provided in previous responses. The 915 entry point URI can be obtained, for example, by manual configuration 916 or some discovery process (e.g., DNS-SD [RFC6763] or Resource 917 Directory [I-D.ietf-core-resource-directory]). For Constrained 918 RESTful environments "/.well-known/core" relative URI is defined as a 919 default entry point for requesting the links hosted by servers with 920 known or discovered addresses [RFC6690]. 922 5.4. Hypermedia-driven Design Guidance 924 Assuming self-describing representation formats (i.e., human-readable 925 with carefully chosen terms or processible by a formatting tool) and 926 a client supporting the URI scheme used, a good rule of thumb for a 927 good hypermedia-driven design is the following: A developer should 928 only need an entry point URI to drive the application. All further 929 information how to navigate through the application (links) and how 930 to construct more complex requests (forms) are published by the 931 server(s). There must be no need for additional, out-of-band 932 information (e.g., API specification). 934 For machines, a well-chosen set of information needs to be shared a 935 priori to agree on machine-understandable semantics. Agreeing on the 936 exact semantics of terms for relation types and data elements will of 937 course also help the developer. [I-D.hartke-core-apps] proposes a 938 convention for specifying the set of information in a structured way. 940 6. Design Patterns 942 Certain kinds of design problems are often recurring in variety of 943 domains, and often re-usable design patterns can be applied to them. 944 Also some interactions with a RESTful IoT system are straightforward 945 to design; a classic example of reading a temperature from a 946 thermometer device is almost always implemented as a GET request to a 947 resource that represents the current value of the thermometer. 948 However, certain interactions, for example data conversions or event 949 handling, do not have as straightforward and well established ways to 950 represent the logic with resources and REST methods. 952 The following sections describe how common design problems such as 953 different interactions can be modeled with REST and what are the 954 benefits of different approaches. 956 6.1. Collections 958 A common pattern in RESTful systems across different domains is the 959 collection. A collection can be used to combine multiple resources 960 together by providing resources that consist of set of (often 961 partial) representations of resources, called items, and links to 962 resources. The collection resource also defines hypermedia controls 963 for managing and searching the items in the collection. 965 Examples of the collection pattern in RESTful IoT systems are the 966 CoRE Resource Directory [I-D.ietf-core-resource-directory], CoAP pub/ 967 sub broker [I-D.ietf-core-coap-pubsub], and resource discovery via 968 ".well-known/core". Collection+JSON [CollectionJSON] is an example 969 of a generic collection Media Type. 971 6.2. Calling a Procedure 973 To modify resource state, clients usually use GET to retrieve a 974 representation from the server, modify that locally, and transfer the 975 resulting state back to the server with a PUT (see Section 4.4). 976 Sometimes, however, the state can only be modified on the server 977 side, for instance, because representations would be too large to 978 transfer or part of the required information shall not be accessible 979 to clients. In this case, resource state is modified by calling a 980 procedure (or "function"). This is usually modeled with a POST 981 request, as this method leaves the behavior semantics completely to 982 the server. Procedure calls can be divided into two different 983 classes based on how long they are expected to execute: "instantly" 984 returning and long-running. 986 6.2.1. Instantly Returning Procedures 988 When the procedure can return within the expected response time of 989 the system, the result can be directly returned in the response. The 990 result can either be actual content or just a confirmation that the 991 call was successful. In either case, the response does not contain a 992 representation of the resource, but a so-called action result. 993 Action results can still have hypermedia controls to provide the 994 possible transitions in the application state machine. 996 6.2.2. Long-running Procedures 998 When the procedure takes longer than the expected response time of 999 the system, or even longer than the response timeout, it is a good 1000 pattern to create a new resource to track the "task" execution. The 1001 server would respond instantly with a "Created" status (HTTP code 201 1002 or CoAP 2.01) and indicate the location of the task resource in the 1003 corresponding header field (or CoAP option) or as a link in the 1004 action result. The created resource can be used to monitor the 1005 progress, to potentially modify queued tasks or cancel tasks, and to 1006 eventually retrieve the result. 1008 Monitoring information would be modeled as state of the task 1009 resource, and hence be retrievable as representation. The result - 1010 when available - can be embedded in the representation or given as a 1011 link to another sub-resource. Modifying tasks can be modeled with 1012 forms that either update sub-resources via PUT or do a partial write 1013 using PATCH or POST. Canceling a task would be modeled with a form 1014 that uses DELETE to remove the task resource. 1016 6.2.3. Conversion 1018 A conversion service is a good example where REST resources need to 1019 behave more like a procedure call. The knowledge of converting from 1020 one representation to another is located only at the server to 1021 relieve clients from high processing or storing lots of data. There 1022 are different approaches that all depend on the particular conversion 1023 problem. 1025 As mentioned in the previous sections, POST request are a good way to 1026 model functionality that does not necessarily affect resource state. 1027 When the input data for the conversion is small and the conversion 1028 result is deterministic, however, it can be better to use a GET 1029 request with the input data in the URI query part. The query is 1030 parameterizing the conversion resource, so that it acts like a look- 1031 up table. The benefit is that results can be cached also for HTTP 1032 (where responses to POST are not cacheable). In CoAP, cacheability 1033 depends on the response code, so that also a response to a POST 1034 request can be made cacheable through a 2.05 Content code. 1036 When the input data is large or has a binary encoding, it is better 1037 to use POST requests with a proper Media Type for the input 1038 representation. A POST request is also more suitable, when the 1039 result is time-dependent and the latest result is expected (e.g., 1040 exchange rates). 1042 6.2.4. Events as State 1044 In event-centric paradigms such as pub/sub, events are usually 1045 represented by an incoming message that might even be identical for 1046 each occurrence. Since the messages are queued, the receiver is 1047 aware of each occurrence of the event and can react accordingly. For 1048 instance, in an event-centric system, ringing a door bell would 1049 result in a message being sent that represents the event that it was 1050 rung. 1052 In resource-oriented paradigms such as REST, messages usually carry 1053 the current state of the remote resource, independent from the 1054 changes (i.e., events) that have lead to that state. In a naive yet 1055 natural design, a door bell could be modeled as a resource that can 1056 have the states unpressed and pressed. There are, however, a few 1057 issues with this approach. Polling is not an option, as it is highly 1058 unlikely to be able to observe the pressed state with any realistic 1059 polling interval. When using CoAP Observe with Confirmable 1060 notifications, the server will usually send two notifications for the 1061 event that the door bell was pressed: notification for changing from 1062 unpressed to pressed and another one for changing back to unpressed. 1063 If the time between the state changes is very short, the server might 1064 drop the first notification, as Observe only guarantees only eventual 1065 consistency (see Section 1.3 of [RFC7641]). 1067 The solution is to pick a state model that fits better to the 1068 application. In the case of the door bell - and many other event- 1069 driven resources - the solution could be a counter that counts how 1070 often the bell was pressed. The corresponding action is taken each 1071 time the client observes a change in the received representation. 1073 In the case of a network outage, this could lead to a ringing sound 1074 10 minutes after the bell was rung. Also including a timestamp of 1075 the last counter increment in the state can help to suppress ringing 1076 a sound when the event has become obsolete. 1078 6.3. Server Push 1080 Overall, a universal mechanism for server push, that is, change-of- 1081 state notifications and stand-alone event notifications, is still an 1082 open issue that is being discussed in the Thing-to-Thing Research 1083 Group. It is connected to the state-event duality problem and 1084 custody transfer, that is, the transfer of the responsibility that a 1085 message (e.g., event) is delivered successfully. 1087 A proficient mechanism for change-of-state notifications is currently 1088 only available for CoAP: Observing resources [RFC7641]. It offers 1089 enventual consistency, which guarantees "that if the resource does 1090 not undergo a new change in state, eventually all registered 1091 observers will have a current representation of the latest resource 1092 state". It intrinsically deals with the challenges of lossy 1093 networks, where notifications might be lost, and constrained 1094 networks, where there might not be enough bandwidth to propagate all 1095 changes. 1097 For stand-alone event notifications, that is, where every single 1098 notification contains an identifiable event that must not be lost, 1099 observing resources is not a good fit. A better strategy is to model 1100 each event as a new resource, whose existence is notified through 1101 change-of-state notifications of an index resource (cf. Collection 1102 pattern). Large numbers of events will cause the notification to 1103 grow large, as it needs to contain a large number of Web links. 1104 Blockwise transfers [RFC7959] can help here. When the links are 1105 ordered by freshness of the events, the first block can already 1106 contain all links to new events. Then, observers do not need to 1107 retrieve the remaining blocks from the server, but only the 1108 representations of the new event resources. 1110 An alternative pattern is to exploit the dual roles of IoT devices, 1111 in particular when using CoAP: they are usually client and server at 1112 the same time. A client observer would subscribe to events by 1113 registering a callback URI at the origin server, e.g., using a POST 1114 request and receiving the location of a temporary subscription 1115 resource as handle. The origin server would then publish events by 1116 sending POST requests containing the event to the observer. The 1117 cancellation can be modeled through deleting the subscription 1118 resource. This pattern makes the origin server responsible for 1119 delivering the event notifications. This goes beyond retransmissions 1120 of messages; the origin server is usually supposed to queue all 1121 undelivered events and to retry until successful delivery or explicit 1122 cancellation. In HTTP, this pattern is known as REST Hooks. 1124 In HTTP, there exist a number of workarounds to enable server push, 1125 e.g., long polling and streaming [RFC6202] or server-sent events 1126 [W3C.REC-html5-20141028]. Long polling as an extension that both 1127 server and client need to be aware of. In IoT systems, long polling 1128 can introduce a considerable overhead, as the request has to be 1129 repeated for each notification. Streaming and server-sent events (in 1130 fact an evolved version of streaming) are more efficient, as only one 1131 request is sent. However, there is only one response header and 1132 subsequent notifications can only have content. There are no means 1133 for individual status and metadata, and hence no means for proficient 1134 error handling (e.g., when the resource is deleted). 1136 7. Security Considerations 1138 This document does not define new functionality and therefore does 1139 not introduce new security concerns. We assume that system designers 1140 apply classic Web security on top of the basic RESTful guidance given 1141 in this document. Thus, security protocols and considerations from 1142 related specifications apply to RESTful IoT design. These include: 1144 o Transport Layer Security (TLS): [RFC5246] and [RFC6347] 1146 o Internet X.509 Public Key Infrastructure: [RFC5280] 1148 o HTTP security: Section 9 of [RFC7230], Section 9 of [RFC7231], 1149 etc. 1151 o CoAP security: Section 11 of [RFC7252] 1153 o URI security: Section 7 of [RFC3986] 1155 IoT-specific security is mainly work in progress at the time of 1156 writing. First specifications include: 1158 o (D)TLS Profiles for the Internet of Things: [RFC7925] 1160 Further IoT security considerations are available in 1161 [I-D.irtf-t2trg-iot-seccons]. 1163 8. Acknowledgement 1165 The authors would like to thank Mert Ocak, Heidi-Maria Back, Tero 1166 Kauppinen, Michael Koster, Robby Simpson, Ravi Subramaniam, Dave 1167 Thaler, Erik Wilde, and Niklas Widell for the reviews and feedback. 1169 9. References 1171 9.1. Normative References 1173 [I-D.ietf-core-dev-urn] 1174 Arkko, J., Jennings, C., and Z. Shelby, "Uniform Resource 1175 Names for Device Identifiers", draft-ietf-core-dev-urn-03 1176 (work in progress), October 2018. 1178 [I-D.ietf-core-object-security] 1179 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1180 "Object Security for Constrained RESTful Environments 1181 (OSCORE)", draft-ietf-core-object-security-16 (work in 1182 progress), March 2019. 1184 [I-D.ietf-core-resource-directory] 1185 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 1186 Amsuess, "CoRE Resource Directory", draft-ietf-core- 1187 resource-directory-20 (work in progress), March 2019. 1189 [REST] Fielding, R., "Architectural Styles and the Design of 1190 Network-based Software Architectures", Ph.D. Dissertation, 1191 University of California, Irvine , 2000. 1193 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1194 Resource Identifier (URI): Generic Syntax", STD 66, 1195 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1196 . 1198 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1199 (TLS) Protocol Version 1.2", RFC 5246, 1200 DOI 10.17487/RFC5246, August 2008, 1201 . 1203 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1204 Housley, R., and W. Polk, "Internet X.509 Public Key 1205 Infrastructure Certificate and Certificate Revocation List 1206 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1207 . 1209 [RFC5590] Harrington, D. and J. Schoenwaelder, "Transport Subsystem 1210 for the Simple Network Management Protocol (SNMP)", 1211 STD 78, RFC 5590, DOI 10.17487/RFC5590, June 2009, 1212 . 1214 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 1215 DOI 10.17487/RFC5988, October 2010, 1216 . 1218 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 1219 "Known Issues and Best Practices for the Use of Long 1220 Polling and Streaming in Bidirectional HTTP", RFC 6202, 1221 DOI 10.17487/RFC6202, April 2011, 1222 . 1224 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1225 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1226 January 2012, . 1228 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1229 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1230 . 1232 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1233 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1234 October 2013, . 1236 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1237 Protocol (HTTP/1.1): Message Syntax and Routing", 1238 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1239 . 1241 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1242 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1243 DOI 10.17487/RFC7231, June 2014, 1244 . 1246 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1247 Application Protocol (CoAP)", RFC 7641, 1248 DOI 10.17487/RFC7641, September 2015, 1249 . 1251 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1252 the Constrained Application Protocol (CoAP)", RFC 7959, 1253 DOI 10.17487/RFC7959, August 2016, 1254 . 1256 [W3C.REC-exi-20110310] 1257 Schneider, J. and T. Kamiya, "Efficient XML Interchange 1258 (EXI) Format 1.0", World Wide Web Consortium 1259 Recommendation REC-exi-20110310, March 2011, 1260 . 1262 [W3C.REC-html5-20141028] 1263 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 1264 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 1265 World Wide Web Consortium Recommendation REC- 1266 html5-20141028, October 2014, 1267 . 1269 9.2. Informative References 1271 [CollectionJSON] 1272 Amundsen, M., "Collection+JSON - Document Format", 1273 February 2013, 1274 . 1276 [I-D.handrews-json-schema-validation] 1277 Wright, A., Andrews, H., and G. Luff, "JSON Schema 1278 Validation: A Vocabulary for Structural Validation of 1279 JSON", draft-handrews-json-schema-validation-01 (work in 1280 progress), March 2018. 1282 [I-D.hartke-core-apps] 1283 Hartke, K., "CoRE Applications", draft-hartke-core-apps-08 1284 (work in progress), October 2018. 1286 [I-D.ietf-core-coap-pubsub] 1287 Koster, M., Keranen, A., and J. Jimenez, "Publish- 1288 Subscribe Broker for the Constrained Application Protocol 1289 (CoAP)", draft-ietf-core-coap-pubsub-08 (work in 1290 progress), March 2019. 1292 [I-D.irtf-t2trg-iot-seccons] 1293 Garcia-Morchon, O., Kumar, S., and M. Sethi, "State-of- 1294 the-Art and Challenges for the Internet of Things 1295 Security", draft-irtf-t2trg-iot-seccons-16 (work in 1296 progress), December 2018. 1298 [IANA-CoAP-media] 1299 "CoAP Content-Formats", n.d., 1300 . 1303 [IANA-media-types] 1304 "Media Types", n.d., . 1307 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1308 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1309 . 1311 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 1312 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013, 1313 . 1315 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 1316 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 1317 2013, . 1319 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1320 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1321 2014, . 1323 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1324 Constrained-Node Networks", RFC 7228, 1325 DOI 10.17487/RFC7228, May 2014, 1326 . 1328 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1329 Application Protocol (CoAP)", RFC 7252, 1330 DOI 10.17487/RFC7252, June 2014, 1331 . 1333 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 1334 RFC 7320, DOI 10.17487/RFC7320, July 2014, 1335 . 1337 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1338 Security (TLS) / Datagram Transport Layer Security (DTLS) 1339 Profiles for the Internet of Things", RFC 7925, 1340 DOI 10.17487/RFC7925, July 2016, 1341 . 1343 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1344 FETCH Methods for the Constrained Application Protocol 1345 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1346 . 1348 [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 1349 Bormann, "Sensor Measurement Lists (SenML)", RFC 8428, 1350 DOI 10.17487/RFC8428, August 2018, 1351 . 1353 [W3C-TD] Kaebisch, S. and T. Kamiya, "Web of Things (WoT) Thing 1354 Description", April 2018, 1355 . 1357 Appendix A. Future Work 1359 o Interface semantics: shared knowledge among system components (URI 1360 schemes, media types, relation types, well-known locations; see 1361 core-apps) 1363 o Unreliable (best effort) communication, robust communication in 1364 network with high packet loss, 3-way commit 1366 o Discuss directories, such as CoAP Resource Directory 1368 o More information on how to design resources; choosing what is 1369 modeled as a resource, etc. 1371 Authors' Addresses 1373 Ari Keranen 1374 Ericsson 1375 Jorvas 02420 1376 Finland 1378 Email: ari.keranen@ericsson.com 1380 Matthias Kovatsch 1381 Siemens AG 1382 Otto-Hahn-Ring 6 1383 Munich D-81739 1384 Germany 1386 Email: matthias.kovatsch@siemens.com 1388 Klaus Hartke 1389 Ericsson 1390 Torshamnsgatan 23 1391 Stockholm SE-16483 1392 Sweden 1394 Email: klaus.hartke@ericsson.com