idnits 2.17.1 draft-hartke-core-apps-07.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 (February 12, 2017) is 2629 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: 'RFCXXXX' on line 727 ** Obsolete normative reference: RFC 5785 (ref. '4') (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 5988 (ref. '5') (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7320 (ref. '6') (Obsoleted by RFC 8820) -- Obsolete informational reference (is this intentional?): RFC 7540 (ref. '8') (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 7230 (ref. '14') (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7231 (ref. '15') (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 5 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 February 12, 2017 5 Expires: August 16, 2017 7 CoRE Application Descriptions 8 draft-hartke-core-apps-07 10 Abstract 12 The interfaces of RESTful, hypermedia-driven Web applications consist 13 of reusable components such as Internet media types and link relation 14 types. This document proposes CoRE Application Descriptions, a 15 convention for application designers to describe the programmable 16 interfaces of their applications in a structured way so that other 17 parties can easily develop interoperable clients and servers or reuse 18 the components in their own applications. 20 Note to Readers 22 This Internet-Draft should be discussed on the Thing-to-Thing 23 Research Group (T2TRG) mailing list 24 . 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on August 16, 2017. 43 Copyright Notice 45 Copyright (c) 2017 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Application Descriptions . . . . . . . . . . . . . . . . . . 4 62 2.1. URI Schemes . . . . . . . . . . . . . . . . . . . . . . . 4 63 2.2. Internet Media Types . . . . . . . . . . . . . . . . . . 5 64 2.2.1. Representation Formats . . . . . . . . . . . . . . . 6 65 2.2.2. Links . . . . . . . . . . . . . . . . . . . . . . . . 7 66 2.2.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . 8 67 2.3. Link Relation Types . . . . . . . . . . . . . . . . . . . 8 68 2.3.1. Template Variable Names . . . . . . . . . . . . . . . 9 69 2.4. Form Relation Types . . . . . . . . . . . . . . . . . . . 9 70 2.4.1. Form Field Names . . . . . . . . . . . . . . . . . . 10 71 2.5. Well-Known Locations . . . . . . . . . . . . . . . . . . 10 72 3. Application Description Template . . . . . . . . . . . . . . 11 73 4. URI Design Considerations . . . . . . . . . . . . . . . . . . 13 74 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 75 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 76 6.1. Content-Format Registry . . . . . . . . . . . . . . . . . 14 77 6.2. Link Relation Type Registry . . . . . . . . . . . . . . . 14 78 6.3. Form Relation Type Registry . . . . . . . . . . . . . . . 15 79 6.3.1. Registering New Form Relation Types . . . . . . . . . 15 80 6.3.2. Initial Registry Contents . . . . . . . . . . . . . . 15 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 82 7.1. Normative References . . . . . . . . . . . . . . . . . . 16 83 7.2. Informative References . . . . . . . . . . . . . . . . . 17 84 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 18 85 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 87 1. Introduction 89 Representational State Transfer (REST) [16] is an architectural style 90 for distributed hypermedia systems. Over the years, REST has gained 91 popularity not only as an approach for large-scale information 92 dissemination, but also as the basic principle for designing and 93 building Internet-based applications in general. 95 In the coming years, the size and scope of the Internet is expected 96 to greatly increase as physical-world objects become smart enough to 97 communicate over the Internet -- a phenomenon known as the Internet 98 of Things (IoT). As things learn to speak the languages of the net, 99 the idea of applying REST principles to the design of IoT application 100 architectures suggests itself. To this end, the Constrained 101 Application Protocol (CoAP) [24] was created, an application-layer 102 protocol that enables RESTful applications in constrained-node 103 networks [10], thus giving rise to a new setting for Internet-based 104 applications: the Constrained RESTful Environment (CoRE). 106 To realize the full benefits and advantages of the REST style, a set 107 of constraints needs to be maintained when designing new applications 108 and their application programming interfaces (APIs). One of the 109 fundamental principles is that "REST APIs must be hypertext-driven" 110 [17]. This principle is often ignored by application designers, who 111 instead specify their APIs out-of-band in terms of fixed URI 112 patterns, e.g., in the API documentation or in a machine-readable 113 format that facilitates code generation. Although this approach may 114 appear easy for clients to use, the fixed resource names and data 115 formats lead to a tight coupling between client and server 116 implementations and make the system less flexible. Violations of 117 REST design principles like this result in APIs that may not be as 118 scalable, extensible, and interoperable as promised by REST [20]. 120 REST is intended for long-lived network-based applications that span 121 multiple organizations [17]. Principled REST APIs require some 122 design effort, since application designers do not only have to take 123 current requirements into consideration, but also have to anticipate 124 changes that may be required in the future -- years or even decades 125 after the application has been deployed for the first time. The 126 reward is long-term stability and evolvability, both of which are 127 very desirable features in the Internet of Things. 129 To aid application designers in the design process, this document 130 proposes CoRE Application Descriptions, a convention for describing 131 the APIs of RESTful, hypermedia-driven Web applications. CoRE 132 Application Descriptions help application designers avoid common 133 mistakes by focusing almost all of the descriptive effort on defining 134 the Internet media type(s) that are used for representing resources 135 and driving application state. 137 A template provides a consistent format for the description of APIs 138 so that implementers can easily build interoperable clients and 139 servers and other application designers can reuse application 140 components in their own applications. 142 2. Application Descriptions 144 A CoRE Application Description is a named set of reusable components. 145 It describes a contract between a server hosting an instance of the 146 described application and clients that wish to interface with that 147 instance. 149 A CoRE Application Description is comprised of: 151 o URI schemes that identify communication protocols, 153 o Internet media types that identify representation formats, 155 o link relation types that identify link semantics, 157 o form relation types that identify form semantics, 159 o variable names that identify the semantics of variables in 160 templated links, 162 o form field names that identify the semantics of form fields in 163 forms, and 165 o optionally, well-known locations. 167 Together, these components provide the specific, in-band instructions 168 for interfacing with a given application. 170 2.1. URI Schemes 172 The foundation of a hypermedia-driven REST API are the communication 173 protocol(s) spoken between a client and a server. Although HTTP/1.1 174 [14] is by far the most common communication protocol for REST APIs, 175 a REST API should typically not be dependent on any specific 176 communication protocol. 178 The use of a particular protocol by a client is guided by URI schemes 179 [7]. URI schemes specify the syntax and semantics of URI references 180 [1] that the server includes in links (Section 2.2.2) and forms 181 (Section 2.2.3). 183 A URI scheme refers to a family of protocols, typically distinguished 184 by a version number. For example, the "http" URI scheme refers to 185 the two members of the HTTP family of protocols: HTTP/1.1 [14] and 186 HTTP/2 [8] (as well as some predecessors). The specific HTTP version 187 used is negotiated between a client and a server in-band using the 188 version indicator in the HTTP request-line or the TLS Application- 189 Layer Protocol Negotiation (ALPN) extension [18]. 191 IANA maintains a list of registered URI schemes at 192 . 194 2.2. Internet Media Types 196 One of the most important aspect of hypermedia-driven communications 197 is the concept of Internet media types [2]. Media types are used to 198 label representations so that it is known how the representation 199 should be interpreted and how it is encoded. The centerpiece of a 200 CoRE Application Description should be one or more media types. 202 A media type identifies a versioned series of representation formats 203 (Section 2.2.1): a media type does not identify a particular version 204 of a representation format; rather, the media type identifies the 205 family, and includes provisions for version indicator(s) embedded in 206 the representations themselves to determine more precisely the nature 207 of how the data is to be interpreted [21]. A new media type is only 208 needed to designate a completely incompatible format [21]. 210 Note: The terms media type and representation format are often used 211 interchangeably. In this document, the term "media type" refers 212 specifically to a string of characters such as "application/xml" 213 that is used to label representations; the term "representation 214 format" refers to the definition of the syntax and semantics of 215 representations, such as XML 1.0 [12] or XML 1.1 [13]. 217 Media types consist of a top-level type and a subtype, structured 218 into trees [2]. Optionally, media types can have parameters. For 219 example, the media type "text/plain; charset=utf-8" is a subtype for 220 plain text under the "text" top-level type in the standards tree and 221 has a parameter "charset" with the value "utf-8". 223 Media types can be further refined by 225 o structured type name suffixes (e.g., "+xml" appended to the base 226 subtype name; see Section 4.2.8 of RFC 6838 [2]), 228 o a "profile" parameter (see Section 3.1 of RFC 6906 [25]), 230 o subtype information embedded in the representations themselves 231 (e.g., "xmlns" declarations in XML documents [11]), 233 or a similar annotation. An annotation directly in the media type is 234 generally preferable, since subtype information embedded in 235 representations can typically not be negotiated during content 236 negotiation (e.g., using the CoAP Accept option). 238 In CoAP, media types are combined with content coding information 239 [15] to indicate the "content format" [24] of a representation. Each 240 content format is assigned a numeric identifier that can be used 241 instead of the (typically much longer) textual name of the media type 242 in representation formats with space constraints. The flat number 243 space loses the structural information that the textual names have, 244 however. 246 The media type of a representation must be determined from in-band 247 information (e.g., from the CoAP Content-Format option). Clients 248 must not assume a structure from the application context or other 249 out-of-band information. 251 IANA maintains a list of registered Internet media types at 252 . 254 IANA maintains a list of registered structured suffixes at 255 . 257 IANA maintains a list of registered CoAP content formats at 258 . 260 2.2.1. Representation Formats 262 In RESTful applications, clients and servers exchange representations 263 that capture the current or intended state of a resource and that are 264 labeled with a media type. A representation is a sequence of bytes 265 whose structure and semantics are specified by a representation 266 format: a set of rules for encoding information. 268 Representation formats should generally allow clients with different 269 goals, so they can do different things with the same data. The 270 specification of a representation format "describes a problem space, 271 not a prescribed relationship between client and server. Client and 272 server must share an understanding of the representations they're 273 passing back and forth, but they don't need to have the same idea of 274 what the problem is that needs to be solved." [22] 276 Representation formats and their specifications frequently evolve 277 over time. It is part of the responsibility of the designer of a new 278 version to insure both forward and backward compatibility: new 279 representations should work reasonably (with some fallback) with old 280 processors and old representations should work reasonably with new 281 processors [21]. 283 Representation formats enable hypermedia-driven applications when 284 they support the expression of hypermedia controls, i.e., links 285 (Section 2.2.2) and forms (Section 2.2.3). 287 2.2.2. Links 289 As described in RFC 5988 [5], a link is a typed connection between 290 two resources. Additionally, a link is the primary means for a 291 client to navigate from one resource to another. 293 A link is comprised of: 295 o a link context (usually the "current" resource), 297 o a link relation type that identifies the semantics of the link 298 (see Section 2.3), 300 o a link target, identified by a URI, and 302 o optionally, target attributes that further describe the link or 303 the link target. 305 A link can be viewed as a statement of the form "{link context} has a 306 {link relation type} resource at {link target}, which has {target 307 attributes}" [5]. For example, the resource 308 could have a "terms-of-service" resource at , 309 which has a representation with the media type "text/html". 311 There are two special kinds of links: 313 o An embedding link is a link with an additional hint: when the link 314 is processed, it should be substituted with the representation of 315 the referenced resource rather than cause the client to navigate 316 away from the current resource. Thus, traversing an embedding 317 link adds to the current state rather than replacing it. 319 The most well known example for an embedding link is the HTML 320 element. When a Web browser processes this element, it 321 automatically dereferences the "src" and renders the resulting 322 image in place of the element. 324 o A templated link is a link where the client constructs the link 325 target URI from provided in-band instructions. The specific rules 326 for such instructions are described by the representation format. 327 URI Templates [3] provide a generic way to construct URIs through 328 variable expansion. 330 Templated links allow a client to construct resource URIs without 331 being coupled to the resource structure at the server, provided 332 that the client learns the template from a representation sent by 333 the server and does not have the template hard-coded. 335 2.2.3. Forms 337 A form is the primary means for a client to submit information to a 338 server, typically in order to change resource state. 340 A form is comprised of: 342 o a form context (usually the "current" resource), 344 o a form relation type that identifies the semantics of the form 345 (see Section 2.4), 347 o a form target, identified by a URI, 349 o a submission method (PUT, POST, PATCH, FETCH, or DELETE), 351 o a description of a representation that the server expects as part 352 of the form submission, and 354 o optionally, target attributes that further describe the form or 355 the form target. 357 A form can be viewed as an instruction of the form "To {form relation 358 type} the {form context}, make a {method} request to {form target}, 359 which has {target attributes}". For example, to "update" the 360 resource , a client could be required to 361 make a PUT request to . (In many cases, 362 the target of a form is the same resource as the context, but this is 363 not required.) 365 The description of the expected representation can be a set of form 366 fields (see Section 2.4.1) or simply a list of acceptable media 367 types. 369 Note: A form with a submission method of GET is, strictly speaking, 370 a templated link, since it provides a way to construct a URI and 371 does not submit a representation to the server. 373 2.3. Link Relation Types 375 A link relation type identifies the semantics of a link [5]. For 376 example, a link with the relation type "copyright" indicates that the 377 resource identified by the target URI is a statement of the copyright 378 terms applying to the link context. 380 Relation types are not to be confused with media types; they do not 381 identify the format of the representation that results when the link 382 is dereferenced [5]. Rather, they only describe how the link context 383 is related to another resource [5]. 385 IANA maintains a list of registered link relation types at 386 . 388 Applications that don't wish to register a link relation type can use 389 an extension link relation type [5], which is a URI that uniquely 390 identifies the link relation type. For example, an application can 391 use the string "http://example.com/foo" as link relation type without 392 having to register it. Using a URI to identify an extension link 393 relation type, rather than a simple string, reduces the probability 394 of different link relation types using the same identifiers. 396 In order to minimize the overhead of link relation types in 397 representation formats with space constraints, IANA-registered link 398 relation types are assigned a numeric identifier that can be used in 399 place of the textual name (see also Section 6.2). For example, the 400 link relation type "copyright" has the number 12. A representation 401 format may additionally provide numeric identifiers for extension 402 link relation types. 404 2.3.1. Template Variable Names 406 A templated link enables clients to construct the target URI of a 407 link, for example, when the link refers to a space of resources 408 rather than a single resource. The most prominent mechanisms for 409 this are URI Templates [3] and the HTML
element with a 410 submission method of GET. 412 To enable an automated client to construct an URI reference from a 413 URI Template, the name of the variable in the template can be used to 414 identify the semantics of the variable. For example, when retrieving 415 the representation of a collection of temperature readings, a 416 variable named "threshold" could indicate the variable for setting a 417 threshold of the readings to retrieve. 419 Template variable names are scoped to link relation types, i.e., two 420 variables with the same name can have different semantics if they 421 appear in links with different link relation types. 423 2.4. Form Relation Types 425 A form relation type identifies the semantics of a form. For 426 example, a form with the form relation type "create-item" indicates 427 that a new item can be created within the form context by making a 428 request to the resource identified by the target URI. 430 IANA maintains a list of registered form relation types at 431 . 433 Similar to extension link relation types, applications can use 434 extension form relation types when they don't wish to register a form 435 relation type. 437 IANA-registered form relation types are assigned a numeric identifier 438 that can be used in place of the textual name. For example, the form 439 relation type "update" has the number 3. A representation format may 440 additionally provide numeric identifiers for extension form relation 441 types. 443 2.4.1. Form Field Names 445 Forms can have a detailed description of the representation expected 446 by the server as part of form submission. This description typically 447 consists of a set of form fields where each form field is comprised 448 of a field name, a field type, and optionally a number of attributes 449 such as a default value, a validation rule or a human-readable label. 451 To enable an automated client to fill out a form, the field name can 452 be used to identify the semantics of the form field. For example, 453 when controlling a smart light bulb, the field name "brightness" 454 could indicate the field for setting the desired brightness of the 455 light bulb. 457 Field names are scoped to form relation types, i.e., two form fields 458 with the same name can have different semantics if they appear in 459 forms with different form relation types. 461 The type of a form field is a data type such as "an integer between 1 462 and 100" or "a RGB color". The type is orthogonal to the field name, 463 i.e., the type should not be determined from the field name even 464 though the client can identify the semantics of the field from the 465 name. This separation makes it easy to change the set of acceptable 466 values in the future. 468 2.5. Well-Known Locations 470 Some applications may require the discovery of information about a 471 host, known as "site-wide metadata" in RFC 5785 [4]. For example, 472 RFC 6415 [19] defines a metadata document format for describing a 473 host; similarly, RFC 6690 [23] defines a link format for the 474 discovery of resources hosted by a server. 476 Applications that need to define a resource for this kind of metadata 477 can register new "well-known locations". RFC 5785 [4] defines the 478 path prefix "/.well-known/" in "http" and "https" URIs for this 479 purpose. RFC 7252 [24] extends this convention to "coap" and "coaps" 480 URIs. 482 IANA maintains a list of registered well-known URIs at 483 . 485 3. Application Description Template 487 As applications are implemented and deployed, it becomes important to 488 describe them in some structured way. This section provides a simple 489 template for CoRE Application Descriptions. A uniform structure 490 allows implementers to easily determine the components that make up 491 the interface of an application. 493 The template below lists all components of applications that both the 494 client and the server implementation of the application need to 495 understand in order to interoperate. Crucially, items not listed in 496 the template are not part of the contract between clients and servers 497 -- they are implementation details. This includes in particular the 498 URIs of resources (see Section 4). 500 CoRE Application Descriptions are intended to be published in human- 501 readable format by designers of applications and by operators of 502 deployed application instances. Application designers may publish an 503 application description as a general specification of all application 504 instances, so that implementers can create interoperable clients and 505 servers. Operators of application instances may publish an 506 application description as part of the API documentation of the 507 service, which should also include instructions how the service can 508 be located and which communication protocols and security modes are 509 used. 511 The fields of the template are as follows: 513 Application name: 514 Name of the application. The name is not used to negotiate 515 capabilities; it is purely informational. A name may include a 516 version number or, for example, refer to a living standard that is 517 updated continuously. 519 URI schemes: 520 URI schemes identifying the communication protocols that need to 521 be understood by clients and servers. This information is mostly 522 relevant for deploymed instances of the application rather than 523 for the general specification of the application. 525 Media types: 527 Internet media types that identify the representation formats that 528 need to be understood by clients and servers. An application 529 description must comprise at least one media type. Additional 530 media types may be required or optional. 532 Link relation types: 533 Link relation types that identify the semantics of links. An 534 application description may comprise IANA-registered link relation 535 types and extension link relation types. Both may be required or 536 optional. 538 Template variable names: 539 For each link relation type, variable names that identify the 540 semantics of variables in templated links with that link relation 541 type. Whether a template variable is required or optional is 542 indicated in-band inside the templated link. 544 Form relation types: 545 Form relation types that identify the semantics of forms and, for 546 each form relation type, the submission method(s) to be used. An 547 application description may comprise IANA-registered form relation 548 types and extension form relation types. Both may be required or 549 optional. 551 Form field names: 552 For each form relation type, form field names that identify the 553 semantics of form fields in forms with that form relation type. 554 Whether a form field is required or optional is indicated in-band 555 inside the form. 557 Well-known locations: 558 Well-known locations in the resource identifier space of servers 559 that clients can use to discover information given the DNS name or 560 IP address of a server. 562 Interoperability considerations: 563 Any issues regarding the interoperable use of the components of 564 the application should be given here. 566 Security considerations: 567 Security considerations for the security of the application must 568 be specified here. 570 Contact: 571 Person (including contact information) to contact for further 572 information. 574 Author/Change controller: 576 Person (including contact information) authorized to change this 577 application description. 579 Each field should include full citations for all specifications 580 necessary to understand the application components. 582 4. URI Design Considerations 584 URIs [1] are a cornerstone of RESTful applications. They enable 585 uniform identification of resources via URI schemes [7] and are used 586 every time a client interacts with a particular resource or when a 587 resource representation references another resource. 589 URIs often include structured application data in the path and query 590 components, such as paths in a filesystem or keys in a database. It 591 is common for many RESTful applications to use these structures not 592 only as an implementation detail but also make them part of the 593 public REST API, prescribing a fixed format for this data. However, 594 there are a number of problems with this practice [6], in particular 595 if the application designer and the server owner are not the same 596 entity. 598 In hypermedia-driven applications, URIs are therefore not included in 599 the application interface. A CoRE Application Description must not 600 mandate any particular form of URI substructure. 602 RFC 7320 [6] describes the problematic practice of fixed URI 603 structures in detail and provides some acceptable alternatives. 605 Nevertheless, the design of the URI structure on a server is an 606 essential part of implementing a RESTful application, even though it 607 is not part of the application interface. The server implementer is 608 responsible for binding the resources identified by the application 609 designer to URIs. 611 A good RESTful URI is: 613 o Short. Short URIs are easier to remember and cause less overhead 614 in requests and representations. 616 o Meaningful. A URI should describe the resource in a way that is 617 meaningful and useful to humans. 619 o Consistent. URIs should follow a consistent pattern to make it 620 easy to reason about the application. 622 o Bookmarkable. Cool URIs don't change [9]. However, in practice, 623 application resource structures do change. That should cause URIs 624 to change as well so they better reflect reality. Implementations 625 should not depend on unchanging URIs. 627 o Shareable. A URI should not be context sensitive, e.g., to the 628 currently logged-in user. It should be possible to share a URI 629 with third parties so they can access the same resource. 631 o Extension-less. Some applications return different data for 632 different extensions, e.g., for "contacts.xml" or "contacts.json". 633 But different URIs imply different resources. RESTful URIs should 634 identify a single resource. Different representations of the 635 resource can be negotiated (e.g., using the CoAP Accept option). 637 5. Security Considerations 639 The security considerations of RFC 3986 [1], RFC 5785 [4], RFC 5988 640 [5], RFC 6570 [3], RFC 6838 [2], RFC 7320 [6], and RFC 7595 [7] are 641 inherited. 643 All components of an application description are expected to contain 644 clear security considerations. CoRE Application Descriptions should 645 furthermore contain security considerations that need to be taken 646 into account for the security of the overall application. 648 6. IANA Considerations 650 [Note to RFC Editor: Please replace XXXX in this section with the RFC 651 number of this specification.] 653 6.1. Content-Format Registry 655 RFC 6838 [2] establishes a IANA registry for media types. Many of 656 these media types are also useful in constrained environments as CoAP 657 content formats. RFC 7252 [24] establishes a IANA registry for these 658 content formats. This specification tasks IANA with the allocation 659 of a content format for any existing or new media type registration 660 that does not define any parameters (required or optional). The 661 content formats shall be allocated in the range 1000-9999. 663 6.2. Link Relation Type Registry 665 RFC 5988 [5] establishes a IANA registry for link relation types. 666 This specification extends the registration template with a "Relation 667 ID": a numeric identifier that can be used instead of the "Relation 668 Name" to identify a link relation type. IANA is tasked with the 669 assignment of an ID to any existing or new link relation type. The 670 IDs shall be assigned in the range 1-9999. 672 6.3. Form Relation Type Registry 674 This specification establishes a IANA registry for form relation 675 types. 677 6.3.1. Registering New Form Relation Types 679 Form relation types are registered in the same way as link relation 680 types [5], i.e., they are registered on the advice of a Designated 681 Expert with a Specification Required. 683 The requirements for registered relation types are adopted from 684 Section 4.1 of RFC 5988 [5]. 686 The registration template is: 688 o Relation Name: 690 o Relation ID: 692 o Description: 694 o Reference: 696 o Notes: [optional] 698 The IDs shall be assigned in the range 1-9999. 700 6.3.2. Initial Registry Contents 702 The Form Relation Type registry's initial contents are: 704 o Relation Name: create-item 705 Relation ID: 1 706 Description: Refers to a resource that can be used to create a 707 resource in a collection of resources. 708 Reference: [RFCXXXX] 710 o Relation Name: delete 711 Relation ID: 2 712 Description: Refers to a resource that can be used to delete a 713 resource in a collection of resources. 714 Reference: [RFCXXXX] 716 o Relation Name: update 717 Relation ID: 3 718 Description: Refers to a resource that can be used to update the 719 state of the form context. 721 Reference: [RFCXXXX] 723 o Relation Name: search 724 Relation ID: 4 725 Description: Refers to a resource that can be used to search the 726 form context. 727 Reference: [RFCXXXX] 729 7. References 731 7.1. Normative References 733 [1] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 734 Resource Identifier (URI): Generic Syntax", STD 66, 735 RFC 3986, DOI 10.17487/RFC3986, January 2005, 736 . 738 [2] Freed, N., Klensin, J., and T. Hansen, "Media Type 739 Specifications and Registration Procedures", BCP 13, 740 RFC 6838, DOI 10.17487/RFC6838, January 2013, 741 . 743 [3] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 744 and D. Orchard, "URI Template", RFC 6570, 745 DOI 10.17487/RFC6570, March 2012, 746 . 748 [4] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 749 Uniform Resource Identifiers (URIs)", RFC 5785, 750 DOI 10.17487/RFC5785, April 2010, 751 . 753 [5] Nottingham, M., "Web Linking", RFC 5988, 754 DOI 10.17487/RFC5988, October 2010, 755 . 757 [6] Nottingham, M., "URI Design and Ownership", BCP 190, 758 RFC 7320, DOI 10.17487/RFC7320, July 2014, 759 . 761 [7] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 762 and Registration Procedures for URI Schemes", BCP 35, 763 RFC 7595, DOI 10.17487/RFC7595, June 2015, 764 . 766 7.2. Informative References 768 [8] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 769 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 770 DOI 10.17487/RFC7540, May 2015, 771 . 773 [9] Berners-Lee, T., "Cool URIs don't change", 1998, 774 . 776 [10] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 777 Constrained-Node Networks", RFC 7228, 778 DOI 10.17487/RFC7228, May 2014, 779 . 781 [11] Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 782 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 783 Wide Web Consortium Recommendation REC-xml-names-20091208, 784 December 2009, 785 . 787 [12] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 788 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 789 Edition)", World Wide Web Consortium Recommendation REC- 790 xml-20081126, November 2008, 791 . 793 [13] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., 794 Yergeau, F., and J. Cowan, "Extensible Markup Language 795 (XML) 1.1 (Second Edition)", World Wide Web Consortium 796 Recommendation REC-xml11-20060816, August 2006, 797 . 799 [14] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 800 Protocol (HTTP/1.1): Message Syntax and Routing", 801 RFC 7230, DOI 10.17487/RFC7230, June 2014, 802 . 804 [15] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 805 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 806 DOI 10.17487/RFC7231, June 2014, 807 . 809 [16] Fielding, R., "Architectural Styles and the Design of 810 Network-based Software Architectures", Ph.D. Dissertation, 811 University of California, Irvine, 2000, 812 . 815 [17] Fielding, R., "REST APIs must be hypertext-driven", 816 October 2008, . 819 [18] Friedl, S., Popov, A., Langley, A., and E. Stephan, 820 "Transport Layer Security (TLS) Application-Layer Protocol 821 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 822 July 2014, . 824 [19] Hammer-Lahav, E., Ed. and B. Cook, "Web Host Metadata", 825 RFC 6415, DOI 10.17487/RFC6415, October 2011, 826 . 828 [20] Li, L., Wei, Z., Luo, M., and W. Chou, "Requirements and 829 Design Patterns for REST Northbound API in SDN", draft-li- 830 sdnrg-design-restapi-02 (work in progress), July 2016. 832 [21] Masinter, L., "MIME and the Web", draft-masinter-mime-web- 833 info-02 (work in progress), January 2011. 835 [22] Richardson, L. and M. Amundsen, "RESTful Web APIs", 836 O'Reilly Media, ISBN 978-1-4493-5806-8, September 2013. 838 [23] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 839 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 840 . 842 [24] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 843 Application Protocol (CoAP)", RFC 7252, 844 DOI 10.17487/RFC7252, June 2014, 845 . 847 [25] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 848 DOI 10.17487/RFC6906, March 2013, 849 . 851 Acknowledgements 853 Jan Algermissen, Mike Amundsen, Mike Kelly, Julian Reschke, and Erik 854 Wilde provided valuable input on link and form relation types. 856 Thanks to Olaf Bergmann, Carsten Bormann, Stefanie Gerdes, Ari 857 Keranen, Michael Koster, Matthias Kovatsch, Teemu Savolainen, and 858 Bilhanan Silverajan for helpful comments and discussions that have 859 shaped the document. 861 Some of the text in this document has been borrowed from [5], [6], 862 [17], [20], and [21]. All errors are my own. 864 This work was funded in part by Nokia. 866 Author's Address 868 Klaus Hartke 869 Universitaet Bremen TZI 870 Postfach 330440 871 Bremen D-28359 872 Germany 874 Phone: +49-421-218-63905 875 Email: hartke@tzi.org