API-Antwortformate: Best Practices für konsistente APIs

Inkonsistente API-Antworten gehören zu den häufigsten Beschwerden von Frontend-Entwicklern. Wenn jeder Endpunkt Daten in einer anderen Struktur zurückgibt, wird der Client-Code mit Sonderfällen übersät. Ein konsistentes Antwortformat verbessert die Entwicklererfahrung, reduziert Fehler und macht Ihre API selbstdokumentierend.

Der Response-Envelope

Verpacken Sie jede Antwort in eine konsistente Struktur:

Erfolg (Einzelne Ressource)

{
  "data": {
    "id": "user_123",
    "name": "Alice",
    "email": "alice@example.com",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Erfolg (Sammlung)

{
  "data": [
    { "id": "user_123", "name": "Alice" },
    { "id": "user_456", "name": "Bob" }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "perPage": 20,
    "requestId": "req_def456"
  }
}

Fehler

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  },
  "meta": {
    "requestId": "req_ghi789"
  }
}

Das Schlüsselprinzip: Clients prüfen immer auf data oder error auf der obersten Ebene. Mischen Sie niemals Erfolgsdaten und Fehlerinformationen in derselben Antwort.

Validieren Sie Ihr Antwortformat mit unserem JSON-Validator.

HTTP-Statuscodes

Verwenden Sie Statuscodes korrekt — sie sind das Erste, was Clients prüfen:

Erfolgscodes

Client-Fehlercodes

Server-Fehlercodes

Fehlerantwort-Design

Gute Fehlerantworten helfen Entwicklern beim schnellen Debuggen:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "User with ID 'user_999' not found",
    "details": [],
    "documentationUrl": "https://api.example.com/docs/errors#RESOURCE_NOT_FOUND"
  },
  "meta": {
    "requestId": "req_xyz789",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Regeln:

• code ist maschinenlesbar (konstanter String, kein HTTP-Status)
• message ist menschenlesbar (kann geändert werden, ohne Clients zu beeinträchtigen)
• details liefert feldspezifische Fehler bei Validierungsproblemen
• requestId ermöglicht dem Support-Team, die Anfrage in den Logs nachzuverfolgen

Paginierungsmuster

Offset-basiert

Einfach und unterstützt Sprünge zu beliebigen Seiten:

{
  "data": ["..."],
  "meta": {
    "page": 2,
    "perPage": 20,
    "total": 142,
    "totalPages": 8
  },
  "links": {
    "first": "/api/users?page=1&per_page=20",
    "prev": "/api/users?page=1&per_page=20",
    "next": "/api/users?page=3&per_page=20",
    "last": "/api/users?page=8&per_page=20"
  }
}

Cursor-basiert

Besser für Echtzeitdaten und große Datensätze:

{
  "data": ["..."],
  "meta": {
    "hasNext": true,
    "hasPrev": true
  },
  "links": {
    "next": "/api/users?cursor=eyJpZCI6MTQzfQ&limit=20",
    "prev": "/api/users?cursor=eyJpZCI6MTIzfQ&limit=20&direction=prev"
  }
}

Datum und Uhrzeit

Verwenden Sie immer ISO 8601 mit Zeitzoneninformation:

{
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:22:33+00:00",
  "expiresAt": "2024-12-31T23:59:59Z"
}

Verwenden Sie niemals:

• Unix-Zeitstempel (mehrdeutig: Sekunden oder Millisekunden?)
• Lokale Daten ohne Zeitzone
• Benutzerdefinierte Formate wie MM/TT/JJJJ

Mehr zur Zeitstempelverarbeitung finden Sie in unserem Unix-Zeitstempel-Leitfaden.

Null vs. fehlende Felder

Zwei gängige Ansätze:

Mit null einbeziehen (explizit):

{ "name": "Alice", "avatar": null, "bio": null }

Fehlende Felder weglassen (sparsam):

{ "name": "Alice" }

Empfehlung: Seien Sie innerhalb Ihrer API konsistent. Explizite Nullwerte sind besser für typisierte Sprachen (Clients wissen, dass das Feld existiert). Sparsam ist besser für bandbreitenbeschränkte Umgebungen.

Versionierung von Antworten

Wenn sich das Antwortformat ändert, versionieren Sie Ihre API:

GET /api/v2/users/123

Breaking Changes, die eine Versionierung erfordern:

• Entfernen eines Feldes
• Ändern eines Feldtyps
• Umbenennen eines Feldes
• Ändern der Response-Envelope-Struktur

Nicht-breaking Changes (sicher ohne Versionierung):

• Hinzufügen neuer Felder
• Hinzufügen neuer Endpunkte
• Hinzufügen neuer Enum-Werte

FAQ

Sollte ich erfolgreiche Antworten in einem data-Key verpacken oder die Ressource direkt zurückgeben?

Die Verwendung eines data-Wrappers bietet eine konsistente Struktur für alle Antworten und lässt Raum für Metadaten, Paginierung und Links neben den Daten. Die direkte Rückgabe der Ressource ist einfacher für Einzelressourcen-Endpunkte. Die meisten modernen APIs verwenden den Wrapper-Ansatz für Konsistenz.

Wie sollte ich Teilausfälle bei Batch-Operationen behandeln?

Geben Sie 200 mit einer Antwort zurück, die sowohl Erfolge als auch Fehler im data-Objekt enthält. Die Verwendung von 207 Multi-Status (WebDAV) ist eine weitere Option, wird aber seltener in REST-APIs verwendet.

Verwandte Ressourcen

• JSON-Formatierer — API-Antworten formatieren
• JSON-API-Designmuster — Umfassender API-Design-Leitfaden
• JSON-Schema-Validierung — Antwortstrukturen validieren