PUT sostituisce lo stato dell’URL che hai già. POST chiede alla risorsa di elaborare il corpo, e spesso di inventare lei l’indirizzo. La seconda PUT identica non è un secondo ordine.
PUT non è POST. Rifare la stessa PUT non è un secondo ordine. Rifare lo stesso POST, se il server lo tratta come creazione, può esserlo. La fonte è l’RFC 9110, HTTP Semantics, giugno 2022, standard. Rilettura del testo il 18 ottobre 2026. Non è SemVer: lì si parla di numeri di versione, qui di metodi HTTP.
In breve: un metodo è idempotente se l’effetto voluto di più richieste identiche è lo stesso di una sola. Nell’elenco dell’RFC ci sono PUT, DELETE e i metodi safe. POST non c’è. PUT che crea una risorsa che non c’era deve rispondere 201. PUT che modifica una risorsa che c’era deve rispondere 200 o 204. POST, se crea, dovrebbe rispondere 201 con un Location. Sono due 201 diversi.
Cosa trovi in questo articolo
Idempotente non vuol dire «senza log»
Sezione 9.2.2. L’effetto considerato è quello chiesto dall’utente. Il server può lo stesso scrivere un log per ogni richiesta, tenere la storia delle revisioni o avere altri effetti collaterali non idempotenti. L’etichetta non vieta il log. Vieta di trattare la seconda PUT identica come se chiedesse un altro stato, diverso dalla prima.
I metodi safe, sezione 9.2.1, sono quelli la cui semantica è in sostanza di sola lettura: il client non chiede e non si aspetta un cambio di stato. Anche un metodo safe può finire in un log. Il punto è che il client non ha chiesto quel di più. PUT non è safe: chiede di creare o sostituire lo stato. È idempotente, non è una lettura.
| Metodo, come lo classifica l’RFC 9110 | Safe | Idempotente |
|---|---|---|
| GET, HEAD, OPTIONS, TRACE (i safe definiti qui) | Sì, per la definizione di sola lettura | Sì, perché i safe sono nell’elenco idempotente |
| PUT | No | Sì |
| DELETE | No | Sì |
| POST | No | Non è nell’elenco |
PATCH non sta in questa specifica. Non lo tratto come se l’RFC 9110 lo avesse definito. Il cluster è Programmazione.
Cosa chiede PUT
Sezione 9.3.4. PUT chiede che lo stato della risorsa target sia creato o sostituito con lo stato definito dalla rappresentazione nel contenuto della richiesta. Una PUT riuscita di una data rappresentazione suggerisce che un GET successivo sulla stessa risorsa rimandi una rappresentazione equivalente in un 200. Non c’è garanzia: altri client possono agire in parallelo, e il server può rielaborare la risorsa prima del GET. Una risposta di successo dice solo che l’intento del client è stato realizzato nel momento in cui l’origin server l’ha elaborato.
Se la risorsa non aveva una rappresentazione e la PUT la crea, il server MUST rispondere 201 Created. Se la rappresentazione c’era ed è stata modificata in accordo con quella inviata, il server MUST rispondere 200 OK oppure 204 No Content. Il 201 della PUT non è «ho inventato un nuovo URL». È «prima qui non c’era una rappresentazione, ora c’è».
Cosa chiede POST
Sezione 9.3.3. POST chiede che la risorsa target elabori la rappresentazione secondo la semantica propria di quella risorsa. Gli esempi del testo: inviare i campi di un form; pubblicare un messaggio su una bacheca, una lista o un blog; creare una risorsa che l’origin server non ha ancora identificato; accodare dati a una rappresentazione già esistente.
Quasi tutti i codici di stato di questa specifica possono arrivare in risposta a POST. Le eccezioni scritte sono 206 Partial Content, 304 Not Modified e 416 Range Not Satisfiable. Se l’elaborazione ha creato una o più risorse, il server SHOULD rispondere 201 con un header Location che identifica la risorsa primaria creata, più una rappresentazione che descrive lo stato della richiesta. Quel Location è il punto: il client non aveva già l’identificatore. Due POST identici, se ognuno crea, non sono due copie della stessa PUT.
Quando il client può riprovare da solo
I metodi idempotenti si distinguono perché la richiesta si può ripetere in automatico se la connessione cade prima che il client legga la risposta. Esempio del testo: il client manda una PUT, la connessione si chiude prima di ogni risposta, il client ne apre un’altra e ripete. L’effetto voluto resta quello, anche se la prima PUT era in realtà riuscita. La risposta può essere diversa.
Un client SHOULD NOT riprovare in automatico un metodo non idempotente, a meno che non abbia un modo per sapere che quella richiesta, su quella risorsa, è di fatto idempotente, oppure un modo per sapere che la richiesta originale non è mai stata applicata. Il testo fa l’esempio di un POST che l’user agent sa essere sicuro per quella risorsa, per progetto o per configurazione. Non è il permesso generale di ritentare ogni POST.
Errori da evitare
Usare POST per «sostituisci questa risorsa» e poi ritentare al timeout. L’RFC non lo mette tra gli idempotenti.
Aspettarsi 201 da ogni PUT. Il 201 è obbligatorio solo se la rappresentazione prima non c’era. Se c’era, 200 o 204.
Trattare il 201 di POST come il 201 di PUT. Al POST creato manca, nel SHOULD, il Location verso un identificatore che il client non aveva.
Credere che idempotente vieti il log. La sezione 9.2.2 dice il contrario.
Chiamare PUT un metodo safe. Chiede un cambio di stato.
Dedurre da questo testo le regole di PATCH. Non sono qui.
In sintesi
PUT sostituisce o crea lo stato della risorsa che hai già nominato nell’URL. POST chiede alla risorsa di elaborare il corpo a modo suo, e spesso di inventare lei l’indirizzo del risultato. La seconda PUT identica ha lo stesso effetto voluto della prima. Il secondo POST no, salvo che tu sappia, per quella risorsa, che è un caso diverso. Giugno 2022, RFC 9110, riletto il 18 ottobre 2026.
Foto di copertina: Markus Spiske, «Code on computer monitor», Wikimedia Commons, CC0. È un monitor, non una cattura di una PUT.
