API-Design: Best Practices für moderne Webanwendungen

Kurz gefasst: Gutes API-Design heißt, dass ein Entwickler Ihre Schnittstelle versteht, ohne den Quellcode zu lesen. Dazu gehören einheitliche Namen für Ressourcen, vorhersehbare Fehlerantworten, eine klare Versionierungsstrategie und eine Dokumentation, die aus dem Code selbst entsteht. Wer diese Regeln von Anfang an festlegt, spart sich später teure Brüche bei Frontend, Mobile-App und Partnerintegrationen.

Warum API-Design über die Lebensdauer einer Webanwendung entscheidet

Eine API ist ein Vertrag. Sobald ein Frontend, eine App oder ein externer Partner sie nutzt, lässt sich nicht mehr beliebig umbauen. Jede Änderung an Feldnamen oder Antwortstrukturen zieht Anpassungen auf der anderen Seite nach sich. Deshalb lohnt es sich, die Grundregeln festzulegen, bevor der erste Endpunkt live geht.

Für viele Unternehmen im Mittelstand ist die API außerdem der Weg, Systeme zu verbinden: Webshop, Warenwirtschaft, CRM. Wenn Sie in diese Richtung denken, lohnt ein Blick auf unseren Beitrag zur API-First-Strategie. Dort geht es um die geschäftliche Seite, hier um das Handwerk.

REST, GraphQL oder tRPC: die passende Schnittstelle wählen

REST als solider Standard

REST ist für öffentliche und partnerseitige Schnittstellen meist die richtige Wahl. Jedes HTTP-Werkzeug versteht es, Caching über HTTP funktioniert direkt, und die Konzepte sind jedem Backend-Entwickler bekannt. Ressourcen werden als Substantive im Plural benannt (/orders, /customers/42/invoices), die Aktion steckt in der HTTP-Methode.

GraphQL bei vielen unterschiedlichen Clients

GraphQL spielt seine Stärken aus, wenn mehrere Clients sehr unterschiedliche Daten brauchen, etwa eine Web-App und eine schlanke Mobile-App. Der Preis ist ein komplexeres Backend: Caching, Berechtigungen auf Feldebene und der Schutz vor teuren Abfragen müssen bewusst gelöst werden.

tRPC für interne TypeScript-Projekte

Wenn Frontend und Backend im selben TypeScript-Repository leben und niemand außer Ihrem eigenen Team die Schnittstelle nutzt, ist tRPC eine pragmatische Option. Typen fließen direkt vom Server zum Client, ohne separates Schema. Für externe Partner eignet sich das nicht.

Regeln, die eine API verständlich machen

Konsistente Namen und Formate

Entscheiden Sie sich für eine Schreibweise bei Feldnamen (zum Beispiel camelCase) und bleiben Sie dabei. Datumswerte gehören im ISO-8601-Format mit Zeitzone in die Antwort, Geldbeträge als ganze Cent-Werte oder als Dezimalstring, niemals als Fließkommazahl.

Fehler, mit denen man arbeiten kann

Eine Antwort mit Status 500 und dem Text "Error" hilft niemandem. Nutzen Sie die passenden Statuscodes (400 für ungültige Eingaben, 401 und 403 für fehlende Rechte, 404, 409 für Konflikte) und ein einheitliches Fehlerobjekt. Der Standard RFC 9457 ("Problem Details for HTTP APIs") gibt dafür ein bewährtes Format vor. Validierungsfehler sollten das betroffene Feld benennen, damit das Frontend die Meldung direkt am Eingabefeld anzeigen kann.

Paginierung und Filter von Anfang an

Listen-Endpunkte wachsen. Wer /orders ohne Paginierung ausliefert, hat irgendwann eine Antwort mit zehntausenden Einträgen. Cursor-basierte Paginierung ist bei großen, sich ändernden Datenmengen stabiler als Seitennummern, weil neue Einträge die Reihenfolge nicht verschieben.

Versionierung ohne Chaos

Bauen Sie Änderungen möglichst abwärtskompatibel: neue Felder hinzufügen ist unproblematisch, Felder entfernen oder umbenennen nicht. Für echte Brüche hat sich eine Version im Pfad (/v2/) bewährt, weil sie sichtbar und einfach zu routen ist. Alte Versionen sollten Sie mit Vorlauf ankündigen und erst abschalten, wenn die Nutzung nachweislich gegen null geht.

Sicherheit gehört in den Entwurf

Authentifizierung und Autorisierung sind Teil des API-Designs. Für Webanwendungen bewähren sich sichere Session-Cookies oder OAuth 2.0 mit kurzlebigen Tokens. Die Details haben wir in unserem Artikel zu Authentifizierung mit OAuth, JWT und Sessions beschrieben.

Ebenso wichtig: Prüfen Sie bei jedem Zugriff, ob der Nutzer genau diese Ressource sehen darf. Fehlende Objekt-Berechtigungsprüfungen gehören laut OWASP API Security Top 10 zu den häufigsten Schwachstellen überhaupt. Rate Limiting, Eingabevalidierung und eine saubere CORS-Konfiguration ergänzen das. Einen breiteren Überblick gibt unser Beitrag zu den Grundlagen der Web-Sicherheit.

Dokumentation, die aktuell bleibt

Handgeschriebene Dokumentation veraltet. Besser ist eine OpenAPI-Spezifikation, die entweder aus dem Code generiert wird oder als Quelle für Code und Validierung dient. In TypeScript-Projekten erzeugen Bibliotheken wie Zod zusammen mit passenden Generatoren Schema, Validierung und Dokumentation aus einer einzigen Definition. Ein interaktiver API-Explorer und ein paar realistische Beispielanfragen sparen Ihren Partnern viele Rückfragen.

Häufige Fragen (FAQ)

Brauchen wir für eine kleine Webanwendung überhaupt ein durchdachtes API-Design?

Ja, wenn auch in kleinem Umfang. Schon zwei Clients, etwa Web und App, profitieren von einheitlichen Fehlern und klaren Namen. Die Regeln kosten am Anfang wenig Zeit und ersparen später Umbauten.

Sollten wir REST oder GraphQL verwenden?

Für die meisten Geschäftsanwendungen und alle Partnerschnittstellen ist REST die einfachere und besser unterstützte Wahl. GraphQL lohnt sich, wenn viele unterschiedliche Clients sehr verschiedene Datenausschnitte brauchen und Ihr Team die zusätzliche Komplexität im Backend tragen kann.

Wie ändern wir eine API, ohne bestehende Integrationen zu brechen?

Erweitern Sie statt umzubauen: neue Felder und Endpunkte ergänzen, alte vorerst weiter bedienen. Für unvermeidbare Brüche führen Sie eine neue Version ein, kündigen die Abschaltung der alten rechtzeitig an und beobachten, wer sie noch nutzt.

Wie dokumentieren wir eine API am besten?

Mit einer OpenAPI-Spezifikation, die automatisch mit dem Code synchron bleibt. Ergänzen Sie sie um kurze Erklärungen zu Authentifizierung, Fehlerformat und Paginierung, denn genau diese Themen sorgen bei Integrationen für die meisten Rückfragen.

Fazit

Eine gute API fällt im Alltag kaum auf, weil sie sich so verhält, wie man es erwartet. Diese Vorhersehbarkeit entsteht durch wenige, früh festgelegte Regeln und die Disziplin, sie einzuhalten. Wenn Sie eine Webanwendung mit sauberer Schnittstelle planen, sprechen Sie mit uns über Webentwicklung.