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 Contect 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.
