Cos'è il codice di stato HTTP 201? Significato, esempi e quando usarlo

Non tutti i codici di stato HTTP sono uguali. Alcuni semplicemente confermano che una richiesta al server è stata completata con successo, mentre altri hanno un significato speciale. Il codice di stato 201 ti dice che il server ha creato con successo una nuova risorsa. Di solito, questo avviene in risposta a una richiesta POST, o a volte a una richiesta PUT, più comunemente usata con i servizi API.

In questo articolo, spiegheremo in dettaglio cosa significa il codice di risposta 201 Created, esamineremo esempi da REST API e moduli del browser, e lo confronteremo con altri simili codici di stato HTTP.

Cos’è il codice di stato HTTP 201?

Il codice di stato 201 significa che una richiesta è stata completata con successo e ha creato una nuova risorsa.

Secondo la specifica HTTP/1.1, un corretto codice di risposta 201 del server dovrebbe includere un campo Location header.

Questo dovrebbe puntare all’URL specifico della risorsa appena creata o principale. Può anche includere un corpo di risposta contenente dettagli sui dati richiesti.

Questo comportamento rende il 201 diverso da altri codici di risposta del server. Ad esempio:

• 200 OK significa semplicemente che la richiesta è stata completata con successo e restituisce i dati richiesti, ma non crea necessariamente una nuova entità.
• 201 Created segnala esplicitamente che una nuova risorsa ora esiste all’URI della richiesta effettiva o a un altro indirizzo di inoltro fornito nel Location header.

In pratica, il 201 è più spesso usato nelle REST API dove una richiesta POST aggiunge un nuovo utente, post del blog, file caricato o qualsiasi altra risorsa target. Può anche applicarsi nei moduli web, come una pagina di registrazione, dove un server soddisfa con successo la richiesta e una nuova entità viene salvata nel database.

Quando usare il 201 (e quando non usarlo)

Il codice di stato 201 si applica quando il server ha soddisfatto con successo una richiesta del client che risulta in qualcosa di nuovo. Di seguito, elencheremo i casi d’uso più comuni.

Casi d’uso corretto

• Registrazione utente – Creare un nuovo account utente restituisce un 201 Created insieme a un Location header che punta alla pagina del profilo.
• Creazione di un post del blog – Pubblicare un post del blog con una richiesta POST dovrebbe restituire 201 una volta che l’articolo è salvato.
• Caricamento di file – Quando un file caricato è memorizzato sul server di origine, il codice di risposta dovrebbe essere 201 Created con un link alla risorsa target.
• Ordine ecommerce – Un processo di checkout dove il server prepara una nuova voce d’ordine può restituire 201 più un corpo di risposta con l’ID dell’ordine.

Casi d’Uso Errato

Il codice 201 Created non dovrebbe essere usato se non è stata generata alcuna nuova risorsa. Errori comuni includono:

• Login o autenticazione – Una richiesta è stata completata con successo, ma non ha aggiunto una nuova entità. Il codice di stato corretto è solitamente 200 OK.
• Aggiornamento di dati esistenti – Una richiesta PUT che modifica un’istanza corrente dovrebbe restituire 200 OK o 204 No Content.
• Query di ricerca – Restituire i dati richiesti non comporta la creazione di risorse; 200 OK è corretto.
• Tentativi di creazione duplicati – Se il server di origine rifiuta di creare perché l’identità del client esiste già, restituisci 409 Conflict.

Usare il codice di risposta sbagliato può causare confusione per l’agente utente e portare a errori semantici o risposte non valide in una REST API.

Esempio API: Creazione di un nuovo utente

Il codice di stato 201 è più spesso visto nelle API quando una risorsa appena creata viene restituita dopo una richiesta del client. Vediamo un caso comune – creare un nuovo utente in una REST API.

Ad esempio, di seguito è riportato un esempio di richiesta POST fatta a api.example.com:

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"name": "John Doe",
"email": "john@example.com"
}

In questa richiesta POST, l’agente utente chiede al server di origine di aggiungere una nuova entità. Di seguito, puoi vedere una comune risposta del server:

HTTP/1.1 201 Created
Location: /users/123
Content-Type: application/json
{
"id": 123,
"name": "John Doe",
"email": "john@example.com"
}

Il codice di risposta del server 201 Created segnala che la richiesta è stata completata con successo e una nuova risorsa è stata aggiunta – un nuovo utente, John Doe, la sua email e un rispettivo ID utente sono stati creati con successo.

Punti chiave in questo esempio:

• Il campo Location header fornisce l’URI specifico dove la risorsa principale creata può essere accessibile.
• Il corpo della risposta restituisce i dati richiesti per il nuovo utente, confermando la creazione della risorsa.
• La richiesta è stata completata con successo in un solo passaggio — non è stato richiesto alcun metodo di richiesta extra o indirizzo di inoltro.

Questo è il modo più corretto e conforme agli standard per usare il codice di risposta HTTP 201 Created secondo la specifica HTTP.

Esempio browser: Demo modulo di registrazione (scenario pratico)

Mentre il codice di stato 201 è più comune nelle API, puoi vederlo in azione con un semplice modulo web.

Vediamo una pagina demo di registrazione dove un visitatore può creare un nuovo account utente.

Quando il modulo viene inviato, il server di origine elabora la richiesta del client, memorizza i dati e restituisce la risposta 201 Created.

Nella nostra demo:

1. Il visitatore compila il suo nome, email e password.
2. Il server convalida i campi dell’header della richiesta e salva i dati come una risorsa appena creata nel database.
3. Il codice di risposta del server è 201 Created, insieme a un Location header che punta al nuovo profilo.
4. Una pagina di conferma mostra i dettagli della risorsa richiesta, dimostrando che la richiesta è stata soddisfatta con successo.

Ricorda che è improbabile vedere codici di risposta 201 sul front-end dei siti web.

Questa demo è pensata per illustrare il processo che di solito avviene “dietro le quinte” quando il server elabora le richieste.

Puoi anche usare gli strumenti Developer e Network del browser per vedere come il codice di stato viene usato in pratica su applicazioni reali.

201 vs. Altri codici di stato simili

Il codice di risposta HTTP 201 Created viene spesso confuso con altri codici di successo. Ecco come si confronta con risposte correlate:

201 vs 200 OK

• 200 OK significa che la richiesta è stata completata con successo e i dati richiesti sono restituiti.
• Non indica che esiste una risorsa appena creata.
• Ad esempio: recuperare un post del blog o aggiornare un’istanza corrente.

201 vs 202 Accepted

• 202 Accepted significa che la richiesta del client è stata ricevuta e potrebbe essere elaborata in seguito.
• Non c’è garanzia che una nuova entità venga creata.
• Ad esempio: inviare un lavoro a una coda per l’elaborazione del rischio, come generare un PDF o gestire un sistema di pagamento digitale.

201 vs 204 No Content

• 204 No Content significa che la richiesta è stata completata con successo e non c’è un corpo del messaggio da restituire.
• Spesso usato per una richiesta PUT che aggiorna una risorsa esistente.
• Nessun Location header o nuova risorsa è coinvolta.

Punti chiave sul codice di stato 201

Riassumiamo i punti principali sul codice 201:

• Il codice di stato HTTP 201 conferma che il server ha soddisfatto con successo una richiesta del client creando una nuova risorsa.
• Un corretto codice di risposta 201 del server dovrebbe includere un campo Location header che punta all’URI specifico della risorsa appena creata e può anche restituire un corpo di risposta con dettagli sui dati richiesti.
• Il codice di risposta 201 Created è più comune nelle REST API per la creazione di risorse (nuovo utente, post del blog, file caricato o ordine).
• Non confondere 201 con altri codici di stato HTTP come 200 OK, 202 Accepted o 204 No Content — ognuno comunica un risultato diverso del metodo di richiesta.
• Usare il codice di stato HTTP corretto significa che l’agente utente può gestire correttamente la risorsa richiesta.

In breve: 201 dice al client, ‘La richiesta ha funzionato, e ora esiste una nuova risorsa’.