Impara / Cheat sheet
Cheat sheet HTTP per il testing delle API
Quello che serve a un tester sull’HTTP in un solo foglio: quali metodi sono sicuri e idempotenti, quale status code deve restituire ogni situazione, gli header su cui vale la pena fare asserzioni, le opzioni di cURL che userai ogni giorno e una checklist per ogni risposta.
Verificato su Semantica HTTP secondo RFC 9110; Problem Details secondo RFC 9457
Metodi
| Metodo | Uso | Sicuro | Idempotente |
|---|---|---|---|
GET | Leggere una risorsa o una collezione | Sì | Sì |
HEAD | Come GET, solo header | Sì | Sì |
OPTIONS | Metodi consentiti; preflight CORS | Sì | Sì |
POST | Creare o eseguire un’azione | No | No |
PUT | Sostituire l’intera risorsa | No | Sì |
PATCH | Modificare alcuni campi | No | Non garantito |
DELETE | Eliminare una risorsa | No | Sì |
Idempotente significa che ripetere la richiesta lascia il server nello stesso stato. La risposta può cambiare: un secondo DELETE può restituire 404.
Status code da verificare
| Codice | Significato | Test tipico |
|---|---|---|
200 OK | Successo con un body | GET di una risorsa esistente |
201 Created | Risorsa creata | POST di dati validi; controlla l’header Location |
204 No Content | Successo, body vuoto | DELETE, o PUT che non restituisce nulla |
301 / 308 | Spostato in modo permanente | Il vecchio URL reindirizza; 308 mantiene il metodo |
304 Not Modified | La copia in cache è ancora valida | GET con If-None-Match: <etag> |
400 Bad Request | Richiesta malformata | JSON non valido, tipi errati |
401 Unauthorized | Non autenticato | Token mancante o scaduto |
403 Forbidden | Autenticato, ma non autorizzato | Accesso alla risorsa di un altro utente |
404 Not Found | Risorsa inesistente | Id sconosciuto (o per nasconderne una che non puoi vedere) |
405 Method Not Allowed | Metodo sbagliato per questo URL | DELETE su un endpoint di sola lettura |
409 Conflict | In conflitto con lo stato attuale | Email duplicata, versione obsoleta |
415 Unsupported Media Type | Formato del body non accettato | Invio di text/plain a un endpoint JSON |
422 Unprocessable Content | JSON valido, valori non validi | Errori di validazione delle regole di business |
429 Too Many Requests | Rate limit superato | Raffica di richieste; controlla Retry-After |
500 Internal Server Error | Bug del server | Mai atteso: è sempre un difetto |
502 / 503 / 504 | Errore a monte, servizio non disponibile, timeout | Dipendenza giù; controlla i retry |
Header da controllare
| Header | Esempio | Perché |
|---|---|---|
Content-Type | application/json; charset=utf-8 | Il formato dichiarato corrisponde al body |
Accept | application/json | Il client chiede un formato; aspettati 406 se non è supportato |
Authorization | Bearer eyJhbGciOi… | Autenticazione con token; se manca → 401 |
Location | /api/orders/1043 | Impostato su 201 Created e sui redirect |
Cache-Control | no-store | I dati personali o sensibili non devono finire in cache |
ETag / If-None-Match | "a1b2c3" | GET condizionale → 304 |
Retry-After | 30 | Inviato con 429 o 503 |
Set-Cookie | sid=…; HttpOnly; Secure; SameSite=Lax | I cookie di sessione richiedono HttpOnly e Secure |
Access-Control-Allow-Origin | https://app.example.com | CORS: mai * per le richieste con credenziali |
cURL
| Attività | Codice |
|---|---|
| Mostra status e header | curl -i https://api.example.com/users/1 |
| Trace completa di richiesta/risposta | curl -v https://api.example.com/users/1 |
| POST di JSON | curl -X POST https://api.example.com/users \
-H 'Content-Type: application/json' \
-d '{"email":"qa@example.com"}' |
| Bearer token | curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me |
| Basic auth | curl -u user:pass https://api.example.com/admin |
| Segui i redirect | curl -L https://example.com/old |
| Solo lo status code | curl -s -o /dev/null -w '%{http_code}' https://api.example.com/health |
| Fallisci su 4xx/5xx negli script | curl --fail-with-body https://api.example.com/health |
Nel cmd di Windows sostituisci gli apici singoli con doppi apici ed esegui l’escape di quelli interni.
Checklist per ogni risposta
| Controllo | Esempio |
|---|---|
| Status code | Esattamente 201, non "un qualsiasi 2xx" |
| Schema del body | Campi obbligatori presenti, tipi corretti, nessun campo sensibile in più |
| Valori | I dati inviati tornano uguali; i campi calcolati (totali, date) sono corretti |
| Header | Content-Type, Location, Cache-Control |
| Formato degli errori | Formato di errore coerente (es. problem details RFC 9457) con un messaggio utile |
| Effetti collaterali | Il record esiste, o non esiste, quando lo rileggi con GET |
| Tempo di risposta | Entro il budget concordato |