Quando una richiesta fallisce e non sai perché
Quasi tutti i «l’API è rotta» sono una richiesta che non ha mai detto chi fosse. La risposta di solito lo dice, nella parte che nessuno legge.
API Post/Get copre ogni metodo HTTP, organizza le richieste in collection e cartelle, gestisce header e autorizzazione e mostra il corpo della risposta con evidenziazione della sintassi. Le scorciatoie da tastiera rendono rapido il ciclo di ripetizione una volta imparate.
Leggi tutta la risposta, non lo stato
L’abitudine che fa risparmiare più tempo è aprire il corpo della risposta in caso di errore invece di reagire allo stato rosso. Le API scritte da persone ci mettono dentro il motivo, ed è di solito una frase che chiude l’indagine.
Poi controlla gli header da entrambe le parti. Una richiesta inviata senza Content-Type: application/json è la singola causa più comune di un 400 apparentemente inspiegabile: il server ha ricevuto il tuo JSON come testo semplice e non ha potuto interpretarlo.
I quattro che significano qualcosa di preciso
- 401 — non ti sei autenticato. Token mancante, malformato o nell’header sbagliato.
- 403 — ti sei autenticato e non hai il permesso. Problema diverso, soluzione diversa; smetti di rimandare il token.
- 404 — su un endpoint che sai esistere, di solito significa che una variabile di percorso si è risolta a vuoto. Controlla se
{{user_id}}ha davvero un valore nell’ambiente selezionato. - 422 — la richiesta è stata capita e i dati rifiutati. Il corpo quasi sempre nomina il campo.
Il 500 è l’unico che è davvero un problema dell’altra parte, e anche allora conviene rimandare la stessa richiesta senza i campi opzionali prima di segnalarlo.
L’autorizzazione, dove se ne va la maggior parte del tempo
Imposta l’autorizzazione a livello di cartella invece che per singola richiesta. Ripetere un bearer su diciannove richieste significa aggiornarne diciannove a ogni rotazione, e quella che ti sfugge è quella su cui farai debug per venti minuti.
E tieni il token in una variabile d’ambiente invece di scriverlo nell’header. Così cambiare ambiente cambia anche identità, che è ciò che volevi cambiando.
Domande frequenti
Ricevo un 400 e la richiesta sembra corretta. E adesso?
Verifica di inviare Content-Type: application/json. Un corpo JSON ricevuto come testo semplice produce esattamente questo: una richiesta che sembra giusta e un server che non riesce a interpretarla.
Qual è la differenza tra 401 e 403?
401 significa che non ti sei autenticato: token mancante o malformato. 403 significa che lo hai fatto e non hai il permesso. Rimandare il token risolve il primo e non fa nulla per il secondo.
Dove deve stare il token di autorizzazione?
In una variabile d’ambiente, applicata a livello di cartella. Scriverlo in ogni richiesta significa aggiornarle tutte a ogni rotazione, e quella che sfugge diventa venti minuti di debug.
