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" Example Feed 2003-12-13T18:30:02Z John Doe ... Sample 2003-12-13T18:30:02Z urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a ... 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" Example Feed 2003-12-13T18:30:02Z John Doe ... Sample 2003-12-13T18:30:02Z urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a ... 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. 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] 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]