Cosa sono le risposte HTTP
Le risposte HTTP sono messaggi inviati dal server in risposta a una richiesta inviata dal client. Hanno una struttura specifica e sono caratterizzate dal codice di risposta (o status code) che permette di capire se la richiesta è andata a buon fine oppure no.
Struttura risposta HTTP
Una risposta HTTP è caratterizzata da:
- lo status code della risposta
- lo status text della risposta, un breve testo, puramente informativo, che offre una descrizione testuale e human-readable dello status code
- zero o più header che caratterizzano la risposta
- un body (opzionale) che contiene i dati associati alla risorsa richiesta
Un esempio di risposta HTTP è il seguente:
HTTP/2 201 Created
Access-Control-Allow-Origin: *
Date: Mon, 16 Jan 2023 19:40:32 GMT
Content-Type: application/json
Content-Length: 131
Cache-Control: private, no-cache, no-store, must-revalidate
Strict-Transport-Security: max-age=15724800; includeSubDomains
{
"id": "fef10dff-d5ad-4d60-b28a-b3fb6c12edf7",
"foo": "bar"
}
In questa risposta, nella prima riga è indicato lo status code o lo status text, le successive contengono gli header che caratterizzano il contenuto della risposta. Dopo una riga vuota di separazione, è presente la risorsa richiesta (in questo caso un file JSON).
Status code HTTP
I codici delle risposte HTTP permettono al client di capire se una specifica richiesta HTTP è andata a buon fine e in che modo. Se consideriamo, infatti, che un client HTTP è, in fondo, un’applicazione generica (non solo un browser web, ma anche un’app per smartphone che chiama un server API), sapere quali codici di risposta possono essere potenzialmente ricevuti ci permette di istruire la nostra applicazione per comportarsi in modi specifici a seconda del codice di risposta ricevuto.
Gli status code HTTP sono numeri a tre cifre, la cui prima cifra permette di capire a quale classe appartiene lo status code. In particolare:
- 1xx (informativo) – la richiesta è stata ricevuta, elaborazione in corso
- 2xx (successo) – la richiesta è stata ricevuta, compresa e accettata con successo
- 3xx (redirezione) – ulteriori azioni devono essere intraprese per completare la richiesta
- 4xx (errore del client) – la richiesta contiene una sintassi errata o non può essere soddisfatta
- 5xx (errore del server) – il server non è riuscito a soddisfare una richiesta apparentemente valida
Ogni numero tra 100 e 599 è, quindi, uno status code valido; alcuni specifici valori sono stati codificati nella specifica HTTP per avere un particolare significato, che riporteremo tra poco.
I server, d’altra parte, possono implementare codici di risposta propri, purché validi e purché in linea con la classe di appartenenza. Per esempio, un server potrebbe rispondere con:
HTTP/2 481 TheCatIsOnTheTable Access-Control-Allow-Origin: * Date: Mon, 16 Jan 2023 19:40:32 GMT
Lo status code 481 non è definito nella specifica HTTP, ma è appartiene alla classe “errore del client”. Il client può quindi:
- non sapere di questo specifico errore, ma trattandosi di un codice 4xx dovrebbe poterlo gestire come un errore generico lato client
- conoscere il significato di questo errore specifico e implementare di conseguenza un comportamento ben definito rispetto agli altri 4xx
Ovviamente, il server dovrebbe documentare quali status code gestisce e quale significato dare a ognuno (anche se una spiegazione minima è nello status text).
I codici di risposta definiti dalla specifica HTTP più frequenti e importanti sono i seguenti:
200 OK
Il codice di risposta 200 OK indica un successo generico della richiesta. L’esatto significato di “successo” dipende dal metodo HTTP della richiesta, così come header e body presenti nella risposta. Per esempio, il body di una 200 OK a seguito di una GET sarà la stessa risorsa richiesta, quello di 200 OK a seguito di una POST potrebbe contenere informazioni di stato o il risultato ottenuto dall’azione corrispondente alla richiesta.
NOTA: il protocollo HTTP è un protocollo di comunicazione, dice come scambiare informazioni, non quali. Nel tempo, si sono formalizzate alcune buone pratiche nell’uso di metodi di richiesta, codici di risposta, contenuto dei body e formato delle URI delle risorse, ma ciò va oltre la specifica HTTP stessa. Per maggiori informazioni cfr https://en.wikipedia.org/wiki/Representational_state_transfer
201 Created
La richiesta è andato a buon fine ed è stata creata una nuova risorsa (il cui contenuto o URI è di solito presente nel body). È la risposta tipica a seguito di una POST o PUT andata a buon fine.
202 Accepted
Il codice di risposta 202 Accepted indica che la richiesta è stata accettata, ma è ancora da elaborare. Notare che, essendo HTTP un protocollo stateless, il server non invierà in modo asincrono una ulteriore risposta per indicare l’effettiva riuscita. Può essere utile, per esempio, su risorse da contattare per far partire un processo batch.
204 No Content
Il codice di risposta 204 No Content indica che non ci sono contenuti da inviare in risposta per la richiesta, ma gli header potrebbero essere utili. Per esempio, il client può aggiornare gli header memorizzati nella cache per questa risorsa con quelle nuove.
301 Moved Permanently
Il codice di risposta 301 Moved Permanently, indica che l’URL della risorsa richiesta è stato modificato in modo permanente. Il nuovo URL viene fornito nella risposta tramite l’header Location:
NOTA: ciò vuol dire che il client dovrà ripetere la richiesta, ma cambiando risorsa con quella fornita dal server.
304 Not Modified
Il codice di risposta 304 Not Modified comunica al client che la risposta non è stata modificata, quindi il client può continuare a utilizzare la stessa versione della risposta memorizzata nella cache.
308 Permanent Redirect
Il codice di risposta 308 Permanent Redirect indica che la risorsa si trova ora in modo permanente in un altro URI, specificato dall’header Location: della risposta. Non è permesso il cambio del metodo da POST a GET.
NOTA: riportiamo questo codice per evidenziare che le specifiche HTTP si sono evolute nel tempo, anche per adattarsi all’uso e alle implementazioni. Sebbene, infatti, possa sembrare uguale a 301 Moved Permanently, la differenza tra le due è nella concessione del cambio di metodo. In passato infatti, alcuni web browser e web server avevano implementato un comportamento custom per il quale a seguito di una POST riuscita veniva fornita una risposta 301 con l’URI verso cui spostarsi per mostrare all’utente un altro contenuto. Da ciò, l’esigenza di un nuovo codice di risposta che fosse più specifico e meno fraintendibile.
401 Unauthorized
Per quanto riguarda il codice di risposta 401 Unauthorized occorre precisare che, sebbene lo standard HTTP specifichi “non autorizzato”, semanticamente questa risposta significa “non autenticato”. Ciò vuol dire che il client deve autenticarsi per ottenere la risposta richiesta.
403 Forbidden
Il codice di risposta 403 Forbidden segnala che il cliente non ha diritti di accesso al contenuto, ovvero non è autorizzato; quindi, il server si rifiuta di fornire la risorsa richiesta. A differenza di 401 Unauthorized, l’identità del client è nota al server.
404 Not Found
Il famosissimo codice di risposta 404 Not Found, che ben conosciamo tutti, ci segnala che il server non riesce a trovare la risorsa richiesta.
L’esatto significato di questo codice dipende anche dall’ambito in cui è stata effettuata la richiesta. Se, infatti, pensiamo a un browser, vuol dire che è stata richiesta una risorsa non presente (esempio: il browser sta chiedendo al server i file delle immagini che ha trovato nell’HTML di una pagina web, ma sul server non è stato caricato un certo file JPEG, oppure è stato commesso un errore nella contenuto dell’HTML).
Se, invece, siamo nell’ambito delle API, potrebbe anche significare che l’endpoint è formalmente valido, ma la risorsa non esiste (GET https://api.ecommerce.com/order/3452 nel caso non esista alcun ordine con id 3452).
410 Gone
Il codice di risposta 410 Gone è simile al precedente (il server non può restituire la risorsa), ma con diversa motivazione.
Questa risposta viene inviata quando il contenuto richiesto è stato definitivamente eliminato dal server. I client dovrebbero rimuovere le proprie cache e i link alla risorsa.
Questo codice d’errore è diventato molto importante nel tempo per strategie SEO, poiché indica ai crawler che quella risorsa può essere rimossa dalla SERP.
500 Internal Server Error
Il codice di risposta 500 Internal Server Error segnala, chiaramente, che il server ha riscontrato una situazione che non sa come gestire.
503 Service Unavailable
Il codice di risposta 503 Service Unavailable indica che il server non è momentaneamente in grado di gestire la richiesta, perché temporaneamente sovraccarico o per una manutenzione pianificata.
Questa risposta dovrebbe essere utilizzata per condizioni temporanee e può indicare tramite l’header Retry-After il tempo stimato prima del ripristino del servizio.
Riferimenti
Per maggiori approfondimenti su questi e altri status code HTTP:
