GitHub, le service de Git populaire, utilise OpenAPI pour décrire son « GitHub v3 REST API ». La définition API est disponible en repository sur GitHub. À l’aide de ce document, un utilisateur peut comprendre exactement quels services sont proposés par l’API de GitHub et comment structurer les requêtes qui lui seront adressées. Par ailleurs, n’importe qui peut utiliser l’API pour écrire du code adapté à l’aide des bons outils.
Selon GitHub, cette définition API sert à décrire, créer, consommer et visualiser l’API REST. À l’heure où nous écrivons ces lignes, la définition API n’est pas disponible dans son intégralité. Il manque encore quelques champs header, qui seront complétés ultérieurement. Il est également mentionné que plusieurs opérations API possibles peuvent être exécutées via différents chemins, alors que la spécification ne liste qu’un chemin.
Pour des questions de compatibilité, GitHub propose la définition API dans différents formats. On trouve tout d’abord une version dite « bundled » (en paquet). Elle contient les composants introduits avec OpenAPI 3.0 et les références rattachées. En parallèle, GitHub propose une version dite « dereferenced » (déréférencée), dont toutes les références ont été supprimées. En raison des répétitions qui en découlent, la définition API déréférencée est presque trois fois plus volumineuse que celle en paquet. De nombreux outils ne prennent pas encore en charge les références : c’est à ces solutions qu’est destinée la version déréférencée.
Vous pouvez consulter vous-même la définition API. Attention, les fichiers complets représentent plusieurs mégabytes. Pour un fichier texte, cela représente une quantité d’information colossale. Il est impossible d’afficher directement un fichier de cette taille sur GitHub. Vous pouvez cependant cliquer sur le lien suivant pour afficher l’API REST de GitHub dans votre navigateur. Il s’agit de la version bien plus compacte et plus lisible en YAML : GitHub REST API (YAML).