Setting Up Your Environment

To get started, ensure you have Node.js and npm installed on your machine. You can verify this by running the following commands in your terminal:

node -v
npm -v

If you don’t have them installed, download and install Node.js from the official website.

Creating a New Express Application

  1. Create a new directory for your project:
   mkdir express-api
   cd express-api
  1. Initialize a new Node.js project:
   npm init -y
  1. Install Express.js:
   npm install express

Basic Structure of an Express Application

Create a new file named app.js in your project directory. This file will contain the main application code.

const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;

// Middleware to parse JSON requests
app.use(express.json());

// Basic route
app.get('/', (req, res) => {
  res.send('Welcome to the Express API!');
});

// Start the server
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

Running Your Application

To run your application, use the following command:

node app.js

You should see a message indicating that the server is running. You can test your API by navigating to http://localhost:3000 in your web browser.

Creating RESTful Endpoints

Now that you have a basic Express application set up, let’s create some RESTful endpoints.

Example: Managing a Simple To-Do List

We will create a simple API to manage a to-do list. This API will support the following operations:

  • GET: Retrieve all to-do items.
  • POST: Add a new to-do item.
  • PUT: Update an existing to-do item.
  • DELETE: Remove a to-do item.

Setting Up the To-Do API

First, we need an in-memory array to store our to-do items.

let todos = [
  { id: 1, task: 'Learn JavaScript', completed: false },
  { id: 2, task: 'Build an API with Express', completed: false },
];

Now, let’s create the routes for our API.

// GET all todos
app.get('/todos', (req, res) => {
  res.json(todos);
});

// POST a new todo
app.post('/todos', (req, res) => {
  const newTodo = {
    id: todos.length + 1,
    task: req.body.task,
    completed: false,
  };
  todos.push(newTodo);
  res.status(201).json(newTodo);
});

// PUT (update) a todo by ID
app.put('/todos/:id', (req, res) => {
  const todoId = parseInt(req.params.id);
  const todo = todos.find(t => t.id === todoId);
  if (!todo) {
    return res.status(404).json({ message: 'Todo not found' });
  }
  todo.task = req.body.task || todo.task;
  todo.completed = req.body.completed !== undefined ? req.body.completed : todo.completed;
  res.json(todo);
});

// DELETE a todo by ID
app.delete('/todos/:id', (req, res) => {
  const todoId = parseInt(req.params.id);
  todos = todos.filter(t => t.id !== todoId);
  res.status(204).send();
});

Testing Your API

You can use tools like Postman or curl to test your API endpoints.

Example curl commands:

  1. Get all todos:
   curl http://localhost:3000/todos
  1. Add a new todo:
   curl -X POST http://localhost:3000/todos -H "Content-Type: application/json" -d '{"task": "Write documentation"}'
  1. Update a todo:
   curl -X PUT http://localhost:3000/todos/1 -H "Content-Type: application/json" -d '{"completed": true}'
  1. Delete a todo:
   curl -X DELETE http://localhost:3000/todos/1

Best Practices for Building RESTful APIs

  1. Use Appropriate HTTP Methods: Use GET for retrieving data, POST for creating, PUT for updating, and DELETE for deleting resources.
  1. Use Status Codes: Return appropriate HTTP status codes to indicate the success or failure of an API request.
  1. Error Handling: Implement error handling to manage invalid requests and provide meaningful error messages.
  1. Versioning: Consider versioning your API (e.g., /api/v1/todos) to manage changes over time.
  1. Documentation: Use tools like Swagger or Postman to document your API endpoints for easier consumption by developers.

Conclusion

In this tutorial, you learned how to build a simple RESTful API using Express.js. By following best practices and structuring your application effectively, you can create scalable and maintainable APIs. Express.js provides a powerful foundation for developing web applications and APIs, allowing you to focus on building features rather than boilerplate code.

Learn more with useful resources