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 they are written by computer programmers. 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 Web works.

Let’s Start with the Client Server


When 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 providers of the resource or the service with the client requesting resources. There are an array of 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 there is a separate server providing the data, your client can make be 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, for instance, 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 continues to grow, 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, and 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 which 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 the case of 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 no. 2 the URI will be /store/2/employee/2.

Conclusion

While REST was not mainly intended as a web service, it did tie directly into HTTP. HTTP by its very nature a RESTful protocol which 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 to over the HTTP protocol. However, the rest api design tool helps streamline the entire design process.

 

Like it? Share it!