Tip: Organize content with Atom categories

Find out what categories are available and then add category elements to your entries

Nicholas Chase (ibmquestions@nicholaschase.com), Writer, Freelance

Nicholas Chase has been involved in Web site development for companies such as Lucent Technologies, Sun Microsystems, Oracle, and the Tampa Bay Buccaneers. Nick has been a high school physics teacher, a low-level radioactive waste facility manager, an online science fiction magazine editor, a multimedia engineer, an Oracle instructor, and the Chief Technology Officer of an interactive communications company. He is the author of several books, including XML Primer Plus (Sams).

Summary: Atom lets you provide an easy way to manage lots of data, but there will come a point at which you need to add some sort of categorization to make that data manageable. This tip shows you how to use categories with Atom feeds and the Atom API. Although you will naturally add category information to information syndicated using Atom, this tip focuses on these categories from the perspective of the Atom Publishing Protocol.

View more content in this series

Date: 17 Jul 2007
Level: Intermediate
Activity: 905 views
Comments:

Allowable categories

As you consider adding categories to your Atom entries, first consider what your choices are. The place to find that out is in the Atom service document, which defines the categories that exist for a particular collection. For example, consider the default service document for the Blogapps server (see Listing 1).

Listing 1. The service document

                
<?xml version="1.0" encoding="UTF-8"?>
<app:service xmlns:app="http://purl.org/atom/app#" 
                     xmlns:atom="http://www.w3.org/2005/atom">
  <app:workspace>
    <atom:title>AdminBlog</atom:title>
    <app:collection 
         href="http://localhost:8080/roller/app/adminblog/entries">
      <atom:title>Weblog Entries</atom:title>
      <app:categories app:fixed="yes" 
              app:scheme="http://localhost:8080/roller/adminblog/">
        <atom:category atom:term="/General" atom:label="General" />
        <atom:category atom:term="/Status" atom:label="Status" />
        <atom:category atom:term="/Java" atom:label="Java" />
        <atom:category atom:term="/Music" atom:label="Music" />
        <atom:category atom:term="/Politics" atom:label="Politics" />
        <atom:category atom:term="/Music" atom:label="Music" />
      </app:categories>
      <app:accept>entry</app:accept>
    </app:collection>
    <app:collection 
          href="http://localhost:8080/roller/app/adminblog/resources">
      <atom:title>Media Files</atom:title>
      <app:accept>image/*</app:accept>
    </app:collection>
  </app:workspace>
  <app:workspace>
    <atom:title>main</atom:title>
    <app:collection 
             href="http://localhost:8080/roller/app/main/entries">
      <atom:title>Weblog Entries</atom:title>
      <app:categories app:fixed="yes" 
                    app:scheme="http://localhost:8080/roller/main/">
        <atom:category atom:term="/General" atom:label="General" />
        <atom:category atom:term="/Status" atom:label="Status" />
        <atom:category atom:term="/Java" atom:label="Java" />
        <atom:category atom:term="/Music" atom:label="Music" />
        <atom:category atom:term="/Politics" atom:label="Politics" />
      </app:categories>
      <app:accept>entry</app:accept>
    </app:collection>
    <app:collection 
               href="http://localhost:8080/roller/app/main/resources">
      <atom:title>Media Files</atom:title>
      <app:accept>image/*</app:accept>
    </app:collection>
  </app:workspace>
</app:service>

In this case, both the adminblog and main weblog collections have sets of categories, but there is more to this data than might meet the eye at first glance.

First of all, notice that the category elements themselves have two important attributes. The first is the term, which is the actual category representation. Notice that in this case, each of the terms start with a slash (/). The Atom Syndication Format specification is silent on the matter of what the form that a term can take, so nothing stops you from creating a hierarchical structure of categories.

The second important attribute is the label, which consists of the human-readable version of the category.

Now, both sets of categories seem to have the same entries, but they don't. If you look at the categories elements, you'll notice that they carry a scheme attribute. The category scheme acts as a way to categorize your categories, so to speak. For example, the adminblog General category might mean something completely different from the main General category.

You can even mix schemes together in a single collection by adding a scheme element to the individual category element.

Using categories

Adding categories to your content is simply a matter of adding the category element to your entry. For example, you might add a new entry to the server (see Listing 2).

Listing 2. Adding a category

                
POST /roller/app/main/entries HTTP/1.1
Host: localhost
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/atom+xml
Content-Length: 760

<entry xmlns="http://www.w3.org/2005/Atom">
    <title>Blogapps supports Atom (Java)</title>
    <updated>2007-12-13T12:30:02Z</updated>
    <summary>The spec's not actually out yet, but fortunately, you 
can still use it.</summary>
    <published>2007-05-25T08:29:29-04:00</published>
    <category term="Java" />
    <author>
      <name>Nick Chase</name>
      <uri>http://www.chaosmagnet.com</uri>
      <email>atomexample@nicholaschase.com</email>
    </author>
    <content type="xhtml" xml:lang="en"
           xml:base="http://diveintomark.org/">
      <div xmlns="http://www.w3.org/1999/xhtml">
         <p><i>The Blogapps server supports the upcoming Atom spec, 
so if you install it ...</i></p>
      </div>
    </content>
</entry>

Here you use the established Java category, so the response shows that the entry was added to it (see Listing 3).

Listing 3. The response

                
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=7818CFD9D1A9A53F5EA3B0A203ABBBCD; Path=/roller
Location: http://localhost:8080/roller/app/main/entry/40288182103d1af401103d6196
9a0068
Content-Type: application/atom+xml;charset=utf-8
Transfer-Encoding: chunked
Date: Sat, 20 Jan 2007 02:41:51 GMT

3fb
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Blogapps supports Atom (Java)</title>
  <link rel="alternate" href="http://localhost:8080/roller/main/entry/blogapps_s
upports_atom_java1" />
  <link rel="edit" href="http://localhost:8080/roller/app/main/entry/40288182103
d1af401103d61969a0068" />
  <category term="/Java" />
  <author>
    <name>admin</name>
...

However, if you try to add a new category, the response will depend on how the server is configured. For example, you can try to add an entry with a nonexistent category (see Listing 4).

Listing 4. Using a nonexistent category

                
...
    <summary>The spec's not actually out yet, but fortunately, 
             you can still use it.</summary>
    <published>2007-05-25T08:29:29-04:00</published>
    <category term="NewCategory" />
    <author>
      <name>Nick Chase</name>
      <uri>http://www.chaosmagnet.com</uri>
...

If you try to send this request to the server as it stands, the result might not be what you expect (see Listing 5).

Listing 5. The results

                
...
  <link rel="edit" href="http://localhost:8080/roller/app/main/entry/40288182103
d1af401103d62f0ea0069" />
  <category term="/General" />
  <author>
    <name>admin</name>
...

Notice that the system used one of the existing categories rather than adding the new one. If you go back in the service documenting Listing 1, you will see that the categories elements specify that the categories are fixed. That means that the categories shown are the only categories allowed.

Category documents

Categories can also be listed in separate category documents. In that case, the service document includes a pointer to that document. For example (see Listing 6).

Listing 6. Pointing to a category document

                
<?xml version="1.0" encoding="UTF-8"?>
<app:service xmlns:app="http://purl.org/atom/app#" 
             xmlns:atom="http://www.w3.org/2005/atom">
  <app:workspace>
    <atom:title>AdminBlog</atom:title>
    <app:collection 
         href="http://localhost:8080/roller/app/adminblog/entries">
      <atom:title>Weblog Entries</atom:title>
      <app:categories 
                href="http://localhost:8080/roller/adminCategories" />
      <app:accept>entry</app:accept>
    </app:collection>
    <app:collection 
          href="http://localhost:8080/roller/app/adminblog/resources">
      <atom:title>Media Files</atom:title>
      <app:accept>image/*</app:accept>
    </app:collection>
  </app:workspace>
...
</app:service>

In this case, the fixed and scheme attributes might not be present, but you can, of course, put them in the category document itself.

Summary

Using categories in Atom is a matter of knowing where to look for them (the service document), and what's permissible. Once you know what categories are available, you can simply add a category element to your entries.

Resources

Learn

An overview of the Atom 1.0 Syndication Format (James Snell, developerWorks, August 2005): See how this popular Web content syndication format stacks up.
Getting to know the Atom Publishing Protocol (James Snell, developerWorks, October - December 2006): Find out about the Atom API in this three-part series:
- Part 1: Create and edit Web resources with the Atom Publishing Protocol: Explore a high-level overview of the protocol and its basic operation and capabilities.
- Part 2: Put the Atom Publishing Protocol (APP) to work: Learn to use APP to interact with a number of real-world deployed applications.
- Part 3: Introducing the Apache Abdera project: Start to implement Atom-enabled apps using a new open-source project, called Abdera, currently under incubation at the Apache Software Foundation.
RSS and Atom in Action (Dave Johnson, Manning Publications, July 2006): If you prefer something more physical, take a look at this book about the blog technologies of news feed formats and publishing protocols and how to put these building blocks together. (Blogapps was put together for this book.)
Atom 1.0 specification: Read about this XML-based Web content and metadata syndication format.
Atom 1.0 compatible software: Visit the Atom Working Group's Wiki for a list of known Atom 1.0 feed consumers.
Use the Atom format for syndicating news and more (Uche Ogbuji, developerWorks, May 2004): Read more on this XML-based standard, format, and API for the interchange and cross-reference of Web metadata.
developerWorks XML zone: Find hundreds more XML resources.
IBM XML certification: Find out how you can become an IBM-Certified Developer in XML and related technologies.
XML technical library: See the developerWorks XML Zone for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks.
developerWorks technical events and webcasts: Stay current with technology in these sessions.
The technology bookstore: Browse for books on these and other technical topics.

Get products and technologies

The Blogapps server: Download the server in this collection of useful RSS and Atom utilities and examples.
IBM trial software: Build your next development project with trial software available for download directly from developerWorks.

Discuss