API Design Best Practices: REST-APIs, die Entwickler lieben

Eine API ist die Schnittstelle zwischen Systemen. Wenn sie gut designt ist, integrieren Entwickler sie in Stunden. Wenn sie schlecht designt ist, brauchen sie Tage – und fluchen dabei.

Die folgenden Best Practices basieren auf Jahren Erfahrung mit REST-APIs in Produktivsystemen. Keine akademische Theorie, sondern pragmatische Regeln, die in der Praxis funktionieren.

1. Konsistente URL-Struktur

Deine API-Endpunkte sollten vorhersagbar sein. Wenn ein Entwickler die Struktur einmal verstanden hat, sollte er jeden Endpunkt erraten können.

Gut:

GET    /api/v1/users          → Alle Nutzer
GET    /api/v1/users/42       → Nutzer #42
POST   /api/v1/users          → Neuen Nutzer anlegen
PATCH  /api/v1/users/42       → Nutzer #42 aktualisieren
DELETE /api/v1/users/42       → Nutzer #42 löschen

Schlecht:

GET    /api/getUsers
GET    /api/user?id=42
POST   /api/createNewUser
POST   /api/updateUser/42
GET    /api/removeUser/42

Regel: Nomen (Plural) für Ressourcen, HTTP-Methoden für Aktionen. Keine Verben in URLs.

2. Sinnvolle HTTP-Statuscodes

Verwende die richtigen Statuscodes. Schicke nicht für alles 200 OK mit einem Error-Flag im Body zurück.

Wichtig: 401 vs. 403 ist ein häufiger Fehler. 401 heißt: „Wer bist du?” 403 heißt: „Ich weiß wer du bist, aber du darfst das nicht.”

3. Einheitliches Error-Format

Jeder API-Fehler sollte das gleiche Format haben. Kein Ratespiel für den Entwickler, ob die Fehlermeldung im message-Feld, im error-Feld oder irgendwo anders steckt.

Empfohlenes Format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Die Eingabedaten sind ungültig.",
    "details": [
      {
        "field": "email",
        "message": "Ungültige E-Mail-Adresse."
      },
      {
        "field": "name",
        "message": "Name darf nicht leer sein."
      }
    ]
  }
}

Warum: Der Frontend-Entwickler kann Fehler direkt beim richtigen Formularfeld anzeigen. Der code ist maschinenlesbar (für i18n oder Error-Handling), die message ist menschenlesbar.

4. Pagination von Anfang an

Wenn eine Liste mehr als 20 Einträge haben kann, braucht sie Pagination. Immer. Ohne Ausnahme.

Cursor-basiert (empfohlen):

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6IDQyfQ==",
    "has_more": true
  }
}

Offset-basiert (einfacher, aber bei großen Datenmengen langsam):

{
  "data": [...],
  "pagination": {
    "total": 1542,
    "page": 3,
    "per_page": 20
  }
}

Warum Cursor statt Offset? Bei Offset-Pagination werden bei Seite 500 tatsächlich 10.000 Zeilen aus der Datenbank geladen und die ersten 9.980 verworfen. Cursor-Pagination ist O(1) unabhängig von der Position.

5. Versionierung

APIs ändern sich. Ohne Versionierung brichst du alle Clients, die deine API nutzen.

URL-Versionierung (pragmatisch):

/api/v1/users
/api/v2/users

Header-Versionierung (sauberer, aber aufwendiger):

Accept: application/vnd.myapi.v2+json

Für die meisten Projekte ist URL-Versionierung der richtige Ansatz. Einfach, offensichtlich, leicht zu testen.

Wichtig: Versioniere die gesamte API, nicht einzelne Endpunkte. Wenn v2 existiert, sollten alle Endpunkte unter /api/v2/ erreichbar sein – auch wenn sich nur einer geändert hat.

6. Authentifizierung richtig machen

Für Server-zu-Server: API-Keys im Header (Authorization: Bearer <key>). Einfach, sicher, bewährt.

Für User-facing APIs: OAuth 2.0 oder JWT. Niemals Passwörter im Klartext über die API senden.

Grundregeln:

• API-Keys gehören in Header, nie in die URL (Query-Parameter werden geloggt!)
• Tokens haben ein Ablaufdatum
• Rate Limiting ist Pflicht (z. B. 100 Requests/Minute pro Client)
• HTTPS ist nicht optional

7. Dokumentation, die aktuell bleibt

Die beste API ist nutzlos ohne Dokumentation. Aber statische Dokumentation veraltet sofort.

Lösung: OpenAPI (Swagger)

Definiere deine API als OpenAPI-Spec (YAML/JSON). Daraus generierst du:

• Interaktive Dokumentation (Swagger UI)
• Client-SDKs in jeder Sprache
• Automatisierte Tests

Bei Django: drf-spectacular oder drf-yasg generieren die Spec automatisch aus deinen Views und Serializers. Siehe auch: Django Performance: 10 Tipps für schnellere Web-Apps.

Minimum für jede API:

• Beschreibung jedes Endpunkts
• Request-/Response-Beispiele
• Fehlercodes und ihre Bedeutung
• Authentifizierung erklärt
• Rate Limits dokumentiert

8. Filtern, Sortieren, Suchen

Nutze Query-Parameter konsistent:

GET /api/v1/users?status=active&sort=-created_at&search=bayram&fields=id,name,email

• ?status=active → Filtern
• &sort=-created_at → Sortieren (Minus = absteigend)
• &search=bayram → Volltextsuche
• &fields=id,name,email → Nur bestimmte Felder zurückgeben (Sparse Fields)

Tipp: Implementiere nicht alles auf einmal. Starte mit Filtern und Sortieren. Sparse Fields und Suche kommen, wenn sie gebraucht werden.

Checkliste für dein nächstes API-Projekt

• [ ] Konsistente URL-Struktur (Nomen, Plural, keine Verben)
• [ ] Richtige HTTP-Statuscodes
• [ ] Einheitliches Error-Format
• [ ] Pagination für Listen
• [ ] API-Versionierung
• [ ] HTTPS + Auth im Header
• [ ] Rate Limiting
• [ ] OpenAPI-Dokumentation
• [ ] Request-/Response-Logging
• [ ] CORS korrekt konfiguriert

Fazit

Gutes API-Design ist keine Raketenwissenschaft. Es ist Konsistenz, Vorhersagbarkeit und Empathie für den Entwickler, der die API nutzen muss. Die Zeit, die du in sauberes Design investierst, sparst du bei jeder Integration zehnfach ein.

Du planst eine API oder möchtest eine bestehende verbessern? Wir designen und implementieren REST-APIs, die sich nahtlos in deine Systemlandschaft einfügen – sauber, dokumentiert und wartbar. Lies auch, wie du mit API-Schnittstellen deine Inselsysteme verbindest und warum CI/CD für professionelle API-Entwicklung unverzichtbar ist.