Abstract
Add some exaples.
Status
Open (JoeGregorio)
Rationale
Proposal
Section 13 Examples
Section 13.1 Simple Create
Here is an example of creating a simple entry. In this example the
client begins with only the URI of the Entry Collection Resource, which is:
http://example.org/app/
The Entry that we wish to use to create a new resource with is:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<updated>2003-12-13T18:30:02Z</updated>
<summary>Some text.</summary>
<content type="xhtml" xml:lang="en"
xml:base="http://example.org/">
<div xmlns="http://www.w3.org/1999/xhtml">
<p><i>Film at eleven.</i></p>
</div>
</content>
</entry>
The client POSTs the Entry to the Collection Resource URI:
POST /app/ HTTP/1.1
Host: example.org
User-Agent: Cosimo/1.0
Accept: application/atom+xml
Content-Type: application/atom+xml
Content-Length: nnnn
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<updated>2003-12-13T18:30:02Z</updated>
<summary>Some text.</summary>
<content type="xhtml" xml:lang="en"
xml:base="http://example.org/">
<div xmlns="http://www.w3.org/1999/xhtml">
<p><i>Film at eleven.</i></p>
</div>
</content>
</entry>
If the resource is created successfully the response might be:
HTTP/1.1 201 Created
Date: Fri, 25 Mar 2005 17:17:11 GMT
Content-Length: 0
Location: http://example.org/app/876
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<updated>2003-12-13T18:30:02Z</updated>
<link rel="edit" href="http://example.org/app/876"/>
<summary>Some text.</summary>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-568596895695</id>
<content type="xhtml" xml:lang="en"
xml:base="http://example.org/">
<div xmlns="http://www.w3.org/1999/xhtml">
<p><i>Film at eleven.</i></p>
</div>
</content>
</entry>
Note that the Location: header gives the URI
of the newly created member resource.
Section 13.2 Resynchronization
Here is an example of a client requesting all the Entries that have changed
since the last time the client synchronized with the server. The last time
the client resynchronized from the server was 2003-12-13T18:30:02Z. The client
wishes to get all the entries that have been updated since that time. The server
returns the following representation for it's Collection Resource:
<?xml version="1.0" encoding="utf-8"?>
<collection xmlns="http://purl.org/atom/app/">
<member-type>entry</member-type>
<search-template>http://example.org/si/{index}</search-template>
<search-template>http://example.org/bydate.cgi?{daterange}</search-template>
</collection>
We are guaranteed to find at least one 'search-template' that allows us to search
by the 'updated' time. That URI in this case is:
http://example.org/bydate.cgi?{daterange}
We expand the URI Template with our search criteria, which is a query
for all entries modified from 2003-12-13T18:30:02Z to now. The URI
of that Search Resource is:
http://example.org/bydate.cgi?-2003-12-13T18:30:02Z
Remember that the first date in the date range is left empty if
we want all entries modified until now. The response will be an Atom
Feed of all the Entries that meet our criteria:
HTTP/1.1 200 OK
Date: Fri, 25 Mar 2005 17:15:33 GMT
Last-Modified: Sun, 28 Aug 2005 18:31:45 GMT
ETag: "23094-2349239-29348"
Content-Type: application/atom+xml; charset="utf-8"
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>Example Feed</title>
<link href="http://example.org/"/>
<updated>2005-08-28T18:30:02Z</updated>
<author>
<name>John Doe</name>
</author>
<id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
...
<entry>
<title>False Alarm on the Atom-Powered Robots Thing</title>
<link href="http://example.org/2003/12/13/atom-powered-robot-retraction.html"/>
<link rel="edit" href="http://example.org/app/877"/>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-498593458954</id>
<updated>2003-12-14T07:59:34Z</updated>
<summary>Ooops</summary>
<content type="xhtml" xml:lang="en"
xml:base="http://example.org/">
<div xmlns="http://www.w3.org/1999/xhtml">
<p><i>What can I say, the Atom menace
never materialized.</i></p>
</div>
</content>
</entry>
<entry>
<title>Atom-Powered Robots Run Amok</title>
<link href="http://example.org/2003/12/13/atom-powered-robots-run-amok.html"/>
<link rel="edit" href="http://example.org/app/876"/>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2003-12-13T18:30:02Z</updated>
<summary>Some text.</summary>
<content type="xhtml" xml:lang="en"
xml:base="http://example.org/">
<div xmlns="http://www.w3.org/1999/xhtml">
<p><i>Film at eleven.</i></p>
</div>
</content>
</entry>
</feed>
Section 13.3 Compound Entry
An example of creating a new entry with an inline image. That is, the client
has an image it must publish and an entry that includes an HTML
'img' element that uses that image. In this scenario we consider
a client that has URIs of two Collection Resources. The first collection
handles only entries. The URI of the first collection
is:
http://example.net/blog/edit/
and it has a Collection representation of:
<?xml version="1.0" encoding="utf-8"?>
<collection xmlns="http://purl.org/atom/app/">
<member-type>entry</member-type>
<search-template>http://example.net/blog/edit/{index}</search-template>
<search-template>http://example.net/blog/edit/{daterange}</search-template>
</collection>
The second collection is a Generic Collection and is has
a URI:
http://example.net/binary/edit
and has a Collection representation of:
<?xml version="1.0" encoding="utf-8"?>
<collection xmlns="http://purl.org/atom/app/">
<member-type>generic</member-type>
<search-template>http://example.net/binary/edit/{index}</search-template>
<search-template>http://example.net/binary/edit/{daterange}</search-template>
</collection>
First the client uploads the image by POSTing to the
URI of the Generic Collection.
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...
Which returns a 201 on success
HTTP/1.1 201 Created
Date: Fri, 25 Mar 2005 17:17:11 GMT
Content-Length: 0
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="srcedit" 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>
Now the last step for the client is to POST the Atom Entry that
refers to the newly created image resource to the first
Collection Resource. Note that the client takes the URI
http://example.net/binary/readonly/129.png and uses it in
the 'img' element in the Entry:
POST /blog/edit/ HTTP/1.1
Host: example.net
User-Agent: Thingio/1.0
Accept: application/atom+xml
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>
<updated>2005-09-02T10:30:00Z</updated>
<summary>Beach!</summary>
<content type="xhtml" xml:lang="en"
xml:base="http://example.org/">
<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>
