A Beginner's Guide to APIs and RESTful APIs with Node.js and Express

What is an API?

Before we talk about REST and RESTful APIs, we should have a firm grasp of what exactly is an API. An API — Application Programming Interface — is a set of rules and protocols that allow different software applications to communicate, interact and share data.

To create an API in Node.js and Express, we can:

npm init //initialize a package.json
npm install express //install the express package

const express = require("express");
const app = express();
const PORT = 3000;

app.get("/", (req, res) => {
    res.send("Hi, I'm at Code with Matt");
})

app.listen(PORT, () => {
    console.log(`Server is running on PORT ${PORT}`)
})

What is REST?

Now, that we have a clearer notion of what an API is, we can take the next step and talk about REST, which is an architectural style for building web services and APIs that use HTTP — HyperText Transfer Protocol — requests to retrieve and manipulate data. REST stands for REpresentational State Transfer and is based on a set of principles or constraints that help ensure they are scalable, flexible, and easy to use.

What is a RESTful API?

Having briefly seen what an API and REST mean, we can explore in more depth what a RESTful API is.

RESTful API is an architectural style for building web services that uses HTTP to communicate between the client and server, based on the concept of resources, where each resource is identified by a unique URI.

The key principles of RESTful API design include client-server architecture, statelessness, cacheability, a uniform interface, and a layered system. Let's see them in more depth:

1. Client-server architecture: A clear separation between the client and server, which allows both to evolve independently and our system to be more scalable.

2. Statelessness: The server shouldn't store any client context between requests. In other words, each request should contain all the information necessary for the server to understand the request.

3. Cacheability: Responses should be cacheable to improve performance and scalability.

4. Uniform interface: The API should adopt the same HTTP methods — GET, POST, PUT, and DELETE — for all resources.

5. Layered system: The API should be built as a layered system, with each layer responsible for specific functionality.

Using HTTP methods such as GET, POST, PUT, DELETE, etc., clients can manipulate resources represented by URIs, and the server responds with the appropriate resource representation. RESTful API is ideal for building web services that need to be accessed by multiple devices and platforms due to its simplicity, scalability, and flexibility.

Now, let's improve our previous API, adopting the REST architectural style to build a RESTful API.

const express = require("express");
const app = express();
const PORT = 3000;

const users = [];

// get: we get all users
app.get("/", (req, res) => {
  res.send(users);
});

// post: we add a user
app.post("/user", (req, res) => {
  // we get the user from the request body
  const user = req.body;
  // we add the user to the users array
  users.push(user);
  // we send a response to the client
  res.send("user added");
});

// put: we update a user
app.put("/user/:id", (req, res) => {
  // we get the id from the request parameters
  const id = req.params.id;
  //  we get the updated user from the request body
  const updatedUser = req.body;
  //   we update the user in the users array
  users[id] = updatedUser;
  //   we send a response to the client
  res.send("user updated");
});

// delete: we delete a user
app.delete("/user/:id", (req, res) => {
  // we get the id from the request parameters
  const id = req.params.id;
  // we delete the user from the users array
  users.splice(id, 1);
  // we send a response to the client
  res.send("user deleted");
});

app.listen(PORT, () => {
    console.log(`Server is running on PORT ${PORT}`)
})

Conclusion

To sum up, APIs and RESTful APIs are essential components of modern web development, allowing different applications to communicate and share data. RESTful APIs, in particular, follow a set of principles or constraints to ensure they are scalable, flexible, and easy to use.

By adopting HTTP methods and using URIs to represent resources, RESTful APIs provide a uniform and accessible way for clients to interact with servers.

In this blog post, we've learned what APIs and RESTful APIs are, the key principles of RESTful API design, and how to create one with Node.js and Express. I hope that with this knowledge, you can build your first RESTful API and start building robust and scalable applications.

See you in the next one!