REST vs the rest – comparing REST with other options


The first two blogs in this series so far have looked at REST and APIs at a high level, and then the technology of HTTP/REST. In this 3rd part, we’ll get into the nub of what a makes a REST API different from REST, why REST APIs are a good idea, and how they stack up against the rest (pun intended).

As seen in the earlier examples, REST was first developed as the engine for the web, and it’s still used for that today. Much of the things which computers GET or POST are images, or websites. Many REST clients are web browsers such as Chrome, Internet Explorer or Safari. But, lots of other applications need to talk to each other. This communication needs to do a lot more than just web browsing. Mobile apps place pizza delivery orders; automated sensors send weather data to forecasters; train station display boards get the time (or the delay) of the next train; and price comparison companies get quotes from insurers (even if they ultimately display these quotes on a website).

Applications talking to each over networks like the internet is nothing new - and predates the REST API surge. Various proprietary mechanisms have been tried over the years, and in 2001 an open “WebServices” standard (also known as SOAP) was agreed by many of the world big tech companies. This had huge advantages in being non-proprietary and was extremely widely adopted. This was therefore supposed to be API to end all APIs. Of course, there is no “end of history” and WebServices are now largely seen as “old hat”; but as the last "big thing" before REST APIs became the current "big thing", they’re a good point of comparison.

Before we compare REST to SOAP there's one more thing which needs to be understood about REST. So far this series has looked at the ‘how’ of REST rather than the ‘why’ – so let’s start there.

The Philosophy of REST

As has been shown, REST fulfils the contractual requirements of an API (in, out, error) but REST also implies a mindset about how to interact with resources, not just a mechanism for getting computers to talk to each other.

State Transfer
REST itself stands for Representational State Transfer – namely you’re able to transfer the current state of resource (thing) by getting it, then either creating another one (POSTing to a different place), or by changing it and putting it back to the same place (PUTting it back, overwriting the old copy). As I keep saying this, coupled with the limited set of Methods makes for a simple but powerful tool.

Links
The other major component of of REST/HTTP/Web is Hyperlinks. This is the way by which one resource can link to another resource(s). In order to fulfil our API ‘contract’ all we need is to know the resource name of the thing we want to interact with and we can. Sadly this doesn’t offer any way of discovering that resource in the first place or discovering other related resources. One of the great strengths of the web is (just as the name says) to create a web of inter-related resources. As anyone who has spent hours bouncing around Wikipedia knows all too well!

State and Links come together to form the core of the REST philosophy – the rather unbecoming acronym HATEOAS (pronounced Hat-ee-os). This means Hypertext As The Engine Of Application State - namely if the state of a thing contains Hyperlinks, and I know how to follow them, then I can I can be guided. I only see the links which are applicable to me, and only for the current state of my journey (e.g. if I GET my shopping basket I won’t be shown the link to GET delivery-slots if the basket is empty). Not only can I now discover the delivery-slots API without knowing about it in advance – I’m also implicitly told when it’s appropriate for me to use it, and when it’s not. Yet again, the core concepts of REST can direct and control the consumer with beautiful simplicity and without the need for additional complicated addons.

REST vs SOAP

Rest vs RPC

SOAP WebServices (along with many pre-SOAP standards) used a pattern called “Remote Procedure Call” (RPC). This takes existing software best practices of building reusable blocks of code and making these available to others as functions; and extends it by making these functions (aka Procedures) available from other computers (remotely across a network).

A Remote Procedure Call is of course an API (with inputs, outputs, errors) to do something, and it's very flexible with no constraints on this can be – so for example (with the inputs in brackets):
  • Get Order (orderNumber)
  • Set Customer Email (newEmailAddress)
  • Add To Basket (product, quantity)
  • Increase Quantity (byHowMuch)
  • Launch Fireworks ()
  • Release The Hounds ()
RPC is thus different to REST. REST says we can only use certain methods such as GET, PUT and DELETE, in RPC you can Increase, Launch, Release, Confuse, Shake or use any other verb you choose. Sadly this very flexibility comes with downsides:
  1. Whilst you can create idempotent methods like this (e.g. SetEmail) you don’t have to. You can use incrementAge() or doubleHeight(). When connecting to another computer over a network things are more likely to fail, so idempotency is nice way of ensuring things can be retried without breaking anything. If an attempt to doubleHeight doesn't reply, it might have worked, it might not have done, so should we retry or not? If we do and it did alredy work we'll end up quadrupling the height. If we had PUT/PATCH a height to be exactly 200cm we could retry as often as we wanted.
  2. With great flexibility comes a certain degree of confusion. In order to make things understandable teams end up having to agree standards and best practices to try to make things easy to understand. For example teams often define their own error catalogues, and may decide to limit the verbs they use. When different teams want to use each other’s services they may not know the standards they chose. This is why I described the relative simplicity of REST as “elegant” in the previous post.

Data in REST APIs

For me, the biggest difference between REST and RPC is a mindset one. In REST people tend to think about their resources as nouns (and as such think about what data they're using) – in RPC people think about the function (verb) they’re trying to achieve at the moment they start. If done well, thinking about data tends to help create things which are more readily reusable, and more easily understandable – although obviously it can still be done badly.

Best practices in REST involve thinking about the resources which are meaningful in a given domain (e.g. Product, Order, Customer, Delivery for retail; or Current Account, Credit Account. Customer, Branch for retail banking). This then forms the basis of APIs which get built on top of the logical list of entities. If we use nouns which are already commonly understood, then the APIs should also be easy to understand.

Economics - Why REST got popular

For all the reasons above about REST being good because of how it structures thinking – that’s not really why it overtook WebServices. The real reasons were cost and speed: REST was simply cheaper and easier to use.

WebServices were based on a technology called XML which was always somewhat cumbersome, and eventually fell out of fashion.

WebServices prided itself on being independent of transport – it could be sent via HTTP but also via other mediums (even Email). As such it avoided using any of the HTTP tools we’ve spoken about:  every message was sent as a POST (even if that message said ‘Get Orders’) and every response returned a 200 code (even if the response contained an error message). This meant there was a lot of work to do to re-create the work done already by HTTP.

Many people (especially those developing websites and mobile apps) were familiar with REST. If your webpage needs to GET an image, why not GET a stock quote, GET an order, or GET any other piece of data? The general move to digital/online made REST feel natural to a lot of people. In my first post I used the analogy of HTTP being like Esperanto in that it’s not tied to a given technology.  In fact SOAP may have more claim to the Esperanto title as it was created by committee, wasn’t natural for anyone to use, and fell from favour to be replaced by something which already existed (as English became the lingua franca not Esperanto).

Finally, SOAP required extensions to do things like caching, security, and discoverability (finding a Webservice). These were designed by yet more committees and as such were often overly complicated or hard to use. They were also extras for people who paid for and maintained these systems. The Web already had cheap (often free) solutions for this - much of which would be needed anyway. Hyperlinks were a proven way to find related content; caching and security could be done using open source tools. The WebService answer was to buy yet another set of tools from the big software vendors. People wondered by they needed all the added complexity and cost?

As we’ll see in the last post in this series, there are actually some additional products and services which have developed to turn REST APIs into a fully featured API Ecosystem, but these tend to fill niches not already solved by the web, rather than reinventing what was already there.

Conclusion

Although cost and ease of use are the main reasons I think REST currently holds the crown - the elegance of REST is also attractive to many. Overall REST fits with what teams know, and reuses tech which every company already has. The fact that it is somewhat constraining means it enforces a set of best practices which make one REST API look and feel a lot like another so it’s easy to understand.

As I mentioned above when talking about WebServices – there is no End of history and even though REST APIs are dominant, there are always new players entering the scene. One is even bringing back the RPC style. This is the open source, Google backed, gRPC (https://grpc.io/). Whether this becomes the next big thing, or a flash in the pan is for now too early to show, but nothing lasts forever so perhaps REST’s days are numbered. Then again, some things do last the test of time (the wheel looks to be here to stay), and ubiquity does make it harder for new entrants so dislodge an incumbent. So REST might stand a chance - only time will tell.

Comments