Meerkat: The XML-RPC Interface

Editor's note: Meerkat predated the popularity of syndication, feed services, and feed readers. Now that other groups are providing this service, we have removed Meerkat in favor of their better solutions. We maintain these articles for the sense of historical interest.

Meerkat, O'Reilly Network's Open Wire Service, extends its open API
with XML-RPC, affording a more standardized XML-based interface to its
aggregated RSS database.

Meerkat is an open service. Its API (Application Programming Interface) is open and well-documented. For HTML jockeys, adding syndicated stories to a web site is only one line of cut-and-paste JavaScript away. Application developers with a little know-how and a sense of adventure may use Meerkat's rich XML feeds and powerful "recipes" (read: queries) as a framework upon which to build their own applications.

Meerkat's API is "URL-line"; similar in concept to the Unix command-line, Meerkat's engine may be queried over the Web using combinations of various arguments.

The URL-line interface is rather common in the web-scripting world. A script's URL is postfixed with "?" and one or more "&"-separated "key=value" pairs representing variables and their associated values. With the emergence of CGI scripting, the URL-line became the Web's command-line interface. The URL-line is lightweight, bookmarkable, simple (hopefully ;-), and builds on the idea of a URL being a unique identifier for content on the Web, whether static or dynamically generated. But how does it fare in more complex applications with richer data requirements? And is there any consistency across URL-line APIs?

The RPC in XML-RPC stands for "Remote Procedure Call," a fancy way of saying that you're calling procedures (functions, subroutines, or methods) on another, remote, server. Just like a URL-line CGI script, arguments are passed and results returned; the difference is only in the serialization (the way it's written), which here, as the name suggests, is XML. XML allows for richer message-passing between client and server. For more information on XML-RPC, pointers to language implementations, and a quick read of the specification, visit XML-RPC.com.

Meerkat's XML-RPC API is a direct port of its straightforward URL-line recipes to an RPC environment. Written (as with the rest of Meerkat) in PHP, it uses Edd Dumbill's PHP XML-RPC modules. These provide simple, clean implementations of both client and server -- I highly recommend them!

Meerkat's XML-RPC server is at the URL: http://www.oreillynet.com/meerkat/xml-rpc/server.php

The server supports five methods: introspection, getCategories, getChannels, getChannelsByCategory, getItems. We'll go through each of these in detail. For demonstration and edification purposes, I've provided a link to Meerkat's live test suite for each of the methods.

Signature: array system.listMethods()
This method lists all the methods (including itself) that Meerkat's XML-RPC server knows how to dispatch. It returns an array of structs of method names, their signatures, and documentation.
[Test system.listMethods]

Signature: array meerkat.getChannelsByCategory(int)
Returns an array of structs of RSS channels in a particular category (specified by integer category ID), each with its associated channel ID.[Test meerkat.getChannelsByCategory]

Signature: array meerkat.getItems(struct)
Returns an array of structs of RSS items given a recipe struct. The getItems method makes full use of Meerkat's powerful recipes (read: query parameters). The following is a complete list of parameters from which to build a recipe:

Here's a simple PHP-based example, searching three days' worth of the xmlhack channel for any mention of XML or Java and returning IDs, descriptions, categories, channels, and dates. Only the latest five items are requested.

Sample 3: Python
An interactive Python session using PythonWare's xmlrpclib to search Meerkat for the latest five stories on Python. Descriptions, turned on by default, have been disabled for brevity's sake in this example.

Hopefully I've succeeded in providing an API that will be useful to you in building your application -- or just to fiddle with or learn from. As usual, I welcome any constructive criticism you might offer. Please post your suggestions, bug reports,
and other feedback (maybe praise?) to the
O'Reilly Network RSS Forum.

And, if you're so inclined, spread the Meerkat word with a nifty "Meerkat Powered!" button. To do so, simply copy-and-paste the following HTML into your document:

Rael Dornfest
is Founder and CEO of Portland, Oregon-based Values of n. Rael leads the Values of n charge with passion, unearthly creativity, and a repertoire of puns and jokes  some of which are actually good.
Prior to founding Values of n, he was O'Reilly's Chief Technical Officer, program chair for the O'Reilly Emerging Technology Conference (which he continues to chair), series editor of the bestselling Hacks book series, and instigator of O'Reilly's Rough Cuts early access program. He built Meerkat, the first web-based feed aggregator, was champion and co-author of the RSS 1.0 specification, and has written and contributed to six O'Reilly books.
Rael's programmatic pride and joy is the nimble, open source blogging application Blosxom, the principles of which you'll find in the Values of n philosophy and embodied in Stikkit: Little yellow notes that think.