Release notes for web API v3

this is work in progress

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

• The 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 should also 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)

Other changes

• Rename taxonomy/taxon method to taxonomy/taxon_info for consistency with tree_of_life/node_info
• Rename taxonomy/lica method to taxonomy/mrca
• Parameter and output field names:
  • ott_id rather than ottID (in taxonomy/taxon_info) and ot:ottId (in tnrs/ methods)
  • name or tax_name rather than ot:ottTaxonName (ArguSON currently uses name)
  • tax_sources instead of tax_source
  • tax_rank rather than rank in taxonomy/taxon, or else change tax_rank to rank ArguSON. Should be consistent
  • tree-of-life/node_info: the sources are returned as tax_sources whose value is a list of strings (in v2 it was tax_source and a single string)
  • nww boolean parameter include_children for the taxonomy/taxon_info method, returns children in result (list of taxon descriptions similar to include_lineage)
  • in all tree-of-life methods, tree_id refers to a source tree and synth_id refers to the version of the synthetic tree (previously, we used tree_id for both).

New features under consideration

• It's proposed to split date in tree_of_life/about into date_created and date_deployed - are both pieces of information available now?
• It's been suggested to write taxon_id instead of ott_id
• Optional argument to tree_of_life/ methods specifying which synthetic tree to use (currently there's only one, but in future there could be several) (this might already be implemented in tm-lite)
• If a request cannot be satisfied, an HTTP 4xx response is returned instead of a 200 with {"error":...}. (In v2 we have a mix of the two conventions.)
• what else? see google doc

Changes being proposed for next version (v4) of APIs

This list 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 conflict report (we have one, but name and calling conventions are unsettled)
• new study/tree index (OTI replacement; new searchable properties for studies and trees)
• make official services for the previously-undocumented "Arguson" format
• Change phylesystem-api methods to underscores from camelCase for consistency
• new service to translate between various taxonomy identifers (i.e. NCBI ID to GBIF ID)