Why REST APIs aren’t that great

You’re a developer. You’re using to simple RPCs (Remote Procedure Calls) to communicate with your database server, which is behind a HTTP server. And someone tells you “Hey, you should make REST web services.”

You spend a week researching and crafting up your first RESTful API to replace your existing API… and find yourself really no better off than when you started, except maybe the buzzword junkie you work with is super-happy now.  What went wrong?

In theory, REST means one thing. In practice, it means another.

Chances are, the API you had was mostly, technically RESTful to start with.  You have your GET, CREATE (POST), UPDATE (PUT/PATCH), and DELETE custom-application methods, and you didn’t have to think nearly half as hard about designing it.

The major difference is that REST must be thought of in terms of acting on resources, and I would argue that it favors flat, not nested, resources.  Some resources are incredibly complicated and will require much more design than previously.

Surprise!  You are now tied to HTTP.

As it stands, REST, in practice, requires intimate knowledge of HTTP workings: methods, query parameters, response codes, reason phrases, content types, message headers – not to mention, a serialization format (or two, or three…) for the actual payload.

This is OK if you’re building a web application and you have a team full of web-conscious developers.  But what if you are building a mobile application?  What if you have a legacy thick client that connects directly with TCP?  Now your developers have to know several languages and formats to get things done.

What if your developers are not web-experienced?  It’s hard enough getting them on the same page about web service design, and now we cloud the waters with this new way of thinking.

Yes, everything these days should be stateless, and most things should be done over the web, but designing your API around the web just means carrying that baggage to every other transport layer.

Programming Shouldn’t Be About The Transport Layer

Programming is about making a product that works (and hopefully works well).  How that is accomplished should be expedient and robust – REST is an esoteric exercise in HTTP-land.  I am all about esoteric exercises, but I cannot seriously justify them on someone else’s dollar.

To make a ‘pure’ REST API you must do a lot more architecting and churn out a lot more code that you possibly will never use.  When your client could have had their product a month ago, is it worth it?  How do you explain the extra time to your manager?  How do you explain the overhead to junior developers who will most likely struggle with the concept?

Unless…

REST is great when you want a discoverable API.  It’s also great for forcing a particular way of thinking onto developers (arguably, a good developer would have already made the right decisions).

The Bottom Line

If your consumer is you, do whatever makes the most sense.  If your consumer is someone else, that’s when you should consider REST.