You can hardly mention the terms API or REST without tripping over some developer’s rant about which API’s are RESTful and which are not. Frankly, I’m running out of reasons to care. Standards and paradigms are tools, not goals. So to everyone still debating over what is and isn’t RESTful I say, “Your mom’s API isn’t REStful.”

Get to the Point

Here’s the deal: we develop API’s so serve real-world needs, not to meet standards. Now, don’t get me wrong. Standards-compliance is a good thing. It just isn’t the be-all-end-all. If we build a perfectly RESTful API that doesn’t meet our users’ needs, we have failed.

If you’ve followed the REST discussion for any length of time, you’ve seen the term HATEOAS (Hypermedia As The Engine Of Application State). It’s a mouthful to say and even more to explain in detail but it wraps up my point nicely. The gist of HATEOAS is leveraging HTTP to its full extent for developing API’s. Here we come to the main point:

Using HTTP for all it’s worth is more important than being RESTful.

So we don’t miss the forest for the trees, let’s consider some practical use cases. The most common use case in my experience is pulling content from a website to a mobile app or another website. Conceptually, it’s a more robust alternative to using RSS feeds. Naturally, we’ll group our content into resource types and use simple, declarative URL’s with HTTP verbs to indicate our clients’ intent to the server. We’ll then return our content in the body of the response as a nicely formatted JSON or XML Document.

Does it Work in a Browser?

So far, our our API is sounding nice and RESTful(ish). But here’s our first difficulty: browser support. Browsers generally only support HTTP GET and POST requests (easily, at least). The simple fact is browsers aren’t built for consuming RESTful API’s. If you’re stuck on browser support, you probably aren’t building an API. You’re probably building a website. API’s are meant to be consumed by applications. Websites are meant to be consumed by users, and yes, submitting a web form involves a user.

So can an API and a website (or web app) coexist? Well, yes, so long as we’re clear on the distinction. Consider our example, ignoring other concerns like authentication and cross-origin resource sharing for now. GET-ing json-encoded content from another website’s API is simple enough with AJAX. POST-ing new json-encoded content from our web form takes some effort but can be accomplished by replacing the typical form submission with another AJAX call. With a little more effort, we can also send PUT and DELETE requests for updating and removing content. Alternatively, we could skip the front-end scripting and make server-to-server API requests from our back-end. In that case, the receiver for our web form can interact with the API via cURL or other similar libraries.

Get (Back) to the Point

So this wasn’t really a tutorial. This was a rant from a developer in the trenches. Take it or leave it, but here are my contentions:

1. HTTP (HATEOAS, if you prefer) is more important that REST.
2. An API is not a website (and vice verse).
3. Websites can consume API’s with a reasonable amount of effort.