Understanding and Using REST APIs


You have probably run into the term “REST APIs” quite a few times and ended up wondering what it really did. Many people have no idea what REST is and what the term 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 constraints.

The constraints defined by the REST API include the client-server model, uniform interface, and stateless interaction. Now, if you still have no idea what all of 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 Webworks.

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 then responds with 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 those for the PC to an ATM and Android devices.

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

The Stateless Interaction

When you use a RESTful design, the server is incapable of storing 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 gets the second one. So, every request that comes from a client will carry all the required information for the necessary action to be taken by the server.

The idea behind this is that 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 that the system scales successfully to any size.

The REST API shouldn’t have any logout or login function, which would require sessions and so 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 be a representation of 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, in stores selling musical instruments, it would be /store/1 and then /store/2, stored as two unique resources with their IDs 1 and then 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. HTTP, by its very nature a RESTful protocol that is used by all REST implementations. So, it is safe to say that 90% of those reading this article may intend for it to be used to build a Web API over the HTTP protocol. However, the rest API design tool helps streamline the entire design process.