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

Discontinued features

• 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)

Incompatible changes in parameters and results

• Synthetic tree node ids are written as strings instead of integers

New features

• include_children boolean parameter to the taxonomy/taxon method, and children in result (list of taxon descriptions similar to include_lineage; compare arguson)

Cosmetic changes under consideration (decisions to be made!)

• Rename taxonomy/taxon method to taxonomy/taxon_info for consistency with tree_of_life/node_info
• Parameter and output field names normalization:
  • 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
• In node_info, the sources are returned as tax_sources whose value is a list of strings
• Rename taxonomy/lica method to taxonomy/mrca
• 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
• It's been noted that tree_id is used in two different ways: for synthetic tree labels (arbitrary strings) and for source tree ids (must be XML ids). Might be better to have distinct names for the two.

New features under consideration

• Considering: /studies/all_studies (list of ids for all studies) - we have the method, just a matter of exposing and documenting it
• Method for getting a subtree of the synthetic tree (exists, but with odd name and calling convention)
• 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)
• what else? see google doc

Probably not ready yet

• advertised conflict report generator
• new study/tree index (OTI replacement) using GET instead of POST etc.

ArguSON is not necessarily ready for outside users. Changes to ArguSON are given here: "Arguson" format

The phylesystem methods use camelCase. Probably not going to be able to make this consistent, this time around at least.