APIs abkündigen - von Kill-Switches und Totmannschaltern

Effiziente und transparente API-Lebenszyklen sind für moderne Webanwendungen entscheidend. In diesem Blog-Beitrag zeige ich euch, wie mit einfachen Mechanismen Produkt Owner die Möglichkeit bekommen, ihr System vor unerwünschten Änderungen zu schützen.

Sunset

Die Internet Engineering Task Force (IETF) bietet mit RFC 9745 (Deprecation Header) und RFC 8594 (Sunset Header) klare Mechanismen, um das Ende eines HTTP API-Endpunktes zu kommunizieren. Client-Entwicklerinnen und Entwickler können so automatisiert erkennen, wann Ressourcen veralten und wann sie abgeschaltet werden. Diese beiden Standards unterstützen vorausschauende Wartung und erleichtern die Migration auf neue Schnittstellen.

Mit dem Deprecation-Header wird der Zeitpunkt festgelegt, ab dem ein Endpunkt als veraltet gilt. Dieses Datum kann in der Zukunft oder in der Vergangenheit liegen. Der Sunset-Header definiert den Zeitpunkt, ab dem ein API-Endpunkt nicht mehr erreichbar ist und sein Verhalten undefiniert wird. Wenn beide Header gleichzeitig verwendet werden, soll das Sunset-Datum nach dem Deprecation-Datum liegen.

Mithilfe dieser beiden HTTP-Headers kann den Nutzerinnen und Nutzern der APIs auf technischer Ebene ein klarer Zeitplan für ihre Transitionsphase kommuniziert werden.

In dem in Abbildung 1 dargestellten Beispiel wird die API zum 1. Januar 2026 als veraltet (deprecated) markiert. Nach dem Sunset-Zeitpunkt am 31. Dezember 2026 ist das Verhalten der Ressource nicht mehr definiert.

Zusätzlich zu den Deprecation- und Sunset-Headern können noch Links (RFC 8288) im Header mitgesendet werden. Diese Link-Header sollen eine URL zu einem Dokument enthalten, das die Hintergründe der Abkündigung menschenlesbar beschreibt.

In der Dokumentation der API muss darauf hingewiesen werden, dass die beschriebene Information im Header mitgesendet werden kann. In der OpenAPI Dokumentation werden die Headerinformationen beispielsweise als optional gekennzeichnet. Benutzerinnen und Benutzer des APIs können ihr System dann so gestalten, dass die Information ausgewertet wird und sie informiert werden, wenn der Abkündigungsfall eintritt.

Anwendungsfall im Bounded Context

In unserem Projekt haben wir den beschriebenen Mechanismus bisher nicht angewendet. Unser Bounded Context agiert eher als Kunde anderer APIs und stellt selbst keine öffentlichen APIs bereit. Dies änderte sich, als die Grenze unseres Bounded Context im Zuge einer Notlösung verschoben werden sollte.

Ein Bounded Context definiert fachliche und sprachliche Grenzen innerhalb einer Domäne, um größere Systeme durch spezifische Teilbereiche zu organisieren. Er liegt in der Regel in der Verantwortung eines Teams. Die klare Abgrenzung von Verantwortlichkeiten in einem Bounded Context ist essenziell für ein stabiles und strategisch sauberes Softwaredesign und Bestandteil des Domain-Driven Design (DDD).

Unser Bounded Context kann wie folgt definiert werden:Verwaltung des Zugangs des Kunden zum direkten Kommunikationskanaldes Auftraggebers durch Administrationsmitarbeiter des Kunden.

Konkret bedeutet dies: Unser Team entscheidet darüber, ob ein Kunde am direkten Kommunikationskanal des Auftraggebers teilnehmen kann.

Die Domäne unseres Bounded Context befindet sich in einem regulierten Umfeld. Innerhalb dieser Domäne gibt es einen weiteren Bounded Context, der den Kommunikationskanal bereitstellt. Über diesen muss eine Verbindung zwischen einem Kunden und einem Mitarbeiter hergestellt werden können. Dies wurde bei der Projektplanung unterschätzt.

Zur Herstellung der Verbindung muss eine Anfrage an das Enterprise-Resource-Planning-(ERP-)System des Kunden gestellt werden. Da das Team des Kommunikationskanals den aktuellen Zeitplan nicht einhalten kann, wurde beschlossen, dass unser Team eine Schnittstelle bereitstellt, die den Verbindungsaufbau übernimmt. Ein neuer HTTP-Endpunkt nimmt eine Anfrage vom Kommunikationskanal entgegen und leitet sie an das ERP weiter. Der Aufwand im Team des Kommunikationskanals ist dadurch überschaubar. Auf unserer Seite ist es allerdings erheblich komplizierter, da wir auch im ERP-System umfangreiche Ergänzungen implementieren müssen.

Durch diese Änderung verschiebt sich die Abgrenzung unseres Bounded Contexts. Er reguliert nun nicht nur den Zugang der Kunden zum direkten Kommunikationskanal des Auftraggebers, sondern auch den Zugang der Mitarbeiter zu den Kunden. Damit kehrt sich die ursprüngliche Abgrenzung um. Darüber hinaus schafft die Notlösung eine zyklische Abhängigkeit zwischen den beiden Bounded Contexten.

Oft wird in solchen Fällen argumentiert, dass eine so kleine Anpassung kein Problem darstelle. Einem solchen Argument muss jedoch sofort entgegengetreten werden. Denn solche taktischen Notlösungen vergiften das strategische Design. Und jede kleine Vergiftung eines Bounded Context führt zu größeren Vergiftungen. Wurde die Tür einmal geöffnet, wird es nämlich nicht bei der einen kleinen Vergiftung bleiben.

Mit der gewählten Notlösung sind in beiden Teams alle unglücklich. Deshalb wurde beschlossen, dass das Team des Kommunikationskanals die Aufgabe des Proxies übernimmt, sofern freie Kapazitäten vorhanden sind. Unser Product Owner, der über langjährige Erfahrung mit der Organisation verfügt, ahnt jedoch, dass es diese freie Kapazität nie geben wird.

Die Maßnahme

Wir müssen also das Team des Kommunikationskanals dazu bringen, so schnell wie möglich mit der Ablösung der Notlösung zu beginnen. Zusammen mit dem Product Owner haben wir ein mehrstufiges Konzept dafür erarbeitet.

In einem ersten Schritt wurde ein Change-Request-Ticket im Backlog des Kommunikationskanalteams angelegt. Dieses beschreibt lediglich, dass der bisherige Weg über den Proxy so schnell wie möglich zurückgebaut werden soll. Im zweiten Schritt wurden in der OpenAPI-Dokumentation des Proxys die Deprecation- und Sunset-Headereinträge angekündigt. Beide Dokumentationsmaßnahmen waren mit sehr geringem Aufwand verbunden. Der Product Owner erhielt durch diese einfachen Mittel die Möglichkeit, neben der verbalen und schriftlichen Kommunikation zur Abkündigung der Notlösung auch technisch die Abschaltung anzukündigen. Das Scharfschalten der Abkündigung ist ebenfalls mit geringem Aufwand implementierbar.

Andererseits sollte das Team für die Kommunikationskanäle einen umgekehrten Totmannschalter implementieren. Dies kann nach der eigentlichen Implementierung der Proxy-Kommunikation iterativ erfolgen. Dabei wird regelmäßig überprüft, ob Deprecation- und Sunset-Header für das API gesetzt sind. Das Team kann beispielsweise per Alarm im Monitoring benachrichtigt werden. Das Team hat dann die Möglichkeit, entsprechende Maßnahmen einzuleiten.

Fazit

Als Architektinnen und Architekten haben wir eine soziotechnische Lösung gefunden, um unserem Product Owner technische und politische Gestaltungsmöglichkeiten zum Schutz seines Bounded Context zu geben. Ob er dies auch umsetzt, kann ich euch aktuell nicht mitteilen, da er sowohl bei der Aktivierung als auch bei der konkreten Abschaltung der Notlösung immer das letzte Wort hat.