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:
Vereinbarungen und Spielregeln
Darüber hinaus gibt es auch noch weitere organisatorische Aspekte mit hoher Relevanz, die in der Dokumentation einer API geregelt werden.
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:
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.