Adding redirects for aliased DOIs in the REST API

From 25 February 2025, we will be adding redirects for aliased DOIs in the REST API. This means that requests won’t return aliased DOIs.

What is aliasing?

DOIs are persistent identifiers and can’t be deleted, but sometimes they get assigned to the wrong thing. Usually this can be corrected but occasionally it’s necessary to create a new DOI for the same item. Unfortunately that means that there can be two identifiers for the same thing, which can be confusing.

To solve this, we allow members to alias one DOI to another. This means that one DOI (the aliased DOI) is effectively replaced by another DOI (the prime DOI) and a request for the aliased DOI using https://doi.org/DOI resolves to the resolution URL of the prime DOI.

What will happen now?

You will see a few changes in the Crossref REST API after the changes have been implemented:

  1. If you request the record of an aliased DOI you will get back the prime DOI record instead (with a 301 http status).
  2. Aliased DOIs won’t appear in the results of queries, only prime DOIs.
  3. Citation counts and other statistics related to an aliased DOI will be added to the count for the prime DOIs.
  4. Snapshots in JSON format and the annual data file will only contain prime DOIs.

The XML and OAI-PMH endpoints won’t be affected.

The changes won’t be noticeable in most cases as the number of aliased DOIs is very small, but be aware that you may see a high rate of 301 statuses and some changes in the number of results for certain queries.

3 Likes

Thanks for the update - this is good news. How many aliased DOIs are there?

We have 891,000 aliased DOIs. It’s a difficult number to find out because we don’t identify them in the REST API or provide a way to filter for them in other endpoints. That’s one of the things we aim to fix in this project - in the future there will be a has-alias filter in the REST API so you can identify all prime DOIs, and hence aliases.

2 Likes

Will this affect requests in the XML API calls, such as the one that returns UNIXSD where we usually will see a crm-item if there is a prime DOI? Also, in the future with the has-alias filter, will we be able to see the aliased DOI? While not valuable to some folks, I think its still valuable for those doing analysis.

2 Likes

Good questions:

  • In the XML, the prime DOI crm-item will still remain, there won’t be any change.
  • Yes, aliases will be listed in the metadata record of the prime DOI (this is a new field we’ll be adding).