API Definition

Business Types sind abstrahierte Datentypen, die häufig genutzte Entitäten innerhalb eines Systems repräsentieren. Beispiele sind „User“, „Order“ oder „Invoice“. Diese Typen helfen dabei, eine einheitliche Struktur über verschiedene Endpunkte hinweg beizubehalten.

Components sind wiederverwendbare API-Bausteine, die in Definitionen wie OpenAPI verwendet werden. Sie umfassen beispielsweise Schema-Definitionen für Datenobjekte, Sicherheitsmechanismen und Parameter. Durch den Einsatz von Components lassen sich API-Spezifikationen modular und wartungsfreundlich gestalten.

Konsistente Namensgebung sicherstellen: Endpunkte sollten klar, vorhersehbar und einheitlich benannt werden. Beispielsweise sollte die Ressource für Benutzer unter /api/users erreichbar sein, anstatt unklare oder unterschiedliche Bezeichnungen wie /api/getUsers oder /api/userList zu verwenden.

Versionierung implementieren: Eine API sollte von Beginn an eine Versionierung nutzen, um Änderungen in der Zukunft sauber verwalten zu können. Beispielsweise kann /api/v1/users für die erste Version der API genutzt werden, während spätere Iterationen unter /api/v2/users laufen können, ohne bestehende Integrationen zu unterbrechen.

HTTP-Methoden korrekt einsetzen: Die Verwendung der richtigen HTTP-Methoden erleichtert das Verständnis und die Nutzung der API. GET sollte für das Abrufen von Daten, POST für das Erstellen neuer Ressourcen, PUT für das Aktualisieren und DELETE für das Entfernen von Daten genutzt werden.

Keine unnötigen Endpunkte erstellen: Jeder Endpunkt sollte einer klaren Funktion dienen. Statt für jede einzelne Aktion einen neuen Endpunkt anzulegen (/api/getUsers, /api/updateUser, /api/removeUser), sollte eine generische Struktur verwendet werden, die CRUD-Operationen konsolidiert (GET /api/users, PUT /api/users/{id}, DELETE /api/users/{id}).

Filterung und Paginierung anbieten: Um die Effizienz zu steigern und große Datenmengen besser verwaltbar zu machen, sollten Endpunkte Optionen zur Filterung (/api/users?role=admin) und Paginierung (/api/users?page=1&limit=20) unterstützen.

Statuscodes korrekt verwenden: Jede API sollte standardisierte HTTP-Statuscodes für ihre Antworten nutzen, um eine eindeutige Interpretation zu gewährleisten. Beispielsweise signalisiert 200 OK, dass die Anfrage erfolgreich war, während 201 Created eine neu erstellte Ressource bestätigt. Fehlerhafte Anfragen sollten durch aussagekräftige Statuscodes wie 400 Bad Request (fehlerhafte Eingaben) oder 404 Not Found (nicht vorhandene Ressource) klar erkennbar sein.

Einheitliche und gut strukturierte Datenformate verwenden: JSON ist das bevorzugte Format für moderne APIs, da es leicht lesbar und effizient verarbeitet werden kann. Ein konsistentes Schema sollte beibehalten werden, um die Struktur verständlich zu machen. Beispielsweise sollte eine API für Benutzer immer das gleiche JSON-Format liefern:

{
  "id": 1,
  "name": "Max Mustermann",
  "email": "max@example.com"
}

Detaillierte Fehlerhinweise bereitstellen: Statt lediglich einen generischen 400 Bad Request Fehler zurückzugeben, sollte die API dem Client genau mitteilen, warum eine Anfrage fehlgeschlagen ist. Beispielsweise:

{
  "error": "Invalid email format",
  "field": "email",
  "suggestion": "Please provide a valid email address."
}

Pagination und Limitierung großer Datenmengen ermöglichen: APIs, die große Datenmengen zurückgeben, sollten Mechanismen zur Paginierung und Filterung implementieren. Beispielsweise könnte eine API folgende Abfrage unterstützen:

GET /users?page=2&limit=20

Caching nutzen, um Performance zu verbessern: Häufig genutzte Daten sollten gecacht werden, um unnötige API-Anfragen zu reduzieren. Durch das Setzen von Cache-Control-Headern kann der Server dem Client mitteilen, wie lange eine Antwort zwischengespeichert werden darf:

Cache-Control: max-age=3600, public

Einheitliche und verständliche Benennung: Namen für Business Types sollten klar, beschreibend und konsistent sein. Statt kryptischer oder abgekürzter Bezeichnungen wie CustOrd1 sollte eine verständliche Schreibweise wie CustomerOrder verwendet werden. Dies erleichtert die Lesbarkeit und reduziert Missverständnisse, insbesondere in größeren Entwicklungsteams oder bei der Integration mit anderen Systemen.

Wiederverwendbarkeit sicherstellen: Eine API sollte so gestaltet sein, dass ihre Komponenten mehrfach genutzt werden können, um Redundanzen zu vermeiden und die Wartbarkeit zu verbessern. Beispielsweise kann ein Address-Schema für Benutzer, Unternehmen und Lieferanten gleichermaßen verwendet werden. Statt separate Address-Modelle für jede Entität zu erstellen (UserAddress, CompanyAddress), sollte ein generisches Address-Schema implementiert werden, das flexibel in verschiedenen Kontexten eingesetzt werden kann. Dies erleichtert nicht nur die Pflege der API, sondern reduziert auch Inkonsistenzen bei der Datenverarbeitung.

Standardisierte Typen nutzen: Um eine konsistente und interoperable API zu gewährleisten, sollten standardisierte Datentypen verwendet werden. Beispielsweise sind UUIDs (Universally Unique Identifiers) ideal für eindeutige Identifikatoren, da sie sicherstellen, dass jeder Eintrag eine einzigartige und nicht vorhersehbare ID erhält. Für Datums- und Zeitangaben sollte der ISO 8601 Standard (YYYY-MM-DDTHH:MM:SSZ) genutzt werden, da er international verständlich und kompatibel mit den meisten Programmiersprachen ist. Dies verhindert Interpretationsfehler, insbesondere in Systemen, die mit verschiedenen Zeitzonen arbeiten. Ebenso können ISO 4217 für Währungsangaben und ISO 3166-1 alpha-2 für Ländercodes verwendet werden, um Einheitlichkeit sicherzustellen.

OAuth 2.0 für sichere Authentifizierung nutzen: OAuth 2.0 ist ein weit verbreiteter und sicherer Standard zur Autorisierung, der eine flexible Zugriffskontrolle ermöglicht. Es unterstützt verschiedene Grant-Typen, darunter den Authorization Code Flow für Webanwendungen und den Client Credentials Flow für serverseitige Anwendungen. Durch die Verwendung von OAuth 2.0 können APIs sicherstellen, dass nur autorisierte Clients Zugriff auf geschützte Ressourcen erhalten. Ein häufig eingesetztes Erweiterungsprotokoll ist OpenID Connect (OIDC), das eine Identitätsüberprüfung mit standardisierten Benutzerinformationen ermöglicht..

JWTs zur Vermeidung von serverseitigen Sitzungen einsetzen: JSON Web Tokens (JWTs) ermöglichen eine sichere und effiziente Authentifizierung ohne die Notwendigkeit serverseitiger Sitzungen. Ein JWT besteht aus drei Teilen: Header, Payload und Signature, die zusammen eine verschlüsselte und signierte Methode zur Überprüfung der Identität eines Nutzers bieten. JWTs sind besonders nützlich für skalierbare Anwendungen, da sie als stateless Tokens fungieren und den Overhead eines zentralen Session-Managements reduzieren. Sie sollten jedoch stets mit kurzen Ablaufzeiten (exp-Claim) versehen und sicher gespeichert werden, z. B. in HTTP-Only-Cookies, um Angriffe durch Token-Diebstahl zu vermeiden.

Tokens niemals in URLs übergeben, sondern in den Authorization-Header setzen: Die Übermittlung von Tokens in URLs birgt erhebliche Sicherheitsrisiken, da URLs in Browser-Historien, Server-Logs und Referrer-Headern gespeichert werden können. Stattdessen sollten Tokens immer sicher im Authorization-Header übergeben werden:

Authorization: Bearer <token>