Nachhaltiges API-Design in einem API-first-Unternehmen

Kürzlich wurde ich gefragt „Was bedeutet API-first allgemein und speziell für fulfillmenttools?“ und ich muss zugeben: Es ist schwer, das in einem Satz oder auch in einer Reihe von Sätzen zu beantworten. In unseren Köpfen hier bei fulfillmenttools gibt es definitiv Bilder, Ideen, Paradigmen und manchmal auch Meinungen zu diesem Thema – aber ein kleines Wunder findet statt, wenn man versucht, diese Dinge im Tagesgeschäft flächendeckend anzuwenden. 

Daher habe ich mich entschlossen, einen aktuellen Arbeitsstand aufzuschreiben, eine bloße „Momentaufnahme“, wie und warum wir API-Design betreiben, ohne zu sagen: „So macht man das – Punkt!“. Es soll ein Einblick für andere Entwickler:innen, Architekt:innen, CTOs und Leute sein, die an der Frage interessiert sind: Wie entwirft und betreibt man eine API, die einerseits konsistent, andererseits aber auch flexibel genug ist, um schnelllebige und sich entwickelnde Geschäftsziele zu unterstützen?

Das Gespräch beginnt oft mit dieser Frage – gefolgt von: „Und was ist die stärkste API-Technologie?“. Es ist nicht verwunderlich, dass die Antworten auf diese Fragen so unterschiedlich sind wie die Menschen, die man fragt. Einerseits mag der typische Product Owner keine vagen Definitionen oder Ziele für die API. Sie sind schwer zu bewerten und werden deshalb wahrscheinlich irgendwann von der Checkliste gestrichen. Andererseits möchten Software-Entwickler:innen, die einen Connector für dieselbe API bauen, saubere Paradigmen und ein konsistentes Erscheinungsbild bei der tatsächlichen Verwendung der API sehen, da dies die Programmierung erleichtert. Die einzige Sorge derjenigen, die Produktionssysteme betreiben, scheinen die Antwortzeiten und die Anzahl der fehlgeschlagenen API-Aufrufe zu sein – ungeachtet der zugrunde liegenden Geschäftsfunktionen oder der angenommenen Nutzung. 

Zumindest in einem Punkt sind sich alle diese Gruppen einig: Eine exzellente Dokumentation der Fähigkeiten und Konzepte einer API (oder des Produkts) ist nicht mehr nur das Sahnehäubchen, sondern ein Muss für API-getriebene IT-Unternehmen. 

fulfillmenttools ist Teil der MACH Alliance. Das bringt eine weitere Perspektive mit: Das „A“ in MACH steht für API-first. Wie weben wir also diese Anforderung in unsere Prozesse ein? Wie stellen wir sicher, dass der Zugang zu unserer Funktion über APIs bei der Entwicklung einer neuen Funktion im Vordergrund steht? Und wie sorgen wir für Transparenz bei der Nutzung unserer APIs, um eine einfache Integration sicherzustellen?

Anstatt immer wieder über viele weitere Meinungen, Herausforderungen und Anforderungen aus der Sicht eines API-Anbieters zu sprechen, möchte ich Euch zwei unserer derzeitigen Ansätze vorstellen. Obwohl sie für uns im Moment funktionieren, solltet ihr nicht vergessen, dass dies nur zwei von vielen weiteren Aspekten sind. Sie werden ständig überprüft und angepasst, da wir in einem sich ständig verändernden agilen Umfeld tätig sind.

Das war der zweite Satz, den ich von meinem CPO gehört habe, als wir mit fulfillmenttools angefangen haben:

Es war eine Lernerfahrung aus der Vergangenheit: Wenn wir mit autonomen Teams in verschiedenen Bereichen gearbeitet haben, sahen die bereitgestellten APIs in der Regel unterschiedlich aus und waren von unterschiedlicher Qualität. Da wir wussten, dass wir ein API-first-Produkt mit einem starken Fokus auf einheitliche und verständliche Schnittstellen für die Plattform anbieten würden, war der erste Schritt, zuzugeben, dass wir in dieser Hinsicht Zeit und Energie investieren müssen. 

In einem Unternehmen mit zehn Mitarbeitenden mag das recht einfach sein. Aber als unser Team wuchs, wurde es zu zeitaufwändig und ineffizient, das gesamte Team einzubeziehen, sodass wir bald erkannten, dass eine Art von Expert:innengruppe benötigt wurde. Die Idee ist nicht neu, und in anderen Organisationen werden diese Gruppen als Gilden oder Community of Practice bezeichnet. In unserem Fall nannten wir die Gruppe „API Brigade“, die an sich funktionsübergreifend ist: Sie umfasst derzeit Product Owner, Architekt:innen, Backend-Entwickler:innen und auch Frontend- Entwickler:innen. Anstatt also nur die Personen auszuwählen, die die API letztendlich nutzen, haben wir beschlossen, die Stakeholder aus Business und Architektur mit einzubeziehen, was zu einem sauberen, präziseren Ansatz führte. Ein Vorteil ist, dass Entscheidungen, die von dieser Brigade getroffen werden, die Teams und die Technik erreichen, die letztendlich für die Umsetzung der Entscheidungen verantwortlich sind. 

Niemand mag zu viele Meetings – und Engpässe sind aus Sicht eines Unternehmens noch schlimmer, besonders in einer wachsenden, agilen Organisation. Die Hauptaufgabe der API-Brigade besteht darin, die Teams in die Lage zu versetzen, bei 90 % der anstehenden Fragen selbst die richtigen Entscheidungen zu treffen. Sie trifft sich aber nur alle zwei Wochen für eine Stunde. Daher war die Entwicklung einer mächtigen Waffe für die tägliche Arbeit der unabhängigen Teams notwendig. In unserem Fall hat es sehr geholfen, Regeln in einem Leitfaden niederzuschreiben, was auch in anderen Organisationen gängige Praxis ist. Die Magie dabei ist eigentlich nicht das Aufschreiben der Regeln – sondern sicherzustellen, dass die Regeln von den Leuten in ihrer täglichen Arbeit befolgt werden. 

Wir haben uns entschlossen, die Macht, die Dinge zu erledigen, in die Hände der Entwickler:innen zu legen. Bei fulfillmenttools wird jede:r Entwickler:in (oder eigentlich jedes Teammitglied) dazu ermutigt, nicht nur geschäftsbezogene Themen, sondern auch technische oder organisatorische Fragen in Backlogs, Verfeinerungen und schließlich in das Team-Board aufzunehmen. So werden technische Themen in den Vordergrund gerückt, wenn die Frage „Was kommt als Nächstes?“ auftaucht. Dieser Ansatz sorgt dafür, dass der Schwerpunkt auf technisch sauberen Lösungen liegt und vermeidet, dass wenig greifbare Themen – wie der API-Zugang zu Geschäftsfunktionen – ins Hintertreffen geraten.

Ein weiterer Aspekt, der uns in der Vergangenheit häufig begegnet ist, ist die Frage: 

Die Antwort ist: Es gibt keine Version – und trotzdem sind wir in der Lage, jeden Tag Dutzende von Versionen und Änderungen an der API vorzunehmen, ohne dass der Vertrag, der zwischen Client und Service besteht, gebrochen wird. Es überrascht nicht, dass dies zu hochgezogenen Augenbrauen und Kopfschütteln führt. Zumindest bevor wir unseren Ansatz erklären, aber wir wollen nicht zu weit vorgreifen.

Lasst uns zunächst einen Schritt zurückgehen: Wenn ihr eine API für ein Produkt bereitstellt, das von Entwickler:innen außerhalb des  Unternehmens verwendet wird, ist es Teil der Vereinbarung, dass der Vertrag, der zwischen Client und Service besteht, nicht gebrochen wird. Oder andersherum: Die API muss vom semantischen Standpunkt aus gesehen stabil sein. Um das zu gewährleisten, könnten wir Versionen einer API veröffentlichen. Die API in einer solchen Version ist „fest“ und ändert sich nie. Leider widerspricht das der Idee einer wachsenden Plattform, wachsender Produkte und ihrer Funktionen, denn insbesondere bei einem agilen Ansatz sollte die erste Iteration einer Funktion einen Mehrwert bringen. Aber manchmal muss diese bereitgestellte Funktion geändert oder erweitert werden. Wie funktioniert das zusammen mit einem agilen kontinuierlichen Integrationsprozess? Aus unserer Sicht: Nicht sehr gut.

Um eine API „aus einem Guss“ (siehe oben) zu haben, die Fähigkeit zur agilen Entwicklung zu erhalten und unseren Kunden iterativ und zeitnah einen Mehrwert zu bieten, haben wir uns für eine versionslose API entschieden. Das bedeutet, dass sie sich ständig weiterentwickelt. Es gibt Regeln für diese Entwicklung, die in unserer Dokumentation transparent beschrieben sind. Wenn ein:e Entwickler:in diese Regeln kennt, ist es nicht schwer, sie zu befolgen, was die entwickelte Lösung robuster und stabiler macht.

Neben den Dingen, die wir als „nicht bahnbrechende Änderungen“ betrachten, haben wir beschlossen, eine Alpha-, Beta- und GA-Versionierung pro Endpunkt oder Modell einzuführen – wiederum mit einem festen Satz von Regeln für diese Bezeichnungen. Mit der Bereitstellung eines Alpha-Endpunkts beispielsweise geben wir unseren Partnern und Kunden bereits eine Vorschau auf die aktuell entwickelten Funktionen – um beispielsweise Feedback und Einblicke aus der Perspektive der Entwickle:innenr zu erhalten. Die Sache ist die: Ein solcher Endpunkt kann sich jederzeit und ohne Vorwarnung semantisch verändern. Beta-Endpunkte hingegen sind wesentlich stabiler und können bei Bedarf in der Produktion eingesetzt werden: Eine Änderung hier muss unseren Partnern vorher mitgeteilt werden. 

Wir bemühen uns aktiv darum, die Zeit der Alpha- und Beta-Endpunkte zu begrenzen, um den größten Teil unserer API allgemein verfügbar zu machen (GA). Bedeutet GA, dass sich die API in Zukunft nie ändern wird? Nein, natürlich nicht! Auch hier können und werden höchstwahrscheinlich non-breaking changes vorgenommen werden, wie z. B. das Hinzufügen von Parametern, Subresourcen usw.

Die mit Alpha- und Beta-Kennzeichnung versehenen Endpunkte sowie die Liste der non-breaking changes ermöglichen es uns, unser Produkt API-first zu entwickeln, ohne den Aufwand einer häufigen Versionierung.