Versioning

API versioning is the process of managing and tracking changes to an API.

Principles

Transparency

Changes to the Oak Curriculum API will be communicated to our users so they can manage their integrations accordingly.

Traceability

Changes to the Oak Curriculum API will be well documented so we have clarity on what has changed and when.

Approach

Semantic versioning

Given a version number MAJOR.MINOR.PATCH, we increment the:

1. MAJOR version when we make ‘breaking changes’ (changes that will require users to modify their codebase in order to continue using the new version of the API)
2. MINOR version when we add functionality in a backward compatible manner
3. PATCH version when we make backward compatible bug fixes

Changelog

Users can interrogate changes to the API using the following endpoints:

GET /changelog

You can test this request in our API playground.

Example response:

[
  {
    "version": "0.5.0",
    "date": "2025-03-06",
    "changes": [
      "PPTX used for slideDeck assets",
      "All video assets now fully downloadable in mp4 format",
      "New /threads/* endpoints"
    ]
  },
  {
    "version": "0.4.0",
    "date": "2025-02-07",
    "changes": [
      "Added /sequences/* and /subjects/* endpoints, and add support for unit optionality"
    ]
  }
]

GET /changelog/latest

You can test this request in our API playground.

Example response:

{
  "version": "0.5.0",
  "date": "2025-03-06",
  "changes": [
    "PPTX used for slideDeck assets",
    "All video assets now fully downloadable in mp4 format",
    "New /threads/* endpoints"
  ]
}

Compatibility

The current API version is v0. We will communicate early when planning a breaking change, as this would result in a new major version (v1).

Each time we release a new major version, we will monitor migration from the previous version. The previous version will then be deprecated.

We will ensure backwards compatibility within each major version.

Sign up to our mailing list to receive important updates about the API.