Report a bug or request a featureContact support
Guides

API versions

Suggest Edits

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

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.

📘

Schema versioning

The ROR API and schema are versioned together, so a new minor or major version of the API will be accompanied by a new major or minor version of the schema. 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 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. 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.

Updated 4 months ago