Xaprb

I usually keep pretty quiet on things that are controversial, and goodness knows you can start a holy war fast with any comments about REST web services. But I’ve been thinking and working on these things for years — REST for over a year, SOAP and friends since 2003 — and maybe my opinions will be interesting to someone.

I dislike SOAP. I’ve worked a lot with it, doing about a dozen major integrations with platforms from companies like Amazon, Google, and Yahoo, using several different programming languages, primarily .NET languages and Perl. I have never worked heavily on the server side with SOAP; I’ve always been a client. From the client side it’s bad enough, and I do consider myself pretty fluent with most of the standards, though some of the WS- standards never were relevant to me. Regardless, I used to be able to read a raw WSDL for a complex service like Adwords, and tell you exactly what XML you needed to send and what you’d get back (primarily because the SOAP libraries available never worked right, and I had to write my own in both C# and Perl).

What’s wrong with SOAP? Complexity. SOAP (and XML in general) is a sledgehammer to crack a nut. It does, however, provide a lot of nice features. You can in theory develop tools for every step of the process: to generate WSDL, write code for servers and clients automatically, and so on. SOAP works, and it generally works well with minor problems caused by quirks of some client libraries not working well with some server implementations (the .NET SOAP libraries never worked right with the WSDLs from Amazon’s early merchant integration services, though they were valid). SOAP is not the most efficient thing that could ever be done, both from the computing and from the human standpoint. You can theoretically do that with other technologies too, but SOAP is the most obvious success story to illustrate (Thrift, CORBA, Protocol Buffers, etc could also be mentioned — but they are not apples-to-apples in this discussion). SOAP is just too heavyweight. I always thought there needs to be something more straightforward and efficient that achieves the same goals.

I’d heard about REST but never looked into it deeply until a couple years ago, when I gained a passing familiarity through some adjacent technologies. Around a year ago I got involved with writing a set of web APIs (I’ll avoid calling them REST APIs) and worked a little more closely to REST. I quickly learned that I didn’t know much, and most of my assumptions were gently shown to be wrong by other team members. But as I learned more, I decided I don’t like REST either.

What’s wrong with REST? Naivety and idealism. No matter how much we dream the dream, things are not self-describing and infinitely fluid, and people seem to fall in love with the “elegance” of HATEOS (which is one of the least elegant acronyms ever created, on any level). When you write a client against a service, the client and all of the systems it’s connected to represent an ossification of some ideas about the interface the service exposes.

An interface of any type is a contract, a promise to the world. The client trusts the promise, and if the promise changes, the client’s code and persistence structures must change to match. The “semantic web” is a wonderful daydream for the day when computers understand “meaning,” but for the time being, very few real useful systems I’m aware of are in the habit of persisting and working with information that might or might not contain anything or nothing in any or no structured format. REST APIs are supposed to somehow be magically discoverable and traversable on demand — “want to know what’s available through the API? Browse the API and see what you find!” This is completely unrealistic. If it were realistic, then why does every REST API have documentation that tells you what you’ll find when you browse the API, and what it means? QED.

Another bit of idealism is the use of HTTP verbs exclusively. HTTP verbs aren’t sacred and somehow sufficient for everything. Designing to four primary verbs encourages a tremendously simplistic (actually, very complicated in subtle ways) worldview of what an efficient API does. Most quasi-REST services I’ve seen (there are very few that really follow the rules) would force one-at-a-time loops over operations involving a lot of data, for example. They were designed by people who’d never heard of the fallacies of distributed computing.

All of this has been said by many others, and probably more succinctly. What do I have to contribute? Only this: to point you to a good design.

I believe that one of the best service designs I’ve ever seen is the Google Adwords API. It uses SOAP, but that’s just a transport — it’s not important. What’s important is the design. It’s made for efficiency on a very large scale — on both the client and the server side — and to work well with a large variety of client platforms, including Javascript in the browser. It uses batch operations nearly everywhere, and sensibly distills the verbs down to “read” and “write.” (Okay, they call it “get” and “mutate.”) The Adwords API actually doesn’t resemble early versions very much — I’ve been writing client code against it since 2004 or so — and the evolution of its design is a case study in large-scale API design.

About a year ago I was cooking up a hybrid of JSON over HTTP, with many design decisions influenced by Adwords’ design, and called it WORK (as opposed to REST, and because I wanted something that would work). The definitions of the operations and data types (yes, I do believe data types and operations should be predefined and agreed-upon, not discovered dynamically because that Just Doesn’t Work, as explained previously) were all written into a small JSON file. This served as an IDL that could, in theory and mostly in practice, be used to autogenerate client and server code. I didn’t see that project through to completion, but it remains an approach I’d use again in the future.

So, in conclusion I would not recommend that anyone try to develop a REST web service. I’d recommend something more like RPC-over-JSON-using-parts-of-HTTP. This is what most so-called REST services really are anyway. I don’t care if anyone calls them REST, but Roy T. Fielding does, so out of respect for him I’ll use the terms somewhat carefully.

If you’re in the DC area, there’s an emergency meeting of the DC Tech Meetup to get involved in advocating against SOPA and PIPA legislation.

If you can’t make it in person, you can use the EFF’s online form to write your representatives about SOPA and PIPA.

Don’t wait until it’s too late. The Internet is a vital part of our freedom. Well-intentioned legislators could damage that greatly while trying to solve problems they don’t understand fully.

I bought a Barnes and Noble Nook Color e-book reader and ripped out the Nook software, replacing it with the CyanogenMod distribution of the Android OS. It’s really, really nice hardware, and CyanogenMod (CM) is really, really nice software. I love them both, and my regular readers will remember that I’m not a gadget guy. Read on for more.

I never thought I’d get a tablet, until my phone died and I got a Droid 2 as a replacement. With all those gadgets, I just started to find myself using my phone for reading my RSS feeds and so on — but hating how small the screen was. I started to think again about a tablet after experiencing how handy the smartphone’s extra features are.

The Nook Color Hardware

The Nook Color is a medium-sized Android tablet with a screen that’s the same size as the Samsung Galaxy Tab. It’s a perfect size for carrying around — much better than iPads and Xooms and so on, which are just too big for my taste. This device literally fits in the pocket of my jeans (specs).

The screen is amazing. It’s super sharp. But the Nook Color doesn’t have a microphone or a camera, and it doesn’t have any phone service. This is fine. I don’t want these items. I want a tablet to use primarily at home for consuming content such as blogs, books, newspapers, music, movies, and so on.

The best parts: 1) it’s way cheaper than a Galaxy Tab or similar tablets. It’s $250 at the store. And 2) it’s really easy to take off the stripped-down version of Android that comes with it, and put something better on it. Which brings me to my next point.

The Software

When you unpack the box, the Nook has a pretty nice little e-reader installed, with a simplified Android interface. It has limited functionality, which is fine. It does have a web browser and a couple other things, and BN recently added their own application store. But it’s really kind of lame. You can only get a small fraction of the apps that you could get through the Android Market.

I updated to CyanogenMod in two stages. First, I simply rooted the device and made it possible to install arbitrary apps from the Android Market. There’s a nice, easy process to do this. It’s called Manual Nooter. I tried this first instead of just going to CyanogenMod because I wanted to see what it was like. It was okay, but it was really obvious that it was a sort of layer on top of the underlying Nook. Pressing the Home button, for example, brought up a prompt to use the Nook home screen or the hijacked home screen for the new software. I tinkered around with this for a while, enough to determine that I didn’t like the patched look and feel. At the same time, I learned that the applications I wanted would work just fine.

So I moved on to CyanogenMod. Early reviews I’d read of this said it wasn’t ready for prime time on the Nook, but the newer updates seemed to be well received. So I backed up everything and took the plunge.

It’s really ridiculously easy to install CyanogenMod on the Nook, even easier if you don’t first update your Nook operating system. It took me longer to burn a bootable ROM on a MicroSD card than anything else. Full instructions can be found beginning at this page.

The result is just brilliant. I’ve now installed my preferred apps, stripped down the interface by removing some stuff I don’t want, such as multiple desktops (CyanogenMod is jammed with features), and I have a simple, elegant, perfectly functioning Android tablet. And I really mean it — there are no rough edges or crashes or anything you might expect from a third-party OS on your tablet. In fact, one of the things I like the most is that it doesn’t come with pre-installed adware, as my Droid did (and the stuff on the Droid can’t be uninstalled without rooting it and voiding the warranty, which is not something I’m going to do on my work phone).

Summary

If you want a small, light, thin tablet with WiFi that you can hold in one hand for reading books and newspapers and so on, which is easy to put in a pocket or purse and carry with you, and doesn’t cost much, then consider the Nook Color. If you want to turn it into something much more full-featured, then consider ripping out the Nook software and replacing it with CyanogenMod. The result is really superb.