And the rest they say are history – an introduction on REST APIs

REST APIs are one of the fastest growing technologies in the world and have displaced other forms of integration to become the de-facto standard for how we connect the world. From mobile apps placing orders on eCommerce sites; to cars getting map data and traffic data in real-time. From Open Banking forcing banks to provide ‘open APIs’ to open up their markets; to companies breaking up their legacy IT systems into “Microservices” in order to evolve faster. All this is enabled by or powered by REST APIs.

Over the last few years working with APIs I’ve had several occasions where I needed to introduce the topic to people who had little or no experience. Although there are many good blogs, I’ve never found a good cold introduction which did quite what I wanted. So, here’s my attempt at writing one.

The target audience for this is really people who are fresh to the subject: people with IT skills but are new to APIs; those from a less technical background (e.g. test); people who operate systems but don’t often create them; or those completely new to this area of IT such as new graduates or really anyone else who is interested. As such this series of blogs starts at a very high level – and uses analogies to the real (non-IT) world. Later posts layer in more detail (so even those with some existing knowledge should find it useful) but it never gets super detailed – that’s where all those other good blogs come in. It’s structured into four posts:

1. The Rest the say are History: The high-level introduction - What are APIs? What is REST?
2. Methods from madness: A more complete look how REST works
3. REST vs the rest: The philosophy of REST APIs, how this differs other options, and why this has some benefits
4. API Ecosystem: Returning to a higher vantage point, to look at how this all comes together with an example case study all the moving parts in the “REST economy” 

What are APIs?

As a start, we should define what an API is. Put simply an API is a way of allowing software Applications to talk with each other – or in technical speak to Interface with each other Programmatically (without a person inbetween). It stands for Application Programming Interface. Essentially, it’s an agreed way of plugging Apps together – ensuring square pegs fit into square holes.

APIs exist across different technologies as languages exists across different groups in the real world, and as with language they’re often impenetrable if they’re not your native tongue. Where French people communicate with the French Language written in the Latin alphabet, and Japanese people use the Japanese Language written in Kanji; Java applications use Java APIs to communicate with other Java applications; and C# applications use C# APIs to talk to other C# applications.

Over time people have tried to find technology independent ways of communicating (a sort of Esperanto – but more successful). REST APIs are the latest – and currently most successful – attempt to do this. It’s a widely adopted, standardised, and language independent format for communication. It’s also the same format the Worldwide Web uses to provide webpages, YouTube videos etc.

This means almost any computer language can use REST APIs, making them extremely flexible. To close our analogy, this is like scientific publications usually being written in one language (English) rather than the native language of the speaker; as this allows maximum reuse of the article across different scientists.

All APIs (REST or other) form an agreement about how to communicate – often described as a ‘contract’ between the two applications. As one application is ‘providing’ a service/function to the other they’re usually referred to as an API provider and API consumer.

In the same way that if I expect a response to a letter I need to make it understandable and include a return address. A contract defines what the consumer needs to do to get a service, and what the provider provides. An example of a contract for a “number dividing service” might be

• Expectations of consumer: provide two numbers, where the 2nd is not zero (e.g. 100 and 2)
• Expectations of provider: send back 1st number divided by 2nd (e.g. 50, as 100/2=50)
• What if it goes wrong: if the consumer fails to give two numbers, or if the 2nd number is zero then send back an error.

This is usually expressed as:

• Inputs: what the consumer sends
• Outputs: what the provider sends back – if successful
• Errors: what the provider sends back – if not successful 

Analogy

One example I once saw described APIs as being like a plug socket. This ‘API’ has a type (e.g. US, European, UK) which is based on a technology (Alternating Current), and it has a contract. In the case of the UK Plug the contract is:

• Input: provide three pins, the top of which is ‘earth’ and the bottom two are live and can conduct electricity
• Output: 230V flowing across the two bottom pins, at 50Hz
• Errors: If top pin is missing the 2 live pins are blocked off (as shown above)

What is REST?

So that’s an API, but what makes an API a REST one? As mentioned above, REST is the mechanism by which the web operates. Most of the web is based on half a dozen simple principles – which form the building block for all the complexity of the web today. To use the internet, clients (such as web browsers), make requests to servers (which “serve up” content for their clients).

Each interaction uses an agreed standard (called HTTP) which allow the client to specify their request to the server and receive a reply – this is sent in an agreed format. Each of these interactions is made up of:

· Resource Name: a thing (picture, video, HTML document) the client wants to interact with

· Resource Payload (aka ‘Body’): the contents of this thing (e.g. the actual picture/video/html file)

· Method:  what client wants to do to/with the resource (e.g. GET it, or DELETE it)

· Headers: additional information sent with the request

· Status: did the interaction succeed or fail?

Using just these five simple things, clients can: retrieve, create, update, and delete text, pictures, and other media online.

In this sense it’s fairly easy to see how REST can act not only as a way of distributing media on the web but as a way of transporting anything needed in an API. Almost like the API is a language and HTTP is the letter, and postal service.

Going back to our API contract – the contract parts are fulfilled by the bits of REST:

·         Inputs: resource name, method, headers and payload (if this is a create/update)

·         Outputs: status, headers, and payload (if this is a retrieval)

·         Errors: status

Conclusion

Hopefully that’s a clear overview of what an API is (a way of connecting two applications), and what REST is (a mechanism by which this can occur in a standardised way). In the next section we’ll get into REST in a bit more detail. We’ll look at the five parts of REST listed above, and throw in a couple of extras in Methods from madness: Understanding the Method, URL, Body, Query, Header, and Status in REST