Atom Service Discovery

You can find out all of the available atom services that a website provides from the Atom Service Document. Here is a common way to find the service document.

  1. Go to the website in your browser

  2. View the Page Source

  3. Locate <link type="application/atomsvc+xml" ... />
    This will normally be in the document's <head>

  4. The Service Document is the href="..." attribute of that <link>

Here is an example of Lotus Connections' Communities Service Document <link> found in the Page's Source: 

<link rel="introspection"
      type="application/atomsvc+xml"
      title="Atom Publishing Protocol"
      href="/communities/service/atom/introspection" />
Service Document Innards

An Atom Service Document is different from an Atom Entry and Atom Feed. Its foundation is XML but its Namespace http://www.w3.org/2007/app normally taking on the shorthand app.

Check out the Atom Publishing Protocol Spec if you would like to take a look at the Atom Service Document Specification. That article will define the elements such as <categories> and <collection>. For the rest of this discussion I will only focus on their meaning with respect to Lotus Connections. Specifically using the following Service Document for Lotus Connections Blogs: 

<?xml version="1.0" encoding="UTF-8"?>
<service xmlns="http://www.w3.org/2007/app"
         xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:generator version="1.0-bcv3" uri="http://www.ibm.com/xmlns/prod/sn">
    Lotus Connections - Blogs
  </atom:generator>
  <workspace xml:lang="en-US" xmlns:xml="http://www.w3.org/XML/1998/namespace">
    <atom:title type="text">From Joe's Moleskin</atom:title>

    <collection
      href="http://example.com/weblogs/services/atom/jjpecora/entries">
      <atom:title type="text">Weblog Entries</atom:title>
      <accept>application/atom+xml; type=entry</accept>
      <categories
        href="http://example.com/weblogs/services/atom/jjpecora/categories" />
    </collection>

    <collection
      href="http://example.com/weblogs/services/atom/jjpecora/media">
      <atom:title type="text">Media Entries</atom:title>
      <accept>video/x-msvideo</accept>
      <accept>application/octet-stream</accept>
      <accept>image/gif</accept><accept>text/html</accept>
      <accept>image/jpeg</accept><accept>image/png</accept>
      <accept>text/plain</accept>
      <categories fixed="yes" />
    </collection>

    <collection
      href="http://example.com/weblogs/services/atom/jjpecora/comments">
      <atom:title type="text">Comment Entries</atom:title>
      <accept>application/atom+xml; type=entry</accept>
      <categories fixed="yes" />
    </collection>

  </workspace>
</service>
Collections and Acceptance

In the above Service Document there are three collections (blue), each with a title tag (red), and a number of accept tags (green). The collections are the Atom services that you are allowed to interact with. The title gives a human readable description of what that collection does. You are not allowed to send just any data to that collection. Each collection accepts certain kinds of data. The type of data they accept are described in their accept tags.

For instance, if you want to post a new Blog Entry you would POST an Atom Entry to this URL: http://example.com/weblogs/services/atom/jjpecora/entries. That is because the title of that collection is "Weblog Entries," it accepts application/atom+xml, and the URL is in the collection's the href attribute.

Here are the important things to take from the Service Document:

  1. Each <collection> describes a service.

  2. That service is accessed via the URL found in that collection's href attribute.

  3. A hint to what that service is used for is found in the <atom:title> tag.

  4. The list of formats you can upload to that collection are listed in <accept> tags.

  5. You may then make use of the REST architecture to POST and GET Atom Entries and Feeds.