Why you might benefit from letting this popular paradigm rest in peace.

I have added a sequel describing JSON-Pure APIs best practice in detail. But do please read this first.

RESTful APIs are awesome, right?

If you have read an internet developer resume or job posting in the past 10 years, then you might be forgiven if you think that RESTful APIs are gifts bestowed from the heavens by The One True Web Developer Deity. RESTful APIs are everywhere. Even the marketing folks are pushing them in sales material intended for CEOs and Human Resources-type folks.

So how good of an idea are RESTful APIs really? Before we answer that, let’s look at where REST came from, and define RESTful APIs.

Where did REST originate?

REST became popular when it was detailed and promoted by Roy Fielding as part of his doctoral dissertation entitled Architectural Styles and the Design of Network-based Software Architectures in the year 2000. Roy is well known for his contributions to development of the web, especially the HTTP specification.

What are RESTful APIs?

REST is Representational State Transfer, an architectural style intended for building scalable web services. Roy advocated using the request methods he helped define in the HTTP standards to impart meaning to HTTP requests.

Thus the following HTTP requests all have different meanings when using REST:

GET /object/list

POST /object/list

PUT /object/list

There are only a few HTTP request methods. The full list is CONNECT , DELETE , GET , HEAD , OPTIONS , PATCH , POST , PUT , and TRACE . You may be forgiven if you’ve never heard of a few of these, as some are almost never supported by client or server software.

Roy also advocated that HTTP response codes he helped define be used to communicate the meaning of the response. There are ~38 HTTP response codes. Below is a complete list. I’ve shortened a few titles in the interest of space:

Method Method 200 OK 201 Created 202 Accepted 203 Non-Authoritative Info 204 No content 205 Reset content 206 Partial content 300 Multiple choice 301 Moved permanently 302 Found 303 See other 304 Not modified 306 (unused) 307 Temporary redirect 400 Bad request 401 Unauthorized 402 Payment required 403 Forbidden 404 Not found 405 Method not allowed 406 Not acceptable 407 Proxy auth required 408 Timeout 409 Conflict 410 Gone 411 Length required 412 Preconditions failed 413 Request entity too large 414 Requested URI too long 415 Unsupported media 416 Bad request range 417 Expectation failed 500 Server error 501 Not implemented 502 Bad gateway 503 Service unavailable 504 Gateway timeout 505 Bad HTTP version

The meaning of such an API transaction over HTTP is therefore at the minimum the result of

the HTTP request method verb, e.g GET

the request address, e.g. /object/list

the request payload, e.g. form fields

the response code, e.g. 200 OK , and

, and the response payload, e.g. the JSON data.

Many have embraced this paradigm when providing a web service over HTTP, and this is what we refer to here as a RESTful API.

A RESTful API transaction can be more complex than shown above for various reasons, some of which we will discuss below. However, we will ignore the complicating factors associated with network transport and caching since these issues are universal to all communication channels.

RESTful APIs are actually pretty awful

REST is a great mechanism for many things such as content delivery, and it has served us well for two decades. But it’s time to break the silence and admit that the RESTful API concept is probably one of the worst ideas ever widely adopted in web software. Roy is probably a great guy and he certainly had a lot of great ideas. However, I don’t believe that RESTful APIs was one of them.

We will soon review a better way to build internet APIs. But before we can fully appreciate that solution, we must first understand the 5 primary problems with RESTful APIs that make them expensive, tedious, and error-prone. Let’s get started!

Problem #1: There is little agreement on what a RESTful API is

Ever notice how nobody calls their API “RESTpure”? Instead they call it “RESTful” or “RESTish”. That’s because nobody can agree on what all the methods, payloads, and response codes really mean.

Consider, for example, when we might use the 200 OK response code. Should we use it to indicate the successful update of a record, or should we use 201 Created ? It seems we really should use a code like 250 Updated but that code doesn’t exist. And can anyone out there explained to me what 417 Expectation failed really means? I mean besides Roy?

The vocabulary of HTTP methods and response codes is too vague and incomplete to get agreement on meanings. No governing body - at least to my knowledge - has convened to set things straight. What one company defines as the meaning of 200 OK is bound to vary in subtle and annoying ways from 200 OK from another company. Which means a RESTful pattern isn’t as predictable as we might like.

If this were the only problem, I’d probably be writing RESTful APIs today. But the problems keep coming…

Problem #2: The REST vocabulary is not fully supported

Even if we could agree on the meaning of the vocabulary of REST, we run into another practical problem: most client and server applications don’t support all verbs or response codes for the HTTP protocol. For example, most web browsers have limited support for PUT or DELETE . And many server applications often don’t properly support these methods either.

So how do we work around these application limitations? One common method developers use with browsers is to embed the intended verb into a browser form. Which means that the REST request now includes:

an HTTP request method, e.g. POST

a request address, e.g. /object/list

a what-we-actually-intended-to-use request method embedded in the request payload, e.g. DELETE

and a request payload itself, e.g. form field data.

Response codes aren’t handled much better. Different web browsers (and servers) often interpret response codes very differently. For example, if a 307 Temporary redirect code is encountered, one browser might allow the client JavaScript to consider the response and cancel it before acting upon it. Another browser might not allow the client JavaScript to consider the response code at all. The only truly reliable response codes across all software are 200 OK and 500 Internal server error . After that, support varies from pretty good to abysmal. Because of this, we often see what-we-actually-intended-to-use response codes embedded in the response payload too.

Of course, even if we could get everyone to agree on what REST is, and magically fix all the not-ready-for-REST software connected to the internet, we’d still have another problem: the REST vocabulary.

Problem #3: The REST vocabulary is not rich enough for APIs

The REST vocabulary of methods and response codes is simply too limited to effectively communicate the wide variety of requests and responses required across all applications. Imagine we create an application where we want to send a “render complete” response back to an HTTP client. But we can’t do that using an HTTP response code, because (a) one doesn’t exist and (b) HTTP is not extensible. Bummer. I guess we are back to embedding what-we-actually-intended-to-use into the response payload.

There’s another problem: we don’t have one vocabulary, we have three. HTTP response codes are numbers (200, 201, 202, etc) that don’t directly correlate with the HTTP request methods ( GET , POST , etc). And our payload is typically in JSON. Executing a REST transaction is like sending a package addressed in Swahili, with English content, and getting delivery confirmation by message drums. This complexity is a great source of confusion and errors. Which brings us to the next problem: debugging.

Problem #4: RESTful APIs are very hard to debug

If you’ve ever worked with a RESTful API, you know they are almost impossible to debug. That’s because we have to look at 7 different locations to piece together what’s happening in a complete transaction:

The HTTP request method, e.g. POST

The request address, e.g. /object/list

The what-we-actually-indended-to-use request method embedded in the request payload, e.g. DELETE

The “real message” in the request payload, e.g. form data.

The response code, e.g. 200 OK

The what-we-actually-indended-to-use response code embedded in the response payload, e.g. 206 Partial content .

. The “real message” in the response payload

Not only do we have two very limited vocabularies that no one agrees upon or fully supports, but now we get to look in 7 different places to try to fully understand and debug a transaction. The only thing that could make this worse is if REST were completely tied to one protocol and not applicable for any other communication channel. That, of course, is our very next problem.

Problem #5: RESTful APIs are usually tied to HTTP

RESTful APIs break one of the fundamental laws about good communications: the message content should be independent of the transmission channel. Mixing of the two is a time-honored way to confuse our audience.

The typical intermingling the HTTP protocol of with the meaning of the transactions makes RESTful APIs completely non-portable. Moving a RESTful API from HTTP to some other transmission method requires disentangling and restructuring information from 7 different locations we use to encode the full meaning of RESTful the transactions.

Happily there is a much better solution that avoids or mitigates almost all the problems with RESTful APIs. We will refer to this solution here as JSON-Pure APIs.

The way forward: JSON-Pure APIs

JSON-Pure APIs fix most of the problem we’ve just discussed.

They use just one transmission method to send a request - typically POST for HTTP or a send for WebSockets.

for HTTP or a for WebSockets. They completely separate the request content from the transmission mechanism. All errors, warnings, and data are placed in the JSON request payload.

They use only one response code to confirm proper receipt of a message - typically 200 OK for HTTP.

for HTTP. They completely separate the response content from the transmission mechanism. All errors, warnings, and data are placed in the JSON response payload.

They are easy to debug since transaction information is found in easy-to-read JSON inside the payloads using a single, domain specific vocabulary.

They can easily be moved or shared between transmission channels such as HTTP/S, WebSockets, XMPP, telnet, SFTP, SCP, or SSH.

JSON-Pure APIs came about because web developers found that RESTful APIs are not very browser or developer friendly. The separation of message and transmission channel results in an API that is usually faster, and almost always more reliable, easier to use, easier to port, and easier to debug. Today, if you use the Twitter API, for example, masochists can choose the RESTful API. The rest of us can use the JSON-Pure API (they call it the “Web API”).

I’ve been asked numerous times over the last decade to use a RESTful API instead of JSON-Pure. The last time I almost had to support a RESTful API was in 2011. Thankfully, the server team agreed to provide an alternate JSON-Pure API along with the RESTful variant by simply stuffing their HTTP methods and response codes into the JSON. After a few months, everyone I knew who used the API had switched to the JSON-Pure version. It was just that much better.

The future of JSON-Pure APIs

UPDATE: I have added a sequel describing JSON-Pure APIs best practice in detail. Certainly, the recommendations aren’t optimal for all situations, but they do result in a the type of API I frequently need for use with responsive Single Page Web Applications. As always, your mileage may vary. But if your use case is like mine, you might just want to make your next API “RESTless” and “go Pure”.

Cheers, Mike