Network Working Group R. Sayre
Internet-Draft Boswijck Memex Consulting
Expires: September 26, 2005 March 25, 2005
The Atom Publishing Protocol (Basic)
draft-sayre-atompub-protocol-basic-00.txt
Status of this Memo
This document is an Internet-Draft and is subject to all provisions
of Section 3 of RFC 3667. 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 become aware will be disclosed, in accordance with
RFC 3668.
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 September 26, 2005.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
This memo presents a protocol for using XML (Extensible Markup
Language) and HTTP (HyperText Transport Protocol) to edit content.
The Atom Publishing Protocol is an application-level protocol for
publishing and editing Web resources belonging to periodically
updated websites. The protocol at its core is the HTTP transport of
Atom-formatted representations. The Atom format is documented in the
Sayre Expires September 26, 2005 [Page 1]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
Atom Syndication Format (draft-ietf-atompub-format-06.txt).
This memo is a variant of the original Atom Publishing Protocol, as
authored by Joe Gregorio.
Editorial Note
To provide feedback on this Internet-Draft, join the atom-protocol
mailing list (http://www.imc.org/atom-protocol/index.html) [1].
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Notational Conventions . . . . . . . . . . . . . . . . . . 3
2. The Atom Publishing Protocol Model . . . . . . . . . . . . . . 3
2.1 Collections . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Orientation . . . . . . . . . . . . . . . . . . . . . . . 3
2.3 Listing . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4 Authoring . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4.1 Create . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4.2 Read . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4.3 Update . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4.4 Delete . . . . . . . . . . . . . . . . . . . . . . . . 5
2.5 Success and Failure . . . . . . . . . . . . . . . . . . . 6
3. Functional Specification . . . . . . . . . . . . . . . . . . . 6
3.1 Interacting With Collections . . . . . . . . . . . . . . . 6
3.1.1 Request and Response . . . . . . . . . . . . . . . . . 6
3.2 Authoring Atom Entries . . . . . . . . . . . . . . . . . . 10
3.2.1 Create . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2.2 Read . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2.3 Update . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2.4 Delete . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3 Authoring Generic Resources . . . . . . . . . . . . . . . 10
3.3.1 Create . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3.2 Read . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3.3 Update . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3.4 Delete . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4 Service Description . . . . . . . . . . . . . . . . . . . 11
3.4.1 Service Description Documents . . . . . . . . . . . . 11
3.4.2 Request and Response . . . . . . . . . . . . . . . . . 13
4. Extensions to the Atom Syndication Format . . . . . . . . . . 14
5. Security Considerations . . . . . . . . . . . . . . . . . . . 14
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
7. Normative References . . . . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . . 15
Intellectual Property and Copyright Statements . . . . . . . . 16
Sayre Expires September 26, 2005 [Page 2]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
1. Introduction
The Atom Publishing Protocol is an application-level protocol for
publishing and editing Web resources using HTTP [RFC2616] and XML 1.0
[W3C.REC-xml-20040204].
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].
2. The Atom Publishing Protocol Model
The Atom Publishing Protocol operates on collections of Web
resources. All collections support the same basic methods of
interaction. The member resources of those collections share the
same interaction patterns. HTTP methods provide a pattern for
working with all such Web resources:
o GET is used to retrieve a representation of a resource or perform
a read-only query.
o POST is used to create a new, dynamically-named resource.
o PUT is used to update a known resource.
o DELETE is used to remove a resource.
2.1 Collections
The APP groups resources into "Collections", which are analogous to
the "folders" or "directories" found in many file systems.
2.2 Orientation
To discover the location of the collections exposed by an APP
service, the client must locate and request a Service Description
Document (Section 3.4).
Client Server
| |
| 1.) GET Service Description |
|------------------------------->|
| |
| 2.) Service Description Doc |
|<-------------------------------|
| |
1. The client sends a GET request to the Service Description
Resource.
Sayre Expires September 26, 2005 [Page 3]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
2. The server responds with a Service Description Document
containing the locations of collections provided by the service.
The content of this document can vary based on aspects of the
client request, including, but not limited to, authentication
credentials.
2.3 Listing
Once the client has discovered the location of a collection, it can
request a listing of the collection's membership. However,
collections might be extremely large, so servers are likely to list a
small subset of the collection by default. Clients that wish to
exercise greater control over the subset returned by the server can
include an Atom-Query (Section 3.1.1.1) header in their request.
Client Server
| |
| 1.) GET to Collection URI |
|------------------------------->|
| |
| 2.) 200 OK, Atom Feed Doc |
|<-------------------------------|
| |
1. The client sends a GET request to the Collection's URI.
2. The server responds with an Atom Feed Document containing a full
or partial listing of the collection's membership.
2.4 Authoring
After locating a collection, the client can alter its membership by
sending HTTP requests to its member resources, rather than the
collection itself, except when it desires to add an entry to the
collection. In that case, it sends a request to the collection.
2.4.1 Create
Client Server
| |
| 1.) POST to Collection URI |
|------------------------------->|
| |
| 2.) 201 Created @ Location |
|<-------------------------------|
| |
1. The client sends a representation of a member to the server via
HTTP POST. The Request URI is that of the Collection.
Sayre Expires September 26, 2005 [Page 4]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
2. The server responds with a response of "201 Created" and a
"Location" header containing the URI of the newly-created
resource.
2.4.2 Read
Client Server
| |
| 1.) GET or HEAD to Member URI |
|------------------------------->|
| |
| 2.) 200 OK |
|<-------------------------------|
| |
1. If the client does not know the current state of the resource, it
sends a GET (or HEAD) request to the member's URI.
2. The server responds with an appropriate representation.
2.4.3 Update
Client Server
| |
| 1.) PUT to Member URI |
|------------------------------->|
| |
| 2.) 200 OK |
|<-------------------------------|
1. The client PUTs an updated representation to the member's URI.
2. The server responds with a representation of the member's new
state.
2.4.4 Delete
Client Server
| |
| 1.) DELETE to Member URI |
|------------------------------->|
| |
| 2.) 204 No Content |
|<-------------------------------|
| |
1. The client sends a DELETE request to the member's URI.
2. The server responds with successful status code.
Sayre Expires September 26, 2005 [Page 5]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
2.5 Success and Failure
HTTP defines classes of response. HTTP status codes of the form 2xx
signal that a request was successful. HTTP status codes of the form
4xx or 5xx signal that an error has occurred, and the request has
failed. Consult the HTTP specification for more detailed definitions
of each status code.
3. Functional Specification
3.1 Interacting With Collections
3.1.1 Request and Response
This specification defines two methods for use with collections: GET
and POST. This section will cover GET. POST is covered in
Section 3.2 and Section 3.3.
Collections can contain extremely large numbers of resources. A
naive client such as a web spider or web browser would be overwhelmed
if the response to a GET reflected the full membership of the
collection, and the server would waste large amounts of bandwidth and
processing time on clients unable to handle the response. As a
result, responses to a simple GET request represent a
server-determined subset of the collection's membership.
This specifcation defines two serializations for Atom Collections.
Servers MUST provide both, but MAY also provide additional
serializations.
1. Atom Feed Documents (application/atom+xml)
2. Atom Feed Documents wrapped by a SOAP envelope
(application/soap+xml)
Clients use the HTTP 'Accept' request header to indicate their
preference. If no 'Accept' header is present in the request, the
server is free to choose any serialization. [[anchor11: Send an
'Accept' header, or you might get an mp3 in response.]]
Example Request
GET /collection HTTP/1.1
Host: example.org
User-Agent: GenericBot/1.0
Accept: */*
Here, the server could return any subset of the collection using any
serialization.
Sayre Expires September 26, 2005 [Page 6]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
Example Request, with Accept header
GET /collection HTTP/1.1
Host: example.org
User-Agent: Cosimo/1.0
Accept: application/atom+xml
Here, the server could return any subset of the collection as an Atom
Feed Document.
Example Response, Atom Feed Document
HTTP/1.1 200 OK
Date: Fri, 25 Mar 2005 17:15:33 GMT
Last-Modified: Mon, 04 Oct 2004 18:31:45 GMT
ETag: "2b3f6-a4-5b572640"
Accept-Ranges: bytes
Content-Length: nnnn
Content-Type: application/atom+xml; charset="utf-8"
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="..."
xmlns:pub="...">
<title>Example Feed</title>
<link href="http://example.org/login"/>
<updated>2003-12-13T18:30:02Z</updated>
<author>
<name>John Doe</name>
</author>
...
<entry>
<title>Sample</title>
<updated>2003-12-13T18:30:02Z</updated>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<link rel="alternate" href="http://example.org/sample.html"/>
<pub:edit href="http://example.org/app/sample.atom" />
<content />
</entry>
...
</feed>
Sayre Expires September 26, 2005 [Page 7]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
Example Request, with SOAP Accept header
GET /collection HTTP/1.1
Host: example.org
User-Agent: Cosimo/1.0
Accept: application/soap+xml
Here, the server could return any subset of the collection as an Atom
Feed Document wrapped by a SOAP envelope.
Example Response, Atom Feed Document wrapped by a SOAP envelope
HTTP/1.1 200 OK
Date: Fri, 25 Mar 2005 17:15:33 GMT
Last-Modified: Mon, 04 Oct 2004 18:31:45 GMT
ETag: "2b3f6-a4-5b572640-89"
Accept-Ranges: bytes
Content-Length: nnnn
Content-Type: application/soap+xml; charset="utf-8"
<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
<env:Header />
<env:Body>
<feed xmlns="..."
xmlns:pub="...">
<title>Example Feed</title>
<link href="http://example.org/login"/>
<updated>2003-12-13T18:30:02Z</updated>
<author>
<name>John Doe</name>
</author>
...
<entry>
<title>Sample</title>
<updated>2003-12-13T18:30:02Z</updated>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<link rel="alternate" href="http://example.org/sample.html"/>
<pub:edit href="http://example.org/app/sample.atom" />
<content />
</entry>
...
</feed>
</env:Body>
</env:Envelope>
Each Atom Entry in the server's response represents a member
Sayre Expires September 26, 2005 [Page 8]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
resource. The client edits member resources by sending HTTP requests
to the URI given in the 'href' attribute of the 'pub:edit' element.
[[anchor12: cover next/previous feed-level elements]]
3.1.1.1 Atom-Query
Clients may require more precise control over the server's response.
For example, the client might wish to construct a record of the
collection's complete membership.
[[anchor13: draft-ietf-atompub-protocol-03 attempts to accomplish
many of the same goals with a custom ranges-specifier. This editor
now believes that's too close to the metal, loses byte ranges,
doesn't jive well with intermediaries (because concatenating two XML
documents does not result in a well-formed XML document), and is
likely to cause interoperability problems for no good reason.]]
The Atom-Query request header field is used to specify a subset of a
collection's member resources. It provides four fields:
o 'count': the maximum number of Atom Entries to be included in the
response.
o 'offset': the offset at which to begin the sequence of entries
that match a given request.
o 'begin': Atom entries in the returned feed MUST have an
atom:updated date later in time than the 'begin' date.
o 'end': Atom entries in the returned feed MUST have an atom:updated
date equal or earlier in time than the 'end' date.
None of the fields are required. This specification does not define
its meaning when used with request methods other than GET.
Example Atom-Query Header
Atom-Query: begin=2003-12-13T18:30:02Z; end=2003-12-25T18:30:02Z;
offset=2; count=4;
If no 'end' field is present: The 'end' date is considered to be the
updated date of the collection's most recently updated member
resource.
If no 'begin' field is present: The 'begin' date is considered to be
the update date of the collection least recently updated member
resource.
If no 'offset' field is present: The 'offset' integer is considered
to be 0.
Sayre Expires September 26, 2005 [Page 9]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
If no 'count' field is present: The 'count' integer is determined by
the server.
[[anchor14: ABNF...]]
3.1.1.2 Atom-Result
The Atom-Result response header indicates the range of results
returned in a query. It MUST include 'offset','count', and 'total'
fields.
Example Atom-Result Header
Atom-Result: offset=10; count=10; total=35000;
[[anchor15: ABNF...]]
3.1.1.3 Example Query Requests and Responses
[[anchor17: Examples...]]
3.2 Authoring Atom Entries
3.2.1 Create
[[anchor19: POSTing to entry collection]]
3.2.2 Read
[[anchor21: GET to an entry's URI]]
3.2.3 Update
[[anchor23: PUT to an entry's URI]]
3.2.4 Delete
[[anchor25: DELETE to an entry's URI]]
3.3 Authoring Generic Resources
3.3.1 Create
[[anchor27: POSTing to generic collection]]
Sayre Expires September 26, 2005 [Page 10]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
POST /_do/exampleblog/generic_collection HTTP/1.1
Host: www.example.com
Content-Type: image/jpeg
Content-Length: nnn
...raw bytes of image go here...
3.3.2 Read
[[anchor29: GET to a resource's URI]]
3.3.3 Update
[[anchor31: PUT to a resource's URI]]
3.3.4 Delete
[[anchor33: DELETE to a resource's URI]]
3.4 Service Description
In order for authoring to commence, a client must first discover the
capabilities and locations of collections offered by an APP service.
3.4.1 Service Description Documents
The Service Description Document describes "workspaces", which are
server-defined groupings of collections. There is no requirement
that servers support multiple workspaces, and a collection may appear
in more than one workspace.
<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://purl.org/atom/ns#">
<workspace title="Main Site" >
<collection contents="entries" title="My Blog Entries"
href="http://example.org/reilly/feed" />
<collection contents="generic" title="Documents"
href="http://example.org/reilly/pic" />
</workspace>
<workspace title="Side Bar Blog">
<collection contents="entries" title="Entries"
href="http://example.org/reilly/feed" />
<collection contents="http://example.net/booklist" title="Books"
href="http://example.org/reilly/books" />
</workspace>
</service>
Sayre Expires September 26, 2005 [Page 11]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
3.4.1.1 Element Definitions
3.4.1.1.1 The 'app:service' Element
The "service" element is the document element of a Service Document,
acting as a container for service data associated with one or more
workspaces.
appService =
element app:service {
( appWorkspace*
& anyElement* )
}
The following child elements are defined by this specification:
o app:service elements MAY contain any number of app:workspace
elements.
3.4.1.1.2 The 'app:workspace' Element
The 'workspace' element element contains information elements about
the collections of resources available for editing.
appWorkspace =
element app:workspace {
attribute title { text },
( appCollection*
& anyElement* )
}
The following attributes and child elements are defined by this
specification:
o app:workspace elements MUST contain a 'title' attribute, which
conveys a human-readable name for the workspace
o app:workspace elements MAY contain any number of app:collection
elements.
3.4.1.1.3 The 'app:collection' Element
The 'app:collection' element describes collections and their member
resources.
Sayre Expires September 26, 2005 [Page 12]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
appCollection =
element app:collection {
attribute title { text },
attribute contents { text },
attribute href { text },
anyElement*
}
The following attributes are defined by this specification:
o app:collection elements MUST contain a 'title' attribute, whose
value conveys a human-readable name for the workspace
o app:collection elements MAY contain a 'contents' attribute
(Section 3.4.1.1.3.1). If it is not present, it's value is
considered to be 'generic'.
o app:collection elements MUST contain an 'href' attribute, whose
value conveys the URI of the collection.
3.4.1.1.3.1 The 'contents' Attribute
The 'contents' attribute conveys the nature of a collection's member
resources. This specification defines two initial values for the
'contents' attribute:
o entries
o generic
Extensibility for 'content' values is handled [[anchor37: Same as
atom:link]].
[[anchor38: Define each 'contents' value...]]
3.4.2 Request and Response
To retrieve a Service Description document, the client sends a GET
request to its URI.
GET /service-desc HTTP/1.1
Host: example.org
User-Agent: Cosimo/1.0
Accept: application/atom+xml
Accept-Encoding: gzip, *;q=0
In the example, the client has included an 'Accept' header, ensuring
the response will be of the correct media type. Otherwise, the
server might return another type of document, such as an HTML or text
file.
Sayre Expires September 26, 2005 [Page 13]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
The server responds to a GET request by returning a Service
Description document in the message body.
HTTP/1.1 200 OK
Date: Mon, 21 Mar 2005 19:20:19 GMT
Server: CountBasic/2.0
Last-Modified: Mon, 21 Mar 2005 19:17:26 GMT
ETag: "4c083-268-423f1dc6"
Accept-Ranges: bytes
Content-Length: 616
Content-Type: application/atom+xml
... Service Description bytes ...
4. Extensions to the Atom Syndication Format
[[anchor41: Document pub: elements]]
5. Security Considerations
[[anchor43: 2617, TLS, etc]]
[[anchor44: Talk here about denial of service attacks using large XML
files, or the billion laughs DTD attack.]]
6. IANA Considerations
This document has no actions for IANA.
7. Normative References
[AtomFormat]
Nottingham, M. and R. Sayre, "The Atom Syndication
Format", work-in-progress, March 2005.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396,
August 1998.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Sayre Expires September 26, 2005 [Page 14]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
Leach, P., Luotonen, A. and L. Stewart, "HTTP
Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999.
[W3C.REC-soap12-part1-20030624]
Nielsen, H., Mendelsohn, N., Gudgin, M., Hadley, M. and J.
Moreau, "SOAP Version 1.2 Part 1: Messaging Framework",
W3C REC REC-soap12-part1-20030624, June 2003.
[W3C.REC-xml-20040204]
Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T. and
E. Maler, "Extensible Markup Language (XML) 1.0 (Third
Edition)", W3C REC REC-xml-20040204, February 2004.
[1] <http://www.imc.org/atom-protocol/index.html>
Author's Address
Robert Sayre
Boswijck Memex Consulting
148 N 9th St. 4R
Brooklyn, NY 11211
US
Email: rfsayre@boswijck.com
URI: http://boswijck.com
Sayre Expires September 26, 2005 [Page 15]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
Intellectual Property Statement
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.
The IETF has been notified of intellectual property rights claimed in
regard to some or all of the specification contained in this
document. For more information consult the online list of claimed
rights.
Disclaimer of Validity
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 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.
Copyright Statement
Copyright (C) The Internet Society (2005). 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.
Sayre Expires September 26, 2005 [Page 16]
Internet-Draft The Atom Publishing Protocol (Basic) March 2005
Acknowledgment
Funding for the RFC Editor function is currently provided by the
Internet Society.
Sayre Expires September 26, 2005 [Page 17]