Wereldkundig API

Dit document beschrijft hoe je verbinding maakt met de Wereldkundig API.

Voor hier je url in

Wij vervangen in de onderstaande documentatie dan de variabele <url> met jouw waarde.

https://

Voor hier je Basic Auth-code in

Wij vervangen dan ook de variabele <base64_encoded_credentials> met jouw code.

Authenticatie

Authenticatie werkt met een Basic Auth-header.

We werken aan een functie waarmee je deze Basic Auth-code zelf kunt aanmaken.

Vraag deze aan via de supportafdeling.

Voeg deze header toe aan je request. <base64_encoded_credentials> is de code die je van ons ontvangt:

http

Authorization: Basic <base64_encoded_credentials>

Endpoints

Basis-URL: https://<url>/wp-json/wereldkundig

Methode	Pad	Beschrijving
GET	`/v1/subscribe/fields`	Haalt de velden op die nodig zijn in de body van het subscribe-POST-endpoint
POST	`/v1/subscribe`	Plaatst een inschrijving met opties

Vervang in de voorbeelden hieronder <url> en <base64_encoded_credentials> door je platform-url en Basic Auth-gegevens.

GET /v1/subscribe/fields

Haalt de velden en categorie-/thema-opties op die je moet gebruiken bij een POST naar /v1/subscribe.

curl -X GET "https://<url>/wp-json/wereldkundig/v1/subscribe/fields" \
  -H "Authorization: Basic <base64_encoded_credentials>" \
  -H "Accept: application/json"

POST /v1/subscribe

Voegt een abonnee toe of werkt een bestaande abonnee bij. De body moet altijd minimaal bevatten:

een geldig e-mailadres
één geldige categorie of één geldig thema

Ontbreekt dat, dan geeft de API een 400-fout terug.

Neem in het options-object alleen categorieën of thema’s op die je wilt bijwerken of toevoegen. Thema’s hebben het voorvoegsel theme- en categorieën category-, zoals geleverd door het GET-endpoint. Elke optie is true of false om aan te geven of die categorie of dat thema voor het e-mailadres moet worden toegevoegd of verwijderd.

Een geslaagde aanmaak of update geeft meestal HTTP 201 terug.

Request body

Voorbeeld body (zie spec.yaml):

json

{
  "email": "test@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "company": "ACME Inc.",
  "options": {
    "theme-1": true,
    "theme-2": false,
    "category-3": false,
    "category-4": true
  }
}

curl -X POST "https://<url>/wp-json/wereldkundig/v1/subscribe" \
  -H "Authorization: Basic <base64_encoded_credentials>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "test@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "company": "ACME Inc.",
    "options": {
      "theme-1": true,
      "theme-2": false,
      "category-3": false,
      "category-4": true
    }
  }'

Automatische selectie van gerelateerde categorieën en thema’s

Er draait automatische logica zodat de API hetzelfde gedrag heeft als het frontend-inschrijfformulier.

Voor nieuwsbrief- én persberichtplatforms

Als een oudercategorie met de sleutel select-all-x in options wordt meegegeven, worden gerelateerde kindcategorieën bij het opslaan genegeerd. Alle kindcategorieën van die ouder worden standaard geselecteerd wanneer select-all-x wordt meegegeven.

Alleen voor nieuwsbriefplatforms

Als categorieën als opties worden meegegeven, worden de bijbehorende ouderthema’s automatisch meegenomen (als die nog niet in options staan).
Als een thema zonder categorieën wordt meegegeven, worden alle categorieën die bij dat thema horen in het options-object opgenomen.

Specificatie

De specificatie is geschreven als OpenAPI 3-specificatie.

Je vindt de specificatie in het bestand spec.yaml. Om het te bekijken, kopieer de inhoud en plak die in de Swagger Editor.