Contents

Protocol details

This section describes the AtomServer document format and query syntax.

Document format

AtomServer and Atom share the same basic data model: a container that holds both some global data and any number of entries. For each protocol, the format is defined by a base schema, but it can be extended using foreign namespaces.

Note: AtomServer feeds are in Atom format and thus, use the Atom namespace as the default namespace by specifying an xmlns attribute on the feed element; see the examples section for examples of how to do that. Thus, the examples in this document don't explicitly specify atom: for elements in an Atom-format feed.

The following tables show the Atom  representations of the elements of the schema. All data not mentioned in these tables is treated as plain XML and shows up the same in both representations. Unless indicated otherwise, the XML elements in a given column are in the namespace corresponding to that column. This summary uses standard XPath notation: in particular, slashes show the element hierarchy, and an @ sign indicates an attribute of an element.

In each of the following tables, the highlighted items are required.

The following table shows the elements of a AtomServer feed:

The following table shows the elements of a AtomServer feed. Note that AtomServer exposes some of the OpenSearch 1.1 Response elements in its search-results feeds.

The following table shows the elements of a AtomServer Entry:

Queries for Time-sensitive Feeds

This section describes how to use the query system to request Feeds that are time-sensitive. The query model is intentionally very simple. The basic tenet is that queries are expressed as HTTP URIs, rather than as HTTP headers or as part of the payload. One benefit of this approach is that you can link to a query.

Query requests

A client queries the AtomServer service by issuing an HTTP GET request. The query URI consists of the resource's URI (called FeedURI in Atom) followed by query parameters. Most query parameters are represented as traditional ?name=value[&...] URL parameters. Category parameters are handled differently; see below.

For example, if the FeedURI is http://foo.com/myserver/v1/widgets/, then you might send a query with the following URI:

http://foo.com/myserver/v1/widgets/acme?updated-min=2005-04-19T15:30:00

AtomServer services support HTTP Conditional GET. AtomServer sets the Last-Modified response header based upon the value of the <atom:updated> element in the returned feed or entry. A client can send this value back as the value of the If-Modified-Since request header to avoid retrieving the content again if it hasn't changed. If the content hasn't changed since the If-Modified-Since time, then the AtomServer service returns a 304(Not Modified) HTTP response. Although a better way to do this is to use the start-index parameter, where the client sets this value to the <as:endIndex> returned in the previous page. Using start-index ensures that the client will never see the same response twice, or miss Entries, since several Entries could have the same "update date", but will never have the same "update index".

http://foo.com/myserver/v1/widgets/acme?start-index=12345

Passing a standard parameter not understood by a given service results in a 403 Forbidden response. Passing an unsupported nonstandard parameter results in a 400 Bad Request response. For information on other status codes, see the HTTP status codes section of this document.

The standard AtomServer query parameters are summarized in the following table. Note that AtomServer supports category queries. All parameter values need to be URL encoded.

Query responses

Queries return an Atom Feed or an Atom Entry, depending on the request parameters and the URL structure.

Query results contain the following OpenSearch elements directly under the <feed> element:

Query results also contain the following AtomServer extension elements directly under the <feed> element: (Note further elements are defined by Aggregate Feeds and Batch processing)

Query results also contain the following AtomServer extension elements directly under the <entry> element: (Note further elements are defined by Aggregate Feeds and Batch processing)

The Atom response Feed and Entries may also include any of the following Atom and AtomServer elements (as well as others listed in the Atom specification):

<link rel="self" type="..." href="..."/>

For Entries, this contains the URI of this resource, without its revision number. For Feeds, this contains the URI required to get back this particular page. The value of the type attribute depends on the requested format. If no data changes in the interim, sending another GET to the self URI returns the same response.

<link rel="edit" type="..." href="..."/>

Contains the URI of the next, presumably unwritten, resource, including its revision number. The value of the type attribute depends on the requested format. If no data changes in the interim, sending PUT to the edit URI will produce a successful update. It is always recommended that you PUT using the "edit" URI.

<link rel="next" type="application/atom+xml" href="..."/>

Specifies the URI of the next chunk of this query result set, if it is chunked. The client must use the next link when accessing the next page of results.

Here's a sample response body, in response to a Feed query:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom" 
      xmlns:as="http://atomserver.org/namespaces/1.0/" 
      xmlns:os="http://a9.com/-/spec/opensearchrss/1.1/">
   <os:totalResults>65801</os:totalResults>
   <os:startIndex>0</os:startIndex>
   <os:itemsPerPage>2</os:itemsPerPage>
   <as:endIndex>153</as:endIndex>
   <link href="/myserver/v1/widgets/acme?start-index=153&amp;max-results=2" rel="next" />
   <link href="/myserver/v1/widgets/acme?start-index=0&amp;max-results=2" rel="self" />
   <author><name>AtomServer APP Service</name></author>
   <title type="text">acme entries</title>
   <updated>2007-10-05T19:17:42.750Z</updated>
   <id>tag:atomserver.org,2007:v1:acme</id>
   <entry>
      <id>/myserver/v1/widgets/acme/205390.en.xml</id>
      <as:entryId>205390</as:entryId>
      <updated>2007-10-05T18:48:23.437Z</updated>
      <published>2007-10-05T18:48:23.437Z</published>
      <title type="text"> Entry: acme 205390.en</title><author>
      <name>AtomServer Atom Service</name></author>
      <link href="/myserver/v1/widgets/acme/205390.en.xml" rel="self" />
      <link href="/myserver/v1/widgets/acme/205390.en.xml/2" rel="edit" />
   </entry>
   <entry>
      <id>/myserver/v1/widgets/acme/205395.en.xml</id>
      <as:entryId>205395</as:entryId>
      <updated>2007-10-05T15:48:56.437Z</updated>
      <published>2007-10-05T12:50:76.437Z</published>
      <title type="text"> Entry: acme 205395.en</title><author>
      <name>AtomServer Atom Service</name></author>
      <link href="/myserver/v1/widgets/acme/205395.en.xml" rel="self" />
      <link href="/myserver/v1/widgets/acme/205395.en.xml/1" rel="edit" />
   </entry>
</feed>

If the requested feed is in the Atom format, if no query parameters are specified, and if the result doesn't contain all the entries, the following element is inserted into the top-level feed: <link rel="next" type="application/atom+xml" href="..."/>. It points to a feed containing the next set of entries. Subsequent sets contain a corresponding <link rel="previous" type="application/atom+xml" href="..."/> element. By following all the next links, a client can retrieve all entries from a feed. Note that following "next links" is the only reliable way to retrieve pages.

Dealing with Time-sensitive Feeds

The RFC4287 Date Specification

Optimistic concurrency (versioning)

Locale sensitivity

HTTP status codes

The following table describes what various HTTP status codes mean in the context of AtomServer.

Additional resources

You may find the following third-party documents useful:

• Overview of Atom from IBM
• HTTP 1.1 method definitions; specification for GET, POST, PUT, and DELETE
• HTTP 1.1 status code definitions
• How to Create a REST Protocol
• Building Web Services the REST Way
• A Technical Introduction to XML
• XML Namespaces by Example

Back to top