REST API — cos’è e come funziona

Una REST API è un modo comune di progettare una web API attorno a risorse come utenti, problemi o ordini. A ogni risorsa viene assegnato un URL e metodi HTTP come GET, POST, PATCH e DELETE indicano al server che cosa il client vuole fare.

REST significa Representational State Transfer. In pratica, un client invia una richiesta HTTP, il server restituisce una rappresentazione di una risorsa e ogni richiesta dovrebbe avere senso da sola. Molte REST API restituiscono JSON, ma il solo JSON non rende un’API RESTful.

Significato di REST API: pensa in termini di risorse

Il modo più rapido per capire REST è pensare in termini di nomi, non di verbi.

Se il tuo sistema ha problemi, studenti e tentativi, questi possono essere risorse. Un’API orientata alle risorse tende a usare URL come /api/problems/42 o /api/attempts/9001.

Il metodo HTTP ti dice poi che tipo di operazione sta avvenendo:

• GET legge una risorsa
• POST crea una nuova risorsa
• PUT sostituisce una risorsa
• PATCH aggiorna una parte di una risorsa
• DELETE rimuove una risorsa

Questa separazione è ciò che rende REST facile da leggere a colpo d’occhio. L’URL dice su cosa stai lavorando. Il metodo dice che cosa vuoi fare.

Come funziona una richiesta REST API

In un flusso tipico, un browser, un’app mobile o un altro servizio invia una richiesta a un server. La richiesta include un URL, un metodo HTTP, header opzionali e talvolta un body.

Il server legge la richiesta, esegue l’azione e restituisce una risposta. Questa risposta di solito include un codice di stato come 200 OK, 201 Created o 404 Not Found, oltre a dati che descrivono il risultato.

Una condizione importante è la statelessness. In REST, ogni richiesta dovrebbe contenere il contesto necessario per quella richiesta. Questo non significa che il server non memorizzi dati. Significa che il server non dovrebbe aver bisogno di uno stato nascosto della conversazione da richieste precedenti per capire quella attuale.

Esempio di REST API: un’app per esercitarsi in matematica

Supponiamo che un’app per esercitarsi in matematica memorizzi problemi di algebra e tentativi degli studenti.

Per leggere il problema $42$, il client potrebbe inviare: