Zum Hauptinhalt springen

API-Design-Grundlagen

Eine API ist kein Transportmechanismus.

Sie ist ein Vertrag.

API-Design entscheidet über:

  • Kopplung zwischen Systemen
  • Änderbarkeit
  • Integrationskosten
  • Fehlerrisiko
  • organisatorische Reibung

Eine schlecht designte API skaliert Probleme.
Eine gute API stabilisiert Systeme.

1. API = Vertrag

Eine API ist:

  • eine öffentliche Schnittstelle
  • ein Stabilitätsversprechen
  • eine Abstraktionsgrenze

Wenn du eine API veröffentlichst, veröffentlichst du Verantwortung.

Deshalb gilt:

API-Design ist Architektur – nicht Implementation.

2. Die zentrale Frage

Nicht:

Wie bekomme ich Daten von A nach B?

Sondern:

Welche Verantwortung kapselt dieses System –
und wie exponiere ich sie minimal?

3. Grundprinzipien guten API-Designs

3.1 Konsistenz​

  • Einheitliche Namenskonventionen
  • Einheitliche Fehlerstruktur
  • Einheitliche Statuscodes
  • Einheitliche Versionierungsstrategie

Inkonsistente APIs erhöhen kognitive Last.

3.2 Klare Ressourcenmodellierung (REST-Kontext)​

  • Substantive statt Verben
  • Ressourcen statt Aktionen
  • Stabiler URI-Raum

Beispiel:


GET /orders/{id}
POST /orders

Nicht:


POST /createOrder
GET /getOrderById

Das ist kein Dogma – sondern Lesbarkeitsprinzip.

3.3 Minimale Exposition​

Expose:

  • nur notwendige Felder
  • keine internen IDs
  • keine Datenbankstruktur
  • keine Framework-Struktur

Eine API darf nicht dein internes Modell leaken.

3.4 Explizite Versionierung​

APIs ändern sich.

Fragen:

  • Wie breche ich Änderungen?
  • Wie lange unterstütze ich alte Versionen?
  • Ist Breaking Change bewusst oder versehentlich?

Fehlende Versionierung erzeugt Integrationschaos.

3.5 Fehlerdesign ist Teil des Designs​

Fehler sind keine Ausnahmefälle.

Gute APIs definieren:

  • klare Fehlercodes
  • maschinenlesbare Fehlerstruktur
  • konsistente Response-Formate

Wenn Fehler ad hoc entstehen, entsteht Integrationsunsicherheit.

3.6 Stabilität vor Perfektion​

Eine API muss nicht perfekt sein.

Aber sie muss stabil sein.

Breaking Changes ohne Governance sind Vertrauensbruch.

4. API-Kopplung verstehen

APIs erzeugen Kopplung auf mehreren Ebenen:

  • technische Kopplung
  • fachliche Kopplung
  • zeitliche Kopplung
  • organisatorische Kopplung

Beispiel:

Wenn zwei Teams für jede kleine API-Änderung synchronisieren müssen, ist die Grenze falsch geschnitten.

5. Anti-Pattern

❌ „CRUD-Expose-Alles“​

Direkte Datenbank-Exposition als API.

Folge:

  • interne Struktur wird extern stabilisiert
  • spätere Refactorings werden teuer

❌ Chatty APIs​

Viele kleine Calls statt klarer Ressourcen.

Folge:

  • Performanceprobleme
  • unnötige Netzwerkkomplexität

❌ Überladene Endpunkte​

Ein Endpoint mit zig optionalen Parametern.

Folge:

  • schwer testbar
  • schwer verständlich
  • unklare Verantwortlichkeit

❌ API als RPC-Wrapper​

Jede interne Methode wird nach außen gespiegelt.

Folge:

  • interne Logik wird Vertrag
  • Architektur wird extern eingefroren

6. API-Design und Abstraktionsgrenzen

APIs definieren Systemgrenzen.

Eine gute API:

  • kapselt Domänenlogik
  • reduziert Wissenstransfer
  • stabilisiert Teamgrenzen

Eine schlechte API:

  • spiegelt interne Strukturen
  • erzeugt Cross-Team-Abhängigkeiten
  • erhöht Kommunikationskosten

7. API-Governance

Ab Stufe 3+ sollten APIs:

  • versioniert
  • dokumentiert
  • getestet (Contract Tests)
  • reviewt
  • Breaking-Changes-gesteuert

werden.

Ohne Governance:

  • entstehen Wildwuchs-APIs
  • Integration wird teuer
  • Systeme fragmentieren

8. API-Design im Microservice-Kontext

Microservices erhöhen API-Volumen.

Ohne gutes API-Design:

  • steigen Koordinationskosten
  • entstehen zyklische Abhängigkeiten
  • fragmentiert Domänenlogik

Microservices multiplizieren API-Fehler.

9. Leitfragen für gutes API-Design

  • Welche Verantwortung kapselt dieser Service?
  • Exponieren wir intern verwendete Details?
  • Ist diese API langfristig stabil?
  • Können wir intern refactoren, ohne extern zu brechen?
  • Wie behandeln wir Breaking Changes?
  • Ist das Modell aus Sicht des Consumers verständlich?

Kerngedanke

APIs sind keine technischen Details.

Sie sind:

  • Verträge
  • Organisationsgrenzen
  • Stabilitätsversprechen

Gutes API-Design reduziert:

  • Integrationskosten
  • Team-Reibung
  • Änderungsrisiken
  • technische Schulden

Schlechtes API-Design konserviert Fehler über Jahre.

Und nichts ist teurer als eine falsch designte öffentliche Schnittstelle.