How Radio talks to a Community Server

It seems that a lot of people are confused around about how Radio talks to a community server (RCS, PyCS or PSS).  Here is an attempt at an explanation.  Sorry Robert, I broke your quote ;-)

First - there is no 'Radio protocol' as such.  After the initial handshake, everything is very general and open.  99% of the work goes on using xmlStorageSystem, which is trivially accessible from any system supporting XML-RPC.

Protocol

Everything runs over XML-RPC.

The URI is http://server/RPC2 for RCS and PyCS, and http://server/XMLRPC.php for PSS.

Namespaces

Three namespaces are used:

radioCommunityServer

This namespace has only one method: getInitialResources.  Radio calls radioCommunityServer.getInitialResources when you change community servers.  This method returns a list of 'resources'.

All implementations return the URL to the comments page (e.g. http://radiocomments.userland.com/comments or http://www.pycs.net/system/comments.py).  This is to allow Radio to form comment links automatically.

RCS will let you set up your own  templates (themes).  When a new client connects to your RCS, it will send info on the local templates in response to a getInitialResources call.  This isn't implemented in PyCS or PSS; if someone wants to figure out what the proper responses look like (or just give me an example wire dump), I'll plug it in.

xmlStorageSystem

This is where most of the work happens.  xmlStorageSystem has a reasonably up-to-date spec on soapware.org.  There is also a directory of implementations.

To register on the server and get a usernum, it calls xmlStorageSystem.registerUser.

When Radio sends files to a server, it calls xmlStorageSystem.sendMultipleFiles.  To delete, it calls xmlStorageSystem.deleteMultipleFiles.

It periodically calls xmlStorageSystem.ping and xmlStorageSystem.getServerCapabilities to keep up-to-date with what's going on on the server.

The following functions are implemented in RCS but not PyCS or PSS:

xmlStorageSystem.getMyDirectory (not used in Radio 8) returns the contents of the user's directory.

xmlStorageSystem.mailPasswordToUser sends an e-mail to the user containing their password.

xmlStorageSystem.pleaseNotify is the entry point for publish-subscribe, a way to get the server to call your client back when a resource that you are interested in changes.

A note on passwords:

The value in the 'password' field in many of the xmlStorageSystem calls is not the plaintext password that you give Radio, but rather a hex digest of an MD5 hash of it.

In Python, this can be computed with md5.md5( password ).hexdigest().

Note that this means that if someone sniffs your packets, they can impersonate you to the xmlStorageSystem server, but they will not know the password you use on your local system.

weblogUpdates

This is called when your weblog changes, after it has been upstreamed to the server.  It tells the server that the weblog should be placed at the head of the 'recently updated' list.

This interface is documented at weblogs.com (it's the same one that you use when pinging weblogs.com).

Other clients/servers

A 4S4C SOAP implementation of server side xmlStorageSystem.

A JavaScript client by Sjoerd Visscher.

Other notes

Charles Miller has some wire dumps.

Some people have had a go at RESTifying xmlStorageSystem.

If I've made any mistakes or any of this is out of date, please correct me!  To get in touch, click on the yellow envelope icon at the bottom of the page.

Comment on this.