Developer Web Site

Atom and Atompub

Atom consists of two parts:

The Atom Publishing Protocol (AtomPub)

is an application-level protocol
for publishing and editing Web resources. The protocol is based on HTTP
transfer of Atom-formatted representations. It is specified in
RFC 5023.

The Atom Syndication Format

is an XML-based Web content and metadata
syndication format. It is specified in
RFC 4287.

The Web Service API uses Atom-formatted XML documents to transfer data and
Atompub as the protocol that specifies how to create, retrieve, update and delete the
Atom-formatted resources.

Data Format

The Web Service API represents individual items of data as Atom
Entries
and collections of items as Atom
Feeds.
Within an Entry, a data item is stored as an XML document within the Entry's
Content element.
Additional information is stored in other Atom elements,
and can be used for tasks like paging through a Feed.

Atom content Element

The API stores each entry's data as a well-formed XML fragment inside the
content element. The element's type attribute has a value of
"application/vnd.ctct+xml". All of the XML is in the
http://ws.constantcontact.com/ns/1.0/ namespace.

The fragment's top-level element indicates the type of the entry, e.g.
ContactList or Activity. The top-level element
also has an id attribute. Its value serves as a unique identifier
for the entry, and can be used to refer to the entry. Each property of the entry
is represented as an element and value inside the top-level element.

Other Atom Elements

Some required Atom element values are populated with values from the underlying
Constant Contact data. For example, in a Contact List entry, the Atom title
element contains the list's name. These values are populated for convenience when
using Atom-aware tools, and because they are required by the Atom specification.
The definitive value is always that in the XML fragment inside the Atom
content element. In particular, on create and update operations values are
always read from the content XML.

Paging and Links

Collections may contain large numbers of entries. To avoid problems with handling large
amounts of data with a single request, the server may elect to provide paged collections.
When it does, it will return an Atom feed containing a subset of the data along
with a link to get the next chunk of data. Specifically,the feed will contain Atom
link elements with rel attributes indicating what the
link is pointing to.

<feed xmlns="http://www.w3.org/2005/Atom">
  ...
  <link href="lists?next=50" rel="next" />
  <link href="lists" rel="first" />
  <link href="lists?next=25" rel="current" />
  <entry>
    ...
  </entry>
  ...
</feed>

In the example above, the first link element has rel="next",
indication that it points to the next page of the collection. The other two links point
to the first and current pages respectively. All links are relative to the current document.

Protocol

This article
gives a good introduction to Atompub.