Gutes API Design: Wie du deine APIs Entwickler-freundlich gestaltest

Als technische Schnittstelle muss eine API für Entwickler einfach zu verstehen, zuverlässig zu nutzen und langfristig wartbar sein. Was genau gutes API Design ausmacht und wie du deine APIs Entwickler-freundlich gestalten kannst erklären wir dir in diesem Blogbeitrag.

Was sind APIs?

Kurz vorab eine allgemeine Definition für APIs: API steht für Application Programming Interface (deutsch: Programmierschnittstelle). APIs sind Schnittstellen zwischen Softwareprogrammen, über die verschiedene Anwendungen Daten austauschen können.

Im Grunde funktionieren sie ähnlich wie ein Vertrag: Sie legen fest, welche Art von Daten du übermitteln musst, an welchen Endpunkt du deine Daten übermitteln musst und welche Art von Daten du im Gegenzug von der API erhältst.

Nahezu jede Art von Software stellt APIs bereit. Einige davon sind öffentlich, andere werden wiederum intern genutzt. Ebenfalls gibt es verschiedene Protokolle zur Implementierung von APIs, wie beispielsweise REST, GraphQL oder gRPC.

Was ist API Design?

Die Entwicklung von APIs bildet einen wichtigen Schritt in der Softwareentwicklung ab, weshalb das API Design auch eine so große Rolle für Entwickler und Softwarebetreiber spielen sollte.

Die Definition relevanter Endpunkte und die Art und Weise der Übertragung sorgen dafür, dass die System-Komponenten reibungslos miteinander kommunizieren können. Ebenfalls sorgt ein durchdachtes API Design für eine angenehme Developer Experience (DX).

Ein mangelhaftes API Design führt häufig zu Frustrationen und ist anfällig für diverse Fehler sowie vermeidbare Missverständnisse.

Die 5 wichtigsten Punkte für gutes API Design

1. Klare Namensgebung

Externe Entwickler kennen deine API in der Regel nicht so gut, wie du selbst. Daher ist eine verständliche Namensgebung deiner Endpunkte von großer Bedeutung. Um die API so selbsterklärend und einheitlich wie möglich zu gestalten sollten gleiche Objekte immer mit dem gleichen Namen angesprochen werden.

Wenn z. B. ein Listen-Endpunkt zum Abrufen von Benutzerdaten /users heißt, sollte der Bestell-Endpunkt /orders heißen und nicht etwa /getOrders.

2. Sinnvolle Nutzung von HTTP-Statuscodes

Mit Hilfe von den dreistelligen Zahlenfolgen der HTTP-Statuscodes kannst du deine API für externe Entwickler mit allgemeinverständlichen Meldungen versorgen.

Du brauchst dabei nicht alle 60+ Codes einbinden. Achte jedoch immer darauf, dass die wichtigsten Codes zurückgegeben werden können. Dazu zählen z. B.:

• 200 OK ⇒ erfolgreiche Anfrage

• 400 Bad Request ⇒ die gesendeten Daten waren ungültig

• 401 / 403 ⇒ nicht autorisiert / Zugriff verweigert

• 404 ⇒ die angeforderte Ressource wurde nicht gefunden

• 500 ⇒ Serverfehler

3. Hilfreiche Fehlermeldungen

Es ist besonders wichtig, dass schnell erkannt werden kann, um welche Art von Fehler es sich handelt. Auch hier spielt die Einheitlichkeit des Codes eine wichtige Rolle. Durch eine klare und konsistente Struktur der Fehlermeldungen können Fehler schneller analysiert und gezielt behoben werden.

Im Folgenden zwei verschiedene Fehlermeldungen

Bei diesem Fehlercode muss mehr oder weniger geraten werden, welche Anfrage der Endpunkt akzeptiert. Die Fehlersuche und -behebung muss also manuell vom jeweiligen Entwickler durchgeführt werden, der versucht die API aufzurufen.

Anders ist es bei diesem Fehlercode:

Hier wird genau mitgeteilt welche Art von Daten fehlen oder ungültig sind. Die Kombination aus maschinenlesbarem Code oder einer Kennung, anhand derer sich erkennen lässt, um welche Art von Fehler es sich handelt und eine für Menschen lesbare Meldung sorgen für eine gute, einheitliche und eindeutige Fehlermeldung.

Es ist ebenfalls wichtig, dass alle aufgetretenen Validierungsfehler immer zusammen zurückgeben werden und nicht einzeln.

4. Es sollte einfach sein, die API korrekt zu nutzen

Was erst einmal banal klingt wird in der Praxis häufig zu einem Stolperstein für viele Entwickler. Losgelöst von dem eigenen Wissen über die APIs sollte geschaut werden, wie jemand, der kein Vorwissen hat von der API erwarten würde.

Zu den Techniken, mit denen sich eine API benutzerfreundlich gestalten lässt, gehören:

• Sinnvolle Standardwerte: Wenn bestimmte Parameter nicht erforderlich sind oder nur in einem Verhältnis von etwa 80 zu 20 vorkommen, sollten die wahrscheinlicheren Fälle als Standardverhalten festgelegt werden.

• Ungültige Zustände verhindern: Achte darauf, wie dein Backend auf ungültige Anfragen reagiert. Ungültige Daten wie widersprüchliche Werte oder fehlerhaft formatierte Anfragen sollten nicht zu einem Erfolg führen.

• Frühzeitiges Scheitern: Wenn die Anfragedaten falsch sind, lehne die Anfrage so schnell wie möglich mit einer klaren Meldung ab und versuche nicht zu interpretieren, was jemand mit seinen falschen Daten wahrscheinlich gemeint hat.

Damit dieses Ziel erreicht werden kann, sollten die APIs frühzeitig anderen Personen wie z. B. Kollegen zur Verfügung gestellt werden, die nur wenig Hintergrundwissen haben, um zu prüfen, ob die API wirklich selbsterklärend ist.

5. Verursache keine Kompatibilitätsprobleme - und wenn es doch einmal unvermeidbar ist, führe eine Versionsverwaltung durch

Eines der lästigsten Probleme bei der Nutzung einer API ist es, wenn eine API implementiert wurde, die plötzlich nicht mehr funktioniert, obwohl sich eigentlich nichts an ihr geändert hat.

Wenn du in einem kleinen internen Team arbeitest, reichen kurze Absprachen mit deinen Kollegen über grundlegende Änderungen oft aus. Bei einer öffentlich genutzten API ist das anders. Müssen Fehler behoben werden, sollte die API versioniert werden. So bleiben bestehende Funktionen weiterhin nutzbar und Drittentwickler haben ausreichend Zeit, auf eine neue Version umzusteigen, bevor die alte als veraltet gekennzeichnet wird.

Fazit

Gutes API Design sorgt dafür, dass Entwickler gerne mit deiner Schnittstelle arbeiten. Besonders wichtig ist dabei ein logischer Aufbau mit einheitlichen Namen, konsistenten Abläufen und klaren Vorgaben für den Umgang mit z. B. Fehlermeldungen. So können Missverständnisse verhindert und eine korrekte sowie einfache Bedienung gesichert werden.