In 60 % der API-Teams ist Versionierung Teil des Change Managements. Nur 26 % nutzen semantische Versionierung, so eine Sekundäranalyse der Postman-Umfrage „State of the API“ 2025. Diese Lücke ist aufschlussreich: Die meisten Organisationen haben akzeptiert, dass Versionierung wichtig ist, aber weit weniger haben sich darauf verständigt, was eine Version ihren Konsumenten eigentlich mitteilt. Das Ergebnis ist eine Governance-Landschaft, die auf der Folie vollständig aussieht und an einem Dienstag im November in sich zusammenfällt, wenn eine Partnerintegration ausfällt, weil niemand sagen konnte, ob v2.3 abwärtskompatibel war oder nicht.
Diese Spannung wächst stetig. Governance ohne Klarheit ist bloßer Mehraufwand. Und in Unternehmen mit mehreren Gateways (31 % der Organisationen, laut derselben Postman-Analyse) vervielfachen uneinheitliche Versionierungsschemata diesen Mehraufwand über jedes Team, jeden Konsumenten und jede Deployment-Pipeline hinweg.
Die API-Design-Richtlinien von Microsoft verstehen APIs als langlebige Verträge: abwärtskompatible, additive Änderungen bevorzugen und eine neue Version nur dann einführen, wenn sich ein Breaking Change nicht vermeiden lässt. Das klingt selbstverständlich. In der Praxis verlangt es etwas, das die meisten Organisationen auslassen: eine schriftliche, durchsetzbare Definition dessen, was in Ihrem Kontext als Breaking Change gilt.
Ein zusätzliches Feld in der Response-Payload gilt in der Regel als abwärtskompatibel. Reale Clients mit striktem Parsing oder fest verdrahteten Schema-Annahmen können trotzdem daran scheitern. Kompatibilität sollte an repräsentativen Konsumenten geprüft werden, statt sie allein aus Überlegungen auf Ebene der Spezifikation abzuleiten. Die Architekturfrage lautet hier nicht: „Haben wir die Versionsnummer erhöht?“ Sie lautet: „Verstehen die Konsumenten dieser API, was diese Änderung für ihren Code bedeutet?“
Jede unterstützte Version vervielfacht den Test- und Betriebsaufwand. Das ist keine theoretische Sorge, sondern ein Posten im Budget. Wenn Ihre Teams keine expliziten Kriterien dafür haben, wann eine neue Version entsteht und wann die bestehende weiterentwickelt wird, wird Versionswildwuchs zu einer versteckten Steuer, die Quartal für Quartal weiter anwächst. Und niemand bemerkt es, bis der Supportaufwand anfängt, die Lieferkapazität aufzuzehren.
Zu viele Teams behandeln Deprecation, also die Abkündigung einer API oder einer Version, als Fußnote in der Dokumentation. Ein „Deprecated“-Badge im Entwicklerportal, vielleicht eine Slack-Nachricht. Das ist keine Deprecation. Das ist die Hoffnung, dass sich das Problem von selbst erledigt.
Wirksame Deprecation ist, wie es die Leitlinien des Azure Architecture Center von Microsoft beschreiben, ein definierter Migrationsprozess: ein Ersatzpfad, Kanäle für Ankündigungen, ein Supportzeitraum, eine Migrationsanleitung und ein Monitoring der Nutzung. Dabei macht es einen Unterschied, ob eine API intern oder öffentlich ist. Interne APIs mit bekannten Konsumenten lassen sich schneller abstimmen; öffentliche APIs brauchen unter Umständen längere Übergangsphasen, weil Sie nicht sehen, wer sie aufruft und wie eng die Aufrufer an sie gekoppelt sind.
Die operative Frage, die reife API-Programme von denen trennt, die es erst werden wollen: Können Sie mir auf Anhieb sagen, welche Konsumenten einen abgekündigten Endpunkt noch aufrufen und wie viel Traffic darüber läuft? Wenn nicht, ist Ihre Deprecation-Policy Fiktion. Was Sie nicht messen können, können Sie nicht stilllegen.
Laut dem „Connectivity Benchmark Report“ 2025 von MuleSoft, wie Sama Integrations ihn zusammenfasst, ging reife Governance mit um 47 % kürzeren Laufzeiten von Integrationsprojekten einher. Diese Zahl verdient eine kritische Prüfung (ein Zusammenhang ist noch keine Kausalität), aber die Richtung ist glaubwürdig: Teams, die wissen, was gilt, was abgekündigt und was stillgelegt ist, verbringen weniger Zeit mit Archäologie und mehr mit der Auslieferung.
Das Governance-Modell, das wirklich skaliert, ist kein Review-Board. Es ist Code.
Policy-as-Code für APIs bedeutet, Ihre Standards als ausführbare Regeln zu formulieren, typischerweise als OpenAPI-Regelsätze (Rulesets), und sie automatisch in der CI/CD-Pipeline laufen zu lassen. Das am häufigsten genannte Tool dafür ist Spectral: Sie definieren Regeln für Namenskonventionen, Pflicht-Metadaten, Sicherheitsanforderungen und die Struktur der Responses. Die Pipeline prüft jede Vertragsänderung gegen diese Regeln, bevor irgendetwas die Staging-Umgebung erreicht. Kein Meeting nötig.
Ein Beitrag von The Weekly Interface bringt es schon im Titel auf den Punkt: „Linters are where API governance becomes real“. Erst im Linter wird API-Governance Wirklichkeit. Ein Styleguide im Wiki ist eine Empfehlung. Ein Spectral-Regelsatz, der bei jedem Pull Request läuft, ist Durchsetzung. Der Unterschied zwischen beiden ist der Unterschied zwischen Governance als Anspruch und Governance als gelebter Betriebsrealität.
Ein berechtigter Einwand bleibt allerdings. Strenge Governance-Gates, die als späte Freigaben umgesetzt werden, bremsen die Auslieferung. Der Sinn von Policy-as-Code ist, Prüfungen nach vorn zu verlagern (Shift Left), in den Workflow der Entwickler, wo die Behebung eines Verstoßes Minuten statt Tage kostet. Und der Regelsatz braucht einen Weg für begründete Ausnahmen. Nicht jede Regel passt auf jede API. Starre Durchsetzung ohne Ventil erzeugt genau den Engpass, den Governance eigentlich verhindern sollte.
Stripe bietet einen nützlichen Bezugspunkt. Der Engineering-Blog des Unternehmens beschreibt, wie API-Änderungen in die Entwicklerprodukte einfließen: über definierte Prozesse, wobei SDK-Migrationsleitfäden als Teil der Versionswechsel veröffentlicht werden. Das ist operationalisierte Governance: kein Policy-Dokument, sondern eine Reihe von Artefakten und Workflows, die Änderungen für die Konsumenten vorhersehbar machen.
Governance-Diskussionen drehen sich meist um Versionierung und Deprecation. Verständlich, denn dort gehen Dinge kaputt. Doch es gibt ein leiseres Problem, das alles andere untergräbt: 34 % der API-Fachleute geben an, vorhandene APIs in der eigenen Organisation nicht zu finden, und 55 % kämpfen mit uneinheitlicher Dokumentation, so die Analyse der Postman-Umfrage durch Conversational Geek Stats.
Wenn Teams nicht finden, was schon existiert, bauen sie Duplikate. Doppelte APIs bedeuten doppelten Governance-Aufwand, doppelte Versionierungsentscheidungen, doppelte Zeitpläne für die Deprecation. Die Kosten bestehen nicht nur aus Entwicklungsstunden, sondern aus der sich immer weiter verstärkenden Komplexität einer API-Landschaft, die in die Breite wächst statt in die Höhe. Einheitliche Dokumentationsstandards und ein durchsuchbares Inventar sind keine glamouröse Governance-Arbeit. Sie sind das Fundament, das Versionierungs- und Deprecation-Richtlinien im großen Maßstab überhaupt erst durchsetzbar macht.
In den meisten Unternehmen misst man Governance reflexhaft an der Prozess-Compliance: wie viele APIs das Review bestanden haben, wie viele Ausnahmen beantragt wurden. Das sind Aktivitätskennzahlen. Sie zeigen, dass die Maschine läuft. Sie zeigen nicht, dass sie etwas bewirkt.
Die Kennzahlen, auf die es ankommt: weniger Breaking Changes, die bis in den Produktivbetrieb gelangen, schnellere Migrationen der Konsumenten, wenn sich Versionen doch ändern, weniger Nacharbeit durch unentdeckte APIs oder undokumentierte Verträge. Wenn Ihr Governance-Programm bei diesen Zahlen keine Bewegung zeigen kann, ist es reines Ritual. Und Rituale sind meiner Erfahrung nach das Erste, was Teams umgehen, sobald der Lieferdruck steigt.
Ein schnelleres Chaos bleibt ein Chaos. Aber Governance, die die Auslieferung bremst, ohne Brüche zu verringern, ist schlimmer als gar keine Governance, weil sie die Kosten verursacht, ohne den Nutzen zu bringen. Der Weg führt über Contract-first-Design, eine automatisierte Durchsetzung der Policies und Deprecation als Produktfähigkeit mit echter Migrationsunterstützung und Nutzungsdaten. Diese Kombination skaliert. Review-Boards nicht.
