www.temple.edu

This is a protocol for editing web sites using HTTP and XML.

Discover

The user asks to edit a website, say http://example.org/blog/. You grab that web page. It should contain a link tag like:

<link rel="service.edit" type="application/x.atom+xml" href="http://example.org/blog/introspect.atom" title="AtomAPI" />

You grab introspect.atom. It should be an XML file like:

<introspection xmlns="http://purl.org/atom/introspect#"> 
  <create-entry>http://example.org/blog/</create-entry>
  <user-prefs>http://example.org/blog/prefs</user-prefs>
  <search-entries>http://example.org/blog/search</search-entries>
  <edit-template>http://example.org/blog/templates</edit-template>
  <categories>http://example.org/blog/categories</categories>
</introspection>

The URIs don’t have to be nice like this, they can be anything, include long CGI ones. Elements can be missing if they’re not implemented by the server

Editing

Create: To create an entry, POST an Atom entry element to the create-entry URI. <link/>, <id/>, <created/> and <modified/> MAY be filled in by the client and MUST be filled in by the server. (dump) The server should return 201 Created with a Location header pointing to the URI of the entry. (dump)

Retrieve: To retrieve an entry, simply GET the URI. (dump) The server should return an Atom entry element. (dump)

Edit: To edit an entry, simply PUT an updated entry to the URI. (dump) The server should return 205 Reset Content. (dump)

Delete: To delete an entry, simply DELETE the URI. (dump) The server should return 200 OK. (dump)

Finding

Entries can be found by appending various things to the search-entries URI and GETing the result. If search-entries already contains a “?”, replace the “?” with a “&” in all of the following. Append “?atom-all=1” to get all entries. Append “?atom-recent=” followed by a number N to get an abbreviate Atom feed element containing the N most recently modified entries. (dump) Append “?atom-start-range=”, a number N, “&atom-end-range=”, and a number M to get entries between the (N-1)th and the (M-1)th created (so that the first entry is 0).

It should return something like this:

<search-results xmlns="http://purl.org/atom/ns#">
  <entry>
    <title>My First Post</title>
    <id>http://example.org/blog/1</id>
  </entry>
  <entry>
    <title>My Second Post</title>
    <id>http://example.org/blog/2</id>
  </entry>
</search-results>

User Preferences

A user-prefs document looks like:

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

You can GET it and PUT it at the user-prefs URI.

Templates

At edit-template should be a file like this:

<resources xmlns="http://purl.org/atom/ns#">
  <resource>
    <title>Main</title>
    <id>http://example.org/tpl/Main.html</id> 
  </resource>
  <resource>
    <title>Story</title>
    <id>http://example.org/tpl/Stry.html</id>
  </resource> 
  <resource>
    <title>Feed</title>
    <id>http://example.org/tpl/Feed.xml</id> 
  </resource>
</resources>

You can GET and PUT any of the id URIs to edit that resource.

Comments

To comment on an entry you need its URI. This can be found two ways: in the <comment> element of an <entry> element and in a link tag on the entry’s web page. The link tag looks like this:

<link rel="service.comment" type="application/x.atom+xml" href="http://example.org/blog/1/comments" title="AtomComment" />

To add a comment, POST an <entry> element to the comment URI. (dump) The server should return 201 Created and MAY return a Location header pointing to the location of the comment as an editable entry (see section Editing, above).

Changes

Since -07: Updated namespace URIs. atom-last is now atom-recent.

[edit, permanent link to this version]