Il momento "non capisco un'API"
Stai costruendo un'app con Claude. Ti dice di "chiamare l'endpoint POST /api/users con il body in JSON". Tu copi, incolli, qualcosa risponde, qualcos'altro no. Quando si rompe, non sai dove guardare. Stai usando le API ma non sai cosa sono.
La metafora del ristorante
Un'API REST è esattamente come un ristorante:
- Tu (il browser/client) = il cliente seduto al tavolo
- Il cameriere = la richiesta HTTP che porta il tuo ordine in cucina
- La cucina = il server
- Il menù = la documentazione delle API (lista degli endpoint)
- L'ordine scritto = il body della richiesta (JSON)
- Il piatto che ti arriva = la response
- "Non abbiamo più la cotoletta" = errore 404
- "Siamo chiusi, è festa" = errore 503
Una volta che vedi questa mappa, non la dimentichi più.
I 4 verbi HTTP che usi al 95%
GET — "fammi vedere"
Chiedi al cameriere di portarti qualcosa che esiste già. Non cambia niente in cucina. GET /api/users/42 → "fammi vedere il profilo dell'utente 42".
POST — "preparami una cosa nuova"
Chiedi alla cucina di creare qualcosa che prima non c'era. Mandi il body con i dati. POST /api/users con { "email": "x@y.com" } → "crea un nuovo utente con questa email".
PUT / PATCH — "modifica una cosa che c'è già"
PUT sostituisce tutto, PATCH modifica solo i campi che mandi. PATCH /api/users/42 con { "phone": "..." } → "aggiorna solo il telefono dell'utente 42".
DELETE — "fai sparire questa cosa"
DELETE /api/users/42 → "cancella l'utente 42". Spesso è un soft-delete (in realtà mette deleted_at = NOW()).
Gli status code che devi conoscere
- 200 OK — tutto bene
- 201 Created — risorsa creata (risposta tipica al POST)
- 400 Bad Request — hai mandato spazzatura nel body
- 401 Unauthorized — non sei loggato
- 403 Forbidden — sei loggato ma non hai i permessi
- 404 Not Found — l'endpoint o la risorsa non esiste
- 422 Unprocessable — validation fallita (email malformata, ecc.)
- 500 Internal Server Error — bug nel codice del server
- 502/503/504 — il server non risponde o è in crash
Quando una chiamata API non funziona, il primo passo è sempre: guarda lo status code nel network tab. Tutto inizia da lì.
📘 Vuoi il decoder completo degli status code?
Nel libro Vibecoding Serio ogni status code ha la sua scheda: cosa significa, dove guardare, e il prompt-ready da mandare a Claude per fixarlo. Più infografica completa "Anatomia di una chiamata HTTP".
Compra il libro — €14,90→Come parlarne a Claude
Mi aspetto che validi email + password (min 8 char) prima di salvarla. Mostra come strutturare la validation con Zod e cosa ritornare al client per mostrare l'errore inline sotto il campo sbagliato.
La regola da portare a casa
Un'API REST è una conversazione strutturata. Verbi (GET/POST/PUT/DELETE), risorse (URL), risposta (status code + body). Quando capisci queste tre cose, capisci tutte le API del mondo.