Das Rest-API der Versionierungsplattform gibt es schon seit 2008, erstmalig veröffentlicht wurde das Application-Programming-Interface nur einen Monat nach dem Launch von github.com. Unter Entwicklern gilt sie als ein Musterbeispiel für gutes API-Design. Aus diesem Grund hat die Plattform eine Open-AI-Beschreibung der API jetzt – zwölf Jahre und drei Major-Revisionen später – unter einer Open-Source-Lizenz veröffentlicht.

Die Open-API-Spezifikation ist ein Programmiersprachen-agnostischer Standard zur Beschreibung von http-API, über den sowohl Menschen als auch Maschinen die Möglichkeiten einer API erkunden können, ohne zuerst die Doku lesen oder die Implementation nachvollziehen zu müssen. Die Spezifikation gilt als Industriestandard.

GitHubs Open-API-Description enthält Beschreibungen von über 600 Vorgängen der hauseigenen Rest-API. Wer die API visuell erkunden möchte, kann sich den Spaß in Form einer Postman-Collection downloaden. Programmatisch könnt ihr die Description nutzen, um Mock-Server, Test-Umgebungen und Bindings für Sprachen zu generieren, die nicht von den offiziellen GitHub-API-Clients unterstützt werden.

Die Description gibt es in zwei Formaten. Mit der gebündelten Version stehen euch verschiedene, wiederverwendbare Objekte zur Verfügung. Die innerhalb des sogenannten Components-Object definierten Objekte können über Properties außerhalb des Components-Objects referenziert werden, andernfalls haben sie keinerlei Effekt auf die API. Wer Tooling verwendet, das solche inline Referenzen nicht unterstützt, kann auf eine dereferenzierte Version zurückgreifen.

Momentan befindet sich die Description in der Beta-Phase – eine zwölf Jahre alte API zu beschreiben, sei keine einfache Aufgabe, schreiben die Autoren des zugehörigen Blogposts. Erstellt wurde die Description über die Verwendung einer Mischung aus JSON-Schemata, dokumentierter Beispiele und Contract-Testing. Bei GitHub wird im Moment aktiv daran entwickelt, in Zukunft soll das Projekt zentraler Bestandteil der GitHub-Developer-Experience werden – sowohl in- als auch extern.

Für GitHub Enterprise Server sowie GitHub Private Instances sollen vierteljährlich Releases der Description verfügbar sein, häufigere Updates soll es über github.com geben, so der zugehörige Blogpost. Wer sich an dem Open-Source-Projekt beteiligen möchte, ist natürlich herzlich willkommen, alle Infos dazu findet ihr im Contribution-Guide der Description.

Mehr zum Thema:

• GitHub erweitert den Funktionsumfang für kostenlose Profile
• Neuigkeiten aus der Arktis: GitHub vermeldet erfolgreiche Archivierung von Open-Source-Code
• Das sind die spannendsten Neuerungen der GitHub Satellite