Cosa sono le API REST? Le API  (Application Programming Interface) sono un insieme di protocolli e di strumenti che consentono a un’applicazione di comunicare e scambiare dati con un altra applicazione. Aziende spesso rilasciano un API per aumentare il proprio pubblico attirando altri a sviluppare integrazioni con i suoi servizi popolari. REST è un acronimo per “Representational State Transfer” e si riferisce a una particolare tipologia di architettura API. In un API RESTful, i dati sono organizzati in risorse che possono essere accessibili tramite URI (Uniform Resource Identifiers) che consentono di identificare in modo unico quella risorsa (ad es. per un sito web si parla di URL) ma anche di manipolarla attraverso un insieme di metodi.

API REST e architettura client-server

Partiamo da un concetto di base, la maggior parte, se non tutte le applicazioni ad oggi funzionanti utilizzano un’architettura client-server. L’applicazione stessa è il client o la parte frontend. Questa applicazione deve comunicare con il server o con il backend per ottenere o salvare i dati.

Il server può fornire pagine web o file di dati e ogni server viene costruito in base alla tipologia di dati e di funzionalità a cui assolve. E comunica a sua volta con il client. Quindi la comunicazione tra server e client è reciproca.

Questa comunicazione tra server e client avviene tramite il protocollo HTTP, che è lo stesso protocollo utilizzato nel web. Lato server, quindi, è possibile esporre dati o servizi che diventano accessibili tramite il protocollo HTTP. Il client può quindi chiamare direttamente questi servizi inviando richieste HTTP.

Client-server-model

REST

È qui che entra in gioco REST. REST è l’abbreviazione di Representational State Transfer. REST è fondamentalmente una convenzione che, utilizzando semplici principi del protocollo HTTP, consente di creare, leggere, aggiornare o cancellare dati. In inglese Create, Read, Update and Delete, che corrispondono all’acronimo CRUD. Che corrispondono ai metodi POST, GET, PUT e DELETE.

REST, un esempio concreto

Supponiamo di avere un’azienda sanitaria chiamata Pippo che offre servizi sanitari a domicilio. Abbiamo un’applicazione client tramite la quale è possibile prenotare servizi di assistenza domiciliare, visite in telemedicina o quant’altro.

Il client può inviare richieste HTTP ad un indirizzo specifico (detto endpoint) per comunicare con il servizio di Pippo. Ora, è necessario sapere alcune cose su questo endpoint. Innanzitutto, l’indirizzo può iniziare con HTTP o HTTPS. Questo dipende dall’applicazione e dai suoi requisiti. Se si vuole che i dati siano scambiati su un canale sicuro, per ovvie ragioni di privacy, si userà HTTPS.

Nel nostro esempio l’endpoint potrebbe essere https://pippo.com/api/clienti

API REST

Una volta definito il nostro endpoint, questo consente di lavorare con i vari client. Tutte le operazioni relative al client, come la creazione o l’aggiornamento di un cliente, di un ordine o la sua cancellazione, vengono effettuate inviando una richiesta HTTP.

Il tipo di richiesta HTTP determina il tipo di operazione e ogni richiesta HTTP ha un metodo che ne determina il tipo o l’intenzione. Ecco i metodi standard:

  • GET: quando dobbiamo ottenere dati dal server e quindi siamo in lettura.
  • POST: quando dobbiamo creare dei dati nuovi, quindi quando siamo in scrittura.
  • PUT: quando i dati devono essere aggiornati, e quindi dobbiamo fare un update
  • DELETE: quando è necessario cancellare i dati.

Una richiesta contiene generalmente il metodo, l’endpoint, il corpo che può contenere dei parametri da aggiornare e spesso un header, dove generalmente vengono inserire l’API Key o alcuni parametri per l’autenticazione.

HTTP GET

Nell’esempio che abbiamo fatto, se per caso volessimo accedere all’elenco di tutti i clienti, dovremmo inviare una richiesta HTTP GET al nostro endpoint. Quindi una richiesta come questa:

GET /api/clienti

Se inviamo questo tipo di richiesta in risposta dovremmo avere un oggetto  contenente tutti i clienti salvati sul server. Potremmo ottenere un oggetto (prevalentemente un file JSON) formato più o meno in questo modo:

[{ id: ‘1’, name: ‘pippo’}, { id: ‘2’, name:’pluto’} etc.]

Se volessimo invece i dati di un singolo cliente, dovremmo includere il suo ID nell’indirizzo.

GET /api/clienti/1

In questo caso quello che andremmo a richiedere è un oggetto che contiene i dati di uno specifico cliente. Ottenendo qualcosa di simile a:

{ id: ‘1’, name: ‘pippo’ }

HTTP PUT

Se invece abbiamo bisogno di aggiornare i dati di un cliente, dobbiamo inviare una richiesta HTTP PUT.

PUT /api/clienti/1

{ name: ‘topolino’}

In questo caso andiamo ad aggiungere al corpo della richiesta l’oggetto del cliente modificato. Come risultato di questa operazione avremo un aggiornamento dell’oggetto del cliente 1 sul server e una nuova risposta simile a:

{ id: ‘1’, name: ‘topolino’ }

HTTP DELETE

Se invece è necessario cancellare il cliente dal server dobbiamo fare una richiesta HTTP DELETE, in questo caso non è necessario aggiungere alla richiesta l’oggetto da modificare, solamente indicare nella richiesta l’ID del cliente da cancellare:

DELETE /api/clienti/1

HTTP POST

Infine, per creare un nuovo cliente, dobbiamo inviare una richiesta HTTP POST al nostro endpoint. Si noti che in questo caso, poiché stiamo aggiungendo un nuovo cliente, non abbiamo a che fare con un cliente specifico, quindi non abbiamo l’ID nell’indirizzo. Avremo quindi questo tipo di richiesta:

POST /api/clienti

{ name: ‘paperino’}

Da notare che in questo caso stiamo lavorando con l’insieme dei clienti, quindi stiamo inviando un nuovo cliente al nostro gruppo. Ecco perché dobbiamo includere l’oggetto cliente nel corpo della richiesta.

Il server riceve questo oggetto e crea il cliente per noi.

Quali sono i vantaggi delle API REST?

  1.  Sono semplici e utilizzano un protocollo comune di comunicazione. Non è necessario preoccuparsi su come sono formattati i data, o come formattare le tue richieste ogni volta. Sono tutti standard usati dall’industria.
  2. Le API REST sono scalabili e stateless. Quindi, se il vostro servizio cresce in complessità, potete facilmente fare delle modifiche. E il fatto che sono stateless significa che non è necessario tenere una connessione costante tra client e server.
  3. Hanno una performance alta in generale, perchè supportano il caching.

Vincoli delle API REST

Le API REST possono essere sviluppate con quasi ogni linguaggio di programmazione e supportano una grande varietà di dati. L’unico requisito richiesto è che l’architettura delle API rispetti dei vincoli.

I 6 vincoli strutturali delle API REST sono:

  1. Client-server: il modello clientserver separa i dati e le funzionalità dellapplicazione in due parti, consentendo agli utenti di interagire con lapplicazione solo tramite il client.
  2. Stateless: le API REST non mantengono lo stato della connessione tra le richieste, il che significa che ogni richiesta è indipendente dalle altre.
  3. Cacheable: le API REST possono essere memorizzate nella cache per migliorare le prestazioni.
  4. Layered system: le API REST possono essere utilizzate in sistemi a più livelli, consentendo agli utenti di accedere solo ai dati e alle funzionalità di cui hanno bisogno.
  5. Code on demand: le API REST possono fornire agli sviluppatori il codice necessario per estendere le funzionalità del client.
  6. Uniform interface: le API REST devono utilizzare uninterfaccia uniforme per tutte le richieste, il che significa che tutte le richieste devono utilizzare lo stesso metodo (ad esempio, GET o POST) e lo stesso formato (ad esempio, JSON o XML).