Programming Web Services with XML-RPC

July 18, 2001

Simon St. Laurent, Joe Johnston, and Edd Dumbill

Chapter 5 (Excerpt)
Integrating Web Applications: XML-RPC in PHP

Editors' note: This excerpt from O'Reilly & Associates' recently published Programming Web Services with XML-RPC

Connecting Web Applications


			Programming Web Services with XML-RPC By Simon St. Laurent, Joe Johnston & Edd Dumbill Foreword by Dave Winer June 2001 0-596-00119-3, Order Number: 1193 230 pages, $34.95

The following sections explore using PHP to integrate two web applications into one interface. The first section demonstrates how to create a complete PHP XML-RPC server application, in this case a discussion server. The web application to which this server will be connected is a database called Meerkat, the brainchild of Rael Dornfest and O'Reilly & Associates, Inc. (who also happen to be the publishers of this book). Meerkat is a storehouse of news about technological developments. After a subsequent section that gives an overview of Meerkat, the chapter demonstrates how to integrate the database with the custom XML-RPC discussion server.

Creating a Discussion Server

A feature of many successful web sites and online applications is the ability to annotate, or provide comments regarding, on-site content. Unfortunately, it can be hard to obtain software supporting this feature that will integrate in the way you wish, often due to rigid user-interface constraints.

In this section, we attempt to solve this problem by creating an XML-RPC discussion/comment server. Because the interface is XML-RPC, you will be able to integrate it into your own applications without sacrificing the feel of your user interface.

The first task is to design the API. In the spirit of doing the simplest thing that works, this example application uses a straightforward interface. All items that can be commented on are identified by a string ID--this might be a URL, for example, or just a number corresponding to a database record identifier. Here is the API:

discuss.addComment(item_id, person_name, comment): This method adds a comment to the item specified by the item ID. It also records the name of the commenter against that comment. All three arguments are strings.
discuss.getComments(item_id): This method returns an array of structs; each struct corresponds to an individual comment and has two members: "person" and "comment."

This minimal interface allows a basic form of annotation to be added to web applications. Example 5-2 shows the listing of the server script that implements the interface. A simple file-based database is used to store the comments.

Note that the server uses Berkeley DB2 databases, so your installation of PHP must be compiled with support for this.[4] The web server must have write access to the directory where the database is stored. Windows users also have to change this directory to something like C:\TEMP.

4. Berkeley DB is now known as SleepyCat DB; see http://www.sleepycat.com/ for more information.

Meerkat: O'Reilly's Technology Database

The Meerkat web application (http://meerkat.oreillynet.com/) is O'Reilly & Associates' database of headlines from technology sites around the Web. (O'Reilly & Associates is known, among other things, for the animal-themed cover designs of the books they publish. Meerkat's name carries on this tradition among O'Reilly's online offerings.) The Meerkat database aggregates the title, description, and URL of technology news stories and other resources from XML files, using the RDF Site Summary (RSS) format.[5] Each site creates an RSS file, which Meerkat retrieves and adds to its database. Meerkat organizes the web sites ("channels") into categories, according to the subject matter they cover. Figure 5-1 shows a screenshot of Meerkat, displaying stories in its "XML" category

In addition to its web interface, Meerkat provides an XML-RPC interface that gives access to its content. A well-structured PHP program normally abstracts its functionality into classes, which contain the program logic and separate activation of those classes in conjunction with HTML markup. XML-RPC for PHP can take advantage of that structuring, enabling you to add a web application interface easily by writing simple wrappers for your existing program logic. Meerkat is an example of an application that has done just that.

**Figure 5-1.** **Meerkat showing stories from its "XML" category**

Meerkat's interface offers the following methods, three of which are used in Example 5-3:

meerkat.getCategories( ): Returns an array of structs of available Meerkat categories (member "title"), each with its associated category ID (member "id").
meerkat.getChannels( ): Returns an array of structs of available RSS channels (member "title"), each with its associated channel ID (member "id").
meerkat.getChannelsByCategory(category_id): Returns an array of structs of RSS channels in a particular category (specified by integer category ID), each with its associated channel ID.
meerkat.getItems(recipe): Returns an array of RSS item structs, given a "recipe" struct. See http://www.oreillynet.com/pub/a/rss/2000/11/14/meerkat_xmlrpc.html for Meerkat info.

5. Resources and tutorials for RSS can be found on the O'Reilly Network Syndication DevCenter at http://www.oreillynet.com/rss/.

Joining Meerkat and the Discussion Server

Now we have two XML-RPC applications at our disposal: Meerkat, to explore stories on web sites, and our discussion server, which can annotate arbitrary items as long as they can be given a string identifier.

PHP and XML-RPC can be used to synthesize these two applications into a new one, allowing spontaneous discussions to take place around news stories. Figures 5-2 and 5-3 show the user interface for such an application. Users can browser Meerkat's database, and whenever stories that have comments are found, the comments are displayed against them. A link gives the option to add a comment to a story.

**Figure 5-2.** **Browsing Meerkat stories with comments**

**Figure 5-3.** **Comment form**

Example 5-3 gives a complete listing of the code required to build this application.

A Closer Look at the Meerkat Discussion Server


			Programming Web Services with XML-RPC By Simon St. Laurent, Joe Johnston & Edd Dumbill Foreword by Dave Winer June 2001 0-596-00119-3, Order Number: 1193 230 pages, $34.95

After reading this chapter, there should hopefully be no surprises for you in the Meerkat discussion application. It is a purely client-based application, creating two xmlrpc_client objects: one for Meerkat and one for our discussion server. However, there are some features worth noting:

The dispatch( ) function wraps all the common error handling required in processing XML-RPC method calls. It may prove useful in your own programs.
The application uses a naïve implementation. Within one invocation of this script, many XML-RPC method calls are generated. HTTP connections are slow to create, and thus it is advisable to make as few method calls as possible within one script. Several tactics could be used to reduce this overhead, such as:
Redesigning the server API to return more data per method call. The discussion server might be redesigned so that discuss.getComments( ) accepts an array of IDs as its argument and returns an array of arrays holding the comments for each ID.
Caching returned results. In our application, the entire list of categories is retrieved each time, regardless of whether it has changed or not. For data that changes infrequently it may be acceptable to cache data, once retrieved, for the rest of the user session. One way to do this in the discussion application would be to use frames to separate the category, channel, and story lists, and to add some JavaScript to enable the frames to interact with each other. This would entail reorganization of the PHP script to support this new architecture.

In general, it is not wise to include many XML-RPC calls in applications that require rapid user feedback--although many factors, such as server load and network conditions, obviously affect this decision.