○ API - Responsen en response codes
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/1234567Headers:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Body:login=johnwatson@example.com firstName=John lastName=WatsonOutput:
Response code: 200
Voorbeeld: Succesvolle API call met _returnSuccessMessage
API call:POST https://<domain>/api/addUser/1234567?_returnSuccessMessage=trueHeaders:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Body:login=janjansen@example.com firstName=Jan lastName=JansenOutput:
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=trueHeaders:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Body:type=Student
Output:name=Voorbeeldgroep
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/ABCDHeaders:Body:
X-API-Key: ****Content-Type: "application/x-www-form-urlencoded"type=Student name=VoorbeeldgroepOutput:
Response code: 403No 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/1234567Headers:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Body:Output:
Response code: 404User does not exist
Voorbeeld: API call bestaat niet
API call:
GET https://<domain>/api/nonExistingCallHeaders:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Output:
Response code: 404Unknown 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/1234567Headers:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Body:login=janjansen@example.com firstName=Jan lastName=JansenOutput:
Response code: 409User 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: