The REST API is designed to be an easy way to access the information in the Zermelo Portal programatically. With just an endpoint and an access token information can be retrieved as JSON. The API now includes CORS headers, so writing web or phonegap applications should be possible without hassle.
All API access is through HTTPS. The API is set up following the REST principles, which means it uses HTTP verbs like GET, POST, PUT and DELETE. Data is transferred as JSON. API versioning and Authentication apply to all requests.
An API request will be forcibly terminated after 60 seconds. You should split your requests up in smaller parts, preferably each of ~10 seconds.
On this page:
The user that uses your application may not have full permissions, and may have further restricted your application by giving a token with reduced permissions. Keep in mind that you may receive "Access Denied" messages and that objects may not have all available fields.
tokens/~current contains a field
effectivePermissions that will allow you to detect what permissions are given to the current access token. The endpoint
users/~me/rules allows you to see which objects are available through school functions. Note that we are currently simplifying this system, as we are phasing out the roles and permissions.
In the new system tokens contain scopes. These can be compared with OAuth scopes. The following scopes will be supported from portal version 1.8:
|Global||This scope encompasses all permissions the user itself has.||User management, staffing, etc. etc.|
|Schedule||This scope is for everything that has to do with the schedule/timetable.||Queries on the |
These scopes can have the following values:
|0||This token does not give you extra permissions for the scope.|
|1||This token grants permission to query data using GET requests for the scope.|
|2||This token grants permissions to read and modify (using POST, PUT, DELETE) data that falls under the scope.|
Note that these scopes only limit privileges obtained through school functions. Limiting rights obtained through permissions cannot be done with scopes.
In general, querying an endpoint will retrieve all objects in that endpoint. If you require a subset you must specify a filtering. All properties returned by the API can be used to restrict the results.
Updating objects using PUT or POST works as follows:
|Action||ID specified||Object exists||Result|
|POST||No||No||A new object will be created, and an ID will be generated. Supported for objects with numeric ids.|
|POST/PUT||Yes||No||Only in specific cases (for example for /users). A new object will be created with the specified id (usually a code).|
|POST/PUT||Yes||Yes||The specified fields will be overwritten. Fields that are not specified will retain their old value.|
We usually recommend using POST to update data, as you can update multiple objects at the same time. This is good for performance.
We also recommend that you only provide values for the fields you want to change, otherwise there is a small chance that you'll overwrite data for fields that other users have modified.
Searching and filtering
For (almost) all endpoints you can filter on GET requests using query parameters. For these query parameters you can use the names of object properties, and in some cases there are extra query parameters supported.
The Zermelo API is versioned in order to allow for major refactorings in the future. The current version is
v3. In order to use the API you will need to construct a versioned endpoint. This is done by appending the version to the endpoint specified by the user. For example the endpoint will turn into the versioned enpoint .
In the rest of this documentation you will see urls with the versioned endpoint removed, for example
/students. To access those resources you would need to use https://example.zportal.nl/api/v3/oauth and respectively.
Interactive API reference
Your own Zermelo Portal contains a live API reference that is always up-to-date. To visit this use the address