Creazione di API RESTful con Node.js ed Express

Le API RESTful sono alla base della comunicazione tra applicazioni moderne. Siti web, app mobile e software aziendali si scambiano dati tramite queste API, sfruttando protocolli standard come HTTP e formati leggeri come JSON. In questa guida, imparerai a creare una REST API utilizzando Node.js ed Express. Due delle tecnologie JavaScript più popolari per lo sviluppo backend. Vedremo passo passo come strutturare una semplice API, come gestire le richieste HTTP e come creare un sistema CRUD per risorse come utenti.

Cos'è un'API RESTful?

Una REST API (Representational State Transfer) è un'architettura per creare servizi web scalabili e leggeri. Segue questi principi:

• Usa i metodi HTTP: GET POST PUT DELETE
• Lavora su risorse identificate da URL.
• È stateless: ogni richiesta è indipendente.
• Restituisce dati in formato JSON (o XML, ma JSON è lo standard moderno).

Requisiti iniziali

Per seguire questa guida ti servono:

• Node.js
• Un terminale e un editor di testo (Visual Studio Code consigliato).
• Conoscenza base di JavaScript e dei metodi HTTP.

Inizializzare il progetto

Apri il terminale e crea una nuova directory per il progetto:

mkdir api-rest-node
cd api-rest-node
npm init -y

Installa Express, il framework backend minimalista:

npm install express

Per uno sviluppo più comodo, puoi installare anche nodemon:

npm install --save-dev nodemon

Aggiorna gli script del tuo package.json per avviare il server in sviluppo:

"scripts": {
  "start": "nodemon index.js"
}

Creare il server con Express

Nel file index.js, scrivi il codice base per avviare un server Express:

// index.js
const express = require('express');
const app = express();
const PORT = 3000;

// Middleware per il parsing JSON
app.use(express.json());
// Rotta di test
app.get('/', (req, res) => {
  res.json({ message: 'Benvenuto nella tua API RESTful con Node.js ed Express!' });
});

// Avvio del server
app.listen(PORT, () => {
  console.log(`Server in ascolto su http://localhost:${PORT}`);
});

Avvia il server con:

npm start

Vai poi su http://localhost:3000

API CRUD: creare, leggere, aggiornare e cancellare risorse

Simuliamo una gestione di utenti con un array in memoria. Le rotte saranno:

Metodo	Rotta	Azione
GET	/users	Ottieni tutti gli utenti
GET	/users/:id	Ottieni un utente specifico
POST	/users	Crea un nuovo utente
PUT	/users/:id	Aggiorna un utente
DELETE	/users/:id	Elimina un utente

Dati d'esempio

let users = [
  { id: 1, name: 'Mario Rossi', email: 'mario@example.com' },
  { id: 2, name: 'Giulia Bianchi', email: 'giulia@example.com' }
];

GET /users – Elenco utenti

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

GET /users/:id – Utente singolo

app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  user
  ? res.json(user)
  : res.status(404).json({ message: 'Utente non trovato' });
});

POST /users – Crea nuovo utente

app.post('/users', (req, res) => {
  const { name, email } = req.body;

  if (!name || !email) {
    return res.status(400).json({ message: 'Nome ed email sono obbligatori' });
  }
  const newUser = {
    id: users.length + 1,
    name,
    email
  };

  users.push(newUser);
  res.status(201).json(newUser);
});

PUT /users/:id

app.put('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) {
    return res.status(404).json({ message: 'Utente non trovato' });
  }

  const { name, email } = req.body;
  user.name = name || user.name;
  user.email = email || user.email;
  res.json(user);
});

DELETE /users/:id – Elimina utente

app.delete('/users/:id', (req, res) => {
  const index = users.findIndex(u => u.id === parseInt(req.params.id));

  if (index === -1) {
    return res.status(404).json({ message: 'Utente non trovato' });
  }
  users.splice(index, 1);
  res.json({ message: 'Utente eliminato correttamente' });
});

Middleware e sicurezza base

Log delle richieste:

app.use((req, res, next) => {
  console.log(`${req.method} ${req.path}`);
  next();
});

Gestione degli errori:

app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ message: 'Errore interno del server' });
});

CORS (se necessario). Per permettere chiamate da altri domini (es. un'app React):

npm install cors

const cors = require('cors');
app.use(cors());

Testare l'API

Puoi usare:

• Postman
• Insomnia
• Oppure curl nel terminale:

curl http://localhost:3000/users

Per inviare dati (esempio POST

curl -X POST http://localhost:3000/users \
-H "Content-Type: application/json" \
-d '{"name": "Luca Verdi", "email": "luca@example.com"}'

Organizzazione del progetto (scalabilità)

Quando l'API cresce, organizza meglio i file:

/api-rest-node
├── index.js
├── routes/
│   └── users.js
├── controllers/
│   └── usersController.js

Espansioni utili

Una volta capito il funzionamento base, puoi aggiungere:

• Database (MongoDB, PostgreSQL, MySQL
• Autenticazione JWT.
• Validazione con Joi o express-validator.
• File upload con Multer.
• Rate limiting per sicurezza.

Conclusione

In questo articolo abbiamo esplorato in dettaglio come costruire un'API RESTful da zero utilizzando Node.js ed Express. Due strumenti essenziali nello sviluppo backend moderno. Abbiamo imparato a creare un server, a definire rotte per la gestione delle risorse e a gestire le richieste HTTP attraverso operazioni CRUD (Create, Read, Update, Delete) restituendo e ricevendo dati in formato JSON. Lo standard più utilizzato nelle comunicazioni web.

Abbiamo inoltre visto come arricchire il progetto con middleware personalizzati, gestione degli errori, logging delle richieste e, dove necessario, supporto al CORS per permettere chiamate cross-origin.

Questa struttura rappresenta una base per lo sviluppo di API professionali, scalabili e mantenibili. La semplicità di Express consente di iniziare subito a sviluppare. Offre però anche la flessibilità necessaria per crescere con il progetto, integrando ulteriori funzionalità come database (MongoDB, MySQL, PostgreSQL), sistemi di autenticazione (come JWT), validazione dei dati, rate limiting per la sicurezza, o file upload con librerie come Multer.

Le API RESTful sono fondamentali per applicazioni moderne. Sia che tu stia creando un frontend con React o Vue, sia che tu stia sviluppando una mobile app, l'API è ciò che collega il mondo dei dati con l'interfaccia utente. Saper progettare una buona API significa anche saper pensare in modo modulare, orientato ai servizi, e attento alla scalabilità.

Imparare a padroneggiare queste tecnologie ti darà un grande vantaggio nel mondo dello sviluppo web. Ti permetterà poi di costruire applicazioni complete, professionali e pronte per la produzione.

Se vuoi continuare, ti consiglio di approfondire:

• Connessione a un database (con mongoose o knex).
• Modularizzazione avanzata con router e controller.
• Autenticazione e autorizzazione con token.
• Scrittura di test automatici con Jest

Che tu sia uno sviluppatore alle prime armi o un professionista che vuole velocizzare il lavoro, padroneggiare queste basi ti aprirà molte porte nel mondo del full-stack development.