The AtomAPI

When editing the content of the website http://example.org/reilly, the first thing to do is find out the servers capabilites. Each server may only implement a subset of this specification, and the 'introspection' file lists all the functions that each site supports. This mirrors the Server Introspection API used by the Blogger 2.0 API.

http://example.org/reilly/

http://example.org/reilly/prefs

http://example.org/reilly/search

]]>

Each element in <introspection> represents a single facet of the AtomAPI. While a site must fully support each facet they list in their introspection file, a site does not need to support all the facets in this RFC. Additionally, new facets may be added either through vendor extension or follow-on RFCs. This first example site furnishes only a minimal set of functionality. A more full featured site might return:

http://example.org/reilly/

http://example.org/reilly/prefs

http://example.org/reilly/search

http://example.org/reilly/templates

http://example.org/reilly/categories ]]> This particular introspection file for http://example.org/reilly tells us that the AtomAPI implementation supports both the 'create-entry' and the 'user-prefs' interfaces, and it also specifies the URIs to use for each of these interfaces. Note that the example URIs given are not normative, nor are there any constraints on the URIs that can be specified. The 'create-entry' URI could just have easily been:

The <link> element has been successful in finding RSS feeds and is appropriate to use here for discovering the location of the Introspection file. The <link> tag goes in the <head> section of an HTML page and is used to indicate a document relationship. For a similar example of using the link tag to discover a URI, refer to the usage of of the link tag for RSS Auto-Discovery. In this case the form of the link tag used to indicate the location of the comment URI is:

]]> Where href should be set to the URI of the Introspection file. Applications looking for the Introspection file to need to parse out the headers of the web page and look for a link tag that has a relation rel of "service.edit" and a mime-type of "application/x.atom+xml".

HTTP POST is used for content creation. The new content is formatted as an Atom Entry and then POSTed to the URI given in the <create-entry/> element of the Introspection file.

To create a new Entry on the site the client connects to port 80 on http://example.org and sends: My First Entry

A very boring entry...

Bob B. Bobbington 2003-02-05T12:29:29

Hello, weblog world! 2 < 4!

]]> This would create a new weblog Entry with the title "My First Entry". Note that in all the examples the full set of HTTP headers for each request and response are not shown, only the most relevant headers are displayed.

Assuming everything goes well and the Entry is created the response might look like: The URI of the filled in Entry is returned via the HTTP headers. The AtomAPI service is responsible for allocating the URI for the Entry. The URI allocation mechanism is implementation dependent and not defined by this document. If a GET is done on the returned URI then a filled in Entry would be returned, including the elements <link/>, <id/>, <created/> and <modified/>.

To retrieve the new Entry on the site the client needs to know the URI of the Atom Entry. This URI is obtained either by the HTTP Location header returned during the creation of the Entry as outlined in , or it is discovered by the search interface discussed in .

For the newly created Atom Entry above, the client connects to port 80 on http://example.org and sends: This would retrieve the Entry just created.

The response might look like: My First Entry

A very boring entry...

Bob B. Bobbington 2003-02-05T12:29:29 2003-02-05T14:10:58Z 2003-02-05T14:10:58Z http://example.org/reilly/2003/02/05#My_First_Entry urn:example.org:reilly:1

Hello, weblog world! 2 < 4!

]]> Information has been added to the Entry, including the <link/>, <id/>, <created/> and <modified/> elements. @@ Editors Note: Beware the Atom syntax is still in flux and the above example is not normative. @@

Editing an Entry is different from creating one, the difference is that the Entry is PUT back to the URI that you retrieved it from via GET.

If the <content/> element is updated the transaction might look like: My First Entry

A very boring entry...

Bob B. Bobbington 2003-02-05T12:29:29 2003-02-05T14:10:58Z 2003-02-05T14:10:58Z http://example.org/reilly/2003/02/05#My_First_Entry urn:example.org:reilly:1

A big hello to the weblog world! 2 < 4!

]]>

The response from the server, on success, returns a 205 HTTP status code. The <content/> element now reflects the updated content, and the <modifed/> element has been updated to reflect when the change was made. As was done after creation, a GET to the URI of the Atom Entry would return the modified Entry.

To retrieve the modified Entry the client connects to port 80 on http://example.org and sends: This would retrieve the recently modified Entry.

The response might look like: My First Entry

A very boring entry...

Bob B. Bobbington 2003-02-05T12:29:29 2003-02-05T14:10:58Z 2003-02-05T14:22:03Z http://example.org/reilly/2003/02/05#My_First_Entry urn:example.org:reilly:1

A big hello to the weblog world! 2 < 4!

]]> The <content/> element now reflects the updated content, and the <modifed/> element has been updated to reflect when the change was made.

Deleting an Entry uses the URI of the Atom Entry. This is the same URI the client does a GET on to retrieve the Atom Entry.

For example, to delete the first Entry in our example the client connects to port 80 on the server and sends:

The response from the server upon a successful deletion is:

Finding an Entry uses the 'search-entries' URI from the Introspection file. For the example Introspection file given, that is the URI http://example.org/reilly/search. The search parameters given are used to select which Entries are listed in the response.

For example, to retrieve the locations of the last 20 Entries, the client connects to port 80 on the server and sends: The server searches for Entries that match the criteria and returns a response that lists those matches.

The response from the server might look like: My First Post http://example.org/reilly/1 My Second Post http://example.org/reilly/2 ]]> There will be one <entry/> element for every Entry that matches the given criteria. Each <entry/> element contains the URI of the Entry and the title of the Entry. If the client needs the Atom Entry then it performs an HTTP GET on the given URI as outlined in . Note that all of the query parameters begin with 'atom-' to avoid conflicts with other query parameters that may already be present in the URI. There are other search critera that can be added. For example the 'atom-all' parameter, if present, requests that the server return a list of all Entries on the site. Other additional parameters that can be added are 'atom-start-range' and 'atom-end-range'. Access to the entries is by an index, with the first Entry having an index number of 0.

For example, this request will return a list of all Entries from index 2 to index 27. The rest of the search parameters and their properties are covered in detail in . Note that the URI the client receives for the search facet may already have query parameters in it so the client may not just append the query parameters to the end of the search URI. The best approach to handling this situation is to parse out all the query parameters, add in the ones being used by the client then join the URI back together.

The preferences for the user are edited through the URI supplied in the <user-prefs/> element of the introspection file. To retrieve the current user preferences issue and HTTP GET on the URI.

For the website at http://example.org/reilly, the request would look like: This would return a list of user configuration parameters and their values.

The reponse would look like: Reilly 1234 reilly@example.org ]]> The values can then be updated, and doing an HTTP PUT of the updated file back to the 'user-prefs' URI will update the user preferences.

For example, if we update our email address, from reilly@example.org to sputnik@example.org, we would then PUT it back to the 'user-prefs' URI: Reilly 1234 sputnik@example.org ]]> Assuming the update goes successfully, the updated user preferences will be returned in the response.

The reponse would look like:

The templates for the user are edited through the URI supplied in the <edit-template/> element of the introspection file. Doing an HTTP GET on the edit-template URI retrieves a file that describes all the available templates and their URIs.

Here is an example template description file. Main http://example.org/tpl/Main.html Story http://example.org/tpl/Stry.html Feed http://example.org/tpl/Feed.xml ]]> Two important things to note on this file. First is that this list of templates is in no way normative. Secondly, note that templates may have different mime-types. To begin editing a template, do a GET on one of the listed URIs. After the content has been edited the client PUTs the modified content back to the same URI.

This part of the AtomAPI does not use the URIs listed in the Introspection file. There are different interfaces now circulating for an TrackBack, Ping-Back, Post-It. All of these are systems for adding comment-like information to an Entry. The only thing missing from the mix is a way to do comments themselves. This section of the specification is intended to be a roll-up of all the above specifications and to cover comments as well. Creating a comment is similar to creating an Entry, that is, you HTTP POST an Entry to a URI. For now we will defer discussing how to obtain the corrent URI to POST to.

For example, if "http://example.org/reilly/1/comments" is the URI that accepts comments for the first Entry on the website http://example.org/reilly, then the client would open port 80 on example.org and send: My Comment Fred F. Fobbington 2003-02-05T12:29:29

Welcome to the neighborhood!

]]> This would create a new comment for the first Entry on "http://example.org/reilly".

The response to this POST, assuming everything went without error would look like this: This would create a new comment/trackback for the first Entry on "http://example.org/reilly". Note that the response can contain a Location: header that points to the comment as an Entry. This is not a required feature of the interface.

Two mechanisms are available for discovering the URI that you would use to create a comment. The first is a way to put that information in HTML, the second is a way to embed that information in an Atom feed.

The <link> element has been successful in finding RSS feeds and is appropriate to use here for discovering the "commentURI" in HTML pages. The <link> tag goes in the <head> section of an HTML page and is used to indicate a document relationship. For a similar example of using the link tag to discover a URI, refer to the usage of of the link tag for RSS Auto-Discovery. In this case the form of the link tag used to indicate the location of the comment URI is:

]]> Where href should be set to the URI that accepts POSTs for comments. Applications looking for a URI to post comments to need to parse out the headers of the web page and look for a link tag that has a relation rel of "service.comment" and a mime-type of "application/x.atom+xml".

There is a <comment/> element in each Entry that is used to provide the location of the URI that accepts comment POSTs. This is providing the same information as the link tag does in HTML.