Understanding and Using REST APIs


You have probably encountered “REST APIs” several times and wondered what it did. Many people do not know what REST is and what RESTful means. Most pages online have a somewhat complicated explanation of these APIs because computer programmers write them. Below, we attempt to demystify REST APIs for the average Joe.

What are REST APIs?

To put it in simple words, REST stands for Representational State Transfer. It is used for designing distributed systems within specific constraints. REST can be considered a resource since it defines the rules.

The constraints the REST API defines include the client-server model, uniform interface, and stateless interaction. Now, if you still have no idea what this means and all you want is to ensure that the API is RESTful, allow me to explain. However, we’ll need to examine how the World Wide Web works.

Let’s Start with the Client Server

Understanding and Using REST APIs 1When you type in stoplight.io into your web browser, the browser is the client, and it uses the HTTP protocol to send a GET request to the server associated with the URL. The server responds, and the browser gets that response and renders the web page or application.

In the model described above, the servers are your resource providers or the service with the client requesting resources. There are many clients, which range from PCs to ATMs and Android devices.

The advantage of adding a constraint to the client-server model is that it will classify each concern. So, as long as a separate server provides the data, your client can make anything and even change it.

The Stateless Interaction

When you use a RESTful design, the server cannot store a communication state. The client saves the sessions. Consequently, if the server gets two very different requests from the same browser, it will not remember the first instance of the request by the time it reaches the second one. So, every request from a client will carry all the required information for the necessary action to be taken by the server.

As the number of clients grows, the server will not get bogged down by keeping track of each client’s request. Not needing to store all that information will ensure the system scales successfully to any size.

The REST API shouldn’t have any logout or login function, which would require sessions and isn’t allowed. So, to authorize and authenticate clients, the server will pick up information from within every request. An instance of this is the JSON web tokens used for authentication.

Why do you need a resource?

A resource can represent an object, like an image or a customer. It can be just about anything, so it is up to the API developer to decide which part of the system will be mapped to these resources.

Let’s say you’re developing a REST web API for a server that hosts a chain of stores selling musical instruments like guitars. So, possible resources will be stores, customers, guitars, visits, sales, employees, etc. Everything can be mapped to the resources.

REST requires that every resource be unique. So, an ID needs to be assigned to each resource. For instance, stores selling musical instruments would be /store/1 and then /store/2, stored as two unique resources with their IDs 1 and 2, respectively. You can also have nested resources; for instance, having employee no. 2 in-store now. 2 the URI will be /store/2/employee/2.


While REST was not mainly intended as a web service, it did tie directly into HTTP. By its very nature, HTTP is a RESTful protocol used by all REST implementations. So, it is safe to say that 90% of those reading this article may intend to use it to build a Web API over the HTTP protocol. However, the rest of the API design tools help streamline the design process.