Bessere APIs, aber wie?

Erik Wilde

APIs spielen viele verschiedene Rollen in Organisationen, je nachdem wofür und wo sie eingesetzt werden. Das Spektrum reicht von internen APIs mit einem kleinen Satz an Konsumenten bis hin zu API-Produkten die vermarktet und verkauft werden. In allen diesen Fällen ist es hilfreich, wenn ein API gewisse Qualitätsmerkmale erfüllt, wie auch immer genau diese definiert werden.

API Linting verfolgt den Ansatz, dass die Beschreibung eines API (z.B. in OpenAPI oder AsyncAPI) gemäss Regeln getestet wird, die die Qualitätsmerkmale überprüfen. Im einfachsten Fall nimmt man also eine API Beschreibung, nimmt ein Linting Tool, und erhält dann Feedback inwieweit das API die Qualitätsmerkmale erfüllt.

Je nachdem, ob ein API noch in der Entwicklungsphase ist oder nicht, können unterschiedliche Regeln angewendet werden. Ebenso ist es möglich, dass je nach Typ des APIs (ob es z.B. ausserhalb der Organisation sichtbar ist oder nicht) verschiedene Regeln angewandt werden. Und neben den eingebauten Regeln ist es ebenso möglich, eigene Regeln zu schreiben und diesen ebenfalls vom Linting Tool überprüfen zu lassen.

API Linting ist nicht grundsätzlich anders als andere Linting Szenarios. Speziell könnte aber hervorgehoben werden, dass API Linting ja nicht nur intern in einer Codebase, also für die Code Qualität, wichtig sind, sondern vor allem auch extern, weil es dort ja um die Schnittstelle geht, mit der Code genutzt werden kann. Deswegen kann es beim API wichtig sein, Eigenschaften der Schnittstelle zu berücksichtigen wie z.B. wo ein API im Lebenszyklus steht, oder um was für einen Typ (z.B. intern vs. extern) es sich handelt.

In diesem einfachen Modell greift das Linting Tool optional auf Regeln zu, die die eingebauten Regeln ergänzen oder ersetzen. Im API Bereich ist das derzeit populärste Linting Tool das Open Source Tool Spectral. Es wurde von Stoplight entwickelt, ist aber komplett frei verfügbar.

Es gibt eine weitere Dimension des API Linting. Diese besteht darin, dass sehr viele Organisationen Richtlinien für APIs haben. Das Ziel besteht dabei darin, API-Design zu vereinfachen weil es für viele Design-Fragen vorgegebene Lösungsmuster gibt. Ein weiteres wichtiges Ziel ist, dass es wesentlich einfacher wird die APIs einer Organisation zu nutzen, wenn diese alle gleichen Design-Ansätzen folgen.

In diesem zweiten Szenario ist die standardisierende Rolle des Linting gleich wichtig wie die Qualitätskontrolle einzelner APIs. Organisationen bemühen sich zunehmend, ihre Richtlinien in solche maschinenausführbaren Regelsätze zu überführen. Wer daran interessiert ist wie diese aussehen, findet hier eine Sammlung von “Spectral Rulesets in the wild”.

In der Praxis ist Spectral einfach zu nutzen, vor allem auch weil es eine grosse Menge an eingebauten Regeln hat und einem so schon ohne jegliche selbstgeschriebene Regeln nützliches Feedback zu API Beschreibungen liefern kann. Gefallen einem diese Regeln nicht, so können sie selektiv ausgeschaltet oder in ihrer Bewertung verändert werden.

Damit wird Spectral zu einem Tool, das sich einfach als Teil der eigenen Entwicklungsplattform nutzen lässt. Erscheint das Standard-Feedback irgendwann nicht mehr gut genug, oder sollen z.B. die Einhaltung eigenen Richtlinien zum API-Design automatisiert unterstützt werden, dann kann zusätzlicher Aufwand betrieben werden mit der Entwicklung eigener Regeln. Diese “Rules” können gruppiert in “Rulesets” verwaltet werden, die dann ihrerseits in automatisierten Scripts je nach Situation verwendet werden können.

Wer an mehr Details interessiert ist kann mehr erfahren im INNOQ Technology Lunch am 5.3.2025. Bei diesem Termin werden weitere Aspekte von Spectral erläutert, es wird auf die Details und Möglichkeiten der Rules und Rulesets eingegangen, und es wird gezeigt, wie Spectral automatisiert in CI/CD Szenarien verwendet werden kann.