Rest APIs Are A Bad Idea

I was involved from the very beginning with the web service revolution. First XML-RPC was developed, followed by XML and SOAP, and then finally JSON and REST became popular. Because I was one of the first people to build rich client applications, I have probably done more technical integration with web services than just about anyone. But now a quarter century later, I have come to the conclusion that most modern REST implementations are a royal mess. The amount of twiddling required to get the average REST integration to work is completely insane.

Here is an example of what I am talking about. I recently added Slack integration to our Snapshot product. The results are cool. Now our customers can send Snapshot Reports and Dashboards directly to any Slack Channel. The Slack developer API is a completely normal REST implementation. I don't mean to cast any shade on that, but rather on the crazy thing that modern REST integration has become.

First, consider the URL endpoint. My integration to send a document to a Slack Channel required calling seven different REST APIs. Each one had a different endpoint. But in some cases, parameters have to be added to the endpoint. Some of these parameters had to be correctly escaped in order to work, and they must also have the right key-value pairs and symbols. You also need the correct HTTP method, like GET or POST, etc.

Next, consider the HTTP headers that are required. There is a bewildering array of arguments passed in the headers. Just in my simple integration, I had five different content types. All of the content types have to match the body of the transaction. In some cases, there were additional headers required for access tokens and security.

Lastly, you need to pass parameters to the API. This requires lots of fiddling around. Sometimes the parameters are in the URL endpoint. Sometimes they are in the body of the document as JSON. Sometimes as XML. Sometimes the parameters are passed as form data. Sometimes they are binary octet-streams. Sometimes parameters are passed as multipart/form-data, which requires complex boundary strings to divide the payload into sections. In this case, each section can have its own content type and payload.

The URL, the method, the headers, and the parameters must all work together or the API transaction will fail. The inevitable way you figure this out is by trying stuff and seeing what happens. Most REST implementations also have skimpy error handling. The errors are a big opportunity to communicate directly with the developer, who is obviously trying to do something and needs help. Instead of returning "invalid form data" the API could examine the original request and provide actual help at that point. There are consistent places where different developers make the same mistakes over and over again.

All of this is completely avoidable. Simply conduct XML or JSON document exchange with a fixed URL endpoint using the POST method. No headers, no URLs, no parameters, no arguments. If the input document is empty, send back a list of example input documents. If the input document is not well formed, send back an example of a document with the right form. In this manner, all a developer needs is a single URL endpoint that they can talk to in an intelligent manner. You can figure everything else out from there without the need for any additional help system.