--- 1/draft-ietf-atompub-protocol-13.txt 2007-03-07 00:12:15.000000000 +0100 +++ 2/draft-ietf-atompub-protocol-14.txt 2007-03-07 00:12:15.000000000 +0100 @@ -1,19 +1,19 @@ Network Working Group J. Gregorio, Ed. Internet-Draft IBM Intended status: Standards Track B. de hOra, Ed. -Expires: August 9, 2007 Propylon Ltd. - February 5, 2007 +Expires: September 5, 2007 Propylon Ltd. + March 4, 2007 The Atom Publishing Protocol - draft-ietf-atompub-protocol-13.txt + draft-ietf-atompub-protocol-14.txt 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 @@ -24,31 +24,31 @@ 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 August 9, 2007. + This Internet-Draft will expire on September 5, 2007. Copyright Notice Copyright (C) The IETF Trust (2007). Abstract The Atom Publishing Protocol (APP) is an application-level protocol for publishing and editing Web resources. The protocol is based on - HTTP transport of Atom-formatted representations. The Atom format is + HTTP transfer of Atom-formatted representations. The Atom format is documented in the Atom Syndication Format [RFC4287]. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 @@ -70,86 +70,89 @@ 5.4.3. Deleting a Resource . . . . . . . . . . . . . . . . . 13 5.5. Use of HTTP Response codes . . . . . . . . . . . . . . . . 13 6. Atom Publishing Protocol Documents . . . . . . . . . . . . . . 14 6.1. Document Types . . . . . . . . . . . . . . . . . . . . . . 14 6.2. Document Extensibility . . . . . . . . . . . . . . . . . . 14 7. Category Documents . . . . . . . . . . . . . . . . . . . . . . 16 7.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 16 7.2. Element Definitions . . . . . . . . . . . . . . . . . . . 16 7.2.1. The "app:categories" element . . . . . . . . . . . . . 16 8. Service Documents . . . . . . . . . . . . . . . . . . . . . . 18 - 8.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 19 - 8.2. Element Definitions . . . . . . . . . . . . . . . . . . . 20 - 8.2.1. The "app:service" Element . . . . . . . . . . . . . . 20 - 8.2.2. The "app:workspace" Element . . . . . . . . . . . . . 20 - 8.2.3. The "app:collection" Element . . . . . . . . . . . . . 21 - 8.2.4. The "app:accept" Element . . . . . . . . . . . . . . . 21 - 8.2.5. The "app:categories" Element . . . . . . . . . . . . . 22 + 8.1. Workspaces . . . . . . . . . . . . . . . . . . . . . . . . 18 + 8.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 8.3. Element Definitions . . . . . . . . . . . . . . . . . . . 20 + 8.3.1. The "app:service" Element . . . . . . . . . . . . . . 20 + 8.3.2. The "app:workspace" Element . . . . . . . . . . . . . 20 + 8.3.3. The "app:collection" Element . . . . . . . . . . . . . 21 + 8.3.4. The "app:accept" Element . . . . . . . . . . . . . . . 21 + 8.3.5. The "app:categories" Element . . . . . . . . . . . . . 22 9. Creating and Editing Resources . . . . . . . . . . . . . . . . 24 9.1. Member URIs . . . . . . . . . . . . . . . . . . . . . . . 24 9.2. Creating resources with POST . . . . . . . . . . . . . . . 24 9.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 25 9.3. Updating Resources with PUT . . . . . . . . . . . . . . . 26 9.4. Deleting Resources with DELETE . . . . . . . . . . . . . . 26 - 9.5. Media Resources and Media Link Entries . . . . . . . . . . 26 - 9.5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 27 - 9.6. The Slug: Header . . . . . . . . . . . . . . . . . . . . . 32 - 9.6.1. Slug: Header syntax . . . . . . . . . . . . . . . . . 33 - 9.6.2. Example . . . . . . . . . . . . . . . . . . . . . . . 33 - 10. Listing Collections . . . . . . . . . . . . . . . . . . . . . 34 - 10.1. Collection Paging . . . . . . . . . . . . . . . . . . . . 34 - 10.2. The "app:edited" Element . . . . . . . . . . . . . . . . . 35 - 11. Atom Format Link Relation Extensions . . . . . . . . . . . . . 36 - 11.1. The "edit" Link Relation . . . . . . . . . . . . . . . . . 36 - 11.2. The "edit-media" Link Relation . . . . . . . . . . . . . . 36 - 12. The Atom Format Type Parameter . . . . . . . . . . . . . . . . 37 - 12.1. The 'type' parameter . . . . . . . . . . . . . . . . . . . 37 - 12.1.1. Conformance . . . . . . . . . . . . . . . . . . . . . 37 - 13. Atom Publishing Controls . . . . . . . . . . . . . . . . . . . 38 - 13.1. The "app:control" Element . . . . . . . . . . . . . . . . 38 - 13.1.1. The "app:draft" Element . . . . . . . . . . . . . . . 38 - 14. Securing the Atom Publishing Protocol . . . . . . . . . . . . 39 - 15. Security Considerations . . . . . . . . . . . . . . . . . . . 40 - 15.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 40 - 15.2. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 40 - 15.3. Spoofing Attacks . . . . . . . . . . . . . . . . . . . . . 40 - 15.4. Linked Resources . . . . . . . . . . . . . . . . . . . . . 40 - 15.5. Digital Signatures and Encryption . . . . . . . . . . . . 40 - 15.6. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 40 - 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 + 9.5. Caching and entity tags . . . . . . . . . . . . . . . . . 26 + 9.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 26 + 9.6. Media Resources and Media Link Entries . . . . . . . . . . 28 + 9.6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 29 + 9.7. The Slug: Header . . . . . . . . . . . . . . . . . . . . . 35 + 9.7.1. Slug: Header syntax . . . . . . . . . . . . . . . . . 36 + 9.7.2. Example . . . . . . . . . . . . . . . . . . . . . . . 36 + 10. Listing Collections . . . . . . . . . . . . . . . . . . . . . 37 + 10.1. Collection partial lists . . . . . . . . . . . . . . . . . 37 + 10.2. The "app:edited" Element . . . . . . . . . . . . . . . . . 38 + 11. Atom Format Link Relation Extensions . . . . . . . . . . . . . 40 + 11.1. The "edit" Link Relation . . . . . . . . . . . . . . . . . 40 + 11.2. The "edit-media" Link Relation . . . . . . . . . . . . . . 40 + 12. The Atom Format Type Parameter . . . . . . . . . . . . . . . . 41 + 12.1. The 'type' parameter . . . . . . . . . . . . . . . . . . . 41 + 12.1.1. Conformance . . . . . . . . . . . . . . . . . . . . . 41 + 13. Atom Publishing Controls . . . . . . . . . . . . . . . . . . . 42 + 13.1. The "app:control" Element . . . . . . . . . . . . . . . . 42 + 13.1.1. The "app:draft" Element . . . . . . . . . . . . . . . 42 + 14. Securing the Atom Publishing Protocol . . . . . . . . . . . . 43 + 15. Security Considerations . . . . . . . . . . . . . . . . . . . 44 + 15.1. Denial of Service . . . . . . . . . . . . . . . . . . . . 44 + 15.2. Replay Attacks . . . . . . . . . . . . . . . . . . . . . . 44 + 15.3. Spoofing Attacks . . . . . . . . . . . . . . . . . . . . . 44 + 15.4. Linked Resources . . . . . . . . . . . . . . . . . . . . . 44 + 15.5. Digital Signatures and Encryption . . . . . . . . . . . . 44 + 15.6. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 44 + 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 16.1. Content-type registration for - 'application/atomserv+xml' . . . . . . . . . . . . . . . . 41 - 16.2. Content-type registration for 'application/atomcat+xml' . 42 - 16.3. Header field registration for 'SLUG' . . . . . . . . . . . 43 - 16.4. The Link Relation registration "edit" . . . . . . . . . . 44 - 16.5. The Link Relation registration "edit-media" . . . . . . . 44 - 16.6. The Atom Format Media Type Parameter . . . . . . . . . . . 44 - 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 - 17.1. Normative References . . . . . . . . . . . . . . . . . . . 45 - 17.2. Informative References . . . . . . . . . . . . . . . . . . 46 - Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 48 - Appendix B. RELAX NG Compact Schema . . . . . . . . . . . . . . . 49 - Appendix C. Revision History . . . . . . . . . . . . . . . . . . 55 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58 - Intellectual Property and Copyright Statements . . . . . . . . . . 59 + 'application/atomserv+xml' . . . . . . . . . . . . . . . . 45 + 16.2. Content-type registration for 'application/atomcat+xml' . 46 + 16.3. Header field registration for 'SLUG' . . . . . . . . . . . 47 + 16.4. The Link Relation registration "edit" . . . . . . . . . . 48 + 16.5. The Link Relation registration "edit-media" . . . . . . . 48 + 16.6. The Atom Format Media Type Parameter . . . . . . . . . . . 48 + 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 + 17.1. Normative References . . . . . . . . . . . . . . . . . . . 49 + 17.2. Informative References . . . . . . . . . . . . . . . . . . 50 + Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 52 + Appendix B. RELAX NG Compact Schema . . . . . . . . . . . . . . . 53 + Appendix C. Revision History . . . . . . . . . . . . . . . . . . 59 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 63 + Intellectual Property and Copyright Statements . . . . . . . . . . 64 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]. The protocol supports the creation of Web resources and provides facilities for: o Collections: Sets of resources, which can be retrieved in whole or in part. - o Service: Discovering and describing Collections. + o Services: Discovery and description of Collections. o Editing: Creating, updating and deleting resources. The Atom Publishing Protocol is different from many contemporary protocols in that the server is given wide latitude in processing requests from clients. See Section 4 for more details. 2. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", @@ -181,55 +184,64 @@ 2.1.3. Use of xml:base and xml:lang XML elements defined by this specification MAY have an xml:base attribute [W3C.REC-xmlbase-20010627]. When xml:base is used, it serves the function described in Section 5.1.1 of URI Generic Syntax [RFC3986], by establishing the base URI (or IRI) for resolving relative references found within the scope of the xml:base attribute. Any element defined by this specification MAY have an xml:lang attribute, whose content indicates the natural language for the - element and its descendents. The language context is only - significant for elements and attributes declared to be "Language- - Sensitive" by this specification. Requirements regarding the content - and interpretation of xml:lang are specified in Section 2.12 of XML - 1.0 [W3C.REC-xml]. + element and its descendents. Requirements regarding the content and + interpretation of xml:lang are specified in Section 2.12 of XML 1.0 + [W3C.REC-xml]. 3. Terminology For convenience, this protocol can be referred to as the "Atom Protocol" or "APP". URI/IRI - A Uniform Resource Identifier and Internationalized Resource Identifier. These terms and the distinction between them are defined in [RFC3986] and [RFC3987]. Before an IRI found in a document is used by HTTP, the IRI is first converted to a URI (see Section 4). - The phrase "the URI of a document" in this specification is shorthand + In this specification the phrase "the URI of a document" is shorthand for "a URI which, when dereferenced, is expected to produce that document as a representation". Resource - A network-accessible data object or service identified by an IRI, as defined in [RFC2616]. See [W3C.REC-webarch-20041215] for further discussion on resources. Representation - An entity included with a request or response as defined in [RFC2616]. Collection - A resource that contains a set of Member Entries. See Section 9. Member - A resource whose IRI is listed in a Collection by a link element with a relation of "edit" or "edit-media". See Section 9.1. + The protocol defines two kinds of Members - Entry and Media + resources. - Workspace - A named group of Collections. See Section 8. + Entry Resource - Member Resources of a Collection that are + represented using the "application/atom+xml" media type. + + Media Resource -Member Resources of a Collection that are represented + with a media type other than "application/atom+xml". + + Media Link Entry - an Entry Resource that contains metadata about a + Media Resource. + + Workspace - A named group of Collections. See Section 8.1. Service Document - A document that describes the location and capabilities of one or more Collections. See Section 8. Category Document - A document that describes the categories allowed in a Collection. See Section 7. 4. Protocol Model The Atom Publishing Protocol uses HTTP methods to author Member @@ -240,96 +252,97 @@ o POST is used to create a new, dynamically-named, resource. When the client submits non-Atom-Entry representations to a Collection for creation, two resources are always created - a Media Entry for the requested resource, and a Media Link Entry for metadata (in Atom Entry format) about the resource. o PUT is used to update a known resource. o DELETE is used to remove a known resource. - This document does not specify the form of the URIs that are used. - HTTP ([RFC2616]) specifies that the URI space of each server is - controlled by that server and the Atom Protocol imposes no - constraints on that control. What this RFC does specify are the - formats of the representations that are exchanged and the actions - that can be performed on the IRIs embedded in those documents. + The Atom Protocol does not specify the form of the URIs that are + used. HTTP ([RFC2616]) specifies that the URI space of each server + is controlled by that server, and this protocol imposes no further + constraints on that control. What is specified here are the formats + of the representations that are exchanged and the actions that can be + performed on the IRIs embedded in those representations. - This document only covers the creation, update and deletion of Entry - and Media resources. Other resources can be created, updated, and - deleted as the result of manipulating a Collection, but the number of - those resources, their media-types, and effects of Atom Protocol - operations on them are outside the scope of this specification. + The Atom Protocol only covers the creation, update and deletion of + Entry and Media resources. Other resources could be created, + updated, and deleted as the result of manipulating a Collection, but + the number of those resources, their media-types, and effects of Atom + Protocol operations on them are outside the scope of this + specification. Since all aspects of client-server interaction are defined in terms of HTTP, [RFC2616] should be consulted for any areas not covered in this specification. Along with operations on Member Resources, the Atom Protocol defines Collection Resources for managing and organizing Member Resources. - Collections are represented by Atom Feed documents and contain the - IRIs of, and metadata about, their Member Resources. The Atom - Protocol does not make a structural distinction between Feeds used - for Collections and other Atom Feeds. The only mechanism that this - specification supplies for distinguishing a Collection Feed is its - appearance in a Service Document. + The representation of Collections are Atom Feed documents, and + contain the IRIs of, and metadata about the Collection's Member + Resources. The Atom Protocol does not make a structural distinction + between Feeds used for Collections and other Atom Feeds. The only + mechanism that this specification supplies for indicating a + Collection Feed is its appearance in a Service Document. Atom Protocol documents allow the use of IRIs [RFC3987], as well as URIs [RFC3986]. Before an IRI found in a document is used by HTTP, the IRI is first converted to a URI according the procedure defined in Section 3.1 of [RFC3987]. In accordance with that specification, - this conversion SHOULD be applied as late as possible. The IRI, and - the URI into which it is converted, identify the same resource. + this conversion SHOULD be applied as late as possible. Conversion + does not imply resource creation - the IRI and the URI into which it + is converted identify the same resource. - There are two kinds of Member Resources - Member Entry Resources and - Media Resources. Member Entry Resources are represented as Atom - Entries [RFC4287]. Media Resources can have representations in any - media type. A Media Link Entry is a Member Entry that contains - metadata about a Media Resource. This diagram shows the - classification of the resources: + There are two kinds of Member Resources - Entry Resources and Media + Resources. Entry Resources are represented as Atom Entries + [RFC4287]. Media Resources can have representations in any media + type. A Media Link Entry is an Entry Resource that contains metadata + about a Media Resource. This diagram shows the classification of the + resources: Member Resource - -> Member Entry Resource - -> Media Link Entry Resource + -> Entry Resource + -> Media Link Entry -> Media Resource - A Collection's Atom Entries contain the Member Entry and Media - Resources IRIs of the Collection. A Collection can contain any - number of Entries for either kind. In the diagram of a Collection - below, there are two Entries. The first contains the IRI of a Member - Entry Resource. The second contains the IRIs of both a Media - Resource and a Media Link Entry Resource, which contains the metadata - for that Media Resource: + A Collection Feed's Atom Entries contain the Entry and Media Resource + IRIs of the Collection. A Collection Feed can contain any number of + Entries for either kind, or an ordered subset of the Entries (see + Section 10.1). In the diagram of a Collection below, there are two + Entries. The first contains the IRI of an Entry Resource. The + second contains the IRIs of both a Media Resource and a Media Link + Entry Resource, which contains the metadata for that Media Resource: Collection Entry - Member Entry IRI -> Member Entry Resource - + Member Entry IRI -> Entry Resource Entry - Member Entry IRI -> Media Link Entry Resource + Member Entry IRI -> Media Link Entry Media IRI -> Media Resource Service Documents represent server-defined groups of Collections, and are used to initialize the process of creating and editing resources. 4.1. Client Implementation Considerations The Atom Protocol imposes few restrictions on the actions of servers. Unless a constraint is specified here, servers can be expected to vary in behavior, in particular around the manipulation of Atom Entries sent by clients. For example, although this specification only defines the expected behavior of Collections with respect to GET and POST, this does not imply that PUT, DELETE, PROPPATCH and others are forbidden on Collection resources - only that this specification - does not define what the servers response would be to those methods. + does not define what the server's response would be to those methods. Similarly while some HTTP status codes are mentioned explicitly, - clients should be prepared to handle any status code from a server. + clients ought to be prepared to handle any status code from a server. Servers can choose to accept, reject, delay, moderate, censor, reformat, translate, relocate or recategorize the content submitted to them. Only some of these choices are immediately relayed back to the client in responses to client requests; other choices may only become apparent later, in the feed or published entries. The same series of requests to two different publishing sites can result in a different series of HTTP responses, different resulting feeds or different entry contents. As a result, client software has to be written flexibly to accept @@ -358,23 +371,22 @@ group of Collections and the capabilities of those Collections supported by the server. The content of this document can vary based on aspects of the client request, including, but not limited to, authentication credentials. 5.2. Listing Collection Members To list the members of a Collection, the client sends a GET request to the URI of a Collection. An Atom Feed Document is returned whose Entries contain the IRIs of Member Resources. The returned Feed may - describe all, or only a subset, of the Members in a Collection (see - Section 10). Section 11 describes extensions to the Atom Syndication - Format used in the Atom Protocol. + describe all, or only a partial list of the Members in a Collection + (see Section 10). Client Server | | | 1.) GET to Collection URI | |------------------------------->| | | | 2.) Atom Feed Doc | |<-------------------------------| | | @@ -393,29 +405,31 @@ | 2.) 201 Created | | Location: Member Entry URI | |<------------------------------------------| | | 1. The client POSTs a representation of the Member to the URI of the Collection. 2. If the Member Resource was created successfully, the server responds with a status code of 201 and a Location: header that - contains the IRI of the newly created Member Entry Resource. - Media Resources could have also been created and their IRIs can - be found through the Member Entry Resource. See Section 9.5 for - more details. + contains the IRI of the newly created Entry Resource. Media + Resources could have also been created and their IRIs can be + found through the Entry Resource. See Section 9.6 for more + details. 5.4. Editing a Resource Once a resource has been created and its Member URI is known, that URI can be used to retrieve, update, and delete the resource. + Section 11 describes extensions to the Atom Syndication Format used + in the Atom Protocol for editing purposes. 5.4.1. Retrieving a Resource Client Server | | | 1.) GET to Member URI | |------------------------------------------>| | | | 2.) Member Representation | |<------------------------------------------| @@ -442,101 +456,99 @@ 2. If the update is successful the server responds with a status code of 200. 5.4.3. Deleting a Resource Client Server | | | 1.) DELETE to Member URI | |------------------------------------------>| | | - | 2.) 200 Ok | + | 2.) 200 OK | |<------------------------------------------| | | 1. The client sends a DELETE request to the URI of a Member Resource. 2. If the deletion is successful the server responds with a status code of 200. - A different approach is taken for deleting Media Resources, see - Section 9.5 for details. + A different approach is taken for deleting Media Resources; see + Section 9.6 for details. 5.5. Use of HTTP Response codes The Atom Protocol uses the response status codes defined in HTTP to indicate the success or failure of an operation. Consult the HTTP specification [RFC2616] for detailed definitions of each status code. Implementers are asked to note that according to the HTTP specification, HTTP 4xx and 5xx response entities SHOULD include a human-readable explanation of the error. 6. Atom Publishing Protocol Documents 6.1. Document Types - This specification describes two kinds of Documents - Category + This specification defines two kinds of Documents - Category Documents and Service Documents. A Category Document (Section 7) contains lists of categories specified using the "atom:category" element from the Atom Syndication - Format. A Service Document (Section 8) describes Workspaces, which - are server-defined groups of Collections. This specification assigns - no meaning to Workspaces; that is, a Workspace does not imply any - specific processing assumptions. Operations on Workspaces - themselves, such as creation or deletion, are not defined by this - specification. + Format. + + A Service Document (Section 8) groups available Collections into + Workspaces. The namespace name [W3C.REC-xml-names] for either kind of document is: http://purl.org/atom/app# [[anchor8: The namespace name needs to be updated with the final URI upon publication]] This specification uses the prefix "app:" for the namespace name. The prefix "atom:" is used for "http://www.w3.org/2005/Atom", the - namespace name of the Atom Syndication Format [RFC4287]. The + namespace name of the Atom Syndication Format [RFC4287]. These namespace prefixes are not semantically significant. Atom Publishing Protocol Documents MUST be well-formed XML. This specification does not define any DTDs for Atom Protocol formats, and hence does not require them to be "valid" in the sense used by XML. 6.2. Document Extensibility Unrecognized markup in an Atom Publishing Protocol document is - considered "foreign markup" as defined in [RFC4287]. Such foreign - markup can be used anywhere within a Category or Service Document - unless it is explicitly forbidden. Processors that encounter foreign - markup MUST NOT stop processing and MUST NOT signal an error. - Clients SHOULD preserve foreign markup when transmitting such - documents. + considered "foreign markup" as defined in Section 6 of [RFC4287]. + Such foreign markup can be used anywhere within a Category or Service + Document unless it is explicitly forbidden. Processors that + encounter foreign markup MUST NOT stop processing and MUST NOT signal + an error. Clients SHOULD preserve foreign markup when transmitting + such documents. The namespace name "http://purl.org/atom/app#" is reserved for forward compatible revisions of the Category and Service Document types - this does not exclude the addition of elements and attributes that might not be recognized by processors conformant to this specification. Such unrecognized markup from the "http://purl.org/atom/app#" namespace MUST be treated as foreign markup. [[anchor9: The namespace name needs to be updated with the final URI upon publication]] 7. Category Documents Category Documents contain lists of categories described using the "atom:category" element from the Atom Syndication Format [RFC4287]. Categories can also appear in Service Documents, where they describe - the categories allowed in a Collection (see Section 8.2.5). + the categories allowed in a Collection (see Section 8.3.5). Category Documents are identified with the "application/atomcat+xml" media type (see Section 16). 7.1. Example Main Site My Blog Entries - This Service Document describes two Workspaces. The first Workspace - is called "Main Site", has two Collections called "My Blog Entries" - and "Pictures" whose IRIs are "http://example.org/reilly/main" and - "http://example.org/reilly/pic" respectively. The "Pictures" - Workspace includes an "accept" element indicating that a client can - post image files to the Collection to create new Media Resources. - Entries with associated Media Resources are discussed in Section 9.5. + The Service Document above describes two Workspaces. The first + Workspace is called "Main Site", and has two Collections called "My + Blog Entries" and "Pictures", whose IRIs are + "http://example.org/reilly/main" and "http://example.org/reilly/pic" + respectively. The "Pictures" Workspace includes an "accept" element + indicating that a client can post image files to the Collection to + create new Media Resources (entries with associated Media Resources + are discussed in Section 9.6). The second Workspace is called "Side Bar Blog" and has a single Collection called "Remaindered Links" whose IRI is "http://example.org/reilly/list". Within each of the two Entry collections, the categories element provides a list of available categories for Member Entries. In the "My Blog Entries" Collection, the list of available categories is - obtainable through the "href" attribute. The "Side Bar Blog" + available through the "href" attribute. The "Side Bar Blog" Collection provides a category list within the Service Document, but states the list is fixed, signaling a request from the server that Entries be POSTed using only those two categories. -8.2. Element Definitions +8.3. Element Definitions -8.2.1. The "app:service" Element +8.3.1. The "app:service" Element The root of a Service Document is the "app:service" element. The "app:service" element is the container for service information associated with one or more Workspaces. An app:service element MUST contain one or more app:workspace elements. namespace app = "http://purl.org/atom/app#" start = appService appService = element app:service { appCommonAttributes, ( appWorkspace+ & extensionElement* ) } -8.2.2. The "app:workspace" Element +8.3.2. The "app:workspace" Element - The "app:workspace" element contains information elements about the - Collections of resources available for editing. The app:workspace - element contains zero or more app:collection elements. + Workspaces are server-defined groups of Collections. The "app: + workspace" element contains zero or more app:collection elements + describing the Collections of resources available for editing. appWorkspace = element app:workspace { appCommonAttributes, ( atomTitle & appCollection* & extensionSansTitleElement* ) } atomTitle = element atom:title { atomTextConstruct } -8.2.2.1. The "atom:title" Element +8.3.2.1. The "atom:title" Element The app:workspace element MUST contain one "atom:title" element (as defined in [RFC4287]), giving a human-readable title for the Workspace. -8.2.3. The "app:collection" Element +8.3.3. The "app:collection" Element The "app:collection" element describes a Collection. The app: collection element MAY contain one app:accept element and MAY contain any number of app:categories elements. The app:collection element MUST NOT contain more than one app:accept element. appCollection = element app:collection { appCommonAttributes, attribute href { atomURI }, ( atomTitle & appAccept? & appCategories* & extensionSansTitleElement* ) } -8.2.3.1. Usage in Atom Feed Documents +8.3.3.1. Usage in Atom Feed Documents The app:collection element MAY appear as a child of an atom:feed or - atom:source element in an Atom Feed Document. Its value identifies a - Collection by which new Entries can be added to appear in the feed. + atom:source element in an Atom Feed Document. Its content identifies + a Collection by which new Entries can be added to appear in the feed. The app:collection element is considered foreign markup as defined in Section 6 of [RFC4287]. -8.2.3.2. The "href" Attribute +8.3.3.2. The "href" Attribute The app:collection element MUST contain an "href" attribute, whose value gives the IRI of the Collection. -8.2.3.3. The "atom:title" Element +8.3.3.3. The "atom:title" Element The app:collection Element MUST contain one "atom:title" element (as defined in [RFC4287]), giving a human-readable title for the Collection. -8.2.4. The "app:accept" Element +8.3.4. The "app:accept" Element The "app:accept" element value specifies a comma-separated list of - media-ranges (see [RFC2616]) identifying the types of representations - that can be POSTed to the URI of a Collection. Whitespace around and - between media-range values is considered insignificant and MUST be - ignored. + media-ranges (see [RFC2616]). The list identifies the types of + representations that can be POSTed to the URI of a Collection. + + Whitespace around and between media-range values is insignificant and + MUST be ignored. The app:accept element is similar to the HTTP Accept request-header [RFC2616] with the exception that app:accept has no notion of preference. As a result, the value syntax of app:accept does not use "accept-params" or "q" arguments as specified in [RFC2616], section 14.1. - The order of media-ranges is not significant. The following lists - are all equivalent: + The order of media-ranges is not significant. For example, the + following lists are all equivalent: image/png,image/* image/*, image/png image/* - A value of "entry" may appear in any list of media-ranges in an - accept element and indicates that Atom Entry Documents can be POSTed - to the Collection. If the accept element exists but is empty, - clients SHOULD assume that the Collection does not support the - creation of new Entries. If the accept element is not present, - clients SHOULD treat this as equivalent to entry. + A value of "entry" MAY appear in any list of media-ranges and + indicates that Atom Entry Documents can be POSTed to the Collection. + The value is equivalent to the media type and format parameter + "application/atom+xml;type=entry", as defined in Section 12. If the + accept element exists but is empty, clients SHOULD assume that the + Collection does not support the creation of new Entries. If the + accept element is not present, clients SHOULD treat this as + equivalent to entry. appAccept = element app:accept { appCommonAttributes, ( appTypeValue? ) } appTypeValue = ( "entry" | media-type |entry-or-media-type ) media-type = xsd:string { pattern = "entry,(.+/.+,?)*" } entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" } -8.2.5. The "app:categories" Element - - The "app:categories" element provides a listing of the categories - that can be applied to the members of a Collection. The absence of - an "app:categories" element means that the category handling of a - server is unspecified. - - atomCategory = - element atom:category { - atomCommonAttributes, - attribute term { text }, - attribute scheme { atomURI }?, - attribute label { text }?, - undefinedContent - } - - appInlineCategories = - element app:categories { - attribute fixed { "yes" | "no" }?, - attribute scheme { atomURI }?, - (atomCategory*) - } - - appOutOfLineCategories = - element app:categories { - attribute href { atomURI }, - undefinedContent - } +8.3.5. The "app:categories" Element - appCategories = appInlineCategories | appOutOfLineCategories + The "app:categories" element provides a list of the categories that + can be applied to the members of a Collection. See Section 7.2.1 for + the detailed definition of app:categories. - The app:categories element MAY contain a "fixed" attribute, with a - value of either "yes" or "no", indicating whether or not the listing - of categories is considered to be a fixed, or closed set. The - absence of the "fixed" attribute is equivalent to the presence of a - "fixed" attribute with a value of "no". Collections that indicate a - fixed set MAY reject members that include categories not specified in - the provided listing. Collections that indicate an open set SHOULD - NOT reject otherwise acceptable members whose categories are not - present in the provided list. + The server MAY reject attempts to create or update members whose + categories are not listed in the Collection Document. Collections + that indicate the category set is open SHOULD NOT reject otherwise + acceptable members whose categories are not listed by the Collection. - The app:categories element MAY contain an "href" attribute, whose - value MUST be an IRI reference identifying a Category Document. If - the "href" attribute is provided, the app:categories element MUST be - empty and the "fixed" and "scheme" attributes MUST NOT be present. + The absence of an "app:categories" element means that the category + handling of the Collection is unspecified. 9. Creating and Editing Resources 9.1. Member URIs - The Member URI supports retrieving, updating and deleting the - resource using HTTP GET, PUT and DELETE. Retrieval and updating of - Member Entry Resources are done by exchanging Atom Entry + The Member URI allows clients to retrieve, update and delete a Member + Resource using HTTP's GET, PUT and DELETE methods. As their name + indicates, Entry Resources have Atom Entry documents as representations. - Member Entry URIs appear in two places. First, they are returned in - a Location header after successful resource creation using POST, as - described below. Second, they appear in the Entries of a Collection - document as atom:link elements with a link relation of "edit". + Member URIs appear in two places. They are returned in a Location + header after successful resource creation using POST, as described in + Section 9.2 below. They can also appear in a Collection feed's + entries, as atom:link elements with a link relation of "edit". - Each Member Entry SHOULD contain such an atom:link element providing - its Member Entry URI. + A Member Entry SHOULD contain such an atom:link element with a link + relation of "edit", which indicates the Member URI. 9.2. Creating resources with POST To add members to a Collection, clients send POST requests to the URI - of a Collection. Successful member creation is normally indicated - with a 201 ("Created") response code. Collections MAY generate a - response with a status code of 415 ("Unsupported Media Type") to - indicate that the media-type of the POSTed entity is not allowed or - supported by the Collection. - - When a Member Resource is created in the Collection which received - the POST, its Member Entry URI MUST be returned in an HTTP Location - header. - - When the server generates a response with a status code of 201 - ("Created"), it SHOULD also return a response body, which if - provided, MUST be an Atom Entry Document representing the newly- - created resource. + of the Collection. + Successful member creation is indicated with a 201 ("Created") + response code. When the Collection responds with a status code of + 201 ("Created"), it SHOULD also return a response body, which MUST be + an Atom Entry Document representing the newly-created resource. Since the server is free to alter the POSTed Entry, for example by - changing the content of the "id" element, returning the Entry as - described in the previous paragraph can be useful to the client, - enabling it to correlate the client and server views of the new - Entry. + changing the content of the "atom:id" element, returning the Entry + can be useful to the client, enabling it to correlate the client and + server views of the new Entry. - If the POST request contained an Atom Entry Document, and the + When a Member Resource is created, its Member Entry URI MUST be + returned in a Location header in the Collections's response. + + If the creation request contained an Atom Entry Document, and the subsequent response from the server contains a Content-Location header that matches the Location header character-for-character, then the client is authorized to interpret the response entity as being the representation of the newly created Entry. Without a matching Content-Location header the client MUST NOT assume the returned entity is a complete representation of the created resource. The request body sent with the POST need not be an Atom Entry. For - example, it might be a picture, or a movie. For a discussion of the - issues in POSTing such content, see Section 9.5. + example, it might be a picture, or a movie. Collections MAY return a + response with a status code of 415 ("Unsupported Media Type") to + indicate that the media-type of the POSTed entity is not allowed or + supported by the Collection. For a discussion of the issues in + creating such content, see Section 9.6. 9.2.1. Example Below, the client sends a POST request containing an Atom Entry representation to the URI of the Collection: POST /myblog/entries HTTP/1.1 Host: example.org User-Agent: Thingio/1.0 Authorization: Basic ZGFmZnk6c2VjZXJldA== @@ -913,84 +898,190 @@ Atom-Powered Robots Run Amok urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 2003-12-13T18:30:02Z John Doe Some text. The server signals a successful creation with a status code of 201. The response includes a Location: header indicating the Member Entry - URI of the Atom Entry and a representation of that Entry in the body + URI of the Atom Entry, and a representation of that Entry in the body of the response. HTTP/1.1 201 Created Date: Fri, 7 Oct 2005 17:17:11 GMT Content-Length: nnn Content-Type: application/atom+xml; charset="utf-8" Location: http://example.org/edit/first-post.atom Atom-Powered Robots Run Amok urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 2003-12-13T18:30:02Z John Doe Some text. - The created Entry returned by the server might not match the Entry - POSTed by the client. A server MAY change the values of various - elements in the Entry such as the atom:id, atom:updated and atom: - author values and MAY choose to remove or add other elements and - attributes, or change element and attribute values. + + The Entry created and returned by the Collection might not match the + Entry POSTed by the client. A server MAY change the values of + various elements in the Entry, such as the atom:id, atom:updated and + atom:author values, and MAY choose to remove or add other elements + and attributes, or change element content and attribute values. 9.3. Updating Resources with PUT - To update a resource, clients send PUT requests to its Member URI, as - specified in [RFC2616]. + To update a Member Resource, clients send PUT requests to its Member + URI, as specified in [RFC2616]. To avoid unintentional loss of data when editing Member Entries or Media Link Entries, Atom Protocol clients SHOULD preserve all metadata that has not been intentionally modified, including unknown foreign markup as defined in Section 6 of [RFC4287]. 9.4. Deleting Resources with DELETE - To delete a resource, clients send DELETE requests to its Member URI, - as specified in [RFC2616]. For Media Resources, deletion of a Media - Link Entry SHOULD result in the deletion of the associated Media - Resource. + To delete a Member Resource, clients send DELETE requests to its + Member URI, as specified in [RFC2616]. For a Media Resource, the + deletion of its Media Link Entry SHOULD result in the deletion of the + Media Resource. -9.5. Media Resources and Media Link Entries +9.5. Caching and entity tags + + Implementers are advised to pay attention to cache controls, and to + make use of the mechanisms available in HTTP to make editing resource + easier, in particular entity-tags as outlined in + [W3C.NOTE-detect-lost-update-19990510]. Clients are not assured to + receive the most recent representations of Collection Members using + GET if the server is authorizing intermediaries to cache them. + +9.5.1. Example + + Below, the client creates a Member Entry using POST: + + POST /myblog/entries HTTP/1.1 + Host: example.org + Authorization: Basic ZGFmZnk6c2VjZXJldA== + Content-Type: application/atom+xml;type=entry + Content-Length: nnn + Slug: First Post + + + + Atom-Powered Robots Run Amok + urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a + 2007-02-123T17:09:02Z + Captain Lansing + It's something moving... solid metal + + The server signals a successful creation with a status code of 201, + and returns an ETag header in the response. Because in this case the + server returned a Content-Location and Location header with the same + value, the returned Entry representation can be understood to be + complete (see Section 9.2) and thus the ETag entity value can be also + be used. + + HTTP/1.1 201 Created + Date: Fri, 23 Feb 2007 21:17:11 GMT + Content-Length: nnn + Content-Type: application/atom+xml;type=entry + Location: http://example.org/edit/first-post.atom + Content-Location: http://example.org/edit/first-post.atom + ETag: "e180ee84f0671b1" + + + + Atom-Powered Robots Run Amok + urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a + 2007-02-123T17:09:02Z + Captain Lansing + It's something moving... solid metal + + + The client can if it wishes use the returned ETag value to later + construct a "Conditional GET" as defined in [RFC2616]. In this case, + prior to editing the client sends the ETag value for the Member using + the If-None-Match: header. + GET /edit/first-post.atom HTTP/1.1 + Host: example.org + Authorization: Basic ZGFmZnk6c2VjZXJldA== + If-None-Match: "e180ee84f0671b1" + + If the Entry has not been modified, the server (or an intermediary + cache) can return a status code of 304 (Not Modified). This allows + the client to determine it still has the most recent representation + of the Entry at the time of editing. + + HTTP/1.1 304 Not Modified + Date: Sat, 24 Feb 2007 13:17:11 GMT + ETag: "e180ee84f0671b1" + + After editing, the client can PUT the updated Entry and send the ETag + entity value in an If-Match header, informing the server to accept + the entry on the condition the entity value sent still matches the + server's. + + PUT /edit/first-post.atom HTTP/1.1 + Host: example.org + Authorization: Basic ZGFmZnk6c2VjZXJldA== + Content-Type: application/atom+xml;type=entry + Content-Length: nnn + If-Match: "e180ee84f0671b1" + + + + Atom-Powered Robots Run Amok + urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a + 2007-02-24T16:34:06Z + Captain Lansing + Update: it's a hoax! + + + The server however has since received a more recent update than the + client's, and responds with a status code of 412 (Precondition + Failed). + + HTTP/1.1 412 Precondition Failed + Date: Sat, 24 Feb 2007 16:34:11 GMT + ETag: "r34rrt84f0671b22" + + This informs the client that the server has a more recent version of + the Entry and will not allow the update. + +9.6. Media Resources and Media Link Entries A client can POST a media type other than application/atom+xml to a Collection. Such a request always creates two new resources - one that corresponds to the entity sent in the request, called the Media Resource, and an associated Member Entry, called the Media Link - Entry. Media Link Entries are represented as Atom Entries. The - server can signal the media types it will accept via the "accept" - element in the Service Document (Section 8.2.4). + Entry. Media Link Entries are represented as Atom Entries and appear + in the Collection. - The Media Link Entry contains the IRI of, and metadata about, the - (perhaps non-textual) Media Resource. The Media Link Entry makes the + The Media Link Entry contains the metadata and IRI of the (perhaps + non-textual) Media Resource. The Media Link Entry thus makes the metadata about the Media Resource separately available for retrieval and update. + The server can signal the media types it will accept using the + "accept" element in the Service Document as specified in + Section 8.3.4. + Successful responses to creation requests MUST include the URI of the Media Link Entry in the Location header. The Media Link Entry SHOULD contain an atom:link element with a link relation of "edit-media" that contains the Media Resource IRI. The Media Link Entry MUST have an "atom:content" element with a "src" attribute. The value of the - "src" attribute is an IRI of the newly created Media Resource. It is - OPTIONAL that the IRI of the "src" attribute on the atom:content + "src" attribute is an IRI for the newly created Media Resource. It + is OPTIONAL that the IRI of the "src" attribute on the atom:content element be the same as the Media Resource IRI. For example, the "src" attribute value might instead be a link into a static cache or content distribution network and not the Media Resource IRI. Implementers are asked to note that according to the requirements of [RFC4287], Entries, and thus Media Link Entries, MUST contain an atom:summary element. Upon successful creation of a Media Link Entry, a server MAY choose to populate the atom:summary element (as well as any other required elements such as atom:id, atom:author and atom:title) with content derived from the POSTed entity or from any @@ -1003,40 +1094,40 @@ media type. It does not specify any request semantics or server behavior in the case where the POSTed media-type is "application/ atom+xml" but the body is something other than an Atom Entry. In particular, what happens on POSTing an Atom Feed Document to a Collection using the "application/atom+xml" media type is undefined. The Atom Protocol does not specify a means to create multiple representations of the same resource (for example a PNG and a JPG of the same image) on creation or update. -9.5.1. Examples +9.6.1. Examples Below, the client sends a POST request containing a PNG image to the URI of a Collection that accepts PNG images: POST /media/ HTTP/1.1 Host: example.org Content-Type: image/png Slug: The Beach Authorization: Basic ZGFmZnk6c2VjZXJldA== Content-Length: nnn ...binary data... The server signals a successful creation with a status code of 201. The response includes a Location header indicating the Member URI of the Media Link Entry and a representation of that entry in the body of the response. The Media Link Entry includes a content element - with a src attribute. It also contains a link using the link - relation "edit-media" specifying the IRI to be used for modifying the + with a src attribute. It also contains a link with a link relation + of "edit-media", specifying the IRI to be used for modifying the Media Resource. HTTP/1.1 201 Created Date: Fri, 7 Oct 2005 17:17:11 GMT Content-Length: nnn Content-Type: application/atom+xml; charset="utf-8" Location: http://example.org/media/edit/the_beach.atom @@ -1225,159 +1316,162 @@ href="http://example.org/blog/edit/a-day-at-the-beach.atom"/> Note that the returned Entry contains a link with a relation of "alternate" that points to the associated XHTML page that was created. This is not required by this specification, but is included to show the kinds of changes a server may make to an Entry. -9.6. The Slug: Header +9.7. The Slug: Header - Slug is a HTTP entity-header whose value is a short name that, when - accompanying a POST to a Collection, constitutes a request by the - client that its value be used as part of the URI for the to-be- - created Member Resource. + Slug is a HTTP entity-header that when accompanying a POST to a + Collection, constitutes a request by the client that its value be + used as part of the URI for the to-be-created Member Resource. - When POSTing an entity to a Collection to add a new Member, the - server MAY use this information when creating the Member URI of the - newly-created resource, for instance by using some or all of the - words in the last URI segment. It MAY also use it when creating the - atom:id or as the title of a Media Link Entry (see Section 9.5.). + Servers MAY use the value of the Slug header when creating the Member + URI of the newly-created resource, for instance by using some or all + of the words in the value for the last URI segment. Servers MAY also + use the value when creating the atom:id or as the title of a Media + Link Entry (see Section 9.6.). - Servers MAY ignore the Slug entity-header and MAY alter its value - before using it. For example, the server MAY filter out some - characters or replace accented letters with non-accented ones, spaces - with underscores, etc. + Servers MAY choose to ignore the Slug entity-header and MAY alter the + value before using it. For instance, a server might filter out some + characters or replace accented letters with non-accented ones, + replace spaces with underscores, change case, and so on. -9.6.1. Slug: Header syntax +9.7.1. Slug: Header syntax The syntax of this header MUST conform to the augmented BNF grammar in section 2.1 of the HTTP/1.1 specification [RFC2616]. The TEXT rule is described in section 2.2 of the same document. Slug = "Slug" ":" *TEXT Clients MAY send non-ASCII characters in the Slug entity-header, which they MUST encode using "encoded-words", as defined in [RFC2047]. Servers SHOULD treat the slug as [RFC2047] encoded if it matches the "encoded-words" production. -9.6.2. Example +9.7.2. Example Here is an example of the Slug: header that uses the encoding rules of [RFC2047]. POST /myblog/entries HTTP/1.1 Host: example.org Content-Type: image/png Slug: =?iso-8859-1?q?The_Beach?= Authorization: Basic ZGFmZnk6c2VjZXJldA== Content-Length: nnn ...binary data... See Section 9.2.1 for an example of the Slug: header applied to the - creation of a Member Entry Resource. + creation of an Entry Resource. 10. Listing Collections Collection Resources MUST provide representations in the form of Atom Feed documents whose Entries contain the IRIs of the Members in the Collection. No structural distinction is made between Collection Feeds and other kinds of Feeds - a Feed might act both as a 'public' feed for subscription purposes and as a Collection Feed. Each Entry in the Feed Document SHOULD have an atom:link element with a relation of "edit" (See Section 11.1). The Entries in the returned Atom Feed SHOULD be ordered by their "atom:updated" property, with the most recently updated Entries - coming first in the document order. Clients SHOULD be constructed in - consideration of the fact that changes which do not alter the atom: + coming first in the document order. Since the Atom Syndication + Format states that the value of atom:updated is altered when the + changes to an Entry are something that "the publisher considers + significant", clients SHOULD be constructed in consideration of the + fact that changes which do not result in alterations to the atom: updated value of an Entry will not affect the position of the Entry - in a Collection. That is, the Atom Syndication Format states that - the value of atom:updated is altered when the changes to an Entry are - something that "the publisher considers significant." The atom: - updated value is not equivalent to the HTTP Last-Modified: header and - can not be used to determine the freshness of cached responses. + in a Collection. The atom:updated value is not equivalent to the + HTTP Last-Modified: header and can not be used to determine the + freshness of cached responses. Clients MUST NOT assume that an Atom Entry returned in the Feed is a - full representation of a Member Entry Resource and SHOULD perform a - GET on the URI of the Member Entry before editing. + full representation of an Entry Resource and SHOULD perform a GET on + the URI of the Member Entry before editing it. See Section 9.5 for a + discussion on the implications of cache control directives when + obtaining entries. -10.1. Collection Paging +10.1. Collection partial lists - Collections can contain large numbers of resources. A naive client - such as a web spider or web browser could be overwhelmed if the - response to a GET contained every Entry in the Collection, and the - server would waste large amounts of bandwidth and processing time on - clients unable to handle the response. For this reason, servers MAY - return a partial listing of the most recently updated Member - Resources. Such partial feed documents MUST have an atom:link with a - "next" relation whose "href" value is the URI of the next partial - listing of the Collection (the next most recently updated Member - Resources) where it exists. This is called "Collection paging". + Collections can contain large numbers of resources. A client such as + a web spider or web browser might be overwhelmed if the response to a + GET contained every Entry in a Collection - in turn the server might + also waste bandwidth and processing time on generating a response + that cannot be handled. For this reason, servers MAY respond to + Collection GET requests with a feed document containing a 'partial + list' of the Collection's members, which also links to the next + partial list feed if it exists. The first such partial list returned + MUST contain the most recently updated member resources and MUST have + an atom:link with a "next" relation whose "href" value is the URI of + the next partial list of the Collection. This next partial list will + contain the next most recently updated set of Member Resources (and + an atom:link to the following partial list if it exists). - The returned Atom Feed MAY contain a subset the Member Entries for a - Collection. In addition, the Atom Feed document MAY contain link - elements with "rel" attribute values of "next", "previous", "first" - and "last" that can be used to navigate through the complete set of - matching Entries. + In addition, partial list feeds MAY contain link elements with "rel" + attribute values of "next", "previous", "first" and "last" that can + be used to navigate through the complete set of entries in the + Collection. For instance, suppose a client is supplied the URI "http://example.org/entries/go" of a Collection of Member entries, where the server as a matter of policy avoids generating feed documents containing more than 10 Entries. The Atom Feed document - for the Collection will then represent the first 'page' in a set of - 10 linked feed documents. The "first" relation will reference the - initial feed document in the set and the "last" relation references - the final Atom Feed Document in the set. Within each document, the - "next" and "previous" link relations reference the preceding and - subsequent documents. + for the Collection will then represent the first partial list of a + set of 10 linked feed documents. The "first" relation will reference + the initial feed document in the set and the "last" relation + references the final Atom Feed Document in the set. Within each + document, the "next" and "previous" link relations reference the + preceding and subsequent documents. ... - The "next" and "previous" link elements for the feed 'page' located - at "http://example.org/entries/2" would look like this: + The "next" and "previous" link elements for the partial list feed + located at "http://example.org/entries/2" would look like this: ... 10.2. The "app:edited" Element The "app:edited" element is a Date construct as defined by [RFC4287] - whose value indicates the most recent instant in time when an Entry - was edited, including when created. Atom Entry elements in - Collection documents SHOULD contain one "app:edited" element, and - MUST NOT contain more than one. + whose content indicates the last time an Entry was edited. If the + entry has not been edited yet, the content indicates the time it was + created. Atom Entry elements in Collection documents SHOULD contain + one "app:edited" element, and MUST NOT contain more than one. appEdited = element app:edited ( atomDateConstruct ) - The server SHOULD change the value of this element every time a Collection Member Resource or an associated Media Resource has been edited. 11. Atom Format Link Relation Extensions 11.1. The "edit" Link Relation This specification adds the value "edit" to the Atom Registry of Link Relations (see section 7.1 of [RFC4287]). The value of "edit" @@ -1401,60 +1495,61 @@ relations in the same Entry reference the same resource. If a client encounters multiple "edit-media" link relations in an Entry then it SHOULD choose a link based on the client preferences for "type" and "hreflang". If a client encounters multiple "edit-media" link relations in an Entry and has no preference based on the "type" and "hreflang" attributes then the client SHOULD pick the first "edit- media" link relation in document order. 12. The Atom Format Type Parameter - The Atom Syndication Format (RFC 4287) defines the 'application/ - atom+xml' media type to identify both Atom Feed and Atom Entry + The Atom Syndication Format (RFC 4287) defines the "application/ + atom+xml" media type to identify both Atom Feed and Atom Entry Documents. Implementation experience has demonstrated that Atom Feed and Entry Documents can have different processing models and that there are situations where they need to be differentiated. This - document defines an optional 'type' parameter used to differentiate + document defines an optional "type" parameter used to differentiate the two types of Atom documents. 12.1. The 'type' parameter This document defines a new "type" parameter for use with the - 'application/atom+xml' media type. + "application/atom+xml" media type: + type = "entry" / "feed" Neither the parameter name nor its value are case sensitive. - The value 'entry' indicates that the media type identifies an Atom + The value "entry" indicates that the media type identifies an Atom Entry Document. The root element of the document MUST be atom:entry. - The value 'feed' indicates that the media type identifies an Atom + The value "feed" indicates that the media type identifies an Atom Feed Document. The root element of the document MUST be atom:feed. If not specified, the type is assumed to be unspecified, requiring Atom processors to examine the root element to determine the type of Atom document. 12.1.1. Conformance New specifications MAY require that the type parameter be used to identify the Atom Document type. Producers of Atom Entry Documents SHOULD use the type parameter regardless of whether or not it is required. Producers of Atom Feed Documents MAY use the parameter. - Atom processors that do not recognize the 'type' parameter MUST + Atom processors that do not recognize the "type" parameter MUST ignore its value and examine the root element to determine the document type. - Atom processors that do recognize the parameter SHOULD detect and - report inconsistencies between the parameter's value and the actual - type of the document's root element. + Atom processors that do recognize the "type" parameter SHOULD detect + and report inconsistencies between the parameter's value and the + actual type of the document's root element. 13. Atom Publishing Controls This specification defines an Atom Format Structured Extension, as defined in Section 6 of [RFC4287], for publishing control within the "http://purl.org/atom/app#" namespace. 13.1. The "app:control" Element namespace app = "http://purl.org/atom/app#" @@ -1477,27 +1572,31 @@ The app:control element and its child elements MAY be included in Atom Feed or Entry Documents. The app:control element can contain an optional "app:draft" element as defined below, and can contain extension elements as defined in Section 6 of [RFC4287]. 13.1.1. The "app:draft" Element + The inclusion of the app:draft element represents a request by the + client to control the visibility of a Member Resource. Server + support is optional and thus the app:draft element MAY be ignored by + the server. + The number of app:draft elements in app:control MUST be zero or one. - Its value MUST be one of "yes" or "no". A value of "no" indicates a - client request that the Member Resource be made publicly visible. If - the app:draft element is missing then the value MUST be understood to - be "no". The inclusion of the app:draft element represents a request - by the client to control the visibility of a Member Resource and the - app:draft element MAY be ignored by the server. + The content of an app:draft element MUST be one of "yes" or "no". If + the element contains "no" this indicates a client request that the + Member Resource be made publicly visible. If the app:draft element + is not present then servers that support the extension MUST behave as + though an app:draft element containing "no" was sent. 14. Securing the Atom Publishing Protocol The Atom Publishing Protocol is based on HTTP. Authentication requirements for HTTP are covered in Section 11 of [RFC2616]. The use of authentication mechanisms to prevent POSTing or editing by unknown or unauthorized clients is RECOMMENDED but not required. When authentication is not used, clients and servers are vulnerable to trivial spoofing, denial of service and defacement attacks, @@ -1507,25 +1606,25 @@ server operator. Clients are likely to face authentication schemes that vary across server deployments. At a minimum, client and server implementations MUST be capable of being configured to use HTTP Basic Authentication [RFC2617] in conjunction with a TLS connection as specified by [RFC2818]. See [RFC4346] for more information on TLS. The choice of authentication mechanism will impact interoperability. The minimum level of security referenced above (Basic Authentication with TLS) is considered good practice for Internet applications at the time of publication of this specification and sufficient for - establishing a baseline for interoperability. Implementers can - investigate and use alternative mechanisms regarded as equivalently - good or better at the time of deployment. It is RECOMMENDED that - clients be implemented in such a way that allows new authentication - schemes to be deployed. + establishing a baseline for interoperability. Implementers are + encouraged to investigate and use alternative mechanisms regarded as + equivalently good or better at the time of deployment. It is + RECOMMENDED that clients be implemented in such a way that allows new + authentication schemes to be deployed. Because this protocol uses HTTP response status codes as the primary means of reporting the result of a request, servers are advised to respond to unauthorized or unauthenticated requests using an appropriate 4xx HTTP response code (e.g. 401 "Unauthorized" or 403 "Forbidden") in accordance with [RFC2617]. 15. Security Considerations As an HTTP-based protocol, APP is subject to the security @@ -1577,69 +1676,69 @@ 16. IANA Considerations 16.1. Content-type registration for 'application/atomserv+xml' An Atom Publishing Protocol Service Document, when serialized as XML 1.0, can be identified with the following media type: MIME media type name: application - MIME subtype name: atomserv+xml + MIME subtype name: atomsvc+xml Mandatory parameters: None. Optional parameters: "charset": This parameter has identical semantics to the charset parameter of the "application/xml" media type as specified in [RFC3023]. Encoding considerations: Identical to those of "application/xml" as described in [RFC3023], section 3.2. Security considerations: As defined in this specification. - [[anchor32: update upon publication]] + [[anchor30: update upon publication]] In addition, as this media type uses the "+xml" convention, it shares the same security considerations as described in [RFC3023], section 10. Interoperability considerations: There are no known interoperability issues. - Published specification: This specification. [[anchor33: update upon + Published specification: This specification. [[anchor31: update upon publication]] Applications that use this media type: No known applications currently use this media type. Additional information: Magic number(s): As specified for "application/xml" in [RFC3023], section 3.2. - File extension: .atomsrv + File extension: .atomsvc Fragment identifiers: As specified for "application/xml" in [RFC3023], section 5. Base URI: As specified in [RFC3023], section 6. Macintosh File Type code: TEXT Person and email address to contact for further information: Joe Gregorio Intended usage: COMMON Author/Change controller: This specification's author(s). - [[anchor34: update upon publication]] + [[anchor32: update upon publication]] 16.2. Content-type registration for 'application/atomcat+xml' An Atom Publishing Protocol Category Document, when serialized as XML 1.0, can be identified with the following media type: MIME media type name: application MIME subtype name: atomcat+xml @@ -1648,30 +1747,30 @@ Optional parameters: "charset": This parameter has identical semantics to the charset parameter of the "application/xml" media type as specified in [RFC3023]. Encoding considerations: Identical to those of "application/xml" as described in [RFC3023], section 3.2. Security considerations: As defined in this specification. - [[anchor35: update upon publication]] + [[anchor33: update upon publication]] In addition, as this media type uses the "+xml" convention, it shares the same security considerations as described in [RFC3023], section 10. Interoperability considerations: There are no known interoperability issues. - Published specification: This specification. [[anchor36: update upon + Published specification: This specification. [[anchor34: update upon publication]] Applications that use this media type: No known applications currently use this media type. Additional information: Magic number(s): As specified for "application/xml" in [RFC3023], section 3.2. @@ -1683,35 +1782,35 @@ Base URI: As specified in [RFC3023], section 6. Macintosh File Type code: TEXT Person and email address to contact for further information: Joe Gregorio Intended usage: COMMON Author/Change controller: This specification's author(s). - [[anchor37: update upon publication]] + [[anchor35: update upon publication]] 16.3. Header field registration for 'SLUG' Header field: SLUG Applicable protocol: http [RFC2616] Status: standard. Author/Change controller: IETF (iesg@ietf.org) Internet Engineering Task Force Specification document(s): draft-ietf-atompub-protocol-13.txt - ([[anchor38: update on rfc number assignment]]) + ([[anchor36: update on rfc number assignment]]) Related information: 16.4. The Link Relation registration "edit" Attribute Value: edit Description: An IRI of an editable Member Entry. When appearing within an atom:entry, the href IRI can be used to retrieve, update and delete the resource represented by that Entry. @@ -1758,22 +1857,20 @@ [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., Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. - [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. - [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types", RFC 3023, January 2001. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005. @@ -1814,39 +1911,47 @@ . [W3C.REC-xmlenc-core] Eastlake, D. and J. Reagle, "XML Encryption Syntax and Processing", World Wide Web Consortium Recommendation REC- xmlenc-core-20021210, December 2002, . 17.2. Informative References + [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. + [RNC] Clark, J., "RELAX NG Compact Syntax", December 2001, . + [W3C.NOTE-detect-lost-update-19990510] + Nielsen, H. and D. LaLiberte, "Editing the Web: Detecting + the Lost Update Problem Using Unreserved Checkout", World + Wide Web Consortium NOTE NOTE-detect-lost-update, + May 1999, . + [W3C.REC-webarch-20041215] Walsh, N. and I. Jacobs, "Architecture of the World Wide Web, Volume One", W3C REC REC-webarch-20041215, December 2004. URIs [1] Appendix A. Contributors The content and concepts within are a product of the Atom community and the Atompub Working Group. - [[anchor42: chairs to compile a contribution list for 1.0 --dehora]] + [[anchor40: chairs to compile a contribution list for 1.0 --dehora]] Appendix B. RELAX NG Compact Schema This appendix is informative. The Relax NG schema explicitly excludes elements in the Atom Protocol namespace which are not defined in this revision of the specification. Requirements for Atom Protocol processors encountering such markup are given in Section 6.2 and Section 6.3 of [RFC4287]. @@ -2103,21 +2208,43 @@ element * - atom:* { (attribute * { text } | text | anyElement)* } # EOF Appendix C. Revision History - [[anchor44: This section to be removed upon publication.]] + [[anchor42: This section to be removed upon publication.]] + + draft-ietf-atompub-protocol-14: typos; removed "The language context + is only significant for elements and attributes declared to be + "Language-Sensitive" by this specification. "; "Successful member + creation is normally indicated with a 201 ("Created") response code." + removed "normally" from that sentence (9.2); Added "Media Link + Entries are represented as Atom Entries and appear in the + Collection." to 9.6; said that an app:accept value of "entry" is + equivalent to "application/atom+xml;type=entry"; double-check spec + terms; Member Entry Resource -> Entry Resource; Added MLE, Entry + Resource and Media Resource terms defs; 6.1 para split; 10.1 + collection paging, rewrote for clarity; 13.1.1 app:edited rewrote for + clarity/conflict; text for GETting entries and cache handling; 4: + Typo: "And Media Resources IRIs", s/Resources/Resource/; consensus + call: application/atomsvc+xml, extension is .atomsvc; DRY app: + categories; make it clear the app:draft support is optional whether + or not the value is sent; 9.2: put related ideas together into + paragraphs.; 10: partial list editing; security: use elharos text; + app:edited: tweak text suplied by ari; create a section for + workspaces and move the descriptive text there; Moved rfc2818 to non- + normative references. Added the W3C note on lost updates as a + reference. draft-ietf-atompub-protocol-13: Added Lisa's verbiage. Folded in James' Atom Format media type 'type' parameter spec. Updated document references to be more consistent, added URLs to some, and shortened up their anchors. Debugged rnc. draft-ietf-atompub-protocol-11: Parts of PaceAppEdited. PaceSecurityConsiderationsRevised. draft-ietf-atompub-protocol-10: PaceRemoveTitleHeader2,