REST is the new SOAP

I author REST APIs and try to do them properly, with mediatypes, link relations, and all the good hypermedia stuff most people avoid. Nonetheless, the author's post reflects the sort of rant I've had to coworkers at the watercooler, or anyone who'd listen.

The author nicely preempts the debate about HATEOAS and "most RESTful APIs aren't REST" and shows that the debate is part of the problem. It is. It's not a spec but an architectural style, and people are bad at design (and quite honestly, they have better things to do with their time), so broad-stroke ideas about how to lay out your system aren't as useful as a framework or codegen. So the least-effort solution wins, where you half-ass implement first three three characteristics of REST-as-seemingly-observed-in-the-wild (HTTP, JSON, templated URLs), and call it a day. If it's good enough for Stripe and Twitter, it's good enough for you.

No wonder we're in this boat; one upon a time REST was just architectural and intellectual wankery, specified in an obtuse and hard-to-read thesis by a guy who's smarter than most of us combined. It sat unknown for years, until AJAX became all the rage, and people began making API calls from jQuery to load-and-splice parts of a page for rich interactivity. Here, a public, HTTP endpoint that served easily-parseable JSON made sense. Some prominent companies released public APIs in this style, and then the blogspam began.

Within a short amount of time, REST and "RESTful" was cool and forward-looking, and SOAP was old and crufty, and any kind of ad-hoc RPC was bad. Implementing a REST API wasn't solely about usability, but also signalling that your company was forward-looking too, rationality be damned, which is why most implementations cargo-cult look the same: HTTP, schemaless JSON, templated URLs. Endless debates about HATEOAS begin, and come to an unsatisfying conclusion, because real developers' concerns about architectural purity are dwarfed by their desire to build a mostly-working API that looks recognizable to the public, and move on.

Serious players looking for reliable internal RPC develop stuff like Thrift and gRPC, which are thoughtful reimplementations of the ideas behind 80s and 90s RPC, but with the added advantage of coming from a single vendor and not committee hell. Meanwhile, Facebook also reinvents SQL in JSON and gives it to the client, what could go wrong?

Maybe the reason "REST" won is because it was easy to glean and misunderstand well enough to put out something simple and good enough. This dominance of the low-end is going to be hard to undo.

It lacks conventions thoug so every api is more quirky and even sloppier than a bad REST api. At least with REST there’s some existing structure and it’s not completely up to the imagination of someone in a hurry.

It occurs to me that young people may be better at bootstrapping in a scrappy way, because they don't yet have the knowledge and experience to immediately consider all the things that would be required in a mature implementation. Speaking for myself, now that I'm approaching middle age (37), if I contemplate developing a new product from scratch, I risk paralysis by analysis, overthinking every aspect of it. I certainly didn't do that when I was 21.

Scrappy bootstrapping is a double-edged sword. On the one hand, it brings us great new products. On the other hand, ignoring some real-world concerns can be a major problem for users. As just one example, consider the impact for people with disabilities (e.g. blind, mobility impaired) who need to use an app that was developed with no regard for accessibility. And I've blissfully ignored other real-world concerns myself. For instance, the first desktop app that I worked on (in my 20s) had no support for HTTP proxies (as often found in corporate networks back then).

REST is like Agile. Almost everyone who claims to do it only kind of do it, and those who really do it get all wrapped up in the theology of it and turn it into an unworkable mess.

REST allows you to make decisions about the http interaction out-of-band, where SOAP provides (and often requires) the ability to describe all decisions about types and parameterization and exception cases in-band.

The REST way allowed one to get started with something small and simple that people could agree to just by talking it over together. With SOAP you had to make all those decisions up front and put it in the specification. I believe SOAP is so complex that it's an analog to CORBA/IDL.

REST is (at least initially) simpler and less specific than SOAP. That's its strength.