I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.
REST APIs must be hypertext-driven
Roy Fielding writes a PhD dissertation describing the architectural style of the World Wide Web. He coins the term ‘Representational State Transfer’ (REST) to describe it – after all, if you’re going to talk about something, you need to give it a name. Somehow, in a semantic shift of epic fail proportions, the term REST has also come to mean something completely different to most people, a ‘style’ of writing web services. This style has no agreed protocol.
I made the mistake of publicly commenting on someone's idea of a RESTful API. And already - I've probably lost you. I don't know any single term more explosive and zeal-inducing than REST and "what it means to be RESTful". Oh - you say "it's quite simple?" You say "what's so hard?" Pedanticize away my pedantic pedant...
At Braintree, we receive nearly 1.5 million API calls per day from thousands of our customers. Instead of a public REST API, we provide client libraries in seven languages to ease integration with our gateway. This covers almost every modern web application language. Using our Java library, we can also reach other JVM languages like Clojure and Scala. As you can imagine, these libraries are built on top of a REST API. Occasionally we are asked why we don't document and expose the REST API, and this inevitably sparks a discussion on our team about the tradeoffs. During these discussions there are three topics that often come up: Security, Platform Support, and Backwards Compatibility. These three topics have kept us in favor of providing client libraries instead of direct access to the low level API.
Every time someone mentions RESTful web services, there’s always that one person that has to chime in: “That’s not really RESTful, it’s just kinda RESTful.” I’d always filed that information away, under ‘things to learn later,’ and let it simmer in the back of my brain. I’ve finally looked into it, and they’re absolutely right: 99.99% of the RESTful APIs out there aren’t fully compliant with Roy Fielding’s conception of REST. Is that bad?
Let's talk about a few cases where either REST or HTTP (which is clearly RESTful in its design) solves a common web development problem.
Nobody Understands REST or HTTP
Ever since Twitter built their “New Twitter” UI on top of their existing API, the idea of incorporating the very same philosophy into my own applications resonated with me. I decided to move forward with the same approach and my team and I been doing so since September. For those of you that have not taken this route, what I’d like to do is share some of the reasons why you may want to, and some advice on how to make it relatively painless.
Why and How You Should Write REST-Centric Applications
It’s been over a decade since Roy Fielding wrote his seminal dissertation on Representation State Transfer (REST). Over this period we’ve seen SOAP/WSDL fall out of favor as the cool kids transition their services over to the REST paradigm. Or so it seems on the surface.
In reality, we’ve spent the last 10 years building various ad-hoc services over HTTP that borrow bits and pieces from the grand vision that Roy outlined. We’ve settled into a rhythm that, depending on your outlook, is either a naive implementation or an enlightened massaging of the initial approach. Is the glass half empty, or half full?
Roy Fielding has weighed in on the recent "buzzwordiness" (hey, if Colbert can make up "truthiness", then I can make up "buzzwordiness") of calling everything a "REST API", a tactic that has become more en vogue of late as vendors discover that the general programming population is finding the WSDL-based XML services stack too complex to navigate successfully for all but the simplest of projects. Contrary to what many RESTafarians may be hoping, Roy doesn't gather all these wayward children to his breast and praise their anti-vendor/anti-corporate/anti-proprietary efforts, but instead, blasts them pretty seriously for mangling his term...