REST API Response-Beispiele: So schreiben, dass Frontend-Teams sie direkt nutzen können

1. Warum schlechte Response-Strukturen Frontend-Teams blockieren

Eine REST API ist nicht fertig, wenn sie HTTP 200 zurückgibt. Sie ist fertig, wenn ein Frontend-Entwickler ohne Rückfragen an den Backend-Entwickler seinen Code schreiben kann. Das klingt nach einer weichen Anforderung, hat aber harte Konsequenzen: Jedes Mal, wenn ein Frontend-Team den Typ eines Feldes aus dem Kontext erschließen muss, kostet das Zeit. Jedes Mal, wenn ein Fehler-Response eine andere Struktur hat als der Erfolgs-Response, entsteht Sonderbehandlungscode im Frontend.

Das häufigste Problem in der Praxis ist Inkonsistenz. Eine Collection-Endpoint gibt ein Array direkt zurück, ein anderer gibt ein Objekt mit einem data-Schlüssel. Ein Fehler hat ein message-Feld, ein anderer hat error und description. Datumsfelder kommen mal als Unix-Timestamp, mal als ISO 8601-String, mal in einem lokalen Format. Aus Frontend-Sicht bedeutet das: jeder neue Endpoint erfordert einen neuen Blick in die Dokumentation, und die Dokumentation ist selten vollständig.

Die Lösung liegt nicht in einem bestimmten JSON-Format, sondern in Konventionen, die konsequent über alle Endpoints durchgehalten werden. Ein Frontend-Entwickler, der einmal verstanden hat, wie die API-Responses aufgebaut sind, sollte jeden neuen Endpoint integrieren können, ohne die Dokumentation zu lesen. Dieses Tutorial zeigt, wie man dahin kommt.

2. Das Envelope-Pattern: Konsistente Hülle für alle Responses

Das Envelope-Pattern umschließt alle API-Responses in eine einheitliche JSON-Hülle. Die Grundstruktur ist ein Objekt mit einem data-Schlüssel für die eigentliche Nutzlast, einem meta-Schlüssel für Pagination und andere Metadaten sowie einem errors-Schlüssel für Fehlerfälle. Diese Struktur gilt für jeden Endpoint, egal ob es sich um ein einzelnes Objekt, eine Collection oder eine leere Antwort handelt. Der Vorteil: Das Frontend weiß immer, wo es die Daten findet.

Ein häufiger Einwand gegen das Envelope-Pattern lautet, es erzeugt unnötige Verschachtelung für einfache Responses. Das stimmt für den einfachsten Fall, aber es gilt abzuwägen: Eine flache Struktur bei einfachen Responses erzeugt Inkonsistenz sobald man Pagination oder Metadaten hinzufügt. Das Envelope-Pattern investiert eine Ebene Verschachtelung, um dafür Konsistenz über alle Endpoints zu erhalten. In TypeScript bedeutet das eine einzige generische ApiResponse<T>-Typdefinition, die für jeden Endpoint funktioniert.

// Single resource — GET /api/v1/orders/42
{
  "data": {
    "id": "ord_7f3a9b2c",
    "status": "confirmed",
    "total": { "amount": 12490, "currency": "EUR", "formatted": "124,90 €" },
    "customer": { "id": "cus_1a2b3c", "email": "kunde@example.de" },
    "createdAt": "2026-05-09T14:22:00Z",
    "updatedAt": "2026-05-09T14:25:33Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "version": "1.0"
  }
}

// Collection — GET /api/v1/orders?page=2&per_page=25
{
  "data": [ /* array of order objects */ ],
  "meta": {
    "pagination": {
      "total": 247,
      "perPage": 25,
      "currentPage": 2,
      "lastPage": 10,
      "from": 26,
      "to": 50
    },
    "requestId": "req_def456"
  }
}

// Empty result — 204 No Content alternative
{
  "data": null,
  "meta": { "requestId": "req_ghi789" }
}

3. Fehlerformate nach RFC 9457: Problem Details

RFC 9457 (Problem Details for HTTP APIs) ist der aktuelle IETF-Standard für maschinenlesbare Fehlerformate in REST APIs. Er definiert ein JSON-Objekt mit genau fünf Feldern: type (URI, die den Fehlertyp eindeutig identifiziert), title (menschenlesbare Kurzbeschreibung), status (HTTP-Statuscode als Integer), detail (konkrete Beschreibung des Fehlers in dieser Instanz) und instance (URI der spezifischen Ressource, die den Fehler verursacht hat). Das Frontend kann anhand von type programmatisch auf Fehlerkategorien reagieren.

Das wichtigste Merkmal von RFC 9457 ist Erweiterbarkeit. Das Standard-Problem-Objekt kann mit eigenen Feldern angereichert werden, solange type, title und status vorhanden sind. Für Validierungsfehler ist es sinnvoll, ein violations-Array hinzuzufügen, das jeden einzelnen Feldvalidierungsfehler mit dem betroffenen Feld, dem verletzten Constraint und einer Meldung beschreibt. So kann das Frontend Fehlermeldungen direkt neben dem entsprechenden Formularfeld anzeigen, ohne selbst Fehler parsen zu müssen.

// HTTP 422 Unprocessable Entity — Validation error (RFC 9457)
// Content-Type: application/problem+json
{
  "type": "https://mironsoft.de/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request body contains 2 validation errors.",
  "instance": "/api/v1/orders",
  "violations": [
    {
      "field": "items[0].quantity",
      "constraint": "min",
      "message": "Menge muss mindestens 1 sein.",
      "rejectedValue": 0
    },
    {
      "field": "shippingAddress.postalCode",
      "constraint": "pattern",
      "message": "PLZ muss aus 5 Ziffern bestehen.",
      "rejectedValue": "1234"
    }
  ]
}

// HTTP 404 Not Found
{
  "type": "https://mironsoft.de/errors/resource-not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Order with ID ord_999xyz does not exist.",
  "instance": "/api/v1/orders/ord_999xyz"
}

// HTTP 429 Too Many Requests
{
  "type": "https://mironsoft.de/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded 100 requests per minute.",
  "instance": "/api/v1/orders",
  "retryAfter": 47
}

4. Typen explizit machen: Datumswerte, Enums und Nullability

Typisierung in JSON-APIs ist immer eine Konvention zwischen Server und Client, weil JSON selbst nur wenige Basistypen kennt. Die kritischen Felder sind Datumswerte, Enums und Felder, die null sein können. Datumswerte sollten ausnahmslos als ISO 8601 UTC-String übertragen werden ("2026-05-09T14:22:00Z"). Kein Unix-Timestamp, kein lokales Format, kein ambiguöses Datum ohne Zeitzone. Der Grund: Zeitzonen-Konvertierung gehört in das Frontend, nicht in die API. Die API liefert UTC, das Frontend konvertiert in die lokale Zeit des Benutzers.

Enums sollten als Strings übertragen werden, nicht als Integer. "status": "confirmed" ist im Netzwerk-Traffic selbstdokumentierend und bricht nicht, wenn sich die Reihenfolge der Enum-Werte ändert. Die vollständige Liste aller möglichen Enum-Werte gehört in die OpenAPI-Spezifikation als enum-Array. Felder, die null sein können, müssen explizit als nullable markiert sein – sowohl im OpenAPI-Schema als auch in Beispieldaten. Ein Frontend, das nie null für ein Feld in Testdaten gesehen hat, hat keinen Code für diesen Fall.

5. Pagination-Metadaten vollständig dokumentieren

Pagination-Metadaten sind eines der Felder, bei denen APIs häufig minimal dokumentiert sind, obwohl Frontend-Teams alle Informationen benötigen, um eine vollständige Paginierungskomponente zu bauen. Das Minimum für Offset-Pagination: Gesamtanzahl der Datensätze (total), aktuelle Seite (currentPage), letzte Seite (lastPage), Anzahl pro Seite (perPage) sowie erster und letzter Index der aktuellen Seite (from und to). Ohne total kann kein Seitennavigator gebaut werden. Ohne lastPage kann kein "Weiter"-Button korrekt disabled werden.

Für Cursor-basierte Pagination – sinnvoll bei großen Datensätzen oder Echtzeit-Feeds – gehören nextCursor und prevCursor in die Metadaten. Das Frontend setzt den Cursor als Query-Parameter für die nächste Anfrage. Wichtig: Der Cursor ist opak für das Frontend. Seine interne Struktur darf nicht dokumentiert werden und muss als stabiler, aber implementierungsabhängiger String betrachtet werden. Das verhindert, dass Frontend-Teams versehentlich auf die Cursor-Struktur bauen.

// Offset Pagination — GET /api/v1/products?page=3&per_page=20
{
  "data": [ /* 20 product objects */ ],
  "meta": {
    "pagination": {
      "total": 583,
      "perPage": 20,
      "currentPage": 3,
      "lastPage": 30,
      "from": 41,
      "to": 60,
      "links": {
        "first": "/api/v1/products?page=1&per_page=20",
        "prev":  "/api/v1/products?page=2&per_page=20",
        "next":  "/api/v1/products?page=4&per_page=20",
        "last":  "/api/v1/products?page=30&per_page=20"
      }
    }
  }
}

// Cursor Pagination — GET /api/v1/feed?cursor=eyJpZCI6MTAwfQ
{
  "data": [ /* feed items */ ],
  "meta": {
    "pagination": {
      "perPage": 25,
      "count": 25,
      "hasMore": true,
      "nextCursor": "eyJpZCI6MTI1fQ",
      "prevCursor": "eyJpZCI6NzV9"
    }
  }
}

6. Verschachtelte Ressourcen: Wann einbetten, wann verlinken?

Eine der häufigsten Designentscheidungen bei REST APIs ist, ob verwandte Ressourcen eingebettet oder als Link referenziert werden sollen. Die Faustregel: Wenn das Frontend die verwandte Ressource für jede Darstellung der Hauptressource benötigt, sollte sie eingebettet werden. Wenn die verwandte Ressource nur manchmal gebraucht wird oder eigenständig navigiert werden kann, sollte nur ein Link (die ID oder eine URL) übertragen werden. Einbetten spart Roundtrips, erhöht aber die Response-Größe und erzeugt Synchronisierungsprobleme, wenn sich die verwandte Ressource ändert.

Eine pragmatische Lösung ist das Compound-Document-Pattern, das JSON:API nutzt: Die Hauptressource enthält nur IDs für verwandte Ressourcen, und alle eingebetteten Objekte kommen in einem separaten included-Array. Das Frontend assembliert die Objekte selbst. Alternativ bietet der Query-Parameter ?include=category,images dem Frontend die Kontrolle, welche Relationen eingebettet werden. Beides ist besser als stille Einbettung ohne Opt-out, die zu übergroßen Responses führt.

7. Partial Responses und Feldselektion

Partial Responses erlauben dem Frontend, nur die Felder anzufordern, die es tatsächlich benötigt. Das Google-Muster nutzt den Query-Parameter ?fields=id,name,price. Das GraphQL-inspirierte Muster nutzt ?fields[product]=id,name&fields[category]=id,slug für verschachtelte Selektion. Beide Ansätze reduzieren die übertragene Datenmenge und CPU-Last für Serialisierung auf dem Server, besonders bei Endpoints, die viele große Objekte zurückgeben.

Wichtig: Partial Responses sind ein Optimierungsfeature, kein Ersatz für saubere Response-Struktur. Ein Endpoint mit schlechter Grundstruktur wird durch Feldselektion nicht besser. Die Dokumentation muss klar angeben, welche Felder selektion-fähig sind, und die OpenAPI-Spezifikation sollte für jeden Endpoint das vollständige Schema ohne Feldselektion als Baseline zeigen. Fehlerbehandlung für ungültige Feldnamen (?fields=nichtexistierendesfeld) sollte einen eindeutigen 400-Fehler zurückgeben, nicht den Wert stillschweigend ignorieren.

8. Realistische Beispieldaten statt Platzhalter

Der größte praktische Unterschied zwischen einer API-Dokumentation, die Frontend-Teams nutzen, und einer, die sie ignorieren, sind die Beispieldaten. "name": "string" oder "id": 1 sind für ein Frontend-Team nutzlos. Realistische Beispieldaten zeigen, wie die Daten im Produktionsbetrieb aussehen werden: echte Produktnamen, deutsche Adressen, typische Preiswerte, korrekte Datumsstempel im ISO-Format, Enum-Werte aus dem tatsächlichen Domänenmodell.

Besonders wichtig sind Randfälle in den Beispieldaten: Ein Produktname mit Sonderzeichen und Umlauten. Eine Adresse mit einem ungewöhnlich langen Straßennamen. Ein Preis von 0,00 EUR für kostenlose Produkte. Ein Array mit einem einzigen Element. Ein Array mit null Elementen. Ein optionales Feld, das null ist. Diese Fälle sollten in den OpenAPI-Beispielen als benannte examples dokumentiert sein, nicht nur als einzelne example. Das Frontend-Team testet damit seine Rendering-Logik, bevor es gegen das echte Backend entwickelt.

# OpenAPI 3.1 — Realistische Beispieldaten mit mehreren Szenarien
components:
  schemas:
    Order:
      type: object
      required: [id, status, total, createdAt]
      properties:
        id:
          type: string
          pattern: '^ord_[a-z0-9]{8}$'
          example: ord_7f3a9b2c
        status:
          type: string
          enum: [pending, confirmed, shipped, delivered, cancelled]
          example: confirmed
        total:
          $ref: '#/components/schemas/Money'
        note:
          type: string
          nullable: true
          description: Optionale Bestellnotiz des Kunden
          example: null
        createdAt:
          type: string
          format: date-time
          example: "2026-05-09T14:22:00Z"

  examples:
    OrderConfirmed:
      summary: Bestätigte Bestellung mit langer Notiz
      value:
        id: ord_7f3a9b2c
        status: confirmed
        total: { amount: 12490, currency: EUR, formatted: "124,90 €" }
        note: "Bitte nach 18 Uhr liefern — Bürogebäude geschlossen"
        createdAt: "2026-05-09T14:22:00Z"
    OrderNullNote:
      summary: Bestellung ohne Notiz (null-Feld Beispiel)
      value:
        id: ord_8a1c4d3e
        status: pending
        total: { amount: 0, currency: EUR, formatted: "0,00 €" }
        note: null
        createdAt: "2026-05-09T09:00:00Z"

9. Response-Formate im direkten Vergleich

Die Entscheidung für ein Response-Format hat langfristige Auswirkungen auf die Frontend-Entwicklung. Die folgende Tabelle vergleicht die häufigsten Anti-Patterns mit den empfohlenen Alternativen.

Die wichtigste Erkenntnis aus dieser Tabelle: Alle Anti-Patterns entstehen aus Kurzfristdenken. Ein Array direkt zurückgeben spart eine Ebene Verschachtelung heute, erzeugt aber einen Breaking Change sobald Pagination hinzukommt. Float für Geldbeträge funktioniert bis die erste Rundungsdifferenz in der Buchhaltung auftaucht. Die empfohlenen Patterns haben minimalen Mehraufwand bei der Implementierung, sparen aber vielfach mehr Zeit bei Integration und Fehlersuche.

10. Zusammenfassung

API-Responses, die Frontend-Teams direkt nutzen können, basieren auf vier Säulen: Konsistenz, Typisierung, vollständige Metadaten und realistische Beispieldaten. Das Envelope-Pattern stellt sicher, dass die Response-Hülle für jeden Endpoint gleich ist, egal ob es sich um eine einzelne Ressource, eine Collection oder einen Fehler handelt. RFC 9457 Problem Details liefern maschinenlesbare, erweiterbare Fehlerformate, die das Frontend programmatisch verarbeiten kann.

Pagination-Metadaten müssen vollständig sein – Gesamtanzahl, aktuelle Seite, letzte Seite und Links für alle Richtungen. Datumsfelder immer als ISO 8601 UTC-String, Geldbeträge als Integer-Cents mit formatiertem String, Enums als sprechende Strings. Und schließlich: OpenAPI-Beispieldaten müssen Randfälle zeigen – null-Felder, leere Arrays, Sonderzeichen, Grenzwerte. Nur wenn das Frontend diese Fälle in der Dokumentation sieht, schreibt es Code, der damit umgeht.

11. FAQ: REST API Response-Beispiele für Frontend-Teams