idnits 2.17.1 draft-keranen-t2trg-rest-iot-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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 363 has weird spacing: '... query frag...' -- The document date (March 13, 2017) is 2595 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 675, but no explicit reference was found in the text == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-02 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-10 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** 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 (-16) exists of draft-ietf-core-senml-05 -- 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: 6 errors (**), 0 flaws (~~), 6 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: September 14, 2017 ETH Zurich 6 March 13, 2017 8 RESTful Design for Internet of Things Systems 9 draft-keranen-t2trg-rest-iot-04 11 Abstract 13 This document gives guidance for designing Internet of Things (IoT) 14 systems that follow the principles of the Representational State 15 Transfer (REST) architectural style. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 14, 2017. 34 Copyright Notice 36 Copyright (c) 2017 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 3. Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 54 3.1. Architecture . . . . . . . . . . . . . . . . . . . . . . 6 55 3.2. System design . . . . . . . . . . . . . . . . . . . . . . 7 56 3.3. Uniform Resource Identifiers (URIs) . . . . . . . . . . . 8 57 3.4. Representations . . . . . . . . . . . . . . . . . . . . . 9 58 3.5. HTTP/CoAP Methods . . . . . . . . . . . . . . . . . . . . 9 59 3.5.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 10 60 3.5.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 10 61 3.5.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 10 62 3.5.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 11 63 3.6. HTTP/CoAP Status/Response Codes . . . . . . . . . . . . . 11 64 4. REST Constraints . . . . . . . . . . . . . . . . . . . . . . 12 65 4.1. Client-Server . . . . . . . . . . . . . . . . . . . . . . 12 66 4.2. Stateless . . . . . . . . . . . . . . . . . . . . . . . . 12 67 4.3. Cache . . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 4.4. Uniform Interface . . . . . . . . . . . . . . . . . . . . 13 69 4.5. Layered System . . . . . . . . . . . . . . . . . . . . . 14 70 4.6. Code-on-Demand . . . . . . . . . . . . . . . . . . . . . 14 71 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 72 6. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 14 73 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 74 7.1. Normative References . . . . . . . . . . . . . . . . . . 15 75 7.2. Informative References . . . . . . . . . . . . . . . . . 16 76 Appendix A. Future Work . . . . . . . . . . . . . . . . . . . . 17 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 79 1. Introduction 81 The Representational State Transfer (REST) architectural style [REST] 82 is a set of guidelines and best practices for building distributed 83 hypermedia systems. At its core is a set of constraints, which when 84 fulfilled enable desirable properties for distributed software 85 systems such as scalability and modifiability. When REST principles 86 are applied to the design of a system, the result is often called 87 RESTful and in particular an API following these principles is called 88 a RESTful API. 90 Different protocols can be used with RESTful systems, but at the time 91 of writing the most common protocols are HTTP [RFC7230] and CoAP 92 [RFC7252]. Since RESTful APIs are often simple and lightweight, they 93 are a good fit for various IoT applications. The goal of this 94 document is to give basic guidance for designing RESTful systems and 95 APIs for IoT applications and give pointers for more information. 96 Design of a good RESTful IoT system has naturally many commonalities 97 with other Web systems. Compared to other systems, the key 98 characteristics of many IoT systems include: 100 o data formats, interaction patterns, and other mechanisms that 101 minimize, or preferably avoid, the need for human interaction 103 o preference for compact and simple data formats to facilitate 104 efficient transfer over (often) constrained networks and 105 lightweight processing in constrained nodes 107 2. Terminology 109 This section explains some of the common terminology that is used in 110 the context of RESTful design for IoT systems. For terminology of 111 constrained nodes and networks, see [RFC7228]. 113 Cache: A local store of response messages and the subsystem that 114 controls storage, retrieval, and deletion of messages in it. 116 Client: A node that sends requests to servers and receives 117 responses. 119 Client State: The state kept by a client between requests. This 120 typically includes the "current" resource, the set of active 121 requests, the history of requests, bookmarks (URIs stored for 122 later retrieval) and application-specific state. (Note that this 123 is called "Application State" in [REST], which has some ambiguity 124 in modern (IoT) systems where the overall state of the distributed 125 application (i.e., application state) is reflected in the union of 126 all Client States and Resource States of all clients and servers 127 involved.) 129 Content Negotiation: The practice of determining the "best" 130 representation for a client when examining the current state of a 131 resource. The most common forms of content negotiation are 132 Proactive Content Negotiation and Reactive Content Negotiation. 134 Form: A hypermedia control that enables a client to change the state 135 of a resource or to construct a query locally. 137 Forward Proxy: An intermediary that is selected by a client, usually 138 via local configuration rules, and that can be tasked to make 139 requests on behalf of the client. This may be useful, for 140 example, when the client lacks the capability to make the request 141 itself or to service the response from a cache in order to reduce 142 response time, network bandwidth and energy consumption. 144 Gateway: A reverse proxy that provides an interface to a non-RESTful 145 system such as legacy systems or alternative technologies such as 146 Bluetooth ATT/GATT. See also "Reverse Proxy". 148 Hypermedia Control: A component embedded in a representation that 149 identifies a resource for future hypermedia interactions, such as 150 a link or a form. If the client engages in an interaction with 151 the identified resource, the result may be a change to resource 152 state and/or client state. 154 Idempotent Method: A method where multiple identical requests with 155 that method lead to the same visible resource state as a single 156 such request. For example, the PUT method replaces the state of a 157 resource with a new state; replacing the state multiple times with 158 the same new state still results in the same state for the 159 resource. However, the response from the server can be different 160 when the same idempotent method is used multiple times. For 161 example when DELETE is used twice on an existing resource, the 162 first request would remove the association and return success 163 acknowledgement whereas the second request would likely result in 164 error response due to non-existing resource. 166 Link: A hypermedia control that enables a client to navigate between 167 resources and thereby change the client state. 169 Media Type: A string such as "text/html" or "application/json" that 170 is used to label representations so that it is known how the 171 representation should be interpreted and how it is encoded. 173 Method: An operation associated with a resource. Common methods 174 include GET, PUT, POST, and DELETE (see Section 3.5 for details). 176 Origin Server: A server that is the definitive source for 177 representations of its resources and the ultimate recipient of any 178 request that intends to modify its resources. In contrast, 179 intermediaries (such as proxies caching a representation) can 180 assume the role of a server, but are not the source for 181 representations as these are acquired from the origin server. 183 Proactive Content Negotiation: A content negotiation mechanism where 184 the server selects a representation based on the expressed 185 preference of the client. For example, in an IoT application, a 186 client could send a request with preferred media type 187 "application/senml+json". 189 Reactive Content Negotiation: A content negotiation mechanism where 190 the client selects a representation from a list of available 191 representations. The list may, for example, be included by a 192 server in an initial response. If the user agent is not satisfied 193 by the initial response representation, it can request one or more 194 of the alternative representations, selected based on metadata 195 (e.g., available media types) included in the response. 197 Representation: A serialization that represents the current or 198 intended state of a resource and that can be transferred between 199 clients and servers. REST requires representations to be self- 200 describing, meaning that there must be metadata that allows peers 201 to understand which representation format is used. Depending on 202 the protocol needs and capabilities, there can be additional 203 metadata that is transmitted along with the representation. 205 Representation Format: A set of rules for serializing resource 206 state. On the Web, the most prevalent representation format is 207 HTML. Other common formats include plain text and formats based 208 on JSON [RFC7159], XML, or RDF. Within IoT systems, often compact 209 formats based on JSON, CBOR [RFC7049], and EXI 210 [W3C.REC-exi-20110310] are used. 212 Representational State Transfer (REST): An architectural style for 213 Internet-scale distributed hypermedia systems. 215 Resource: An item of interest identified by a URI. Anything that 216 can be named can be a resource. A resource often encapsulates a 217 piece of state in a system. Typical resources in an IoT system 218 can be, e.g., a sensor, the current value of a sensor, the 219 location of a device, or the current state of an actuator. 221 Resource State: A model of a resource's possible states that is 222 represented in a supported representation type, typically a media 223 type. Resources can change state because of REST interactions 224 with them, or they can change state for reasons outside of the 225 REST model. 227 Reverse Proxy: An intermediary that appears as a server towards the 228 client but satisfies the requests by forwarding them to the actual 229 server (possibly via one or more other intermediaries). A reverse 230 proxy is often used to encapsulate legacy services, to improve 231 server performance through caching, and to enable load balancing 232 across multiple machines. 234 Safe Method: A method that does not result in any state change on 235 the origin server when applied to a resource. For example, the 236 GET method only returns a representation of the resource state but 237 does not change the resource. Thus, it is always safe for a 238 client to retrieve a representation without affecting server-side 239 state. 241 Server: A node that listens for requests, performs the requested 242 operation and sends responses back to the clients. 244 Uniform Resource Identifier (URI): A global identifier for 245 resources. See Section 3.3 for more details. 247 3. Basics 249 3.1. Architecture 251 The components of a RESTful system are assigned one or both of two 252 roles: client or server. Note that the terms "client" and "server" 253 refer only to the roles that the nodes assume for a particular 254 message exchange. The same node might act as a client in some 255 communications and a server in others. Classic user agents (e.g., 256 Web browsers) are always in the client role and have the initiative 257 to issue requests. Origin servers always have the server role and 258 govern over the resources they host. 260 ________ _________ 261 | | | | 262 | User (C)-------------------(S) Origin | 263 | Agent | | Server | 264 |________| |_________| 265 (Browser) (Web Server) 267 Figure 1: Client-Server Communication 269 Intermediaries (such as forward proxies, reverse proxies, and 270 gateways) implement both roles, but only forward requests to other 271 intermediaries or origin servers. They can also translate requests 272 to different protocols, for instance, as CoAP-HTTP cross-proxies. 274 ________ __________ _________ 275 | | | | | | 276 | User (C)---(S) Inter- (C)--------------------(S) Origin | 277 | Agent | | mediary | | Server | 278 |________| |__________| |_________| 279 (Browser) (Forward Proxy) (Web Server) 281 Figure 2: Communication with Forward Proxy 283 Reverse proxies are usually imposed by the origin server. In 284 addition to the features of a forward proxy, they can also provide an 285 interface for non-RESTful services such as legacy systems or 286 alternative technologies such as Bluetooth ATT/GATT. In this case, 287 reverse proxies are usually called gateways. This property is 288 enabled by the Layered System constraint of REST, which says that a 289 client cannot see beyond the server it is connected to (i.e., it is 290 left unaware of the protocol/paradigm change). 292 ________ __________ _________ 293 | | | | | | 294 | User (C)--------------------(S) Inter- (x)---(x) Origin | 295 | Agent | | mediary | | Server | 296 |________| |__________| |_________| 297 (Browser) (Gateway) (Legacy System) 299 Figure 3: Communication with Reverse Proxy 301 Nodes in IoT systems often implement both roles. Unlike 302 intermediaries, however, they can take the initiative as a client 303 (e.g., to register with a directory, such as CoRE Resource Directory 304 [I-D.ietf-core-resource-directory], or to interact with another 305 thing) and act as origin server at the same time (e.g., to serve 306 sensor values or provide an actuator interface). 308 ________ _________ 309 | | | | 310 | Thing (C)-------------------------------------(S) Origin | 311 | (S) | Server | 312 |________| \ |_________| 313 (Sensor) \ ________ (Resource Directory) 314 \ | | 315 (C) Thing | 316 |________| 317 (Controller) 319 Figure 4: Constrained RESTful environments 321 3.2. System design 323 When designing a RESTful system, the state of the distributed 324 application must be assigned to the different components. Here, it 325 is important to distinguish between "client state" and "resource 326 state". 328 Client state encompasses the control flow and the interactions 329 between the components (see Section 2). Following the Stateless 330 constraint, the client state must be kept only on clients. That is, 331 there is no establishment of shared information about future 332 interactions between client and server (usually called a session). 333 On the one hand, this makes requests a bit more verbose since every 334 request must contain all the information necessary to process it. On 335 the other hand, this makes servers efficient and scalable, since they 336 do not have to keep any state about their clients. Requests can 337 easily be distributed over multiple worker threads or server 338 instances. For the IoT systems, it lowers the memory requirements 339 for server implementations, which is particularly important for 340 constrained servers (e.g., sensor nodes) and servers serving large 341 amount of clients (e.g., Resource Directory). 343 Resource state includes the more persistent data of an application 344 (i.e., independent of the client control flow and lifetime). This 345 can be static data such as device descriptions, persistent data such 346 as system configuration, but also dynamic data such as the current 347 value of a sensor on a thing. 349 3.3. Uniform Resource Identifiers (URIs) 351 An important part of RESTful API design is to model the system as a 352 set of resources whose state can be retrieved and/or modified and 353 where resources can be potentially also created and/or deleted. 355 Uniform Resource Identifiers (URIs) are used to indicate a resource 356 for interaction, to reference a resource from another resource, to 357 advertise or bookmark a resource, or to index a resource by search 358 engines. 360 foo://example.com:8042/over/there?name=ferret#nose 361 \_/ \______________/\_________/ \_________/ \__/ 362 | | | | | 363 scheme authority path query fragment 365 A URI is a sequence of characters that matches the syntax defined in 366 [RFC3986]. It consists of a hierarchical sequence of five 367 components: scheme, authority, path, query, and fragment (from most 368 significant to least significant). A scheme creates a namespace for 369 resources and defines how the following components identify a 370 resource within that namespace. The authority identifies an entity 371 that governs part of the namespace, such as the server 372 "www.example.org" in the "http" scheme. A host name (e.g., a fully 373 qualified domain name) or an IP address, potentially followed by a 374 transport layer port number, are usually used in the authority 375 component for the "http" and "coap" schemes. The path and query 376 contain data to identify a resource within the scope of the URI's 377 scheme and naming authority. The fragment allows to refer to some 378 portion of the resource, such as a section in an HTML document. 379 However, fragments are processed only at client side and not sent on 380 the wire. [RFC7320] provides more details on URI design and 381 ownership with best current practices for establishing URI 382 structures, conventions, and formats. 384 For RESTful IoT applications, typical schemes include "https", 385 "coaps", "http", and "coap". These refer to HTTP and CoAP, with and 386 without Transport Layer Security (TLS) [RFC5246]. (CoAP uses 387 Datagram TLS (DTLS) [RFC6347], the variant of TLS for UDP.) These 388 four schemes also provide means for locating the resource; using the 389 HTTP protocol for "http" and "https", and with the CoAP protocol for 390 "coap" and "coaps". If the scheme is different for two URIs (e.g., 391 "coap" vs. "coaps"), it is important to note that even if the rest of 392 the URI is identical, these are two different resources, in two 393 distinct namespaces. 395 The query parameters can be used to parametrize the resource. For 396 example, a GET request may use query parameters to request the server 397 to send only certain kind data of the resource (i.e., filtering the 398 response). Query parameters in PUT and POST requests do not have 399 such established semantics and are not commonly used. Whether the 400 order of the query parameters matters in URIs is unspecified and they 401 can be re-ordered e.g., by proxies. Therefore applications should 402 not rely on their order; see Section 3.3 of [RFC6943] for more 403 details. 405 3.4. Representations 407 Clients can retrieve the resource state from an origin server or 408 manipulate resource state on the origin server by transferring 409 resource representations. Resource representations have a media type 410 that tells how the representation should be interpreted by 411 identifying the representation format used. Typical media types for 412 IoT systems include "text/plain" for simple UTF-8 text, "application/ 413 octet-stream" for arbitrary binary data, "application/json" for the 414 JSON format [RFC7159], "application/senml+json" [I-D.ietf-core-senml] 415 for Sensor Markup Language (SenML) formatted data, "application/cbor" 416 for CBOR [RFC7049], and "application/exi" for EXI 417 [W3C.REC-exi-20110310]. A full list of registered Internet Media 418 Types is available at the IANA registry [IANA-media-types] and 419 numerical media types registered for use with CoAP are listed at CoAP 420 Content-Formats IANA registry [IANA-CoAP-media]. 422 3.5. HTTP/CoAP Methods 424 Section 4.3 of [RFC7231] defines the set of methods in HTTP; 425 Section 5.8 of [RFC7252] defines the set of methods in CoAP. As part 426 of the Uniform Interface constraint, each method can have certain 427 properties that give guarantees to clients: Safe methods do not cause 428 any state change on the origin server when applied to a resource. 429 Idempotent methods can be applied multiple times to the same resource 430 while causing the same visible resource state as a single such 431 request. The following lists the most relevant methods and gives a 432 short explanation of their semantics. 434 3.5.1. GET 436 The GET method requests a current representation for the target 437 resource. Only the origin server needs to know how each of its 438 resource identifiers corresponds to an implementation and how each 439 implementation manages to select and send a current representation of 440 the target resource in a response to GET. 442 A payload within a GET request message has no defined semantics. 444 The GET method is safe and idempotent. 446 3.5.2. POST 448 The POST method requests that the target resource process the 449 representation enclosed in the request according to the resource's 450 own specific semantics. 452 If one or more resources has been created on the origin server as a 453 result of successfully processing a POST request, the origin server 454 sends a 201 (Created) response containing a Location header field 455 that provides an identifier for the resource created and a 456 representation that describes the status of the request while 457 referring to the new resource(s). 459 The POST method is not safe nor idempotent. 461 3.5.3. PUT 463 The PUT method requests that the state of the target resource be 464 created or replaced with the state defined by the representation 465 enclosed in the request message payload. A successful PUT of a given 466 representation would suggest that a subsequent GET on that same 467 target resource will result in an equivalent representation being 468 sent. 470 The fundamental difference between the POST and PUT methods is 471 highlighted by the different intent for the enclosed representation. 472 The target resource in a POST request is intended to handle the 473 enclosed representation according to the resource's own semantics, 474 whereas the enclosed representation in a PUT request is defined as 475 replacing the state of the target resource. Hence, the intent of PUT 476 is idempotent and visible to intermediaries, even though the exact 477 effect is only known by the origin server. 479 The PUT method is not safe, but is idempotent. 481 3.5.4. DELETE 483 The DELETE method requests that the origin server remove the 484 association between the target resource and its current 485 functionality. 487 If the target resource has one or more current representations, they 488 might or might not be destroyed by the origin server, and the 489 associated storage might or might not be reclaimed, depending 490 entirely on the nature of the resource and its implementation by the 491 origin server. 493 The DELETE method is not safe, but is idempotent. 495 3.6. HTTP/CoAP Status/Response Codes 497 Section 6 of [RFC7231] defines a set of Status Codes in HTTP that are 498 used by application to indicate whether a request was understood and 499 satisfied, and how to interpret the answer. Similarly, Section 5.9 500 of [RFC7252] defines the set of Response Codes in CoAP. 502 The status codes consist of three digits (e.g., "404" with HTTP or 503 "4.04" with CoAP) where the first digit expresses the class of the 504 code. Implementations do not need to understand all status codes, 505 but the class of the code must be understood. Codes starting with 1 506 are informational; the request was received and being processed. 507 Codes starting with 2 indicate a successful request. Codes starting 508 with 3 indicate redirection; further action is needed to complete the 509 request. Codes stating with 4 and 5 indicate errors. The codes 510 starting with 4 mean client error (e.g., bad syntax in the request) 511 whereas codes starting with 5 mean server error; there was no 512 apparent problem with the request, but server was not able to fulfill 513 the request. 515 Responses may be stored in a cache to satisfy future, equivalent 516 requests. HTTP and CoAP use two different patterns to decide what 517 responses are cacheable. In HTTP, the cacheability of a response 518 depends on the request method (e.g., responses returned in reply to a 519 GET request are cacheable). In CoAP, the cacheability of a response 520 depends on the response code (e.g., responses with code 2.04 are 521 cacheable). This difference also leads to slightly different 522 semantics for the codes starting with 2; for example, CoAP does not 523 have a 2.00 response code whereas 200 ("OK") is commonly used with 524 HTTP. 526 4. REST Constraints 528 The REST architectural style defines a set of constraints for the 529 system design. When all constraints are applied correctly, REST 530 enables architectural properties of key interest [REST]: 532 o Performance 534 o Scalability 536 o Reliability 538 o Simplicity 540 o Modifiability 542 o Visibility 544 o Portability 546 The following sub-sections briefly summarize the REST constraints and 547 explain how they enable the listed properties. 549 4.1. Client-Server 551 As explained in the Architecture section, RESTful system components 552 have clear roles in every interaction. Clients have the initiative 553 to issue requests, intermediaries can only forward requests, and 554 servers respond requests, while origin servers are the ultimate 555 recipient of requests that intent to modify resource state. 557 This improves simplicity and visibility, as it is clear which 558 component started an interaction. Furthermore, it improves 559 modifiability through a clear separation of concerns. 561 4.2. Stateless 563 The Stateless constraint requires messages to be self-contained. 564 They must contain all the information to process it, independent from 565 previous messages. This allows to strictly separate the client state 566 from the resource state. 568 This improves scalability and reliability, since servers or worker 569 threads can be replicated. It also improves visibility because 570 message traces contain all the information to understand the logged 571 interactions. 573 Furthermore, the Stateless constraint enables caching. 575 4.3. Cache 577 This constraint requires responses to have implicit or explicit 578 cache-control metadata. This enables clients and intermediary to 579 store responses and re-use them to locally answer future requests. 580 The cache-control metadata is necessary to decide whether the 581 information in the cached response is still fresh or stale and needs 582 to be discarded. 584 Cache improves performance, as less data needs to be transferred and 585 response times can be reduced significantly. Less transfers also 586 improves scalability, as origin servers can be protected from too 587 many requests. Local caches furthermore improve reliability, since 588 requests can be answered even if the origin server is temporarily not 589 available. 591 4.4. Uniform Interface 593 RESTful APIs all use the same interface independent of the 594 application. It is defined by: 596 o URIs to identify resources 598 o representation formats to retrieve and manipulate resource state 600 o self-descriptive messages with a standard set of methods (e.g., 601 GET, POST, PUT, DELETE with their guaranteed properties) 603 o hypermedia controls within representations 605 The concept of hypermedia controls is also known as HATEOAS: 606 hypermedia as the engine of application state. The origin server 607 embeds controls for the interface into its representations and 608 thereby informs the client about possible requests. The mostly used 609 control for RESTful systems is Web Linking [RFC5590]. Hypermedia 610 forms are more powerful controls that describe how to construct more 611 complex requests, including representations to modify resource state. 613 While this is the most complex constraints (in particular the 614 hypermedia controls), it improves many different key properties. It 615 improves simplicity, as uniform interfaces are easier to understand. 616 The self-descriptive messages improve visibility. The limitation to 617 a known set of representation formats fosters portability. Most of 618 all, however, this constraint is the key to modifiability, as 619 hypermedia-driven, uniform interfaces allow clients and servers to 620 evolve independently, and hence enable a system to evolve. 622 4.5. Layered System 624 This constraint enforces that a client cannot see beyond the server 625 with which it is interacting. 627 A layered system is easier to modify, as topology changes become 628 transparent. Furthermore, this helps scalability, as intermediaries 629 such as load balancers can be introduced without changing the client 630 side. The clean separation of concerns helps with simplicity. 632 4.6. Code-on-Demand 634 This principle enables origin servers to ship code to clients. 636 Code-on-Demand improves modifiability, since new features can be 637 deployed during runtime (e.g., support for a new representation 638 format). It also improves performance, as the server can provide 639 code for local pre-processing before transferring the data. 641 5. Security Considerations 643 This document does not define new functionality and therefore does 644 not introduce new security concerns. We assume that system designers 645 apply classic Web security on top of the basic RESTful guidance given 646 in this document. Thus, security protocols and considerations from 647 related specifications apply to RESTful IoT design. These include: 649 o Transport Layer Security (TLS): [RFC5246] and [RFC6347] 651 o Internet X.509 Public Key Infrastructure: [RFC5280] 653 o HTTP security: Section 9 of [RFC7230], Section 9 of [RFC7231], 654 etc. 656 o CoAP security: Section 11 of [RFC7252] 658 o URI security: Section 7 of [RFC3986] 660 IoT-specific security is mainly work in progress at the time of 661 writing. First specifications include: 663 o (D)TLS Profiles for the Internet of Things: [RFC7925] 665 6. Acknowledgement 667 The authors would like to thank Mert Ocak, Heidi-Maria Back, Tero 668 Kauppinen, Michael Koster, Robby Simpson, Ravi Subramaniam, Dave 669 Thaler, and Erik Wilde for the reviews and feedback. 671 7. References 673 7.1. Normative References 675 [I-D.ietf-core-object-security] 676 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 677 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 678 object-security-02 (work in progress), March 2017. 680 [I-D.ietf-core-resource-directory] 681 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 682 Resource Directory", draft-ietf-core-resource-directory-10 683 (work in progress), March 2017. 685 [REST] Fielding, R., "Architectural Styles and the Design of 686 Network-based Software Architectures", Ph.D. Dissertation, 687 University of California, Irvine , 2000. 689 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 690 Resource Identifier (URI): Generic Syntax", STD 66, 691 RFC 3986, DOI 10.17487/RFC3986, January 2005, 692 . 694 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 695 (TLS) Protocol Version 1.2", RFC 5246, 696 DOI 10.17487/RFC5246, August 2008, 697 . 699 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 700 Housley, R., and W. Polk, "Internet X.509 Public Key 701 Infrastructure Certificate and Certificate Revocation List 702 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 703 . 705 [RFC5590] Harrington, D. and J. Schoenwaelder, "Transport Subsystem 706 for the Simple Network Management Protocol (SNMP)", 707 STD 78, RFC 5590, DOI 10.17487/RFC5590, June 2009, 708 . 710 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 711 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 712 January 2012, . 714 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 715 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 716 October 2013, . 718 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 719 Protocol (HTTP/1.1): Message Syntax and Routing", 720 RFC 7230, DOI 10.17487/RFC7230, June 2014, 721 . 723 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 724 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 725 DOI 10.17487/RFC7231, June 2014, 726 . 728 [W3C.REC-exi-20110310] 729 Schneider, J. and T. Kamiya, "Efficient XML Interchange 730 (EXI) Format 1.0", World Wide Web Consortium 731 Recommendation REC-exi-20110310, March 2011, 732 . 734 7.2. Informative References 736 [I-D.ietf-core-senml] 737 Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 738 Bormann, "Media Types for Sensor Measurement Lists 739 (SenML)", draft-ietf-core-senml-05 (work in progress), 740 March 2017. 742 [IANA-CoAP-media] 743 "CoAP Content-Formats", n.d., 744 . 747 [IANA-media-types] 748 "Media Types", n.d., . 751 [RFC6943] Thaler, D., Ed., "Issues in Identifier Comparison for 752 Security Purposes", RFC 6943, DOI 10.17487/RFC6943, May 753 2013, . 755 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 756 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 757 2014, . 759 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 760 Constrained-Node Networks", RFC 7228, 761 DOI 10.17487/RFC7228, May 2014, 762 . 764 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 765 Application Protocol (CoAP)", RFC 7252, 766 DOI 10.17487/RFC7252, June 2014, 767 . 769 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 770 RFC 7320, DOI 10.17487/RFC7320, July 2014, 771 . 773 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 774 Security (TLS) / Datagram Transport Layer Security (DTLS) 775 Profiles for the Internet of Things", RFC 7925, 776 DOI 10.17487/RFC7925, July 2016, 777 . 779 Appendix A. Future Work 781 o Interface semantics: shared knowledge among system components (URI 782 schemes, media types, relation types, well-known locations; see 783 core-apps) 785 o Discuss design patterns, such as "Observing state (asynchronous 786 updates) of a resource", "Executing a Function", "Events as 787 State", "Conversion", "Collections", "robust communication in 788 network with high packet loss", "unreliable (best effort) 789 communication", "3-way commit", etc. 791 o Discuss directories, such as CoAP Resource Directory 793 o More information on how to design resources; choosing what is 794 modeled as a resource, etc. 796 Authors' Addresses 798 Ari Keranen 799 Ericsson 800 Jorvas 02420 801 Finland 803 Email: ari.keranen@ericsson.com 804 Matthias Kovatsch 805 ETH Zurich 806 Universitaetstrasse 6 807 Zurich CH-8092 808 Switzerland 810 Email: kovatsch@inf.ethz.ch