The reason behind the half-REST design pattern

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:


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


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:

  1. 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)
  2. 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.

  1. What would be more helpful is if browsers would pick up support for other HTTP methods. There are ways of doing a tunneled DELETE via POST however. At least with the Catalyst Framework

  2. Yup, yup, yup. I’ve written a half-dozen of half-RESTful APIs just like you describe. I’m not anti-REST, but it seems that limiting an API to 4 verbs just ain’t cutting it for me. The “GET for real gets and POST for everything else” is clean and can be used by *any* HTTP client, not just those that support PUT and DELETE. If it’s not really RESTful, that’s fine by me. I’m calling it half-RESTful like you, but it’s working better than full REST in every case.

  3. Asking from ignorance, regarding reason #1, how would you handle file uploads? I don’t think a Javascript interpolation layer like you described could insert file contents into the XML/JSON request document without relying on Java or Flash for filesystem access.

    • dan
    • April 21st, 2010

    Jersey and Jax-Rs takes care of XML and JSON for you, transparently. ReastEasy even adds YAML.

    But no, Java is uncool!!!

  4. John, you are correct. The Javascript transform would not be needed when there is already a document to put / post (as in the file upload case you describe). It would only be used for “regular” forms.

    • Mark
    • April 21st, 2010

    It’s mostly logic on the server vs. logic on the client issue.

  5. #4posterity
    Never let you GETs delete, crawlers will wipe you out.
    PUTs are idempotent.

    • Russell
    • April 21st, 2010

    Makes making real RESTful APIs easy. It makes it trivial to support multiple input formats for PUT and POST and trivial to return multiple formats for GETs. I use it with dojo to allow me to simply turn forms into JSON and POST/PUT them on the the server. So could the answer to your question be: choice of tools?

    • Anonymous
    • April 21st, 2010

    That makes sense, thanks.

    Generally, how would you handle an unstructured file upload like an image in REST? Would it just be PUT by itself and metadata added afterwards?

    • Andre
    • June 11th, 2010

    Ok so the obvious question here is why not use a popular web framework like django or rails, which include these things fo sho, and guide you pretty well.

    By the point scale of that old dude going on about true RESTful-ness, these frameworks seem to be pretty high on that. Like 75%. Nobody can be 100% on that biblical RESTful stuff and still be practical.

    But it’s more than your “half-REST”

    • Andrew Rodland
    • June 11th, 2010

    There’s a red herring here; application/x-www-urlencoded is no less a serialization format than XML or JSON. Sure, it’s a *simple* one, but a lot of data is simple. I see no reason not to use it, as appropriate.

    • JoostM
    • June 12th, 2010

    It doesn’t matter which MIME types you support, as long as server and client both understand them. Content negotiation or supporting multiple MIME types is not a neccessity. Overloading POST is an acceptable work-around for clients not supporting PUT or DELETE – not pretty, but not a huge deal either.

    RESTfulness merely implies that the architecture is resource-oriented instead of RPC oriented. This means that every object that is interesting to the client has a URL and can be acted upon through HTTP methods on that URL. Again, it’s not a neccessity to use PUT and DELETE, this can be put easily in the request body.

    If I send a POST to a URL and the form submission data in the request body includes a delete key instead of an update or a create key, the server knows enough to handle the request. It could even internally re-route it to the DELETE or PUT handlers, if so desired.

    By contrast, SOAP puts method information and resource information all in the request body: all ever you do is send POST messages to the same URL. The request body is probably going to include some kind of ID to indicate which object is acted upon.

  6. The respective banks of properties are rather appointed important, and not in investor of city.

    percocet addiction symptoms
    what is percocet

  7. headache fioricetcarisoprodol fioricet
    Street has historically been characterized after martin luther king jr. the pursue is recently the long aegis wrongdoer, islamic with the custody to instance.

  8. Thanks for every other wonderful article. The place else could anybody get that kind of info in such a perfect means of writing? I’ve a presentation subsequent week, and I am at the look for such information.

  9. Hey there I am so happy I found your web site, I really found you by error, while I was looking on Google for
    something else, Nonetheless I am here now and would just like to
    say thanks for a remarkable post and a all round exciting blog
    (I also love the theme/design), I don’t have time to browse it all
    at the minute but I have bookmarked it and also added in your RSS feeds, so
    when I have time I will be back to read a lot more, Please do keep up the superb work.

  10. ten Power-Packed Promotion Strategies

  1. April 23rd, 2010
    Trackback from : Top Posts —

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: