Getting started voor aanbieders

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/suppliers' -H "Authorization: bearer $APITOKEN" | jq

Antwoord:

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

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'.

Invoeren van opleidingen

  1. Begin met het opstellen van de JSON-documenten. Deze moeten voldoen aan het JSON-schema voor opleidingen, dat te vinden is bij de request body van de API-call PUT /suppliers/{orgUnitId}/programs/{programId}/{clientId}.

  2. Test documenten met de API-call POST /validations/programs. Zet het document in de data-property van de request body.

    Voorbeeld van een valide programma:

    curl -s -XPOST 'https://api.edudex.nl/data/v1/validations/programs' \
     -H "Authorization: Bearer $APITOKEN" -H 'Content-Type: application/json' -d '
{
  "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": {
    }
  }
}' | jq

    Antwoord:

    {
  "validates": true,
  "validationMessages": []
}

    Als er validatiefouten zijn, staan de foutmeldingen in validationMessages, bijvoorbeeld:

    {
  "validates": false,
  "validationMessages": [
    {
      "level": "error",
      "forClient": null,
      "message": "must have required property 'editor'",
      "contextPath": "",
      "ruleName": "json-schema",
      "params": {
        "missingProperty": "editor"
      }
    }
  ]
}

  3. Gebruik voor invoeren van de opleiding de API-call PUT /suppliers/{orgUnitId}/programs/{programId}/{clientId}. Gebruik voor parameters de volgende waardes:

    • orgUnitId: toegekende orgUnitId bij aanmelding van de organisatie

    • programId: URL-geëncodeerde programId (dus opleiding 1 wordt opleiding%20).

    • clientId: gebruik voor maatwerk opleidingen de orgUnitId van de afnemer zoals geregistreerd bij EDU-DEX (met URL-encoding, dus rio/stap wordt rio%2Fstap), en gebruik public voor publiek toegankelijke opleidingen. In het eerste geval moet het clientId-element in de opleiding ook gevuld zijn met de orgUnitId van de client.

    Voorbeeld van het toevoegen van de opleiding die hierboven is gevalideerd:

    curl -s -XPUT 'https://api.edudex.nl/data/v1/suppliers/voorbeeld/programs/voorbeeld-opleiding/public' \
     -H "Authorization: Bearer $APITOKEN" -H 'Content-Type: application/json' -d '
{
  "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": {
  }
}' | jq

    Antwoord:

    {
  "status": "ok",
  "validationMessages": []
}

  4. Het overzicht van ingevoerde opleidingen is te vinden op GET /suppliers/{orgUnitId}/programs.

    Het in het bovenstaande voorbeeld toegevoegde programma is nu terug te vinden in de lijst van opleidingen:

    curl -s 'https://api.edudex.nl/data/v1/suppliers/voorbeeld/programs' \
     -H "Authorization: Bearer $APITOKEN" | jq

    Antwoord:

    {
  "items": [
    {
      "orgUnitId": "voorbeeld",
      "programId": "voorbeeld-opleiding",
      "clientId": "public"
    }
  ]
}

  5. Gebruik voor het ophalen van ingevoerde opleidingen de API-call POST /programs/bulk.

    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": {}
      }
    }
  ]
}

Invoeren van kortingen op publieke opleidingen

  1. Begin met het opstellen van de JSON-documenten. Deze moeten voldoen aan het JSON-schema voor kortingen, dat te vinden is bij de request body van de API-call PUT /suppliers/{orgUnitId}/discounts/{clientId}.

  2. Test documenten met de API-call POST /validations/discounts. Zet het document in de data-property van de request body.

    Voorbeeld van een valide korting:

    curl -s -XPOST 'https://api.edudex.nl/data/v1/validations/discounts' \
     -H "Authorization: Bearer $APITOKEN" -H 'Content-Type: application/json' -d '
{
  "data": {
    "clientId": "afnemer",
    "discount": [
      {
        "amount": "100",
        "costType": "tuition fee",
        "programId": ["voorbeeld-opleiding"]
      },
      {
        "percentage": "10",
        "costType": "examination",
        "programId": ["voorbeeld-opleiding"]
      }
    ],
    "editor": "editor@voorbeeld.nl",
    "expires": "2030-01-01",
    "format": "1.0",
    "generator": "curl",
    "lastEdited": "2023-12-01T12:34:56",
    "orgUnitId": "voorbeeld"
  }
}' | jq

    Antwoord:

    {
  "validates": true,
  "validationMessages": []
}

  3. Voor invoeren van het document gebruik de API-call PUT /suppliers/{orgUnitId}/discounts/{clientId}. Gebruik voor parameters de volgende waardes:

    • orgUnitId: toegekende orgUnitId bij aanmelding van de organisatie

    • clientId: gebruik hier de orgUnitId van de afnemer zoals geregistreerd bij EDU-DEX (met URL-encoding, dus rio/stap wordt rio%2Fstap). Het clientId-element in de korting moet ook gevuld zijn met de orgUnitId van de client.

    Voorbeeld van het aanmaken van een korting voor een afnemer:

    curl -s -XPUT 'https://api.edudex.nl/data/v1/suppliers/voorbeeld/discounts/afnemer' \
     -H "Authorization: Bearer $APITOKEN" -H 'Content-Type: application/json' -d '
{
  "clientId": "afnemer",
  "discount": [
    {
      "amount": "100",
      "costType": "tuition fee",
      "programId": ["voorbeeld-opleiding"]
    },
    {
      "percentage": "10",
      "costType": "examination",
      "programId": ["voorbeeld-opleiding"]
    }
  ],
  "editor": "editor@voorbeeld.nl",
  "expires": "2030-01-01",
  "format": "1.0",
  "generator": "curl",
  "lastEdited": "2023-12-01T12:34:56",
  "orgUnitId": "voorbeeld"
}' | jq

    Antwoord:

    {
  "status": "ok",
  "validationMessages": []
}

  4. Het overzicht van alle ingevoerde kortingen is te vinden via de API-call GET /suppliers/{orgUnitId}/discounts.

    Voorbeeld van deze call:

    curl -s 'https://api.edudex.nl/data/v1/suppliers/voorbeeld/discounts' \
     -H "Authorization: Bearer $APITOKEN" | jq

    Antwoord:

    {
  "items": [
    {
      "orgUnitId": "voorbeeld",
      "clientId": "afnemer"
    },
    {
      "orgUnitId": "voorbeeld",
      "clientId": "andere-afnemer"
    }
  ]
}

  5. Gebruik voor het ophalen van ingevoerde kortingen voor een specifieke afnemener de API-call GET /suppliers/{orgUnitId}/discounts/{clientId}.

    Voorbeeld van de ingevoerde kortingen voor afnemer:

    curl -s 'https://api.edudex.nl/data/v1/suppliers/voorbeeld/discounts/afnemer' \
     -H "Authorization: Bearer $APITOKEN" | jq

    Antwoord:

    {
  "clientId": "afnemer",
  "discount": [
    {
      "amount": "100",
      "costType": "tuition fee",
      "programId": [
        "voorbeeld-opleiding"
      ]
    },
    {
      "percentage": "10",
      "costType": "examination",
      "programId": [
        "voorbeeld-opleiding"
      ]
    }
  ],
  "editor": "editor@voorbeeld.nl",
  "expires": "2030-01-01",
  "format": "1.0",
  "generator": "curl",
  "lastEdited": "2023-12-01T12:34:56",
  "orgUnitId": "voorbeeld"
}

Verwijderen van gegevens

Voor het verwijderen van gegevens wordt de POST-methode gebruikt. Calls die daarmee worden aangeroepen geven geen data terug, maar bij een succesvolle verwijdering wordt de HTTP-statuscode 204 No Content teruggestuurd.

  1. Voor het verwijderen van de kortingen gebruik de API-call DELETE /suppliers/{orgUnitId}/discounts/{clientId}.

    Verwijderen van de korting voor afnemer:

    curl -i -XDELETE 'https://api.edudex.nl/data/v1/suppliers/voorbeeld/discounts/afnemer' \
     -H "Authorization: Bearer $APITOKEN"

    De korting wordt nu niet meer teruggegeven (alleen de korting voor de andere-afnemer is nog aanwezig):

    curl -s 'https://api.edudex.nl/data/v1/suppliers/voorbeeld/discounts' \
     -H "Authorization: Bearer $APITOKEN" | jq

    Antwoord:

    {
  "items": [
    {
      "orgUnitId": "voorbeeld",
      "clientId": "andere-afnemer"
    }
  ]
}

  2. Voor het verwijderen van de opleiding gebruik de API-call DELETE /suppliers/{orgUnitId}/programs/{programId}/{clientId}.

    Verwijderen van de voorbeeldopleiding:

    curl -i -XDELETE 'https://api.edudex.nl/data/v1/suppliers/voorbeeld/programs/voorbeeld-opleiding/public' \
     -H "Authorization: Bearer $APITOKEN"

    De opleiding wordt nu niet meer teruggegeven:

    curl -s 'https://api.edudex.nl/data/v1/suppliers/voorbeeld/programs' \
     -H "Authorization: Bearer $APITOKEN" | jq

    Antwoord:

    {
  "items": []
}

Aanpassen van de metadata

  1. Begin met het opstellen van de JSON-documenten. Deze moeten voldoen aan het JSON-schema voor instituutsgegevens, dat te vinden is bij de request body van de API-call PUT /suppliers/{orgUnitId}/metadata.

  2. Test documenten met de API-call POST /validations/institutes. Zet het document in de data-property van de request body.

    Voorbeeld van valide metadata:

    curl -s -XPOST 'https://api.edudex.nl/data/v1/validations/institutes' \
     -H "Authorization: Bearer $APITOKEN" -H 'Content-Type: application/json' -d '
{
  "data": {
    "editor": "editor@voorbeeld.nl",
    "expires": "2030-01-01",
    "format": "1.0",
    "generator": "curl",
    "instituteName": {
      "en": "Example organisation",
      "nl": "Voorbeeldorganisatie"
    },
    "lastEdited": "2023-12-01T12:34:56",
    "orgUnitId": "voorbeeld"
  }
}' | jq

    Antwoord:

    {
  "validates": true,
  "validationMessages": []
}

  3. Gebruik voor het aanpassen van de metadata van de organisatie de API-call PUT /suppliers/{orgUnitId}/metadata. Let erop dat dit geen patch is, dus ook alle gegevens die niet zijn gewijzigd, moeten worden opgestuurd!

    Voorbeeld van het toevoegen van een Engelse naam:

    curl -s -XPUT 'https://api.edudex.nl/data/v1/suppliers/voorbeeld/metadata' \
     -H "Authorization: Bearer $APITOKEN" -H 'Content-Type: application/json' -d '
{
  "editor": "editor@voorbeeld.nl",
  "expires": "2030-01-01",
  "format": "1.0",
  "generator": "curl",
  "instituteName": {
    "en": "Example organisation",
    "nl": "Voorbeeldorganisatie"
  },
  "lastEdited": "2023-12-01T12:34:56",
  "orgUnitId": "voorbeeld"
}' | jq

    Antwoord:

    {
  "status": "ok",
  "validationMessages": []
}

  4. Gebruik voor het ophalen van de zelf ingevoerde metadata de API-call GET /suppliers/{orgUnitId}/metadata. Deze geeft de gegevens terug zoals ingevoerd.

    De toegevoegde Engelse naam wordt nu teruggegeven:

    curl -s 'https://api.edudex.nl/data/v1/suppliers/voorbeeld' \
     -H "Authorization: Bearer $APITOKEN" | jq

    Antwoord:

    {
  "id": "voorbeeld",
  "name": {
    "en": "Example organisation",
    "nl": "Voorbeeldorganisatie"
  }
}

    De uiteindelijke set van accreditaties (inclusief zoals ingevoerd in EDU-DEX door accreditaties kan worden bekeken via de API-call GET /organizations/{orgUnitId}.

    Hiermee worden ook de rollen van de afnemer teruggegeven:

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

    Antwoord:

    {
  "id": "voorbeeld",
  "name": {
    "en": "Example organisation",
    "nl": "Voorbeeldorganisatie"
  },
  "roles": [
    "supplier"
  ]
}