How to Build RESTful APIs? The Unknown Hero Under The Hood (Part 1)
We use technology with almost everything in our life, to communicate and socialize with friends and family, to purchase and buy things from stores, and to learn new things.
How does this happen? How does data get from one place to another? How different applications and devices communicate with each other to allow us to upload a video for our friends to watch on Facebook, to chat with family, or to enroll in an online course to learn something new?
APIs (application programming interfaces) help us achieve all of that, it’s the unknown hero under the hood. In this article, I will talk about the following:
- Introduction to APIs — Part 1
- What is REST? — Part 1
- Why REST API? — Part 1
- Summary — Part 1
- How to build a REST API? — Part 2
Introduction to APIs
A long time ago, car manufacturers were used to building cars as one function or entity, they manufacture the car engine, doors, wheels, and all other parts of the car by themselves. Then, they started to build each part in the car as a separate function independently, nowadays, the market is really huge, there are a lot of companies and manufacturers that are specialized in manufacturing car engines for example, and that’s the only thing they do, and there are other companies that are specialized in manufacturing car wheels and so on. This makes cars more perfect because each company focuses on one small part.
In the software industry, we were developing software as one monolithic application, we faced a lot of problems back then but nowadays, we separate logical functionalities in one software into multiple logical independent units (we usually call them services), let’s take an online learning platform as an example, the following are the logical units for the online learning platform:
- Authentication service
- Student enrollment service
- Content building service
- Learning management system
The authentication service deals with user login, registration, and authorization logic. Student enrollment service deals with everything that is related to student enrollments in courses. The content building service deals with course content creation. The learning management system deals with student states, grades, and progress in courses.
As you can see each service has its own responsibilities, it only handles its part of the job, no one can touch any logic related to the other services. That’s cool, right?
Software services need to interact with each other to provide users with the intended full experience. APIs (application programming interface) is a way for applications to communicate with each other without having to know how other applications are implemented, this provides flexibility, simplification, and a big room for innovation.
An application programming interface (API) is a computing interface that defines interactions between multiple software intermediaries. It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc. It can also provide extension mechanisms so that users can extend existing functionality in various ways and to varying degrees.
— Wikipedia
What is REST?
Imagine that each application uses its own approach of building an API without unified standards, eventually, it will lead to a missy situation so we need to introduce some unified standards or a unified style of building APIs.
Thanks to REST, it provides a unified style of designing an API and it sets a list of constraints to standardize how applications communicate with each other. RESTful APIs allow clients to access and manipulate data using a textual representation of resources like XML and JSON.
Most of the RESTful APIs use JSON as a textual representation for resources. JSON (JavaScript Object Notation) is a lightweight data-interchange format, that is easy for humans to read and understand, at the same time it’s easy for machines to parse.
Representational state transfer (REST) is a software architectural style that defines a set of constraints to be used for creating Web services. Web services that conform to the REST architectural style, called RESTful Web services, provide interoperability between computer systems on the internet. RESTful Web services allow the requesting systems to access and manipulate textual representations of Web resources by using a uniform and predefined set of stateless operations.
— Wikipedia
Some people mix between HTTP and REST, they are different things. HTTP (Hypertext Transfer Protocol) is an application-layer protocol for transmitting hypermedia documents, such as HTML (Hypertext Markup Language). REST (Representational State Transfer) is a set of rules, that when followed, enable you to build a distributed application that has a specific set of desirable constraints, it uses HTTP to transport messages between applications.
Interacting with REST APIs often involves the use of CRUD-like functions because they are built around resources, which can be created, updated, read, and deleted. The best practice of using CRUD-like functions in REST is as follows:
When we want to create a new resource we usually use the POST HTTP method, PUT method with updating a specific resource, DELETE method with deleting a specific resource, and GET method with retrieving either a list of resources or a specific resource.
In order to design a RESTful API you have to follow the following 6 constraints:
- Client-server — By separating the user interface from the backend logic and database storage, we improve backend scalability and improve portability for the user interface.
- Stateless — Each request from the client to the server must contain all the necessary information without using any existing state context in the backend, each request cannot know anything about any other request.
- Uniform interface — Must decide an API interface for resources inside the application. Each resource in the application should have one URI only. All resources should be accessed through a common approach like the above CRUD methods. It’s used in REST in order to simplify things.
- Cachable — Resources must declare if they are cachable or not, caching shall be applied to them when applicable. Caching can be on the client-side or the server-side, it doesn’t matter.
- Layered system — Allows you to use layered system architecture, you can deploy your APIs to a server, data storage to another server, and do some other logic on a third server.
- Code on demand (optional) — Most of the time you will be returning resources in the form of JSON or XML but it’s allowed to return an executable code in REST to the client-side (e.g. a client can call the API to request a UI widget to render).
Why REST APIs?
Designing our API with REST constraints in mind will provide you with the following advantages:
- Scalability
Because the client-side is separated from the server-side, the application might be scaled easily without facing any challenges. Application services can remain stable while adapting to changes, upgrades, overhauls, and resource reduction. - Flexibility and Portability
Because application components are loosely coupled, the application will have the ability to adapt to possible or future changes in requirements, It is possible to migrate from one server to another at any time, it can adapt when external changes occur, and it can respond to uncertainty. Also, the frontend and the backend can be hosted on different servers. - Independence
Due to the separation between client-side and server-side, REST makes it easier for teams to develop multiple areas of an application independently, it offers the ability to try numerous environments during development because it always adapts to the working syntax and platform.
Summary
So now you know how applications communicate and interact with each other, each service has its own API and we use REST to provide a unified style of designing an API and to set a list of constraints to standardize how applications communicate with each other. Also, you know the 6 main constraints of REST and we follow them to take the advantage of scalability, flexibility, portability, and independence.
Next Part: How to build a REST API?
In the next part, we’ll go through DOs and DONTs, the important technical principles, and best practices in RESTful APIs. Then, we’ll walk through steps on how you can build a RESTful API using Flask microframework from A-Z.
