HTTP 201 Created
Risposta di successo per la creazione: ora esiste una nuova risorsa, e Location indica dove.
Cosa significa HTTP 201
HTTP 201 Created viene restituito quando una richiesta — quasi sempre una POST o una PUT — ha creato con successo una nuova risorsa sul server. Le API REST lo usano per distinguere “ora esiste qualcosa di nuovo” dal generico successo 200.
Una risposta 201 corretta include un header Location con l'URL della risorsa appena creata, e spesso restituisce l'oggetto creato nel corpo, così il client non ha bisogno di una GET successiva.
Cause comuni delle risposte 201
- Una richiesta POST ha creato un record, un file o un account.
- Una richiesta PUT ha creato una risorsa esattamente all'URL fornito dal client.
- Un endpoint batch ha finito di creare una risorsa primaria in modo sincrono.
Buone pratiche per gli sviluppatori
- Imposta l'header Location sull'URL canonico della nuova risorsa.
- Restituisci la rappresentazione creata (con il suo id assegnato dal server) nel corpo, per far risparmiare ai client un round trip.
- Se la creazione è in coda anziché completata, restituisci 202 Accepted invece.
- POST identiche ripetute che creano duplicati? Valuta le chiavi di idempotenza e rispondi 200/409 per i replay.
Esempio di risposta
HTTP/1.1 201 Created
Location: /api/users/1024
Content-Type: application/json
{"id":1024,"name":"New user"}FAQ
Qual è la differenza tra 200 e 201?
Entrambi indicano successo, ma 201 dice specificamente al client che è stata creata una nuova risorsa. 200 significa solo che la richiesta è stata elaborata.
L'header Location è obbligatorio con 201?
È fortemente consigliato: indica l'URL della risorsa appena creata così i client possono recuperarla o collegarla.
Quando un'API dovrebbe restituire 202 invece di 201?
Quando la creazione avviene in modo asincrono — 202 significa che la richiesta è stata accettata ma la risorsa non esiste ancora.