Skip to end of metadata
Go to start of metadata

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.

Request timeout

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:

Security

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:

ScopeDescriptionExample
GlobalThis scope encompasses all permissions the user itself has.User management, staffing, etc. etc.
ScheduleThis scope is for everything that has to do with the schedule/timetable.Queries on the appointments endpoint, viewing a list of all students/teachers.

These scopes can have the following values:

ValueNameDescription
0NONEThis token does not give you extra permissions for the scope.
1READThis token grants permission to query data using GET requests for the scope.
2READWRITEThis 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.

Retrieving objects

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

Updating objects using PUT or POST works as follows:

ActionID specifiedObject existsResult
POSTNoNoA new object will be created, and an ID will be generated. Supported for objects with numeric ids.
POST/PUTYesNoOnly in specific cases (for example for /users). A new object will be created with the specified id (usually a code).
POST/PUTYesYesThe 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.

API Versioning

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 https://school.zportal.nl/api will turn into the versioned enpoint https://school.zportal.nl/api/v3.

In the rest of this documentation you will see urls with the versioned endpoint removed, for example /oauth and /students. To access those resources you would need to use https://example.zportal.nl/api/v3/oauth and https://example.zportal.nl/api/v3/students 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 https://<name>.zportal.nl/static/swagger.

  • No labels