Note that this pulls ideas from many of the recent paces and list
discussion and incorporates a few new ideas as well. Head nods in
particular to contributions from Joe G., Robert S., and Luke A.
Now, I would not dream of proposing this significant of a change
this late in the game unless I felt there was significant benefit
in doing so. I've gone through and implemented this as an
experiment to compare against my -06 implementation and have been
able to realize a significantly less complicated implementation.
It also takes significantly less effort to explain ;-). I believe
the operative term is "Radical simplification".
If the WG desires, I can split this up into individual paces but I
would like y'all to at least consider it as a coherent chunk,
Change summary:
1. Drops introspection documents. Get on Collection URI returns an
Atom feed containing a server-defined subset of entries.
Introspection doc can be defined in a separate I-D.
2. The Atom feed returned by the collection MAY contain an
app:member-type element.
3. The Atom feed returned by the collection MAY contain an app:list-
template element to allow for client-defined subsets
4. All Collections are media collections by default. Servers MAY
choose to limit the membership to specific types. This eliminates
the need to explicitly distinguish media collections, greatly
simplifying the overall model. Entry collections are Media
collections whose content is limited to Atom Entry Documents.
5. Clients may post anything to the server. The server accepts and
rejecrs whatever it wishes. The protocol is no more concerned
about whether valid atom:entry representations are posted as it is
about whether valid PNG files are posted. The server is
responsible for taking whatever is posted (and accepted) and
creating an appropriate member resource based on the input. For
the core protocol, it does not matter who generates atom:id or
whether atom:author is present, etc. Interestingly, this also gives
us a degree of backwards-compatibility with current AtomAPI
(gregorio-09) implementations and would allow servers to do things
like creating member entries in response to trackback pings and
HTML form submissions.
6. The metadata for a media resource can be updated by doing a POST
against the member resource IRI. This allows for setting/changing
things like the title and summary of a PNG, for instance. use of
the the Title HTTP header is dropped.
So, when I have an Entry Collection URI, and GET it, what I receive
is:
<feed>
...
<app:member-type>entry</app:member-type>
<app:list-template>http://.../{index}</app:list-template>
...
<!-- server defined subset of entries -->
</feed>
Anyway, I'd appreciate your comments|concerns|suggestions
====================================================================
1. Introduction
The Atom Publishing Protocol is an application-level
protocol for publishing and editing Web resources
using HTTP and XML 1.0.
1.1 Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
Note: This specification mentions the use of IRIs [RFC3987], as
well as
URIs [RFC3986]. Every URI is an IRI, so any URI can be used where
an IRI
is needed. How to map an IRI to a URI is specified in Section 3.1 of
Internationalized Resource Identifiers (IRIs) [RFC3987].
The XML elements defined in this specification are specified in
terms of
the XML Information Set, serialised as XML 1.0 [W3C.REC-xml-20040204].
This specification does not define any DTDs for Atom Protocol, and
hence
does not require them to be valid (in the sense used by XML).
This specification uses a shorthand for two common terms: the phrase
"Information Item" is omitted when naming Element Information Items
and
Attribute Information Items. Therefore, when this specification
uses the
term "element," it is referring to an Element Information Item in
Infoset terms. Likewise, when it uses the term "attribute," it is
referring to an Attribute Information Item.
The namespace URI [W3C.REC-xml-names-19990114] for the elements
described in this specification is:
http://purl.org/atom/app#
This specification uses the prefix "app:" for the namespace URI. The
choice of namespace prefix is not semantically significant.
This specification also uses the prefix "atom:" for the namespace URI
"http://www.w3.org/2005/Atom"; specified in [AtomFormat].
Some sections of this specification are illustrated with fragments of
a non-normative RELAX NG Compact schema [RNC]. However, the text of
this specification provides the definition of conformance. A complete
schema appears in Appendix __.
1.2 Terminology
For convenience, this protocol may be referred to as "Atom
Protocol" or
"APP".
URI/IRI - A Uniform Resource Identifier and Internationalized Resource
Identifier, respectively. These terms (and the distinction between
them)
are defined in [RFC3986] and [RFC3987].
resource - A network data object or service that can be identified
by a
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 IRIs, as
described
in Section 8 of this specification.
member - A resource whose IRI is listed in a collection.
2. Protocol Model
The Atom Publishing Protocol uses HTTP methods to manipulate
collections of editable Web resources.
APP Collections contain the IRI's and descriptive metadata for zero
or more member resources and are responsible for the creation of
new member resources.
APP Collections are themselves Web resources identified by an IRI
that MUST be resolvable into an HTTP URL. In response to
Collection HTTP GET requests sent to the Collection IRI, Collection
resources SHOULD return an Atom Feed Document containing a list of
atom:entry elements representative of member resources. Because
Collections may contain extremely large numbers of resources, a
naive client could become overwhelmed if the returned Atom Feed
Document contained an atom:entry for every member of the
Collection, and the server would waste large amounts of bandwidth
and processing time on clients incapable of handling the response.
As a result, the Atom Feed Document returned in response to a
simple GET request on the Collection IRI MAY represent a server-
determined subset of the collection membership.
While each of the atom:entry elements contained in the Atom Feed
Document returned by the Collection is representative of a single
member resource, those entries MUST NOT be considered editable
representations of the member resource.
Each member resource contained by a collection is associated with
an IRI that MUST be resolvable into an HTTP URL. Each atom:entry
contained in the Atom Feed Document returned by the Collection
resource MUST contain one atom:link element with a rel attribute
value of "edit" whose href attribute specifies the IRI of the
member resource.
Clients retrieve an editable representation of a member resource by
sending an HTTP GET request to the IRI of the member resource.
Clients submit updates to member resources by sending an HTTP PUT
request to the IRI of the member resource containing the updated
representation of the resource.
Clients may append or modify metadata associated with a member
resource by sending an HTTP POST request to the IRI of the resource.
Clients remove member resources by sending an HTTP DELETE request
to the IRI of the member resource.
Clients may request the creation of a new member resource by
POSTing a representation of the new member resource to the
Collection resource's IRI.
3. Protocol Operations
3.1 Retrieving a list of member resources
Client Server
| |
| 1) GET to Collection IRI |
|------------------------------->|
| |
| 2) Atom Feed Document |
|<-------------------------------|
| |
1. The client sends a GET request to the
IRI of the Collection resource
2. The server responds with an Atom Feed
Document containing a set of entries
representative of a server-defined
subset of member resources.
3.2 Creating a member resource
Client Server
| |
| 1) POST to Collection IRI |
|------------------------------->|
| |
| 2) 201 Created |
|<-------------------------------|
| |
1. The client POSTs a representation
of the resource to the IRI of the
Collection resource
2. If the member resource was created
successfully, the server MAY respond
with a status code of either 201
("Created") or 303 ("See Other").
3.3 Retrieving an editable representation of a member
resource
Client Server
| |
| 1) GET to Member Resource IRI |
|------------------------------->|
| |
| 2) Member Representation |
|<-------------------------------|
| |
1. The client sends a GET request to the
IRI of the member resource
2. The server responds with an editable
representations of the resource.
3.4 Updating a Resource
Client Server
| |
| 1) PUT to Member Resource IRI |
|------------------------------->|
| |
| 2) 200 OK |
|<-------------------------------|
| |
1. The client PUTs an updated representation
to the IRI of the member resource
2. Upon a successful update of the resource,
the server responds with a status code of
200.
3.5 Appending metadata to a resource
Client Server
| |
| 1) POST to Member Resource IRI |
|------------------------------->|
| |
| 2) 200 OK |
|<-------------------------------|
| |
1. The client POSTs a representation
of the metadata to append to the
IRI of the member resource
2. Upon successful processing of the
append operation, the server responds
with a status code of either a 200 ("OK")
or 204 ("No Content").
3.6 Deleting a Resource
Client Server
| |
| 1) DELETE to Member Resource IRI |
|--------------------------------->|
| |
| 2) 200 OK |
|<---------------------------------|
| |
1. The client sends a DELETE request to the
IRI of the member resource.
2. Upon the successful deletion of the resource,
the server responds with a status code of 200.
3.7 HTTP Status Codes
APP uses the HTTP defined response status codes to indicate the
success or failure of an operation. Consult the HTTP specification
[RFC2616] for detailed definitions of each status code. It is
strongly recommended that entities contained within HTTP 4xx and
5xx responses include a human readable, natural language
explanation of the error.
4 Collection Membership
APP Collection resources MAY choose to constrain the types of
member resources that may be contained within the collection.
4.1 The 'app:member-type' extension element
Atom Feed Documents returned by Collection resources MAY contain
one 'app:member-type' elements whose content value specifies the
type of member resources contained by the collection. The
'app:member-type' extension MUST only appear as a child of the
atom:feed element.
appMemberType = element app:member-type {
appCommonAttributes,
( 'entry' | extensionType )
}
extensionType = ( NMTOKEN | IRI | media-type)
<feed xmlns="http://www.w3.org/2005/Atom";>
...
<app:member-type>entry</app:member-type>
</feed>
This specification defines the app:member-type value 'entry' to
indicate a collection whose member resources consist entirely of
Atom Entry Documents.
If the 'app:member-type' element is not specified, the membership
type of a Collection is considered to be unspecified.
If the 'app:member-type' element specifies a value that is not
understood by the client, the client MUST ignore the 'app:member-
type' and continue to operate as if the element were not specified.
If a client sends a POST or PUT request to the server containing a
representation not supported by the Collection resource, the server
MAY return a status code of 415 ("Unsupported Media Type").
5 Listing Collection Members
The Atom Feed Document returned by the Collection Resource in
response to a simple GET request against the Collection's IRI MAY
contain a set of atom:entry elements representative of server-
defined subset of member resources. Typically, this subset will
represent the most recently modified members of the collection
ordered such that the most recently modified member is presented
first.
5.1 List Templates
The Collection resource MAY choose to provide clients with an
alternative method of retrieving Atom Feed Documents containing
client-defined subsets of member resources by including one
'app:list-template' extension element within the Atom Feed Document
returned by the Collection resource.
The content value the 'app:list-template' element specifies an IRI
template as defined in Section 6 that may be processed to produce
an IRI resolvable into an HTTP URL. Clients may then perform a GET
against the produced IRI to retrieve an Atom Feed Document
representing the subset of member resources specified by the IRI.
appListTemplate = element app:list-template {
appCommonAttributes,
( appIriTemplate )
}
<feed xmlns="http://www.w3.org/2005/Atom";>
...
<app:list-template>http://example.org/{index}</app:list-template>
</feed>
6. IRI Templates
An IRI Template is a string containing zero or more embedded tokens
that when processed will produce a syntactically valid IRI that is
resolvable to an HTTP URL.
appIriTemplate = xsd:string { pattern = ".+\{.+\}.*" }
Processing an IRI Template involves substituting each contained
token with a value representation appropriate for the token.
This specification defines the token "{index}" to represent a pair
of non-negative integer indices separated by a dash character, e.g.
0-10. The index values are 0 based and select members from the
collection based on the member's index, with the set of members
ordered in reverse chronological order according to the value of
their atom:updated property (most recently updated member first).
The specified range is considered to be a closed set -- if an entry
matches one of the range exactly it MUST be included in the
response. If no members fall within the specified range, the
server MUST respond with an Atom Feed containing no entries
For example, suppose the client is supplied this IRI template:
http://example.org/blog/entries/{index}
If the client wishes to retrieve a listing of the 15 most recently
updated entries in the collection, it would substitute the brace
delimited token {index} with the value 0-14, producing:
http://example.org/blog/entries/0-14
IRI Templates containing tokens not understood by the client MUST
be ignored.
7. Atom Entry Extensions
... (app:control) ...
8. Example
...
9. Security Considerations
...
10. IANA Considerations
...
11. References
...
