Skip to end of metadata
Go to start of metadata

So you're planning to build something that uses the Zermelo API? That's great! We've built it as open as possible so that everyone can access the information from the Zermelo Portal.

To get you started, we've written down some things that may help you with your project. Good luck!

1. Software is hard - start small

There is a saying that if you're not ashamed about the lack of features in version 1.0 of your product, you've waited too long before releasing it. You should pick a clearly defined goal, and leave all the frills for version 1.1 (or perhaps version 2). Release early, release often. Your users may complain, but in the long run they'll be better off. Be sure to reserve plenty of time after a release though, so you can quickly iron out all bugs and missing features.

2. Give your project a good name

A good name is memorable and pronounceable. Not much else. You could try to put a clever word-play into it, but most people won't get that anyway.

You may be tempted to use "Zermelo" in the name. Please be careful with this, as this can cause confusion about what's an "official" project and what's 3rd party.

Please don't use Zermelo in the name of your project, except with "voor Zermelo" or "for Zermelo".

OKNot OK (examples)
  • Material voor Zermelo
  • ScheduleApp for Zermelo
  • RandomApp
  • Roosterzz
  • Ernst Rooster
  • Cantor
  • Zermelo - FooBar
  • Zermelo Rooster
  • Zermeloos
  • Zrmlo
  • Zermeloner
  • Zcrmclo
  • Z3rm3!0

If you're writing a library that uses the Zermelo API, we don't mind as much if you name it something like "zermelo.js", as long as you clearly state that it's a 3rd party library.

3. Make sure your project looks good

If you value your users, don't hurt their eyes every time they use your product. If you're not a designer you should pick a main color and use that as much as possible. You may also want to pick a secondary color that goes well with the primary. Also, use either only a single font, or use one font for headings and another for "body text".

Whatever you do, please don't copy any of our design and don't use our logo. Thanks!

4. Think about the license

If you want your project to be open source it's easiest to pick a simple permissive license. Apache 2.0 is a good choice, or MIT. If you don't want someone else to "steal" your code and use it in a closed source app then pick something like the GPLv3. Note that in practice this almost never happens.

Whether your project is open source or closed source, think about the licenses you're using for libraries/artwork. Some open source licenses (like the GPL) are "viral" and will obligate you to release your project under the GPL as well.

5. Consider load you're putting on the API

If you're writing software that will benefit our customers then you're very welcome to put some load on our API. However, please note that the time an API request is busy it is probably hogging a core (and definitely a connection) on our database server.

Please use the latest API version you can, and make sure to use the fields= parameter. Not only will your software be quicker, this will also lessen the load. Also, don't poll too often. If you're retrieving appointments, you can use the /appointments?modifiedSince=... parameter to only retrieve appointments that have actually changed.

6. Add support for other schools

Quite a lot of apps are only available for select schools. Why not add the possibility for people from other schools to use your project? Often it's as simple as adding a textbox that allows people to enter the name of their portal. You can even have it hidden by default.

7. Check your response codes

This is mainly important if you're writing data to the API. In that case: check your response codes! Everything that's not in the 200 range is an error, and you should either retry or warn the user. Not doing so will cause data loss, which is fully your responsibility. We do not store any data from a failed request.

8. Don't be afraid to ask

Trouble using the API? Documentation unclear? Need some other help? Please mail us at helpdesk@zermelo.nl!

9. When you release, drop us a note!

We always like to see what people have built on our API. We will also add your project to the list on developers.zermelo.nl.


  • No labels