Stolzieren in der Softwareentwicklung

Ich spreche über API-Dokumentationen

Was ist API?

Die Softwareentwicklung hat sich in den letzten Dekaden massiv geändert. Früher waren Programme autark. Sie liefen eigenständig und konnten alles, was sie für ihre Arbeit benötigten, selbst. Dies hat sich gewandelt, speziell im mobilen Bereich. Daher lege ich in diesem Artikel meinen Fokus auf Web-Applikationen bzw. Webseiten und Smartphone-Apps.

Software in diesem Bereich ist sehr häufig geprägt von einer starken Vernetzung. Man spricht daher von Softwaresystemen. Das altgriechische "systema" bedeutet "aus mehreren Einzelteilen zusammengestztes Ganzes". Die spannende Aufgabe, mit der ich mich oft beschäftige, ist es solche Software-Einzelteile über Schnittstellen zu verbinden und miteinander interagieren zu lassen. Damit dies gelingt, gibt es die Application Programming Interfaces, kurz APIs. Dies Programmschnittstellen sind Befehle und Funktionen, die ein Programmierer nutzen kann, um auf andere Systeme oder Systemteile zuzugreifen.

API-Beispiel

Die Smartphone-App "Wetter" kennt das aktueller Wetter nicht, da sie nicht durch die Kamera des Smartphones das Wetter sehen und deuten kann. Wie gelangt nun das aktuelle Wetter und die Wettervorhersage in das Handy? Richtig. Durch eine bzw. mehrere APIs.

Zunächst kennt die App die API des Smartphone-Betriebssystems und kann die GPS-Position erfragen. Zudem kennt die App auch die API eines Wetterdienstes und kann durch Befehlsaufrufe auf dessen Server und der übermittlung der eigenen Position die aktuellen Wetterdaten abfragen.

Es geht also um Kommunikation

Richtig. Sprechenden Menschen, äh Programmen kann geholfen werden. Die einzelnen Systemteile kommunizieren miteinander, stellen Funktionen zur Verfügung oder rufen diese auf.

Wenn wir Menschen kommunizieren ist es wichtig, dass wir gegenseitig unsere Worte verstehen. Hierzu verwenden wir Sprache mit Grammatik (Regeln) und Worten.

Gleiches gilt auf für Software-Systeme. Daher ist es ungemein hilfreich, wenn ein Softwareentwickler weiß, wie er fremde Systeme bedienen kann.

API-Dokumentation mit Swagger

Als Softwareentwickler bin ich darauf angewiesen zu wissen, wie ich Schnittstellen ansprechen kann. Daher ist eine Verständigung darüber wichtig, wie diese genau Funktioneren, was sie machen und was nicht.

Ich verwende zur Dokumentation solcher APIs die OpenAPI Spezifikation OAS3. Einhergehend damit nutze ich als Entwickler von Web-Applikationen Swagger (aus dem Englischen: prahlen, stolzieren), eine Open-Source-Werkzeugsammlung zum Entwerfen, Dokumentieren und Visualisieren von HTTP-Webservices bzw. REST-APIs.

Die Definition der APIs erstelle ich über einen Text-Editor in einer Formatierung gemäß der OAS3 Spezifikation entweder im JSON- oder YAML-Format. Mittels selbst gehosteten Swagger UI werden dann die API-Dokumentationen für meine Programme für meine Kunden, meine Partner und für mich zur Verfügung. Für einzelne Programme wird also so beschrieben, wie genau die einzelnen Funktionen aufgerufen werden und welche Informationen zurückgeliefert werden.

Beispiel: sipgate API
Ein GET-Aufruf von /history liefert mir bei meinem Telefonanbieter Sipgate nach Authentifizierung alle meine Telefonate und Anrufbeantworter-Nachrichten. Mit dem Parameter from kann ich die Anrufe z.B. eines bestimmten Kunden filtern.

API-Dokumentation in der Praxis

Ich bin der Überzeugung, dass in der professionellen Softwareentwicklung Dokumentation unerlässlich ist. Speziell bei vernetzter Software bieten API-Dokumentationen überhaupt erst eine verlässliche Möglichkeit zu entwickelt. Auch wenn die Definition einer API Zeit benötigt, so ist diese unerlässlich.

In dieser Woche habe für ein Kundenprojekt die oben dargestellte API (Ausschnitt zu sehen) entwickelt und dokumentiert. Hintergrund ist die Anbindung zweier Smartphone-Apps, die Daten aus einem Web-Portal auslesen müssen. Mein externer Partner, der die Smartphone-Apps entwickelt, kann somit ohne große Absprache den Datenaustausch realisieren.

Der Aufwand für die Erstellung der Dokumentation mit ca. 15 Funktionen inkl. aller Beispiele, Fehler-Codes und Daten betrug ca. 2 Tage.

Vorteile:

Keine Absprachen unter den Entwicklern notwendig
exaktes Verhalten der API bestimmt
Programmcode für Handy-Apps und Server kann aus der Dokumentation automatisch generiert werden - WAHNSINN!