API REST

Un’API REST espone i dati di un’applicazione come risorse, ad esempio /orders o /orders/42, e permette ai client di agire su di esse con i metodi HTTP standard. REST (Representational State Transfer) è uno stile architetturale più che uno standard, quindi le API reali lo seguono in misura diversa. Le idee centrali sono URL orientati alle risorse, uso significativo dei metodi e degli status code HTTP e richieste stateless: ogni richiesta contiene tutto ciò di cui il server ha bisogno, autenticazione compresa.

Esempio

Richiesta	Significato	Esito positivo tipico
GET /orders?status=open	Elenca gli ordini aperti	200 OK
GET /orders/42	Legge un ordine	200 OK
POST /orders	Crea un ordine	201 Created + header Location
PUT /orders/42	Sostituisce l’ordine	200 OK o 204 No Content
PATCH /orders/42	Modifica alcuni campi	200 OK
DELETE /orders/42	Elimina l’ordine	204 No Content

Un test con REST Assured 5:

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;

given()
    .baseUri("https://api.example.com")
    .header("Accept", "application/json")
.when()
    .get("/orders/42")
.then()
    .statusCode(200)
    .body("id", equalTo(42))
    .body("status", equalTo("open"));

Cosa testare in un’API REST

• Status code per il successo e per ogni percorso di errore: autenticazione mancante, ruolo sbagliato, body non valido, id sconosciuto, conflitti.
• Body e schema della risposta: nomi dei campi, tipi, campi obbligatori, e che i campi sensibili non vengano esposti.
• Header: Content-Type, Location dopo una creazione, header di caching e CORS dove rilevanti.
• Semantica dei metodi: GET non ha effetti collaterali, PUT e DELETE sono idempotenti.
• Autorizzazione a livello di oggetto: l’utente A non deve poter leggere /orders/{id} appartenente all’utente B.
• Paginazione, filtri e ordinamento, comprese le pagine vuote e l’ultima pagina.

Differenze rispetto ad altri stili di API

GraphQL di solito espone un unico endpoint in cui il client descrive i dati che vuole, e spesso restituisce 200 anche quando una parte della query è fallita, quindi i test devono controllare il campo errors. SOAP usa envelope XML e un contratto WSDL formale. gRPC usa HTTP/2 e Protocol Buffers. Una suite di test REST si appoggia molto su HTTP stesso, ed è per questo che i fondamenti di HTTP sono così importanti per chi testa le API.