Atom consists of two parts:
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.
content
ElementThe 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.
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.
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.
This article gives a good introduction to Atompub.