Contact supportReport a bug or request a featureSee ROR docs on GitHub
Guides
Start typing to search…

API versions

This page documents policies around ROR API versioning. ROR API v2 was deployed to production in April 2024. ROR API v1 was sunset in December 2025.

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.

API versioning

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.

📘

Schema versioning

A new major version of the API will be accompanied by a new major version of the schema. Minor schema updates, however, will be rolled into major versions of the API. Read more about Schema versions.

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 require versioning

Minor version change

  • Changing existing API functionality such that the response to a given request has the same structure but a different meaning or nature (e.g., current ?query search behavior is changed to ?query.advanced behavior)

Major version change

  • Removing API functionality
  • Significantly changing existing API functionality such that the response to a given request is different in structure (e.g., removing container element from ?affiliation response)

Changes that do not require versioning

  • Minor (non-breaking) changes to existing API functionality, such as bug fixes and incremental improvements to search behavior to improve performance/accuracy
  • Adding new features to the API that do not impact existing features/functionality (e.g., adding a new endpoint)

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.

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, Bluesky, LinkedIn, the ROR Technical Forum, and the ROR Community Forum. Regular reminders will continue prior to the sunset date.

Implementing API versions

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

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.


Updated 1 day ago