Er zijn 3 soorten outputformaten mogelijk als respons: JSON, XML of Text. Om aan te geven welke soort output je wilt ontvangen, vind je meer informatie in dit artikel.

Response codes

Op POST requests ontvang je een response code 200 als de request succesvol is. Indien het niet succesvol is, ontvang je een andere response code. Meer informatie daarover vind je hieronder.

Op GET requests ontvang je een response code 200 en de gevraagde gegevens, indien beschikbaar. Als het niet beschikbaar is, krijg je een andere response code. Meer informatie daarover vind je hieronder.

Success

Standaard ontvang je een response code 200 zonder een bericht van de API als een POST request succesvol is.

Het is mogelijk om toch een succesbericht in het aangegeven outputformaat als respons te ontvangen door de parameter _returnSuccessMessage met als waarde true aan de URL toe te voegen.

Voorbeeld: Succesvolle API call zonder _returnSuccessMessage

API call:

POST https://<domain>/api/addUser/1234567
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
login=johnwatson@example.com
firstName=John
lastName=Watson
Output:
Response code: 200

Voorbeeld: Succesvolle API call met _returnSuccessMessage

API call:

POST https://<domain>/api/addUser/1234567?_returnSuccessMessage=true
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
login=janjansen@example.com
firstName=Jan
lastName=Jansen
Output:
Response code: 200
{"success":"OK"}

Errors

Een API call kan onsuccesvol zijn om verschillende redenen. De API stuurt een response code en foutmelding. Standaard is de foutmelding niet in het aangegeven outputformat, maar platte tekst.

Het is mogelijk om de foutmelding ook in het aangegeven outputformaat te ontvangen door de parameter _formatErrors met als waarde true aan de URL toe te voegen.

Response code 400

Dit betekent dat een verplichte parameter mist of dat een parameter een ongeldige waarde heeft.

Voorbeeld: Missende parameter met _formatErrors

API call:

POST https://<domain>/api/addGroup/ABCD?_formatErrors=true
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
type=Student
name=Voorbeeldgroep
Output:
Response code: 400
{"error":"Missing parameter: name"}
Response code 403

Dit betekent dat de API key mist, niet klopt of dat de API key niet gebruikt kan worden vanaf jouw IP-adres.

Voorbeeld: Missende API key

API call:

POST https://<domain>/api/addGroup/ABCD
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
type=Student
name=Voorbeeldgroep
Output:
Response code: 403
No API key specified
Response code 404

Dit betekent dat de URL niet bestaat (er mist bijvoorbeeld een deel), of dat het object waar de URL naar verwijst niet bestaat (de gebruiker bestaat bijvoorbeeld niet).

Voorbeeld: Gebruiker met specifiek e-mailadres bestaat niet

API call:

POST https://<domain>/api/initializeId/janjansen@example.com/1234567
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
Output:
Response code: 404
User does not exist

Voorbeeld: API call bestaat niet

API call:

GET https://<domain>/api/nonExistingCall
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Output:
Response code: 404
Unknown command: nonExistingCall
Response code 409

Dit betekent dat de staat van het object het onmogelijk maakt om de actie uit te voeren. Bijvoorbeeld: Een gebruiker toevoegen die al bestaat.

Voorbeeld: Gebruiker bestaat al

API call:

POST https://<domain>/api/addUser/1234567
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
login=janjansen@example.com
firstName=Jan
lastName=Jansen
Output:
Response code: 409
User already exists
Response code 500

Dit betekent dat er zich een fout voordoet aan de kant van de server.


Om API calls te testen en te zien welke responsen en response codes je ontvangt, kun je de /apidocs pagina van je leeromgeving gebruiken. Meer informatie daarover vind je in het volgende artikel:

API - De /apidocs gebruiken