Retired API Endpoints
Summary of retired API endpoints
Retired API Endpoints
API endpoints are typically deprecated 6 months prior to sunset, at which time they are completely removed. During this period, APIs will respond with a Sunset HTTP Header field containing the approximate date and time that the API will be shutdown.
Upcoming Endpoint Retirements
| API Endpoint | Deprecation Date | Sunset Date | Suggested Replacement |
|---|---|---|---|
/v1/* | June 3, 2024 | December 2, 2024 | /v2/* |
All remaining v1 endpoints will be deprecated as of June 3, 2024 and retired as of December 2, 2024. The v2 endpoints can be used to replace these endpoints although API names, input, and output values in most cases have changed. Note that programs that rely on these endpoints, including the v1 Command-line tools will stop working on the sunset date as well. Also in June of 2024, all v2 endpoints will transition to v2, and be stable.
Retired Endpoints
| API Endpoint | Deprecation Date | Sunset Date | Suggested Replacement |
|---|---|---|---|
/v1/genome/taxon/{taxon}/tree | February 2, 2023 | August 1, 2023 | /v1/taxonomy and /v1/taxonomy/filtered_subtree |
/v1alpha/assembly_descriptors/taxid/{tax_id} | February 2, 2023 | August 1, 2023 | /v1/genome/taxon/{taxon} |
/v1alpha/assembly_descriptors/organism/{tax_name} | February 2, 2023 | August 1, 2023 | /v1/genome/taxon/{taxon} |
/v1alpha/assembly_descriptors/accession/{assembly_accession} | February 2, 2023 | August 1, 2023 | /v1/genome/accession/{accessions} |
/v1/genome/taxon_suggest/{taxon_query} | February 2, 2023 | August 1, 2023 | /v1/taxonomy/taxon_suggest/{taxon_query} |
Notes about replacing retired APIs
/v1/genome/taxon/{taxon}/tree
While it may be quite convenient for the user, this API has a serious flaw in sending back all children with assemblies, for the given taxon rank. This creates rather large reply objects that are taxing on the system to generate, and rather large for the client to process. Furthermore, for the most up-to-date taxonomic information, the /v1/taxonomy (or /v2/taxonomy) set of endpoints is preferred.
By example, to replace https://api.ncbi.nlm.nih.gov/datasets/v1/genome/taxon/primates/tree, one would need to use:
- A call to the filtered-subtree API to retrieve the primate lineage, and all children (at the requested rank limits) that have genomes.
- Iteratively call the filtered-subtree API for the desired children.
- For any node that you would like more information about, use the taxonomy metadata API.