Geavanceerde JSON-structuren en ontwerppatronen

Geneste vs. Platte structuren

Gebalanceerde aanpak (Aanbevolen)

{
  "id": 1,
  "name": "John",
  "address": {
    "street": "123 Main St",
    "city": "NYC"
  },
  "contact": {
    "email": "john@example.com",
    "phone": "+1234567890"
  }
}

Vermijd overmatige nestificatie (>3-4 niveaus).

Normalisatie

Gedenormaliseerd (Ingebed)

{
  "orders": [
    {
      "id": 1,
      "customer": {
        "id": 101,
        "name": "Alice"
      }
    }
  ]
}

Gebruik dit wanneer gegevens vaak worden gelezen, maar zelden worden bijgewerkt.

Genormaliseerd (Referenties)

{
  "orders": [
    { "id": 1, "customerId": 101 }
  ],
  "customers": {
    "101": { "id": 101, "name": "Alice" }
  }
}

Gebruik dit wanneer gegevens regelmatig veranderen.

API-antwoordpatronen

Envelope Patroon

{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1
  }
}

Foutantwoord

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Ongeldige invoer",
    "details": [
      {
        "field": "email",
        "message": "Ongeldig formaat"
      }
    ]
  }
}

Paginering Patronen

Op offset gebaseerd

{
  "data": [...],
  "pagination": {
    "page": 2,
    "perPage": 20,
    "total": 156
  }
}

Op cursor gebaseerd

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTAwfQ==",
    "hasMore": true
  }
}

Polymorfe gegevens

Discriminator Patroon

{
  "notifications": [
    {
      "type": "email",
      "recipient": "user@example.com",
      "subject": "Hallo"
    },
    {
      "type": "sms",
      "phoneNumber": "+1234567890",
      "message": "Je code is 123456"
    }
  ]
}

Versionering

{
  "version": "2.0",
  "data": {
    "id": 1,
    "fullName": "John Doe"
  }
}

Event/Bericht Patronen

{
  "eventId": "evt_abc123",
  "eventType": "user.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0",
  "data": {
    "userId": 123
  }
}

Praktische tips

Naamgevingsconventies

{
  "userId": 1,       // camelCase (veelgebruikt in JavaScript)
  "user_id": 1       // snake_case (veelgebruikt in Python)
}

Wees consistent!

Datum/Tijd

{
  "createdAt": "2024-01-15T10:30:00Z"  // ISO 8601
}

Geld/Valuta

{
  "price": {
    "amount": 2999,    // In centen
    "currency": "EUR"
  }
}

HATEOAS Patroon

{
  "id": 1,
  "name": "Product",
  "links": {
    "self": "/api/products/1",
    "update": "/api/products/1",
    "delete": "/api/products/1"
  }
}

Bulk-operaties

{
  "operations": [
    { "op": "create", "data": {...} },
    { "op": "update", "id": 1, "data": {...} },
    { "op": "delete", "id": 2 }
  ]
}

Sparse Fieldsets (Beperkte velden)

GET /api/users?fields=id,name,email

{
  "data": [
    { "id": 1, "name": "Alice", "email": "alice@example.com" }
  ]
}

Conclusie

Een goed ontwerp van een JSON-structuur:

Houdt nestificatie in balans.

Normaliseert op basis van lees- en schrijfpatronen.

Gebruikt consistente patronen.

Voorziet de gegevens van een versie.

Volgt duidelijke naamgevingsconventies.

Een goed gestructureerde JSON maakt API's gemakkelijker te gebruiken en te onderhouden!