DataCite API Deprecation Guide
DataCite provides a number of APIs, including the DataCite REST API as well as the MDS, GraphQL, OAI-PMH, Usage Reports, Content Negotiation and Event Data APIs. DataCite strives to avoid API changes that disrupt existing functionality and require code changes for compatibility. However, in some circumstances, DataCite may introduce deprecations to DataCite APIs based on community needs and DataCite organizational priorities. This guide details the process for deprecating API functionality to allow the DataCite community to adapt to changes with minimal disruption.
What do we mean by breaking change and deprecation?
A deprecation is a planned breaking change. A breaking change is a non-backward-compatible change to existing API behavior.
A breaking change may remove, rename, or move data within a response or invalidate previously valid API requests. Examples of breaking changes include:
- Removing, renaming, or modifying the data type of an object in a response.
- Making backward incompatible changes to the submission validation of a field.
- Removing an API endpoint.
When will breaking changes happen?
In all possible circumstances, DataCite will avoid deprecations with measures like API versioning, backward compatible changes, and user-configurable requests. However, deprecations may be implemented under the following circumstances:
- Existing functionality has been significantly improved by new functionality.
- Functionality is no longer efficient, secure or scalable.
- Functionality no longer aligns with DataCite’s strategic goals or community requirements.
- Functionality has low usage.
How will I know when a breaking change is going to happen?
DataCite will use the following channels to notify users of upcoming deprecations:
- DataCite Status Page
- DataCite Support Site, including the API Reference and applicable documentation
- Email communication with:
- DataCite Members
- DataCite Registered Service Providers
- Targeted outreach (where possible)
It is your responsibility as a DataCite Member, Consortium Lead or Consortium Organization to ensure that correct and up to date contact information has been added to your organization’s contact list in DataCite Fabrica.
How much notice should I expect when an API deprecation is planned?
We strive to notify users of deprecations within the timeframes below.
| Deprecation type | Advance notice timeframe |
|---|---|
| Minor changes such as: Changes that are backward compatible with user configuration; for example, by updating a URL query or header. | 6 months |
| Significant changes such as: Removing, renaming, or modifying the data type of an object in a response. Major submission validation changes, like the deprecation of support of a DataCite Metadata Schema version. Retiring endpoints with low community use. | 12 months |
| Major changes such as: Retiring the previous version of an API endpoint after a new API version has been introduced. Retiring endpoints with significant community use. | 24 months |
| Changes that involve: Urgent security concerns. Urgent infrastructural concerns. | Case-by-case |
We would be happy to hear from you if you have any questions about API deprecations. Please contact [email protected].
Updated 5 days ago