Collecties

Zodra je aan de slag gaat met je eigen API, begin je bij het hart van het systeem: de collecties. Dit zijn de onderdelen waarin je vastlegt wat voor soort gegevens je wilt opslaan en gebruiken in je app. Of je nu een webshop, bibliotheek of blog bouwt — alles draait om collecties. Ze bepalen welke informatie beschikbaar is, hoe die eruitziet en hoe alles met elkaar samenhangt.

Wat is een collectie?

Een collectie is een groep gegevens van hetzelfde type — ook wel een entiteit genoemd. Een entiteit is een representatie van een generiek stukje data. Denk bijvoorbeeld aan een product: hier zal een webshop er waarschijnlijk tientallen of honderden van hebben. Elk item in de product-collectie heeft dezelfde opbouw (zoals name, price en description) maar de waardes die erin komen te staan zijn voor ieder item anders (t-shirts, broeken, etc.). Wanneer klanten een account bij onze webshop aanmaken, willen we dat er naast e-mailadres en wachtwoord ook adresgegevens worden opgeslagen, dus hebben we ook een customer-collectie nodig. Wanneer zo'n klant een aankoop doet, verzamelen we één of meerdere producten in een bestelling, dus hebben we ook een order-collectie nodig. Zo bestaan er nog veel meer mogelijkheden, denk bijvoorbeeld aan:

  • Een collectie products voor een webshop, met velden zoals naam, prijs en voorraad
  • Een collectie posts voor een blogplatform, met titel, inhoud en auteur
  • Een collectie orders voor bestellingen, met klantinformatie, productregels en status

Zelf collecties definiëren

In de NOVI Dynamic API definieer je collecties via het collections-gedeelte in je JSON-configuratiebestand. Elke collectie bevat minimaal drie onderdelen:

  • name: de naam van de collectie (bijvoorbeeld "products")
  • fields: een lijst met velden die beschrijven welke informatie elk item bevat
  • permissions: toegangsrechten per rol (bijv. wie mag lezen, schrijven of verwijderen)

Voorbeeld:

{
  "collections": [
    {
      "name": "products",
      "fields": [
        // Zie hoofdstuk 'Velden'
      ],
      "permissions": {
        // Zie hoofdstuk 'Rollen en Permissies'
      }
    }
  ]
}

Een goede naam voor je collectie zorgt voor duidelijkheid en consistentie. Houd je daarom aan deze regels:

  • Gebruik altijd meervoud voor collectienamen (products, posts, orders)
  • Gebruik kleine letters en eventueel underscores (order_items)
  • Kies beschrijvende namen die direct duidelijk maken wat de collectie bevat
  • Gebruik altijd Engelse termen voor collectie- en veld-namen. De waardes die je erin opslaat mag je uiteraard in het Nederlands beschrijven.

Voorbeeld: webshopcollecties

Hieronder zie je hoe je meerdere collecties maakt voor een webshop. In dit voorbeeld werken we met producten, categorieën, bestellingen en klanten:

{
  "collections": [
    {
      "name": "products",
      "fields": [],
      "permissions": {}
    },
    {
      "name": "categories",
      "fields": [],
      "permissions": {}
    },
    {
      "name": "orders",
      "fields": [],
      "permissions": {}
    },
    {
      "name": "customers",
      "fields": [],
      "permissions": {}
    }
  ]
}

Ontwerptips voor collecties

Het ontwerp van je collecties is bepalend voor de structuur en flexibiliteit van je API. Hieronder vind je vier praktische richtlijnen om een goed doordacht datamodel op te zetten.

  1. Splits gegevens logisch op

Voorkom dat je álle data in één collectie stopt. Maak in plaats daarvan een aparte collectie voor elk type entiteit. Stel: je bouwt een applicatie waarin gebruikers blogposts kunnen plaatsen met reacties daaronder. Dan maak je één collectie voor posts en een aparte collectie voor comments. Zet dus niet gebruikers, berichten en reacties samen in één lijst — houd het gescheiden en overzichtelijk.

  1. Denk in relaties

Bedenk welke collecties met elkaar verbonden zijn en hoe die relaties eruitzien. Een bestelling hoort bijvoorbeeld bij één klant en bevat één of meerdere producten. In de collectie orders kun je dan een veld customerId opnemen dat verwijst naar een item in de customers-collectie. Let op: voorkom cirkelverwijzingen. Als een bestelling al verwijst naar een klant, hoeft de klant niet óók weer te verwijzen naar al zijn bestellingen.

  1. Houd gebruikersinformatie gescheiden van gebruikersaccounts

De ingebouwde gebruikersstructuur van de API bevat standaard alleen e-mailadres, wachtwoord en rol. Wil je extra profielinformatie opslaan — zoals een profielfoto, gebruikersnaam, adres of voorkeuren — maak dan een aparte collectie aan, bijvoorbeeld profiles. Deze koppel je aan een gebruiker via een userId-veld. Zo houd je de logingegevens en de gebruikersdata netjes gescheiden.

  1. Houd het simpel en beheersbaar

Begin klein. Voeg alleen collecties toe die je daadwerkelijk nodig hebt in je eerste versie. Heb je nog geen reactie-fuctionaliteit voor onder je blogposts? Dan hoef je ook nog geen comments-collectie aan te maken. Je kunt die later altijd toevoegen als je app zich uitbreidt.

In de volgende hoofdstukken leer je hoe je velden toevoegt aan collecties, hoe je gegevens toevoegt en gebruikersrollen creeërt.