RESTful design is akin to the graphical user interface on modern computers — ubiquitous enough to be considered the de facto choice, but in practice, not necessarily the only option. REST is certainly considered by many to be the king of the hill, but it’s wrong to think it’s the only player in town.

In fact, it’s more correct to state that RESTful design isn’t the most popular, but simply the most public — there’s a veritable surfeit of APIs that defy REST standards, and in fact drive many of those successful REST APIs.

Today, we’re going to take a look at some of the most common instances of unRESTful APIs, isolating what it is that makes these APIs and systems function outside the realm of RESTful guidelines. We’ll discuss other alternatives to REST, and nail down just what sort of standards really matter when designing robust web APIs…

Defining REST

Before we dive too far into this topic, let’s truly define what REST is, and how it’s applied to APIs. This is elementary knowledge for many API aficionados, but many would be surprised at just how many common terms and concepts are often misinterpreted or misrepresented in common usage.

In dry definition, REST stands for Representational State Transfer, and focuses on stateless, client-server communications, most often over HTTP, as defined by Roy Fielding in his groundbreaking dissertation that originally defined REST. In actual usage, what REST typically means is significantly more complicated.

Firstly, regarding calls made made by a RESTful client. RFC 7231 states that “request methods are considered “safe” if their defined semantics are essentially read-only.”

Idempotency is a strange beast but is fundamental to both the extended security and functionality of a RESTful API. To be idempotent, multiple identical requests to an API should produce the same affect as a single request. RESTAPITutorial defines indempotency as “clients can make that same call repeatedly while producing the same result.” For instance, an API with a shopping cart add function should not include a GET request with a cart modifier, such as below:

https://nordicapis.com/addToCart?cart=1234&item=5678

This call adds an additional item on each run, which is against REST guidelines. This function limitation is the same across any function, whether it be a request for additional data, a modification of server-side stored data, or an establishment of cause for the server (i.e., establishing authentication and authorization parameter data). However, there are exceptions to the rule: for a REST API working over HTTP keep in mind DELETE is not safe, but idempotent, and POST and PATCH are both safe, but not always idempotent.

Fielding says that “REST APIs should not be dependent on a single communication protocol.” The whole point of REST is to establish dynamic application states via a state engine driven by hypertext for ease of use and transfer. As Fielding describes, “if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API.”

Finally, and perhaps most important, RESTful design should rely on a sort of blind communication between the client and the provider. Users must enter into the handshake and communication process with only a single URI or collection of URIs that then present a list of choices generated via server properties for their interaction. Fundamentally, REST, despite having “state” in its name, is technically stateless — the server does not store states for the client session on the server side, instead relying on the client to store that data, and pass it to the server when needed.

With all of this in mind, what are some great cases of unRESTful APIs?

Complex Data with Evernote

A great example of when RESTful design approaches break down is in the Evernote suite of productivity applications. REST is great at what it does when it handles data, but there’s a fundamental flaw in how it handles complex data transfers.

Evernote API is unRESTful to handle complex data transfers more efficiently

Each chunk of data in the RESTful approach is underlined by the control flows of underlying services, and because of this, RESTful APIs often face huge bottlenecks. The problem is so extreme in large datasets that some groups, like the Service Platform Lab at HP Labs in Singapore, have designed entire systems to better constrain data workflow.

Rather than patching a hole in the sinking boat, however, Evernote went out of their way to bake a unRESTful solution right into the code. By depending on Apache Thrift, and not HTTP as dictated by REST API specifications, data transfers are much, much more efficient.

Using Thrift also opened up the API to handle native bindings, rather than processing each relation and code interaction on every single client. Not having to worry about parsing and marshalling code eliminates much of the errors at the base interaction level.

Most importantly, Evernote managed to avoid much of the compatibility errors that arise when designing in a RESTful state. Clients developed today will function with clients from years ago, and in five years time, these current clients will function with those future revisions, without any issues.

Contracts in SOAP

REST isn’t the only player, either. SOAP, or Simple Object Access Protocol, is an alternative to REST — and by its very nature, incompatible as an operant. While REST can use SOAP web services, SOAP as a protocol cannot be definition be RESTful.

The best way to think about the difference between SOAP and REST is to think about it in terms of mail exchange. SOAP is like an envelope, whereas REST is like a postcard. Whereas REST is lean, clean, and effective, SOAP has much more overhead. On the other hand, you can fit much more inside an envelope that you can inside a postcard.

What this functionally means is that, despite being heavier with greater overhead, SOAP is often a much more secure choice, especially when formal contracts and interactions must be dictated.

A good example of where SOAP makes sense over REST is the PayPal SOAP API. Because the PayPal ecosystem depends entirely on contractual communication with a specific security schema, a SOAP solution makes more sense than a RESTful one. While much of the data is logged with usernames and passwords, as well as process IDs and transaction information, this is actually a benefit, as this process logs transactions and interactions to unique identifiers.

As a side note, the PayPal API does something incredibly useful that many APIs eschew. The PayPal API by design assumes any data being processed is in Unicode UTF–8 and returns data in that format. This covers both domestic and international transactions and interactions, and is vital to preventing bugs and other issues in the API.

That being said, the PayPal API is also a great example of how REST can be “hacked” to have close to the same benefits. The SOAP APIs are considered legacy by the developer, with some of the feature sets replicated in REST:

“I should point out Paypal has REST APIs going forward, our SOAP support is considered legacy … Also, contracts can be enforced with REST using Swagger/RAML/Apiary/etc+JSON Schema, albeit somewhat different.”

Operation-Specific and CRUD Violations

REST works best when a simple phrase is met as closely as possible — CRUD. Create, Retrieve, Update, and Delete. When an API has simple interactions — such as is the case with the Facebook API, where users need to create timeline posts, retrieve other’s posts, update their own, and delete their posts — REST is just fine.

The problem comes when the operation is the focus, rather than the resource. With REST, CRUD operates on the idea that the resource is what must be modified and extensible — in APIs dealing with transactions or modification of non-static data, SOAP is more appropriate.

WCF .NET prefer SOAP for operational benefit

A good example of this is the Windows Communication Foundation (WCF) SOAP API. This API allows for live manipulation of not only the data being operated upon but the operations that can be done against it. It’s this modularity and operation-specific functionality that makes SOAP so powerful, and such a good choice against REST.

More specifically, SOAP, in this case, fills an interesting gap between the idea of supporting hypermedia in the REST API specification as a matter of principle and the reality of handling simple, raw data that does not need to be relationally linked. The operation of claiming a quote, or generating a ticket number, is so simple, that creating a RESTful API to do so is wasteful, and when paired with large numbers of quote requests or receipt generations, absolutely untenable.

Is It That Important?

All of this begs the question then of whether or not it’s even that important. The easy answer is that “it depends”. When APIs violate a standard such as REST, the knee-jerk reaction is to say the service is faulty. Violating REST standards in many people’s eyes has become a negative line in the sand, something that represents unfamiliarity or juvenile approach to development.

The REST vs SOAP argument is much more about style than it is about function or form. Style and efficiency aside, anything done in SOAP can be done in the variety of languages, syntaxes, and approaches that make up the bulk of REST development, and likewise, anything that can be done in REST can be done in some configuration in SOAP.

Just as one developer would not consider an API in golang to be juvenile over one developed in Python, so too should the API world step back from its fervent love of REST — at least, when it’s warranted. What matters is what the specific requirements of the API is in terms of weight, processing speed, and type of data processed.

Conclusion

unRESTful APIs are much more common than one might think, despite the radio chatter that suggests otherwise. What is often phrased in hyperbole as the difference between “ancient and modern” is an argument of style more often than not, and is highly variable given the type of data and demands of the system.

There are, of course, situations where the demands of the data issuer or commercial entity all but requires a specific REST format. To those situations REST is a constraint, rather than a feature, and is something that must be done for compliance. That does not mean that everything in the IoT or healthcare industries, for example, are best done with REST — it just means that those whom the systems are created for tend to prefer it done in REST. If SOAP is more appropriate, or any variation outside of REST for that matter, the style should be dictated by the content where allowed.

Opening ourselves to accepting SOAP, RPC, and other unRESTful solutions will only benefit the ecosystem as a whole, creating new and better alternatives to systems already in place. Other solutions that dramatically augment REST, such as GraphQL, can be equally beneficial — a fact we will extrapolate upon in a further article. Focusing too much on REST could have the opposite — and negative — effect.