Express, REST API e OpenAPI

1. Le domande del design di una API REST

Nel capitolo 3 abbiamo visto il server Web che serve file, e poi il server con templating che li compone. Con Node.js il server diventa un programma che decide cosa rispondere: e appena si arriva a questo punto, la domanda smette di essere tecnica e diventa di design. Progettare una API REST significa rispondere a un elenco preciso di domande, che l'esercitazione mette in fila senza girarci intorno:

• Qual è il codice di stato della risposta HTTP appropriato per un determinato scenario? 101 200 201 302 400 404 418 500…
• Quali nomi utilizzare per i segmenti di percorso URI? /users/userId, /leagues/leagueName
• Quale metodo di richiesta deve essere utilizzato per interagire con la risorsa? GET POST PUT DELETE PATCH…
• Come mappare le operazioni non CRUD sugli URI? /message/messageId/send
• Come gestire le versioni delle rappresentazioni di stato di una risorsa? Nell'URL (/api/v1/leagues), in query (/api/leagues?v=1), negli header HTTP…
• Come strutturare un collegamento ipertestuale in JSON?

Sono domande che non hanno una risposta imposta dal protocollo: HTTP permette tranquillamente GET /deleteUser?id=1234. È il design a stabilire che quella richiesta è sbagliata, e le prossime sezioni servono esattamente a giustificare perché.

2. Resource modeling: i quattro archetipi

Quando si modellano le risorse di una API si può partire da alcuni archetipi di risorse di base. Un'API REST è composta da quattro archetipi distinti: document, collection, store e controller.

Document

Una risorsa documento è un concetto simile a un'istanza di oggetto o a un record di database. La rappresentazione del suo stato include in genere sia valori sia collegamenti ad altre risorse collegate. Il tipo documento è l'archetipo di base per gli altri archetipi. Ciascuno di questi URI identifica un documento:

http://api.soccer.restapi.org/leagues/seattle
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet

Un documento può avere risorse figlio che rappresentano i suoi concetti subordinati; con la sua capacità di riunire molti tipi di risorse diversi sotto un unico genitore, un documento è il candidato logico per la risorsa radice di una API REST — nell'esempio, http://api.soccer.restapi.org identifica il punto di ingresso.

Collection

Una collection è un repository di risorse gestita dal server, usata per raggruppare risorse correlate. I client possono proporre nuove risorse da aggiungere a una collezione, ma spetta alla collezione scegliere se creare o meno la risorsa, cosa vuole contenere, e decidere gli URI delle risorse contenute:

http://api.soccer.restapi.org/leagues
http://api.soccer.restapi.org/leagues/seattle/teams

Store

Uno store è un repository di risorse gestito dal client. Consente al client di inserire risorse, recuperarle ed eliminarle; da soli gli store non creano nuove risorse e non generano nuovi URI. Ogni risorsa memorizzata ha un URI che è stato scelto da un client quando è stata inizialmente inserita. L'esempio mostra un utente (con ID 1234) che inserisce un documento chiamato alonso nel proprio archivio di preferiti:

PUT /users/1234/favorites/alonso

Controller

Un controller modella un concetto procedurale: funzioni eseguibili, con parametri e valori restituiti, di input e di output. Una API REST si basa sulle risorse controller per eseguire azioni specifiche dell'applicazione che non possono essere mappate logicamente su uno dei metodi standard (CRUD). In genere compaiono come ultimo segmento in un percorso URI, senza risorse figlio che li seguono nella gerarchia:

POST /alerts/245743/resend

3. Operazioni su collection e su document

L'esempio guida dell'esercitazione è una smart city. Il punto di ingresso della API è http://api.smartcity.example.com/api, l'entità City ha un name (stringa) e una Population (numero), e le risorse possibili sono:

Le operazioni sulle collezioni sono quattro: GET .../cities elenca tutte le città, POST .../cities crea una nuova città nella collezione, PUT .../cities aggiorna la collezione con il contenuto della richiesta, DELETE .../cities elimina tutte le città. Sui documenti invece: GET .../cities/cesena recupera i dettagli, PUT .../cities/cesena li aggiorna, DELETE .../cities/cesena elimina la città — e POST .../cities/cesena non ha senso.

Lo stesso schema si applica alle relazioni tra risorse: GET .../cities/cesena/sensors elenca tutti i sensori a Cesena, POST .../cities/cesena/sensors ne crea uno nuovo, GET .../cities/cesena/sensors/12345 recupera il contenuto di quel sensore, PUT .../cities/cesena/sensors/12345 ne aggiorna i dettagli. La relazione City has Sensor diventa un percorso.

4. Best practice per gli URI

Le API REST utilizzano gli Uniform Resource Identifier per indirizzare le risorse, e i designer spaziano tra soluzioni molto diverse: dal parlante http://api.restapi.org/paris/louvre/leonardo-da-vinci/mona-lisa all'opaco http://api.restapi.org/68dd0-a9d3-11e0-9f1c-0800200c9a66. Le regole raccolte a lezione sono queste.

Gli antipattern citati esplicitamente per la penultima riga sono quattro, e sono istruttivi perché sbagliano in modi diversi: GET /deleteUser?id=1234 (verbo nell'URI e metodo sbagliato, con un GET che modifica), GET /deleteUser/1234 (idem), DELETE /deleteUser/1234 (metodo giusto ma verbo ridondante nell'URI), POST /users/1234/delete (l'operazione mascherata da risorsa controller quando esiste già il metodo standard).

Sul versioning l'esercitazione mette a confronto due forme senza imporne una: http://api.soccer.restapi.org/my-app/api/leagues?version=1 e http://api.soccer.restapi.org/my-app/api/v1/leagues.

5. Il corpo del messaggio e i codici di stato

Una API REST utilizza comunemente il corpo del messaggio di risposta per trasmettere lo stato della risorsa identificata dalla richiesta, con un formato basato su testo che rappresenta lo stato come un insieme di campi significativi. Oggi i formati più usati sono XML e JSON:

{
  "firstName": "Mario",
  "lastName": "Rossi",
  "address": {
    "city": "Cesena",
    "postalCode": "47521"
  }
}

Ogni risposta HTTP contiene poi un codice di stato che indica l'esito della richiesta del client: sono numeri a tre cifre, raggruppati per classe.

Si possono utilizzare codici standard e personalizzati, purché rispettino il significato della loro classe. La differenza tra 401 e 403 è la più fraintesa: il primo dice "non so chi sei", il secondo "so chi sei e non puoi".

6. Documentare l'API: OpenAPI e Swagger

Una API REST ben progettata deve essere anche ben documentata. La documentazione permette a sviluppatori e utenti di comprendere le risorse disponibili e i loro URI, conoscere i metodi supportati, vedere lo schema di richieste e risposte e conoscere i possibili codici di stato restituiti.

OpenAPI è uno standard per descrivere le API REST in modo strutturato e leggibile da una macchina. È stato creato inizialmente come Swagger Specification ed è ora gestito dalla OpenAPI Initiative (OAI). È un documento JSON o YAML che descrive risorse e path, parametri di input e output, schemi dei dati di richiesta e risposta, codici di stato e autenticazione.

I vantaggi elencati sono sei: documentazione interattiva; generazione automatica di SDK/client in vari linguaggi; creazione di mock server per test rapidi; integrazione in tool come Swagger UI o Postman; comunicazione più chiara tra sviluppatori backend e frontend; possibilità di generare la documentazione a partire dal codice. Swagger UI, in particolare, permette di visualizzare e interagire con le API tramite un'interfaccia web: elenco delle risorse disponibili, possibilità di provare le richieste direttamente dal browser, esempi di input e output generati automaticamente.

La struttura del documento segue cinque blocchi: versione della specifica, informazioni sull'API, definizione dei server, sicurezza, definizione dei path.

openapi: 3.0.0
info:
  title: SmartCity API
  description: API per gestire smart city
  version: 1.0.0

servers:
  - url: https://api.smartcity.example.com/v1

security:
  - bearerAuth: []

paths:
  /cities:
    get:
      summary: Elenca tutte le città
      tags: [Cities]
      responses:
        '200':
          description: Lista delle città
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/City'

Sulla stessa risorsa si descrive poi il post, con il requestBody obbligatorio e le due risposte possibili — 201 per la città creata con successo e 400 per i dati non validi — e infine i components, dove vivono gli schemi di autenticazione e i modelli di dati riutilizzabili:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    City:
      type: object
      properties:
        id:
          type: string
          example: cesena
        name:
          type: string
          example: Cesena
        population:
          type: integer
          example: 96500
        sensors:
          type: array
          items:
            $ref: '#/components/schemas/Sensor'
    Sensor:
      ...

L'esercizio associato chiede di partire dal file exercises/exercise-01/openapi-film.yaml, definire l'API Filmoteca per gestire dei film e validare il file con Swagger Editor. Un film ha i campi id, title, director, year e genres (un array).

7. Express: il primo server

Express si presenta come "Fast, unopinionated, minimalist web framework for Node.js". Permette di creare web server e API REST in modo semplice e veloce, e aggiunge molte funzionalità utili per lo sviluppo web. Le caratteristiche principali sono cinque: semplicità (API intuitive e facili da usare), flessibilità (adatto a esigenze e progetti diversi), middleware (supporto per funzioni che gestiscono richieste e risposte), routing (sistema potente e flessibile), performance (ottimizzato per alte prestazioni).

Le slide dello stack MEAN aggiungono il quadro d'insieme: Express è un web application framework server-side minimale e flessibile che facilita l'uso di Node.js e l'implementazione di API REST, supporta diversi template engine, fornisce routing, middleware e un sistema modulare, e — dettaglio importante — il layer di funzionalità che fornisce non "oscura" le funzionalità di Node.js. È spesso la base per architetture più complesse.

Si installa con npm install express --save (o semplicemente npm install express) dopo aver creato il progetto con npm init. Le modifiche che ne conseguono sono tre: package.json guadagna la dipendenza, compare package-lock.json con l'albero delle dipendenze, e nasce la cartella node_modules con il codice dei moduli.

Esiste anche express-generator, uno strumento che crea velocemente una struttura dell'applicazione: si installa con npm install express-generator e si usa per esempio con express --view=pug myapp.

Exact match e la rotta di fallback

Visitando una rotta non definita — per esempio /asw — la risposta è Cannot GET /asw, perché Express utilizza una logica di exact-match, in ordine di definizione delle rotte. Per gestire il caso si definisce in fondo una rotta che cattura tutto:

app.get('/*thepath', (req, res) => {
    res.setHeader('Content-Type', 'text/plain');
    res.status(404);
    res.send('Page not found ' + req.params.thepath);
});

Le due parole "in ordine di definizione" sono la cosa più importante di questa sezione: la posizione delle rotte nel file è semantica. Una rotta catch-all messa all'inizio intercetta tutto e rende irraggiungibile ogni rotta successiva.

8. Rispondere: JSON, file statici, parametri

Restituire JSON

Dato un file colors.json, per restituirne il contenuto sulla rotta /colors si importano i dati con require e si definisce l'handler. Ci sono due alternative:

const data = require('./colors.json');

// alternativa 1: header esplicito + send
res.header("Content-Type", 'application/json');
res.send(JSON.stringify(data));

// alternativa 2: json fa entrambe le cose
res.json(data);

Con res.json non è necessario specificare il tipo di contenuto: il metodo imposta l'header e serializza da solo. È il motivo per cui nelle API REST si usa praticamente sempre la seconda forma.

Servire file statici

Per restituire il file contacts.html alla rotta /contacts si può usare res.sendFile, che però richiede un path assoluto:

const path = require('path');
app.get('/contacts', (req, res) => {
    res.sendFile(path.join(__dirname, 'contacts.html'));
});

La domanda che l'esercitazione pone subito dopo è la più utile: e quando HTML e CSS sono separati, e la pagina include più file — script, fogli di stile, immagini? Serve una rotta per ogni file statico? No: si definisce una cartella public con dentro tutti i file statici e si servono in blocco con un middleware:

app.use(express.static('public'));

Parametri di rotta e query string

Ci sono due modi di passare un id, e a ciascuno corrisponde un accesso diverso:

app.get('/sayhello/:name', (req, res) => {
  res.send("Hello " + req.params.name + "!");
});

La scelta tra i due non è stilistica ma di design, e risponde alle regole della sezione 4: il path parameter identifica una risorsa (fa parte della gerarchia), la query string filtra o impagina una collezione. /films/12 è un film; /films?director=Nolan è un sottoinsieme della collezione dei film.

9. Router e middleware

Il routing gestisce le richieste verso path specifici e permette di organizzare il codice in modo modulare, separando le rotte. Il costrutto è express.Router(), che si comporta come una mini-applicazione esportabile:

const express = require('express');
const router = express.Router();

router.get('/', (req, res) => {
  res.send('Lista di risorse');
});

router.post('/', (req, res) => {
  res.send('Crea nuova risorsa');
});

router.get('/:id', (req, res) => {
  res.send('Dettagli risorsa ' + req.params.id);
});

module.exports = router;

Middleware

Le funzioni middleware sono blocchi che elaborano richieste e risposte. Possono fare quattro cose: eseguire codice, modificare req e res, terminare la richiesta, oppure passare il controllo al middleware successivo chiamando next().

function logger(req, res, next) {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  next(); // passa al middleware/rotta successiva
}

app.use(logger);

Express ne fornisce alcuni già pronti: express.json() per il parsing del JSON nel body delle richieste, express.urlencoded() per i dati di form (x-www-form-urlencoded), express.static() per servire file statici — quest'ultimo lo abbiamo già usato senza chiamarlo per nome.

10. CORS, validazione, sessioni e JWT

CORS

Cross-Origin Resource Sharing è una sicurezza del browser che impedisce richieste a origini diverse. Per abilitare l'accesso da frontend esterni si usa il pacchetto cors:

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

Questo è il middleware che serve nel momento in cui, dal capitolo 10 in poi, il frontend Vue gira su una porta diversa da quella del backend Express: due porte sono due origini, e senza CORS il browser blocca la chiamata.

Validazione dei dati

express-validator è un insieme di middleware per la validazione e la sanificazione dei dati nelle richieste HTTP:

const { body, validationResult } = require('express-validator');

app.post('/user', body('email').isEmail(), (req, res) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }
    res.send('Utente valido!');
  }
);

Notate la forma: il validatore è passato come middleware nella definizione della rotta, prima dell'handler, e l'handler si limita a leggere il risultato. E notate il codice di stato: 400 Bad Request, perché l'errore è del client.

Autenticazione e sessioni

Due strade. JWT (pacchetto jsonwebtoken) per l'autenticazione stateless: il token viaggia con ogni richiesta e il server non conserva nulla — coerente con la natura stateless di HTTP vista nel capitolo 3. Cookie e sessioni (express-session) per gestire sessioni utente, cioè per aggiungere stato:

const session = require('express-session');
app.use(session({
  secret: 'segreto',
  resave: false,
  saveUninitialized: true,
  cookie: { secure: false } // true se HTTPS
}));

11. La struttura routes, controllers, models

Arrivati a questo punto un file unico non regge più, e l'esercitazione impone la buona prassi: separare il codice in moduli. Tre cartelle, tre responsabilità:

Questo approccio permette di separare la gestione delle rotte dalla logica applicativa. Il flusso delle chiamate è a tre livelli:

// index.js utilizza i router definiti in routes
const myRouter = require('./src/routes/myRouter');
app.use('/example', myRouter);

// i router utilizzano la logica definita nei controllers
const myController = require('../controllers/myController');
router.route('/').get(myController.helloWorld);

// i controllers implementano la logica e usano i models per i dati
const myModel = require('../models/myModel');
exports.helloWorld = (req, res) => { res.send('Hello World!'); }
exports.getAll = (req, res) => { res.json(myModel.getAll()); }

12. Gli esercizi: la Filmoteca

Il filo rosso delle esercitazioni è un archivio di film, che ricompare in forme sempre più complete. La prima versione parte dalla specifica OpenAPI già scritta (exercises/exercise-02/spec.yaml) e chiede di implementare un server Express con cinque rotte:

Ogni film è un oggetto JSON con id, title, director, year e genres; i film sono memorizzati in un array in memoria come database fittizio — al riavvio del server le modifiche vanno perse, e sarà il capitolo 7 a rimediare con MongoDB. Vanno restituiti i corretti codici di stato HTTP e le API vanno testate con Postman o Swagger UI, generando la documentazione dall'OpenAPI.

Gli extra

• Ricerca e filtri su /films tramite query string: ?director=Nolan, ?year=2010, ?genre=Sci-Fi, combinabili tra loro (?director=Nolan&genre=Sci-Fi).
• Validazione avanzata (backend e OpenAPI): year compreso tra 1888 — considerato l'anno del primo film — e l'anno corrente; genres con almeno un elemento; divieto di creare un film con un id già esistente.
• Endpoint statistiche: GET /films/stats che restituisce totalFilms, byDirector e byGenre come oggetti di conteggi.
• Ordinamento: ?sort=year per anno crescente, ?sort=-year per decrescente, ?sort=title alfabetico.
• OpenAPI esteso: query parameter (director, year, genre, sort), regole di validazione (minimum, maximum, minItems, uniqueItems) e il nuovo endpoint /films/stats.

La seconda versione dell'esercizio (esercitazione 03) rifà lo stesso servizio applicando le buone prassi: niente database per la persistenza, gestione dei dati con un array, il file movies.json con i film già presenti, ma il codice separato in routes, controllers e models.

Verifica le tue conoscenze