Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

HTTP e API2. Verbi e codicip. 27

Verbi e codici

Cosa chiedi, e com'è andata

  • 12 minuti di lettura

Nel capitolo Il viaggio di una richiesta hai smontato una richiesta e una risposta. Due pezzi li abbiamo lasciati per dopo, e sono i più corti di tutto il messaggio:

  • la prima parola della richiesta, il verbo: dice cosa vuoi fare (leggere, creare, sostituire, ritoccare, togliere);
  • il numero nella prima riga della risposta, il codice di stato: dice com'è andata (bene, altrove, colpa tua, colpa del server).

Sono le cinque del mattino al deposito della Linea Menta. Ernesto Pozzi, il capo deposito, prova InfoMenta prima che apra la linea. Chiede il tram 4:

Terminale
curl -i http://127.0.0.1:8000/treni/4
HTTP/1.1 200 OK
date: Thu, 19 Nov 2026 15:59:46 GMT
server: uvicorn
content-length: 78
content-type: application/json

{"codice":"T05","tipo":"tram","vagoni":1,"stazione_id":2,"guasto":null,"id":4}

200 OK: tutto bene, ecco il treno. Il verbo nel comando non si vede perché curl, se non gli dici niente, fa una GET. In questo capitolo leggi tante richieste scritte con curl: per leggerle bastano quattro pezzi.

Nel comandoVuol dire
-iMostra anche la riga di stato e gli header della risposta, non solo il corpo
-X DELETEIl verbo. Senza -X, curl fa una GET
-H "Content-Type: application/json"Aggiunge un header alla richiesta
-d '{"vagoni": 5}'Il corpo della richiesta: i dati che mandi

Come si scrivono, e tutte le altre opzioni, è il capitolo dopo: Fare richieste.

Il disegno

Ernesto manda un annuncio all'altoparlante di Porta Codice. Ecco cosa passa sul filo. La richiesta:

HTTP
POST /annunci HTTP/1.1
Host: 127.0.0.1:8000
User-Agent: curl/8.7.1
Accept: */*
Content-Type: application/json
Content-Length: 43

{"testo": "Il primo treno parte alle 5:42"}

E la risposta:

HTTP
HTTP/1.1 201 Created
date: Thu, 19 Nov 2026 15:59:46 GMT
server: uvicorn
content-length: 49
content-type: application/json

{"testo":"Il primo treno parte alle 5:42","id":1}

Il verbo è la prima parola della richiesta. Il codice è il numero nella prima riga della risposta, seguito da una frase in inglese che lo ripete a parole.

Client (curl, l'app)                         InfoMenta (il server)
        │                                             │
        │  POST /annunci   e il corpo                 │
        │ ── il verbo: cosa voglio fare ────────────▶ │  crea l'annuncio,
        │                                             │  gli dà l'id 1
        │ ◀── il codice: com'è andata ─────────────── │
        │  201 Created   e l'annuncio con l'id        │

I cinque verbi

VerboCosa faSu InfoMentaCambia i dati?Il corpo della richiesta
GETLeggeGET /treni/4NoVuoto
POSTCrea una cosa nuovaPOST /treniSì: una cosa in piùLa cosa nuova, senza id
PUTSostituisce tutta la cosaPUT /treni/3SìTutti i campi, anche quelli che non cambiano
PATCHRitocca una partePATCH /treni/3SìSolo i campi che cambiano
DELETEToglieDELETE /treni/3Sì: una cosa in menoVuoto

Guarda la colonna «Su InfoMenta»: lo stesso percorso, /treni/3, compare con tre verbi diversi. Il percorso dice su cosa, il verbo dice cosa fare.

Tre cose da sapere sui verbi.

GET non cambia niente. Puoi chiedere lo stesso treno cento volte: InfoMenta resta com'era.

POST crea, e l'id lo sceglie il server. Si scrive POST /treni, non POST /treni/7: il treno nuovo un id non ce l'ha ancora. E se mandi la stessa POST due volte, crei due cose: due annunci uguali, con l'id 1 e l'id 2.

PUT sostituisce, PATCH ritocca. Al treno M16 tolgono un vagone: da 6 a 5. Con la PUT mandi il treno intero, anche quello che non cambia:

JSON
{"codice": "M16", "tipo": "metro", "vagoni": 5, "stazione_id": 5}

Con la PATCH mandi solo il campo che cambia:

JSON
{"vagoni": 5}

Se mandi {"vagoni": 5} con una PUT, InfoMenta non indovina il resto: risponde con un errore, perché mancano codice, tipo e stazione_id. Nelle API che scriverai nei prossimi capitoli userai la PUT; la PATCH è il bonus, per chi finisce prima.

Le quattro famiglie di codici

I codici sono numeri di tre cifre, e la prima cifra dice quasi tutto.

2xx   tutto bene         la richiesta è andata a buon fine
3xx   vai altrove        la cosa sta da un'altra parte: segui il nuovo indirizzo
4xx   hai sbagliato tu   il problema è nella richiesta: l'indirizzo, i dati, il badge
5xx   ho sbagliato io    il problema è nel server: tu non puoi farci niente

Davanti a un codice che non conosci, guarda la prima cifra: sai già di chi è la colpa.

I dodici codici da riconoscere

CodiceLa fraseVuol direSulla Linea Menta
200OKTutto bene, ecco la rispostaErnesto chiede il tram 4: eccolo
201CreatedCreato: la risposta a una POSTUn annuncio nuovo: creato, ed ecco il suo id
204No ContentFatto, niente da restituireUn treno tolto: fatto. Il corpo della risposta è vuoto
301Moved PermanentlySpostato per sempreUn indirizzo vecchio: la risposta dice qual è quello nuovo, nell'header location
400Bad RequestRichiesta scritta male, o senza sensoUn viaggio che parte e arriva nella stessa stazione
401UnauthorizedChi sei? Manca il loginIl registro del deposito senza badge, o con un badge che non esiste
403ForbiddenSo chi sei, ma non puoiIl registro con il badge vero di una capotreno: è solo per il capo deposito
404Not FoundNon esisteIl treno 99, oppure un percorso scritto male
422Unprocessable ContentDati non validi: tipico di FastAPIUn treno con 12 vagoni (al massimo 8), o la stazione abc
429Too Many RequestsTroppe richieste: rallentaTroppi annunci in un minuto: l'altoparlante riposa
500Internal Server ErrorIl server si è rottoUn'eccezione nel codice di InfoMenta che nessuno ha previsto, per esempio un ZeroDivisionError
503Service UnavailableServizio giù o sovraccaricoUn servizio in manutenzione: c'è, ma adesso non risponde. Riprova più tardi

Tre coppie si confondono più delle altre.

401 o 403? Il 401 chiede «chi sei?»: non hai mandato il badge, o il badge non lo conosce nessuno. Il 403 dice «so chi sei, ma non puoi»: il badge è vero, ma quella porta non è per te. Il login vero è un altro libro: Chi sei, cosa puoi fare.

400 o 422? Il 422 lo manda FastAPI da solo, prima di entrare nella funzione che risponde: manca un campo, un numero è scritto abc, un valore è fuori dai limiti. Il 400 lo decide la funzione: i dati sono del tipo giusto, ma la domanda non ha senso. Come leggere un 422 campo per campo è nel capitolo Pydantic.

500 o 503? Il 500 è un incidente: il codice del server si è rotto, e nessuno l'aveva previsto. Il 503 è un cartello: il servizio è giù, o troppo pieno, e lo sa. Spesso dice anche quando riprovare, nell'header retry-after.

Altri tre che vedrai

Non sono tra i dodici, ma nei prossimi capitoli li incontri di sicuro.

CodiceLa fraseVuol direDove lo vedi
405Method Not AllowedIl percorso c'è, il verbo noDELETE /stazioni/1: le stazioni di InfoMenta si leggono soltanto. La risposta ha l'header allow: GET, i verbi che ci sono
409ConflictIn conflitto con quello che c'è giàUn treno nuovo con il codice M12, che è già usato
501Not ImplementedNon ancora fattoLa riga «da fare» degli esercizi dei prossimi capitoli. Finché c'è, il test dice assert 501 == 200

Dove lo vedi, il codice

  • Con curl -i: è la prima riga della risposta, HTTP/1.1 200 OK.

  • Nel terminale del server: ogni richiesta lascia una riga, con il verbo, il percorso e il codice. Le due richieste di Ernesto, viste da InfoMenta:

    INFO:     127.0.0.1:59810 - "GET /treni/4 HTTP/1.1" 200 OK
    INFO:     127.0.0.1:59811 - "POST /annunci HTTP/1.1" 201 Created
  • In /docs: dopo Execute, sotto Server response, nella colonna Code.

  • Nei test: risposta.status_code. Quando un test è rosso con assert 404 == 200, il primo numero è il codice arrivato, il secondo quello che il test aspettava.

E adesso

Sai leggere una richiesta e riconoscere la risposta. Il prossimo passo è farle tu, le richieste: dal browser, con curl, con Postman e da Python. È il capitolo Fare richieste.

Ricorda

  • Il verbo dice cosa vuoi fare: GET legge, POST crea, PUT sostituisce, PATCH ritocca, DELETE toglie.
  • Stesso percorso, verbo diverso: azione diversa.
  • La prima cifra del codice dice quasi tutto: 2 bene, 3 altrove, 4 colpa tua, 5 colpa del server.
  • 401 «chi sei?», 403 «so chi sei, ma non puoi».
  • Il 422 lo manda FastAPI prima della funzione; il 400 lo decide la funzione.