Cos'è API REST?

Definito per la prima volta nel 2000 dall'informatico Dr. Roy Fielding nella sua tesi di dottorato, lo stile REST offre agli sviluppatori un livello relativamente elevato di flessibilità, uniformità, scalabilità ed efficienza. Le API REST rappresentano un modo semplice per creare API web e sono comunemente utilizzate per facilitare lo scambio di dati tra applicazioni, servizi web e database e per connettere componenti nelle architetture di microservizi .

A livello base, un'API è un meccanismo che permette a un'applicazione o a un servizio di accedere a una risorsa all'interno di un'altra applicazione, servizio o database. 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 vari 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 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 tramite 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 d'oro, non dare per scontato che le applicazioni client e server si connettano direttamente tra loro. Nel ciclo di comunicazione potrebbero essere presenti diversi intermediari. 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 inviano solitamente 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 su richiesta.

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 timestamp, è 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.

GraphQL e API REST: Qual è la differenza?

Sebbene la flessibilità sia un vantaggio significativo della progettazione delle API REST, quella stessa flessibilità rende facile progettare 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 server stub in diversi linguaggi di programmazione.

Anche la protezione di un'API REST inizia 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.0può 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.