API PUT: aggiornare
Prima di iniziare: le parole della lezione
- PUT e PATCH
- PUT esprime la sostituzione della rappresentazione della risorsa all’URL indicato. PATCH esprime una modifica parziale descritta dal body.
- Campi modificabili e identità
- I campi modificabili costituiscono i dati che l’API permette al client di cambiare. L’identità della risorsa resta quella selezionata dall’URL.
- Indice dell’array
- Posizione numerica di un elemento, a partire da zero: non è l’ID dell’elemento e può cambiare dopo una cancellazione.
PUT serve convenzionalmente a sostituire la rappresentazione della risorsa; il corso lo usa per aggiornare un elemento di un array. Per modifiche parziali si usa spesso PATCH.
app.put('/api/persone/:id', (req, res) => {
const id = Number(req.params.id);
const persona = persone.find(p => p.id === id);
if (!persona) return res.status(404).json({ errore: 'Non trovata' });
const nome = req.body?.nome;
if (typeof nome !== 'string' || !nome.trim())
return res.status(400).json({ errore: 'Nome non valido' });
persona.nome = nome.trim();
res.json(persona);
});
Esempio aggiuntivo: con PUT /api/persone/2 e body {"nome":"Marco"}, l'oggetto con ID 2 viene aggiornato senza cambiare ID.
Chi fa cosa, e perché
La trascrizione parte da un aggiornamento diretto nell’array. Per renderlo affidabile, prima cerca la persona per ID, poi valida tutto ciò che vuoi modificare. Non usare l’ID direttamente come indice: la persona 5 potrebbe trovarsi in posizione 2 oppure non esserci.
Nel modello ridotto con il solo campo nome, l’esempio PUT sopra sostituisce tutti i dati modificabili. Nel laboratorio i campi sono nome e ruolo: una PUT richiede entrambi. Se vuoi cambiare solo ruolo conservando nome, usa un contratto PATCH. Anche una PATCH può essere idempotente quando assegna valori, ma non lo è necessariamente quando esprime operazioni come “incrementa”.
Un altro esempio guidato
// Frammento: aggiunta all'API persone con campo ruolo
app.patch('/api/persone/:id', (req, res) => {
const id = Number(req.params.id);
if (!Number.isSafeInteger(id) || id <= 0)
return res.status(400).json({ errore: 'ID non valido' });
const persona = persone.find(p => p.id === id);
if (!persona) return res.status(404).json({ errore: 'Non trovata' });
const ruolo = req.body?.ruolo;
if (typeof ruolo !== 'string' || !ruolo.trim() || ruolo.trim().length > 80)
return res.status(400).json({ errore: 'Ruolo non valido' });
persona.ruolo = ruolo.trim();
res.json(persona);
});
Come leggerlo e risultato atteso. Inviando {"ruolo":"editor"} modifichi il ruolo senza toccare nome e ID. Questa PATCH accetta il solo campo ruolo come modifica; un body senza ruolo non è valido. È una scelta del contratto, non un formato universale per tutte le PATCH.
Prova tu. Invia la stessa PUT due volte: lo stato finale deve restare uguale. Confronta poi una PUT senza ruolo nel laboratorio con la PATCH qui sopra.