Network Working Group J. Gregorio, Ed.
Internet-Draft Google
Intended status: Standards Track June 16, 2008
Expires: December 18, 2008
AtomPub Multipart Media Creation
draft-gregorio-atompub-multipart-01
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on December 18, 2008.
Abstract
This specification defines how an Atom Publishing Protocol collection
should process multipart/related requests and also defines how a
service announces that it accepts multipart/related entities.
Editorial Note
To provide feedback on this Internet-Draft, join the Atom Protocol
mailing list (http://www.imc.org/atom-protocol/) [1].
Gregorio Expires December 18, 2008 [Page 1]
Internet-Draft AtomPub Multipart Media Creation June 2008
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3
1.2. Design Considerations . . . . . . . . . . . . . . . . . . 3
1.3. Applicability . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Multipart Representations . . . . . . . . . . . . . . . . . . 4
4. Service Document Extension . . . . . . . . . . . . . . . . . . 4
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
6. Security Considerations . . . . . . . . . . . . . . . . . . . 8
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
8. Normative References . . . . . . . . . . . . . . . . . . . . . 8
Appendix A. Revision History . . . . . . . . . . . . . . . . . . 9
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9
Intellectual Property and Copyright Statements . . . . . . . . . . 10
Gregorio Expires December 18, 2008 [Page 2]
Internet-Draft AtomPub Multipart Media Creation June 2008
1. Introduction
The Atom Publishing Protocol [RFC5023] defines Media Collections and
how to create a Media Resource by POSTing the media to the Media
Collection. RFC 5023 does not define handling multipart/related
[RFC2387] represenatations nor does it specify how the acceptance of
such representations should be advertised in the Service Document.
This specification covers both the processing and the Service
Document aspects of handling multipart/related content.
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
1.2. Design Considerations
The primary objective of multipart/related POSTs is to reduce round-
trips for creating Media Resources. There will be three round trips
in the typical Media Resource creation scenario; POST of the media,
GET of the Media Link Entry, and subsequent PUT of the updated Media
Link Entry. This specification reduces that to just a single round-
trip by allowing the client to package up the media and the
associated Media Link Entry into a single multipart/related
representation which is POSTed to the Media Collection.
The design of the handling of multipart/related representations was
aimed at backward compatibility, that is for non-multipart/related
aware clients to fully function. A second aim was to retain and
utilize the expressiveness of the current app:accept element in the
Service Document. The last aim was to ease the burden on clients by
allowing the mulitpart representation to be constructed in an order
that was convenient for the client.
1.3. Applicability
The applicability of multipart/related representations to AtomPub
Collections is restricted to just creating new entries in Media
collections. It does not specify the creation or use of a resource
that supports a GET to return the multipart/related representation
nor does it specify the creation or use of a resource that supports a
PUT of a multipart/related representation.
2. Terminology
The terms Collection, Media Resource, Media Link Entry, and Service
Gregorio Expires December 18, 2008 [Page 3]
Internet-Draft AtomPub Multipart Media Creation June 2008
Document are used as defined in [RFC5023].
3. Multipart Representations
This section covers the constraints on a multipart/related
representation sent to a Media Collection. Section 4 covers how a
client discovers that a Media Collection accepts multipart/related
representations.
A multipart/related POST to a Media Collection MUST be a valid
multipart/related representation as defined by [RFC2387] and MUST
contain two body parts. One body part MUST be an Atom Entry with a
media type of 'application/atom+xml' or 'application/
atom+xml;type=entry'. The other body part MUST be of a media type
acceptable to the collection. The order of the body parts and which
one is the 'root' object are not relavant and an AtomPub service MUST
accept otherwise valid multipart/related POST representations in
either order.
That is, if a client is creating a media resource of type image/png
it can either POST a multipart/related representation with a type
parameter of either "application/atom+xml;type=entry" or "image/png".
If the optional start parameter is provided it MAY point, via
Content-ID, to either the image/png or the application/atom+xml
object.
A successful POST of a multipart/related representation to a Media
Collection proceeds as any successful Media Resource creation. The
non-Atom object is used to create the Media Resource and the Atom
Entry object is used to create the Media Link Entry. Media Resource
creation proceeds as defined in Section 9.6 of [RFC5023] with a
successful creation returning a 201 status code and a Location:
header pointing to the newly created Media Link Entry. All other
aspects of [RFC5023] MUST be followed for Media Resource creation
including Slug: header processing.
While a multipart/related request replaces three round trips in the
typical Media Resource creation scenario, AtomPub has no mechanism to
report partial success and the handling of a multipart/related
request by the server MUST be atomic; it should either succeed with a
201 Created status code, or return an error status code.
4. Service Document Extension
An AtomPub service announces that it will accept multipart/related
POSTs by an extension to the app:accept element. The 'multipart'
Gregorio Expires December 18, 2008 [Page 4]
Internet-Draft AtomPub Multipart Media Creation June 2008
attribute is boolean valued, either "yes" or "no", and a "yes"
indicates that the collection accepts multipart/related POSTs for the
value of the app:accept element. The following example indicates a
collection that allows the creation of resources with the Ogg
Bitstream Format and will also accept them in multipart form.
<app:accept multipart="yes">application/ogg</app:accept>
The 'multipart' attribute is foreign markup and will be ignored by
clients that do not understand multipart/related uploads. In
addition it permits the full range of the app:accept element to be
used. The following indicates that the collection accepts any image
media type and will also accept them in multipart form.
<app:accept multipart="yes">image/*</app:accept>
The 'multipart' attribute can only have values of "yes" or "no". If
not present the client MUST interpret the app:accept element as if
the multipart attribute were present and had the value "no".
The 'multipart' attribute allows clients that are unaware of
multipart/related to continue to operate as normal since the
multipart attribute is foreign markup. The alternative, which was to
put a multipart/related media type in the app:accept element loses
flexibility since the 'type' parameter to the multipart/related media
type accepts only media types and not media ranges.
5. Examples
Here is an example service document that contains two media
collections. The first collection accepts multipart/related POSTs
for video media types only. The second collection accepts multipart/
related POSTs for image/jpeg and image/png media types.
Gregorio Expires December 18, 2008 [Page 5]
Internet-Draft AtomPub Multipart Media Creation June 2008
<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom">
<workspace>
<atom:title>Media Collections</atom:title>
<collection
href="http://example.org/blog/main" >
<atom:title>Mostly Media</atom:title>
<accept multipart="yes">video/*</accept>
<accept multipart="no" >text/*</accept>
<accept >audio/*</accept>
</collection>
<collection
href="http://example.org/blog/pic" >
<atom:title>Pictures Only</atom:title>
<accept multipart="yes">image/png</accept>
<accept multipart="yes">image/gif</accept>
</collection>
</workspace>
</service>
Here is an example interaction of a client creating a new Media
Resource in the Pictures Only media collection using a png image in a
multipart/related representation.
Gregorio Expires December 18, 2008 [Page 6]
Internet-Draft AtomPub Multipart Media Creation June 2008
POST /blog/pic HTTP/1.1
Host: example.org
Content-Length: nnnn
content-type: multipart/related;
boundary="===============1605871705=="
slug: The Beach
mime-version: 1.0
Media Post
--===============1605871705==
Content-Type: application/atom+xml; charset="utf-8"
MIME-Version: 1.0
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>The Beach</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2005-10-07T17:17:08Z</updated>
<author><name>Daffy</name></author>
<summary type="text">
A nice sunset picture over the water.
</summary>
<content src="cid:99334422@example.com"
type="image/gif" />
</entry>
--===============1605871705==
Content-Type: image/gif
MIME-Version: 1.0
Content-ID: <99334422@example.com>
GIF89a...binary image data...
--===============1605871705==--
If the request was successful the response might look like:
Gregorio Expires December 18, 2008 [Page 7]
Internet-Draft AtomPub Multipart Media Creation June 2008
HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/media/edit/the_beach.atom
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>The Beach</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2005-10-07T17:17:08Z</updated>
<author><name>Daffy</name></author>
<summary type="text">
A nice sunset picture over the water.
</summary>
<content type="image/png"
src="http://media.example.org/the_beach.png"/>
<link rel="edit-media"
href="http://media.example.org/edit/the_beach.png" />
<link rel="edit"
href="http://example.org/media/edit/the_beach.atom" />
</entry>
6. Security Considerations
The security considerations are the same as delineated in [RFC5023].
7. IANA Considerations
No IANA actions are required by this document.
8. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2387] Levinson, E., "The MIME Multipart/Related Content-type",
RFC 2387, August 1998.
[RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing
Protocol", RFC 5023, October 2007.
[1] <http://www.imc.org/atom-protocol/>
Gregorio Expires December 18, 2008 [Page 8]
Internet-Draft AtomPub Multipart Media Creation June 2008
Appendix A. Revision History
00 - Initial Revision.
Author's Address
Joe Gregorio (editor)
Google
Email: joe@bitworking.org
URI: http://bitworking.org/
Gregorio Expires December 18, 2008 [Page 9]
Internet-Draft AtomPub Multipart Media Creation June 2008
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Gregorio Expires December 18, 2008 [Page 10]