Prefs Distribution thru XML-RPC

Sun, Sep 19, 1999; by Dave Winer.

Prefs Distribution thru XML-RPC

Suppose you have a website that is distributed across several machines, perhaps geographically, with some or all of them serving dynamic pages with per-user customization. You want to provide a single place for the user to set preferences and have the changes percolate to the other servers on your internal network.

We had to build such a prefs distribution network for UserLand.Com, and naturally we used XML-RPC to implement it. Because we used XML-RPC, Frontier applications can be mixed with applications running in other environments that support XML-RPC.

The interface is easy to implement once you have an XML-RPC layer running. It consists of a single RPC handler, updateMemberInfo, on each of the affiliate machines. It's a little more complicated on the prefs hub -- it has to implement a database of affiliated machines, and call each machine when a preference is updated.

About this document

This document describes the protocol strictly in XML-RPC terms.

Example

Here's a full XML-RPC request that sets four values in Bull Mancuso's record in the default membership group.

<methodCall>
	<methodName>updateMemberInfo</methodName>
	<params>
		<param>
			<value>default</value>
			</param>
		<param>
			<value>bull@mancuso.com</value>
			</param>
		<param>
			<value>
				<struct>
					<member>
						<name>appearance.alink</name>
						<value>pink</value>
						</member>
					<member>
						<name>appearance.bgcolor</name>
						<value>beige</value>
						</member>
					<member>
						<name>appearance.link</name>
						<value>navy</value>
						</member>
					<member>
						<name>appearance.text</name>
						<value>black</value>
						</member>
					<member>
						<name>appearance.vlink</name>
						<value>teal</value>
						</member>
					</struct>
				</value>
			</param>
		</params>
	</methodCall>

Membership groups and users

This protocol assumes a membership environment composed of groups of people. Each group has its own set of members.

A group is specified by a string of arbitrary characters, known as a groupname. If you need a single membership group, we suggest, but don't require that you use the name default for the membership group.

username is a string of characters identifying a user. It could be a mail address, a screen name. It's a convention that must be established in each network. As an example, UserLand.Com uses a member's email address as the identifier.

The combination of groupname and username completely specify a record in the membership database for a single user in a single domain.

What's in a Record?

A record is a name space. It may be hierarchic, allowing names like appearance.text, or personalInfo.biography; or it may be flat, without structure.

The namespace can be dynamic, meaning that if a name that hasn't been defined in a record, storage for the name is automatically created when the value is set thru updateMemberInfo.

The types of data stored for each name are the same types as supported by XML-RPC, including <array>s and <struct>s.

updateMemberInfo

updateMemberInfo (groupname, username, rpcParamTable)

groupname and username together identify a record in the membership database.

rpcParamTable is an XML-RPC <struct> containing values that are to be updated in the member's record. The name of each item in the <struct> is the name of a field in the member database. The value of each item in the struct is the value to be assigned to that field.

updateMemberInfo returns true if it was able to set the membership information, it <fault>s if there was an error.

Notes

Allowing the groupname to be specified makes it possible for a network of servers to manage several domains that don't share user profile information.

It's recommended that you secure your updateMemberInfo handler so that it only accepts calls from a single server, based on IP address, or very small range of servers.

Any kind of information that can be transmitted by XML-RPC can be transmitted thru this protocol, so complex structures and arrays, pictures and other media types can be encoded in XML-RPC messages and stored in membership databases.

Evangelism/Pointers

We imagine that an affiliate could easily be written for ASP, PHP, Cold Fusion, Zope, etc. If we could get compatibility between all those environments, we'd really have something cool!

We have provided implementations of both sides of this protocol for Frontier installations.To see how this prefs distribution works in Frontier, and for example source code, see this page on the Frontier site.

UserLand's preferences server, Prefs.UserLand.Com, uses this protocol.

In August 1999, we published a specification for connecting text editing tools with discussion group software.

If you have questions, comments or suggestions post a response here, or on the XML-RPC mail list.