idnits 2.17.1 draft-hartke-core-apps-00.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 16, 2015) is 3297 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7320 (Obsoleted by RFC 8820) -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group K. Hartke 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Informational April 16, 2015 5 Expires: October 18, 2015 7 CoRE Application Descriptions 8 draft-hartke-core-apps-00 10 Abstract 12 This document defines a template for describing the interface of 13 RESTful, hypertext-driven applications in Constrained RESTful 14 Environments (CoRE). 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on October 18, 2015. 33 Copyright Notice 35 Copyright (c) 2015 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Application Descriptions . . . . . . . . . . . . . . . . . . 3 52 2.1. Communication Protocols and URI Schemes . . . . . . . . . 3 53 2.2. Internet Media Types . . . . . . . . . . . . . . . . . . 3 54 2.3. Representation Formats . . . . . . . . . . . . . . . . . 4 55 2.4. Link Relation Types . . . . . . . . . . . . . . . . . . . 4 56 2.5. Well-Known Locations . . . . . . . . . . . . . . . . . . 5 57 2.6. URI Structures . . . . . . . . . . . . . . . . . . . . . 5 58 3. Template . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 61 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 62 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 7.1. Normative References . . . . . . . . . . . . . . . . . . 6 64 7.2. Informative References . . . . . . . . . . . . . . . . . 7 65 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 67 1. Introduction 69 The Constrained Application Protocol (CoAP) [RFC7252] is designed to 70 enable applications implementing the REST architectural style [REST] 71 in Constrained-Node Networks [RFC7228]. 73 As CoAP applications are implemented and deployed, it becomes 74 increasingly important to be able to describe them in some structured 75 way to promote interoperability and reuse. Previous efforts like 76 WADL [WADL] focus on code generation from machine-readable service 77 descriptions and are not truly RESTful [DWNWADL]. 79 REST APIs must be hypertext-driven [RESTAPI]. This means that the 80 application interface is a description of the common vocabulary 81 between the client and the server, centered around media types and 82 link relation types, rather than a list of resources and the 83 operations supported on them. 85 RESTful applications are often easy to understand, but require some 86 design effort. The reward is long-term stability and evolvability 87 ("design for decades"). REST is intended for long-lived network- 88 based applications that span multiple organizations. 90 This document defines a template for describing the interface of 91 RESTful, hypertext-driven applications in Constrained RESTful 92 Environments (CoRE). 94 2. Application Descriptions 96 In this specification, an application description is a named set of 97 reusable, self-descriptive components, and is comprised of: 99 o Communication protocols, 101 o URI schemes, 103 o Internet media types, 105 o link relation types, and 107 o optionally, well-known locations. 109 Together, these components provide the specific, in-band instructions 110 for interfacing with a given service. 112 2.1. Communication Protocols and URI Schemes 114 The basics of a hypertext-driven REST API are the communication 115 protocol(s) spoken between a client and a server. Although HTTP 116 [RFC7230] is by far the most common communication protocol for REST 117 APIs, a REST API should typically not be dependent on a specific 118 communication protocol. 120 The use of a particular protocol is guided by URI schemes [RFC3986] 121 describing the URI references found in links and forms (Section 2.3). 122 For example, the COAPS URI scheme identifies resources that are 123 accessible over CoAP [RFC7252] using DTLS [RFC6347] for transport 124 security. 126 IANA maintains a list of registered URI schemes at 127 . 129 2.2. Internet Media Types 131 One of the most important aspect of hypertext-driven communications 132 is the concept of media types. Media types are used to label 133 resource representations so that it is known how the representation 134 should be interpreted, and how it is encoded. The core of an 135 application description should be one or more hypertext media types. 137 Media types consist of a top-level type and a subtype, structured 138 into trees [RFC6838]. Optionally, media types can have parameters. 139 For example, the media type "text/plain; charset=utf-8" is a subtype 140 for generic text under the "text" top-level type in the standards 141 tree, and has a parameter "charset" set to "utf-8". 143 Media types can be further refined by structured type name suffixes 144 (e.g., "+xml" appended to the base subtype name; see Section 4.2.8 of 145 [RFC6838]), or by subtype information embedded in the representations 146 themselves (e.g., "xmlns" declarations in XML documents). 148 A media type must be determined from in-band information (e.g., from 149 the CoAP Content-Format option). Clients must not assume a structure 150 from the application context or other out-of-band information. 152 IANA maintains a list of registered Internet media types at 153 . 155 IANA maintains a list of registered structured suffixes at 156 . 158 IANA maintains a list of registered CoAP content formats at 159 . 161 2.3. Representation Formats 163 In RESTful applications, clients and servers exchange representations 164 that capture the current or intended state of a resource and are 165 labeled with a media type. A representation is a sequence of bytes 166 whose structure and semantics are specified by a representation 167 format, a set of rules for encoding information in digital form. 169 Representation formats enable hypertext-driven applications when they 170 support the expression of links and/or forms. 172 o A link is a typed connection between two resources [RFC5988] and 173 is the primary means for a client to change application state. It 174 is comprised of a context (usually the current resource), a link 175 relation type (Section 2.4), a target resource URI, and, 176 optionally, some attributes that describe the link target. URI 177 Templates [RFC6570] provide a way to describe a range of URIs as 178 the link target through variable expansion. 180 o A form is associated with a single resource and is the primary 181 means for a client to change resource state. It is comprised of a 182 target resource URI, a submission method (PUT, POST, PATCH, or 183 DELETE), and, optionally, a description of a representation that 184 the service accepts as part of the form submission. 186 2.4. Link Relation Types 188 A link relation type identifies the semantics of a link [RFC5988]. 189 For example, a link with the relation type "copyright" indicates that 190 the resource identified by the target URI is a statement of the 191 copyright terms applying to the current context. 193 Relation types are not to be confused with media types [RFC6838]; 194 they do not identify the format of the representation that results 195 when the link is dereferenced. Rather, they only describe how the 196 current context is related to another resource. 198 IANA maintains a list of registered link relation types at 199 . 201 2.5. Well-Known Locations 203 Some applications may require the discovery of information about a 204 host ("site-wide metadata"). For example, [RFC6415] defines a 205 metadata document format for describing hosts; similarly, [RFC6690] 206 defines a link format for the discovery of resources hosted by a 207 server. 209 Applications that need to define a resource for site-wide metadata 210 can register new "well-known locations". [RFC5785] defines a path 211 prefix in HTTP(S) URIs for this purpose, "/.well-known/"; [RFC7252] 212 extends this concept to COAP(S) URIs. 214 IANA maintains a list of registered well-known URIs at 215 . 217 2.6. URI Structures 219 Application descriptions must not constrain URI structures in ways 220 that aren't explicitly allowed by [RFC3986]. In particular, 221 mandating particular forms of URI substructure is inappropriate. 222 [RFC7320] describes this problematic practice and provides some 223 acceptable alternatives for use in application descriptions. 225 3. Template 227 Application name: 229 Protocols: 231 URI schemes: 233 Media types: 235 Link relations: 237 Well-known locations: 239 4. Security Considerations 241 This document raises no new security issues beyond those described in 242 the referenced documents. 244 5. IANA Considerations 246 This document includes no request to IANA. 248 6. Acknowledgements 250 Thanks to Carsten Bormann, Stefanie Gerdes, Matthias Kovatsch, Teemu 251 Savolainen, and Bilhanan Silverajan for helpful comments and 252 discussions that have shaped the document. 254 Some of the text in this document has been borrowed from [RESTAPI], 255 [RFC5988], and [RFC7320]. All errors are my own. 257 This work was funded in part by Nokia. 259 7. References 261 7.1. Normative References 263 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 264 Resource Identifier (URI): Generic Syntax", STD 66, RFC 265 3986, January 2005. 267 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 268 Uniform Resource Identifiers (URIs)", RFC 5785, April 269 2010. 271 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 273 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 274 and D. Orchard, "URI Template", RFC 6570, March 2012. 276 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 277 Specifications and Registration Procedures", BCP 13, RFC 278 6838, January 2013. 280 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 281 7320, July 2014. 283 7.2. Informative References 285 [DWNWADL] Gregorio, J., "Do we need WADL?", June 2007, 286 . 288 [REST] Fielding, R., "Architectural Styles and the Design of 289 Network-based Software Architectures", Ph.D. Dissertation, 290 University of California, Irvine, 2000, 291 . 294 [RESTAPI] Fielding, R., "REST APIs must be hypertext-driven", 295 October 2008, . 298 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 299 Security Version 1.2", RFC 6347, January 2012. 301 [RFC6415] Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC 302 6415, October 2011. 304 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 305 Format", RFC 6690, August 2012. 307 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 308 Constrained-Node Networks", RFC 7228, May 2014. 310 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 311 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 312 2014. 314 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 315 Application Protocol (CoAP)", RFC 7252, June 2014. 317 [WADL] Hadley, M., "Web Application Description Language", W3C 318 Member Submission SUBM-wadl-200908316, August 2009, 319 . 321 Author's Address 323 Klaus Hartke 324 Universitaet Bremen TZI 325 Postfach 330440 326 Bremen D-28359 327 Germany 329 Phone: +49-421-218-63905 330 EMail: hartke@tzi.org