API Response structuur

API Response structuur

Alle API’s volgen dezelfde JSON-envelope voor succesvolle responses. Dit maakt parsing voorspelbaar voor elke client.

{
  "id": "<uuid-v4>",
  "params": { /* echo van de invoer */ },
  "data": { /* resultaat of lijst met resultaten */ },
  "error": {},
  "meta": {},
  "status": "success"
}

Top-level velden

Veld	Type	Verplicht	Uitleg
id	string	ja	Unieke request-/response-ID (UUID v4) voor correlatie en debugging.
params	object	nee	Echo van relevante invoerparameters (query/body/path). Kan genormaliseerde waarden bevatten (bijv. uppercase/trim).
data	object	ja	Het domeinspecifieke resultaat. Structuur verschilt per endpoint.
error	object	ja	Leeg object ({}) bij succesvolle responses. (Fouten worden beschreven onder Foutafhandeling hieronder.)
meta	object	nee	Metadata over de response (pagineringsinfo, cachehint, bron, etc.). Leeg als niet van toepassing.
status	string	ja	"success" bij succesvolle responses. Anders "failure".

Conventies

• Casing: camelCase voor alle veldnamen.

• Nullability: velden die (tijdelijk) onbekend zijn kunnen null zijn.

• Datums & tijden: ISO-8601 (YYYY-MM-DD of RFC3339 met tijdzone).

• Getallen: numeriek waar mogelijk (geen quotes rond numerieke waarden).

• Lists: volgorde is betekenisvol waar van toepassing; anders ongespecificeerd.

Foutafhandeling

Voor HTTP-fouten (4xx/5xx) gebruiken we dezelfde de envelope hierboven, maar enkele velden zoals meta , data , en params zullen leeg zijn. Zie de aparte pagina API Foutmeldingen. In het kort:

{
  "id": "<request-id>",
  "status": "failure",
  "error": {
    "code": 404,
    "message": "Not Found",
    "errors": [
      { "reason": "Not Found", "message": "The requested route or method was not found." }
    ]
  }
}

• 401 Unauthorized, 403 Forbidden, 404 Not Found, 503 Service Unavailable, etc.

• Deze responses bevatten CORS-headers.

Backwards-compatibiliteit

• De top-level velden van de envelope zijn stabiel. We kunnen velden toevoegen aan data en meta zonder dat dit een breaking change is.

• Onbekende 'error sleutels' dienen door clients genegeerd te worden.