UserPreferences

PaceExamples05


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>

Impacts

Notes


CategoryProposals