idnits 2.17.1 draft-wilde-accept-post-03.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 (Aug 5, 2014) is 3551 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) == 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) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 3 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: February 6, 2015 E. Wilde 6 UC Berkeley 7 Aug 5, 2014 9 The Accept-Post HTTP Header 10 draft-wilde-accept-post-03 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 February 6, 2015. 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 . . . . . . . . . . . . . . . . . . . . 6 68 6.1. Eclipse Lyo . . . . . . . . . . . . . . . . . . . . . . . 6 69 6.2. RWW.I/O . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 6.3. Tivoli Workload Automation . . . . . . . . . . . . . . . . 8 71 6.4. Jazz for Service Management . . . . . . . . . . . . . . . 8 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 73 8. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 9. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 10 75 9.1. From -03 to -04 . . . . . . . . . . . . . . . . . . . . . 10 76 9.2. From -02 to -03 . . . . . . . . . . . . . . . . . . . . . 10 77 9.3. From -01 to -02 . . . . . . . . . . . . . . . . . . . . . 10 78 9.4. From -00 to -01 . . . . . . . . . . . . . . . . . . . . . 10 79 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 80 10.1. Normative References . . . . . . . . . . . . . . . . . . . 10 81 10.2. Informative References . . . . . . . . . . . . . . . . . . 11 82 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 85 1. Introduction 87 This specification defines a new HTTP response header field Accept- 88 Post, which indicates server support for specific media types for 89 entity bodies in HTTP POST requests. This header field is comparable 90 to the Accept-Patch response header field specified together with the 91 HTTP PATCH method [RFC5789] (notice, however, that while Accept-Patch 92 is defined to only list specific media types, Accept-Post reuses the 93 "media range" concept of HTTP's Accept header and thus allows media 94 type wildcards as well). 96 2. Terminology 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 100 document are to be interpreted as described in RFC 2119 [RFC2119]. 102 3. The Accept-Post Response Header Field 104 This specification introduces a new response header field Accept-Post 105 used to specify the document formats accepted by the server in HTTP 106 POST requests. Accept-Post SHOULD appear in the OPTIONS response for 107 any resource that supports the use of the POST method. The presence 108 of the Accept-Post header in response to any method is an implicit 109 indication that POST is allowed on the resource identified by the 110 Request-URI. The presence of a specific document format in this 111 header indicates that this specific format is allowed on the resource 112 identified by the Request-URI. 114 The syntax for Accept-Post headers, using the ABNF [RFC5234] syntax 115 defined in Section 5.3.2 of HTTP/1.1 [RFC7231], is given by the 116 following definition: 117 Accept-Post = #( media-range [ accept-params ] ) 119 (Please note that this ABNF differs from the one given in Section 120 5.3.2 of RFC 7231 [RFC7231], which includes the header field name.) 122 The Accept-Post header specifies a media range as defined by HTTP 123 [RFC7231]. The media range specifies a type of representation that 124 can be POSTed to the Request-URI. 126 The app:accept element is similar to the HTTP Accept request header 127 field [RFC7231]. Media type parameters are allowed within Accept- 128 Post, but Accept-Post has no notion of preference - "accept-params" 129 or "q" arguments, as specified in Section 5.3.2 of [RFC7231], are not 130 significant. 132 4. IANA Considerations 134 This specification defines a response header field for the Hypertext 135 Transfer Protocol (HTTP) that has been registered with the Internet 136 Assigned Numbers Authority (IANA) following the "Registration 137 Procedures for Message Header Fields" [RFC3864]. 139 4.1. The Accept-Post Response Header 141 The Accept-Post response header should be added to the permanent 142 registry of message header fields (see [RFC3864]), taking into 143 account the guidelines given by HTTP/1.1 [RFC7231]. 145 Header Field Name: Accept-Post 147 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 149 Status: Standard 151 Author/Change controller: IETF 153 Specification document(s): RFC XXXX 155 5. Examples 157 Accept-Post extends the way in which interaction information can be 158 exposed in HTTP itself. The following sections contain some examples 159 how this can be used in concrete HTTP-based services. Based on the 160 first example of AtomPub Section 5.1, when sending a GET request to 161 the URI of a collection, the following response could be sent, if the 162 server decided to support Accept-Post headers: 163 HTTP/1.1 201 OK 164 Date: Fri, 23 Feb 2007 21:17:11 GMT 165 Content-Length: nnn 166 Content-Type: application/atom+xml;type=feed 167 Accept-Post: image/gif, image/jpeg, image/png 169 In this response to the GET request of a collection URI, the server 170 indicates that this particular collection accepts new entries in the 171 form of GIF, JPEG, or PNG images. No parameters are used, which 172 means that there is no server-specified preference among those media 173 types. 175 5.1. Atom Publishing Protocol 177 The Atom Publishing Protocol (AtomPub) [RFC5023] defines a model of 178 interacting with collections and members, based on representations 179 using the Atom [RFC4287] syntax. AtomPub allows clients to create 180 new collection members by using HTTP POST, with the request being 181 sent to the collection URI. AtomPub servers can limit the media 182 types they accept in these POST requests, and the accepted media 183 types are listed in an "AtomPub service document". 185 The Accept-Post header field does allow an AtomPub server to 186 advertise its support for specific media types in interactions with 187 the collection resource, without the need for a client to locate the 188 service document and interact with it. This increases the visibility 189 of the "POST to Create" model of AtomPub, and makes it easier for 190 clients to find out about the capabilities of a specific collection. 192 While the AtomPub protocol cannot be changed retroactively, this 193 additional way of exposing interaction guidance could make it easier 194 for clients to interact with AtomPub services that do support the 195 Accept-Post header field. For those that do not support Accept-Post, 196 clients would still have to rely on using the information contained 197 in the service document (including the sometimes tricky issue of how 198 to locate the service document for a given collection). 200 5.2. Linked Data Platform 202 The Linked Data Platform (LDP) [W3C.WD-ldp-20140311] describes a set 203 of best practices and simple approach for a read-write Linked Data 204 architecture, based on HTTP access to Web resources that describe 205 their state using the RDF data model. LDP defines LDP Containers 206 (LDPC) and LDP Resources (LDPR). Adding new LDPRs to an LDPC is done 207 by sending an HTTP POST request to the LDPC. An LDPC can constrain 208 the media types it is accepting for these POST requests, and should 209 expose its support for accepted media types via Accept-Post. 211 In fact, the Accept-Post header was initially developed within the 212 W3C's LDP Working Group (LDPWG), see Appendix A for acknowledgements. 213 It was then decided that the header itself might be useful in other 214 contexts as well, and thus should be specified in a standalone 215 document. 217 5.3. Additional Information in Error Responses 219 If a client POSTs an unsupported POST document, it is possible for 220 the server to use Accept-Post to indicate the supported media types. 221 These can be specified using a 415 (Unsupported Media Type) response 222 when the client sends a POST document format that the server does not 223 support for the resource identified by the Request-URI. Such a 224 response then MAY include an Accept-Post response header notify the 225 client what POST document media types are supported. 227 This example applies to all resources supporting a limited set of 228 media types for POST requests, such as the ones listed in the 229 previous to sections. In both AtomPub and LDP, it would be possible 230 for a server to include an Accept-Post header in a 415 response to a 231 failed POST request, and indicate the media types that are accepted 232 for POST requests. 234 6. Implementation Status 236 Note to RFC Editor: Please remove this section before publication. 238 This section records the status of known implementations of the 239 protocol defined by this specification at the time of posting of this 240 Internet-Draft, and is based on a proposal described in RFC 6982 241 [RFC6982]. The description of implementations in this section is 242 intended to assist the IETF in its decision processes in progressing 243 drafts to RFCs. Please note that the listing of any individual 244 implementation here does not imply endorsement by the IETF. 245 Furthermore, no effort has been spent to verify the information 246 presented here that was supplied by IETF contributors. This is not 247 intended as, and must not be construed to be, a catalog of available 248 implementations or their features. Readers are advised to note that 249 other implementations may exist. 251 According to RFC 6982, "this will allow reviewers and working groups 252 to assign due consideration to documents that have the benefit of 253 running code, which may serve as evidence of valuable experimentation 254 and feedback that have made the implemented protocols more mature. 255 It is up to the individual working groups to use this information as 256 they see fit". 258 6.1. Eclipse Lyo 260 Organization: IBM developed and contributed to the Eclipse Lyo 261 project [3]. 263 Name: Eclipse Lyo "LDP reference implementation" [4] 265 Description: A very simple reference implementation for W3C Linked 266 Data Platform (LDP) using some base Java technologies such as 267 JAX-RS 2.0 and Apache Jena. The goals of this reference 268 implementation is to experiment with validating the concepts in 269 the specification and understanding what a SDK might look like to 270 build LDP-compliant servers. Additional goal is to validate the 271 approach for usage in OSLC4J SDK for building OSLC [5] clients and 272 servers. 274 Maturity: Early prototype/alpha. 276 Coverage: All parts of the specification were covered for server 277 requirements. 279 Licensing: Freely distributable (Eclipse Public License (EPL) [6] 280 and Eclipse Distribution License (EDL) [7]). 282 Implementation Experience: Experience is only from the server 283 perspective of generating the HTTP response header. It was 284 trivial using JAX-RS 2.0 mechanism using a ContainerResponseFilter 285 on all responses. More details about this approach are described 286 in this blog post [8]. 288 Contact: Steve Speicher 290 6.2. RWW.I/O 292 Organization: No particular organization. The work done is part 293 of project RWW.I/O [9]. 295 Name: RWW.I/O - personal linked data storage. 297 Description: A minimal support for LDP is now included in RWW.I/O, 298 which is a personal linked data storage space, following the 299 structure of a Unix file system. Currently, only LDPCs are 300 supported, since the LDPRs are always files or directories that 301 are being managed through RESTful operations. RWW.I/O encourages 302 the use of .meta files to semantically describe non-LD resources 303 (e.g. images, html, js, css, etc.), and the use of .acl files for 304 access control rules using the WAC vocabulary. Both .meta and 305 .acl should be used per file (i.e. photo.jpg will have a 306 .meta.photo.jpg and a .acl.photo.jpg). 308 Maturity: Beta until more features from LDP spec are included (if 309 necessary). 311 Coverage: LDPCs on the server side, pagination and Accept-Post 312 header. You can test LDPC support like this: curl -H "Accept: 313 text/turtle" https://deiu.rww.io/public/?p=1 ; You can test 314 Accept-Post header like this: curl -v -X OPTIONS -H "Accept: text/ 315 turtle" https://deiu.rww.io/public/ 317 Licensing: MIT license. Source code is available on GitHub [10]. 319 Implementation Experience: Implementing current LDP features in 320 RWW.I/O was trivial. I've also decided to add the Accept-Post 321 header to HEAD replies, as it helps to reduce the number of 322 requests for a client trying to discover more information about 323 the server. 325 Contact: Andrei Sambra 327 6.3. Tivoli Workload Automation 329 Organization: IBM [11] 331 Name: Tivoli Workload Automation [12] 333 Description: An existing scheduling product that already 334 implements the OSLC Automation specification [13] (both client and 335 server roles), including creation factories for Automation 336 Requests that accept HTTP POST requests. Since OSLC Automation 337 offers no programmatic way for clients to know which media types 338 are supported by the server, clients are limited in practice to 339 those required by OSLC Automation (RDF/XML), or to making 340 optimistic requests using other RDF media types. 342 Maturity: Early prototype/alpha 344 Coverage: All parts of the specification were covered for server 345 and client requirements. 347 Licensing: proprietary 349 Implementation Experience: Experience from the server perspective 350 of generating the HTTP response header is that it was trivial 351 using JAX-RS annotations to add another response header. Client 352 parsing of the header presented no new problems, since the syntax 353 is almost identical to the server-side processing of an Accept 354 header. 356 Contact: John Arwe 358 6.4. Jazz for Service Management 360 Organization: IBM [11] 362 Name: Jazz for Service Management Registry Services 364 Description: An existing component bundled with multiple existing 365 Cloud and Smarter Infrastructure (formerly branded as Tivoli) 366 products. It already supports multiple resource collections that 367 use HTTP POST requests to create new member resources, e.g. 368 "registration records". Given that clients have no existing means 369 by which they can know which media types the server supports, and 370 given that Registry Services has been adding new media types over 371 the past few months as part of its continuous delivery process, 372 Accept-Post is a natural fit to enable looser client coupling. 374 Maturity: Early prototype/alpha 376 Coverage: All parts of the specification were covered for server 377 requirements. 379 Licensing: proprietary 381 Implementation Experience: Experience is only from the server 382 perspective of generating the HTTP response header. It was easy 383 to add a new header using JAX-RS annotations. 385 Contact: John Arwe 387 7. Security Considerations 389 The Accept-Post header may expose information that a server would 390 prefer to not publish. In such a case, a server can simply stop 391 exposing the header, in which case HTTP interactions would be back to 392 the level of standard HTTP (i.e., with no indication what kind of 393 media types a resource accepts in POST requests). 395 8. Open Issues 397 Note to RFC Editor: Please remove this section before publication. 399 o Accept-Post currently uses the "media range" concept of HTTP's 400 Accept header field. An alternative would be only support fully 401 specified media types, which is what the Accept-Patch header field 402 is doing. This latter solution is more constrained, and fails to 403 address some uses cases, such as AtomPub's way of exposing 404 collection support for POST requests. 406 o While "accept-post" is currently defined in the "HTTP Link Hints" 407 draft [I-D.nottingham-link-hint], it would be good to align the 408 way in which they work. Currently, the "accept-post" of link 409 hints allows a list of specific media types, whereas the Accept- 410 Post header field may contain "media ranges". 412 9. Change Log 414 Note to RFC Editor: Please remove this section before publication. 416 9.1. From -03 to -04 418 o Updating references (removing RFC 2616, adding new HTTP/1.1 RFCs). 420 9.2. From -02 to -03 422 o Adding reference to RFC 5234 (ABNF). 424 o Updating references. 426 o Adding proper registration template. 428 9.3. From -01 to -02 430 o Added header field example. 432 o Updated author address. 434 o Adding more entries to the "Implementation Status" section. 436 9.4. From -00 to -01 438 o Changed ABNF for header field from RFC 2616 to HTTPbis convention 439 (only specify the header field value grammar). 441 o Added implementations (all from the LDP community for now). 443 o Added open issue for aligning accept-post as defined by the "HTTP 444 Link Hints" draft. 446 10. References 448 10.1. Normative References 450 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 451 Requirement Levels", RFC 2119, March 1997. 453 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 454 Procedures for Message Header Fields", BCP 90, RFC 3864, 455 September 2004. 457 10.2. Informative References 459 [I-D.nottingham-link-hint] 460 Nottingham, M., "HTTP Link Hints", 461 draft-nottingham-link-hint-00 (work in progress), 462 June 2013. 464 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 465 Syndication Format", RFC 4287, December 2005. 467 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 468 Protocol", RFC 5023, October 2007. 470 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 471 Specifications: ABNF", STD 68, RFC 5234, January 2008. 473 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 474 RFC 5789, March 2010. 476 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 477 Code: The Implementation Status Section", RFC 6982, 478 July 2013. 480 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 481 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 483 [W3C.WD-ldp-20140311] 484 Speicher, S., Arwe, J., and A. Malhotra, "Linked Data 485 Platform 1.0", World Wide Web Consortium LastCall WD-ldp- 486 20140311, March 2014, 487 . 489 URIs 491 [1] 493 [2] 495 [3] 497 [4] 499 [5] 501 [6] 503 [7] 505 [8] 508 [9] 510 [10] 512 [11] 514 [12] 517 [13] 520 Appendix A. Acknowledgements 522 Thanks for comments and suggestions provided by Martin Duerst, Barry 523 Leiba, Mark Nottingham, and Julian Reschke. 525 This work has been done in the context of the W3C Linked Data 526 Platform Working Group (LDPWG) [W3C.WD-ldp-20140311]; thanks for 527 comments and suggestions provided by the working group as a whole. 529 Authors' Addresses 531 John Arwe 532 IBM 534 Email: johnarwe@us.ibm.com 536 Steve Speicher 537 IBM 539 Email: sspeiche@us.ibm.com 541 Erik Wilde 542 UC Berkeley 544 Email: dret@berkeley.edu 545 URI: http://dret.net/netdret/