Video 01 - Web Service JSON
API REST in 5 minuti: Node.js, json-server, db.json e test CRUD completo con GET, POST, PUT, PATCH, DELETE da browser e curl.
1. Perche utilizzare json-server nella didattica e nel prototyping
Nello sviluppo di applicazioni moderne, il frontend deve dialogare con un backend tramite Web Services REST. Configurare un backend reale con Express, routing, autenticazione e un database come MySQL o MongoDB richiede ore e distoglie l'attenzione dall'obiettivo didattico principale: imparare a consumare le API.
json-server e un pacchetto npm che risolve questo problema alla radice. Trasforma un singolo file JSON in un server REST completo, con persistenza automatica su disco. E' lo strumento ideale quando devi prototipare un'app, insegnare i metodi HTTP o testare un'interfaccia senza dipendenze esterne.
Database istantaneo: il file db.json e il tuo database. Ogni POST, PUT o DELETE aggiorna il file in tempo reale.
CRUD automatico: non devi scrivere rotte. Ottieni subito /users, /users/:id e cosi via.
Funzioni reali integrate: CORS, filtri, paginazione _page & _limit, ricerca full-text q= e ordinamento sono gia disponibili.
2. Prerequisiti: installazione di Node.js
json-server e eseguito dal runtime Node.js. L'errore piu comune tra gli studenti e il messaggio npm: command not found o npx: command not found, che indica semplicemente che Node non e installato o non e nel PATH di sistema.
La soluzione e scaricare la versione LTS (Long Term Support) dal sito ufficiale nodejs.org. Dopo l'installazione, apri un terminale e verifica l'installazione con due comandi. Se entrambi restituiscono un numero di versione, sei pronto a procedere.
Non e necessario installare json-server globalmente. Useremo npx, lo strumento incluso in npm che esegue un pacchetto senza installazione permanente, evitando conflitti di versione.
3. Creazione della struttura dati: il file db.json
Crea una cartella di lavoro, ad esempio web-service, e al suo interno un file chiamato db.json. Questo file rappresenta le tue collezioni. Ogni chiave di primo livello diventa un endpoint REST.
Il punto critico, spesso sottovalutato, e il campo id. json-server lo usa come chiave primaria per identificare la risorsa da modificare o cancellare. Se crei oggetti senza id, le richieste successive di aggiornamento falliranno o genereranno duplicati incoerenti.
JSON e molto rigido: richiede doppi apici "nome" e vieta virgole finali. Un errore come {"users": [...] ,} o {'nome':'Mario'} genera Unexpected token e blocca il server. Prima di avviare, valida sempre il file su jsonlint.com.
4. Avvio dell'API REST
Posizionati con il terminale nella cartella che contiene db.json ed esegui un unico comando. Il flag --watch e fondamentale: dice al server di osservare il file e riscriverlo ad ogni modifica fatta via API, garantendo la persistenza.
A questo punto il server e attivo su http://localhost:3000. Se la porta 3000 e gia occupata da un altro servizio, puoi cambiarla con --port 4000. Apri il browser su /users per vedere immediatamente la lista in formato JSON.
5. Testare i metodi HTTP: mappatura CRUD
Non ti serve un frontend per testare l'API. Puoi usare curl (gia presente su macOS e Linux, disponibile su Windows 10+), Postman o l'estensione Thunder Client di VS Code. L'obiettivo e capire la corrispondenza tra verbo HTTP e operazione sul database.
La lettura dei dati e immediata: una richiesta GET all'endpoint della collezione restituisce l'array completo, mentre aggiungendo l'id ottieni il singolo record. Per le operazioni di scrittura, c'e un dettaglio che blocca il 90% dei principianti: l'header Content-Type: application/json. Senza di esso, json-server riceve un body vuoto e crea un oggetto con solo l'id.
| Obiettivo | Metodo | Endpoint | Note fondamentali |
|---|---|---|---|
| Leggere tutta la collezione | GET | /users | Restituisce array JSON |
| Leggere singolo utente | GET | /users/1 | Filtra per id |
| Creare nuovo record | POST | /users | Richiede header Content-Type e body JSON |
| Aggiornare parziale | PATCH | /users/1 | Modifica solo i campi inviati |
| Sostituire totale | PUT | /users/1 | Sovrascrive l'intero oggetto |
| Rimuovere | DELETE | /users/1 | Cancellazione definitiva |
Esempio pratico per creare un utente: invii un JSON con nome, email ed eta. json-server generera automaticamente un nuovo id incrementale e aggiornera db.json sotto i tuoi occhi.
6. L'errore piu costoso: confondere PUT e PATCH
Questa e la sezione a piu alto valore didattico e la causa principale di perdita di dati nei laboratori. I due verbi sembrano simili ma hanno semantica opposta.
PUT e una sostituzione totale. Quando invii PUT /users/1 con body {"email":"nuova@test.it"}, stai dicendo al server: "d'ora in poi l'utente 1 e fatto SOLO da questa email". Il server cancellera nome ed eta. E' utile solo quando invii l'oggetto completo e aggiornato.
PATCH e un aggiornamento parziale. Con PATCH /users/1 e lo stesso body, il server modifica solo la chiave email, lasciando intatti nome, eta e altri campi. Per il 95% degli aggiornamenti in un'interfaccia utente, devi usare PATCH.
Scenario tipico: form di modifica email con un solo input. Lo studente usa PUT pensando di aggiornare. Risultato: l'utente nel db.json si ritrova con solo l'email, nome ed eta spariti. Soluzione professionale: usa sempre PATCH per i form parziali e riserva PUT solo quando hai tutti i campi a disposizione.
7. Funzionalita avanzate integrate senza codice
Uno dei motivi per cui json-server e superiore a un mock statico e che simula un database reale direttamente tramite query string. Non devi scrivere una riga di codice per ottenere queste funzioni, essenziali per un frontend moderno:
- Filtri:
/users?nome=Mariorestituisce solo gli utenti con quel nome. Utile per barre di ricerca. - Paginazione:
/users?_page=1&_limit=5simula la paginazione di tabelle lunghe, fondamentale per non caricare migliaia di record. - Ricerca full-text:
/users?q=testcerca la stringa in tutti i campi. Perfetto per prototipare una ricerca globale. - Relazioni:
/posts?userId=1o/posts?_expand=userper simulare join tra collezioni.
Queste feature ti permettono di sviluppare un frontend completo con filtri, ricerca e pagine, prima ancora di avere un backend di produzione.
8. Esercizio pratico consigliato
Per consolidare quanto appreso, prova a creare un flusso completo in autonomia. Crea una collezione users e una posts, avvia il server e verifica dal browser che entrambi gli endpoint rispondano. Poi usa un client HTTP per eseguire in sequenza: lettura lista, lettura singolo id, creazione di un terzo utente, aggiornamento parziale della sua email con PATCH e infine cancellazione del secondo utente. Al termine, apri db.json e osserva come si e evoluto.
Questo esercizio ti insegna non solo la sintassi, ma il ciclo di vita di un dato in un'API REST, competenza richiesta in qualsiasi colloquio per sviluppatori frontend.
📚 Approfondimento professionale
json-server e uno strumento di sviluppo, non per la produzione. In produzione userai framework come Express.js, FastAPI o Spring Boot con un database reale. Tuttavia, la logica REST che impari qui (verbi HTTP, status code, idempotenza di PUT vs PATCH, gestione Content-Type) e identica e direttamente trasferibile. Una volta padrone di questi concetti, passare a un backend reale sara solo questione di sintassi.