Die Bedeutung von API-Dokumentation

Damit APIs wie vorgesehen verwendet werden, muss der Kunde oder Verbraucher eine API schnell implementieren und verstehen können. Leider erschweren viele APIs die Implementierung und verfehlen damit ihren eigentlichen Zweck. Bei der Erstellung Ihrer API müssen Sie darauf achten, dass Sie eine informative API-Dokumentation bereitstellen. Diese muss Ihren Entwicklern dabei helfen, Verbindungen zu integrieren und eventuelle Fehler zu beheben. Außerdem ist es wichtig, dass relevante Daten zurückgesendet werden, wenn ein Benutzer einen Aufruf tätigt – insbesondere bei fehlgeschlagenen Aufrufen.

Eine gut formatierte, kohärente Antwort in Ihrer API-Dokumentation ist äußerst wichtig. (Sie sollte einfach zu deserialisieren, iterieren und verstehen sein.) Darüber hinaus sollten Sie Entwicklern Schnellübersichten, einschließlich Statuscodes, über den Verlauf des Aufrufs bereitstellen. Bei Fehlern sollten Sie beschreibende Fehlermeldungen bereitstellen, die nicht nur auf den Fehler hinweisen, sondern auch Anleitungen für die Fehlerbehebung enthalten.

Sie sollten bereits bei der Planung Ihrer API wissen, wie Sie die Dokumentation Ihrer API pflegen werden. Unterschätzen Sie diesen Aspekt nicht: Er ist nachweislich ausschlaggebend für die Benutzerfreundlichkeit der meisten öffentlichen APIs. Auf den ersten Blick mag Dokumentation wie eine schnelle und einfache Aufgabe erscheinen. Die meisten Unternehmen halten sie jedoch für eine der größten Herausforderungen und Hindernisse bei der Wartung ihrer APIs.

Dokumentation ist einer der ausschlaggebenden Faktoren für den Erfolg einer API. Mit einer aussagekräftigen, einfach verständlichen Dokumentation wird die API-Implementierung zum Kinderspiel. Eine verwirrende, nicht synchrone, unvollständige oder komplizierte Dokumentation dagegen kann die Aufgabe so sehr erschweren, dass Entwickler vor lauter Frust zu Lösungen von Wettbewerbern abwandern.

Die Herausforderung liegt darin, dass Ihre Dokumentation nicht nur konsistent aufgebaut, sondern auch mit den Funktionen Ihrer API konsistent sein und stets die aktuellen Änderungen widerspiegeln muss. Darüber hinaus sollte Ihre Dokumentation leicht verständlich und für Entwickler geschrieben sein (in der Regel von einem erfahrenen Dokumentationsteam). Bis vor Kurzem umfassten Lösungen für Dokumentation kostspielige Drittanbietersysteme, die Verwendung des vorhandenen CMS (Content Management System) oder sogar ein auf einer Open-Source-Software wie zum Beispiel Drupal oder WordPress basierendes dediziertes CMS. Teure spezielle API-Dokumentationslösungen können für Konsistenz beim Look and Feel Ihrer API sorgen – und dies ist mit einem CMS schwieriger. Die Synchronisierung muss jedoch manuell von einem Entwickler (falls vom Code abgeleitet) oder einem Dokumentationsteam durchgeführt werden.

Dank der Erweiterung offener Spezifikationen wie zum Beispiel RAML und der damit verbundenen Communities ist Dokumentation mittlerweile sehr viel einfacher. Anstatt zu versuchen, Codekommentare zu parsen und Inline-Beschreibungen von (in der Regel) Entwicklern schreiben zu lassen, kann das Dokumentationsteam in der API-Spezifikation beschreibende Dokumentation bereitstellen, wobei alle Code-Parameter/-Beispiele bereits enthalten sind. Das macht die Dokumentationserstellung deutlich leichter. Immer mehr Unternehmen bieten API-Dokumentation als SaaS (Software as a Service) an und verwenden und erweitern diese Spezifikationen. Dadurch wird die Erstellung eines effektiven API-Portals und effektiver API-Dokumentation einfacher und kostengünstiger als je zuvor.

Gute Dokumentation sollte als Referenz und als Informationsquelle dienen, sodass Entwickler schnell und auf einen Blick die notwendigen Informationen finden. Darüber hinaus sollten Entwickler beim Durchlesen der Dokumentation herausfinden, wie sie die jeweilige Ressource/Methode integrieren.

Gute Dokumentation sollte nicht nur klar und präzise, sondern auch visuell sein und Folgendes enthalten:

• Eine klare Erklärung des Zwecks der Methode/Ressource
• Hervorhebungen wichtiger Informationen für Entwickler, einschließlich Warnungen und Fehlermeldungen
• Einen Beispielaufruf mit dem entsprechenden Medientyp-Body
• Eine Liste der für diese Ressource/Methode verwendeten Parameter sowie deren Typen, Sonderformatierungen, Regeln und Angaben dazu, ob sie erforderlich sind
• Eine Beispielantwort, einschließlich Medientyp-Body
• Codebeispiele für mehrere Programmiersprachen, einschließlich des gesamten notwendigen Codes
• (zum Beispiel Curl bei PHP sowie Beispiele für Java, .Net, Ruby usw.)
• SDK-Beispiele (wenn SDKs bereitgestellt werden), die den Zugriff auf die Ressource/Methode mit dem SDK für ihre Programmiersprache illustrieren
• Interaktive Erfahrungen, um API-Aufrufe auszuprobieren/zu testen (API Console, API Notebook)
• Häufig gestellte Fragen/Szenarien mit Codebeispielen
• Links zu zusätzlichen Ressourcen (andere Beispiele, Blogs usw.)
• Einen Kommentarbereich, in dem Benutzer Code austauschen und über Code diskutieren können
• Andere Support-Ressourcen (Foren, Kontaktformulare usw.)

Einer der Hauptvorteile spezifikationsgesteuerter Entwicklung besteht darin, dass es für Spezifikationen wie RAML, Swagger und API Blueprint solide Open-Source-Communities gibt, die vorkonfigurierte Dokumentationstools zur Verfügung stellen. So sind Sie nicht auf teure und komplexe Anbieter angewiesen und müssen keine Ad-hoc-API-Dokumentationslösung in einem CMS wie WordPress oder Drupal entwickeln. Für jede Spezifikation gibt es spezifische Tools, doch an dieser Stelle beschränken wir uns auf die von der RAML-Community bereitgestellten Tools. Die RAML-Community hat bereits Parser für mehrere verschiedene Programmiersprachen wie zum Beispiel Java, Ruby, PHP und Node sowie vollständige Skripte zur Verwaltung der API-Dokumentation zusammengestellt und bietet interaktive Umgebungen wie API Console und API Notebook. Diese Tools helfen Ihnen dabei, Dokumentationen bereitzustellen, wie in den obigen Beispielen für ReadMe.io, Constant Contact und Twilio zu sehen. Sie müssen dazu lediglich die Installation durchführen und Ihre RAML definieren. Hier stehen einige Tools zum kostenlosen Download zur Verfügung.

Unternehmen erkennen  den steigenden Wert von APIs und entwickeln Hunderte von APIs. Die Fähigkeit, APIs so zu veröffentlichen, dass der verbrauchende Entwickler sie einfach finden, recherchieren und verstehen kann, entscheidet über den Erfolg Ihres gesamten API-Programms. Gute Dokumentation spielt hierbei eine wichtige Rolle.