In den vergangenen Wochen bin ich aus unterschiedlichen Richtungen immer wieder auf dieselbe Frage zurückgekommen. Kann eine moderne HTTP-API bereits Legacy sein? Ist eine HTTP-Schnittstelle wirklich die richtige Grenze für ein API-Produkt? Definiert ein Bounded Context die API um sich herum? Ist Design First dasselbe wie zuerst das OpenAPI-Dokument zu schreiben? Und was passiert mit Developer Portals, wenn der Consumer nicht mehr zwangsläufig ein Entwickler ist? Aus diesen Fragen sind sechs separate LinkedIn-Artikel entstanden.

Zunächst wirkten sie wie unterschiedliche API-Themen. Betrachtet man sie jedoch gemeinsam, wird ein wiederkehrendes Muster sichtbar. Wir erwarten von der API, zu viele Grenzen gleichzeitig abzubilden.

Eine HTTP-Schnittstelle beschreibt, wie Systeme miteinander interagieren. Ein Domänenmodell gibt Konzepten innerhalb eines bestimmten Kontexts Bedeutung. Ein Produkt schafft Wert für einen Consumer. Eine API-Beschreibung formalisiert Teile einer Schnittstelle. Ein Deployment ergänzt Laufzeitinformationen. Ein Portal stellt eine Interaktionsoberfläche bereit. All diese Dinge hängen zusammen. Sie sind jedoch nicht dasselbe. Und die Probleme beginnen, wenn wir so handeln, als wären sie es.

Wenn eine moderne API zu Legacy wird

Besonders deutlich wurde das beim Nachdenken über Legacy. Üblicherweise verbinden wir Legacy mit Technologie: alten Plattformen, alten Protokollen, alten Programmiersprachen. Eine API muss jedoch technisch nicht alt sein, um schwer veränderbar zu werden. Sie kann auf einer aktuellen Plattform laufen, HTTP bereitstellen und über eine vollständig gültige OpenAPI-Beschreibung verfügen, während die Organisation nach und nach das Wissen über ihren Kontext verliert. Warum existiert diese API? Wer nutzt sie? Welche Business Capability unterstützt sie? Welche Entscheidungen haben ihren Vertrag geprägt? Was hängt von einem Verhalten ab, das niemand mehr anfassen möchte? Die Schnittstelle allein kann uns diese Fragen nicht beantworten.

So betrachtet geht es bei Legacy nicht nur um alternde Technologie. Legacy kann auch entstehen, wenn der Abstand zwischen einem System und unserem Verständnis davon immer größer wird. Dieser Gedanke führt direkt zu einem weiteren Grenzproblem.

Eine HTTP-API ist nicht automatisch ein API-Produkt

Sobald wir APIs als Produkte betrachten, liegt es nahe, die Produktgrenze um die technische API zu ziehen. Produkte werden jedoch nicht durch Controller, Endpunkte oder Deployment-Einheiten definiert. Sie werden über Consumer, Probleme und Wert definiert. Ein API-Produkt kann mehrere technische APIs erfordern. Dieselbe technische API kann Bestandteil unterschiedlicher Produkte oder Journeys sein.

HTTP bleibt eine wichtige Schnittstellengrenze. Es beantwortet lediglich eine andere Frage. Es beschreibt, wie Interaktion stattfindet. Es sagt uns nicht, wo ein Produkt beginnt und endet. Dieselbe Vorsicht ist geboten, wenn Domain Modelling ins Spiel kommt.

Ein Bounded Context ist keine API-Vorlage

Domain-Driven Design bietet uns leistungsfähige Werkzeuge, um Modellierungsgrenzen zu definieren. Ein Bounded Context zeigt, innerhalb welcher Grenze ein Modell, eine Terminologie und ein Regelwerk sinnvoll und konsistent bleiben. Das kann für API-Design und Ownership äußerst hilfreich sein. Daraus folgt jedoch nicht, dass jeder Bounded Context genau eine API bereitstellen sollte oder dass sein internes Modell zum externen Vertrag werden muss. Consumer überschreiten diese Grenze mit ihrem eigenen Kontext. Ihre Aufgaben, ihre Terminologie und ihre Erwartungen können sich von denen des Providers unterscheiden. Domänengrenzen können API-Grenzen daher beeinflussen, ohne sie vollständig festzulegen. Diese Unterscheidung wird wichtig, noch bevor die erste Zeile OpenAPI geschrieben wird.

Design First beginnt vor der Spezifikation

Specification First ist nützlich. Eine OpenAPI-Beschreibung vor der Implementierung zu erstellen, ermöglicht Review, Mocking, Contract Testing, parallele Entwicklung und Automatisierung. Dennoch ist es möglich, die Spezifikation zuerst zu schreiben und trotzdem die falsche API zu entwerfen. Die Fragen, die am Anfang zählen, sind andere.

Wer ist der Consumer? Was möchte er erreichen? Welche Capability soll bereitgestellt werden? Welche Interaktionen gehören zusammen? Wie fügt sich die API in Produkte und Schnittstellen ein, die bereits in der Landschaft vorhanden sind?

Erst danach wird die Formalisierung wirklich sinnvoll. Eine aussagekräftigere Reihenfolge lautet daher:

Design → Vertrag → Code

Die Spezifikation bildet Entscheidungen ab, die während des Designs getroffen wurden. Sie sollte nicht mit dem Designprozess selbst verwechselt werden. Und selbst dieser Vertrag enthält nicht zwangsläufig alles, was wir später über die API wissen müssen.

Kontext entsteht im Laufe der Zeit

Eine API-Beschreibung entsteht zu einem bestimmten Zeitpunkt im Lebenszyklus, doch die API sammelt danach weiteren Kontext. Deployment-Umgebungen werden bekannt. Runtime-Endpunkte entstehen. Consumer beginnen, sich auf bestimmtes Verhalten zu verlassen. Ownership kann sich verändern. Operative Informationen werden verfügbar. Nicht all das gehört in die ursprüngliche Beschreibung. OpenAPI Overlays sind in diesem Zusammenhang interessant, weil sie einen Mechanismus bieten, zusätzliche Informationen anzuwenden, ohne die ursprüngliche OpenAPI-Beschreibung zum Container für jedes Lifecycle-Thema machen zu müssen. Die entscheidende Idee geht jedoch über Overlays hinaus. Informationen sollten in die Landschaft einfließen, sobald sie maßgeblich und verlässlich sind. Der Versuch, ein einziges Artefakt gleichzeitig für Design, Deployment, Governance, Betrieb und Produktkontext stehen zu lassen, macht dieses Artefakt letztlich weniger präzise statt vollständiger. Agents machen dieses Problem noch deutlicher sichtbar.

Ein Portal ist nur eine Sicht auf eine API-Landschaft

Developer Portals wurden größtenteils für eine menschliche Journey entwickelt. Ein Entwickler sucht nach einer API, liest ihre Dokumentation, beantragt Zugriff, erhält Zugangsdaten und beginnt mit der Integration. Ein Agent bringt ein anderes Interaktionsmodell mit sich. Er muss möglicherweise eine Capability identifizieren, verstehen, wie diese Capability aufgerufen werden kann, feststellen, ob er zur Ausführung einer Aktion berechtigt ist, und die Aktion anschließend ausführen.

Das kann MCP, Tool-Definitionen, Registries oder andere Mechanismen umfassen. Ein einheitliches Discovery-Modell für Agents zeichnet sich bislang nicht ab. Eines wird jedoch bereits klar: Von einem Agent zu erwarten, dass er dieselbe Informationsarchitektur navigiert, die wir für menschliche Entwickler geschaffen haben, dürfte nicht ausreichen. Die Informationen unterhalb des Portals werden wichtiger als das Portal selbst. Capabilities, Verträge, Einschränkungen, Ownership, Autorisierung und Beziehungen müssen maschinenlesbar und miteinander verknüpft werden. Und genau hier beginnen die sechs einzelnen Beobachtungen zusammenzulaufen.

Von APIs zu API-Landschaften

In unserem früheren TechRadar-Beitrag „API-Landschaften verstehen, nicht nur verwalten“ haben wir argumentiert, dass ein API-Inventar noch keine API-Landschaft ist. Zu wissen, dass eine API existiert, ist nützlich. Zu verstehen, wie sie mit Produkten, Consumern, Capabilities, Teams, Systemen und Runtime-Abhängigkeiten zusammenhängt, ist etwas anderes. Die Fragen aus den sechs LinkedIn-Artikeln zeigen, warum diese Unterscheidung wichtig ist. Wenn die technische API nicht zwangsläufig die Produktgrenze darstellt, wenn ein Bounded Context den externen Vertrag nicht automatisch definiert, wenn Design vor der Spezifikation beginnt, wenn Deployment-Kontext erst später entsteht und wenn unterschiedliche Consumer unterschiedliche Wege benötigen, um Capabilities zu entdecken, dann kann kein einzelnes API-Artefakt das vollständige Bild abbilden. Und das sollte es auch nicht.

OpenAPI sollte weiterhin gut darin sein, Schnittstellen zu beschreiben. API Management sollte weiterhin gut darin sein, Runtime-Exposition und Policies zu verwalten. Developer Portals sollten weiterhin gut darin sein, menschliche Consumer zu unterstützen. Enterprise Architecture sollte weiterhin gut darin sein, Capabilities, Anwendungen und organisatorischen Kontext zu modellieren. Was fehlt, ist kein weiteres Master-Artefakt, das all diese Dinge ersetzt. Es ist das Wissen, das sie miteinander verbindet.

Welche API unterstützt welche Capability? Welches Produkt stellt sie bereit? Welche Consumer sind von ihr abhängig? Welcher Domänenkontext verleiht ihren Konzepten Bedeutung? Welches Team ist verantwortlich? Welches Deployment implementiert sie? Was verändert sich, wenn sich eine dieser Beziehungen ändert? Genau das ist Wissen über die API-Landschaft. Deshalb werden auch graphbasierte Ansätze interessant. Nicht weil eine Graphdatenbank Architekturprobleme auf magische Weise löst, sondern weil Beziehungen explizit werden, statt über Dokumente, Repositories und Plattformen verstreut zu bleiben. Eine API ist dann nicht mehr nur ein Endpunkt, eine Spezifikation oder ein Katalogeintrag. Sie wird Teil einer beobachtbaren Landschaft.

Die sechs LinkedIn-Artikel begannen mit unterschiedlichen API-Fragen. Sie enden am selben Punkt:

Die API selbst ist nicht die Grenze des Wissens, das wir benötigen, um sie zu verstehen.