REST API: cos'è, metodi HTTP e principio di funzionamento nelle app mobile

Cos'è REST API?

REST API (API di Trasferimento dello Stato Rappresentazionale) è uno stile architetturale proposto da Roy Fielding nella sua tesi di dottorato nel 2000. Definisce un insieme di vincoli e principi per la progettazione di protocolli di rete. Un'API che rispetta questi vincoli è chiamata RESTful. REST non è un protocollo o uno standard — è un approccio architetturale che utilizza protocolli esistenti (principalmente HTTP) per lo scambio di dati tra client e server.

L'idea chiave di REST è l'architettura orientata alle risorse. Invece di chiamare metodi sul server (come in SOAP o RPC), il client opera sulle risorse: ottiene elenchi, ne crea di nuovi, li aggiorna o li elimina. Ogni risorsa è un'entità del dominio: utente, ordine, prodotto, articolo. Una risorsa ha uno stato che viene trasmesso al client in un formato standardizzato, solitamente JSON. Il server non memorizza lo stato del client tra le richieste — questo è il principio stateless, un requisito fondamentale di REST.

Caratteristiche principali di REST API:

• Stateless — ogni richiesta dal client contiene tutte le informazioni necessarie per la sua elaborazione
• Cacheable — le risposte del server devono essere esplicitamente marcate come memorizzabili in cache o meno
• Layered system — l'architettura può includere server intermedi, bilanciatori di carico, proxy
• Uniform interface — un'interfaccia di interazione unificata tramite metodi HTTP, URL e codici di stato

Principi dell'architettura REST

REST si basa su sei vincoli architetturali formulati da Fielding. Il rispetto di questi vincoli garantisce scalabilità, prestazioni e facilità di integrazione. Ogni principio risolve un problema specifico dei sistemi distribuiti — dalla necessità di caching ai requisiti di sicurezza. Esaminiamo ogni principio in dettaglio.

Il principio Uniform Interface include inoltre quattro sotto-vincoli: identificazione delle risorse tramite URI, manipolazione delle risorse attraverso rappresentazioni, messaggi auto-descrittivi e HATEOAS (Hypermedia come Motore dello Stato dell'Applicazione). L'ultimo sotto-vincolo è spesso ignorato nella pratica — la maggior parte delle API REST moderne non implementa completamente HATEOAS, portando a discussioni sul fatto che tale API sia “realmente” RESTful.

Il principio Stateless è uno dei più importanti per la scalabilità. L'assenza di sessioni sul server significa che qualsiasi istanza del server può elaborare qualsiasi richiesta. Questo semplifica la scalabilità orizzontale: basta aggiungere nuovi server dietro un bilanciatore di carico. Per le applicazioni mobili, stateless significa anche che una richiesta può essere inviata a qualsiasi server CDN, fondamentale per la disponibilità globale.

Metodi HTTP in REST

Ogni metodo HTTP in REST API corrisponde a un'operazione specifica su una risorsa: GET per la lettura, POST per la creazione, PUT per l'aggiornamento completo, PATCH per l'aggiornamento parziale, DELETE per l'eliminazione. L'idempotenza dei metodi è una caratteristica chiave: GET, PUT, DELETE sono idempotenti (l'esecuzione ripetuta produce lo stesso risultato), POST e PATCH no. Questo è importante per gestire gli errori di rete quando il client non sa se la richiesta è arrivata al server.

• GET — ottenimento di una risorsa o elenco di risorse. Idempotente, non modifica lo stato del server
• POST — creazione di una nuova risorsa. Non idempotente, ogni chiamata crea una nuova risorsa
• PUT — sostituzione completa della risorsa. Idempotente, le chiamate ripetute non modificano lo stato dopo la prima
• PATCH — aggiornamento parziale della risorsa. Parzialmente idempotente (dipende dall'implementazione)
• DELETE — eliminazione della risorsa. Idempotente, l'eliminazione ripetuta restituisce 404, non un errore

I codici di stato HTTP sono parte integrante di REST API. Ogni codice ha un significato specifico: 200 OK per GET riuscito, 201 Created per POST, 204 No Content per DELETE senza corpo della risposta, 400 Bad Request per dati non validi, 401 Unauthorized per assenza di autenticazione, 404 Not Found per risorsa inesistente. L'uso corretto dei codici di stato rende l'API auto-documentante e semplifica il debug.

Formati dei dati: JSON e altri

JSON (Notazione Oggetti JavaScript) è il formato principale di trasferimento dati in REST API. La sua popolarità è dovuta alla semplicità, leggibilità umana e supporto nativo in JavaScript. JSON viene trasmesso con l'intestazione Content-Type: application/json. Le alternative includono XML (verboso, invecchiato), YAML (comodo per la configurazione, meno comune per le API) e Protocol Buffers (binario, efficiente per sistemi ad alto carico).

La struttura di un oggetto JSON in REST API include solitamente i campi id, type e gli attributi della risorsa. Per le collezioni, viene utilizzato un array JSON con metadati di paginazione. Le API REST moderne seguono la specifica JSON:API (jsonapi.org) o JSON Schema per la validazione delle risposte. L'uso di un formato dati unificato semplifica lo sviluppo di librerie client e la generazione di documentazione.

Esempio di risposta JSON per un elenco di utenti:

{
    "data": [
        {
            "id": 1,
            "name": "Anna Petrova",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

La scelta del formato di trasferimento dati influisce sulle prestazioni dell'applicazione mobile. JSON si comprime tramite GZIP del 70-80%, rendendolo accettabile per la maggior parte degli scenari. Per le applicazioni in tempo reale con grandi volumi di dati (streaming, giochi), si consiglia di passare a protocolli binari o utilizzare WebSocket in combinazione con Protocol Buffers.

Esempi di richieste REST API

Vediamo esempi pratici di lavoro con REST API dal lato dell'applicazione mobile. Come esempio, prendiamo un'API per lavorare con gli ordini in un negozio online. Per ogni metodo HTTP, vengono mostrati una richiesta e la risposta attesa dal server. Gli esempi dimostrano la struttura tipica di un'API RESTful utilizzata nello sviluppo mobile.

GET — ottenimento di un elenco di ordini

Una richiesta per ottenere tutti gli ordini di un utente con paginazione. La risposta contiene un array di oggetti ordine e meta-informazioni per la navigazione tra le pagine. I parametri page e per_page vengono passati tramite query string.

// Interfaccia Retrofit per REST API
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — creazione di un nuovo ordine

Creazione di un nuovo ordine tramite una richiesta POST. Il server restituisce lo stato 201 Created e l'oggetto creato nel corpo della risposta. Importante: la creazione avviene sulla collezione /api/v1/orders, non su una risorsa specifica — questo è il pattern RESTful standard.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// Esempio di corpo della richiesta
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — eliminazione di un ordine

L'eliminazione di una risorsa viene effettuata con il metodo DELETE sull'URL specifico dell'ordine. L'eliminazione riuscita restituisce 204 No Content. L'idempotenza di DELETE significa che una richiesta ripetuta allo stesso URL restituisce 404 Not Found, gestito correttamente dal client.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// Utilizzo in ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Questi esempi mostrano un'implementazione tipica di REST API sul lato Android utilizzando Retrofit e Kotlin Coroutines. Per le applicazioni iOS, URLSession o la libreria Alamofire insieme ai protocolli Codable svolgono un ruolo simile. La struttura di REST API rimane la stessa indipendentemente dalla piattaforma — cambia solo il modo di effettuare le richieste.

Progettazione API RESTful: raccomandazioni pratiche

Progettare un'API RESTful di qualità richiede il rispetto di convenzioni che rendano l'API intuitiva per gli sviluppatori. Le risorse dovrebbero essere nominate con sostantivi plurali (/users, /orders, /products), i metodi HTTP dovrebbero riflettere le operazioni e gli URL dovrebbero rappresentare la gerarchia di annidamento. Gli errori dovrebbero restituire un JSON standardizzato con codice e messaggio, non solo uno stato HTTP. Il rispetto di queste convenzioni abbassa la barriera d'ingresso per i nuovi sviluppatori e semplifica l'integrazione.

• Assegnazione dei nomi delle risorse — plurale, kebab-case: /api/v1/user-orders, non /api/v1/getUserOrders
• Filtraggio e ordinamento — tramite parametri query: ?status=active&sort=created_at:desc
• Paginazione — basata su cursore per grandi insiemi, basata su pagina per piccoli
• Versionamento — tramite URL (/api/v2/) o intestazione Accept-Version
• Errori — formato unificato: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — intestazioni X-RateLimit-Remaining e Retry-After

Un errore comune nella progettazione di una REST API è l'annidamento eccessivo delle risorse. Invece di /users/1/orders/5/items/3, è meglio usare una struttura piatta con parametri query: /items?order_id=5&user_id=1. Questo semplifica la memorizzazione nella cache, non richiede di mantenere percorsi lunghi sul server ed è più facile da documentare. L'architettura piatta è anche più compatibile con le query basate su grafo in caso di futura migrazione a GraphQL.

La sicurezza di REST API è implementata attraverso l'autenticazione (JWT, OAuth 2.0) e l'autorizzazione a livello di risorsa. Ogni richiesta deve verificare se l'utente ha accesso alla risorsa richiesta. HTTPS è obbligatorio — senza crittografia, i token e i dati vengono trasmessi in chiaro. Per le applicazioni mobili, si consiglia di utilizzare OAuth 2.0 con PKCE (Proof Key for Code Exchange) per l'ottenimento sicuro dei token.

Versionamento e caching

Il versionamento di REST API è necessario per la retrocompatibilità durante le modifiche. Gli approcci più comuni sono: versione nell'URL (/api/v1/orders), versione nell'intestazione (Accept: application/vnd.myapi.v1+json) e versione nel parametro query (?api_version=1). Il versionamento tramite URL è il metodo più popolare poiché è esplicitamente visibile nei log e nella documentazione. Tuttavia, viola il principio REST di un singolo URL per risorsa.

Il caching in REST API è implementato tramite le intestazioni HTTP Cache-Control, ETag e Last-Modified. Le richieste GET marcate come memorizzabili nella cache possono essere servite dalla cache del browser o proxy senza contattare il server. Per le applicazioni mobili, il caching è particolarmente importante — riduce il consumo di dati e accelera la visualizzazione dei dati precedentemente caricati in caso di connettività scadente. ETag è un hash del contenuto della risposta: il client lo invia in If-None-Match e il server restituisce 304 Not Modified se i dati non sono cambiati.

Le alternative moderne a REST API includono GraphQL (recupero flessibile dei dati dal client) e gRPC (protocollo binario su HTTP/2 per microservizi). Tuttavia, REST rimane lo standard principale per le API pubbliche grazie alla sua semplicità, universalità e ampio supporto di strumenti. La scelta tra REST e alternative dipende dai requisiti specifici del progetto: complessità delle query, volume di dati, esigenze di aggiornamenti in tempo reale.