De Zermelo API

De Zermelo API is een JSON REST-API die zich bevindt op https://<portalnaam>.zportal.nl/api.

Naast authenticatie zijn bij ieder verzoek (als koppelpartner) twee request parameters verplicht:

schoolInSchoolYear=...: een komma-gescheiden lijst id’s van roosterprojecten waar u rechten voor heeft.
fields=...: een komma-gescheiden lijst van de velden die u in het antwoord wilt krijgen.

Geldigde waardes voor zowel schoolInSchoolYear als fields zijn te verkrijgen via het /api/partners/~me endpoint. Hiervoor zijn bovenstaande parameters niet nodig. Zie Authenticatie en autorisatie voor meer informatie.

Naast deze parameters is het mogelijk andere parameters op te geven om de resultaten van het verzoek te filteren. Welke parameters mogelijk zijn verschilt per endpoint. Zie daarvoor de documentatie van dat endpoint. Op enkele endpoints zijn meer parameters nodig. Als u een request op zo’n endpoint doet, krijgt u daar een melding over. Een verzoek zou er als volgt uit kunnen zien:

GET /api/groupindepartments?schoolInSchoolYear=1001702,1001703&fields=id,departmentOfBranch,name,extendedName,yearOfEducation,isMainGroup

De respons van een API-verzoek is een JSON-object met de volgende standaardvorm:

{
    "response": {
        "status": <http-status>,
        "message": "",
        "details": "",
        "eventId": 0,
        "startRow": 0,
        "endRow": 0,
        "totalRows": 0,
        "data": [
            <een lijst met JSON-objecten>
        ]
    }
}

De velden message, details, en eventId zijn alleen gevuld in het geval van een foutmelding. Dit zult u kunnen herkennen aan de http-status. Mocht het nodig zijn om met Zermelo te communiceren over het probleem, dan is dit interessante informatie.

In de meeste gevallen zult u natuurlijk "status": 200 zien en geeft totalRows het aantal teruggegeven objecten. De objecten zelf vindt u in de lijst data.

Keyboard shortcuts

De Zermelo API

De Zermelo API