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 ()
- 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.
- 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 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 (API Ecosystem), 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
Post a Comment