idnits 2.17.1 draft-hartke-core-apps-02.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 (August 18, 2015) is 3167 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFCXXXX' is mentioned on line 406, but not defined ** 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 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Thing-to-Thing Research Group K. Hartke 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Informational August 18, 2015 5 Expires: February 19, 2016 7 CoRE Application Descriptions 8 draft-hartke-core-apps-02 10 Abstract 12 The interfaces of RESTful, hypertext-driven applications consist of 13 reusable, self-descriptive components such as Internet media types 14 and link relation types. This document defines a template that 15 application designers can use to describe their application's 16 interface in a structured way so that other parties can develop 17 interoperable clients and servers or reuse the components in their 18 own applications. 20 Note to Readers 22 This Internet-Draft should be discussed on the Thing-to-Thing 23 Research Group (T2TRG) mailing list . 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on February 19, 2016. 42 Copyright Notice 44 Copyright (c) 2015 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Application Descriptions . . . . . . . . . . . . . . . . . . 3 61 2.1. Communication Protocols . . . . . . . . . . . . . . . . . 3 62 2.2. URI Schemes . . . . . . . . . . . . . . . . . . . . . . . 3 63 2.3. Internet Media Types . . . . . . . . . . . . . . . . . . 4 64 2.4. Representation Formats . . . . . . . . . . . . . . . . . 5 65 2.5. Link Relation Types . . . . . . . . . . . . . . . . . . . 6 66 2.6. Form Relation Types . . . . . . . . . . . . . . . . . . . 7 67 2.7. Well-Known Locations . . . . . . . . . . . . . . . . . . 7 68 2.8. URI Structures . . . . . . . . . . . . . . . . . . . . . 7 69 3. Template . . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 71 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 72 5.1. Form Relation Type Registry . . . . . . . . . . . . . . . 8 73 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 74 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 75 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 76 7.2. Informative References . . . . . . . . . . . . . . . . . 10 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 79 1. Introduction 81 The Constrained Application Protocol (CoAP) [RFC7252] is designed to 82 enable applications implementing the REST architectural style [REST] 83 in Constrained-Node Networks [RFC7228]. 85 As CoAP applications are implemented and deployed, it becomes 86 increasingly important to be able to describe them in some structured 87 way in order to promote interoperability and reuse. Previous efforts 88 like WADL [WADL] however focus on code generation from machine- 89 readable service descriptions and are not truly RESTful [DWNWADL]. 91 REST application interfaces (APIs) are by definition hypertext-driven 92 [RESTAPI]. This means that the interface is a description of the 93 common vocabulary between the client and the server, centered around 94 Internet media types and link relation types, rather than a static 95 list of resources and the operations supported on them. 97 RESTful applications are often easy to understand, but require some 98 design effort. This is because application designers do not only 99 have to take current requirements into consideration, but also 100 anticipate changes that may be required in the future. The reward is 101 long-term stability and evolvability ("design for decades"). REST is 102 intended for long-lived network-based applications that span multiple 103 organizations [RESTAPI]. 105 This document defines a template for describing the interface of 106 RESTful, hypertext-driven applications in Constrained RESTful 107 Environments (CoRE). 109 2. Application Descriptions 111 A CoRE Application Description is a named set of reusable, self- 112 descriptive components. It is comprised of: 114 o URI schemes that identify communication protocols, 116 o Internet media types that identify representation formats, 118 o link relation types that identify link semantics, 120 o form relation types that identify form semantics, and 122 o optionally, well-known locations. 124 Together, these components provide the specific, in-band instructions 125 for interfacing with a given service. 127 2.1. Communication Protocols 129 The foundation of a hypertext-driven REST API are the communication 130 protocol(s) spoken between a client and a server. Although HTTP/1.1 131 [RFC7230] is by far the most common communication protocol for REST 132 APIs, a REST API should typically not be dependent on any specific 133 communication protocol. 135 2.2. URI Schemes 137 The use of a particular protocol is guided by URI schemes [RFC7595] 138 that describe the syntax and semantics of URI references found in 139 links and forms (Section 2.4). 141 A URI scheme refers to a family of protocols, typically distinguished 142 by a version number. For example, the "http" URI scheme refers to 143 the two members of the HTTP family of protocols: HTTP/1.1 [RFC7230], 144 and HTTP/2 [RFC7540]. The specific HTTP version is negotiated 145 between the client and the server through version indicators in the 146 protocol or the TLS application-layer protocol negotiation (ALPN) 147 extension [RFC7301]. 149 IANA maintains a list of registered URI schemes at 150 . 152 2.3. Internet Media Types 154 One of the most important aspect of hypertext-driven communications 155 is the concept of media types [RFC6838]. Media types are used to 156 label representations so that it is known how the representation 157 should be interpreted, and how it is encoded. The core of an 158 application description should be one or more hypertext media types. 160 A media type identifies a versioned series of representation formats 161 (Section 2.4): a media type does not identify a particular version of 162 a representation format; rather, the media type identifies the 163 family, and includes provisions for version indicator(s) embedded in 164 the representations themselves to determine more precisely the nature 165 of how the data is to be interpreted. A new media type is only 166 needed to designate a completely incompatible format [MIMEWEB]. 168 Media types consist of a top-level type and a subtype, structured 169 into trees. Optionally, media types can have parameters. For 170 example, the media type "text/plain; charset=utf-8" is a subtype for 171 generic text under the "text" top-level type in the standards tree, 172 and has a parameter "charset" set to "utf-8". 174 Media types can be further refined by structured type name suffixes 175 (e.g., "+xml" appended to the base subtype name; see Section 4.2.8 of 176 RFC 6838), or by subtype information embedded in the representations 177 themselves (e.g., "xmlns" declarations in XML documents [XMLNS]). 178 Structured type name suffixes should be preferred, because embedded 179 subtype information cannot be negotiated (e.g., using the CoAP Accept 180 option). 182 A media type must be determined from in-band information (e.g., from 183 the CoAP Content-Format option). Clients must not assume a structure 184 from the application context or other out-of-band information. 186 IANA maintains a list of registered Internet media types at 187 . 189 IANA maintains a list of registered structured suffixes at 190 . 192 IANA maintains a list of registered CoAP content formats at 193 . 195 2.4. Representation Formats 197 In RESTful applications, clients and servers exchange representations 198 that capture the current or intended state of a resource and that are 199 labeled with a media type. A representation is a sequence of bytes 200 whose structure and semantics are specified by a representation 201 format, a set of rules for encoding information. 203 Representation formats should generally allow clients with different 204 goals, so they can do different things with the same data. The 205 specification of a representation format "describes a problem space, 206 not a prescribed relationship between client and server. Client and 207 server must share an understanding of the representations they're 208 passing back and forth, but they don't need to have the same idea of 209 what the problem is that needs to be solved." [WEBAPIS] 211 Representation formats and their specifications evolve over time. It 212 is part of the responsibility of the designer of a new version of a 213 format to try to insure both forward and backward compatibility: new 214 documents should work reasonably (with some fallback) with old 215 processors, and old documents should work reasonably with new 216 processors [MIMEWEB]. 218 Representation formats enable hypertext-driven applications when they 219 support the expression of hypermedia controls: links (Section 2.4.1) 220 and/or forms (Section 2.4.2). 222 2.4.1. Links 224 A link is the primary means for a client to change application state, 225 i.e., to navigate from one resource to another. A link is a typed 226 connection between two resources [RFC5988], and is comprised of: 228 o a context (usually the current resource), 230 o a link relation type that identifies the semantics of the link 231 (Section 2.5), 233 o a target resource URI, and 235 o optionally, attributes that describe the link target. 237 A link can be viewed as a statement of the form "{context IRI} has a 238 {relation type} resource at {target URI}, which has {target 239 attributes}" [RFC5988]. For example, might 240 have a "terms-of-service" resource at , which 241 has the media type "text/html". 243 There are two special kind of links: 245 o An embedding link is a link with the additional hint that it, when 246 processed, should be substituted with a representation of the 247 referenced resource. Thus, traversing an embedding link adds to 248 the application state, rather than replacing it. 250 o A templated link is a link where the client constructs the target 251 resource URI from provided in-band instructions. The specific 252 rules for such instructions are described by the representation 253 format. URI Templates [RFC6570] provide a generic way to 254 construct URIs through variable expansion. 256 2.4.2. Forms 258 A form is the primary means for a client to change resource state. 259 It is comprised of: 261 o a context (usually the current resource), 263 o a form relation type that identifies the semantics of the form 264 (Section 2.6), 266 o a target resource URI, 268 o a submission method (PUT, POST, PATCH, or DELETE), and 270 o and a description of a representation that the service accepts as 271 part of form submission. This description can be a set of form 272 fields, or simply a list of acceptable media types. 274 A form can be viewed as an instruction of the form "To {relation 275 type} {context}, make a {method} request to {target URI}". For 276 example, to "create-item" in , a 277 client might make a POST request to . 279 Note: A form with a submission method of GET is, strictly speaking, 280 a templated link, since it provides a way to construct a URI and 281 does not change resource state. 283 2.5. Link Relation Types 285 A link relation type identifies the semantics of a link [RFC5988]. 286 For example, a link with the relation type "copyright" indicates that 287 the resource identified by the target URI is a statement of the 288 copyright terms applying to the current context. 290 Relation types are not to be confused with media types [RFC6838]; 291 they do not identify the format of the representation that results 292 when the link is dereferenced. Rather, they only describe how the 293 current context is related to another resource. 295 IANA maintains a list of registered link relation types at 296 . 298 2.6. Form Relation Types 300 A form relation type identifies the semantics of a form. For 301 example, a form with the relation type "create-item" indicates that a 302 new item can be created within the current context by making a 303 request to the resource identified by the target URI. 305 IANA maintains a list of registered link relation types at 306 . 308 2.7. Well-Known Locations 310 Some applications may require the discovery of information about a 311 host ("site-wide metadata"). For example, [RFC6415] defines a 312 metadata document format for describing hosts; similarly, [RFC6690] 313 defines a link format for the discovery of resources hosted by a 314 server. 316 Applications that need to define a resource for site-wide metadata 317 can register new "well-known locations". [RFC5785] defines a path 318 prefix in "http" and "https" URIs for this purpose, "/.well-known/"; 319 [RFC7252] extends this concept to "coap" and "coaps" URIs. 321 IANA maintains a list of registered well-known URIs at 322 . 324 2.8. URI Structures 326 Application descriptions must not constrain URI structures in ways 327 that aren't explicitly allowed by [RFC3986]. In particular, 328 mandating particular forms of URI substructure is inappropriate. 329 [RFC7320] describes this problematic practice and provides some 330 acceptable alternatives for use in application descriptions. 332 3. Template 334 Application name: 336 URI schemes: 338 Media types: 340 Link relations: 342 Form relations: 344 Well-known locations: 346 Interoperability considerations: 348 Security considerations: 350 Contact: 352 Author/Change controller: 354 4. Security Considerations 356 The security considerations of [RFC3986], [RFC5785], [RFC5988], 357 [RFC6570], [RFC6838], [RFC7320], and [RFC7595] are inherited. 359 All components of an application description are expected to contain 360 clear security considerations. Application descriptions should 361 further contain security considerations that need to be taken into 362 account for the security of the overall application. 364 5. IANA Considerations 366 5.1. Form Relation Type Registry 368 This specification establishes the Form Relation Type registry. 370 5.1.1. Registering New Form Relation Types 372 Form relation types are registered in the same way as link relation 373 types [RFC5988], i.e., they are registered on the advice of a 374 Designated Expert, with a Specification Required. 376 The requirements for registered relation types are adopted from 377 [RFC5988], Section 4.1. 379 The registration template is: 381 o Relation Name: 383 o Description: 385 o Reference: 387 o Notes: [optional] 389 5.1.2. Initial Registry Contents 391 The Form Relation Type registry's initial contents are: 393 o Relation Name: create-item 394 Description: Refers to a resource that can be used to create a 395 resource in a collection of resources. 396 Reference: [RFCXXXX] 398 o Relation Name: delete 399 Description: Refers to a resource that can be used to delete a 400 resource in a collection of resources. 401 Reference: [RFCXXXX] 403 o Relation Name: update 404 Description: Refers to a resource that can be used to update the 405 state of the form's context. 406 Reference: [RFCXXXX] 408 6. Acknowledgements 410 Thanks to Jan Algermissen, Mike Amundsen, Olaf Bergmann, Carsten 411 Bormann, Stefanie Gerdes, Mike Kelly, Michael Koster, Matthias 412 Kovatsch, Julian Reschke, Teemu Savolainen, Bilhanan Silverajan, and 413 Erik Wilde for helpful comments and discussions that have shaped the 414 document. 416 Some of the text in this document has been borrowed from [RESTAPI], 417 [RFC5988], [RFC7320], and [MIMEWEB]. All errors are my own. 419 This work was funded in part by Nokia. 421 7. References 423 7.1. Normative References 425 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 426 Resource Identifier (URI): Generic Syntax", STD 66, 427 RFC 3986, DOI 10.17487/RFC3986, January 2005, 428 . 430 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 431 Uniform Resource Identifiers (URIs)", RFC 5785, 432 DOI 10.17487/RFC5785, April 2010, 433 . 435 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 436 DOI 10.17487/RFC5988, October 2010, 437 . 439 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 440 and D. Orchard, "URI Template", RFC 6570, 441 DOI 10.17487/RFC6570, March 2012, 442 . 444 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 445 Specifications and Registration Procedures", BCP 13, 446 RFC 6838, DOI 10.17487/RFC6838, January 2013, 447 . 449 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, 450 RFC 7320, DOI 10.17487/RFC7320, July 2014, 451 . 453 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 454 and Registration Procedures for URI Schemes", BCP 35, 455 RFC 7595, DOI 10.17487/RFC7595, June 2015, 456 . 458 7.2. Informative References 460 [DWNWADL] Gregorio, J., "Do we need WADL?", June 2007, 461 . 463 [MIMEWEB] Masinter, L., "MIME and the Web", draft-masinter-mime-web- 464 info-02 (work in progress), January 2011. 466 [REST] Fielding, R., "Architectural Styles and the Design of 467 Network-based Software Architectures", Ph.D. Dissertation, 468 University of California, Irvine, 2000, 469 . 472 [RESTAPI] Fielding, R., "REST APIs must be hypertext-driven", 473 October 2008, . 476 [RFC6415] Hammer-Lahav, E., Ed. and B. Cook, "Web Host Metadata", 477 RFC 6415, DOI 10.17487/RFC6415, October 2011, 478 . 480 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 481 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 482 . 484 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 485 Constrained-Node Networks", RFC 7228, 486 DOI 10.17487/RFC7228, May 2014, 487 . 489 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 490 Protocol (HTTP/1.1): Message Syntax and Routing", 491 RFC 7230, DOI 10.17487/RFC7230, June 2014, 492 . 494 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 495 Application Protocol (CoAP)", RFC 7252, 496 DOI 10.17487/RFC7252, June 2014, 497 . 499 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 500 "Transport Layer Security (TLS) Application-Layer Protocol 501 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 502 July 2014, . 504 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 505 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 506 DOI 10.17487/RFC7540, May 2015, 507 . 509 [WADL] Hadley, M., "Web Application Description Language", World 510 Wide Web Consortium Member Submission SUBM-wadl-20090831, 511 August 2009, 512 . 514 [WEBAPIS] Richardson, L. and M. Amundsen, "RESTful Web APIs", 515 O'Reilly, September 2013. 517 [XMLNS] Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 518 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 519 Wide Web Consortium Recommendation REC-xml-names-20091208, 520 December 2009, 521 . 523 Author's Address 525 Klaus Hartke 526 Universitaet Bremen TZI 527 Postfach 330440 528 Bremen D-28359 529 Germany 531 Phone: +49-421-218-63905 532 EMail: hartke@tzi.org