Beschreibungssprachen für APIs wie OpenAPI, AsyncAPI, gRPC, oder GraphQL haben den Vorteil, dass (potentielle) Konsumenten eines APIs sich einen schnellen Überblick über das Verhalten eines APIs verschaffen können. Diese Konsumenten können dann auch Tools verwenden, die ihnen basierend auf den Beschreibungen das Konsumieren der APIs vereinfachen.
Doch was passiert, wenn sich ein API nicht verhält wie beschrieben? Kann das überhaupt passieren? Wenn ja, was können Gründe sein und was die Folgen? Und wie kann man verhindern, dass diese Dinge überhaupt passieren?
Die Ursachen für API Drift
In verschiedenen Szenarien gibt es verschiedene Wege, sowohl eine Beschreibung eines APIs zu haben als auch eine Implementierung. Manche bevorzugen einen “Code First” Ansatz, in dem zuerst das API implementiert wird und dann die Beschreibung dazu separat erstellt oder auch generiert wird.
Andere folgen einem “API First” Ansatz, bei dem zuerst die Beschreibung erstellt wird, um danach die Implementierung zu erstellen.
Beide Strategien haben ihre Einsatzgebiete und ihre Gefolgschaften. Aber in beiden Fällen kann es dazu kommen, dass Beschreibung und Implementierung auseinander driften. Das ist zunächst einmal logische Folge dessen, das Beschreibung und Implementierung zwei unterschiedliche Dinge sind, die ohne Disziplin und Tooling nicht von selber in Sync bleiben.
Die Folgen von API Drift
Welche Folgen kann API Drift haben? Streng genommen heisst API Drift, dass ein API Anbieter den “Vertrag” den er seinem Abnehmer verspricht, nicht einhält. Das mag etwas streng formuliert klingen (und ist es absichtlich auch), aber das ist die Essenz der Situation.
Für Konsumenten ist es frustrierend, wenn die Beschreibung ein bestimmtes Verhalten verspricht, dies in der Praxis dann aber anders aussieht.
Vor allem ist es zunehmend so, dass sich Konsumenten auf die Beschreibung verlassen und diese verwenden, um den Konsum des APIs zu vereinfachen, z.B. generieren sie u.U. Code. Dieser Code wird entweder Fehlermeldungen verursachen oder crashen, und in beiden Fällen ist es aufwendig und unintuitiv, den Fehler im Verhalten des APIs zu suchen. Die Fehlersuche wird also schwierig und frustrierend werden, und das sind keine guten Rezepte, um Konsumenten zufriedenzustellen.
Das Vermeiden von API Drift
Was lässt sich tun, um API Drift zu vermeiden? Wie bei Vielem heute geht es da vor allem um Automatisierung. Je häufiger und gründlicher automatisiert getestet wird, ob sich eine Implementierung wie beschrieben verhält, desto schneller lässt sich Drift erkennen. Und je schneller Drift erkannt wird, desto schneller kann sie nicht nur eliminiert werden, sondern es sollte auch Ursachenforschung betrieben werden wie es zu dieser Drift kam.
API Drift in der Realität
Das mag sich nun alles etwas theoretisch und alarmistisch anhören. API Drift ist sicher keine gute Sache, aber passiert das häufig und ist es ein reales Problem? Ein letztens veröffentlichter Report lässt vermuten, dass es sich durchaus um ein reales Problem handelt:
❗️ Nur die Hälfte aller untersuchten APIs hatten überhaupt eine offizielle Beschreibung.
❗️ Nur ein Viertel aller beschriebenen APIs verhielt sich exakt so wie beschrieben.
Wer an weiteren Details des Reports interessiert ist, kann hier ein Interview mit David O’Neill, einem der Initianten des Reports, anschauen:
Wer den Report lesen möchte, dieser findet sich hier (aber ist nur unter Angabe einer Email Adresse zugänglich):
👉 APIContext: The challenges of API Drift - most production APIs don’t match their specs