Die vielfältigen Bestandteile API-basierter Produkte

Denken wir als IT-Experten an APIs und API-Produkte, kommen uns oft die technischen APIs der Umgebungen und Systeme in den Sinn, mit denen wir viel Erfahrung gesammelt haben. Damit sich eine technische API zu einem wertvollen Produkt entwickeln kann, braucht es aber die Ergänzung um gänzlich andere Bestandteile.

Technische Webservices

Eine API besteht natürlich aus einem technischen System, das eine Geschäftsfähigkeit kapselt und zum Beispiel über REST, SOAP oder andere technische Schnittstellen zugänglich macht. Aber auch asynchrone Protokolle, wie z.B. Websockets oder PubSub Protokolle wie Kafka gehören dazu. Auch diese haben logischerweise API-Charakter. Dieser Teil unserer API wird auch (Web)Service genannt.

API Design – Dokumentation und Spezifikation

Zusätzlich zu diesem technischen Teil des Systems benötigen wir in der Regel auch einen Beipackzettel für die Partner und Kollegen, die sich mit diesem technischen Dienst integrieren wollen. In dieser sogenannten API-Dokumentation bzw. dem API Design Dokument wird Folgendes beschrieben:

Auflistung der möglichen Operationen
Beschreibung von Taxonomien und Datenmodellen
Erklärung der fachlichen Auswirkungen der Operationen
Technische Spezifikation des Zugriffs (z.B. inkl. Zugriffskonzept)

Vereinbarungen und Spielregeln

Darüber hinaus gibt es auch noch weitere organisatorische Aspekte mit hoher Relevanz, die in der Dokumentation einer API geregelt werden.

Wer sind die Ansprechpartner hinter dieser API?
Wie kann ich mit diesen bei aufkommenden Fragen und Problemen in Kontakt treten?
Welche Vereinbarungen und Zusicherungen seitens des API Providers gelten bei der Verwendung, wie z.B. Limits, Mengengerüste, SLAs und Verfügbarkeiten beim Zugriff, aber auch ggf. Haftungsfragen in Problemsituationen?

Standardisierung der Interaktion mit Hilfe des API Lifecycles

Wie aber kommuniziert der Anbieter einer API mit seinen Konsumenten? Hierfür hat sich ein Interaktionsmodell herauskristallisiert - der sogenannte API Lifecycle. Der API Lifecycle liefert standardisierte Antworten auf folgende Fragestellungen:

Wie lange kann ich versichern, dass eine API-Version nutzbar ist?
Wie veröffentliche ich Fehlerbehebungen oder zusätzliche Features, ohne die laufende Interaktion mit Konsumenten zu stören?
Wie verhält sich ein API Provider Team im Falle von „Breaking Changes“ (=Änderungen der geltenden technischen/organisatorischen Vereinbarungen)?

Also zusammengefasst sind APIs ein Interaktionsmodell, das sogenannten soziotechnischen Systemen (Wertschöpfung bestehend aus dem Zusammenspiel von Mensch und Technik) erlaubt, ihre Zusammenarbeit zu standardisieren, ohne dabei die Unabhängigkeit/Agilität beider Parteien negativ zu beinträchtigen. APIs bieten bei richtiger Anwendung die Möglichkeit, widerstandsfähige und stabile Integrationen zu ermöglichen.

Tipp für den Einstieg: Gutes Design für den langfristigen Erfolg von API-Produkten

Was vermeintlich einfach klingt, ist in der Praxis die erste große Herausforderung. Ein geschickt gestaltetes und inhaltlich vollständiges API Design reduziert die Einstiegshürden und damit auch die Entwicklungskosten auf Seiten der API Konsumenten. Aber nicht nur auf Seiten der API Konsumenten bringt es Vorteile, sich hier auf Erfahrungswerte und Best-Practices zu stützen. Ein guter, fachlich versierter Schnitt der APIs, aber auch die Wahl der richtigen Design-Patterns, reduziert die Wahrscheinlichkeit von Breaking Changes und damit auch die Kommunikationsaufwände beim API-Anbieter.