This document describes the protocol used by the AtomServer data APIs ("AtomServer"), including information about what a query looks like, what results look like, and so on. This the reference document and is intended for anyone wanting to understand the XML format and protocol used by AtomServer.
For a further, detailed description of the actual protocol, either
- See the Atom Publishing Protocol Reference for further information about the elements of the feed itself. Note that we do not exhaustingly document this information herein, because we are using Atom entirely as dictated by the standard.
- See the AtomServer Protocol
Basics document for general information about communicating with
the AtomServer service.
Nor does this document explain the basics of XML, namespaces, syndicated feeds, and the GET, POST, PUT, and DELETE requests in HTTP, as well as HTTP's concept of a "resource." For more information about those things, see the Additional resources section of this document.
This document doesn't rely on any particular programming language; you can send and receive AtomServer messages using any programming language that lets you issue HTTP requests and parse XML-based responses.
Finally, giving credit where it is due, this document is "liberally derived" from the GData Protocol Reference document.
- Protocol details
- Document format
- Queries for Time-sensitive Feeds
- Dealing with Time-sensitive Feeds
- Optimistic Concurrency
- Locale Sensitivity
- Http Response Codes
- Additional resources
This section describes the AtomServer document format and query syntax.
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
and thus, use the Atom namespace as the default namespace by specifying
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
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:
|Feed Schema Item||Atom Representation|
|Feed HTML Link||
|Feed Last Update Date||
(RFC 4287 format) See the About Date Constructs section for further details.
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.
|Search Result Feed Schema Item||Atom Representation|
|Number of Search Results||
|Search Result Start Index||
|Number of Search Results Per Page||
The following table shows the elements of a AtomServer Entry:
|Entry Schema Item||Atom Representation|
|Entry Publication Date||
(RFC 4287) See the About Date Constructs section for further details.
|Entry Update Date||
(RFC 4287) See the About Date Constructs section for further details.
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.
A client queries the AtomServer service by issuing an HTTP
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
parameters. Category parameters are handled differently; see below.
For example, if the FeedURI is
then you might send a query with the following URI:
AtomServer services support HTTP Conditional
response header based upon the value of the
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
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".
Passing a standard
parameter not understood by a given service results in a
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.
||Bounds on the entry update date||
||The "update index" of the last result retrieved
||Maximum number of results to be retrieved||
||The locale Id of the
||The type of Entry to return.
|entryID.localeID.xml||ID of a specific entry to be retrieved||
Queries return an Atom Feed or an Atom Entry, depending on the request parameters and the URL structure.
Query results contain the following OpenSearch
||The total number of search results for the query||
||The index of the first result.||See the start-index in the table above for important information about this element.|
||The maximum number of items that appear on one page.||This allows clients to
generate direct links to any set of subsequent pages. However, for a
possible pitfall in using this number, see the note regarding
||The "update index" of the final result.||See the start-index description in the table above for important information about this element. Note; the endIndex returned by a Feed can be used as the start-index for a subsequent Feed page request.|
||The Id of the Atom Entry.||This element is provided as a convenience to the User. It is particularly important for POST requests, when the Id was created within AtomServer. It saves the User the trouble of parsing the Id out of the <id> element, because inevitably the User will need it for further processing.|
||The revision number of the Atom
||This element is provided as a convenience to the User. It is used for optimistic concurrency requests (see below).|
||The "update index" of the Atom
||This element is provided as a convenience to the User. It is primarilly used for debugging.|
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
typeattribute 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
typeattribute 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,
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'?>
<link href="/myserver/v1/widgets/acme?start-index=153&max-results=2" rel="next" />
<link href="/myserver/v1/widgets/acme?start-index=0&max-results=2" rel="self" />
<author><name>AtomServer APP Service</name></author>
<title type="text">acme entries</title>
<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" />
<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" />
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:
rel="next" type="application/atom+xml" href="..."/>. It
points to a feed containing the next set of entries. Subsequent sets
contain a corresponding
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.
The Last Modified Date must be provided using the RFC4287 standard, which is detailed below. And the Last Modified Date is inclusive. In other words, the time-sensitive Feed will contain all Entries from the Last Modified Date onwards, including those at the Last Modified Date itself.
It is important to understand that a time-sensitive Feed contains any Entries that have been modified since the provided date. And since AtomServer is a store, Entries may be continually modified. This means that it is entirely possible that you will see Entries you've seen previously in a Feed. For example, Let's imagine that you've requested a Paged Feed, and you've seen Entries A, B, C ,D, and E, and let's say that B has been deleted (remember, deleted Entries are not really deleted, but are simply marked as deleted) and that D has been modified. Then you will see both B and D again in a later page.
The best way to access a time-sensitive Feed is to use the start-index URL Query (e.g. GET /v1/widgets/acme?start-index=153). Using this method ensures that you will never receive any inappropriate duplicate Entries. The reason for this is that a "last modified date" operation is, by definition, an inclusive operation (i.e. ">="). And that many Entries may have the same Date. To work around this, AtomServer indexes every Entry monotonically. And a "get next index" operation is exclusive (i.e. ">"), so you are therefore assured of getting the appropriate next Entry. The start-index for a Feed is equal to the endIndex returned by the last page you received.
You may also place an upper bound on time-sensitive Feeds using either the updated-max and end-index query parameters. (e.g. GET /v1/widgets/acme?start-index=153&end-index=299 or widgets/acme?updated-min=2005-04-19&updated-max=2008-10-07). Note that updated-max is "exclusive" and end-index is inclusive. It is an error (400 BAD REQUEST) to request updated-max less than updated-min, or end-index less than start-index. If start-index equals end-index, a 304 NOT MODIFIED is returned.
dates are assumed to be in GMT, unless you provide a timezone offset!
3.3. Date Constructs
A Date construct is an element whose content MUST conform to the
"date-time" production in [RFC3339]. In addition, an uppercase "T"
character MUST be used to separate date and time, and an uppercase
"Z" character MUST be present in the absence of a numeric time zone
Such date values happen to be compatible with the following
specifications: [ISO.8601.1988], [W3C.NOTE-datetime-19980827], and
Example Date constructs:
Date values SHOULD be as accurate as possible. For example, it would
be generally inappropriate for a publishing system to apply the same
timestamp to several entries that were published during the course of
a single day.
In AtomServer, we achieve these semantics by appending a version ID to each entry's edit URI. Note that the edit URI always points to the version you should PUT to (i.e. to one version greater than the current version), while the self link always points to an "unversioned" URI. Note that only the edit URI is affected, not the entry ID. In this scheme, each update changes the entry's revision number, and its corresponding edit URI, thus guaranteeing that subsequent updates based on the original version fail. Deletes, of course, are identical to updates with respect to this feature; if you send a delete with an old version number, the delete fails.
If the server detects a version conflict on PUT or DELETE, the server responds with 409 Conflict. The body of the response contains the correct edit URI of the entry. The client is advised to resolve the conflict and resubmit the request, using the edit URI from the 409 response. An example error response follows;
<a:message>Optimistic Concurrency Error:: /myserver/v1/widgets/acme/12345.en.xml/2</a:message>
<link xmlns="http://www.w3.org/2005/Atom" href="/myserver/v1/widgets/acme/12345.en.xml/3" rel="edit" />
A couple of things to note:
* you are not required to send the version ID on a GET (in fact, it is discouraged), but if you supply one, it must be correct, and you will get a 404 NOT FOUND if it is wrong
* if you try to DELETE a resource that does not exist, you will get a 404 NOT FOUND response.
* if you try to PUT or DELETE a revision that already has been written, you will get a 409 CONFLICT.
Overriding Optimistic Concurrency
By its very nature, Optimistic Concurrency is easily ignored by clients - that is to say, whenever AtomServer refuses to write a resource because of a mismatched version ID, it will respond telling the client what the correct version ID is. If the client wishes, it can always use that link to immediately overwrite the resource. In the case of resources that have a "single writer", where you will always know that the data you want to write should be written, you can avoid having to make that first round trip to determine the version ID by specifying a version ID of "*". For example, if you do a PUT to http://foo.com/myserver/v1/widgets/acme/1234.en.xml/*, your write will succeed, regardless of the current version ID. The response will still contain the correct entry links and version ID.
Motivation and design notes
This approach to optimistic concurrency allows us to implement the semantics we want without requiring new markup for version IDs, which makes AtomServer's responses compatible with non-AtomServer Atom endpoints.
Instead of specifying version IDs, we could have chosen to look at the update timestamp on each entry (/atom:entry/atom:updated). However, there are two problems with using the update timestamp:
* It only works for updates and not deletions.
* It forces applications to use date/time values as version IDs, which are problematic.
not receive 123.en.xml - you will receive a 404 NOT FOUND. Similar for Feed requests, when you request /widgets?locale=en_GB, you will receive only en_GB Entries -- and if there are none; 404. It was decided that this behavior was more consistent with a "Data Service". And that locale sensitivity was confusing and complicating things in the client Feed Readers.
The following table describes what various HTTP status codes mean in the context of AtomServer.
|200 OK||No error.|
|201 CREATED||Creation of a resource was successful.|
|304 NOT MODIFIED||The resource hasn't changed since the time specified in the request's If-Modified-Since header.|
|400 BAD REQUEST||Invalid request URI or header, or unsupported nonstandard parameter.|
|401 UNAUTHORIZED||Authorization required.|
|403 FORBIDDEN||Unsupported standard parameter, or authentication or authorization failed.|
|404 NOT FOUND||Resource (such as a feed or entry) not found.|
|409 CONFLICT||Specified version number doesn't match resource's latest version number.|
|422 BAD CONTENT
||The data within this entry's
<content> is not valid. For example, this may indicate not
|500 INTERNAL SERVER ERROR||Internal error. This is the default code that is used for all unrecognized errors.|
You may find the following third-party documents useful:
- Overview of Atom from IBM
- HTTP 1.1 method
definitions; specification for
- 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