How to access UserLand's DGs thru XML-RPC

Fri, Aug 27, 1999; by Dave Winer.

XML-RPC Interface

This document describes the XML-RPC interface implemented by UserLand discussion groups.

With this interface you can create a workstation editor that's not browser based, allowing you to create and edit messages with more advanced text editors than the ones built into web browsers.

This is an open specification. Of course we welcome all text editors to hook in from the workstation side, but we also welcome compatibility on the server side. We want competition to help to define a new standard and with that a new market for net-aware writing tools and servers that manage content created with those editors.

System address

Send your XML-RPC messages to: www.xmlrpc.com, port 80, path /RPC2.

For now this is the only UserLand server that's open to these calls. As we move forward we will open all UserLand-hosted DGs. We want to mature the spec here and only here.

Common parameters

All the handlers require three common parameters: dgname, username and password.

dgname is the name of one of the discussion groups hosted on the server. The dgname for this site is xmlRpc. A dgname can be arbitrarily long, and follows syntactic rules set by the server.

username and password are a valid combination in the membership database. They are the same as would be transmitted thru a cookie to give the user permission to edit or save a message. As with the dgname, the syntax and size limits on username and password are set by the server.

When you create a message, username is stored with the message. For UserLand servers, username is always a mail address, but this spec doesn't require that it be a mail address.

msgnums

Some of the handlers, but not all, use a parameter called msgnum, or return msgnum as part of the returned struct. While the msgnum name indicates that it's a number, it could also be a string, possibly containing non-numeric characters. Editorial interfaces should not do arithmetic on msgnums, just pass them back to the server as they were given to you. Any 7-bit ASCII character can be present in a msgnum.

Creating a new message

mainResponder.discuss.newMessage (dgname, username, password, title, body, inResponseTo)

This handler takes three extra parameters, the title of the message and the body of the message, both of which are strings; and inResponseTo, which is a number. If you want to start a new thread, set inResponseTo to 0.

title can be empty if inResponseTo is non-zero. In that case, we assign the title to the message, by inserting a "Re:" at the front of the parent's title, if and only if it doesn't already begin with "Re:". If the title is empty and inResponseTo is zero, a <fault> occurs.

As with all the other handlers, username and password must be a valid combination, ie there must be a user with the indicated name, and password must be the password for that user.

newMessage returns a <struct> containing msgnum, the number of the new message; url, the location on the server where the message can be viewed; and title, the title of the message.

Editing an existing message

mainResponder.discuss.editMessage (dgname, username, password, msgnum)

Returns a <struct> containing the title, body and url of the indicated message, provided the username and password pair are valid.

Saving a message

mainResponder.discuss.saveMessage (dgname, username, password, msgnum, body, title)

Stores the message in the discussion group database. Returns a <struct> containing the url and title of the message, and lastsave, a date/time at the server when the save was performed.

Attaching an enclosure

mainResponder.discuss.attachEnclosure (dgname, username, password, msgnum, enclosureType, enclosureBits, enclosureAddress)

Adds an enclosure to the message indicated by msgnum.

enclosureType is a mime type, enclosureBits is the base64 encoded binary data, and enclosureAddress indicates where the object should be stored when the object is downloaded. It can be an object database address (a dotted id) or any kind of string that will be understood by software on the user's machine when it is downloaded.

The DG server need not be able to display the data, but it's great if it can.

All handlers return <struct>s

We chose to return <struct>s instead of values so that we could expand the flow of information back to the workstation without breaking apps or requiring more complex interactions.

We expect the workstation software, if at all possible, to retain all information we send back, and provide a reasonable user interface. For example, you should store the URL to display the document in a web browser. This is a pretty important bit of functionality.

And it will be nice to have a broad pipe going back so we can add features as we think of them, again, without breaking apps.

Amusing note

I am using an editor that complies with this spec to write this spec!

Pointers

See An XML-RPC interface for XML-RPC.COM for background.