Che cos’è OpenAPI?
La redazione di IONOS
OpenAPI è uno standard per la descrizione delle interfacce di programmazione, ovvero le Application Programming Interfaces (API). La specifica OpenAPI definisce un formato di descrizione aperto e non soggetto a licenza per i servizi API. In particolare, tramite OpenAPI si possono descrivere, sviluppare, testare e documentare le API REST.
La specifica OpenAPI attuale deriva dal precedente progetto Swagger. La società di sviluppo SmartBear ha posto la specifica Swagger esistente sotto licenza aperta e ne ha affidato la manutenzione e l’ulteriore sviluppo alla OpenAPI Initiative. Accanto a SmartBear, fanno parte della OpenAPI Initiative alcuni colossi del settore come Google, IBM e Microsoft; il progetto è supportato anche dalla Linux Foundation.
- Gestione record DNS
- Amministrazione SSL
- Documentazione API
OpenAPI in sintesi
Un punto che può creare confusione è la distinzione tra OpenAPI e Swagger. OpenAPI è una specifica, cioè una descrizione astratta che non è legata a un’implementazione tecnica particolare. Fino alla versione 2.0, questa specifica era chiamata Swagger ed è stata rinominata in seguito specifica OpenAPI. Tuttavia, i tool forniti dalla società di sviluppo originale, SmartBear, continuano a esistere con il nome di Swagger.
OpenAPI permette di descrivere una API in modo uniforme. Si parla a tal proposito di “definizione API”, che viene generata in un formato leggibile dalle macchine. In particolare si utilizzano i due linguaggi YAML e JSON.
Accanto alla definizione API, si può talvolta sentir parlare di “specifica API”. Si tratta in questo caso di una descrizione astratta di API, creata esclusivamente per il lettore umano.
Tecnicamente, YAML e JSON differiscono solo marginalmente, per cui è possibile convertire automaticamente una definizione API esistente da un linguaggio all’altro. YAML, però, ha una struttura più chiara ed è più facilmente leggibile per l’occhio umano. Di seguito un esempio dello stesso server object OpenAPI, scritto in YAML e JSON:
# YAML
servers:
- url: https://development.example.com/v1
description: Development server
- url: https://staging.example.com/v1
description: Staging server
- url: https://api.example.com/v1
description: Production server// JSON
{
"servers": [
{
"url": "https://development.example.com/v1",
"description": "Development server"
},
{
"url": "https://staging.example.com/v1",
"description": "Staging server"
},
{
"url": "https://api.example.com/v1",
"description": "Production server"
}
]
}La specifica OpenAPI definisce una serie di proprietà che possono essere utilizzate per costruire la propria API. Queste proprietà sono raggruppate come cosiddetti oggetti (in inglese “objects”). Nell’attuale versione 3.0.3, OpenAPI definisce, tra l’altro, la struttura per i seguenti oggetti:
- Info Object: versione, nome, ecc. dell’API.
- Contact Object: informazioni di contatto del fornitore API.
- License Object: licenza con la quale l’API fornisce i suoi dati.
- Server Object: nomi degli host, struttura degli URL e porte dei server con cui viene indirizzata l’API.
- Components Object: componenti incapsulati che possono essere utilizzati più volte all’interno di una definizione API.
- Paths Object: percorsi relativi agli endpoint delle API che vengono utilizzati insieme al Server Object.
- Path Item Object: operazioni, come GET, PUT, POST, DELETE, consentite per un determinato percorso.
- Operation Object: specifica, ad esempio, i parametri e le risposte del server previste per un’operazione.
Quali sono i campi di applicazione di OpenAPI?
In generale, OpenAPI è utilizzato per descrivere le API REST in modo uniforme. Poiché questa descrizione, cioè la definizione API, è in un formato leggibile dalle macchine, è possibile generare automaticamente diversi artefatti virtuali, come ad esempio:
- creazione di documentazione API: la documentazione basata su HTML viene generata automaticamente dalla definizione API leggibile dalle macchine. Questa serve come testo di riferimento per gli sviluppatori che accedono ai servizi API. Se la definizione API cambia, la documentazione viene rigenerata in modo che entrambe rimangano coerenti.
- creazione di collegamenti in diversi linguaggi di programmazione: utilizzando gli strumenti appropriati, è possibile generare a partire dalla definizione API una libreria lato client in un linguaggio di programmazione supportato. Ciò consente ai programmatori di diversi linguaggi di accedere alle API. La libreria viene integrata in maniera classica; gli accessi ai servizi API avvengono quindi, ad esempio, tramite chiamate di funzione all’interno dell’ambiente di programmazione abituale.
- creazione di casi di prova: ogni componente di un software deve essere sottoposto a test per garantire la propria funzionalità. In particolare, un componente software deve essere testato a ogni modifica del codice sottostante. Dalla definizione API, questi test possono essere generati automaticamente, in modo che la funzionalità dei componenti software possa essere monitorata ininterrottamente.
Per completezza, va ricordato che non tutte le API possono essere mappate con OpenAPI. Tuttavia, le API REST sono esplicitamente supportate.
Quali sono i vantaggi di OpenAPI?
In generale, il vantaggio di OpenAPI è quello di mantenere una coerenza tra l’implementazione, la documentazione e i test di una API durante lo sviluppo e la manutenzione. Inoltre, l’uso della specifica OpenAPI permette un migliore coordinamento dello sviluppo delle API tra back end e front end. Da entrambi i lati, i componenti del codice possono essere generati dalla definizione delle API, permettendo ai team di back end e front end di sviluppare e testare senza doversi aspettare reciprocamente.
Oltre a questi vantaggi generali, OpenAPI è particolarmente utilizzato come base standardizzata per lo sviluppo di API REST. Questo è interessante perché non è banale sviluppare un’API REST manualmente. Tuttavia, le API REST hanno alcuni vantaggi; ad esempio, REST funziona su HTTP/S e le porte sono aperte in qualsiasi firewall.
Inoltre, l’utilizzo di OpenAPI presenta i seguenti vantaggi:
- definizione delle API HTTP indipendentemente da un linguaggio di programmazione specifico
- generazione del codice server per una API definita in OpenAPI
- generazione di librerie lato client per un’API conforme a OpenAPI in più di 40 linguaggi di programmazione
- elaborazione di una definizione OpenAPI con strumenti appropriati
- creazione di documentazione API interattiva
- possibilità di permettere a uomini e macchine di scoprire e comprendere le capacità di un servizio senza dover guardare il codice sorgente o la documentazione aggiuntiva
- possibilità di accedere ai servizi API con il minimo sforzo di implementazione
Quali sono le versioni di OpenAPI e in cosa differiscono?
Al momento della scrittura del presente articolo, la versione attuale è OpenAPI 3.0.3. Di seguito una breve panoramica delle versioni precedenti:
| Versione | Nome | Stato |
|---|---|---|
| 1.0, agosto 2011 | Specifica Swagger | Non più in uso |
| 2.0, settembre 2014 | Specifica Swagger > Specifica OpenAPI | Ancora supportata |
| 3.0, luglio 2017 | Specifica OpenAPI | Ancora supportata |
Di seguito vi mostriamo le novità più importanti quando si passa dalla versione 2.0 alla versione 3.0:
Nuovo nome dell’oggetto root
Con il rilascio della versione 3.0 è stato introdotto l’oggetto OpenAPI, che sostituisce l’oggetto Swagger precedentemente utilizzato:
# <= 2.0
"swagger": "2.0"
# >= 3.0
"OpenAPI": "3.0.0"Più host/server
A partire dalla versione 3.0 di OpenAPI, una API può essere indirizzata da più di un server. Inoltre, è possibile definire in modo variabile parti dell’URL del server. Un esempio qui di seguito:
"servers": [
{
"url": "https://{username}.example.com:{port}/{basePath}",
"description": "The production API server",
"variables": {
"username": {
"default": "demo",
"description": "this value is assigned by the service provider, in this example `example.com`"
},
"port": {
"enum": [
"8443"
"443"
],
"default": "8443"
},
"basePath": {
"default": "v2"
}
}
}
]Nuovi componenti e oggetti di riferimento
I componenti e gli oggetti di riferimento aggiunti nella versione 3.0 di OpenAPI sono una delle principali novità. L’oggetto componente consente di definire più oggetti riutilizzabili all’interno della definizione delle API. Questi cosiddetti componenti sono inclusi nella definizione API utilizzando la speciale istruzione $ref.
Utilizzando i componenti e i riferimenti, è possibile costruire una definizione API a partire da diverse parti riutilizzabili. Questo rende più facile la lettura e riduce le dimensioni dell’intero documento. Di seguito è riportato un esempio dalla definizione ufficiale API di GitHub:
- schema di un repository di codice GitHub, definito come oggetto componente;
- definizione della licenza, con riferimento a un componente definito esternamente.
"components": {
"schemas": {
// Schema del repository
"repository": {
"title": "Repository",
"description": "A git repository",
"type": "object",
"properties": {
"id": {
"description": "Unique identifier of the repository",
"example": 42,
"type": "integer"
},
"node_id": {
"type": "string",
"example": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5"
},
"name": {
"description": "The name of the repository.",
"type": "string",
"example": "Team Environment"
},
"full_name": {
"type": "string",
"example": "octocat/Hello-World"
},
// Definizione della licenza
"license": {
"nullable": true,
"allOf": [
{
// Riferimento a un componente definito esternamente
"$ref": "#/components/schemas/license-simple"
}
]
},OpenAPI in pratica: due esempi
La specifica OpenAPI e i relativi tool, in particolare Swagger, sono utilizzati su vasta scala per la creazione di varie API. Vi presentiamo qui due esempi:
GitHub v3 REST API
Il popolare servizio Git GitHub utilizza OpenAPI per descrivere la sua “GitHub v3 REST API”. La definizione API è disponibile su GitHub come repository. Con il suo aiuto, un utente può visualizzare esattamente a quali servizi può accedere tramite l’API di GitHub e come devono essere strutturate esattamente i richiami in questione. Inoltre, chiunque può utilizzare l’API per generare il relativo codice utilizzando gli strumenti appropriati.
Secondo GitHub, la definizione API viene utilizzata per descrivere, creare, eseguire e visualizzare l’API REST. Al momento della scrittura del presente articolo, la definizione API non è completa. Mancano, ad esempio, alcuni campi di intestazione che verranno aggiunti in futuro. Va inoltre notato che è possibile eseguire alcune delle possibili operazioni API tramite percorsi diversi, sebbene nelle specifiche possa essere elencato un solo percorso.
Per motivi di compatibilità, GitHub fornisce la definizione delle API in diversi formati. Da un lato, c’è una versione denominata “bundled”, che contiene i componenti introdotti con OpenAPI 3.0 e i relativi riferimenti. Dall’altro, viene offerta una versione chiamata dereferenziata (“deferenced”), in cui i riferimenti sono tutti risolti. A causa della ridondanza che si verifica, la definizione API dereferenziata è circa tre volte più grande di quella “bundled”. Molti strumenti non supportano ancora i riferimenti; per questi casi, la definizione di API dereferenziata è la scelta opportuna.
Potete dare un’occhiata voi stessi alla definizione API. Si noterà che il file completo ha una dimensione di diversi megabyte. Per un file di testo, si tratta di una quantità incredibilmente grande di informazioni. GitHub non può visualizzare direttamente un file così grande. Tuttavia, è possibile utilizzare il seguente link per visualizzare l’API REST di GitHub nel browser. Questa è la versione YAML, molto più compatta e leggibile: GitHub REST API (YAML).
Esempio di API petstore di SwaggerHub
Come secondo esempio, vi illustriamo un caso di API che può essere generato su SwaggerHub. SwaggerHub è una piattaforma online per la progettazione e lo sviluppo di API REST con OpenAPI. Qui potete registrarvi e creare un account utente gratuito, ma anche accedere con un account di GitHub (se ne avete già uno).
Una volta effettuato il login in SwaggerHub, è possibile creare una nuova API. C’è un’opzione per crearne una a partire da un modello esistente. Ad esempio, esiste un template API per un “petstore” virtuale, quindi per un negozio di animali. L’API del petstore creata con il template include una vasta gamma di oggetti OpenAPI. Questi includono:
- Informazioni di contatto, condizioni di utilizzo, licenza, ecc.
- Gli endpoint API e le operazioni di ogni endpoint
- I parametri di ingresso e di uscita consentiti delle operazioni
- Specifiche di sicurezza
Osservando l’API del petstore, si può imparare molto su come funziona OpenAPI. Inoltre, la definizione di petstore è un buon esempio per comprendere come costruire un’API REST. Infine, facciamo un esempio di codice partendo dall’API del petstore. Analizziamo la seguente sezione del codice:
- Il codice definisce l’endpoint API '/pet'.
- Con una richiesta HTTP POST viene aggiunto un nuovo animale domestico al negozio di animali.
- Se invece utilizzate il verbo HTTP PUT sullo stesso endpoint, potete modificare un animale già presente nel negozio.
- Per le operazioni sono definite diverse risposte del server. In questo esempio, i codici di stato HTTP includono il noto codice di stato 404 “Not Found”. Questo è stilizzato in questo caso come “Pet not found” nell’esempio dell’API del petstore.
Le righe di codice che iniziano con '$ref' e commentate con “OpenAPI 3.0+ Component” sono riferimenti a componenti OpenAPI definiti singolarmente.
# Petstore API Template #
# API Endpoint '/pet'
/pet:
# HTTP-POST Request
post:
tags:
- pet
summary: Add a new pet to the store
operationId: addPet
# HTTP-Status codes
responses:
'405':
description: Invalid input
security:
# Permissions
- petstore_auth:
- 'write:pets'
- 'read:pets'
requestBody:
# OpenAPI 3.0+ Component
$ref: '#/components/requestBodies/Pet'
# HTTP-PUT Request
put:
tags:
- pet
summary: Update an existing pet
operationId: updatePet
# HTTP-Status codes
responses:
'400':
description: Invalid ID supplied
'404':
description: Pet not found
'405':
description: Validation exception
security:
# Permissions
- petstore_auth:
- 'write:pets'
- 'read:pets'
requestBody:
# OpenAPI 3.0+ Component
$ref: '#/components/requestBodies/Pet'OpenAPI si è affermato come formato di descrizione aperto e non soggetto a licenza per i servizi API. Si prevede che sarà ampiamente utilizzato come standard per la costruzione di API REST nel prossimo futuro.
