"Holy mother of lock-in!" is my first knee-jerk reaction. Just catching up on the new Facebook platform stuff, and boy did they get it backwards. It's an improvement by miles over MySpace and little semi-hacked Flash includes, but man! Let's all climb in the trunk, eh? I need to let this stuff sink in more, maybe it's not that bad.

I guess part of my thing is, I don't live within Facebook. I keep meaning to do more, but the last online social network in which I really invested any serious effort was LiveJournal.

Checking into the Facebook API, among other things, has me thinking about web service APIs today. I'll probably be rambling in-progress throughout the day.

I first started getting excited about web services back around mid-2000 when I read Jon Udell's Practical Internet Groupware while on a plane to a Builder.com conference in San Francisco. Basically, he had the notion, almost as a sidebar, that CGI scripts returning HTML pages for people to view could just as easily return data for programs to process - and thus you could program against web apps. Brilliant. It was one of those bolts-from-the-blue moments for me.

The first real web service about which I got excited was the original LiveJournal "flat" Client / Server protocol. You could use this to do all kinds of stuff from a desktop client - post new entries, manage friends, etc. It was its own thing and followed no real standard but its own: RPC tunnelled over port 80 with calls expressed as POST'ed application/x-www-form-urlencoded parameters. Response data was name / value pairs, with names and values alternating on carriage-return-delimited lines. The mere existence of the API and the utility of LiveJournal itself made it worth coding to whatever was offered.

One of the next web services for which I went gaga was the Blogger API - and later the MetaWeblog API. And beneath the API was XML-RPC, which in comparison to the LJ API implementation was brilliant. It took advantage of XML encoding rules, and abstracted the expression of common scripting language data structures and function calls. Sure, it's verbose over the wire, but who cares? It's all wrapped in a library and dead simple to use. And, sure, it's got some things missing one might like to have like method introspection and such - but it got the job done, saved a lot of time, and lifted a lot of mental load.

Of course, one of my pain points with XML-RPC came in moments when I needed to debug by hand. Then, the over-the-wire verbosity made me dizzy, and it was mostly unmanageable unless I had some tool between me and the wire translating calls and parameters for me. I couldn't just run straight HTTP requests and "see the Matrix". An annoyance far outweighed by the alternatives, but an annoyance nonetheless. In the end, though, XML-RPC solved problems for me, professionally.

Eventually, I ran into some of my first SOAP web services. I can't remember many of note, mostly because I've willfully purged those experiences from my brain. Among other things, I used Google's search APIs for fun mashups, and even went a few rounds with Interwoven's Content Services SDK in recent years. Incompatible toolkits, incomprehensible XML, inconsolable sobs.

SOAP took all my pain points from XML-RPC, sharpened them, and invented plenty of new ones. My current working strategy for dealing with SOAP has devolved to this admitted stupidity: 1) Find some toolkit in some language somewhere that successfully speaks to the desired API; 2) come up with all the calls I'm going to use and capture an over-the-wire example of each; 3) build a simple client library in my desired environment that uses the over-the-wire captures as templates to POST requests. This strategy has thus far saved my butt on a few tight-timeline occasions involving SOAP calls from JavaScript, PHP, Perl, Python, and Java.

The one time I had a relatively good experience with SOAP: It was when we were using Microsoft products from end-to-end, controlled every end of every wire, and I slogged through Visual Studio to get anything done.

The next breed of web services that caught my interest were kind of back-to-roots, like those I found via Jon Udell and LiveJournal: Still tunnelling RPC over port 80, but much simpler. Just about everything shoehorned into a GET, function call parameters expressed as query parameters, but response data in XML. This describes most of the APIs offered by del.icio.us, Flickr, Yahoo! Search, Technorati, Amazon ECS and others. Much easier to deal with by hand than SOAP, and even XML-RPC. cURL from the command line is my baseline client of choice.

I (and others) call this style of web service "POX" - or plain-old XML. Many authors of POX-style web service APIs describe them as "REST", but they're wrong. In pretty much every mention of the term REST, they're wrong.

This might seem like cranky nerdery and hair-splitting, but there are some very specific things that make something REST-ful - and tunnelling RPC over port 80 via HTTP GET requests ain't it. What's confusing is that some POX-style APIs - mostly the ones that are read-only - coincidentally demonstrate REST characteristics. But, true REST (which I'll get to shortly) is not RPC - it embodies a different way of thinking about programming against the web, and really needs to not have become a marketing term for simple POX-style APIs.

Really, just stop saying your API is a REST API when it isn't. It's cool that you've got an RPC-over-HTTP-GET API that outputs XML, you can admit it. I'm happy you've got an API on the web at all, and that it's not done in SOAP.

The thing about POX-style web APIs is that you're back-to-basics again. They're oftimes very simple to implement on both sides of the wire, but each one is a little different and follows no standard but its own, like the original LJ API. The big improvement is that we've gone from name / value pairs on alternating lines to using arbitrary XML. The loss is that you no longer have the (albeit small) abstraction of name / value pairs, and most of these services are (ab)using HTTP GET for writes, whereas the original LJ API and XML-RPC at least had the courtesy to use HTTP POST.

Hello world. TGIF.