REST Won't Help You Understand HTTP

February 18th, 2016Dan Yoder

The HTTP protocol gets a bad rap. HTTP is simply an application protocol that provides a well-considered set of features for distributed applications. Naming, caching, compression, and so forth, are not superfluous complications introduced by HTTP. They’re just things distributed applications need to do. HTTP is annoying because distributed computing is annoying.

Naturally, developers looked for guidance, and, in doing so, unfortunately turned to REST. But REST is the wrong lens through which to understand HTTP. REST was introduced in a Ph.D. dissertation. Notably, the title of the paper is not A Gentle Introduction To HTTP nor Building Your First Web API nor even Teaching Distributed Computing With Acronyms. In fact, the title of the paper does not mention either REST nor HTTP.

A Certain Audience

It’s unlikely that the then-doctoral candidate Roy Fielding anticipated the acrimonious debates that would follow the publication of his paper, Architectural Styles and the Design of Network-based Software Architectures. REST and the Web serve merely as an example to illustrate his thesis, which makes sense because he also happened to be a principal author of the HTTP specification.

If case there was any doubt, he later clarified on his blog that his dissertation was never written to help developers use HTTP correctly:

My dissertation is written to a certain audience: experts in the fields of software engineering and network protocol design. These are folks with long industry careers or graduate degrees, usually Ph.D.s who have spent decades learning about their field…

Guaranteed To Know

An unfortunate series of events ensued which led to HTTP getting the aforementioned bad rap among developers tired of being scolded for, in effect, not having read and understood Fielding’s dissertation. Which, again, Fielding wrote for a “certain audience,” of which they probably were not a member, and not interested in becoming one.

Of course, no one was forcing them to talk about REST, a concept that Fielding had invented and for which he was thus was the authority.

I don’t try to tell [developers] exactly what to do because, quite frankly, I don’t have anywhere near enough knowledge of their specific context to make such a decision. What I can do is tell them what isn’t REST or that doesn’t fit my definitions, because that is something about which I am guaranteed to know more than anyone else on this planet.

I could have entitled this post, The Case Of The Missing Web Site. If HTTP was introduced today, it would likely come with its own Web site, complete with an introduction and examples. Sort of like the one for HTTP/2. But that it isn’t Fielding’s fault, nor that of REST, nor HTTP. The Web was a smaller place in the late 90s, populated almost entirely by enthusiasts. Developer evangelism would have been redundant. Even if it wasn’t, Fielding had already done his part by helping to write the HTTP spec. He didn’t owe anyone an exposition on its proper use.

Start At The Beginning

HTTP is conceptually simple. And HTTP best practices are drawn from four decades of practical experience. But framing them in terms of REST is confusing at best and pedantic at worst. Imagine being a developer trying to build an API for the first time and the first thing you’re supposed to read is someone’s dissertation? That’s why our HTTP Made Simple series makes little mention of REST. But even that attempt suffers from a pervasive REST subtext. We need to put REST aside and start at the beginning: with naming, caching, authorization, and so on. REST is something you can come to later, to deepen your understanding. As a primer, it serves only to obscure, not to reveal.