API Version Policy

Last Updated

In order to gather information from the Local Contexts Hub to publish on your site, a request needs to be made through the API. As development of the Hub continues to grow, changes to the API may be needed for new features, updated terminology, or keeping up with metadata changes. This page describes when those changes are necessary and how that will affect the Hub API.

This policy will take effect June 1, 2026. Any API updates after this date will follow this policy.

Version Changes

Each change in the API will be denoted by a version number, MAJOR.MINOR.PATCH.

  1. MAJOR version increments indicate breaking changes.
  2. MINOR version increments indicate non-breaking, additional functionality or new features with backward compatibility.
  3. PATCH version increments indicate non-breaking, bug fixes with backward compatibility.

All version changes will be available in the sandbox Hub testing purposes prior to the updates in the main Hub API.

Major (X.0.0)

A major API change will occur when large, breaking changes occur to the API. This can include removal of old fields, field name changes, data type changes, access restrictions, etc. These updates may require code changes to ensure the connection to your platform and the Hub API are maintained.

These updates are rare and will be announced to all users via email at least 3 months before the new version is released.

Local Contexts will aim to support 2 major API versions at a time. As a new major API version is released, support for older versions will be deprecated. We will give at least 12 months notice before retiring the oldest major version, and send periodic reminder emails. We will support each version for 3 years.

Minor (0.X.0)

A minor API change will occur when new features are added to the API. This can include addition of new fields, new parameters, and additional metadata options. These updates, while non-breaking changes, are meant to enhance the data that is being requested. Code changes may be needed to include any of the new features, but are not required.

These updates will be announced to API users via email.

Patch (0.0.X)

A patch API change will occur when bug fixes are added to the API. These updates are to address any bugs or issues within the API. Code updates are not required for patches.

These updates will be announced to API users via email.

Feature Updates Across Major Releases

Aside from minor updates within the same major release, there may be some non-breaking changes across major releases that add to the functionality of the API. While users of a previous major release may ignore these changes without fear of the connection breaking, they should keep in mind that there will be less refined metadata available.

An example of this from v2 of the API is the addition of Contributor Roles. Although the contributor section is the same from v1, the additional fields of role_type and a separate new object for Individual Contributors means that this additional information is inaccessible in v1.

Changelog

For past API versions and changes, visit our changelog and API guide.

The Hub receives regular updates, and the Local Contexts team appreciates your questions and feedback as we continue to develop the Hub into a useful tool. Please get in touch with us by emailing support@localcontexts.org.