Warum API Guidelines eine coole Sache sind

„Ich sehe die Vorteile nicht. Das bremst mich nur aus.“
„Das funktioniert für mich nicht.“
Mit so ähnlichen Aussagen hatten wir zunächst zu tun, als wir die Initiative für API Guidelines gestartet haben.

Aber dann kamen wir im Austausch schnell an den Punkt, die Gemengelage genauer unter die Lupe zu nehmen, in der wir bei OTTO stecken:
• OTTO wandelt sich zum Marktplatz.
• Das Unternehmen wächst.
• Wir entwickeln Software in einer Vielzahl von autonomen Produktteams.

Wer das liest, kann die Herausforderungen, die das mit sich bringt, vielleicht mitfühlen und hat die unmittelbaren Auswirkungen und Folgen im täglichen Arbeitsumfeld auch schon mal gespürt.
Zur genaueren Einordnung: Viele kennen OTTO als Einzelhändler. Allein in dem Kontext gibt es eine Menge Schnittstellen. Mit dem Wandel zum Marktplatz kommen noch viele weitere Schnittstellen dazu, zusätzlich noch Marktplatzpartner. Da sind wir natürlich mit APIs unterwegs, um Business-Funktionalität bereitzustellen. Und das passiert in den unterschiedlichsten autonom-arbeitenden Teams und noch dazu in verschiedenen IT-Bereichen. Lass‘ das mal wirken!

Am Markt gibt es übrigens ähnliche Herausforderungen: Wir sitzen da z.B. mit Spotify, Atlassian oder Zalando in einem Boot.

Lass' uns mal kurz was knobeln: Stell dir eine API vor, die Zugang zu einer “Liste von Produktvarianten” und “einer Produktvariante” bietet. Welche URI würdest du wählen?

Abbildung 1: Quiz 

All diese Pfade sind aus reiner REST-Perspektive technisch korrekt, aber jede Antwort unterscheidet sich von den anderen. Diese Lösungen sind inkonsistent.
So ist das in der Produktentwicklung mit vielen Teams: Viele Menschen entwickeln APIs und jede*r macht’s anders. Uns war so glasklar, dass API Guidelines eine coole Sache sind und uns als einheitlicher Standard hier sehr helfen wird. Aber auch, dass wir auf dem Weg zu leicht verständlichen und einheitlichen APIs noch gut zu tun haben. Da mussten wir ran.

An der Erarbeitung der API Guidelines sollten möglichst viele Kolleg*innen aus unterschiedlichen Teams mitwirken, um viele Bedarfe aus der Praxis einfließen zu lassen. Darüber hinaus schafft Mitarbeit und Mitspracherecht eine größere Akzeptanz bei der späteren Anwendung. Um Ressourcen für eine Arbeitsgruppe dieser Größe freizuräumen, haben wir unseren internen Priorisierungsprozess genutzt. Kaum war das durch, ging’s los mit Kickoff, gemeinsamer Themenerfassung, Aufteilung in Kleingruppen für Themenschwerpunkte und Einigung auf eine Arbeitsweise mit GitHub-Project-Board und Abstimmung über Daily Standups.

In dieser Phase haben wir auch direkt einen Technical Writer mit ins Boot geholt, um zu beleuchten: Ist das verständlich, was wir hier skizzieren? Versteht das auch ein Junior? Wir wollen schließlich Dokumentation rausgeben, die auch für alle Zielgruppen gut konsumierbar ist.

Durch Fokussierung und leichtgewichtige Prozesse hat die Arbeitsgruppe schnell Ergebnisse erzielt. So konnten wir direkt damit in der Organisation „hausieren“ gehen, Feedback einsammeln und einarbeiten. Im Anschluss haben wir uns die explizite Zusage der Teams eingeholt, zukünftig die API Guidelines beim API Design zu verwenden – mit dem ausdrücklichen Hinweis: Die Guidelines sind ein lebendes Dokument und können jederzeit erweitert werden.

Um übergreifende Zusammenarbeit zu fördern, haben wir zusätzlich mit einer Roadshow über unseren Meilenstein informiert und die API Guidelines auch über unsere Organisationseinheit hinaus bekanntgemacht.

Jedem wird klar sein: Ein Dokument zu veröffentlichen und dann zu erwarten, dass sich alle danach richten, ist irgendwie unrealistisch und zum Scheitern verurteilt. Um unseren neuen Standard im Unternehmen zu etablieren und die Teams bei der Anwendung zu unterstützen, haben wir die Rolle des API Coaches eingeführt. Erfahrene Entwickler*innen begleiten bei Bedarf den API-Entwicklungsprozess von der Spezifikation zwischen API Provider und Konsument*innen über die Implementierung bis hin zum Go Live. Diese Rolle sollte Starthilfe sein und langfristig in den Teams und im Austausch mit einer aktiven API-Community gelebt werden.

Neben Hands-on Unterstützung haben wir einen Linter entwickelt, mit dem die API-Spezifikationen automatisch auf die Einhaltung der Richtlinien überprüft werden können. Das ist richtig cool!

Abbildung 2: Linter Ergebnisse

Zusätzlich ermöglichen wir einfachen Zugriff auf unsere Guidelines über unser API Portal. So können API-Konsument*innen direkt sehen, dass wir beim API Design nach einem Standard arbeiten und Wert auf Qualität legen.

Nach mittlerweile über zwei Jahren mit etablierten API Guidelines können wir aus unserer Erfahrung sagen: API Guidelines SIND eine coole Sache! Immer mehr Teams sehen die Vorteile der Nutzung eines Standards, weil sie sich an etwas Vorhandenem bedienen können, statt Zeit aufzuwenden und sich selbst Gedanken zu machen. Gerade API Konsument*innen fordern nach API Guidelines entwickelte APIs explizit an, damit der Reibungsverlust bei der Einarbeitung nicht zu hoch ist.
Hochwertige, langlebige und vorhersagbare APIs sind wichtiger denn je und machen API Guidelines für uns unverzichtbar.