API Schema lezen

Via de KampAdmin API kan je naast de eigenlijke data ook de velddefinities (schema) van een tabel opvragen. Dit is handig als je dynamisch wil weten welke velden beschikbaar zijn, wat hun type is, en welke waarden een keuzeveld kan bevatten, zonder dat je die informatie hard hoeft te coderen in jouw integratie.

Basis Schema-request

Een schema-request ziet er als volgt uit:

[GET] /api/v3/{tenant_id}/{table_name}/schema?token={api_token}

Parameters:

tenant_id: Jouw organisatie-ID.
table_name: De naam van de tabel waarvan je het schema wil opvragen, bijvoorbeeld activities.
api_token: Het unieke token dat aan de tabel is gekoppeld. Dit is hetzelfde token als dat je gebruikt voor het opvragen van records.

Opgelet:
Enkel tabellen en kolommen die geactiveerd zijn voor API-gebruik, worden weergegeven in de response. Kolommen die niet geactiveerd zijn, worden niet getoond maar worden wel meegeteld in counts.api_disabled.

Voorbeeldverzoek

[GET] /api/v3/dev_org/activities/schema?token={activities_api_token}

Response

De response is een JSON-object met drie onderdelen: de tabelnaam, een teloverzicht en een lijst van velden.

{
  "table": "activities",
  "counts": {
    "api_enabled": 5,
    "api_disabled": 12,
    "note": "12 column(s) on this table are not currently exposed via the API. Contact us to enable additional columns on request."
  },
  "fields": [
    {
      "key": "activity_name",
      "name": "Naam activiteit",
      "type": "text",
      "required": true,
      "description": null,
      "config": {}
    },
    {
      "key": "activity_price",
      "name": "Prijs",
      "type": "money",
      "required": false,
      "description": "Basisprijs in eurocent",
      "config": {}
    },
    {
      "key": "activity_type",
      "name": "Type",
      "type": "select",
      "required": false,
      "description": null,
      "config": {
        "options": [
          { "value": "day-camp", "label": "Dagkamp" },
          { "value": "residential", "label": "Residentieel kamp" }
        ]
      }
    }
  ]
}

Betekenis van de velden

table
De interne naam van de tabel.

counts

Veld	Beschrijving
`api_enabled`	Aantal kolommen dat momenteel via de API beschikbaar is.
`api_disabled`	Aantal kolommen op deze tabel dat niet via de API beschikbaar is, maar op aanvraag wel geactiveerd kan worden.
`note`	Leesbare toelichting bij `api_disabled`.

Via api_disabled weet je dus meteen of er nog extra velden beschikbaar zijn die je als integrator zou kunnen aanvragen. Neem hiervoor contact op via info@kampadmin.be.

fields — per veld:

Eigenschap	Type	Beschrijving
`key`	string	De interne sleutel die je gebruikt in API-lees requests en filters.
`name`	string	De leesbare naam van het veld (zoals getoond in de admin).
`type`	string	Het veldtype (zie overzicht hieronder).
`required`	boolean	Of dit veld verplicht is bij schrijfoperaties.
`description`	string \	null
`config`	object	Extra veldconfiguratie, afhankelijk van het type (zie hieronder).

Veldtypes

Het type-veld geeft aan hoe je de waarden in een records-response moet interpreteren:

Type	Beschrijving
`text`	Tekstveld (vrije invoer)
`textarea`	Meerdere regels tekst
`number`	Geheel getal
`money`	Geldbedrag in eurocent (integer)
`date`	Datum in `yyyy-mm-dd` formaat (UTC)
`datetime`	Datum en tijd in UTC
`boolean`	`true` of `false`
`select`	Eén waarde uit een vaste lijst (zie `config.options`)
`tags`	Meerdere waarden uit een vaste lijst (array)
`relation`	UUID van een gelinkt record
`file` / `image`	UUID van een bestand; op te halen via het image-endpoint

Het `config`-object

Niet elk veld heeft een config-object. Als config leeg ({}) is, zijn er geen extra parameters van toepassing. Hieronder de mogelijke sleutels:

options — bij select- en tags-velden
Een array van beschikbare keuzes, elk met value (de code die in de data staat) en label (de leesbare naam):

"config": {
  "options": [
    { "value": "day-camp", "label": "Dagkamp" },
    { "value": "residential", "label": "Residentieel kamp" }
  ]
}

Numerieke beperkingen — bij number- en money-velden

Sleutel	Beschrijving
`min`	Minimumwaarde
`max`	Maximumwaarde
`step`	Stapgrootte (bv. `1` of `0.5`)
`decimal`	`true` als decimalen toegelaten zijn

Tekstbeperkingen — bij text- en textarea-velden

Sleutel	Beschrijving
`minlength`	Minimum aantal tekens
`maxlength`	Maximum aantal tekens
`pattern`	Regex-patroon waaraan de waarde moet voldoen

Overige

Sleutel	Beschrijving
`is_image`	`true` als het bestand een afbeelding is (te gebruiken met het image-endpoint)
`accept`	Toegelaten bestandsextensies bij bestandsvelden (bv. `".pdf,.jpg"`)
`allow_null`	`true` als een lege waarde toegelaten is
`language`	Taalcode voor meertalige tekstvelden

Wanneer gebruik je dit endpoint?

Het schema-endpoint is vooral nuttig wanneer je een dynamische integratie bouwt die zich aanpast aan de veldconfiguratie van de organisatie, bijvoorbeeld:

Een formulier dat automatisch de juiste veldtypes en keuzelijsten toont.
Een mapping die key → label omzet voor het weergeven van gegevens.
Een validatielaag die required, min, max en pattern gebruikt vóór het versturen van data.

Voor statische integraties waar de velden gekend zijn, is een éénmalige raadpleging van het schema-endpoint voldoende om de configuratie te cachen.

Voor meer informatie, kan je steeds mailen naar info@kampadmin.be.