TypeList Auto-Discovery Using Atom

Overview: In addition to hosted weblogs, TypePad offers all subscribers a feature called TypeLists. TypeLists are used to manage sidebar lists of links, books, music, people, and notes. From a developer standpoint, this content is highly structured data with information such as ratings, and can be accessed using the steps outlined in this article.

Since taking on my new role at Six Apart as Manager of Platform Technology, I have taken an interest in Six Apart’s APIs and integration technologies. I have become more involved in the Atom Working Group which is helping to build consensus around a core Atom Publishing Protocol.

I have been playing around with TypePad and Atom to create more than just blog entries. On TypePad you can use Atom not only to create weblog entries, but also TypeList entries and Photo Album entries as well. But taking advantage of this feature in an elegant way often depends upon a user specifying which blog, photo album, or TypeList they wish to post the new item to.

I was pleasantly surprised that TypePad’s current Atom implementation provides a lot of the capabilities that the Working Group is trying to codify into the core Atom protocol. One of those capabilities is a form of "introspection," a way of discovering what resources are available within a given TypePad account. This article explores how one can "introspect" a TypePad account via the Atom Publishing Protocol to discover a set of TypeLists available within that account.

If you have not used TypePad or are unfamiliar TypeLists, a TypeList is a way of sharing a list of web sites, books, CDs, DVDs, or people on your weblog. TypeLists can also be used to insert raw HTML into the sidebar of your TypePad weblog.

To understand how this works, let's first take a look at how TypePad exposes introspection through Atom.

TypePad exposes three introspection URLs: one for TypeLists, Weblogs and Photo Albums respectively. By performing a simple (authenticated) HTTP GET on one of the following URLs one can retrieve a document describing the resources available at that URL:

The introspection document returned by TypePad is an Atom feed itself.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://purl.org/atom/ns#" xmlns:list="http://sixapart.com/atom/list#">
    <link rel="service.post" href="http://www.typepad.com/t/atom/typelist/list_id=1" 
          type="application/x.atom+xml" title="Link TypeList" list:type="Link" />
    <link rel="service.feed" href="http://www.typepad.com/t/atom/weblog/list_id=1" 
          type="application/x.atom+xml" title="Link TypeList" list:type="Link" />
    <link rel="service.post" href="http://www.typepad.com/t/atom/weblog/list_id=2" 
          type="application/x.atom+xml" title="Friends TypeList" list:type="People" />
    <link rel="service.feed" href="http://www.typepad.com/t/atom/weblog/list_id=2" 
          type="application/x.atom+xml" title="Friends TypeList" list:type="People" />
</feed>

Within this document two pointers can be found for each TypeList associated with the current account: a pointer to the URL from which a feed can be retrieved and a URL to which assets can be manipulated. Also contained with this document is valuable metadata about each TypeList, specifically the TypeList's name and type.

Let's walk through a simple script that retrieves this document and then outputs its contents in a human readable format. The following code samples are written in Perl and utilize the XML::Atom perl module, but the concepts are simple and can be applied to any programming language.

1  #!/usr/bin/perl
2  #
3  # Description: Test script for fetching a list of TypeLists
4  #      Author: Byrne Reese <byrne@sixapart.com>
5  #
6
7  use XML::Atom::Client;
8  use XML::Atom::Entry;

The above is your typically exciting boilerplate for any Perl program. Note the "use" statements where we import the necessary code from the XML::Atom module.

9  sub get_typelists {
10     my $lists;
11     my $feed = $api->getFeed("http://www.typepad.com/t/atom/lists");
12     my @links = $feed->link();

The get_typelists subroutine is responsible for assembling a simple hash containing the properties of each TypeList in your TypePad account by retrieving one of these introspection documents.

The process of fetching and parsing this document is automated via the getFeed method belonging to your XML::Atom::Client as in the code above on line number 11.

13     foreach my $l (@links) {
14         my ($id) = ($l->href =~ /list_id=(\d+)/);
15         if ($l->rel eq 'service.feed') {
16             $lists->{$id}->{'feed'} = $l->href;
17         } elsif ($l->rel eq 'service.post') {
18             $lists->{$id}->{'post'} = $l->href;
19         }
20         $lists->{$id}->{'title'} = $l->title;
21         $lists->{$id}->{'type'} = 
22               $l->{elem}->getAttributeNS($ListNS,'type');
23     }

The get_typelists subroutine continues by assembling the hash of TypeList properties. Lines 15-19 simply parse out the URIs for fetching the items on a TypeList (the ‚Äúfeed‚Äù) and for posting new items to the TypeList (the ‚Äúpost‚Äù uri). Lines 21 and 22 extract the TypeList type from a custom XML attribute that Six Apart has added to the link relation. A TypeList's type can be one of several values: "People," "Notes," "Music," "Links," or "Reading."

24     return $lists;
25 }

When the hash of TypeList properties has been assembled, it is simply returned.

26 sub prompt {
27     my ($msg) = @_;
28     print "$msg ";
29     my $in = <STDIN>;
30     chomp $in;
31     return $in;
32 }

The above is a simple utility function I created to prompt the user for their TypePad username and password (keep in mind, your username and password are case-sensitive).

Now that our utility functions have been created, we put it to use in a very simple script below.

33 my $ListNS  = 'http://www.sixapart.com/atom/list#'
34 my $api = XML::Atom::Client->new;
35 $api->username(prompt("Enter your TypePad username:"));
36 $api->password(prompt("Enter your TypePad password:"));

In line 34 we instantiate a new Atom client object, and populate that instance with the user’s TypePad username and password.

37 my $lists = get_typelists();
38 foreach my $id (keys %$lists) {
39     $list = $lists->{$id};
40     print "TypeList #".$id."\n";
41     foreach my $key (keys %$list) {
42         print "  $key = ".$list->{$key}."\n";
43     }
44 }

Then we make a call to our get_typelists subroutine and parse the list properties hash that is returned and display it nicely to the user.

I admit this is a trivial script, but hopefully it gets the gears turning in your own mind about how you could use this in one of your own projects. Perhaps to present to a user a list of their TypeLists, allowing them to select the list they would like an item added, and then posting the new item to that list on their behalf.

In Summary

One thing I’m really proud of is the fact that TypePad has already solved the introspection problem to some extent. The "standard" method of introspection may be solved in some other manner, and TypePad will certainly support that, but in the meantime TypePad doesn’t leave you high and dry.

Download the Script