mijn.edudex.nl

Getting started voor afnemers en intermediairs

In dit document wordt door middel van voorbeelden het gebruik van de JSON API van EDU-DEX uitgelegd.

Authenticatie

Voor het gebruik van de API is een authenticatie-token vereist. Deze is aan te maken in de beheeromgeving van EDU-DEX via de applicatie "API-sleutels" en begint met 'secret-token:'. Het authenticatie-token moet worden meegegeven in de HTTP-header Authorization als bearer-token:

Authorization: bearer APITOKEN

Daarnaast is er voor het beheer van een organisatie nodig te weten wat het organisatie-id ervan is. Deze orgUnitId wordt verstrekt na inschrijving bij EDU-DEX.

Opzet van dit document

In dit document worden voorbeelden gegeven van het aanroepen van de verschillende API-calls. Hierbij wordt curl gebruikt om de API-calls via een command line aan te roepen. Hierbij wordt ervan uitgegaan dat het token zich in een environment variable genaamd APITOKEN bevindt. Daarnaast wordt in de voorbeelden 'voorbeeld' gebruikt als orgUnitId. jq is een utility die kan worden gebruikt om de teruggegeven JSON-data leesbaar te formatteren.

Een aanroep om het token en connectivity met de API te testen, het ophalen van de lijst van organisaties:

curl -s 'https://api.edudex.nl/data/v1/organizations' -H "Authorization: bearer $APITOKEN" | jq

Antwoord:

{
  "suppliers": [
    ...
    {
      "id": "voorbeeld",
      "name": {
        "nl": "voorbeeld"
      },
      "roles": [
        "client"
      ]
    }
    ...
  ]
}

Uitgebreide interactieve documentatie van alle beschikbare API-calls is bereikbaar via SwaggerUI. Om de calls in SwaggerUI aan te kunnen roepen, kan het API-token worden ingesteld via de knop 'Authorize'.

Opleidingen opvragen

Gebruik voor het ophalen van ingevoerde opleidingen de API-call POST /programs/bulk. Met deze API kunnen tot en met 100 opleidingen per keer worden opgevraagd.

Ophalen van de gegevens van de opleiding voorbeeld-opleiding:

curl -s -XPOST 'https://api.edudex.nl/data/v1/programs/bulk' \
      -H "Authorization: Bearer $APITOKEN" -H 'Content-Type: application/json' -d '
{
  "programs": [
    {
      "orgUnitId": "voorbeeld",
      "programId": "voorbeeld-opleiding",
      "clientId": "public"
    }
  ]
}' | jq

Antwoord:

{
  "programs": [
    {
      "programId": "voorbeeld-opleiding",
      "orgUnitId": "voorbeeld",
      "clientId": "public",
      "error": null,
      "data": {
        "editor": "editor@voorbeeld.nl",
        "expires": "2030-01-01",
        "format": "1.0",
        "generator": "curl",
        "inPublication": true,
        "lastEdited": "2023-12-01T12:34:56",
        "programAdmission": {
          "applicationOpen": true,
          "applicationType": "individual",
          "paymentDue": "up-front",
          "startDateDetermination": "fixed starting date"
        },
        "programClassification": {
          "degree": "Ad",
          "orgUnitId": "voorbeeld",
          "programDuration": {
            "years": 1
          },
          "programForm": [
            "full-time"
          ],
          "programId": "voorbeeld-opleiding",
          "programLevel": "hbo",
          "programLocation": [
            {
              "description": "Hoofdlocatie"
            }
          ],
          "programType": "regular"
        },
        "programContacts": {
          "contactData": []
        },
        "programCurriculum": {},
        "programDescriptions": {
          "programDescriptionText": {
            "nl": "Deze opleiding dient als voorbeeld voor het gebruik van de EDU-DEX JSON API."
          },
          "programName": {
            "nl": "Voorbeeldopleiding"
          },
          "programSummaryText": {
            "nl": "Dit is een voorbeeldopleiding"
          }
        },
        "programSchedule": {}
      }
    }
  ]
}

Catalogi

In de API zijn er twee types catalogi, handmatig ('static' in de API) en dynamisch ('dynamic' in de API). Een handmatige catalogus wordt met de hand beheerd, opleidingen worden door de gebruiker op individuele basis toegevoegd aan en verwijderd uit de catalogus. Een dynamische catalogus bevat alle opleidingen van een geselecteerde groep van opleiders (eventueel gefiltered op regio en het het aanwezig zijn van kortingen.)

In een catalogus wordt voor elke opleiding in de catalogus bijgehouden wanneer de gegevens per opleiding gewijzigd zijn, de opleiding verwijderd is dat deze weer is aangemaakt. In een handmatige catalogus worden de programIds van verwijderde opleidingen nog 90 dagen vastgehouden. Als in die periode de opleiding weer wordt opgevoerd door de opleider zal deze automatisch weer actief worden in de catalogus.

Statische catalogi

Opleidingen aan een statische catalogus worden toegevoegd op basis van de orgUnitId van de aanbieder en het programId van de opleiding. De aanbieder kan vervolgens een publieke opleiding beschikbaar hebben (clientId = "public") of een gespecialiseerde opleiding (clientId = orgUnitId van uw organisatie). Bij toevoegen op programId zal de API bepalen wat het clientId van de beschikbare opleiding is en deze teruggeven.

Op het moment kunnen opleidingen het beste via de web interface worden toegevoegd en verwijderd.

De lijst van huidige statische calogi kan worden opgevraagd met de API-call GET /organizations/{orgUnitId}/staticcatalogs.

curl -X 'GET' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/staticcatalogs' \
  -H "Authorization: Bearer $APITOKEN"

Antwoord:

{
  "catalogs": [
    {
      "catalogId": "05b3d0d5-b95d-4f4e-a076-8edd71737f7f",
      "title": "Voorbeeld statische catalogus",
      "clientId": "voorbeeld",
      "countActive": 0,
      "countTotal": 0
    }
  ]
}

Een nieuwe catalogus kan worden aangemaakt met POST /organizations/{orgUnitId}/staticcatalogs.

curl -X 'POST' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/staticcatalogs' \
  -H "Authorization: Bearer $APITOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "clientId": "voorbeeld",
  "title": "Voorbeeld statische catalogus"
}'

Antwoord:

{
  "catalogId": "05b3d0d5-b95d-4f4e-a076-8edd71737f7f",
  "title": "Voorbeeld statische catalogus",
  "clientId": "voorbeeld",
  "countActive": 0,
  "countTotal": 0
}

De gehele inhoud opvragen kan met GET /organizations/{orgUnitId}/staticcatalogs/{catalogId}/programs.

curl -X 'GET' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/staticcatalogs/05b3d0d5-b95d-4f4e-a076-8edd71737f7f/programs' \
  -H "Authorization: Bearer $APITOKEN"

Antwoord:

[
  {
    "status": "active",
    "supplierId": "voorbeeld-opleider",
    "programId": "voorbeeld-opleiding-1",
    "clientId": "public",
    "lastChange": "2024-01-02T03:04:05.000Z"
  }
]

Wijzigingen vanaf een bepaalde datum opvragen kan met GET /organizations/{orgUnitId}/staticcatalogs/{catalogId}/changes.

curl -X 'GET' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/staticcatalogs/05b3d0d5-b95d-4f4e-a076-8edd71737f7f/changes?changesSince=2024-01-01T01%3A02%3A03Z' \
  -H "Authorization: Bearer $APITOKEN"

Antwoord:

[
  {
    "status": "active",
    "supplierId": "voorbeeld-opleider",
    "programId": "voorbeeld-opleiding-1",
    "clientId": "public",
    "lastChange": "2024-01-02T03:04:05.000Z"
  },
  {
    "status": "removed",
    "supplierId": "voorbeeld-opleider",
    "programId": "verwijderde-opleiding",
    "clientId": null,
    "lastChange": "2024-02-03T04:05:06.111Z"
  }
]

Verwijderen can de catalogus gebeurt met de API-call DELETE /organizations/{orgUnitId}/staticcatalogs/{catalogId}.

curl -X 'DELETE' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/staticcatalogs/05b3d0d5-b95d-4f4e-a076-8edd71737f7f' \
  -H 'accept: */*' \
  -H "Authorization: Bearer $APITOKEN"

Dynamische catalogi

De lijst van huidige dhynamische calogi kan worden opgevraagd met de API-call GET /organizations/{orgUnitId}/dynamiccatalog.

curl -X 'GET' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/dynamiccatalogs' \
  -H "Authorization: Bearer $APITOKEN"

Antwoord:

{
  "catalogs": [
    {
      "catalogId": "a46b1790-b7f3-425f-8a2c-c4e593be5b0d",
      "title": "Voorbeeld dynamische catalogus",
      "clientId": "voorbeeld",
      "countActive": 0,
      "countTotal": 0
    }
  ]
}

Een nieuwe catalogus kan worden aangemaakt met POST /organizations/{orgUnitId}/dynamiccatalog.

curl -X 'POST' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/dynamiccatalogs' \
  -H "Authorization: Bearer $APITOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "clientId": "voorbeeld",
  "title": "Voorbeeld dynamische catalogus",
}'

Antwoord:

{
  "catalogId": "a46b1790-b7f3-425f-8a2c-c4e593be5b0d",
  "title": "Voorbeeld dynamische catalogus",
  "clientId": "voorbeeld",
  "countActive": 0,
  "countTotal": 0
}

De lijst van geselecteerde opleiders voor deze catalogus kan worden opgevraagd GET /organizations/{orgUnitId}/dynamiccatalog/{catalogId}/suppliers.

curl -X 'GET' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/dynamiccatalogs/a46b1790-b7f3-425f-8a2c-c4e593be5b0d/suppliers' \
  -H "Authorization: Bearer $APITOKEN"

Antwoord:

{
  "suppliers": [
    {
      "selection": "all",
      "supplierId": "voorbeeld-aanbieder"
    }
  ]
}

Een opleider kan worden toegevoegd/aangepast met PUT /organizations/{orgUnitId}/dynamiccatalog/{catalogId}/suppliers/{supplierId}.

curl -X 'PUT' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/dynamiccatalogs/a46b1790-b7f3-425f-8a2c-c4e593be5b0d/suppliers/voorbeeld-aanbieder' \
  -H "Authorization: Bearer $APITOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "selection": "all"
}'
Antwoord:
```json
{
  "selection": "all",
  "supplierId": "voorbeeld-aanbieder"
}

Een opleider kan worden verwijderd met DELETE /organizations/{orgUnitId}/dynamiccatalog/{catalogId}/suppliers/{supplierId}.

curl -X 'DELETE' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/dynamiccatalogs/a46b1790-b7f3-425f-8a2c-c4e593be5b0d/suppliers/voorbeeld-aanbieder' \
  -H 'accept: */*' \
  -H "Authorization: Bearer $APITOKEN"

De gehele inhoud opvragen kan met GET /organizations/{orgUnitId}/dynamiccatalog/{catalogId}/programs.

curl -X 'GET' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/dynamiccatalogs/a46b1790-b7f3-425f-8a2c-c4e593be5b0d/programs' \
  -H "Authorization: Bearer $APITOKEN"

Antwoord:

[
  {
    "status": "active",
    "supplierId": "voorbeeld-opleider",
    "programId": "voorbeeld-opleiding-1",
    "clientId": "public",
    "lastChange": "2024-01-02T03:04:05.000Z"
  }
]

Wijzigingen vanaf een bepaalde datum opvragen kan met GET /organizations/{orgUnitId}/dynamiccatalog/{catalogId}/changes.

curl -X 'GET' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/dynamiccatalogs/a46b1790-b7f3-425f-8a2c-c4e593be5b0d/changes?changesSince=2024-01-01T01%3A02%3A03Z' \
  -H "Authorization: Bearer $APITOKEN"

Antwoord:

[
  {
    "status": "active",
    "supplierId": "voorbeeld-opleider",
    "programId": "voorbeeld-opleiding-1",
    "clientId": "public",
    "lastChange": "2024-01-02T03:04:05.000Z"
  },
  {
    "status": "removed",
    "supplierId": "voorbeeld-opleider",
    "programId": "verwijderde-opleiding",
    "clientId": null,
    "lastChange": "2024-02-03T04:05:06.111Z"
  }
]

Verwijderen kan met DELETE /organizations/{orgUnitId}/dynamiccatalog/{catalogId}.

curl -X 'DELETE' \
  'https://api.edudex.nl/data/v1/organizations/voorbeeld/dynamiccatalogs/a46b1790-b7f3-425f-8a2c-c4e593be5b0d' \
  -H 'accept: */*' \
  -H "Authorization: Bearer $APITOKEN"

Webhooks

Per organisatie kunnen er maximaal 5 webhooks worden ingesteld, die worden aangeroepen als de inhoud van uw catalogi verandert. Deze webhooks worden voor alle catalogi van de organisatie aangeroepen, er kan geen selectie worden gemaakt.

Om een webhook aan te maken, dient er een publieke webserver te zijn met een URL die bereikt kan worden door de EDU-DEX server. Als er een wijziging is, zal de EDU-DEX server een HTTP POST request doen naar deze URL, met contenttype 'application/json' en als body een JSON bestand met de volgende structuur:

{
  "id": <uw organisatie-id>,
  "event": "catalog",
  "catalogs": [ { "type": <catalogustype, "static" of "dynamic">, "id": <catalogus-id> } ]
}

Als een webhook ontvangen wordt, moet er een respons worden teruggegeven met HTTP status code 200 om ontvangst te bevestigen. U kunt vervolgens met de API's /organizations/staticcatalogs/<catalogId>/changes?changesSince=<ISO8601 datetime> of/organizations/dynamiccatalogs/<catalogId>/changes?changesSince=<ISO8601 datetime> de wijzigingen ophalen vanaf de vorige keer dat u wijzigingen hebt opgehaald.

Wijzingen aan catalogi worden met een kleine vertraging verstuurd.

Toevoegen van een webhook

Open de applicatie 'API tokens'
Kies 'Webhooks' uit het menu.
Kies 'Toevoegen'.
Voer de HTTP URL in die aangeroepen moet worden.
Zorg dat de checkbox 'Catalogusupdates' aan staat.
Zorg dat de checkbox 'Actief' aan staat.
Druk op 'OK'.

Om de webhook te testen, klik op 'Testen'.