Che cos'è OpenAPI?

Un file OpenAPI, noto anche come documento OpenAPI o specifica OpenAPI, consente a uno sviluppatore di descrivere un'API. Questa specifica descrive anche come utilizzare questa API, inclusi gli endpoint disponibili, i parametri delle operazioni, i metodi di autenticazione e altre informazioni. Queste specifiche sono scritte in YAML o JSON, e lo schema JSON viene utilizzato per descrivere i formati dati all'interno di un'API.

OpenAPI funge sia da documentazione che da contratto (nello spirito, descrive cosa dovrebbe fare un'API, non è legalmente vincolante) tra consumatori e produttori di API. In sostanza, funge da "unica fonte di informazioni" che fornisce le istruzioni in un formato standardizzato.

Questa standardizzazione semplifica il consumo e l'integrazione delle API. Consente agli esseri umani e ai computer di comprendere la funzione e la struttura di una determinata API senza accedere al codice sorgente o senza dover capire il funzionamento interno dell'API. Permette inoltre agli sviluppatori di lavorare con un'API, indipendentemente dal linguaggio in cui è stata scritta.

OpenAPI automatizza la creazione di documentazione interattiva e aggiornata, eliminando alcune attività ripetitive e contribuendo a garantire che la documentazione rimanga sempre attuale. OpenAPI consente inoltre la generazione di codice per gli SDK client e la generazione automatica di altro codice boilerplate dalla specifica, riducendo l'errore umano e minimizzando ulteriormente il carico di lavoro degli sviluppatori.

Gli strumenti che utilizzano le specifiche OpenAPI, incluso SwaggerUI, possono renderizzare una specifica API in un'interfaccia interattiva. Questa interfaccia non solo aiuta a visualizzare le specifiche, ma consente anche di effettuare chiamate API reali, direttamente dal browser o dal servizio web, a scopo di test e convalida.

Standardizzando la descrizione delle API REST, OpenAPI aiuta a migliorare l'interoperabilità e gli strumenti, e supporta le operazioni durante tutto il ciclo di vita dell'API. Una specifica forte e ben mantenuta può essere uno strumento fondamentale per implementare una strategia API completa, supportando l'integrazione, la collaborazione, la prevenzione degli errori e una gestione API più forte.

La specifica completa è disponibile su GitHub.

Come standard "de facto" del settore, OpenAPI fornisce un documento sicuro, automatizzato e ampiamente compreso per lo sviluppo di API.

OpenAPI è stata originariamente creata dallo sviluppatore Tony Tam e rilasciata per la prima volta nel 2011 con il nome di Swagger. All'epoca, le specifiche API erano spesso documenti statici che richiedevano aggiornamenti tediosi e spesso erano obsoleti. La specifica Swagger includeva diverse innovazioni nello sviluppo delle API, tra cui un pulsante "prova" per testare le chiamate API dal vivo e in tempo reale.

Swagger ha fatto della documentazione un elemento centrale della propria esistenza. Ha permesso agli sviluppatori di includere annotazioni, simili a una nota adesiva, nel loro codice sorgente. Swagger poteva leggere queste annotazioni e aggiornare automaticamente la documentazione, garantendo che la documentazione rimanesse aggiornata senza lavori di aggiornamento noiosi e ripetitivi. Swagger ha anche introdotto un formato per descrivere le API in JSON leggibile dalla macchina, che lo rendeva indipendente dal linguaggio: indipendentemente dal linguaggio di un backend, Swagger dava un file JSON universale in output.

Swagger è stata acquisita da SmartBear Software nel 2015, è stata rinominata OpenAPI poco dopo e donata alla nuova OpenAPI Initiative (OAI), sotto l'egida della Linux Foundation. La versione attuale è OpenAPI 3.1.

La specifica OpenAPI è un documento standardizzato, leggibile sia dagli esseri umani che dalle macchine, che definisce la struttura e la sintassi delle API. Tutti i documenti OpenAPI includono determinati componenti e sono conformi alla stessa struttura di base, ma alcune specifiche contengono più informazioni di altre. Come minimo, una specifica deve includere i campiopenAPI einfo e almeno un campopath , component o webhook.¹

openAPI: rileva la versione OpenAPI utilizzata dal documento, ad esempio "3.1.1"

info: include i metadati generali dell'API, come il titolo e il numero di versione dell'API, una descrizione dell'API, i termini di servizio e le informazioni di contatto. 

server: un elenco degli URL base a cui l'API può essere accessibile (che può includere sia ambienti di staging che di produzione). Questa lista include variabili per host specifici dell'ambiente.

paths: descrive i percorsi e i metodi HTTP associati (o operazioni, ad esempio GET, PUT, POST) e i parametri, i corpi delle richieste e le risposte per ogni elemento del percorso.

components: elenca gli oggetti riutilizzabili, come schemi di dati, parametri, risposte, intestazioni e definizioni di sicurezza. Questi oggetti possono essere citati in tutto il documento. I componenti vengono referenziati, in modo piuttosto semplice, tramite $ref. Questa strategia consente di mantenere il design di un'API il più snello possibile. 

security: indica gli schemi di sicurezza e i meccanismi di autenticazione che l'API utilizza, come OAuth o le chiavi API. Inoltre, consente l'applicazione di schemi di sicurezza a livello globale o per operazione.

tag: elenco di tag di alto livello utilizzati per organizzare le operazioni. L'utilizzo di tag può contribuire a migliorare la chiarezza del documento (ad esempio, "Utenti" o "Ordini").

external documentation: collega a guide, documenti di onboarding e altra documentazione esterna per l'API

webhooks: descrive le chiamate in entrata che l'API riceve. 

OpenAPI fornisce una singola fonte affidabile per gli sviluppatori e i consumatori di API e offre caratteristiche che aggiungono valore ed efficienza ai progetti API.

OpenAPI è nata con una forte attenzione alla documentazione delle API REST, e tale obiettivo rimane tuttora al centro della sua filosofia. La documentazione è standardizzata, interattiva, aggiornata in tempo reale e fornisce al contratto una singola fonte affidabile.

Esistono vari strumenti per leggere i documenti OpenAPI ed esportare il codice. Uno di questi strumenti è Swagger Codegen, che legge i documenti scritti secondo le specifiche OpenAPI. Swagger Codegen può quindi produrre kit di sviluppo software (SDK) per codice client API, codice lato server (stubs) e pagine web leggibili con documentazione aggiornata e leggibile dall'uomo.

Una delle funzionalità più innovative di OpenAPI rimane il pulsante "prova", che consente di effettuare test e convalide in tempo reale direttamente dal browser. L'interfaccia utente di Swagger, uno strumento open source gratuito, consente un'interfaccia visiva in cui uno sviluppatore può inviare richieste effettive per assicurarsi che rispondano come desiderato. Questo strumento facilita la verifica immediata del funzionamento di una richiesta.

OpenAPI viene comunemente utilizzato con le piattaforme di integrazione come servizio, o iPaaS.

Le piattaforme iPaaS utilizzano le specifiche OpenAPI per comprendere e connettere diverse applicazioni in un ecosistema IT. Quando le applicazioni espongono specifiche OpenAPI che descrivono le loro API, le piattaforme iPaaS possono utilizzare queste informazioni per scoprire automaticamente endpoint, metodi di autenticazione e strutture dati. Questa strategia rende più veloce la costruzione di integrazioni, come collegare una piattaforma di ecommerce a un software di contabilità.

OpenAPI consente inoltre agli sviluppatori frontend e backend di lavorare in parallelo. È preferibile lavorare in parallelo piuttosto che, come a volte accade, costringere il team di frontend ad aspettare che il team di backend abbia il database attivo e funzionante. Con un contratto OpenAPI, il team frontend può creare un server API fittizio che si comporta come uno reale, abilitando e ottimizzando i test prima che lo sviluppo del backend sia completato. 

La governance delle API, ovvero gli standard, le politiche e le pratiche che guidano come un'organizzazione sviluppa e utilizza le API, è fondamentale per garantire che le API operino in modo fluido, coerente e senza ripetizioni inutili. Poiché OpenAPI agisce come un contratto tra sviluppatori, governance e sicurezza possono essere integrate fin dall'inizio.

Prendiamo ad esempio gli API Gateway, che gestiscono compiti come instradamento del traffico, monitoraggio e limitazione di velocità. Gli API gateway possono in genere utilizzare le specifiche OpenAPI e applicare eventuali limiti di traffico o altre misure di sicurezza stabilite nelle specifiche.

Lo stesso vale per le regole di sicurezza. Una specifica OpenAPI consente agli sviluppatori di dichiarare i requisiti di sicurezza (come l'uso di OAuth 2.0 e delle chiavi API), e questi requisiti possono essere applicati a valle (magari da un gateway).  Delineare le funzionalità di sicurezza in un contratto API aiuta a garantire che gli sviluppatori non adottino schemi di sicurezza non supportati.

OpenAPI può rafforzare la gestione delle API, ovvero il processo scalabile di creazione, pubblicazione e gestione delle connessioni API, in diversi modi. Ad esempio, poiché le specifiche OpenAPI sono leggibili da macchina e standardizzate, i software di catalogo e portale possono indicizzarle automaticamente. Questa standardizzazione rende più facile trovare e comprendere le API in tutta un'organizzazione. Questa scopribilità aiuta a evitare che i team costruiscano inconsapevolmente API duplicate.

OpenAPI supporta inoltre una gestione e una governance coerenti rendendo espliciti e applicabili gli standard organizzativi. I team possono definire requisiti, come convenzioni di controllo delle versioni, formati di risposta agli errori o modelli di denominazione, direttamente all'interno o insieme alle specifiche. Poiché queste aspettative sono documentate in un formato standardizzato, possono essere automaticamente convalidate rispetto alle nuove API man mano che vengono aggiunte. Questa convalida riduce la dipendenza dalle recensioni manuali e aiuta a garantire che le API rimangano coerenti man mano che il portfolio di un'organizzazione cresce.