REST API Explained
If you have used any modern website, then chances are that you have interacted with a website that uses REST. In this article we will explain what a REST API is by showing how it has evolved and how it works.
Introduction
In the Tech world, you hear the word API almost everywhere. Companies of all sizes, major and small, provide public APIs to provide a layer of interaction with their internal applications. But what is an API? what does it do? how it works? and why do we need them? These are all valid questions that we are going to discuss in this article.
Before we go into details about APIs, let’s go back in time and introduce some problems that led to the creation of APIs in its current form.
History
There is no single way to describe the Web. Web technologies have undergone fundamental changes in the past 30 years to reach its current state. Thousands of technologies, inventions, problems, and architectures contributed to the web world to develop from a single ping, to what we have today on our mobile apps. I will try to simplify the idea of APIs as much as possible by working on a real-life example.
Let’s think of applications outside the web framework. We are talking about an application you installed on your phone, or your desktop. The app is written in a single programming language, and runs on a specific environment. Swift runs on iOS, Mac Applications run on MacOS, Windows applications run on Windows Operating System, Android apps run on Android device, Java runs on a virtual machine called JVM etc…
Any application running on any environment can be decomposed to smaller functions determined by their business logic.
Let’s say, we have a Point of Sales (POS) application that allows us to sell inventory items. Our sales application has different functions, such as creating sales and creating purchase. Now when we create a sales, we need to updates the inventory level. To do that, we just call another function called update inventory to do the job. This all happens within the same application. We call this Procedure Call.
Let’s expand the scope of our example, suppose we have two applications in our company. The first application is our Sales Application, the other application is the Accounting Application used by accounting department. This application allows to maintain the company ledger.
Now, after each sales we make, we need to update the accounting ledger as well. To do that, we take a copy of the printed the invoice, and hand it over to the accounting department. Some employee in the accounting department takes the invoice and enters the data into the ledger to update the current balance.
Now suppose we make 10 sales, 100 sales, or even 1,000 sales a day. What if the company grows to have multiple branches? how many invoices need to be handed over to the accounting department? Do you see the problem? At some point the accounting department will not be able to handle the operations and the business will definitely crash as we are wasting all of our resources on manually entering data across applications.
How do we solve this problem? what if we buy another software that has sales and accounting modules combined into a single application? Great idea, but that is extra cost, we need to train employees to use the new software, and migrate all the data from the first two applications to the new one. What if we have a third CRM application? another application for HR? Payroll? Etc..
This is clearly not feasible. So instead of buying a software that has all the functions we need under the hood, we can simply make the two applications talk to each other. We want our sales application to talk to the Accounting application and tell it to update the ledger or vice versa whenever a sales is made without having to update them manually after each transaction.
Therefore, we need some sort of Integration mechanism between the two applications. The application A needs to perform some functions in Application B. This is called Remote Procedure Call, shortened to RPC.
RPC
But what is RPC ?As the name suggests, it is a procedure when an application performs some remote procedures outside its scope. The other application could run anywhere on a shared network, it could be the same device, same internal network or a global network like the Internet.
There are different implementations of RPC, but to simplify it we talk about RPC in the context of our example context.
As we said, the Sales application needs to perform some actions in Accounting Application without caring much about the details of how this is done. It just needs a simple function to tell the other application that a sales is made, with some parameters like sales amount and customer name.
The sales application doesn’t need to tell the accounting about what type of items is sold, that is the job of sales application. The accounting application is only interested in money. Similarly, the sales application doesn’t need to know about what account should be updated, that is the job of accounting application. This is called Separation of Concern. Each application should know the details of its own operations only.
As we said before, there are different ways of performing Remote Procedure Call. We need a unified mechanism that structures the data in a certain way for integration. We can call this the Contract. The contract contains some details about the structure of the data, and what to pass as an argument, how to handle the data, where it is located and etc... Later in this article we will talk about two ways of handling this interoperability between two applications.
To allow the integration between applications, one of the applications needs to expose a set of functions defined in the contract, the set of these functions work as an interface to that application. When an application works that way, we call it a Web Service.
Any web service function have different operation nature, an operation either Create, Read, Update, or Delete. We refer to them as CRUD operations.
In our example, we can create a web service for the accounting application, we need a function that is can be called after a sales is made so the accounting software creates a sales transaction to update the ledger.
We call this function CREATE SALES. This function receives some parameters: the amount of sales, sales type (Cash, Credit) and the buying customer ID. The accounting software now knows what to do with this transaction, it creates a transaction with the given parameters to create a sales, update the ledger, and responds back to the sales application that it has done that successfully.
So in the contract of this web service, we define what type of data is being received, what address should we call, what security measures to implement … etc. To do this we need a mechanism, or a protocol to structure this procedure and tell the other software what to expect and successfully read and process data.
SOAP
In early days of web development, and specifically in late 90s, the concept of web service became so popular where a software provides a contract that can be called by another software running in the same or different environment. So people at Microsoft, developed a protocol named Simple Object Access Protocol, shortened to SOAP for implementing web services. SOAP uses XML as medium of structuring data, and contains so much information like the location of the other application, types of data (numbers, characters, currencies, lists, etc..). It was designed to rely on HTTP protocol for transfer. Since HTTP runs on all operating systems, including Windows, MacOS, Linux etc.. applications can talk to each other using this protocol and in a format of XML regardless of their environment and programming languages.
With the increased usage of web services in the early 2000s, SOAP became so popular and used everywhere as it allowed for integration in any environment. However, the large amount of standardization applied to the XML data caused the data to be huge in size even for simple operations. In addition, the slow processing of XML caused this protocol to be a bit problematic and difficult to use and here is where REST came into place.
REST
REST stands for Representational State Transfer. It is an architecture style used in web services without the need of using additional protocols like SOAP for structuring data and meta information. Since HTTP is already organized and structured, the need of additional information to standardize the data as in SOAP does not matter anymore.
The web service that uses this style is called RESTful Web Service, or simply just a REST Service. With time, the term Web Service became more associated with SOAP and the term REST Service became more associated with RESTful Web Service.
REST suggests that we should leverage the existing HTTP methods to provide support for CRUD operations. The idea of REST is to use all website URL’s as access points to resources on the server. Let’s look at a standard HTTP call to see what it provides.
HTTP
Any HTTP call, is divided into two parts: Header and Body. The header contains meta information and the Body contains the information we need to send to the other side.
The Header contains information like address, method, content-type etc.. The address is simply a URL, the method is one of HTTP methods (Common methods are: GET, POST, PUT, and DELETE) We can use these methods to perform our CRUD operation. Therefore, GET translates to Read, POST to Create, PUT to Update, and DELETE to delete.
The content type tells us what is in the body of HTTP, could be XML, HTML, JSON etc. However, JSON is preferred due to its light weight and easy to parse nature. We can say that JSON is the de facto industry standard for sending REST data over HTTP.
Since REST leverages the HTTP protocol, it does not need to apply strict standards to the data as in case of SOAP. Strict standards applied in SOAP increases the size of Data significantly and makes it slower and harder to parse especially that it uses XML data type.
In REST, JSON can be used in the body of HTTP instead of XML without additional files which makes it significantly faster and easier to process.
We can define a Rest Service contract using these conventions. Let’s go back to our examples and apply a RESTful operation for creating sales.
The HTTP header will look like this:
In the header we used POST method since we want to create a sales data. We specified the address for this resource in the accounting application, and we set the content type to JSON so the server would parse the supplied data in JSON.
So the contract says whenever we want to call this address, we should structure our HTTP call in that way. Similarly, we can use the same address with a different methods to perform different actions like reading, updating, and deleting.
Thats all what we need to do with rest, as HTTP will take care of everything else. We don’t need to supply standards in the body to tell the server how to read the data as in SOAP.
HTTP Request and Response
When we send HTTP calls, we call it HTTP request. and the response we receive is called HTTP Response.
Now if you think about the bigger picture when using HTTP. Can you tell what HTTP are you sending when you type: http://www.google.com in the browser and what we get?
As you can see, we sent an HTTP GET method to the google server which is located at http://www.google.com, we did not specify the content type as we are not sending any data, we are simply requesting data to read. Google server sends back a response. The response header gives us additional information. In the first line we see a status code 200 which means everything is OK. There are different status codes for every status, for example the code 404 means the requested resource was not found, you have probably seen this before. Also in the header, we can see content-type set to HTML. This means google server is telling us that the supplied data is in HTML.
In the body of the response message, we see HTML data, so the browser shows you Google Page content as HTML.
Here is an exercise for you, let’s say you want to login into Facebook. What HTTP should be sent? and what we get? Think for a minute then read the answer below.
Solution: Well, again it’s easy. It’s just a POST method at http://www.facebook.com/login, with body containing your email and password written in JSON, the response contains an HTML page to your logged-in facebook home page if login is successful (200). Or a response status of 400 (Bad request) if the login was not successful. The browser shows a message that the login was not successful.
API
So now that we know what REST and HTTP are, we can separate our applications by their logic. In my previous article, I talked about client-server architecture. Any web service has a consumer and a provider. A consumer is the one who calls the web service, and the provider is the software that provides the web service. We can translate this into client and server where the client is the consumer of the web service, and the server is the provider. (Note that The consumer can also be a server that is talking to another server, hence, the client in this case is just another server).
In our example of sales and accounting applications, the consumer is the sales application, and the provider is the accounting application. Where sales application needs to call accounting application to update ledger.
We can define several functions in the accounting web service for different purposes to be exposed for external calls, for example, create sales, update sales, create purchase.. etc. This creates an interface for the accounting application. The set of these functions are called Application Programming Interface or API.
Let’s assume a more comprehensive scenario. For example let’s say we built a software that is responsible for of handling customers logic. This software exposes a set of functions to handle customer operations like create customer, update customer information, delete a customer, and read customer information. We call these functions Customer API.
Our customer REST API is located on the this url: http://www.company.com/customer/api
Applying REST architecture style, our REST API will have the following functions:
GET: /customers
GET: /customers/1
POST: /customers
PUT: /customers/1
DELETE: /customers/1
Can you tell each function by the url only? Let’s explain:
The first one’s url is http://www.company.com/customer/api/customers
it simply retrieves a list of all customers.
The second one is located at http://www.company.com/customer/api/customers/1
and retrieves the customer with an ID 1.
The third one creates a new customer (customer information is supplied in the body). The forth one updates the customer with ID 1 (information is supplied in body). and the last one deletes the customer with an ID 1.
Note that we almost used the same URL but changed the HTTP methods for each function, and the API differentiates them by their method. All of these are documented in the API.
Although all websites are powered by HTTP, by default, not any website is a RESTful application. There are conventions need to be applied to make the application restful. The most important one is to make each URL of the website an access point to the resources where we they respond to CRUD operations, as we showed in our customers API. A website like YouTube is a restful website as each URL is an access point to a resource on the server.