Click here to show or hide the menubar.

Home >  Archive >  2010 >  July >  20

Previous / Next

Realtime XML-RPC API
By Dave Winer on Tuesday, July 20, 2010 at 11:10 AM.

To restart the Instant Outliner, I needed the equivalent of FriendFeed's realtime update functionality.  permalink

It's really elegant, but I couldn't make my software depend on another service for update notification. I started to do it in REST and realized that I was reinventing a lot of what XML-RPC already did.  permalink

So I put aside the REST approach and went with XML-RPC.  permalink

A day later I had it working and a day after that I had the Instant Outliner converted. Unlike previous implementations this one works perfectly, is instantaneous and requires no polling. The long-poll approach works perfectly. permalink

I wanted to document this for the programmers who are testing the Instant Outliner, because the realtime updating functionality is more general, it can be used to connect our workgroup together in more ways than through I/Oing.  permalink

There are two entry-points, one to get the next set of updates, and one to push an update to the workgroup. Both assume there's an identity system in place that can independently determine if a username/password is valid. (The identity function hooks in as a callback.) permalink

Users can connect from more than one location at a time, each instance gets a complete set of updates. So I can leave my I/O app running at home and stay connected from a classroom or Starbucks. permalink

You can find the source for both the client and the server at builtins.realtime in opml.root. permalink

Here are the two entry-points: permalink

1. realtime.getUpdates (username, password) returns array of struct permalink

This is the long poll call. This routine doesn't return until: 1. There's one or more updates. 2. It times out.  permalink

If there are N updates, the returned array contains N structs. Each struct has four or five pieces of information:  permalink

1. htmltext -- a string that can be displayed explaining in verbiage what the event was. permalink

2. type -- a string that indicates how the update is to be processed. It's something a callback on the client can watch for. For the instant outliner, the type is "instantOutline." permalink

3. when -- the date/time the event was posted. permalink

4. username -- the user who caused the update.  permalink

5. data -- optional, it's up to the poster of the event what it contains. In the instant outliner, it's the OPML text of the outline that updated. permalink

If there's an update waiting it returns immediately. permalink

The timeout period is up to the server. I have mine set to time out after 180 seconds. When it times out, the array returned has 0 elements.  permalink

After receiving an update, whether it was an error or not, the caller should loop back and make another update call.  permalink

2. realtime.pushUpdate (username, password, htmltext, type, data) permalink

The other side of the updating mechanism. Each user that's listening receives a copy of the update struct, which is returned when they next make a request to be updated. permalink

RSS feed for Scripting News
This site contributes to the community river.

© Copyright 1997-2012 Dave Winer. Last update: Tuesday, July 20, 2010 at 3:18 PM Eastern. Last build: 8/26/2012; 5:50:56 PM. "It's even worse than it appears."

RSS feed for Scripting News

Previous / Next