JSON gebruiken in REST API's: Beste praktijken

JSON in REST API's

JSON en REST API's zijn een perfecte combinatie. JSON's lichtgewicht syntax, native array-ondersteuning en universele taalondersteuning maken het het standaardformaat voor moderne web-API's. Maar simpelweg JSON in je API gebruiken is niet genoeg -- het volgen van gevestigde conventies en beste praktijken zorgt ervoor dat je API consistent, intuïtief en eenvoudig te integreren is.

Verzoek- en Antwoordformaat

Consistente envelopstructuur

Gebruik een consistente JSON-envelop voor alle API-antwoorden. Dit maakt client-side verwerking voorspelbaar en vereenvoudigt de foutafhandeling.

{
  "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

Kies één naamgevingsconventie en houd je eraan in je hele API:

• Camel Case (createdAt, firstName): Gebruikelijk in JavaScript/TypeScript-ecosystemen
• Snake Case (created_at, first_name): Gebruikelijk in Python-, Ruby- en PHP-ecosystemen

Wat je ook kiest, documenteer het duidelijk en overweeg een transformatielaag te gebruiken als je backendtaal een andere conventie gebruikt.

HTTP-statuscodes met JSON

Correcte HTTP-statuscodes vullen je JSON-antwoorden aan. Gebruik ze consistent:

| Statuscode | Betekenis | Wanneer te gebruiken | |-------------|---------|-------------| | 200 OK | Succes | GET-, PUT-, PATCH-succes | | 201 Created | Resource aangemaakt | POST-succes | | 204 No Content | Verwijderingssucces | DELETE-succes (geen JSON-body) | | 400 Bad Request | Ongeldige JSON-syntax | Foutief gevormde verzoekbody | | 401 Unauthorized | Authenticatie vereist | Ontbrekend of ongeldig token | | 403 Forbidden | Onvoldoende rechten | Geldige authenticatie maar niet toegestaan | | 404 Not Found | Resource bestaat niet | Ongeldig ID of pad | | 422 Unprocessable Entity | Validatiefout | Semantische fouten in geldige JSON | | 429 Too Many Requests | Tarieflimiet bereikt | Client overschrijdt limieten | | 500 Internal Server Error | Serverfout | Onverwachte fouten |

Standaard foutantwoordformaat

{
  "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"
      }
    ]
  }
}

Geneste Resources

Relaties weergeven

REST API's moeten vaak gerelateerde resources weergeven. Hier zijn veelvoorkomende patronen:

Ingebed (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
      }
    ]
  }
}

Gerefereerd (lazy loading) -- gebruik ID's en bied afzonderlijke endpoints aan:

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

Vuistregel: Bed gerelateerde gegevens in die altijd samen nodig zijn. Referentieer gegevens die voorwaardelijk of op een ander moment worden opgehaald.

Pagineringspatronen

Bij het teruggeven van lijsten met resources is paginering essentieel. Gebruik een consistent pagineringsformaat:

Op offset gebaseerde paginering

{
  "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"
    }
  }
}

Op cursor gebaseerde paginering (aanbevolen voor grote datasets)

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

Op cursor gebaseerde paginering is betrouwbaarder voor realtime gegevens waarbij nieuwe records paginagrenzen kunnen verschuiven.

JSON in API-verzoeken

POST- / PUT-verzoeklichamen

Accepteer JSON met de Content-Type: application/json-header:

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

Gedeeltelijke updates met PATCH

Gebruik PATCH voor gedeeltelijke updates. Accepteer alleen de velden die moeten veranderen:

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

Filteren, sorteren en zoeken

Gebruik queryparameters voor gegevensmanipulatie en houd de JSON-body schoon:

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

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

Tariefbeperking

Neem informatie over tariefbeperking op in antwoordheaders en optioneel in de JSON-body:

{
  "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"
    }
  }
}

Checklist voor beste JSON-praktijken

• [ ] Gebruik consistente sleutelnaamgeving (camelCase of snake_case overal)
• [ ] Geef bij elk antwoord de juiste HTTP-statuscodes terug
• [ ] Gebruik een consistent foutformaat met machineleesbare foutcodes
• [ ] Pagineer lijstendpoints met een gestandaardiseerd pagineringsobject
• [ ] Gebruik JSON Schema om verzoek-/antwoordstructuren te documenteren en valideren
• [ ] Stel Content-Type: application/json in op alle JSON-endpoints
• [ ] Comprimeer JSON-antwoorden met gzip of brotli in productie
• [ ] Handhaaf maximale payloadgroottelimieten (bijv. 1MB standaard)
• [ ] Gebruik HTTPS om JSON-gegevens tijdens transport te versleutelen
• [ ] Structureer foutdetails zodat clients kunnen debuggen zonder interne zaken bloot te leggen

Je API-JSON valideren

Laat je API-antwoorden door een JSON-validator lopen om opmaakfouten te ontdekken voordat ze clients bereiken. Consistente, geldige JSON-antwoorden maken je API betrouwbaar en ontwikkelaarsvriendelijk. Gebruik onze JSON Formatter & Validator-tool om je payloads tijdens de ontwikkeling te testen.