Skip to end of metadata
Go to start of metadata

API Versions

When a new version of the API is released, the previous version is supported for at least a year.

VersionReleasedCurrently supportedSupported until
v4in development(error)
v32016-8-17(tick)at least a year from now
v22014-9-1(error)2017-8-31
v12011(error)2014-12-31

On this page:

Want an email when something changes?

Upcoming changes

DescriptionDateVersionEndpointsChanges
API version 4TBDv4all

API version 4 is currently under development. These are the planned changes:

  • Read-only fields will no longer be silently ignored for a POST or a PUT.
  • When updating an existing object using PUT or POST, by default only the ID field is returned. If you need other fields you can use the ?fields=... parameter.
  • The API no longer silently accepts null values for fields when creating an object where it would not support that value when updating it. If you want to leave a field at the default value you should omit it from your json. If you want to specify an empty list you should use [].

Note that not every addition of functionality will be documented here. We only include items we deem of sufficient general interest. For the latest information on what is supported take a look at the Swagger documentation. Note that everything that is available in the portal interface is also available through the API

Changelog

Version 2 is discontinued (31-8-2017)

DescriptionDateVersionEndpointsChanges
Version 2 of the API will be discontinued2017-08-31v2allDue to security and maintenance problems we will be discontinuing version 2 of the API. Please see the changelog for version 1.6 of the portal below for the changes. Feel free to contact us for advice on how to make the switch. Note that requests on v2 of the API may continue to work for a while, but support will be removed gradually.

Zermelo Portal 1.13 (august 2017)

DescriptionDateVersionEndpointsChanges
Complete removal of "families"2017-08-09v3/1.13.0families + all references to this endpoint

We have removed support for families from the portal and the API completely. We are doing this because the school administration does not have this information, and we had to painstakingly detect and generate the families. This went wrong way too often. During the summer holidays we will be removing the families endpoint and all fields referencing families. We will be replacing this with a direct link between a student and a parent.

From now on, do NOT use the "families" endpoint or any reference to a "family" field in your code. Please contact Zermelo on how adapt your code. We have already added some parameters to the API which make it easy to do so.

The "familymember" endpoint will still be in use and will continue to exist. It will have a direct link to students instead of going through a familymember object.

We are sorry for discontinuing this functionality on short notice, but it is not feasible to support it for a longer period of time.

Addition of the intakeProjects field to students2017-08-09v3/1.13.0studentsWe added the field intakeProjects to the students endpoint. This is a reference to a schoolInSchoolYear that this student first entered the school. This is an array field, containing the id of schoolInSchoolYears.


Zermelo Portal 1.11 (may 2017)

  • The appointments?branch= parameter is supported again in v3 (and later) of the API. Internally it uses the branchOfSchool field.

Zermelo Portal 1.8 (march 2017)

  • Version 1.8 of the Zermelo Portal introduces a new way of specifying the rights a newly created API-token should have. The new method is described in API overview.
  • Tokens created through the Portal will use the new system.
  • At this time, there is no planned date to disable old-style permissions. This means that:
    • Tokens created with old-style permissions will continue to work.
    • Creating tokens with old-style permissions is still possible
  • However, we do recommend that you use the new system for any new projects.

Zermelo Portal 1.6 / API version 3 (august 2016)

Version 3 of the API brings the following changes:

  • Unknown fields will no longer be silently ignored. The API will give an error when you specify a field it knows nothing about. This will make debugging your code much easier.
  • Some fields can only be specified when creating an object. Specifying those for an update on an existing object is no longer supported.
  • We are encouraging to use the fields= parameter for every request to specify what fields you are interested in. That way the request will be performed faster and less data will need to be transferred. You will also get an error when you don't have permissions for all these fields, instead of them being silently missing.
EndpointChanges
appointments
  • Please specify user=~me if you're only interested in the appointments for the current user. Also, you should lowercase the code yourself.
  • The "old style" search options groups=, locations=, subjects=, branch= and branches= are no longer supported. Please search for groupsInDepartments etc. From 1.11 the branch parameter is supported again. Internally, it uses the branchOfSchool field.
  • The unused fields originalAppointment and updatedAppointment have been removed.
  • Uploading the locations or groups of an appointment using the locations and groups fields is no longer supported. Please use the groupsInDepartments and the locationsOfBranch fields.
announcements
  • When retrieving announcements it is mandatory to specify a user= parameter. For the announcements for the current user specify user=~me&current=true.
branchesofschools
  • The /api/v2/branchofschool?mine= query parameter has been removed.
employees
  • The ldap= and hasPassword query parameters have been removed.
  • The fields ldap, hasPassword and email are no longer provided, as are street, houseNumber, postalCode and city.
groupindepartments
  • the fields studentInDepartments,mentors,mentorUserCodes,educations,yearOfEducation are no longer provided by default, but are available using the fields parameter
students
  • The ldap= and hasPassword query parameters have been removed.
  • The fields ldap, hasPassword and email are no longer provided, as are street, houseNumber, postalCode and city.
schoolleaders
  • A compatibility fix that caused a users with the right permissions to appear as schoolleaders has been removed.
subjectselections
  • Deans could change subjectselections by providing a full list of new selections. This is no longer supported.
studentsindepartments
  • The field previousMainGroup has been removed, please use mainGroupPreviousYear.
users
  • The field deleted has been removed, please use archived.


Zermelo Portal 1.4 (march 2015)

  1. Choices (chosen subjects) can now be marked as describing a study or a major/minor.
  2. Choices are now linked to departments.
  3. It's now possible to only partially change a set of chosen subjects through the API.

Zermelo Portal 1.3 (december 2015)

  • We've changed the way permissions are checked in the API. You may receive slightly different errors. Please let us know if we've broken anything in v2 of the API.
  • Some fields for /contracts are no longer used and any attempt to set them will be silently ignored.
  • We've added a lot of endpoints and fields (take a look at Swagger). One of the more useful things is that we now have real groups with real students. Take a look at the /groupindepartments endpoint for more information. A lot of functionality for contract and employee management has also been added.

Zermelo Portal 1.1 (june 2015):

  • added some fields to /appointments
  • replaced the history mechanism from originalAppointment/updatedAppointment to a list of versions (can be sorted by creation date/time).
  • added support for retrieving only changed appoinment versions instead of having to process everything.

Version 2 of the API ("v2"):

  • For retrieving the schedule of the current user use "user=~me" instead of "user=me". Users can now have the username "me".
  • For retrieving the current token use "~current" instead of "current".
  • Appointments now have camelCase members instead of snake_case. This means that the "original_appointment" field is now "originalAppointment".


  • No labels