So dokumentiert man seine Rest API richtig

Als Entwickler erfreut man sich über eine gute API-Dokumentation. Doch leider sind Rest-APIs in den wenigstens Fällen gut dokumentiert. Oft fehlen Beispiele, Parameter, Statuscodes ändern sich oder die Paths sind einfach falsch. Dann googelt man nach einer Lösung oder muss mit dem Support in Kontakt treten, was die Nutzererfahrung verschlechtert.

Mit diesen Formaten, Tools und Lösungen gelingt die Rest-API-Dokumentation, damit sich auch deine Benutzer an einer guten Dokumentation erfreuen können.

Vorteile einer gut dokumentierten API

Eine gute API-Dokumentation bringt verschiedene Vorteile mit sich. Diese zu verstehen, rechtfertigt den Aufwand bei der Erstellung und Instandhaltung dieser Dokumentation. Denn die API-Dokumentation ist ein stetiger Prozess. Bei der Entwicklung ändern sich schnell Parameter, Statuscodes, Paths oder sogar Methoden und das sollte man dann direkt in die Dokumentation übernehmen. Die Vorteile einer gut dokumentierten Rest API:

Verständlichkeit bei der Entwicklung: Mit einer klaren Dokumentation erleichtert man sich selbst, aber auch dem eigenen Team die zukünftige Entwicklung an der API.

Verwendung durch andere Nutzer: Mit einer guten API-Dokumentation erhöht man die Nutzererfahrung und die Akzeptanz der API bei anderen Entwicklern. Hierdurch verbreiten sich die API und das Produkt besser.

Niedrigere Supportkosten: Durch eine gepflegte API-Dokumentation kann man die Supportkosten verringern. Denn viele Supportanfragen entstehen, wenn es keine API-Dokumentation gibt oder diese veraltet ist.

Einfachere Fehlerbehebung: Eine umfassende API-Dokumentation kann Entwicklern helfen, Fehler in der API schneller zu finden. Denn diese ist ähnlich wie ein Test formuliert. Es werden erwartete Paths, Methoden, StatusCodes und Eingaben angegeben, welche erwartete Responses geben sollten.

Konsistenz der API: Eine gute Dokumentation hilft dabei, eine konsistente Benennung von Endpunkten, Parameter und Datenstrukturen sicherzustellen. Dadurch wird die Konsistenz der API verbessert und die Wahrscheinlichkeit von Fehlern verringert.

Die Erstellung der API Dokumentation

Zum Glück gibt es inzwischen Formate, mit denen die Erstellung einer API-Dokumentation leicht von der Hand geht. Am Markt sind mehrere Formen der API-Dokumentation. Doch haben sich zwei ganz besonders durchgesetzt.

Das liegt vermutlich an der Benutzerfreundlichkeit dieser und der Akzeptanz am Markt. Sie sind leicht in den Alltag des Entwicklers einzubauen. Es gibt inzwischen ein immer größeres Ökosystem um die Formate. Es werden Tools angeboten, welche die Arbeit der Dokumentation weiterhin vereinfachen.

Swagger - OpenAPI

OpenAPI oder früher auch Swagger. Ist ein Dateiformat zur Spezifikation von API Schnittstellen. Diese Spezifikationen werden in YAML oder JSON geschrieben. In der Spezifikation werden Authentication, Endpunkte, Parameter, URLs und Datenstrukturen festgehalten.

Die OpenAPI-Spezifikation kann dann für verschiedene Imports oder Generatoren verwendet werden. So kann man sie direkt in Webseiten mit der Dokumentation oder als Client-Library in eine bestimmte Programmiersprache umwandeln.

OpenAPI ist vermutlich das verbreitetste Format zur Erstellung von API-Dokumentationen. Das liegt an der Kompatibilität. Denn in OpenAPI wird alles für die API definiert und von dort aus kann man in die anderen Formate umwandeln.

Swagger selbst bietet einen webbasierten Editor zur Erstellung und Bearbeitung von OpenAPI und Swagger Dateien. Diese können dann zwischen YAML und JSON konvertiert werden. Es wird eine HTML zur Vorschau generiert und man erkennt Fehler direkt durch Markierungen im Text.

Postman - Postman Collection

Postman ist bei den Entwicklern als Software zum Testen von API Schnittstellen bekannt. Dabei ist es naheliegend, dass man die Endpunkte direkt in Postman dokumentiert, um sie bei der Entwicklung wieder zu verwenden. Der Vorteil an Postman ist die visuelle Schnittstelle. Man kann die API-Requests visuell zusammenstellen und hat dafür eine geeignete und bekannte Oberfläche.

In Postman kann man dann direkt Collections anlegen. Das sind Gruppen von API-Calls, welche noch in Ordner unterteilt werden können. Diese können Datenmodelle und Variablen miteinander teilen.

Da viele Entwickler Postman verwenden, um bei der Entwicklung die Schnittstelle zu testen, ist die Software sowieso im Alltag gebräuchlich. Hierdurch fällt es einfacher, die API-Calls einfach in Collections zu verpacken.

Diese Collections können dann exportiert und geteilt werden. Es ist möglich, OpenAPI-Dateien in Postman zu importieren. Diese werden dann automatisch in eine Collection umgewandelt.

Diese Tools helfen bei der API-Dokumentation

Die folgenden Tools spielen in das Ökosystem um Swagger und Postman mit hinzu und erleichtern die Erstellung oder Verwendung dieser Formate im Entwickler Alltag.

Swagger Editor: Ein webbasierter Editor zu Erstellung und Bearbeitung von Swagger und OpenAPI-Spezifikationen im YAML und Json Format.

Redoc: Ein Opensource-Tool, um Dokumentations-Webseiten aus OpenAPI-Spezifikationen zu generieren. Dabei bietet es eine klare Struktur der Seite, die man schon von anderen API Dokumentation kennt. Ein Beispiel gibt es hier.

DocGen: Ein Tool, zur Erstellung einer Dokumentations-Seite in HTML aus einer Postman Collection.

ReadMe: Eine Platform, die interaktive Dokumentation der APIs anbietet und Nutzern hilft die API schneller zu adaptieren.

Außer den genannten Tools gibt es weitere Werkzeuge, die das Arbeiten mit den API-Formaten erleichtern. Erstrecht Code-Generatoren, welche Libraries für Clients und Server aus OpenAPI-Dateien erstellen können, sind beliebt.

Beispiele für gute API Dokumentation

Zum Schluss schauen wir uns noch ein paar gute API Dokumentationen an, um Inspiration für unsere Dokumentation zu bekommen. Außerdem werden wir immer zeigen, weshalb diese Dokumentationen gut sind und welche Tools verwendet wurden.

Stripe:

Stripe bietet die Infrastruktur Zahlungen im Internet entgegen zu nehmen. Dabei zählt es darauf, dass die API von Stripe in andere Software eingebunden wird. Daher ist es für Stripe naheliegend, dass sie eine gute API-Dokumentation bereitstellen.

Stripe bietet verschiedene APIs an, welche jeweils sehr umfassend sind. Darüber hinaus gibt es Clients in vielen Programmiersprachen und Beispiele zur Verwendung.

Stripe verwendet OpenAPI, welche in diesem Github Repository öffentlich verfügbar ist.

Twillio:

Twilio ist eine Cloud-basierter Anbieter für Kommunikations-Plattformen. Sie ermöglichen, versenden von SMS, MMS, Sprach- und Video-Anrufen und mehr per API-Schnittstelle. Also wieder ein Produkt, welches eine Schnittstelle zwischen zwei Welten erschließt und dabei von der Adaption der Nutzer lebt.

Sie bieten auf ihrer API-Webseite ausführliche Dokumentation zu allen Schnittstellen, die sie anbieten und erleichtern mit Beispielen die Integration dieser in weitere Anwendungen.

Twilio bietet hier ein öffentliches Github Repository mit der OpenAPI-Spezifikation an.

GitHub:

GitHub ist eine Software zur Versionsverwaltung und Zusammenarbeit an Softwareprojekten. Dabei sind Entwickler ihre Hauptzielgruppe. Die Nutzer sollen das Produkt lieben. Das erzielen sie durch eine gute Nutzerfreundlichkeit der Plattform und leichte Erweiterbarkeit durch APIs. Die API-Dokumentationen sind gut geschrieben und leicht verständlich.

Auch Github hat ein öffentliches Github Repository mit der OpenAPI-Spezifikation.

OpenAI:

OpenAI ist ein Forschungs- und Entwicklungsunternehmen, welches Lösungen im Bereich der Künstlichen Intelligenz bereitstellt. Mit Lösungen wie den GPT-Modellen, DALL-E oder Whiper bieten sie LLMS, Bildgenerierung und Text to Speech.

API bietet selbst grafische Schnittstelle, um mit den Lösungen zu interagieren. Jedoch liegt ein großes Geschäft auf den APIs. Und mit ihnen können Entwickler Anwendungen um interessante KI-Features erweitern.

Sie bieten eine hervorragende API-Dokumentation. Diese ist übersichtlich, hat ein verständliches Pricing und bietet verschiedene Einstellungen. Dabei verwendet auch Openai OpenAPI zur Spezifikation der API-Schnittstellen. Die Datei findet man in diesem Github Repository.