○ API - De API aanroepen en het outputformaat
Je kunt de API via HTTPS aanroepen met deze basis-URL:
https://<domein>/api/
<domein> is het domein van de leeromgeving (bijvoorbeeld: demo.anewspring.com). De basis-URL wordt gevolgd door de functie die je wilt uitvoeren en eventueel ook parameters.
Zorg ervoor dat je HTTPS gebruikt bij het aanroepen van de API.
De API accepteert HTTP requests met de GET en POST method. We raden aan om POST requests te doen als je ook gegevens wilt meesturen. De codering van de parameters moet UTF-8 zijn.
Er is altijd een API key nodig. Deze kun je meesturen als header (aanbevolen) of als parameter in de URL, maar dat zou in sommige situaties een beveiligingsrisico kunnen zijn.
Parameters in de URL
Dit zijn algemene parameters die je in de URL van een API call kan meesturen:
_key | We raden aan om de API key in de X-API-Key header mee te sturen zoals hieronder beschreven, maar het is technisch ook mogelijk om deze in de _key parameter mee te sturen. Als je het op beide manieren doet, krijgt de _key parameter voorrang. |
_returnSuccessMessage | Als je deze als waarde true meegeeft, ontvang je ook JSON of XML output terug als de API call succesvol is. Standaard staat deze waarde op false en ontvang je alleen response code 200. |
_formatErrors | Als je deze als waarde true meegeeft, ontvang je foutmeldingen ook als JSON of XML output. Standaard staat deze waarde op false en ontvang je alleen tekst. |
_pretty | Als je deze als waarde true meegeeft, wordt de output zo geformatteerd dat deze makkelijker te lezen is. Dit kan nuttig zijn voor debugging. |
Headers
Dit zijn de headers die je aan je request kunt toevoegen:
X-API-Key * | Gebruik deze header voor de API key. Als alternatief kun je ook de _key parameter gebruiken, zoals hierboven beschreven. Als je het op beide manieren doet, krijgt de _key parameter voorrang. |
Content-Type * | Voor deze header zijn er twee opties: application/x-www-form-urlencoded of multipart/form-data (als je ook een bestand mee wilt sturen). |
Accept | Deze header kun je gebruiken om aan te geven welk outputformaat je wilt ontvangen. Deze waardes worden geaccepteerd:
Het is ook op een andere manier mogelijk om aan te geven in welk formaat je de output wilt ontvangen, zie hieronder. |
*Verplicht
Voorbeeld in cURL:
curl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "login=testuser&firstName=test&lastName=test" https://demo.anewspring.com/api/addUser/testid
Specifieke parameters per API call
In de API documentatie vind je alle parameters die met een POST mee kan sturen. Er zijn twee types: path en formData. Als we als voorbeeld POST /updateCourse/{ID} nemen, is de parameter ID een path parameter en zijn de andere parameters die je op de /apidocs-pagina kunt vinden formData parameters.
path parameters
Dit zijn gewoonlijk externe ID's. Standaard plaats je deze na een / in de URL.
Als alternatief, kun je deze ook in de query string van de URL plaatsen (als een extern ID bijvoorbeeld een / bevat).
Zorg dat urlencode op speciale tekens wordt toegepast.
Voorbeelden voor /updateCourse/{ID}
ID = "1234 ABC"
In het pad: /updateCourse/1234%20ABC
curl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "startDate=2020-12-16&expireDate=2021-06-16" https://demo.anewspring.com/api/updateCourse/1234%20ABC
In de query string: /updateCourse?ID=1234%20ABCcurl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "startDate=2020-12-16&expireDate=2021-06-16" https://demo.anewspring.com/api/updateCourse?ID=1234%20ABC
query parameters
Path parameters kunnen ook als query parameters worden gebruikt als alternatief (zie voorbeeld hierboven), maar de enige parameters die altijd in de query string moeten worden verstuurd zijn UID's. Deze kunnen in veel gevallen als alternatief voor externe ID's worden gebruikt.
Voorbeeld voor /updateCourse?UID={UID}
UID = "1807abf8-f34b-404d-8bb3-d6b8fd5ffb27"
In de query string:
/updateCourse?UID=1807abf8-f34b-404d-8bb3-d6b8fd5ffb27curl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "startDate=2020-12-16&expireDate=2021-06-16" https://demo.anewspring.com/api/updateCourse?UID=1807abf8-f34b-404d-8bb3-d6b8fd5ffb27
formData parameters
Standaard stuur je deze in de body als application/x-www-form-urlencoded of multipart/form-data.
Als alternatief kun je deze ook in de query string sturen.
Voorbeeld voor /updateCourse/{ID} met x-www-form-urlencoded
startDate = "2020-12-16"
expireDate = "2021-06-16"/updateCourse/1234
body:
startDate=2020-12-16&expireDate=2021-06-16curl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "startDate=2020-12-16&expireDate=2021-06-16" https://demo.anewspring.com/api/updateCourse/1234
Voorbeeld voor /updateCourse/{ID} met een query string
startDate = "2020-12-16"
expireDate = "2021-06-16"/updateCourse/1234?startDate=2020-12-16&expireDate=2021-06-16
curl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://demo.anewspring.com/api/updateCourse/1234?startDate=2020-12-16&expireDate=2021-06-16
Outputformaat
De API ondersteunt 3 soorten outputformaat voor de responsen vanuit de API:
- JSON
- XML
- Text
Het standaardformaat is JSON, dus dit ontvang je als als je helemaal niets aangeeft.
In plaats van de Accept header (zie boven), kun je het gewenste formaat ook aangeven door een extensie aan de API call toe te voegen. De opties zijn .json, .xml of .txt.
Voorbeeld:
Je wilt nagaan of een gebruiker (met extern ID 1234567) al bestaat en je wilt de output als XML.
De API call om dit te achterhalen is: POST /userExists/{userID}
Je kunt de output als XML krijgen door de extensie .xml aan de API call toe te voegen:
POST https://<domain>/api/userExists.xml/1234567
Als je zowel de Accept header als de extensie gebruikt, krijgt de extensie voorrang.
Het volgende artikel geeft meer informatie over de responsen en response codes: