REST API Design Explained

What:

The API is an interface, through which a client can acquire information from a server, the goal is for it to be reliable, quick, and easy.

Imagine yourself at a restaurant, the API is like a waiter making the link between your table and the kitchen, it transmits information from a client (your table) to the kitchen (the server). It sends data out and provides a result.

The term REST stands for REpresentational State Transfer. It’s a particular architectural style that defines a Web Services, think of it as a set of rules and good practices to build an API. The general idea behind id is to communicate not by sending out a stream of data, but by describing the object that represents that data. The user then gets a description of the data he’s asking for.

For example, imagine a user is requesting a movie, you receive a request for information about the title, duration, languages available, subtitles, cast, etc… The server then creates an object with all this information to best describe the demanded movie. What is sent by the server is the state of that object. That’s why the method is known as Representational State Transfer.

This architecture style uses less bandwidth and makes applications more suitable for large user bases.

Let’s now look at the reasons why you should understand the need for a REST API.

Why:

Let’s imagine for this explanation that you are Netflix and have to provide millions of users with movies. You’d need large amounts of data as the information on your servers is never static, you either have new movies coming out or shows that depend on what cities the users are in. In any case, your data is constantly changing and makes your lives even harder.

How do you think a user or its application would receive that data ?

Well, that data is received from the application to a Web-server, a request gets sent, asking for the movie via an API. The user doesn’t see any of that happening, it all happens behind the curtains. The server receives that request and sends back its response.

As a user, what you see is an HTML page, however, the server doesn’t directly send out its information as an HTML page, it would use a lot of bandwidth and make it very difficult for developers to get easy information on what the web page contains.

The information received is in a structured format rather than a complete Web page, often as a JSON or XML file. These files both have hierarchical structures.

With this in mind, there is still an issue with the framework we’re using. Requesting a movie would mean that the application has to send out a lot of requests and using this method to retrieve complex data would prove quite time-consuming and cumbersome.

This is the exact moment where REST APIs introduce themselves, the REST API creates an object of the desired data and then sends out the requested information about it in response to the client. The client which now has access to the object can ask for any specific information about that item.

In a sense, it’s like introducing the topic of a discussion between the client and the server, the user can then ask any question on the topic, this ensures both subjects know what they’re talking about and are ready to transmit the data.

How:

To help you understand how to build one, let’s take a look at the principles laid down by Dr.Fielding, the designer of the REST API:

• Stateless

Any request from the user has to contain the required information to make the server understand what the request is. Most of the time, this is done through a URL, body, or header of the HTTP protocol. Once processed, the information is sent back to the user through the body, status, or headers part of an HTML page.

• Client-server

This type of architecture separates a server from its user, enhancing security. It also creates a uniform interface that makes it portable across multiple platforms and scalable.

• Cacheable

Part of the goals of this architecture is performance, for that reason, requests are often cacheable, meaning the server will keep his response in memory for easy access and so that clients can reuse that data later on.

• Layered system

Using the REST architecture makes an application more layered, it limits the behavior of a user and makes the overall application more stable. As layers can’t interact with one another, the applications are often more secure. By having different layers and with the right cache architecture, applications also become more balanced in terms of load on the system which in turn helps with scalability and performance

• Code on demand

This constraint is optional as it allows clients to download code to be used within their applications for efficiency purposes.

        The REST API Design is an architecture type that aims at standardizing the output from a server. The main idea is that the server creates an object from a user request, that object serves as the communication thread between client and server. As data becomes more and more complex, REST proves itself as a way to improve efficiency, performance, and scalability.