Das Team, welches wir schon beim letzten Mal kennengelernt haben, hat nun die API für die ERP-Lösung in einem weiteren Sprint entsprechend den Anforderungen der Konsumenten fertiggestellt. Im neusten Sprint sollen sie nun eine weitere API erstellen. Diese soll die vorhandene API mit Daten einer API, welche durch ein anderes Team entwickelt wurde, anreichern.
Eine solche API wird auch gerne als Third Party API beschrieben. Das Team stellt bei einem Vergleich ihrer eigenen mit der anderen API fest, dass die API-Definitionen schon sehr unterschiedlich hinsichtlich der Verwendung der OpenAPI-Spezifikation sind. Auf Nachfrage erklärt das andere Team, dass man sich als Team Richtlinien, die sogenannten API-Guidelines, definiert habe, um das Design von APIs zu vereinheitlichen und aufgrund des Regelwerks überprüf- und testbar zu machen. In einem ersten Schritt werden nun die Guidelines von unserem Team kopiert, um sofort Anwendung zu finden. Ob dies eine gute Idee war, werden wir später noch erörtern.
Design braucht Regeln
Jedes Design, ob analog oder digital, basiert auf Regeln. Diese Regeln dienen dazu, zu jeder Zeit Antworten auf Fragen im Designprozess geben zu können, um so auch immer die gleiche Qualität und Güte zu liefern. Im Kontext von APIs dienen die Regeln in großen Organisationen auch dazu, für Konsistenz in Bezug auf Themen wie Compliance und Governance zu sorgen. Als Leser fragen Sie sich sicherlich, was alles passieren würde, wenn APIs ohne gemeinsamen Katalog an Regeln erstellt werden. Zuallererst führt dies zu einem inkonsistenten Design, welches mehr Verwirrung erzeugen wird, als dass es Sinn stiftet. Ebenso werden gleichartige Konzepte auf unterschiedliche Weisen im Design dargestellt. Des Weiteren wird es über kurz oder lang zu Dokumentationslücken kommen. Wenn wir diese Regeln nun zusammenfassen, entstehen Richtlinien. Diese Richtlinien passen in Gänze immer auf die Organisation.
Nicht kopieren, sondern adaptieren
Aus diesem Grund sollten Regeln daher auch nicht einfach kopiert werden. Denn Regeln beziehungsweise Richtlinien entstehen durch gelebte Praxis und unterliegen gerade am Anfang einem hohen Anpassungsdruck. Dies bedeutet, dass man sich gerne von den führenden API-first-Unternehmen inspirieren lassen kann, um dann diese Regel auf die eigene Organisation zu übertragen und in der Praxis zu leben. Ich möchte dies einmal mit einem Beispiel untermauern. So ist die Verwendung des HTTP-Errorcodes 429 (Too Many Requests) nur sinnvoll, wenn geplant ist, Rate-Limiting, einen Kontrollmechanismus für den ein- und ausgehenden Datenverkehr für APIs, die in der Organisation angedacht sind, zu verwenden. Ansonsten verwirrt die Angabe dieses Errorcodes mehr, als dass es wirklich wert stiftet.
Listing 1: Kurzes Spectral-Beispiel
Aufgeschrieben ist schön, aber nicht wirksam
Es ist schon mal ein guter Schritt in die richtige Richtung, wenn man in einer Organisation oder zumindest in Teilen Richtlinien für den Entwickleralltag findet. Aus der Praxis heraus wissen wir, dass niedergeschriebene Regeln in einer Umsetzung sich nur mit großem Aufwand überprüfen lassen. Daher gilt es nun, die verschriftlichten in prüfbare Regelsätze zu transformieren. Im Fall von APIs ist das ein einfaches Unterfangen, entsprechendes Tooling vorgesetzt. Wenn wir API-Definitionen schreiben, ist uns ja sehr daran gelegen, dass diese zur entsprechenden Version der OpenAPI-Spezifikation passen. Dies können wir mit Validierung gegen das jeweilige Schema überprüfen. Unter [Tools] finden wir eine Liste entsprechender Tools und Frameworks in den verschiedensten Programmiersprachen.
Mit den Tools openapi-cli [Redocly] und Spectral [Stoplight] können wir die Standardvalidierungen mithilfe von Rule(set)s, Functions und Plug-ins auf die jeweiligen Bedürfnisse der Organisation oder der Teams anpassen. Hierbei verwenden die beiden Produkte jeweils eine Kombination aus YAML und JavaScript, um die Erweiterungen schreiben zu können. Ich möchte Ihnen nun in Listing 1 ein kurzes Beispiel für eine geschriebene Rule mit Spectral geben, um das Ganze ein wenig zu veranschaulichen.
Es wird nun überprüft, ob die OpenAPI-Extension x-amazonintegration im paths-Objekt vorhanden ist. Dies ist nur eines von vielen Beispielen, mit denen aus den starren API-Guidelines testbare Regelsätze werden. Sowohl für openapi-cli als auch Spectral gibt es Erweiterungen für Editoren wie Visual Studio Code, sodass die Validierung zum Teil des Schreibprozesses, dem sogenannten Linting, wird, weil schon direkt im Editor eine Überprüfung stattfindet.
Regelsätze als Teil des Testings
Und von der Überprüfung im Editor ist es dann nicht mehr weit, dass die Validierung zu einem Teil von Continuous Integration innerhalb einer Build- beziehungsweise Deploy-Pipeline wird. Und dies ist auch unter anderem ein Punkt, wo API-Guidelines zu einem Rettungsanker für das Design von APIs werden. So wird sichergestellt, dass sich über die Zeit ein sehr konsistentes API-Design entwickelt, was auch vor allem den Konsumenten der APIs hilft, diese zu verstehen und anzuwenden.
Weitere Informationen
[Redocly] https://redoc.ly/openapi-cli
[Stoplight] https://stoplight.io/spectral
