Hey all,
Over the past couple of weeks we've been kicking around the -06 draft
and have seen a significant amount of spirited discussion and new Paces.
As I've been following the discussions, I've had a recurring and
nagging feeling that we this stuff could stand a drastic and radical
simplification. Unfortunately, it's not particularly easy to describe
what I have in mind in a series of individual paces so I've decided to
draft up my ideas as a single chunk included below.
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
...
