draft-ietf-atompub-protocol-10.txt   draft-ietf-atompub-protocol-11.txt 
Network Working Group J. Gregorio, Ed. Network Working Group J. Gregorio, Ed.
Internet-Draft IBM Internet-Draft IBM
Expires: March 9, 2007 B. de hOra, Ed. Expires: April 6, 2007 B. de hOra, Ed.
Propylon Ltd. Propylon Ltd.
September 05, 2006 October 03, 2006
The Atom Publishing Protocol The Atom Publishing Protocol
draft-ietf-atompub-protocol-10.txt draft-ietf-atompub-protocol-11.txt
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware 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 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. aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 1, line 35 skipping to change at page 1, line 35
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on March 9, 2007. This Internet-Draft will expire on April 6, 2007.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2006). Copyright (C) The Internet Society (2006).
Abstract Abstract
The Atom Publishing Protocol (APP) is an application-level protocol The Atom Publishing Protocol (APP) is an application-level protocol
for publishing and editing Web resources. The protocol is based on for publishing and editing Web resources. The protocol is based on
HTTP transport of Atom-formatted representations. The Atom format is HTTP transport of Atom-formatted representations. The Atom format is
documented in the Atom Syndication Format (RFC4287). documented in the Atom Syndication Format [RFC4287].
Editorial Note Editorial Note
To provide feedback on this Internet-Draft, join the atom-protocol To provide feedback on this Internet-Draft, join the atom-protocol
mailing list (http://www.imc.org/atom-protocol/index.html) [1]. mailing list (http://www.imc.org/atom-protocol/index.html) [1].
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 5 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 5
2.1 XML-related Conventions . . . . . . . . . . . . . . . . . 5 2.1 XML-related Conventions . . . . . . . . . . . . . . . . . 5
2.1.1 Referring to Information Items . . . . . . . . . . . . 5 2.1.1 Referring to Information Items . . . . . . . . . . . . 5
2.1.2 RELAX NG Schema . . . . . . . . . . . . . . . . . . . 5 2.1.2 RELAX NG Schema . . . . . . . . . . . . . . . . . . . 5
2.1.3 Use of xml:base and xml:lang . . . . . . . . . . . . . 5 2.1.3 Use of xml:base and xml:lang . . . . . . . . . . . . . 5
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . 8 4. Protocol Model . . . . . . . . . . . . . . . . . . . . . . . 7
5. Protocol Operations . . . . . . . . . . . . . . . . . . . . 10 5. Protocol Operations . . . . . . . . . . . . . . . . . . . . 9
5.1 Retrieving a Service Document . . . . . . . . . . . . . . 10 5.1 Retrieving a Service Document . . . . . . . . . . . . . . 9
5.2 Listing Collection Members . . . . . . . . . . . . . . . . 10 5.2 Listing Collection Members . . . . . . . . . . . . . . . . 9
5.3 Creating a Resource . . . . . . . . . . . . . . . . . . . 11 5.3 Creating a Resource . . . . . . . . . . . . . . . . . . . 10
5.4 Editing a Resource . . . . . . . . . . . . . . . . . . . . 11 5.4 Editing a Resource . . . . . . . . . . . . . . . . . . . . 10
5.4.1 Retrieving a Resource . . . . . . . . . . . . . . . . 11 5.4.1 Retrieving a Resource . . . . . . . . . . . . . . . . 10
5.4.2 Updating a Resource . . . . . . . . . . . . . . . . . 12 5.4.2 Updating a Resource . . . . . . . . . . . . . . . . . 11
5.4.3 Deleting a Resource . . . . . . . . . . . . . . . . . 12 5.4.3 Deleting a Resource . . . . . . . . . . . . . . . . . 11
5.5 Use of HTTP Response codes . . . . . . . . . . . . . . . . 12 5.5 Use of HTTP Response codes . . . . . . . . . . . . . . . . 11
6. Atom Publishing Protocol Documents . . . . . . . . . . . . . 13 6. Atom Publishing Protocol Documents . . . . . . . . . . . . . 12
6.1 Document Types . . . . . . . . . . . . . . . . . . . . . . 13 6.1 Document Types . . . . . . . . . . . . . . . . . . . . . . 12
6.2 Document Extensibility . . . . . . . . . . . . . . . . . . 13 6.2 Document Extensibility . . . . . . . . . . . . . . . . . . 12
7. Category Documents . . . . . . . . . . . . . . . . . . . . . 14 7. Category Documents . . . . . . . . . . . . . . . . . . . . . 13
7.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . 14 7.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . 13
7.2 Element Definitions . . . . . . . . . . . . . . . . . . . 14 7.2 Element Definitions . . . . . . . . . . . . . . . . . . . 13
7.2.1 The "app:categories" element . . . . . . . . . . . . . 14 7.2.1 The "app:categories" element . . . . . . . . . . . . . 13
8. Service Documents . . . . . . . . . . . . . . . . . . . . . 16 8. Service Documents . . . . . . . . . . . . . . . . . . . . . 15
8.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . 16 8.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . 16
8.2 Element Definitions . . . . . . . . . . . . . . . . . . . 17 8.2 Element Definitions . . . . . . . . . . . . . . . . . . . 17
8.2.1 The "app:service" Element . . . . . . . . . . . . . . 17 8.2.1 The "app:service" Element . . . . . . . . . . . . . . 17
8.2.2 The "app:workspace" Element . . . . . . . . . . . . . 17 8.2.2 The "app:workspace" Element . . . . . . . . . . . . . 17
8.2.3 The "app:collection" Element . . . . . . . . . . . . . 18 8.2.3 The "app:collection" Element . . . . . . . . . . . . . 18
8.2.4 The "app:accept" Element . . . . . . . . . . . . . . . 19 8.2.4 The "app:accept" Element . . . . . . . . . . . . . . . 19
8.2.5 The "app:categories" Element . . . . . . . . . . . . . 20 8.2.5 The "app:categories" Element . . . . . . . . . . . . . 20
9. Creating and Editing Resources . . . . . . . . . . . . . . . 22 9. Creating and Editing Resources . . . . . . . . . . . . . . . 22
9.1 Member URIs . . . . . . . . . . . . . . . . . . . . . . . 22 9.1 Member URIs . . . . . . . . . . . . . . . . . . . . . . . 22
9.2 Creating resources with POST . . . . . . . . . . . . . . . 22 9.2 Creating resources with POST . . . . . . . . . . . . . . . 22
9.2.1 Example . . . . . . . . . . . . . . . . . . . . . . . 23 9.2.1 Example . . . . . . . . . . . . . . . . . . . . . . . 23
9.3 Updating Resources with PUT . . . . . . . . . . . . . . . 24 9.3 Updating Resources with PUT . . . . . . . . . . . . . . . 24
9.4 Deleting Resources with DELETE . . . . . . . . . . . . . . 24 9.4 Deleting Resources with DELETE . . . . . . . . . . . . . . 24
9.5 Media Resources and Media Link Entries . . . . . . . . . . 24 9.5 Media Resources and Media Link Entries . . . . . . . . . . 24
9.6 The Slug: Header . . . . . . . . . . . . . . . . . . . . . 25 9.6 The Slug: Header . . . . . . . . . . . . . . . . . . . . . 25
9.6.1 Slug: Header syntax . . . . . . . . . . . . . . . . . 25 9.6.1 Slug: Header syntax . . . . . . . . . . . . . . . . . 25
9.6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . 26 9.6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . 26
10. Listing Collections . . . . . . . . . . . . . . . . . . . . 28 10. Listing Collections . . . . . . . . . . . . . . . . . . . . 28
10.1 Collection Paging . . . . . . . . . . . . . . . . . . . 28 10.1 Collection Paging . . . . . . . . . . . . . . . . . . . 28
10.2 The "app:edited" Element . . . . . . . . . . . . . . . . 29
11. Atom Format Link Relation Extensions . . . . . . . . . . . . 30 11. Atom Format Link Relation Extensions . . . . . . . . . . . . 30
11.1 The "edit" Link Relation . . . . . . . . . . . . . . . . 30 11.1 The "edit" Link Relation . . . . . . . . . . . . . . . . 30
11.2 The "edit-media" Link Relation . . . . . . . . . . . . . 30 11.2 The "edit-media" Link Relation . . . . . . . . . . . . . 30
12. Atom Publishing Controls . . . . . . . . . . . . . . . . . . 31 12. Atom Publishing Controls . . . . . . . . . . . . . . . . . . 31
12.1 The "app:control" Element . . . . . . . . . . . . . . . 31 12.1 The "app:control" Element . . . . . . . . . . . . . . . 31
12.1.1 The "app:draft" Element . . . . . . . . . . . . . . 31 12.1.1 The "app:draft" Element . . . . . . . . . . . . . . 31
13. Securing the Atom Protocol . . . . . . . . . . . . . . . . . 32 13. Securing the Atom Publishing Protocol . . . . . . . . . . . 32
14. Security Considerations . . . . . . . . . . . . . . . . . . 33 14. Security Considerations . . . . . . . . . . . . . . . . . . 33
14.1 Denial of Service . . . . . . . . . . . . . . . . . . . 33
14.2 Replay Attacks . . . . . . . . . . . . . . . . . . . . . 33
14.3 Spoofing Attacks . . . . . . . . . . . . . . . . . . . . 33
14.4 Linked Resources . . . . . . . . . . . . . . . . . . . . 33
14.5 Digital Signatures and Encryption . . . . . . . . . . . 33
14.6 URIs and IRIs . . . . . . . . . . . . . . . . . . . . . 33
15. IANA Considerations . . . . . . . . . . . . . . . . . . . . 34 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . 34
15.1 Content-type registration for 15.1 Content-type registration for
'application/atomserv+xml' . . . . . . . . . . . . . . . 34 'application/atomserv+xml' . . . . . . . . . . . . . . . 34
15.2 Content-type registration for 15.2 Content-type registration for
'application/atomcat+xml' . . . . . . . . . . . . . . . 35 'application/atomcat+xml' . . . . . . . . . . . . . . . 35
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 15.3 Header field registration for 'SLUG' . . . . . . . . . . 36
16.1 Normative References . . . . . . . . . . . . . . . . . . 37 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 38
16.2 Informative References . . . . . . . . . . . . . . . . . 38 16.1 Normative References . . . . . . . . . . . . . . . . . . 38
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 39 16.2 Informative References . . . . . . . . . . . . . . . . . 39
A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 40 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 40
B. RELAX NG Compact Schema . . . . . . . . . . . . . . . . . . 41 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 41
C. Revision History . . . . . . . . . . . . . . . . . . . . . . 47 B. RELAX NG Compact Schema . . . . . . . . . . . . . . . . . . 42
Intellectual Property and Copyright Statements . . . . . . . 50 C. Revision History . . . . . . . . . . . . . . . . . . . . . . 48
Intellectual Property and Copyright Statements . . . . . . . 51
1. Introduction 1. Introduction
The Atom Publishing Protocol is an application-level protocol for The Atom Publishing Protocol is an application-level protocol for
publishing and editing Web resources using HTTP [RFC2616] and XML 1.0 publishing and editing Web resources using HTTP [RFC2616] and XML 1.0
[W3C.REC-xml-20040204]. The protocol supports the creation of [W3C.REC-xml-20060816]. The protocol supports the creation of
arbitrary web resources and provides facilities for: arbitrary web resources and provides facilities for:
o Collections: Sets of resources, which can be retrieved in whole or o Collections: Sets of resources, which can be retrieved in whole or
in part. in part.
o Service: Discovering and describing Collections. o Service: Discovering and describing Collections.
o Editing: Creating, updating and deleting resources. o Editing: Creating, updating and deleting resources.
2. Notational Conventions 2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
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 [RFC3987] (Section 3.1). The resource identified by the URI after
conversion is the same as the one identified by the IRI.
2.1 XML-related Conventions 2.1 XML-related Conventions
2.1.1 Referring to Information Items 2.1.1 Referring to Information Items
Atom Protocol Document formats are specified in terms of the XML Atom Protocol Document formats are specified in terms of the XML
Information Set [W3C.REC-xml-infoset-20040204], serialized as XML 1.0 Information Set [W3C.REC-xml-infoset-20040204], serialized as XML 1.0
[W3C.REC-xml-20040204]. [W3C.REC-xml-20060816].
The Infoset terms "Element Information Item" and "Attribute The Infoset terms "Element Information Item" and "Attribute
Information Item" are shortened to "element" and "attribute" Information Item" are shortened to "element" and "attribute"
respectively. Therefore, when this specification uses the term respectively. Therefore, when this specification uses the term
"element", it is referring to an Element Information Item, and when "element", it is referring to an Element Information Item, and when
it uses the term "attribute", it is referring to an Attribute it uses the term "attribute", it is referring to an Attribute
Information Item. Information Item.
2.1.2 RELAX NG Schema 2.1.2 RELAX NG Schema
Some sections of this specification are illustrated with fragments of Some sections of this specification are illustrated with fragments of
a non-normative RELAX NG Compact schema [RNC]. However, the text of a non-normative RELAX NG Compact schema [RNC]. However, the text of
this specification provides the definition of conformance. Complete this specification provides the definition of conformance. Complete
schemas appear in Appendix B. schemas appear in Appendix B.
2.1.3 Use of xml:base and xml:lang 2.1.3 Use of xml:base and xml:lang
XML elements defined by this specification MAY have an xml:base XML elements defined by this specification MAY have an xml:base
attribute [W3C.REC-xmlbase-20010627]. When xml:base is used, it attribute [W3C.REC-xmlbase-20010627]. When xml:base is used, it
serves the function described in section 5.1.1 of URI Generic Syntax serves the function described in Section 5.1.1 of URI Generic Syntax
[RFC3986], by establishing the base URI (or IRI) for resolving [RFC3986], by establishing the base URI (or IRI) for resolving
relative references found within the scope of the xml:base attribute. relative references found within the scope of the xml:base attribute.
Any element defined by this specification MAY have an xml:lang Any element defined by this specification MAY have an xml:lang
attribute, whose content indicates the natural language for the attribute, whose content indicates the natural language for the
element and its descendents. The language context is only element and its descendents. The language context is only
significant for elements and attributes declared to be "Language- significant for elements and attributes declared to be "Language-
Sensitive" by this specification. Requirements regarding the content Sensitive" by this specification. Requirements regarding the content
and interpretation of xml:lang are specified in Section 2.12 of XML and interpretation of xml:lang are specified in Section 2.12 of XML
1.0 [W3C.REC-xml-20040204]. 1.0 [W3C.REC-xml-20060816].
3. Terminology 3. Terminology
For convenience, this protocol can be referred to as the "Atom For convenience, this protocol can be referred to as the "Atom
Protocol" or "APP". Protocol" or "APP".
URI/IRI - A Uniform Resource Identifier and Internationalized URI/IRI - A Uniform Resource Identifier and Internationalized
Resource Identifier. These terms and the distinction between them Resource Identifier. These terms and the distinction between them
are defined in [RFC3986] and [RFC3987]. IRIs are mapped to URIs are defined in [RFC3986] and [RFC3987]. Before an IRI found in a
before dereferencing takes place. 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 The phrase "the URI of a document" in this specification is shorthand
for "a URI which, when dereferenced, is expected to produce that for "a URI which, when dereferenced, is expected to produce that
document as a representation". document as a representation".
Resource - A network-accessible data object or service identified by Resource - A network-accessible data object or service identified by
an IRI, as defined in [RFC2616]. See [W3C.REC-webarch-20041215] for an IRI, as defined in [RFC2616]. See [W3C.REC-webarch-20041215] for
further discussion on resources. further discussion on resources.
Representation - An entity included with a request or response as Representation - An entity included with a request or response as
defined in [RFC2616]. defined in [RFC2616].
Collection - A resource that contains a set of Member IRIs. See Collection - A resource that contains a set of Member Entries. See
Section 9. Section 9.
Member - A resource whose IRI is listed in a Collection by a link 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. element with a relation of "edit" or "edit-media". See Section 9.1.
Workspace - A group of collections. See Section 8. Workspace - A group of collections. See Section 8.
Service Document - A document that describes the location and Service Document - A document that describes the location and
capabilities of one or more Collections. See Section 8. capabilities of one or more Collections. See Section 8.
Category Document - A document that describes the categories allowed Category Document - A document that describes the categories allowed
in a Collection. See Section 7. in a Collection. See Section 7.
4. Protocol Model 4. Protocol Model
The Atom Publishing Protocol uses HTTP methods to edit and author The Atom Publishing Protocol uses HTTP methods to author Member
Member Resources as follows: Resources as follows:
o GET is used to retrieve a representation of a known resource. o GET is used to retrieve a representation of a known resource.
o POST is used to create a new, dynamically-named, resource. o POST is used to create a new, dynamically-named, resource.
o PUT is used to update a known resource. o PUT is used to update a known resource.
o DELETE is used to remove a known resource. o DELETE is used to remove a known resource.
Along with operations on Member Resources the Atom Protocol defines Along with operations on Member Resources the Atom Protocol defines
Collection resources for managing and organizing Member Resources. Collection resources for managing and organizing Member Resources.
Collections are represented by Atom Feed documents and contain the Collections are represented by Atom Feed documents and contain the
IRIs of, and metadata about, their Member Resources. IRIs of, and metadata about, their Member Resources.
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]. The resource identified by the URI
after conversion is the same as the one identified by the IRI.
There are two kinds of Member Resources - Member Entry Resources and There are two kinds of Member Resources - Member Entry Resources and
Media Resources. Member Entry Resources are represented as Atom Media Resources. Member Entry Resources are represented as Atom
Entries. Media Resources MAY have representations in any media type. Entries [RFC4287]. Media Resources can have representations in any
A Media Link Entry is a Member Entry that contains metadata about a media type. A Media Link Entry is a Member Entry that contains
Media Resource. This diagram shows the classification of the metadata about a Media Resource. This diagram shows the
resources: classification of the resources:
Member Resource Member Resource
-> Member Entry Resource -> Member Entry Resource
-> Media Link Entry Resource -> Media Link Entry Resource
-> Media Resource -> Media Resource
Collections, represented by Atom feeds, contain entries. Those Collections, represented by Atom feeds, contain entries. Those
entries contain the Member Entry and Media Resources IRIs of the entries contain the Member Entry and Media Resources IRIs of the
Collection. A Collection can contain any number of entries of either Collection. A Collection can contain any number of entries of either
kind. In the diagram of a Collection below there are two entries. kind. In the diagram of a Collection below there are two entries.
skipping to change at page 10, line 11 skipping to change at page 9, line 11
Service Documents represent server-defined groups of Collections, and Service Documents represent server-defined groups of Collections, and
are used to initialize the process of creating and editing resources. are used to initialize the process of creating and editing resources.
5. Protocol Operations 5. Protocol Operations
5.1 Retrieving a Service Document 5.1 Retrieving a Service Document
Client Server Client Server
| | | |
| 1.) GET to URI of Service Document | | 1.) GET to Service Document |
|------------------------------------------>| |------------------------------------------>|
| | | |
| 2.) Service Document | | 2.) Service Document |
|<------------------------------------------| |<------------------------------------------|
| | | |
1. The client sends a GET request to the URI of the Service 1. The client sends a GET request using the URI of the Service
Document. Document.
2. The server responds with the document enumerating the IRIs of a 2. The server responds with the document enumerating the IRIs of a
set of Collections and the capabilities of those Collections set of Collections and the capabilities of those Collections
supported by the server. The content of this document can vary supported by the server. The content of this document can vary
based on aspects of the client request, including, but not based on aspects of the client request, including, but not
limited to, authentication credentials. limited to, authentication credentials.
5.2 Listing Collection Members 5.2 Listing Collection Members
To list the members of a Collection the client sends a GET request to To list the members of a Collection, the client sends a GET request
the URI of a Collection. An Atom Feed Document is returned to the URI of a Collection. An Atom Feed Document is returned
containing one Atom Entry for each Member Entry Resource. See containing one Atom Entry for each Member Entry Resource. See
Section 10 and Section 11 for a description of the feed contents. Section 10 and Section 11 for a description of the feed contents.
Client Server Client Server
| | | |
| 1.) GET to Collection URI | | 1.) GET to Collection URI |
|------------------------------->| |------------------------------->|
| | | |
| 2.) 200 OK, Atom Feed Doc | | 2.) 200 OK, Atom Feed Doc |
|<-------------------------------| |<-------------------------------|
skipping to change at page 12, line 46 skipping to change at page 11, line 46
with a status code of 200. with a status code of 200.
A different approach is taken for deleting Media Resources, see A different approach is taken for deleting Media Resources, see
Section 9.5 for details. Section 9.5 for details.
5.5 Use of HTTP Response codes 5.5 Use of HTTP Response codes
The Atom Protocol uses the response status codes defined in HTTP to The Atom Protocol uses the response status codes defined in HTTP to
indicate the success or failure of an operation. Consult the HTTP indicate the success or failure of an operation. Consult the HTTP
specification [RFC2616] for detailed definitions of each status code. specification [RFC2616] for detailed definitions of each status code.
It is RECOMMENDED that entities contained within HTTP 4xx and 5xx Implementers are asked to note that per the HTTP specification, HTTP
responses include a human-readable explanation of the error. 4xx and 5xx response entities SHOULD include a human-readable
explanation of the error.
6. Atom Publishing Protocol Documents 6. Atom Publishing Protocol Documents
6.1 Document Types 6.1 Document Types
This specification describes two kinds of Documents - Category This specification describes two kinds of Documents - Category
Documents and Service Documents. Documents and Service Documents.
A Category Document (Section 7) contain lists of categories specified A Category Document (Section 7) contain lists of categories specified
using the "atom:category" element from the Atom Syndication Format. using the "atom:category" element from the Atom Syndication Format.
A Service Document (Section 8) describes capabilities of workspaces, A Service Document (Section 8) describes capabilities of workspaces,
which are server-defined groupings of Collections. which are server-defined groupings of Collections.
The namespace name [W3C.REC-xml-names-19990114] for either kind of The namespace name [W3C.REC-xml-names-20060816] for either kind of
document is: document is:
http://purl.org/atom/app# http://purl.org/atom/app#
[[anchor8: Needs to be updated with the final URI upon publication]]
This specification uses the prefix "app:" for the namespace name. This specification uses the prefix "app:" for the namespace name.
The prefix "atom:" is used for "http://www.w3.org/2005/Atom", the 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]. The
namespace prefixes are not semantically significant. namespace prefixes are not semantically significant.
Atom Publishing Protocol Documents MUST be well-formed XML. This Atom Publishing Protocol Documents MUST be well-formed XML. This
specification does not define any DTDs for Atom Protocol formats, and 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. hence does not require them to be "valid" in the sense used by XML.
6.2 Document Extensibility 6.2 Document Extensibility
The namespace name "http://purl.org/atom/app#" is reserved for future
forward-compatible revisions of the document types. Future versions
of this specification could add new elements and attributes.
Software written to conform to this version of the specification will
not be able to process such markup correctly and in fact will not be
able to distinguish it from markup error.
Unrecognized markup in an Atom Publishing Protocol document is Unrecognized markup in an Atom Publishing Protocol document is
considered "foreign markup" as defined in [RFC4287]. 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 or signal an error, and SHOULD
preserve foreign markup when transmitting such documents.
Markup from other vocabularies ("foreign markup") can be used The namespace name "http://purl.org/atom/app#" is reserved for
anywhere within a Category or Service Document unless it is forward compatible revisions of the Category and Service Document
explicitly forbidden. Processors that encounter foreign markup MUST types - this does not exclude the addition of elements and attributes
NOT stop processing or signal an error, and SHOULD preserve foreign that might not be recognised by processors conformant to this
markup when transmitting such documents. specification. Such unrecognised markup from the
"http://purl.org/atom/app#" namespace MUST be treated as foreign
markup.
7. Category Documents 7. Category Documents
Category Documents contain lists of categories described using the Category Documents contain lists of categories described using the
"atom:category" element from the Atom Syndication Format [RFC4287]. "atom:category" element from the Atom Syndication Format [RFC4287].
Categories can also appear in Service Documents and describe the Categories can also appear in Service Documents and describe the
categories allowed in a Collection (see Section 8.2.5). categories allowed in a Collection (see Section 8.2.5).
Category Documents are identified with the "application/atomcat+xml" Category Documents are identified with the "application/atomcat+xml"
media type (see Section 15). media type (see Section 15).
skipping to change at page 14, line 27 skipping to change at page 13, line 27
<?xml version="1.0" ?> <?xml version="1.0" ?>
<app:categories <app:categories
xmlns:app="http://purl.org/atom/app#" xmlns:app="http://purl.org/atom/app#"
xmlns="http://www.w3.org/2005/Atom" xmlns="http://www.w3.org/2005/Atom"
fixed="yes" scheme="http://example.com/cats/big3"> fixed="yes" scheme="http://example.com/cats/big3">
<category term="animal" /> <category term="animal" />
<category term="vegetable" /> <category term="vegetable" />
<category term="mineral" /> <category term="mineral" />
</app:categories> </app:categories>
This Category Document contains three categories with the terms This Category Document contains three categories, with the terms
"animal", "vegetable", and "mineral". None of the categories has a "animal", "vegetable", and "mineral". None of the categories use the
label attribute (as defined in [RFC4287]). They all inherit the 'label' attribute defined in [RFC4287]. They all inherit the
"http://example.com/cats/big3" category 'scheme' (in the [RFC4287] "http://example.com/cats/big3" 'scheme' attribute declared on the
sense) declared on the app:categories element. Therefore if the app:categories element. Therefore if the "mineral" category were to
"mineral" category were to appear in an Atom Entry or Feed Document, appear in an Atom Entry or Feed Document, it would appear as:
it would appear as:
<category scheme="http://example.com/cats/big3" term="mineral" /> <category scheme="http://example.com/cats/big3" term="mineral" />
7.2 Element Definitions 7.2 Element Definitions
7.2.1 The "app:categories" element 7.2.1 The "app:categories" element
The root of a Category Document is the "app:categories" element. An The root of a Category Document is the "app:categories" element. An
app:categories element MAY contain one or more "atom:category" app:categories element can contain zero or more "atom:category"
elements from the Atom namespace ("http://www.w3.org/2005/Atom"). elements from the Atom namespace ("http://www.w3.org/2005/Atom").
If an app:category child element has no "scheme" attribute it An app:category child element that has no "scheme" attribute inherits
inherits the attribute from its app:categories parent. An app: the attribute from its app:categories parent. An app:category child
category child element with an existing "scheme" attribute does not element with an existing "scheme" attribute does not inherit the
inherit the "scheme" value of its "app:categories" parent element. "scheme" value of its "app:categories" parent element.
7.2.1.1 Attributes of "app:categories" 7.2.1.1 Attributes of "app:categories"
The app:categories element MAY contain a "fixed" attribute, with a The app:categories element can contain a "fixed" attribute, with a
value of either "yes" or "no", indicating if the list of categories value of either "yes" or "no", indicating whether the list of
is a fixed or an open set. Collections that indicate the set is categories is a fixed or an open set. Newly created or updated
fixed MAY reject members whose categories are not listed in the members whose categories are not listed in the Collection Document
Collection Document. Collections that indicate the set is open MAY be rejected by the server. Collections that indicate the set is
SHOULD NOT reject otherwise acceptable members whose categories are open SHOULD NOT reject otherwise acceptable members whose categories
not listed in the Collection. are not listed in the Collection.
Alternatively, the app:categories element MAY contain an "href" Alternatively, the app:categories element MAY contain an "href"
attribute, whose value MUST be an IRI reference identifying a attribute, whose value MUST be an IRI reference identifying a
Category Document. If the "href" attribute is provided, the app: Category Document. If the "href" attribute is provided the app:
categories element MUST be empty and MUST NOT have the "fixed" or categories element MUST be empty and MUST NOT have the "fixed" or
"scheme" attributes. "scheme" attributes.
atomCategory = atomCategory =
element atom:category { element atom:category {
atomCommonAttributes, atomCommonAttributes,
attribute term { text }, attribute term { text },
attribute scheme { atomURI }?, attribute scheme { atomURI }?,
attribute label { text }?, attribute label { text }?,
undefinedContent undefinedContent
skipping to change at page 15, line 40 skipping to change at page 14, line 36
appInlineCategories = appInlineCategories =
element app:categories { element app:categories {
attribute fixed { "yes" | "no" }?, attribute fixed { "yes" | "no" }?,
attribute scheme { atomURI }?, attribute scheme { atomURI }?,
(atomCategory*) (atomCategory*)
} }
appOutOfLineCategories = appOutOfLineCategories =
element app:categories { element app:categories {
attribute href { atomURI }, attribute href { atomURI },
(empty) undefinedContent
} }
appCategories = appInlineCategories | appOutOfLineCategories appCategories = appInlineCategories | appOutOfLineCategories
8. Service Documents 8. Service Documents
For authoring to commence, a client needs to first discover the For authoring to commence, a client needs to first discover the
capabilities and locations of the available collections. Service capabilities and locations of the available collections. Service
Documents are designed to support this discovery process. Documents are designed to support this discovery process. How
Service Documents are in turn discovered is not defined in this
specification.
A Service Document describes workspaces, which are server-defined A Service Document describes workspaces, which are server-defined
groupings of Collections. Service Documents are identified with the groupings of Collections. Service Documents are identified with the
"application/atomserv+xml" media type (see Section 15). "application/atomserv+xml" media type (see Section 15).
There is no requirement that a server support multiple workspaces. There is no requirement that a server support multiple workspaces.
In addition, a Collection MAY appear in more than one Workspace. In addition, a Collection MAY appear in more than one Workspace.
8.1 Example 8.1 Example
skipping to change at page 18, line 10 skipping to change at page 17, line 42
8.2.2 The "app:workspace" Element 8.2.2 The "app:workspace" Element
The "app:workspace" element contains information elements about the The "app:workspace" element contains information elements about the
collections of resources available for editing. The app:workspace collections of resources available for editing. The app:workspace
element contains zero or more app:collection elements. element contains zero or more app:collection elements.
appWorkspace = appWorkspace =
element app:workspace { element app:workspace {
appCommonAttributes, appCommonAttributes,
( appCollection* ( atomTitle
& appCollection*
& extensionElement* ) & extensionElement* )
} }
atomTitle = element atom:title { atomTextConstruct } atomTitle = element atom:title { atomTextConstruct }
In an app:workspace element, the first app:collection element MUST In an app:workspace element, the first app:collection element MUST
refer to the preferred or primary Collection. In the following refer to the preferred or primary Collection. This distinction is
example, the "Entries" collection would be considered the preferred considered useful in scenarios where Members and Media Link Entries
are POSTed to different Collections. In the following example, the
"Eintragungen" collection would be considered the preferred
Collection: Collection:
<service xmlns="http://purl.org/atom/app#" <service xmlns="http://purl.org/atom/app#"
xmlns:atom="http://www.w3.org/2005/Atom"> xmlns:atom="http://www.w3.org/2005/Atom">
<workspace> <workspace xml:lang="de">
<atom:title>My Blog</atom:title> <atom:title>Das Blog</atom:title>
<collection <collection
href="http://example.org/myblog/entries" > href="http://example.org/blog/eintragungen" >
<atom:title>Entries</atom:title> <atom:title>Eintragungen</atom:title>
</collection> </collection>
<collection <collection
href="http://example.org/myblog/fotes"> href="http://example.org/blog/fotos">
<atom:title>Photos</atom:title> <atom:title>Fotos</atom:title>
<accept>image/*</accept> <accept>image/*</accept>
</collection> </collection>
</workspace> </workspace>
</service> </service>
8.2.2.1 The "atom:title" Element 8.2.2.1 The "atom:title" Element
The app:workspace element MUST contain one "atom:title" element, The app:workspace element MUST contain one "atom:title" element (as
giving a human-readable title for the workspace. defined in [RFC4287]), giving a human-readable title for the
workspace.
8.2.3 The "app:collection" Element 8.2.3 The "app:collection" Element
The "app:collection" element describes a Collection. The app: The "app:collection" element describes a Collection. The app:
collection element MAY contain one app:accept element and MAY contain collection element MAY contain one app:accept element and MAY contain
any number of app:categories elements. The app:collection element any number of app:categories elements. The app:collection element
MUST NOT contain more that one app:accept element. MUST NOT contain more than one app:accept element.
appCollection = appCollection =
element app:collection { element app:collection {
appCommonAttributes, appCommonAttributes,
attribute href { atomURI }, attribute href { atomURI },
( appAccept? ( atomTitle
& appAccept?
& appCategories* & appCategories*
& extensionElement* ) & extensionElement* )
} }
8.2.3.1 Usage in Atom Feed Documents 8.2.3.1 Usage in Atom Feed Documents
The app:collection element MAY appear as a child of an atom:feed or 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 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. Collection by which new entries can be added to appear in the feed.
The app:control element is considered foreign markup as defined in
Section 6 of [RFC4287].
8.2.3.2 The "href" Attribute 8.2.3.2 The "href" Attribute
The app:collection element MUST contain an "href" attribute, whose The app:collection element MUST contain an "href" attribute, whose
value gives the IRI of the Collection. value gives the IRI of the Collection.
8.2.3.3 The "atom:title" Element 8.2.3.3 The "atom:title" Element
The app:collection Element MUST contain one "atom:title" element, The app:collection Element MUST contain one "atom:title" element,
giving a human-readable title for the Workspace. giving a human-readable title for the Workspace.
8.2.4 The "app:accept" Element 8.2.4 The "app:accept" Element
The "app:accept" element value specifies a comma-separated list of The "app:accept" element value specifies a comma-separated list of
media-ranges (see [RFC2616]) identifying the types of representations media-ranges (see [RFC2616]) identifying the types of representations
that can be POSTed to the URI of a Collection. Whitespace separation that can be POSTed to the URI of a Collection. Whitespace around and
of the media-range values is considered insignificant and MUST be between media-range values is considered insignificant and MUST be
ignored. ignored.
The app:accept element is similar to the HTTP Accept request-header The app:accept element is similar to the HTTP Accept request-header
[RFC2616] with the exception that app:accept has no notion of [RFC2616] with the exception that app:accept has no notion of
preference. As a result, the value syntax of app:accept does not use preference. As a result, the value syntax of app:accept does not use
"accept-params" or "q" arguments as specified in [RFC2616], section "accept-params" or "q" arguments as specified in [RFC2616], section
14.1. 14.1.
The order of media-ranges is not significant. The following lists The order of media-ranges is not significant. The following lists
are all equivalent: are all equivalent:
skipping to change at page 20, line 44 skipping to change at page 20, line 39
appInlineCategories = appInlineCategories =
element app:categories { element app:categories {
attribute fixed { "yes" | "no" }?, attribute fixed { "yes" | "no" }?,
attribute scheme { atomURI }?, attribute scheme { atomURI }?,
(atomCategory*) (atomCategory*)
} }
appOutOfLineCategories = appOutOfLineCategories =
element app:categories { element app:categories {
attribute href { atomURI }, attribute href { atomURI },
(empty) undefinedContent
} }
appCategories = appInlineCategories | appOutOfLineCategories appCategories = appInlineCategories | appOutOfLineCategories
The app:categories element MAY contain a "fixed" attribute, with a The app:categories element MAY contain a "fixed" attribute, with a
value of either "yes" or "no", indicating whether or not the listing value of either "yes" or "no", indicating whether or not the listing
of categories is considered to be a fixed, or closed set. The of categories is considered to be a fixed, or closed set. The
absence of the "fixed" attribute is equivalent to the presence of a absence of the "fixed" attribute is equivalent to the presence of a
"fixed" attribute with a value of "no". Collections that indicate a "fixed" attribute with a value of "no". Collections that indicate a
fixed set MAY reject members that include categories not specified in fixed set MAY reject members that include categories not specified in
the provided listing. Collections that indicate an open set SHOULD the provided listing. Collections that indicate an open set SHOULD
NOT reject otherwise acceptable members whose categories are not NOT reject otherwise acceptable members whose categories are not
present in the provided list. present in the provided list.
skipping to change at page 22, line 25 skipping to change at page 22, line 25
a Location header after successful resource creation using POST, as a Location header after successful resource creation using POST, as
described below. Second, in the entries of a Collection document, by described below. Second, in the entries of a Collection document, by
an atom:link element with a link relation of "edit". an atom:link element with a link relation of "edit".
Each Member Entry SHOULD contain such an atom:link element providing Each Member Entry SHOULD contain such an atom:link element providing
its Member Entry URI. its Member Entry URI.
9.2 Creating resources with POST 9.2 Creating resources with POST
To add members to a Collection, clients send POST requests to the URI To add members to a Collection, clients send POST requests to the URI
of a Collection. Collections MAY impose constraints on the media- of a Collection. Successful member creation is normally indicated
types of request entities POSTed to the Collection and MAY generate a with a 201 ("Created") response code. Collections MAY generate a
response with a status code of 415 ("Unsupported Media Type"). response with a status code of 415 ("Unsupported Media Type") to
indicate media-type of POSTed entity is not allowed or supported by
the Collection.
If a Member Resource was created in the Collection which received the When a Member Resource is created in the Collection which received
POST, its Member Entry URI MUST be returned in an HTTP Location the POST, its Member Entry URI MUST be returned in an HTTP Location
header. header.
When the server generates a response with a status code of 201 When the server generates a response with a status code of 201
("Created"), it SHOULD also return a response body, which if ("Created"), it SHOULD also return a response body, which if
provided, MUST be an Atom Entry Document representing the newly- provided, MUST be an Atom Entry Document representing the newly-
created resource, and SHOULD include its Member Entry URI in an atom: created resource.
link element that has a relation of "edit".
Since the server is free to alter the posted entry, for example by Since the server is free to alter the posted entry, for example by
changing the content of the "id" element, returning the Entry as changing the content of the "id" element, returning the Entry as
described in the previous paragraph can be useful to the client, described in the previous paragraph can be useful to the client,
enabling it to correlate the client and server views of the new enabling it to correlate the client and server views of the new
Entry. Entry.
When the POST request contains an Atom Entry Document, the response When the POST request contains an Atom Entry Document, the response
from the server SHOULD contain a Content-Location header that from the server SHOULD contain a Content-Location header that
contains the same character-by-character value as the Location contains the same character-by-character value as the Location
skipping to change at page 24, line 38 skipping to change at page 24, line 40
as specified in [RFC2616]. For Media Resources, deletion of a Media as specified in [RFC2616]. For Media Resources, deletion of a Media
Link Entry SHOULD result in the deletion of the associated Media Link Entry SHOULD result in the deletion of the associated Media
Resource. Resource.
9.5 Media Resources and Media Link Entries 9.5 Media Resources and Media Link Entries
A client can POST a media type other than application/atom+xml to a A client can POST a media type other than application/atom+xml to a
Collection. Such a request creates two new resources - one that Collection. Such a request creates two new resources - one that
corresponds to the entity sent in the request, called the Media corresponds to the entity sent in the request, called the Media
Resource, and an associated Member Entry, called the Media Link Resource, and an associated Member Entry, called the Media Link
Entry. The server can signal the media types it will accept via the Entry. Media Link Entries are represented as Atom Entries. The
"accept" element in the Service Document (Section 8.2.4). server can signal the media types it will accept via the "accept"
element in the Service Document (Section 8.2.4).
The Media Link Entry contains the IRI of the Media Resource and makes The Media Link Entry contains the IRI of the Media Resource and makes
metadata about it separately available for retrieval and update. The metadata about it separately available for retrieval and update. The
Media Link Entry is used to store metadata about the (perhaps non- Media Link Entry is used to store metadata about the (perhaps non-
textual) Media Resource. textual) Media Resource.
Successful responses to creation requests MUST include the URI of the Successful responses to creation requests MUST include the URI of the
Media Link Entry in the Location header. The Media Link Entry SHOULD Media Link Entry in the Location header. The Media Link Entry SHOULD
contain an atom:link element with a link relation of "edit-media" contain an atom:link element with a link relation of "edit-media"
that contains the Media Resource IRI. The Media Link Entry MUST have that contains the Media Resource IRI. The Media Link Entry MUST have
skipping to change at page 25, line 29 skipping to change at page 25, line 33
POST body has an Atom Entry entity declared as an Atom media type POST body has an Atom Entry entity declared as an Atom media type
("application/atom+xml"), or a non-Atom entity declared as a non-Atom ("application/atom+xml"), or a non-Atom entity declared as a non-Atom
media type. It does not specify any request semantics or server media type. It does not specify any request semantics or server
behavior in the case where the POSTed media-type is "application/ behavior in the case where the POSTed media-type is "application/
atom+xml" but the body is something other than an Atom Entry. In atom+xml" but the body is something other than an Atom Entry. In
particular, what happens on POSTing an Atom Feed Document to a particular, what happens on POSTing an Atom Feed Document to a
Collection using the "application/atom+xml" media type is undefined. Collection using the "application/atom+xml" media type is undefined.
9.6 The Slug: Header 9.6 The Slug: Header
Slug is a HTTP entity-header whose value is a "slug", i.e. a short Slug is a HTTP entity-header whose value is a "slug" - a short name
name that can be used as part of URI for a Member Resource. that can be used as part of the URI for a Member Resource.
When posting an entity to a Collection to add a new Member, the 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 server MAY use this information when creating the Member URI of the
newly-created resource, for instance by using some or all 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 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.). atom:id or as the title of a Media Link Entry (see Section 9.5.).
Servers MAY ignore the Slug entity-header and MAY alter its value Servers MAY ignore the Slug entity-header and MAY alter its value
before using it. For example, the server MAY filter out some before using it. For example, the server MAY filter out some
characters or replace accented letters with non-accented ones, spaces characters or replace accented letters with non-accented ones, spaces
skipping to change at page 28, line 12 skipping to change at page 28, line 12
See Section 9.2.1 for an example of the Slug: header applied to the See Section 9.2.1 for an example of the Slug: header applied to the
creation of a Member Entry Resource. creation of a Member Entry Resource.
10. Listing Collections 10. Listing Collections
Collection resources MUST provide representations in the form of Atom Collection resources MUST provide representations in the form of Atom
Feed documents whose entries represent the Members in the Collection. Feed documents whose entries represent the Members in the Collection.
Each entry in the Feed Document SHOULD have an atom:link element with Each entry in the Feed Document SHOULD have an atom:link element with
a relation of "edit" (See Section 11.1). a relation of "edit" (See Section 11.1).
The entries in the returned Atom Feed MUST be ordered by their "atom: The entries in the returned Atom Feed SHOULD be ordered by their
updated" property, with the most recently updated entries coming "atom:updated" property, with the most recently updated entries
first in the document order. Clients SHOULD be constructed in coming first in the document order. Clients SHOULD be constructed in
consideration of the fact that changes which do not alter the atom: consideration of the fact that changes which do not alter the atom:
updated value of an entry will not affect the position of the entry updated value of an entry will not affect the position of the entry
in a Collection. in a Collection.
Clients MUST NOT assume that an Atom Entry returned in the Feed is a 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 full representation of a Member Entry Resource and SHOULD perform a
GET on the URI of the Member Entry before editing. GET on the URI of the Member Entry before editing.
10.1 Collection Paging 10.1 Collection Paging
skipping to change at page 28, line 36 skipping to change at page 28, line 36
such as a web spider or web browser could be overwhelmed if the 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 response to a GET contained every entry in the Collection, and the
server would waste large amounts of bandwidth and processing time on server would waste large amounts of bandwidth and processing time on
clients unable to handle the response. For this reason, servers MAY clients unable to handle the response. For this reason, servers MAY
return a partial listing of the most recently updated Member return a partial listing of the most recently updated Member
Resources. Such partial feed documents MUST have an atom:link with a Resources. Such partial feed documents MUST have an atom:link with a
"next" relation whose "href" value is the URI of the next partial "next" relation whose "href" value is the URI of the next partial
listing of the Collection (the next most recently updated Member listing of the Collection (the next most recently updated Member
Resources) where it exists. This is called "Collection paging". Resources) where it exists. This is called "Collection paging".
The returned Atom Feed MAY NOT contain entries for all the Members in The returned Atom Feed MAY contain a subset the Member Entries for a
a Collection. Instead, the Atom Feed document MAY contain link Collection. In addition, the Atom Feed document MAY contain link
elements with "rel" attribute values of "next", "previous", "first" elements with "rel" attribute values of "next", "previous", "first"
and "last" that can be used to navigate through the complete set of and "last" that can be used to navigate through the complete set of
matching entries. matching entries.
For instance, suppose a client is supplied the URI For instance, suppose a client is supplied the URI
"http://example.org/entries/go" of a Collection of Member entries, "http://example.org/entries/go" of a Collection of Member entries,
where the server as a matter of policy avoids generating feed where the server as a matter of policy avoids generating feed
documents containing more than 10 entries. The Atom Feed document documents containing more than 10 entries. The Atom Feed document
for the Collection will then represent the first 'page' in a set of for the Collection will then represent the first 'page' in a set of
10 linked feed documents. The "first" relation will reference the 10 linked feed documents. The "first" relation will reference the
skipping to change at page 30, line 5 skipping to change at page 29, line 30
href="http://example.org/entries/go" /> href="http://example.org/entries/go" />
<link rel="previous" <link rel="previous"
href="http://example.org/entries/go" /> href="http://example.org/entries/go" />
<link rel="next" <link rel="next"
href="http://example.org/entries/3" /> href="http://example.org/entries/3" />
<link rel="last" <link rel="last"
href="http://example.org/entries/10" /> href="http://example.org/entries/10" />
... ...
</feed> </feed>
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.
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 by any means.
11. Atom Format Link Relation Extensions 11. Atom Format Link Relation Extensions
11.1 The "edit" Link Relation 11.1 The "edit" Link Relation
This specification adds the value "edit" to the Atom Registry of Link This specification adds the value "edit" to the Atom Registry of Link
Relations (see section 7.1 of [RFC4287]). The value of "edit" Relations (see section 7.1 of [RFC4287]). The value of "edit"
specifies that the value of the href attribute is the IRI of an specifies that the value of the href attribute is the IRI of an
editable Member Entry. When appearing within an atom:entry, the href editable Member Entry. When appearing within an atom:entry, the href
IRI MAY be used to retrieve, update and delete the resource IRI can be used to retrieve, update and delete the resource
represented by that entry. An atom:entry MUST contain no more than represented by that entry. An atom:entry MUST contain no more than
one "edit" link relation. one "edit" link relation.
11.2 The "edit-media" Link Relation 11.2 The "edit-media" Link Relation
This specification adds the value "edit-media" to the Atom Registry This specification adds the value "edit-media" to the Atom Registry
of Link Relations (see section 7.1 of [RFC4287]). When appearing of Link Relations (see section 7.1 of [RFC4287]). When appearing
within an atom:entry, the value of the href attribute is an IRI that within an atom:entry, the value of the href attribute is an IRI that
MAY be used to modify a Media Resource associated with that entry. can be used to modify a Media Resource associated with that entry.
An atom:entry element MAY contain zero or more "edit-media" link An atom:entry element MAY contain zero or more "edit-media" link
relations. An atom:entry MUST NOT contain more than one atom:link relations. An atom:entry MUST NOT contain more than one atom:link
element with a rel attribute value of "edit-media" that has the same element with a rel attribute value of "edit-media" that has the same
type and hreflang attribute values. All "edit-media" link relations type and hreflang attribute values. All "edit-media" link relations
in the same entry reference the same resource. If a client in the same entry reference the same resource. If a client
encounters multiple "edit-media" link relations in an entry then it encounters multiple "edit-media" link relations in an entry then it
SHOULD choose a link based on the client preferences for type and SHOULD choose a link based on the client preferences for type and
hreflang. If a client encounters multiple "edit-media" link hreflang. If a client encounters multiple "edit-media" link
relations in an entry and has no preference based on the type and relations in an entry and has no preference based on the type and
skipping to change at page 31, line 34 skipping to change at page 31, line 34
The "app:control" element MAY appear as a child of an atom:entry The "app:control" element MAY appear as a child of an atom:entry
which is being created or updated via the Atom Publishing Protocol. which is being created or updated via the Atom Publishing Protocol.
The app:control element MUST appear only once in an Entry. The app: The app:control element MUST appear only once in an Entry. The app:
control element is considered foreign markup as defined in Section 6 control element is considered foreign markup as defined in Section 6
of [RFC4287]. of [RFC4287].
The app:control element and its child elements MAY be included in The app:control element and its child elements MAY be included in
Atom Feed or Entry Documents. Atom Feed or Entry Documents.
The app:control element MAY contain exactly one "app:draft" element The app:control element can contain an optional "app:draft" element
as defined below, and MAY contain zero or more extension elements as as defined below, and can contain extension elements as defined in
defined in Section 6 of [RFC4287]. Section 6 of [RFC4287].
12.1.1 The "app:draft" Element 12.1.1 The "app:draft" Element
The number of app:draft elements in app:control MUST be zero or one. 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 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 client request that the Member Resource be made publicly visible. If
the app:draft element is missing then the value MUST be understood to 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 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 by the client to control the visibility of a Member Resource and the
app:draft element MAY be ignored by the server. app:draft element MAY be ignored by the server.
13. Securing the Atom Protocol 13. Securing the Atom Publishing Protocol
All instances of publishing Atom Format entries SHOULD be protected The Atom Publishing Protocol is based on HTTP. Authentication
by authentication to prevent posting or editing by unknown sources. requirements for HTTP are covered in Section 11 of [RFC2616].
[[anchor23: note: this section is currently under discussion.]]
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,
however, in some contexts, this is an acceptable risk.
The type of authentication deployed is a local decision made by the
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
[RFC4346] as specified by [RFC2818].
The choice of authentication mechanism will impact interoperability.
The minimum level of security referenced above (Basic Auth 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 should, in general,
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].
14. Security Considerations 14. Security Considerations
The security of the Atom Protocol is based on [[anchor25: note: As an HTTP-based protocol, APP is subject to the security
refers to incomplete section]]. considerations found in Section 15 of [RFC2616].
[[anchor26: note: talk here about denial of service attacks using 14.1 Denial of Service
large XML files, or the billion laughs DTD attack.]]
Atom Publishing server implementations need to take adequate
precautions to ensure malicious clients cannot consume excessive
server resources (CPU, memory, disk, etc).
14.2 Replay Attacks
Atom Publishing server implementations are susceptible to replay
attacks. Specifically, this specification does not define a means of
detecting duplicate requests. Accidentally sent duplicate requests
are indistinguishable from intentional and malicious replay attacks.
14.3 Spoofing Attacks
Atom Publishing implementations are susceptible to a variety of
spoofing attacks. Malicious clients may send Atom entries containing
inaccurate information anywhere in the document.
14.4 Linked Resources
Atom Feed and Entry documents can contain XML External Entities as
defined in Section 4.2.2 of [W3C.REC-xml-20060816]. Atom
implementations are not required to load external entities. External
entities are subject to the same security concerns as any network
operation and can alter the semantics of an Atom document. The same
issues exist for resources linked to by Atom elements such as atom:
link and atom:content.
14.5 Digital Signatures and Encryption
Atom Entry Documents sent to a server might contain XML Digital
Signatures [W3C.REC-xmldsig-core-20020212] and might be encrypted
using XML Encryption [W3C.REC-xmlenc-core-20021210] as specified in
Section 5 of [RFC4287].
Servers are allowed to modify received resource representations in
ways that can invalidate signatures covering those representations.
14.6 URIs and IRIs
Atom Publishing Protocol implementations handle URIs and IRIs. See
Section 7 of [RFC3986] and Section 8 of [RFC3987].
15. IANA Considerations 15. IANA Considerations
15.1 Content-type registration for 'application/atomserv+xml' 15.1 Content-type registration for 'application/atomserv+xml'
An Atom Publishing Protocol Service Document, when serialized as XML An Atom Publishing Protocol Service Document, when serialized as XML
1.0, can be identified with the following media type: 1.0, can be identified with the following media type:
MIME media type name: application MIME media type name: application
skipping to change at page 34, line 28 skipping to change at page 34, line 28
Optional parameters: Optional parameters:
"charset": This parameter has identical semantics to the charset "charset": This parameter has identical semantics to the charset
parameter of the "application/xml" media type as specified in parameter of the "application/xml" media type as specified in
[RFC3023]. [RFC3023].
Encoding considerations: Identical to those of "application/xml" as Encoding considerations: Identical to those of "application/xml" as
described in [RFC3023], section 3.2. described in [RFC3023], section 3.2.
Security considerations: As defined in this specification. Security considerations: As defined in this specification.
[[anchor27: update upon publication]] [[anchor31: update upon publication]]
In addition, as this media type uses the "+xml" convention, it In addition, as this media type uses the "+xml" convention, it
shares the same security considerations as described in [RFC3023], shares the same security considerations as described in [RFC3023],
section 10. section 10.
Interoperability considerations: There are no known interoperability Interoperability considerations: There are no known interoperability
issues. issues.
Published specification: This specification. [[anchor28: update upon Published specification: This specification. [[anchor32: update upon
publication]] publication]]
Applications that use this media type: No known applications Applications that use this media type: No known applications
currently use this media type. currently use this media type.
Additional information: Additional information:
Magic number(s): As specified for "application/xml" in [RFC3023], Magic number(s): As specified for "application/xml" in [RFC3023],
section 3.2. section 3.2.
skipping to change at page 35, line 16 skipping to change at page 35, line 16
Base URI: As specified in [RFC3023], section 6. Base URI: As specified in [RFC3023], section 6.
Macintosh File Type code: TEXT Macintosh File Type code: TEXT
Person and email address to contact for further information: Joe Person and email address to contact for further information: Joe
Gregorio <joe@bitworking.org> Gregorio <joe@bitworking.org>
Intended usage: COMMON Intended usage: COMMON
Author/Change controller: This specification's author(s). [[anchor29: Author/Change controller: This specification's author(s). [[anchor33:
update upon publication]] update upon publication]]
15.2 Content-type registration for 'application/atomcat+xml' 15.2 Content-type registration for 'application/atomcat+xml'
An Atom Publishing Protocol Category Document, when serialized as XML An Atom Publishing Protocol Category Document, when serialized as XML
1.0, can be identified with the following media type: 1.0, can be identified with the following media type:
MIME media type name: application MIME media type name: application
MIME subtype name: atomcat+xml MIME subtype name: atomcat+xml
skipping to change at page 35, line 40 skipping to change at page 35, line 40
Optional parameters: Optional parameters:
"charset": This parameter has identical semantics to the charset "charset": This parameter has identical semantics to the charset
parameter of the "application/xml" media type as specified in parameter of the "application/xml" media type as specified in
[RFC3023]. [RFC3023].
Encoding considerations: Identical to those of "application/xml" as Encoding considerations: Identical to those of "application/xml" as
described in [RFC3023], section 3.2. described in [RFC3023], section 3.2.
Security considerations: As defined in this specification. Security considerations: As defined in this specification.
[[anchor30: update upon publication]] [[anchor34: update upon publication]]
In addition, as this media type uses the "+xml" convention, it In addition, as this media type uses the "+xml" convention, it
shares the same security considerations as described in [RFC3023], shares the same security considerations as described in [RFC3023],
section 10. section 10.
Interoperability considerations: There are no known interoperability Interoperability considerations: There are no known interoperability
issues. issues.
Published specification: This specification. [[anchor31: update upon Published specification: This specification. [[anchor35: update upon
publication]] publication]]
Applications that use this media type: No known applications Applications that use this media type: No known applications
currently use this media type. currently use this media type.
Additional information: Additional information:
Magic number(s): As specified for "application/xml" in [RFC3023], Magic number(s): As specified for "application/xml" in [RFC3023],
section 3.2. section 3.2.
skipping to change at page 36, line 30 skipping to change at page 36, line 30
Base URI: As specified in [RFC3023], section 6. Base URI: As specified in [RFC3023], section 6.
Macintosh File Type code: TEXT Macintosh File Type code: TEXT
Person and email address to contact for further information: Joe Person and email address to contact for further information: Joe
Gregorio <joe@bitworking.org> Gregorio <joe@bitworking.org>
Intended usage: COMMON Intended usage: COMMON
Author/Change controller: This specification's author(s). [[anchor32: Author/Change controller: This specification's author(s). [[anchor36:
update upon publication]] update upon publication]]
15.3 Header field registration for 'SLUG'
[[anchor37: incomplete section --dehora]]
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-11.txt
([[anchor38: update on rfc number assignment --dehora]])
Related information:
16. References 16. References
16.1 Normative References 16.1 Normative References
[RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
Part Three: Message Header Extensions for Non-ASCII Text", Part Three: Message Header Extensions for Non-ASCII Text",
RFC 2047, November 1996. RFC 2047, November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 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 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
Types", RFC 3023, January 2001. Types", RFC 3023, January 2001.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, January 2005. Identifiers (IRIs)", RFC 3987, January 2005.
[RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication
Format", RFC 4287, December 2005. Format", RFC 4287, December 2005.
[W3C.REC-xml-20040204] [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security
Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T., (TLS) Protocol Version 1.1", RFC 4346, April 2006.
and E. Maler, "Extensible Markup Language (XML) 1.0 (Third
Edition)", W3C REC REC-xml-20040204, February 2004. [W3C.REC-xml-20060816]
Bray, T., Paoli, J., Maler, E., Sperberg-McQueen, C., and
F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth
Edition)", World Wide Web Consortium Recommendation REC-
xml-20060816, August 2006.
[W3C.REC-xml-infoset-20040204] [W3C.REC-xml-infoset-20040204]
Cowan, J., Tobin, R., and A. Layman, "XML Information Set Cowan, J., Tobin, R., and A. Layman, "XML Information Set
(Second Edition)", W3C REC W3C.REC-xml-infoset-20040204, (Second Edition)", W3C REC W3C.REC-xml-infoset-20040204,
February 2004. February 2004.
[W3C.REC-xml-names-19990114] [W3C.REC-xml-names-20060816]
Hollander, D., Bray, T., and A. Layman, "Namespaces in Hollander, D., Bray, T., and A. Layman, "Namespaces in
XML", W3C REC REC-xml-names-19990114, January 1999. XML", World Wide Web Consortium Recommendation REC-xml-
names-20060816, August 2006.
[W3C.REC-xmlbase-20010627] [W3C.REC-xmlbase-20010627]
Marsh, J., "XML Base", W3C REC W3C.REC-xmlbase-20010627, Marsh, J., "XML Base", W3C REC W3C.REC-xmlbase-20010627,
June 2001. June 2001.
[W3C.REC-xmldsig-core-20020212]
Solo, D., Reagle, J., and D. Eastlake, "XML-Signature
Syntax and Processing", World Wide Web Consortium
Recommendation REC-xmldsig-core-20020212, February 2002,
<http://www.w3.org/TR/2002/REC-xmldsig-core-20020212>.
[W3C.REC-xmlenc-core-20021210]
Eastlake, D. and J. Reagle, "XML Encryption Syntax and
Processing", World Wide Web Consortium Recommendation REC-
xmlenc-core-20021210, December 2002,
<http://www.w3.org/TR/2002/REC-xmlenc-core-20021210>.
16.2 Informative References 16.2 Informative References
[RNC] Clark, J., "RELAX NG Compact Syntax", December 2001. [RNC] Clark, J., "RELAX NG Compact Syntax", December 2001.
[W3C.REC-webarch-20041215] [W3C.REC-webarch-20041215]
Walsh, N. and I. Jacobs, "Architecture of the World Wide Walsh, N. and I. Jacobs, "Architecture of the World Wide
Web, Volume One", W3C REC REC-webarch-20041215, Web, Volume One", W3C REC REC-webarch-20041215,
December 2004. December 2004.
URIs URIs
skipping to change at page 41, line 5 skipping to change at page 41, line 10
Phone: +353-1-4927444 Phone: +353-1-4927444
Email: bill.dehora@propylon.com Email: bill.dehora@propylon.com
URI: http://www.propylon.com/ URI: http://www.propylon.com/
Appendix A. Contributors Appendix A. Contributors
The content and concepts within are a product of the Atom community The content and concepts within are a product of the Atom community
and the Atompub Working Group. and the Atompub Working Group.
[[anchor42: chairs to compile a contribution list for 1.0 --dehora]]
Appendix B. RELAX NG Compact Schema Appendix B. RELAX NG Compact Schema
This appendix is informative. This appendix is informative.
The Relax NG schema explicitly excludes elements in the Atom Protocol The Relax NG schema explicitly excludes elements in the Atom Protocol
namespace which are not defined in this revision of the namespace which are not defined in this revision of the
specification. Requirements for Atom Protocol processors specification. Requirements for Atom Protocol processors
encountering such markup are given in Section 6.2 and Section 6.3 of encountering such markup are given in Section 6.2 and Section 6.3 of
[RFC4287]. [RFC4287].
skipping to change at page 42, line 18 skipping to change at page 43, line 18
appCommonAttributes, appCommonAttributes,
( appWorkspace+ ( appWorkspace+
& extensionElement* ) & extensionElement* )
} }
# app:workspace # app:workspace
appWorkspace = appWorkspace =
element app:workspace { element app:workspace {
appCommonAttributes, appCommonAttributes,
( appCollection* ( atomTitle
& appCollection*
& extensionElement* ) & extensionElement* )
} }
atomTitle = element atom:title { atomTextConstruct } atomTitle = element atom:title { atomTextConstruct }
# app:collection # app:collection
appCollection = appCollection =
element app:collection { element app:collection {
appCommonAttributes, appCommonAttributes,
attribute href { atomURI }, attribute href { atomURI },
( appAccept? ( atomTitle
& appAccept?
& appCategories* & appCategories*
& extensionElement* ) & extensionElement* )
} }
# app:categories # app:categories
atomCategory = atomCategory =
element atom:category { element atom:category {
atomCommonAttributes, atomCommonAttributes,
attribute term { text }, attribute term { text },
skipping to change at page 43, line 9 skipping to change at page 44, line 10
appInlineCategories = appInlineCategories =
element app:categories { element app:categories {
attribute fixed { "yes" | "no" }?, attribute fixed { "yes" | "no" }?,
attribute scheme { atomURI }?, attribute scheme { atomURI }?,
(atomCategory*) (atomCategory*)
} }
appOutOfLineCategories = appOutOfLineCategories =
element app:categories { element app:categories {
attribute href { atomURI }, attribute href { atomURI },
(empty) undefinedContent
} }
appCategories = appInlineCategories | appOutOfLineCategories appCategories = appInlineCategories | appOutOfLineCategories
# app:accept # app:accept
appAccept = appAccept =
element app:accept { element app:accept {
appCommonAttributes, appCommonAttributes,
( appTypeValue? ) ( appTypeValue? )
skipping to change at page 47, line 7 skipping to change at page 48, line 7
element * - atom:* { element * - atom:* {
(attribute * { text } (attribute * { text }
| text | text
| anyElement)* | anyElement)*
} }
# EOF # EOF
Appendix C. Revision History Appendix C. Revision History
draft-ietf-atompub-protocol-11: Parts of PaceAppEdited.
PaceSecurityConsiderationsRevised.
draft-ietf-atompub-protocol-10: PaceRemoveTitleHeader2, draft-ietf-atompub-protocol-10: PaceRemoveTitleHeader2,
PaceSlugHeader4, PaceOnlyMemberURI,PaceOneAppNamespaceOnly, PaceSlugHeader4, PaceOnlyMemberURI,PaceOneAppNamespaceOnly,
PaceAppCategories, PaceExtendIntrospection, PaceAppCategories, PaceExtendIntrospection,
UseElementsForAppCollectionTitles3, renamed Introspection to Service, UseElementsForAppCollectionTitles3, renamed Introspection to Service,
lots of good editorials suggestions, updated media example with slug, lots of good editorials suggestions, updated media example with slug,
moved xml conventions to convention sections, renamed XMl related moved xml conventions to convention sections, renamed XMl related
Conventions to Atom Publishing Protocol Documents, added auth header Conventions to Atom Publishing Protocol Documents, added auth header
to examples, consolidated definition of all resource types into the to examples, consolidated definition of all resource types into the
model section, added IANA reg info for application/atomcat+xml. model section, added IANA reg info for application/atomcat+xml.
 End of changes. 81 change blocks. 
157 lines changed or deleted 307 lines changed or added

This html diff was produced by rfcdiff 1.32. The latest version is available from http://www.levkowetz.com/ietf/tools/rfcdiff/