Cos'è un'API REST?

Introdotto per la prima volta nel 2000 dall'informatico Roy Fielding nella sua tesi di dottorato, REST offre agli sviluppatori un livello relativamente elevato di flessibilità, scalabilità ed efficienza. Per questi motivi, le API REST sono emerse quale metodo comune per connettere componenti e applicazioni in un'architettura di microservizi.

A livello di base, un'API è un meccanismo che consente a un'applicazione o servizio di accedere a una risorsa all'interno di un'altra applicazione o servizio. L'applicazione o il servizio che accede alle risorse è il client e l'applicazione o il servizio che contiene la risorsa è il server. Alcune API, come SOAP o XML-RPC, impongono un framework rigoroso agli sviluppatori. Ma gli sviluppatori possono sviluppare API REST utilizzando praticamente qualsiasi linguaggio di programmazione e supportare una varietà di formati di dati. L'unico requisito è che siano allineati ai seguenti sei principi di progettazione REST, noti anche come vincoli architetturali.

Tutte le richieste API per la stessa risorsa devono avere lo stesso aspetto, indipendentemente dalla provenienza della richiesta. L'API REST deve garantire che lo stesso dato, ad esempio il nome o l'indirizzo e-mail di un utente, appartenga a un solo URI (Uniform Resource Identifier). Le risorse non devono essere troppo grandi, ma devono contenere tutte le informazioni di cui il cliente potrebbe aver bisogno.

Nella progettazione di API REST, le applicazioni client e server devono essere completamente indipendenti l'una dall'altra. L'unica informazione che l'applicazione client deve conoscere è l'URI della risorsa richiesta; non può interagire con l'applicazione server in nessun altro modo. Allo stesso modo, un'applicazione server non dovrebbe modificare l'applicazione client se non passandole i dati richiesti via HTTP.

Le API REST sono stateless, il che significa che ogni richiesta deve includere tutte le informazioni necessarie per elaborarla. In altre parole, le API REST non richiedono sessioni lato server. Le applicazioni server non sono autorizzate a memorizzare dati relativi a una richiesta del client.

Quando possibile, le risorse dovrebbero essere memorizzabili nella cache sul lato client o server. Le risposte del server devono inoltre contenere informazioni sull'eventuale autorizzazione della memorizzazione nella cache per la risorsa recapitata. L'obiettivo è migliorare le prestazioni sul lato client, aumentando al contempo la scalabilità sul lato server.

Nelle API REST, le chiamate e le risposte passano attraverso diversi livelli. Come regola generale, non dare per scontato che le applicazioni client e server si connettano direttamente tra loro. Possono esserci diversi intermediari nel ciclo di comunicazione. Le API REST devono essere progettate in modo che né il client né il server possano sapere se comunicano con l'applicazione finale o con un intermediario.

Le API REST di solito inviano risorse statiche, ma in alcuni casi le risposte possono contenere anche codice eseguibile (come gli applet Java). In questi casi, il codice deve essere eseguito solo on-demand.

Le API REST comunicano tramite richieste HTTP per eseguire funzioni di database standard come la creazione, la lettura, l'aggiornamento e l'eliminazione di record (insieme di operazioni noto anche come CRUD) all'interno di una risorsa.

Ad esempio, un'API REST utilizzerà una richiesta GET per recuperare un record. Una richiesta POST crea un nuovo record. Una richiesta PUT aggiorna un record e una richiesta DELETE ne elimina uno. Tutti i metodi HTTP possono essere utilizzati nelle chiamate API. Un'API REST ben progettata è simile a un sito web in esecuzione in un browser web con funzionalità HTTP integrata.

Lo stato di una risorsa in un determinato istante, o data/ora, è noto come rappresentazione della risorsa. Queste informazioni possono essere inviate a un client praticamente in qualsiasi formato, tra cui JavaScript Object Notation (JSON), HTML, XLT, Python, PHP o testo semplice. JSON è popolare perché è leggibile sia dagli esseri umani che dalle macchine ed è indipendente dal linguaggio di programmazione.

Anche le intestazioni e i parametri delle richieste sono importanti nelle chiamate API REST perché includono importanti informazioni di identificazione come metadati, autorizzazioni, URI, memorizzazione nella cache, cookie e altro ancora. Le intestazioni di richiesta e le intestazioni di risposta, insieme ai codici di stato HTTP convenzionali, vengono utilizzate all'interno di API REST ben progettate.

Sebbene la flessibilità sia un grande vantaggio della progettazione delle API REST, la stessa flessibilità semplifica la progettazione di un'API che non funziona o funziona male. Per questo motivo, gli sviluppatori professionisti condividono le best practice nelle specifiche delle API REST.

Lo standard OpenAPI Specification (OAS) stabilisce un'interfaccia per descrivere un'API in modo da consentire a qualsiasi sviluppatore o applicazione di scoprirla e comprenderne appieno i parametri e le funzionalità. Queste informazioni includono gli endpoint disponibili, le operazioni consentite su ciascun endpoint, i parametri delle operazioni, i metodi di autenticazione e molto altro. L'ultima versione, OAS3, include strumenti pratici, come OpenAPI Generator, per la generazione di client APi e stub di server in diversi linguaggi di programmazione.

La protezione di un'API REST inizia anche con le best practice del settore. Utilizza algoritmi di hashing per la sicurezza delle password e HTTPS per la trasmissione sicura dei dati. Un framework di autorizzazione come OAuth 2.0 può aiutare a limitare i privilegi delle applicazioni di terze parti.

Utilizzando una data/ora nell'intestazione HTTP, un'API può anche rifiutare qualsiasi richiesta che arrivi dopo un certo periodo di tempo. La convalida dei parametri e i JWT (JSON Web Token) sono altri modi per garantire che solo i clienti autorizzati possano accedere all'API.