BitWorking

AtomAPI URIs

The URIs in the draft AtomAPI RFC are not normative, they are examples. The draft RFC isn't about specifying the form of the URLs that are to be used. Yes, there are guidelines you should follow when creating URIs, but those are just general guidelines. That is an important document and if you're creating server side software you should know it already.

Updated: Now includes the template editing facet.

In the end, it's the server that controls the URI space for that domain. Now, for convenience that space may be mapped to a file system hierarchy, but again, there's no requirement for that to be true. So what does the RFC specify? It lays out the formats of the files that can be returned, and the actions that can be performed on the URIs. Note that URIs are embedded in some of those formats. That embedding, that intertwingling of format and URI, is the crux of hypertext, and we are using HTTP as our protocol, the Hypertext Transfer Protocol. Here then is an abbreviated description of the AtomAPI as it stands today, with all the example URIs contracted into short names.

URI HTTP Verbs Format Return values
introspectionURI GET Introspection
createURI POST AtomEntry returns an entryURI in the Location: header.
prefsURI GET, PUT Preferences
entryURI GET, PUT, DELETE AtomEntry
searchURI GET SearchResults
commentURI POST AtomEntry returns an entryURI in the Location: header.
findTemplateURI GET FindTemplate
templateURI GET, PUT any

Introspection

<introspection xmlns="http://example.com/newformat#" > 
  <create-entry>createURI</create-entry>
  <user-prefs>prefsURI</user-prefs>
  <search-entries>searchURI</search-entries>
  <edit-template>templateURI</edit-template>
</introspection>

SearchResults

<search-results xmlns="http://example.com/newformat#" > 
  <match title="My First Post">entryURI</match>
  <match title="My Second Post">entryURI</match>
</search-results>

FindTemplates

<templates xmlns="http://example.com/newformat#" >
 <template title="Main">templateURI</template> 
 <template title="Story">templateURI</template> 
 <template title="Feed">templateURI</template> 
</templates>

Preferences

<userprefs xmlns="http://example.com/newformat#" > 
   <name>Reilly</name>
   <id>1234</id>
   <email>reilly@example.org</email>
</userprefs>

AtomEntry

<entry xmlns="http://example.com/newformat#" >  
    <title>My First Entry</title> 
    <subtitle>In which a newbie learns to blog...</subtitle> 
    <summary>A very boring entry...</summary> 
 
    <author> 
      <name>Bob B. Bobbington</name> 
      <homepage>http://bob.name/</homepage> 
      <weblog>http://bob.blog/</weblog> 
    </author> 

    <issued>2003-02-05T12:29:29</issued> 
    <created>2003-02-05T14:10:58Z</created> 
    <modified>2003-02-05T14:10:58Z</modified> 
    
    <link>http://example.org/reilly/2003/02/05#My_First_Entry</link>
    <id>urn:example.org:reilly:1</id>
 
    <content type="application/xhtml+xml" xml:lang="en-us"> 
      <p xmlns="...">Hello, <em>weblog</em> world! 2 < 4!</p> 
    </content>  
</entry> 
the result of FindTemplate appears to have changed from draft 0.6 to 0.7 but you haven't updated this page.  Likewise for Entry SearchResults.  Thank you for maintaining all this information.

Posted by Lance Lavandowska on 2003-08-29

2003-07-29