APIs zu designen, ist in vielen Softwareprojekten eine erfolgskritische Aktivität. Ihr Gelingen hängt von den Anforderungen, aber auch von der Erfahrung der API-Designer ab. Patternsammlungen dokumentieren kollektive Erfahrungen und ermöglichen es so, schneller und risikoärmer zu passenden Entwürfen zu kommen. Begleiten Sie uns auf einer kleinen Reise durch die Microservices-API-Patterns, die protokollunabhängige Problemstellungen im API-Design betrachten und bewährte Lösungen in kompakter Form vorschlagen.

Typischerweise ruft ein Entwickler erst einmal zahlreiche APIs in der Clientrolle auf, bevor er die Aufgabe bekommt, als API-Designer „die Seiten zu wechseln“, ein API selbst zu entwickeln und anderen zur Verfügung zu stellen. Das geschieht heutzutage eher früher als später, denn aus der aktuellen Softwarepraxis sind Web-APIs und Service-Schnittstellen nicht mehr wegzudenken. Die meisten Systeme, die wir entwickeln, sind verteilt und benötigen daher APIs, um Anwendungsteile, die an verschiedenen Orten gehostet werden (z. B. auch in der Cloud), miteinander kommunizieren zu lassen. Dies gilt sowohl für applikationsinterne APIs (z. B. in einer Microservices-Architektur) als auch für APIs externer Partner (z. B. einen Zahlungs-Service für Onlinshops). APIs verbergen per definitionem Implementierungsdetails vor ihren Aufrufern. Damit erlauben sie das Mocking von Komponenten während des Testens und den Austausch von alternativen Implementierungen ohne unmittelbare Auswirkungen auf die Nutzer. Der Entwicklungs- und Lebenszyklus des Serviceanbieters wird von dem der API-Clients entkoppelt, was Entwicklung, Betrieb und Wartung des Gesamtsystems erheblich flexibilisiert.

Wie bei allen anspruchsvollen Fragestellungen kann man leider auch beim API-Design einiges falsch machen: Verwirrende Datenstrukturen erhöhen den Programmier- und Testaufwand auf der Clientseite; Implementierungsdetails im Schnittstellenvertrag beeinträchtigen die Wartbarkeit; Versprechungen, die ein API (ggf. auch nur implizit) macht, aber nicht implementiert, und fehlende Robustheit enttäuschen die API-Nutzergemeinde.

Die Auswirkungen solcher Fehler können unterschiedlich schwere Konsequenzen nach sich ziehen und reichen von Mehrkosten in der Implementierung über Missverständnisse und Mängel, die erst in Integrationsphasen gefunden werden und ein aufwendiges Redesign erfordern, bis hin zu späteren Produktionsproblemen (Performanz, Skalierbarkeit) mit daraus resultierenden Korrektur-Erfordernissen bis hin zu teuren Architekturänderungen. Je später ein Fehler gefunden wird, desto höher sind oft die Kosten für Fixes.

Daher stellt sich die Frage, wie Fehler im API-Design von vornherein vermieden werden können und wie man effektiv und effizient reagieren kann, wenn trotz aller Bemühungen ein Entwurf doch einmal nicht ganz zu den Anforderungen passt (die sich vielleicht parallel zum Entwurf erst herauskristallisieren).

Die Rolle von Patterns im API-Design

Ein API zu entwickeln ist wie eine Reise. Der erste Halt einer jeden Reise sollte an einem Buchladen (oder im Internet) auf der Suche nach einem Reiseführer sein. Reiseführer enthalten Erfahrungen der Autoren zu Sehenswürdigkeiten und Restaurants. Wir alle lernen aus Erfahrung. Oftmals sind es unsere eigenen Fehler (wie ein schlecht gewähltes Restaurant im Urlaub), die uns langfristig weiterbringen (hier: genauerer Blick auf Karte und Ambiente am nächsten Abend, Erwägen von Alternativen), aber auch gute Lösungen, die sich in unserer Erfahrung bewährt haben, benutzen wir gerne weiter (haben wir nicht alle unser Lieblingsrestaurant?). Natürlich können wir auch beim API-Design von den Erfahrungen anderer profitieren – so wie von denen im Reiseführer.

Eine populäre Art, Erfahrungen aus der Softwareentwicklung zu dokumentieren und für viele nutzbar zu machen, sind Patternbeschreibungen. Ein Pattern ist ein Lösungsmuster für ein bestimmtes wiederkehrendes Problem. Hierbei geht es nicht um Codewiederverwendung, sondern um die Beschreibung konzeptioneller, technikübergreifender Probleme und Lösungen, die nichttriviale, zum Teil widersprüchliche Anforderungen adressieren.

Ein Blick in die Literatur zeigt, dass es bereits Patterns...