Migration Guide

Overview

This major release introduces many new features with only a minimal number of breaking changes. Most breaking changes are the result of stricter naming conventions and can typically be resolved by updating property names.

The most significant change in version 2—though not strictly breaking—is the introduction of the mutation engine. Integrating this feature into an existing implementation requires some additional effort. We therefore strongly recommend reviewing the mutation engine documentation before starting the migration.

Mandatory steps

Complete all steps in this section to avoid breaking changes in your application.

• Change the Base URL

The new API is accessible at:

https://onderwijsregio.onderwijsin.nl/api/v2

All endpoints referenced in the documentation are relative to this base URL.

• Change the Authentication Header

The old api-key header is deprecated. Use the x-api-key header instead.

Optional steps

These steps are optional but recommended to take advantage of new features and improvements.

• Integrate the Sandbox Environment

For non-production environments, you can now use the sandbox environment. The sandbox provides access to the same API features as production but is fully isolated from production data. You can use the same API keys as usual.

To enable the sandbox, use one of the following approaches:

• Prefix the endpoint with /sandbox instead of /v2. Example:

  https://onderwijsregio.onderwijsin.nl/api/sandbox/schema

  plaintext

• Set the x-api-sandbox header to true

• Explore the new endpoints in the API Explorer

Version 2 introduces dozes of new endpoints you can use in your application. You can explore, inspect and test them in the interactive API Reference.