Effektives API-Design: Prinzipien für verlässliche APIs verständlich erklärt

Das API-Design ist die Phase bei der Entwicklung einer API, in der ein Entwickler die Regeln bzw. den Vertrag der Schnittstelle festlegt: Ressourcen und Pfade, Methoden, Datenformate, Fehlermeldungen und Versionen. Dieser Vertrag bindet beide Seiten, den API-Anbieter und jedes System, das sie nutzt. Verwaltet und überwacht werden fertige APIs anschließend mit entsprechender API-Management-Software.

Ressourcen sind dabei die Objekte, die eine API anbietet, in der Supply Chain etwa Aufträge, Sendungen oder Lagerbestände. Wie eine REST-API Ressourcen, Methoden und Statuscodes einsetzt, klären wir in den Grundlagen der REST-API.

Für HTTP-APIs beschreibt die OpenAPI Specification diesen Vertrag in einem standardisierten Format. Ein OpenAPI-Dokument ist ein JSON-Objekt, das sich in den Textformaten JSON oder YAML schreiben lässt und unabhängig von Programmiersprachen ist.

Nicht jedes Tool beherrscht eine neue Ausgabe sofort, weshalb vor der Wahl einer Ausgabe genau geprüft werden muss, welche Version vorhandene Tools verarbeiten.

Design-first und Code-first sind zwei gegensätzliche Ansätze eine API zu entwerfen: Bei Code-first wird zuerst der Code programmiert und daraus anschließend die OpenAPI-Beschreibung erstellt. Bei Design-first läuft es genau umgekehrt, was auch der ausdrücklich empfohlene Weg ist, weil OpenAPI nicht jede mögliche HTTP-API beschreiben kann. Wird der Spieß umgedreht und zuerst programmiert, entsteht eine Schnittstelle, die sich später nur unvollständig beschreiben lässt.

Unabhängig vom Ansatz rät die OpenAPI Initiative zu genau einer maßgeblichen Quelle für den Vertrag, damit Code und Beschreibung nicht auseinanderlaufen. Auch das US-amerikanische National Institute of Standards and Technology (NIST) verlangt für jede API eine Spezifikation ihrer Endpoints, also der aufrufbaren Adressen.

Aus den Empfehlungen von NIST, der OpenAPI Initiative und Zalando ergibt sich ein Ablauf in vier Schritten:

1. Das Team beschreibt die API vor der Implementierung in OpenAPI, bei Zalando als eigenständige YAML-Datei.
2. Für jede Anfrage und Antwort legt es Schemata mit gültigen Wertebereichen fest, wie NIST es empfiehlt (REC-API-3).
3. Kolleginnen, Kollegen und die Teams der künftigen Clients prüfen den Entwurf bevor Code entsteht.
4. Ein API-Linter prüft den Entwurf automatisch gegen die Designregeln des Teams. Später melden Prüfwerkzeuge in der Continuous Integration (CI), wenn der Code von der Beschreibung abweicht.

Nach Semantic Versioning 2.0.0 steigt die erste Stelle der Versionsnummer, sobald sich eine API inkompatibel ändert. Kompatible Erweiterungen erhöhen die zweite Stelle, kompatible Fehlerkorrekturen die dritte.

Was als kompatibel gilt, präzisiert Google in seinen API-Regeln (AIP-180): Innerhalb einer Hauptversion dürfen Bestandteile hinzukommen, aber nicht wegfallen. Neue Pflichtfelder in bestehenden Anfragen schließt die Regel ebenfalls aus.

Für inkompatible Änderungen nennt die IETF-Leitlinie RFC 9205 drei Wege: eine neue Link-Relation, einen neuen Medientyp oder ein neues Headerfeld. Dass eine Ressource abgekündigt ist oder wird, meldet der Header Deprecation. Den voraussichtlichen Abschalttermin nennt der Header Sunset aus RFC 8594, einem Dokument der Kategorie „Informational“ ohne Status als Standard.

Ein Beispiel aus der Verwaltung ist die Empfehlung „API Architektur Bund“ der Schweizerischen Bundeskanzlei vom Januar 2022. Danach sollen API-Releases Semantic Versioning folgen, wobei die Version etwa in der URL oder in einem HTTP-Header steht. Für das Abschalten einer Hauptversion sieht die Empfehlung eine Übergangsfrist vor. Wie lange alte Versionen parallel laufen und wer über ihre Abschaltung entscheidet, behandelt der Artikel zum Lebenszyklus einer API.

Für API-Economy ist das Design einer API maßgebend, da es die Monetarisierbarkeit stark beeinflusst. Ein gut verwalteter API-Lebenszyklus ermöglicht es zudem, unmittelbar auf Veränderungen zu reagieren und schnell gezielte Maßnahmen an den APIs vornehmen zu können.

Dieser Prozess erfordert ein ganzheitliches API-Management und besteht aus mehreren Schritten, um sicherzustellen, dass alle Phasen von der Planung bis nach der Veröffentlichung berücksichtigt werden und Nutzer Ihre API reibungslos implementieren können.

1. Planung und Analyse: In dieser Phase wird der Bedarf und der Zweck der API bestimmt. Es geht darum, die Ziele klar zu definieren und zu verstehen, welche Daten und Funktionen die API bereitstellen soll.
2. Design-Konzept: Hier wird die Struktur und alle Parameter der API spezifiziert, einschließlich Endpunkte, Datenformate und Protokolle. Ein gut durchdachter Entwurf ist entscheidend für die Benutzerfreundlichkeit und die spätere Wartbarkeit der API.
3. Implementierung: In dieser Phase wird die API entwickelt. Dabei wird der im Entwurf festgelegte Plan umgesetzt und die Funktionalität der API realisiert.
4. Testing: Um die Zuverlässigkeit und Leistung der API sicherzustellen, werden umfangreiche Tests durchgeführt. Dies umfasst sowohl automatisierte als auch manuelle Testszenarien.
5. Deployment: Nach dem erfolgreichen Testen wird die API zur Bereitstellung in die Produktionsumgebung integriert und für die Nutzung freigegeben.
6. Motivation: Ist eine API veröffentlicht, müssen als nächstes Anreize für Entwickler geschaffen werden, die API zu verwenden und weiterzuentwickeln. Diese Anreize stehen oft mit der Monetarisierung der Schnittstelle in Verbindung.
7. Monitoring und Maintenance: Auch nach der Einführung der API ist eine kontinuierliche Überwachung und regelmäßige Wartung erforderlich, um Leistung und Sicherheit zu gewährleisten.
8. Versionierung und Aktualisierung: APIs entwickeln sich weiter, um neue Anforderungen zu erfüllen oder Verbesserungen zu integrieren. Dies erfordert eine effektive Versionierung und das Management von Updates.

Werden diese Schritte im API-Design-Lifecycle berücksichtigt, wird damit sichergestellt, dass APIs nicht nur funktional, sondern auch zukunftssicher sind.

Ein elegantes API-Design stellt immer die Nutzerbedürfnisse in den Fokus. Wer zugängliche, flexible und leistungsstarke APIs entwerfen und anbieten möchte, benötigt daher auch ein tiefgreifendes Verständnis für die Bedürfnisse und Use-Cases der späteren Anwender. Um diese besser zu verstehen und die Erkenntnisse in zukünftige Änderungen zu integrieren, hilft eine sorgfältige Analyse des Nutzungsverhaltens.

Dabei kann die Lobster Data Platform eine große Hilfe sein mit ihren ausführlichen Monitoring- und Analysefunktionen, die es Untenehmen einfach ermöglichen, ihre APIs mühelos zu verwalten und deren Betrieb zu überwachen. Mit praktischen Funktionen wie automatisierter Dokumentation, Performance-Monitoring und Sicherheitsmanagement unterstützt Lobster Unternehmen dabei, die Herausforderungen des API-Managements zu meistern und das volle Potenzial der eigenen digitalen Infrastruktur auszuschöpfen.

In einer unverbindlichen Demo mit unseren Spezialisten zeigen wir bei Interesse gerne wie schnell die Lobster Data Platform die Systemlandschaft eines Unternehmens transformieren kann.