Tip: How to use Atom's slug header when you publish content

Influence what URL is assigned when you add a resource to an Atom API server

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: One advantage of the Atom Publishing Protocol is the ability to not only retrieve information, but also to add or edit information. In this tip, learn to use Atom's Slug header to influence the final URL for this information. This tip uses the Blogapps server, which supports draft 10 of the Atom Publishing Protocol 1.0 specification, but is applicable to any APP 1.0 compliant server.

View more content in this series

Date: 05 Jun 2007
Level: Intermediate
Activity: 858 views
Comments:

Publishing content with Atom API

The Atom Publishing Protocol works on the principle that you can accomplish everything you want to do through simple HTTP operations. You can read an item using the GET method, or add one to the system using the POST method. When you do, the response includes the URL for the new entry.

For example, to add a new blog entry to the system, you can send an Atom entry element to the server as the content of a POST request (see Listing 1).

Listing 1. Adding a new entry to the server

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

<entry xmlns="http://www.w3.org/2005/Atom">
    <title>Blogapps supports Atom</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>
    <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>

Listing 1 shows the raw HTTP request, including headers. These headers include the target for the request (in this case, /roller/app/main/entries), authorization information (in other words, and encoded version of the username and password, Authorization: Basic YWRtaW46YWRtaW4=), and the length of the content. The request itself is the object that you want to add to the system, in this case an entry.

Assuming all is well, the server responds with a message to confirm that the entry has been created (see Listing 2).

Listing 2. The server response

                
HTTP/1.1 201 Created

Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=E6A3B2F843B16DE06A03F8AAAB59D020; Path=/roller
Location: http://localhost:8080/roller/app/main/entry/40288182103d1af401103d3924
c80033
Content-Type: application/atom+xml;charset=utf-8
Transfer-Encoding: chunked
Date: Sat, 20 Jan 2007 01:57:40 GMT

3eb
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Blogapps supports Atom</title>
  <link rel="alternate" 
        href="http://localhost:8080/roller/main/entry/blogapps_supports_atom" />
  <link rel="edit" href="http://localhost:8080/roller/app/main/entry/40288182103
d1af401103d3924c80033" />
  <category term="/General" />
  <author>
    <name>admin</name>
    <email>admin@example.com</email>
  </author>
  <id>http://localhost:8080/roller/main/entry/blogapps_supports_atom</id>
  <updated>2007-12-13T12:30:02Z</updated>
  <published>2007-05-25T12:29:29Z</published>
  <content type="html"><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>
  <app:control xmlns:app="http://purl.org/atom/app#">
    <app:draft>no</app:draft>
  </app:control>
  <atom-draft 
xmlns="http://rollerweblogger.org/namespaces/app">9</atom-draft>
</entry>
0

The server decides where to put the entry, and how to represent that location as a URL. In the case of this blog entry, it used a version of the entry title. That makes sense, but what if you add an image to the system instead? For example (see Listing 3).

Listing 3. Adding an image

                
POST /roller/app/main/resources HTTP/1.1
Host: localhost
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: image/jpg
Content-Length: 6730

/9j/4AAQSkZJRgABAQEAhACEAAD/4QfuRXhpZgAASUkqAAgAAAAJAA8BAgAWAAAAegAAABABAgAh
AAAAkAAAABIBAwABAAAAAQAAABoBBQABAAAAsgAAABsBBQABAAAAugAAACgBAwABAAAAAgAAADIB
AgAUAAAAwgAAABMCAwABAAAAAQAAAGmHBAABAAAA1gAAAAAAAABFQVNUTUFOIEtPREFLIENPTVBB
TlkAS09EQUsgRFg0NTMwIFpPT00gRElHSVRBTCBDQU1FUkEAGQAAmBAAACAAAACYEAAAIAAyMDA3
...
oFxWuuGbzn1PPvU8lcH/2Q==

Here again you see the headers specifying what you're doing, and the object that you're adding to the system as the content of the POST. In this case, however, there is no easy title to use as part of the URL, so in most cases you wind up with something like that shown in Listing 4.

Listing 4. The server response to adding an image

                
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=8E0BAE66A14BE79270084301FD6C50CF; Path=/roller
Location: http://localhost:8080/roller/app/main/resource/main-2007011920984.jpg.
media-link
Transfer-Encoding: chunked
Date: Sat, 20 Jan 2007 01:35:02 GMT

26e
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>main-2007011920984.jpg</title>
  <link rel="edit" href="http://localhost:8080/roller/app/main/resource/main-200
7011920984.jpg.media-link" />
  <link rel="edit-media" href="http://localhost:8080/roller/app/main/resource/ma
in-2007011920984.jpg" />
  <id>http://localhost:8080/roller/app/main/resource/
main-2007011920984.jpg</id>
  <updated>1970-01-01T00:00:00Z</updated>
  <content type="image/jpeg" 
    src="http://localhost:8080/roller/resources/main/main-2007011920984.jpg" />
  <atom-draft
 xmlns="http://rollerweblogger.org/namespaces/app">9</atom-draft>
</entry>
0

Now that might be a perfectly reasonable URL, but it's hardly user-friendly. What if you wanted to control -- or at least influence -- the URL your server chose? The Atom API provides a specific header, Slug, that enables you to do that.

The Slug header is named after the publishing industry's slug, or short name used to refer to articles. A server is not required to honor the Slug header, but if yours does, you can use it to control at least part of the URL provided to a new resource. For example, you could specify a name for this image (see Listing 5).

Listing 5. Specifying a title

                
POST /roller/app/main/resources HTTP/1.1
Host: localhost
Authorization: Basic YWRtaW46YWRtaW4=
Slug: RingNumberThree
Content-Type: image/jpg
Content-Length: 6730

/9j/4AAQSkZJRgABAQEAhACEAAD/4QfuRXhpZgAASUkqAAgAAAAJAA8BAgAWAAAAegAAABABAgAh
AAAAkAAAABIBAwABAAAAAQAAABoBBQABAAAAsgAAABsBBQABAAAAugAAACgBAwABAAAAAgAAADIB
AgAUAAAAwgAAABMCAwABAAAAAQAAAGmHBAABAAAA1gAAAAAAAABFQVNUTUFOIEtPREFLIENPTVBB
TlkAS09EQUsgRFg0NTMwIFpPT00gRElHSVRBTCBDQU1FUkEAGQAAmBAAACAAAACYEAAAIAAyMDA3
...

If the server supports the Slug header, you should see a response something like this (see Listing 6).

Listing 6. Supporting the Slug header

                
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=4F33EA3CCA134A48B81D9AA7C2B43EAC; Path=/roller
Location: http://localhost:8080/roller/app/main/resource/ringnumberthree.jpg.med
ia-link
Transfer-Encoding: chunked
Date: Sat, 20 Jan 2007 01:39:03 GMT

25f
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>ringnumberthree.jpg</title>
  <link rel="edit" href="http://localhost:8080/roller/app/main/resource/ringnumb
erthree.jpg.media-link" />
  <link rel="edit-media" href="http://localhost:8080/roller/app/main/resource/ri
ngnumberthree.jpg" />
  
<id>http://localhost:8080/roller/app/main/resource/ringnumberthree.jpg</id>
  <updated>1970-01-01T00:00:00Z</updated>
  <content type="image/jpeg" 
    src="http://localhost:8080/roller/resources/main/ringnumberthree.jpg" />
  <atom-draft 
xmlns="http://rollerweblogger.org/namespaces/app">9</atom-draft>
</entry>
0

Here the server integrated the Slug header into the name it chose for the resource. You can use this for any resource, including Entry objects.

Summary

The Slug header enables you to influence the URL assigned to any kind of resource you add to an Atom API server. This can be handy for servers that do not automatically use the title for the URL, or in any situation in which you want more control over the URL that the server chooses.

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: Learn all about XML at the developerWorks XML zone.
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.