LUCAS CASTRO
REST API's in a Nutshell

REST API's in a Nutshell

Lucas Castro's photo
Lucas Castro
·

4 min read

Introduction

The world of web development is full of weird acronyms. MVC, HTTP, URL, www, REST, API, and so on. These acronyms have a specific meaning and describe important aspects of web technology and design. In this article, I will be addressing two of them, REST and API. I will begin by contextualizing APIs and then diving into REST.

What is an API?

I could write a whole article just about APIs (as I probably should) and their importance for the web, but today I really want to focus on the REST acronym. So in a nutshell, API stands for Application Programming Interface. Great, so what does it really mean?

According to the Lexico Oxford dictionary, an API is a set of functions and procedures that allows the development of different applications and systems. In other words, an API is a service that establishes how two different systems, will interact.

Usually, APIs serve as a bridge between the client (front-end) and the server (back-end). When a client wants to send data to the server, or the server sends a response back to the client, it is the API that defines how these requests and responses will be handled and delivered.

What is REST?

Now that we have a basic understanding of what an API is, REST will make more sense. Apart from being something that I am currently needing, REST is an acronym that stands for Representational State Transfer. It is a type of software architecture that models how web services should be created.

In a REST architecture, web resources are represented textually instead of visually, as is the case of the MVC (Model-View-Controller) architecture that is often used in server-side rendered applications. In a REST service, HTTP requests that are made to a web resource will generate a response in an HTML, XML, or JSON format.

Like any software architecture, REST has six constraints that outline the development of REST APIs. They are:

  • Client-Server: There must be a separation of concerns between the client (usually the front-end) and the server where the data is being stored (back-end). This constraint allows great portability, as now multiple clients (web or mobile apps) can have access to our server resources.

  • Stateless: Each request must contain all the information necessary for the server to be able to process its response back to the client. Taking advantage of a stored context on the server is not allowed.

  • Cacheable: Server responses must inform explicitly or implicitly whether the response data for a request can be cacheable or not. Uniform Interface: Maintain uniformity (consistency and standards) in an interface construction.

  • Layered System: When a client access an endpoint, it is not necessary to expose implementation details for the server to generate a response.

  • Code on Demand (optional): Allows code and scripts to be downloaded and executed on the client.

When an API meets all of these constraints, that API is now considered RESTful.

Example

Now we understand the theory, but how does a RESTful API look like in code? Here is a very basic example in Node.js using the Express framework.

const express = require('express');

const app = express()

/* An example of a type of web resource. In real-world applications these resources are data from a database */
const users = [
  {
    username: 'lucasamonrc',
    github_url: 'https://github.com/lucasamonrc',
    repositories: 23,
  },
  {
    username: 'someuser',
    github_url: 'https://github.com/someuser',
    repositories: 30,
  },
  {
    username: 'another',
    github_url: 'https://github.com/another',
    repositories: 15,
  },
]

// The HTTP method that handle GET requests to the server
app.get('/users', (request, response) => {
  // A response data formatted in JSON
  return response.json(users);
}

app.listen(3333, () => console.log('Server is running'));

This is a pretty silly example of the beginnings of a RESTful API. But note how the response is being made in a JSON format back to the client. It will be now up to the client how to use that data.

Conclusion

There is much more to RESTful APIs; however, I believe that these things are a really good start to understand this type of architecture so you can start implementing it on your projects.

If there is anything that I would like you to have learned from this article, is that a RESTful API have a separation of concerns between the front-end client and the back-end server; and that the communication is made between a data structure model like JSON, instead of a complete rendered page or view.

If you would like to see more examples of RESTful APIs, please visit my GitHub repositories and look at some of my projects, I am pretty sure you will be able to learn a thing or two.

REST APIbackendExpressJavaScript