📋
← ZurĂŒck zu Anleitungen

JSON in REST-APIs verwenden: Best Practices

· Tags: json, rest-api, api-design, json-best-practices, pagination, web-development

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.

JSON in REST-APIs verwenden: Best Practices - CoolTool