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).