Those of you plugged into the REST world have most likely seen at least one of Roy T. Fielding’s rants on “REST” implementations out in the wild (one of the best known being this one). While there are a number of reasons why an API might not technically fit the definition of REST, I have come to observe one incredibly commonplace “REST” design-pattern that is far and away the most common way in which APIs are only sort-of RESTful. I have also come to observe the reasons why (and they are fascinating… read on).

The vast majority of REST-like APIs I see follow a distinct pattern of being RESTful on reads (GETs) and not so RESTful with all other operations. Often you will see the following:

The API supports the HTTP GET method for lookups and searches supporting a variety of output formats such as XML, JSON, YAML, etc… Pretty RESTful so far.

The API utilizes the HTTP POST method for creating and, updating resources using POST name/value pairs (vs. via data in the request body). Not so RESTful.

The API does not support the HTTP PUT method. Typical PUT operations are implemented with POST as described above. Not so RESTful.

The API may or may not support the HTTP DELETE method. When it does not, delete operations are usually implemented with a specific “delete” URL, perhaps with query parameters, and the HTTP GET method.

In essence, the API is written such that reads (lookups and searches) are done in a REST style but writes (inserts and updates) are done in more of an RPC style.

Instead of a POST or PUT with something like the following in the request body:

<contact> <first-name>John</first-name> <last-name>Smith</last-name> . . . </contact>

we more often see a POST (or sometimes even a GET (ouch!)) that looks something like this:

http://.../add-contact?first-name=John&last-name=Smith&...

So the big question is why. Why do such an overwhelming number developers naturally drift towards API designs like we just described? Are all those developers really lame? Probably not, and if we examine the problem more carefully we can see at least two very compelling reasons why:

The current architecture of HTML forms greatly encourages an RPC style API. Very often you would like to interact with an API via an HTML form. What’s easier, creating a form that submits a set of name/value pairs via POST (i.e. the standard way we use HTML forms), or writing Javascript code that bypasses the standard forms submission behavior and instead packages all form contents into a JSON object (or XML document) and POST/PUTs it to the server? No brainer. The second path has too much friction, and is much more work. Someone really should create a Javascript library to do just this. Maybe I will break down and write it eventually (and post it for y’all). I believe that this alone would help tremendously in the adoption of more RESTful API designs across the land. (If any reader knows of the existence of such a library please do let me know). Of course, all of this is in addition to the lack of support many browser have for the HTTP PUT and DELETE methods (but this is changing) It is currently much easier to support multiple payload formats (XML, JSON, YAML, etc…) using the RPC style. Implementing a real REST API would require server code to parse data from POSTs and PUTs in each supported format (XML, JSON, YAML, etc…). Too much work for most. If you write an API that (a) supports multiple formats on GETs and (b) implements POST/PUT with name/value pairs via HTTP POST, then you can say you support multiple formats with a straight face.

It is really the state of our software infrastructure, languages, and frameworks that encourage the web API designs we are seeing out there. We need to collectively do a little work to make it less painful to implement and use truly RESTful APIs by providing some client and server frameworks that make full REST just as easy as the half REST we are seeing out there.