Community feedback

In the autumn of 2022, ROR asked for community feedback on plans for versioning the ROR metadata schema and API. Read the draft and final proposals below.

Handling schema & API versioning in ROR (Draft) - proposal open for comment through November 2022
Handling schema & API versioning in ROR (Final Draft) - proposal adopted November 2022

API versioning

The ROR metadata schema and API will be versioned in lockstep, meaning that when a new major schema version is introduced, the API version will also be incremented so that users can unambiguously request a response in a specific schema version. Read more about Schema versioning.

The ROR API will use semantic versioning:

A minor version (ex, X.1, X.2, etc) will be incremented when substantial non-breaking changes are made, such as changing existing API functionality so that the response to a given request has the same structure but a different meaning, e.g., changing the ?query search behavior to include ?query.advanced behavior.
A major version (ex, 1.X, 2.X, etc) will be incremented when breaking changes are made, such as removing existing API functionality or significantly changing existing API functionality so that the response to a given request is different in structure, e.g., removing the container element from the ?affiliation response.

Changes that do not require versioning include non-breaking changes to existing API functionality such as bug fixes, and incremental improvements to search behavior to improve speed or accuracy.

Deploying new API versions

No more than 1 new major API version will be released each year, and ROR will not seek to release a major version each year unless there's need for it. It's very likely that there will be several years between major version releases.

New versions will be made available in the ROR staging environment for approximately 1 month prior to production release. Users will have an opportunity to provide feedback on the technical implementation of the new schema version via ROR communication channels, such as the ROR Technical Forum.

Supporting and sunsetting previous API versions

When a new API version is deployed to production, any supported previous versions will continue to be supported until their planned sunset date. This may sometimes result in supporting 3 versions concurrently.

Plans to sunset a previous version will be announced at least 1 year prior to the planned sunset date, via the ROR community meetings and other communication channels such as the ROR blog, Mastodon, the PID Forum, the Crossref Community Forum, and the ROR Technical Forum. Regular reminders will continue prior to the sunset date.

Implementing API versions

Major versions will be required in the path portion of an API request, e.g., https://api.ror.org/X.X/organizations.

Requests that do not include a version in the path portion will default to version 1 of the API and schema until version 1 is sunset. At that point a version will be required in the path, and requests without a version in the path portion will return a 410 Gone error, with a detailed message.

Minor (non-breaking) API version changes will be implemented within the current major version.

2 major API versions will be supported concurrently (the current major version and the most recent previous version). Requests using an unsupported API version will return a 410 Gone error with a detailed message.