idnits 2.17.1 draft-wilde-accept-post-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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 7, 2014) is 3725 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-23 == Outdated reference: A later version (-03) exists of draft-nottingham-link-hint-00 -- Obsolete informational reference (is this intentional?): RFC 6982 (Obsoleted by RFC 7942) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Arwe 3 Internet-Draft S. Speicher 4 Intended status: Standards Track IBM 5 Expires: August 11, 2014 E. Wilde 6 UC Berkeley 7 February 7, 2014 9 The Accept-Post HTTP Header 10 draft-wilde-accept-post-02 12 Abstract 14 This specification defines a new HTTP response header field Accept- 15 Post, which indicates server support for specific media types for 16 entity bodies in HTTP POST requests. 18 Note to Readers 20 This draft should be discussed on the apps-discuss mailing list [1]. 22 Online access to all versions and files is available on github [2]. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on August 11, 2014. 41 Copyright Notice 43 Copyright (c) 2014 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. The Accept-Post Response Header Field . . . . . . . . . . . . 3 61 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 62 4.1. The Accept-Post Response Header . . . . . . . . . . . . . 4 63 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 5.1. Atom Publishing Protocol . . . . . . . . . . . . . . . . . 4 65 5.2. Linked Data Platform . . . . . . . . . . . . . . . . . . . 5 66 5.3. Additional Information in Error Responses . . . . . . . . 5 67 6. Implementation Status . . . . . . . . . . . . . . . . . . . . 5 68 6.1. Eclipse Lyo . . . . . . . . . . . . . . . . . . . . . . . 6 69 6.2. RWW.I/O . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 6.3. Tivoli Workload Automation . . . . . . . . . . . . . . . . 7 71 6.4. Jazz for Service Management . . . . . . . . . . . . . . . 8 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 73 8. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 9. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 9 75 9.1. From -01 to -02 . . . . . . . . . . . . . . . . . . . . . 9 76 9.2. From -00 to -01 . . . . . . . . . . . . . . . . . . . . . 10 77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 78 10.1. Normative References . . . . . . . . . . . . . . . . . . . 10 79 10.2. Informative References . . . . . . . . . . . . . . . . . . 10 80 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 83 1. Introduction 85 This specification defines a new HTTP response header field Accept- 86 Post, which indicates server support for specific media types for 87 entity bodies in HTTP POST requests. This header field is comparable 88 to the Accept-Patch response header field specified together with the 89 HTTP PATCH method [RFC5789] (notice, however, that while Accept-Patch 90 is defined to only list specific media types, Accept-Post reuses the 91 "media range" concept of HTTP's Accept header and thus allows media 92 type wildcards as well). 94 2. Terminology 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 98 document are to be interpreted as described in RFC 2119 [RFC2119]. 100 3. The Accept-Post Response Header Field 102 This specification introduces a new response header field Accept-Post 103 used to specify the document formats accepted by the server in HTTP 104 POST requests. Accept-Post SHOULD appear in the OPTIONS response for 105 any resource that supports the use of the POST method. The presence 106 of the Accept-Post header in response to any method is an implicit 107 indication that POST is allowed on the resource identified by the 108 Request-URI. The presence of a specific document format in this 109 header indicates that this specific format is allowed on the resource 110 identified by the Request-URI. 112 The syntax for Accept-Post headers, using the ABNF syntax defined in 113 Section 5.3.2 of the revised version of HTTP/1.1 114 [I-D.ietf-httpbis-p2-semantics], is given by the following 115 definition: 116 Accept-Post = #( media-range [ accept-params ] ) 118 (Please note that this ABNF differs from the one given in Section 119 14.1 of RFC 2616 [RFC2616], which includes the header field name.) 121 The Accept-Post header specifies a media range as defined by HTTP 122 [RFC2616]. The media range specifies a type of representation that 123 can be POSTed to the Request-URI. 125 The app:accept element is similar to the HTTP Accept request header 126 field [RFC2616]. Media type parameters are allowed within Accept- 127 Post, but Accept-Post has no notion of preference - "accept-params" 128 or "q" arguments, as specified in Section 14.1 of [RFC2616], are not 129 significant. 131 4. IANA Considerations 133 4.1. The Accept-Post Response Header 135 The Accept-Post response header should be added to the permanent 136 registry of message header fields (see [RFC3864]). Based on the 137 first example of AtomPub Section 5.1, when sending a GET request to 138 the URI of a collection, the following response could be sent, if the 139 server decided to support Accept-Post headers: 140 HTTP/1.1 201 OK 141 Date: Fri, 23 Feb 2007 21:17:11 GMT 142 Content-Length: nnn 143 Content-Type: application/atom+xml;type=feed 144 Accept-Post: image/gif, image/jpeg, image/png 146 In this response to the GET request of a collection URI, the server 147 indicates that this particular collection accepts new entries in the 148 form of GIF, JPEG, or PNG images. No parameters are used, which 149 means that there is no server-specified preference among those media 150 types. 152 5. Examples 154 Accept-Post extends the way in which interaction information can be 155 exposed in HTTP itself. The following sections contain some examples 156 how this can be used in concrete HTTP-based services. 158 5.1. Atom Publishing Protocol 160 The Atom Publishing Protocol (AtomPub) [RFC5023] defines a model of 161 interacting with collections and members, based on representations 162 using the Atom [RFC4287] syntax. AtomPub allows clients to create 163 new collection members by using HTTP POST, with the request being 164 sent to the collection URI. AtomPub servers can limit the media 165 types they accept in these POST requests, and the accepted media 166 types are listed in an "AtomPub service document". 168 The Accept-Post header field does allow an AtomPub server to 169 advertise its support for specific media types in interactions with 170 the collection resource, without the need for a client to locate the 171 service document and interact with it. This increases the visibility 172 of the "POST to Create" model of AtomPub, and makes it easier for 173 clients to find out about the capabilities of a specific collection. 175 While the AtomPub protocol cannot be changed retroactively, this 176 additional way of exposing interaction guidance could make it easier 177 for clients to interact with AtomPub services that do support the 178 Accept-Post header field. For those that do not support Accept-Post, 179 clients would still have to rely on using the information contained 180 in the service document (including the sometimes tricky issue of how 181 to locate the service document for a given collection). 183 5.2. Linked Data Platform 185 The Linked Data Platform (LDP) [W3C.WD-ldp-20130730] describes a set 186 of best practices and simple approach for a read-write Linked Data 187 architecture, based on HTTP access to Web resources that describe 188 their state using the RDF data model. LDP defines LDP Containers 189 (LDPC) and LDP Resources (LDPR). Adding new LDPRs to an LDPC is done 190 by sending an HTTP POST request to the LDPC. An LDPC can constrain 191 the media types it is accepting for these POST requests, and should 192 expose its support for accepted media types via Accept-Post. 194 In fact, the Accept-Post header was initially developed within the 195 W3C's LDP Working Group (LDPWG), see Appendix A for acknowledgements. 196 It was then decided that the header itself might be useful in other 197 contexts as well, and thus should be specified in a standalone 198 document. 200 5.3. Additional Information in Error Responses 202 If a client POSTs an unsupported POST document, it is possible for 203 the server to use Accept-Post to indicate the supported media types. 204 These can be specified using a 415 (Unsupported Media Type) response 205 when the client sends a POST document format that the server does not 206 support for the resource identified by the Request-URI. Such a 207 response then MAY include an Accept-Post response header notify the 208 client what POST document media types are supported. 210 This example applies to all resources supporting a limited set of 211 media types for POST requests, such as the ones listed in the 212 previous to sections. In both AtomPub and LDP, it would be possible 213 for a server to include an Accept-Post header in a 415 response to a 214 failed POST request, and indicate the media types that are accepted 215 for POST requests. 217 6. Implementation Status 219 Note to RFC Editor: Please remove this section before publication. 221 This section records the status of known implementations of the 222 protocol defined by this specification at the time of posting of this 223 Internet-Draft, and is based on a proposal described in RFC 6982 224 [RFC6982]. The description of implementations in this section is 225 intended to assist the IETF in its decision processes in progressing 226 drafts to RFCs. Please note that the listing of any individual 227 implementation here does not imply endorsement by the IETF. 228 Furthermore, no effort has been spent to verify the information 229 presented here that was supplied by IETF contributors. This is not 230 intended as, and must not be construed to be, a catalog of available 231 implementations or their features. Readers are advised to note that 232 other implementations may exist. 234 According to RFC 6982, "this will allow reviewers and working groups 235 to assign due consideration to documents that have the benefit of 236 running code, which may serve as evidence of valuable experimentation 237 and feedback that have made the implemented protocols more mature. 238 It is up to the individual working groups to use this information as 239 they see fit". 241 6.1. Eclipse Lyo 243 Organization: IBM developed and contributed to the Eclipse Lyo 244 project [3]. 246 Name: Eclipse Lyo "LDP reference implementation" [4] 248 Description: A very simple reference implementation for W3C Linked 249 Data Platform (LDP) using some base Java technologies such as 250 JAX-RS 2.0 and Apache Jena. The goals of this reference 251 implementation is to experiment with validating the concepts in 252 the specification and understanding what a SDK might look like to 253 build LDP-compliant servers. Additional goal is to validate the 254 approach for usage in OSLC4J SDK for building OSLC [5] clients and 255 servers. 257 Maturity: Early prototype/alpha. 259 Coverage: All parts of the specification were covered for server 260 requirements. 262 Licensing: Freely distributable (Eclipse Public License (EPL) [6] 263 and Eclipse Distribution License (EDL) [7]). 265 Implementation Experience: Experience is only from the server 266 perspective of generating the HTTP response header. It was 267 trivial using JAX-RS 2.0 mechanism using a ContainerResponseFilter 268 on all responses. More details about this approach are described 269 in this blog post [8]. 271 Contact: Steve Speicher 273 6.2. RWW.I/O 275 Organization: No particular organization. The work done is part 276 of project RWW.I/O [9]. 278 Name: RWW.I/O - personal linked data storage. 280 Description: A minimal support for LDP is now included in RWW.I/O, 281 which is a personal linked data storage space, following the 282 structure of a Unix file system. Currently, only LDPCs are 283 supported, since the LDPRs are always files or directories that 284 are being managed through RESTful operations. RWW.I/O encourages 285 the use of .meta files to semantically describe non-LD resources 286 (e.g. images, html, js, css, etc.), and the use of .acl files for 287 access control rules using the WAC vocabulary. Both .meta and 288 .acl should be used per file (i.e. photo.jpg will have a 289 .meta.photo.jpg and a .acl.photo.jpg). 291 Maturity: Beta until more features from LDP spec are included (if 292 necessary). 294 Coverage: LDPCs on the server side, pagination and Accept-Post 295 header. You can test LDPC support like this: curl -H "Accept: 296 text/turtle" https://deiu.rww.io/public/?p=1 ; You can test 297 Accept-Post header like this: curl -v -X OPTIONS -H "Accept: text/ 298 turtle" https://deiu.rww.io/public/ 300 Licensing: MIT license. Source code is available on GitHub [10]. 302 Implementation Experience: Implementing current LDP features in 303 RWW.I/O was trivial. I've also decided to add the Accept-Post 304 header to HEAD replies, as it helps to reduce the number of 305 requests for a client trying to discover more information about 306 the server. 308 Contact: Andrei Sambra 310 6.3. Tivoli Workload Automation 312 Organization: IBM [11] 314 Name: Tivoli Workload Automation [12] 316 Description: An existing scheduling product that already 317 implements the OSLC Automation specification [13] (both client and 318 server roles), including creation factories for Automation 319 Requests that accept HTTP POST requests. Since OSLC Automation 320 offers no programmatic way for clients to know which media types 321 are supported by the server, clients are limited in practice to 322 those required by OSLC Automation (RDF/XML), or to making 323 optimistic requests using other RDF media types. 325 Maturity: Early prototype/alpha 327 Coverage: All parts of the specification were covered for server 328 and client requirements. 330 Licensing: proprietary 332 Implementation Experience: Experience from the server perspective 333 of generating the HTTP response header is that it was trivial 334 using JAX-RS annotations to add another response header. Client 335 parsing of the header presented no new problems, since the syntax 336 is almost identical to the server-side processing of an Accept 337 header. 339 Contact: John Arwe 341 6.4. Jazz for Service Management 343 Organization: IBM [11] 345 Name: Jazz for Service Management Registry Services 347 Description: An existing component bundled with multiple existing 348 Cloud and Smarter Infrastructure (formerly branded as Tivoli) 349 products. It already supports multiple resource collections that 350 use HTTP POST requests to create new member resources, e.g. 351 "registration records". Given that clients have no existing means 352 by which they can know which media types the server supports, and 353 given that Registry Services has been adding new media types over 354 the past few months as part of its continuous delivery process, 355 Accept-Post is a natural fit to enable looser client coupling. 357 Maturity: Early prototype/alpha 359 Coverage: All parts of the specification were covered for server 360 requirements. 362 Licensing: proprietary 364 Implementation Experience: Experience is only from the server 365 perspective of generating the HTTP response header. It was easy 366 to add a new header using JAX-RS annotations. 368 Contact: John Arwe 370 7. Security Considerations 372 The Accept-Post header may expose information that a server would 373 prefer to not publish. In such a case, a server can simply stop 374 exposing the header, in which case HTTP interactions would be back to 375 the level of standard HTTP (i.e., with no indication what kind of 376 media types a resource accepts in POST requests). 378 8. Open Issues 380 Note to RFC Editor: Please remove this section before publication. 382 o All references to HTTP currently reference RFC 2616, except for 383 the ABNF reference of the header field value, which references the 384 latest HTTPbis draft. The final version should make sure that all 385 references are to the same version of HTTP, either RFC 2616, or 386 the updated HTTPbis version currently being finalized. 388 o Accept-Post currently uses the "media range" concept of HTTP's 389 Accept header field. An alternative would be only support fully 390 specified media types, which is what the Accept-Patch header field 391 is doing. This latter solution is more constrained, and fails to 392 address some uses cases, such as AtomPub's way of exposing 393 collection support for POST requests. 395 o While "accept-post" is currently defined in the "HTTP Link Hints" 396 draft [I-D.nottingham-link-hint], it would be good to align the 397 way in which they work. Currently, the "accept-post" of link 398 hints allows a list of specific media types, whereas the Accept- 399 Post header field may contain "media ranges". 401 9. Change Log 403 Note to RFC Editor: Please remove this section before publication. 405 9.1. From -01 to -02 407 o Added header field example. 409 o Updated author address. 411 o Adding more entries to the "Implementation Status" section. 413 9.2. From -00 to -01 415 o Changed ABNF for header field from RFC 2616 to HTTPbis convention 416 (only specify the header field value grammar). 418 o Added implementations (all from the LDP community for now). 420 o Added open issue for aligning accept-post as defined by the "HTTP 421 Link Hints" draft. 423 10. References 425 10.1. Normative References 427 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 428 Requirement Levels", RFC 2119, March 1997. 430 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 431 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 432 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 434 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 435 Procedures for Message Header Fields", BCP 90, RFC 3864, 436 September 2004. 438 10.2. Informative References 440 [I-D.ietf-httpbis-p2-semantics] 441 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 442 (HTTP/1.1): Semantics and Content", 443 draft-ietf-httpbis-p2-semantics-23 (work in progress), 444 July 2013. 446 [I-D.nottingham-link-hint] 447 Nottingham, M., "HTTP Link Hints", 448 draft-nottingham-link-hint-00 (work in progress), 449 June 2013. 451 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 452 Syndication Format", RFC 4287, December 2005. 454 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 455 Protocol", RFC 5023, October 2007. 457 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 458 RFC 5789, March 2010. 460 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 461 Code: The Implementation Status Section", RFC 6982, 462 July 2013. 464 [W3C.WD-ldp-20130730] 465 Speicher, S., Arwe, J., and A. Malhotra, "Linked Data 466 Platform 1.0", World Wide Web Consortium LastCall WD-ldp- 467 20130730, July 2013, 468 . 470 URIs 472 [1] 474 [2] 476 [3] 478 [4] 480 [5] 482 [6] 484 [7] 486 [8] 489 [9] 491 [10] 493 [11] 495 [12] 498 [13] 501 Appendix A. Acknowledgements 503 Thanks for comments and suggestions provided by Julian Reschke. 505 This work has been done in the context of the W3C Linked Data 506 Platform Working Group (LDPWG) [W3C.WD-ldp-20130730]; thanks for 507 comments and suggestions provided by the working group as a whole. 509 Authors' Addresses 511 John Arwe 512 IBM 514 Email: johnarwe@us.ibm.com 516 Steve Speicher 517 IBM 519 Email: sspeiche@us.ibm.com 521 Erik Wilde 522 UC Berkeley 524 Email: dret@berkeley.edu 525 URI: http://dret.net/netdret/