JSON in REST-APIs verwenden: Best Practices

JSON in REST-APIs

JSON und REST-APIs sind eine perfekte Kombination. Die schlanke Syntax von JSON, die native Array-Unterstützung und die universelle Sprachunterstützung machen es zum Standardformat für moderne Web-APIs. Aber einfach nur JSON in Ihrer API zu verwenden, reicht nicht aus -- die Einhaltung etablierter Konventionen und Best Practices stellt sicher, dass Ihre API konsistent, intuitiv und einfach zu integrieren ist.

Anforderungs- und Antwortformat

Konsistente Envelope-Struktur

Übernehmen Sie eine konsistente JSON-Envelope für alle API-Antworten. Das macht die Verarbeitung auf Client-Seite vorhersehbar und vereinfacht die Fehlerbehandlung.

{
  "status": "success",
  "data": {
    "user": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    }
  },
  "meta": {
    "requestId": "req-a1b2c3d4",
    "timestamp": "2026-07-19T10:30:00Z"
  }
}

Snake Case vs. Camel Case

Wählen Sie eine Namenskonvention und bleiben Sie in Ihrer gesamten API konsequent dabei:

• Camel Case (createdAt, firstName): Häufig in JavaScript-/TypeScript-Ökosystemen
• Snake Case (created_at, first_name): Häufig in Python-, Ruby- und PHP-Ökosystemen

Welche Sie auch wählen, dokumentieren Sie sie klar und erwägen Sie eine Transformationsschicht, wenn Ihre Backend-Sprache eine andere Konvention verwendet.

HTTP-Statuscodes mit JSON

Passende HTTP-Statuscodes ergänzen Ihre JSON-Antworten. Verwenden Sie sie konsequent:

| Statuscode | Bedeutung | Wann verwenden | |-------------|---------|-------------| | 200 OK | Erfolg | GET-, PUT-, PATCH-Erfolg | | 201 Created | Ressource erstellt | POST-Erfolg | | 204 No Content | Löschung erfolgreich | DELETE-Erfolg (kein JSON-Body) | | 400 Bad Request | Ungültige JSON-Syntax | Fehlerhafter Anforderungstext | | 401 Unauthorized | Authentifizierung erforderlich | Fehlendes oder ungültiges Token | | 403 Forbidden | Unzureichende Berechtigungen | Gültige Authentifizierung, aber nicht erlaubt | | 404 Not Found | Ressource existiert nicht | Ungültige ID oder ungültiger Pfad | | 422 Unprocessable Entity | Validierungsfehler | Semantische Fehler in gültigem JSON | | 429 Too Many Requests | Rate-Limit erreicht | Client überschreitet Limits | | 500 Internal Server Error | Fehler auf Server-Seite | Unerwartete Fehler |

Standardformat für Fehlerantworten

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "age",
        "message": "Must be a positive integer",
        "code": "OUT_OF_RANGE"
      }
    ]
  }
}

Verschachtelte Ressourcen

Beziehungen darstellen

REST-APIs müssen häufig zusammenhängende Ressourcen darstellen. Hier sind gängige Muster:

Eingebettet (eager loading):

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customer": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    },
    "items": [
      {
        "productId": 42,
        "name": "Widget",
        "quantity": 2,
        "price": 14.99
      }
    ]
  }
}

Referenziert (lazy loading) -- IDs verwenden und separate Endpunkte bereitstellen:

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customerId": 123,
    "itemIds": [101, 102]
  }
}

Faustregel: Betten Sie zusammengehörige Daten ein, die immer zusammen benötigt werden. Referenzieren Sie Daten, die bedingt oder zu einem anderen Zeitpunkt abgerufen werden.

Paginierungsmuster

Beim Zurückgeben von Listen mit Ressourcen ist Paginierung unerlässlich. Verwenden Sie ein konsistentes Paginierungsformat:

Offset-basierte Paginierung

{
  "status": "success",
  "data": [
    { "id": 1, "name": "User 1" },
    { "id": 2, "name": "User 2" }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "totalItems": 156,
    "totalPages": 8,
    "links": {
      "first": "/api/users?page=1&perPage=20",
      "prev": null,
      "next": "/api/users?page=2&perPage=20",
      "last": "/api/users?page=8&perPage=20"
    }
  }
}

Cursor-basierte Paginierung (empfohlen für große Datensätze)

{
  "status": "success",
  "data": [
    { "id": 100, "name": "User 100" },
    { "id": 101, "name": "User 101" }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6MTAxfQ==",
    "hasMore": true
  }
}

Cursor-basierte Paginierung ist für Echtzeitdaten zuverlässiger, bei denen neue Datensätze die Seitengrenzen verschieben könnten.

JSON in API-Anforderungen

POST-/PUT-Anforderungstexte

Akzeptieren Sie JSON mit dem Header Content-Type: application/json:

{
  "title": "New Blog Post",
  "content": "This is the content...",
  "tags": ["json", "rest-api"],
  "published": false
}

Teilaktualisierungen mit PATCH

Verwenden Sie PATCH für Teilaktualisierungen. Akzeptieren Sie nur die Felder, die sich ändern sollen:

// PATCH /api/users/123
{
  "email": "newemail@example.com"
}

Filtern, Sortieren und Suchen

Verwenden Sie Query-Parameter für die Datenmanipulation, um den JSON-Body sauber zu halten:

GET /api/users?filter[role]=admin&sort=-createdAt&search=alice

{
  "status": "success",
  "data": [ /* filtered, sorted results */ ]
}

Rate Limiting

Nehmen Sie Informationen zum Rate Limit in die Antwort-Header und optional in den JSON-Body auf:

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  },
  "meta": {
    "rateLimit": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2026-07-19T11:00:00Z"
    }
  }
}

Checkliste für JSON-Best-Practices

• [ ] Verwenden Sie konsistente Schlüsselnamen (durchgängig camelCase oder snake_case)
• [ ] Geben Sie bei jeder Antwort passende HTTP-Statuscodes zurück
• [ ] Nehmen Sie ein konsistentes Fehlerformat mit maschinenlesbaren Fehlercodes auf
• [ ] Paginieren Sie Listen-Endpunkte mit einem standardisierten Paginierungsobjekt
• [ ] Verwenden Sie JSON Schema zum Dokumentieren und Validieren von Anforderungs-/Antwortstrukturen
• [ ] Setzen Sie Content-Type: application/json auf allen JSON-Endpunkten
• [ ] Komprimieren Sie JSON-Antworten in der Produktion mit gzip oder brotli
• [ ] Legen Sie maximale Payload-Größenbegrenzungen fest (z. B. 1MB Standard)
• [ ] Verwenden Sie HTTPS, um JSON-Daten während der Übertragung zu verschlüsseln
• [ ] Strukturieren Sie Fehlerdetails so, dass Clients debuggen können, ohne interne Details preiszugeben

Validieren Ihrer API-JSON

Lassen Sie Ihre API-Antworten durch einen JSON-Validator laufen, um Formatierungsfehler zu erkennen, bevor sie Clients erreichen. Konsistente, gültige JSON-Antworten machen Ihre API zuverlässig und entwicklerfreundlich. Verwenden Sie unser JSON-Formatter-&-Validator -Tool, um Ihre Payloads während der Entwicklung zu testen.