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

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.

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



05 June 2007

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

Get products and technologies

  • The Blogapps server: Download the server in this collection of useful RSS and Atom utilities and examples.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into XML on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=XML
ArticleID=218656
ArticleTitle=Tip: How to use Atom's slug header when you publish content
publish-date=06052007