Release notes for web API v3

Release date: April 7, 2016

This page gives information for users of the Open Tree of Life v2 web API regarding the transition to v3.

Full documentation for the v3 web API is here: Open Tree of Life Web APIs

Major changes

• new base URL for all v3 services is https://api.opentreeoflife.org/v3/
• for all tree_of_life methods that return a node ID for a node in the synthetic tree, the result is a string (not a long). These IDs will either transfer well or fail gracefully for future versions of the tree (previously, some node IDs were re-minted for new versions of the tree and may have transferred poorly).
• all graph/ methods are discontinued, not available even under their v2/ URLs, with no replacement (with the exception of graph/node_info which is now tree_of_life/node_info)
• we are making public the method used to construct the visualization on the tree-of-life browser. This is tree_of_life/subtree with format=arguson
• support and conflict: tree_of_life/node_info and tree_of_life/subtree now return information about the sources underlying a node
• where method return information about a taxon, these fields are grouped into a dictionary with fields standardized across methods
• the tnrs/match_names method does not use fuzzy matching by default (previously, the default was fuzzy_matching = true). This is to increase efficiency of large queries.

Other changes

Here is a summary of the other changes. Please see the documetation of each method for details.

tree_of_life methods

• tree_of_life/about
  • renamed input parameter study_list to include_source_list and changed default to false
  • output parameter study_list now a combination of source_list plus source_id_map
  • now bundles all information about the root node into a standardized taxon dict
  • new output parameters synth-id, num_source_trees and filtered_flags
• tree_of_life/node_info
  • replaces graph_of_life/node_info
  • input parameter node_id is now a string, not a long int (and method returns a canonical node_id string)
  • now returns information about source that support / conflict with the node
  • output parameter lineage is now a list of standardized node dicts, not a list of strings
  • if node is a taxon, all taxon fields grouped into a taxon dict
  • output parameter num_synth_tips renamed to num_tips
• tree_of_life/mrca
  • input parameter node_ids is now a list of strings, not long ints
  • information about the mrca node collected into a mrca dict with standardized node fields
  • information about nearest taxon (if mrca is not a taxon) collected into a nearest_taxon dict
  • invalid ott_ids or node_ids now return a 400 response
• tree_of_life/induced_subtree
  • input parameter node_ids is now a list of strings, not long ints
  • can control format of labels in newick string using input parameter label_format
• tree_of_life/subtree
  • input parameter node_ids is now a list of strings, not long ints
  • method now returns either a newick string or the custom 'arguson' format (controlled by the new input parameter format)
  • can control format of labels in newick string using input parameter label_format

taxonomy methods

• taxonomy/taxon_info :
  • renamed method from taxonomy/taxon for consistency with tree_of_life/node_info
  • renamed output parameter ot:ottId to ott_id
  • renamed output parameter ot:ottTaxonName to name
  • the synonyms list no longer includes the name of the taxon itself
• taxonomy/mrca:
  • renamed method from taxonomy/lica for consistency with tree_of_life/mrca
  • renamed return parameter lica to mrca and returned as standardized dict of taxon fields
  • removed input parameter include_lineage. to get the lineage, use the taxonomy/taxon_info method.
• taxonomy/subtree return parameter subtree changed to newick for consistency with tree_of_life/subtree

tnrs methods

• match_names:
  • renamed input parameter include_dubious to include_suppressed
  • renamed output parameters *_name_ids to *_names
  • id in results is now name
  • the matches list groups all of the taxon fields into a standardized taxon dict, with some parameter name changes and also the addition of information about taxonomy sources
  • the synonyms list no longer includes the name of the taxon itself
• autocomplete_name
  • renamed input parameter include_dubious to include_suppressed
  • renamed output parameter ot:ottId to ott_id
  • renamed output parameter is_dubious to is_suppressed

study methods

• removed some fields from find_trees and find_studies result set

collection methods

• these methods, for finding and getting tree collections, are now public. They have not changed from the (undocumented) v2 format.

Changes being proposed for next version (v4) of APIs

This list is just FYI, and should not be considered final. Feedback welcome, though!

• use GET instead of POST where possible (for example, study methods)
• new service for generating a conflict report (we have one, but name and calling conventions are unsettled)
• new study/tree index (OTI replacement; will allow searching over more properties)
• Change phylesystem-api methods to underscored_names from camelCase for consistency
• new service to translate between various taxonomy identifers (i.e. NCBI ID to GBIF ID)