Here is a pace that expresses a protocol model without
collections. It would shorten the draft a bit.
This is my first crack at this so the language probably
needs lots of work. I am sure there are also glaring
omissions.
The pace is long but the change effected language
throughout the draft. Though alterations may seem
drastic in some respects, note that the cat picture
example required almost no change.
There may be pieces of this that could be split out.
I would have put this on the wiki but the wiki is still
having problems.
- Luke
== Abstract ==
Decouple resource discovery from resource creation.
== Status ==
Open
== Rationale ==
Creating and discovering resources are two distinct operations. The
current protocol model conflates the two using the metaphor of a
"collection". This is confusing as the behavior of implementations
will often be quite different from that of a set of physical
collections.
Perhaps even more importantly, the protocol is easier to explain in a
more literal fashion. For instance, we can simply write about "a
representation" rather than "a member representation".
== Proposal ==
Replace section 1 with:
{{{
1. Introduction
The Atom Publishing Protocol is an application-level protocol for
publishing and editing Web resources using HTTP [RFC2616] and XML 1.0
[W3C.REC-xml-20040204]. The protocol provides facilities for
discovering, creating, reading, updating and deleting resources.
}}}
Remove from section 2:
{{{
The Introspection Document allows the use of IRIs [RFC3987], as well
as URIs [RFC3986].
}}}
Remove from section 3:
{{{
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.
IRI template - A parameterized string that becomes a IRI when the
parameters are filled in. See Section 9.
introspection document - A document that describes the location and
capabilities of one or more collections. See Section 7
}}}
Add to section 3:
{{{
feed link - an Atom or HTML link element whose rel attribute value
is 'feed'
edit link - an Atom or HTML link element whose rel attribute value
is 'edit'
alternate link - an Atom or HTML link element whose rel attribute
value is 'alternate'
next link - an Atom or HTML link element whose rel attribute value is
'next'
prev link - an Atom or HTML link element whose rel attribute value is
'prev'
start link - an Atom or HTML link element whose rel attribute value
is 'start'
end link - an Atom or HTML link element whose rel attribute value is
'end'
entrypost link - an Atom or HTML link element whose rel attribute
value is 'entrypost
mediapost link - an Atom or HTML link element whose rel attribute
value is 'mediapost'
editable - an editable representation is one that actors might be
allowed to edit but editing of any representation can be disallowed
by implementers.
}}}
Replace section 4 with:
{{{
4. Protocol Model
The Atom Publishing Protocol uses HTTP to edit resources on the web.
Atom Feed Documents are used to list entry resources. Atom Entry
Documents are used to represent entry resources. The APP uses these
HTTP verbs:
o GET is used to retrieve a representation of a resource.
o POST is used to create a new resource.
o PUT is used to update a known resource.
o DELETE is used to remove a resource.
The protocol allows editing of resources with representations of any
media-type.
}}}
Replace section 5 with two sections:
{{{
5. Discovering Resources
Atom Feeds are used to discover the IRIs and other metadata of
various resources.
Client Server
| |
| 1.) GET |
|------------------------------->|
| |
| 2.) 200 OK, Atom Feed Doc |
|<-------------------------------|
| |
1. The client sends a GET request to a known IRI.
2. The server responds with an Atom Feed Document containing the
IRIs and other metadata of various resources.
The methods of identifying the IRIs of resources are detailed in
sections 5.1 - 5.5.
5.1 Feeds
The IRIs of Atom Feeds are found in the href attributes of feed links
(see section 3).
5.1.1 Paging
Feeds can be extremely large. A naive client such as a web spider or
web browser would be overwhelmed if the response to a GET contained
every entry in the feed, and the server would waste large amounts of
bandwidth and processing time on clients unable to handle the
response.
To cope with this, a feed can be represented by a series of Atom Feed
Documents connected together using next links, prev links, start
links and end links.
5.2 Entries
The IRI of the source (editable) Atom Entry Document representation
can be found in the href attribute of an edit link (see section 3).
The IRIs of other (derived) representations can be found in the
href attributes of alternate links.
5.3 Media
The IRI of an editable representation that may be of any media type
can be found in the src attribute of an atom content element.
5.4 Entry Post
IRIs used to create resources by POSTing Atom Entry Documents can be
found in the href attributes of entrypost links (see section 3).
5.5 Media Post
IRIs used to create resources by POSTing representations of any media
type can be found in the href attributes of mediapost links (see
section 3).
6. Protocol Operations
6.1 Creating a Resource
Client Server
| |
| 1.) POST |
|------------------------------------------>|
| |
| 2.) 201 Created |
|<------------------------------------------|
| |
1. The client POSTs a representation.
2. If the resource was created successfully the server responds with
a status code of 201 and a Location: header that contains the IRI
of the newly created resource.
6.1.1 Creating a Resource via Entry Post
If the representation was POSTed to an entry post (see section 5.1.4)
the IRI returned is that of the editable Atom Entry Document.
6.1.2 Creating a Resource via Media Post
If the representation was POSTed to a media post (see section 5.1.5)
the IRI returned will be that of a representation of the same type
POSTed.
6.2 Reading a Resource
Client Server
| |
| 1.) GET |
|------------------------------------------>|
| |
| 2.) Representation |
|<------------------------------------------|
| |
1. The client sends a GET request to a known IRI to retrieve
a representation of a resource.
2. The server responds with the representation of the resource.
6.3 Updating a Resource
Client Server
| |
| 1.) PUT |
|------------------------------------------>|
| |
| 2.) 200 OK |
|<------------------------------------------|
1. The client PUTs an updated representation to a known IRI.
2. Upon a successful update of the resource the server responds with
a status code of 200.
6.4 Deleting a Resource
Client Server
| |
| 1.) DELETE |
|------------------------------------------>|
| |
| 2.) 200 Ok |
|<------------------------------------------|
| |
1. The client sends a DELETE request to a known IRI.
2. Upon the successful deletion of the resource the server responds
with a status code of 200.
6.5 Success and Failure
The Atom Protocol uses HTTP status codes to signal the results of
protocol operations. Status codes of the form 2xx signal that a
request was successful. HTTP status codes of the form 4xx or 5xx
signal that an error has occurred. Consult the HTTP specification
[RFC2616] for the definitions of HTTP status codes.
}}}
Remove sections 7, 8, and 9
Rename section 6 as section 7
Renumber subsequent sections.
Replace the text at the beginning of section 10:
{{{
10. Atom Entry Extensions
This specification adds two new values to the Registry of Link
Relations and adds a new element to Atom Entries called "app:control"
for controlling publishing.
}}}
Replace section 10.1
{{{
10.1 The 'edit' Link Relation
This specification adds the value "edit" to the Registry of Link
Relations. The value of "edit" signifies that the IRI in the value
of the href attribute is the IRI of the resource, and is intended to
be used to update and delete resources as described in section 6.
}}}
Add the following subsection to section 10:
{{{
10.2 The 'feed' Link Relation
This specification adds the value "feed" to the Registry of Link
Relations. The value of "feed" signifies that the IRI in the value
of the href attribute is the IRI of a feed resource, and is intended
to be used to discover resources as described section 5.
}}}
Renumber remaining subsections of section 10.
Renumber section 10 to section 8
Replace section 11:
{{{
11. Example
This is an example of a client creating a new entry with an image.
The client has an image to publish and an entry that includes an HTML
'img' element that uses that image. In this scenario we consider a
client that has the IRIs of both an entry post and a media post. (see
section 5) The IRI of the entry post is:
http://example.net/blog/edit/
The IRI of the media post is:
http://example.net/binary/edit
First the client creates a new image resource by POSTing the image to
the IRI of the media post.
POST /binary/edit/ HTTP/1.1
Host: example.net
User-Agent: Thingio/1.0
Content-Type: image/png
Content-Length: nnnn
Title: A picture of the beach
...binary data...
The resource is created and an HTTP status code of 201 is returned.
HTTP/1.1 201 Created
Date: Fri, 25 Mar 2005 17:17:11 GMT
Content-Length: nnnn
Content-Type: application/atom+xml
Location: http://example.net/binary/edit/b/129.png
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom";>
<title>A picture of the beach.</title>
<link rel="edit"
href="http://example.net/binary/edit/b/129.png"/>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-568596895695</id>
<updated>2005-09-02T10:30:00Z</updated>
<summary>Waves</summary>
<content type="image/png"
src="http://example.net/binary/readonly/129.png"/>
</entry>
The client then POSTs the Atom Entry that refers to the newly created
image resource. Note that the client takes the IRI
http://example.net/binary/readonly/129.png and uses it in the 'img'
element in the Entry content:
POST /blog/edit/ HTTP/1.1
Host: example.net
User-Agent: Thingio/1.0
Content-Type: application/atom+xml
Content-Length: nnnn
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom";>
<title>What I did on my summer vacation</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-568599874695</id>
<updated>2005-09-02T10:30:00Z</updated>
<summary>Beach!</summary>
<content type="xhtml" xml:lang="en">
<div xmlns="http://www.w3.org/1999/xhtml";>
<p>We went to the beach for summer vacation.
Here is a picture of the waves rolling in:
<img
src="http://example.net/binary/readonly/129.png";
alt="A picture of the beach."
/>
</p>
</div>
</content>
</entry>
}}}
Renumber section 11 as section 9 and renumber remaining sections.
== Impacts ==
draft06
== Notes ==
----
CategoryProposals
![http://example.net/binary/edit/b/129.png"/](http://example.net/binary/edit/b/129.png"/){kind=link}
![http://example.net/binary/readonly/129.png"/](http://example.net/binary/readonly/129.png"/){kind=link}
![http://example.net/binary/readonly/129.png"](http://example.net/binary/readonly/129.png"){kind=link}