Some thoughts on the OTL API

[sckott]

@kcranston asked about our (ropensci) thoughts on the API. Our perspective is of course from working in R...here goes:

• Write methods would be useful for R users. There is a huge community of people working with phylogenies in R that could contribute back if write methods available.
• Phylogeny formats: A variety of formats would be nice: NeXML, Newick, etc., but we could convert from one to others easily if only one format available.
• Data compression would be nice to have so that data comes back faster (not R specific of course)
• Authentication: For our use case, using web APIs via a programming interface (in this case R), using OAuth is a bit of an awkward experience since you have to go out of R command line to a browser to authenticate. API keys are easier to deal with for users and our own development. If you prefer OAuth, we can definitely make that work.
• Fuzzy search on node/tip names: Don't know if this is built in, but would be awesome to have.
• Web interface behaves the same as the API: For example, in the old GBIF API, data returned was only for the exact taxonomic match, while in the web interface, they returned data for the taxonomic match plus its synonyms. This results in users not trusting the API, so they want to stick with using the web interface. The new GBIF API fixes this I think. Anyway, it's a more seamless experience if R users can get the same data back when using the browser and R.
• Taxonomy: Can be tricky because no one stop shop for taxonomy, and the trusted source differs by taxonomic group. Perhaps taxonomic identifiers can be provided for a variety of different taxonomy sources (ITIS, NCBI, GBIF backbone, etc.).
• Multiple input fields (e.g., study_id='4,5,6' or study_id=4&study_id=5&study_id=6 instead of haivng to request 4, 5 and 6 in 3 separate calls): This may be harder on your side, but the APIs we work with that allow passing in of multiple identifiers in a single call (e.g., the PLOS altmetrics API) make for faster data acquisition.
• Will there be Solr or ElasticSearch endpoints to hit? Or perhaps text search is available in the graph database?
• Pagination (allowing us to decide how much to retrieve) - obviously better for you too
• Time stamps - nice metadata to have
• Data aggregation where suitable (so it is done on server side rather than on our end [R is slow as you probably know])

[mtholder]

Hi Scott, Thanks for the feedback. That is very helpful. It would be great (for me at least) if you could expand a bit on what you mean by "write methods" in the first bullet point. Were you thinking about methods for submitting entirely new studies, methods for annotating trees from published studies, or something else? I know that there are lots of potential pieces of information that someone might want to associate with a tree, but having a few examples of the types of data that you think folks would want to write would be very helpful.

[sckott]

@mtholder Sorry, by write methods, I meant POST/PUT, so being able to submit data, and not just get data. I was simply thinking of submitting data in general. Hard to know what would be most useful for the community. I imagine submitting annotations to trees would be of use, e.g., an R user may generate a new tree with node age estimates that could be submitted, or traits associated with nodes or tips that could be submitted.

[leto]

Submitting new studies and updating existing studies via the API are documented here:

https://github.com/OpenTreeOfLife/api.opentreeoflife.org/blob/master/docs/README.md

[sckott]

Great, thanks @leto

[jimallman]

Fuzzy search on node/tip names: Don't know if this is built in, but would be awesome to have.

We do currently support this in the TNRS, for example:

curl 'http://ec2-54-203-194-13.us-west-2.compute.amazonaws.com/taxomachine/ext/TNRS/graphdb/autocompleteBoxQuery' -H 'Content-Type: application/json' -H 'Accept: application/json, text/javascript, */*; q=0.01' --data-binary '{"queryString":"arac","contextName":"Animals"}'

As suggested by the name autcompleteBoxQuery, this is tailored to user experience we wanted for taxon search in the main webapp. But we can definitely get there from here..

[sckott]

Nice, good to hear @jimallman

[chinchliff]

There is another query that is tailored for sets of names occurring in the same tree:

curl 'http://ec2-54-203-194-13.us-west-2.compute.amazonaws.com/taxomachine/ext/TNRS/graphdb/c http://ec2-54-203-194-13.us-west-2.compute.amazonaws.com/taxomachine/ext/TNRS/graphdb/autocompleteBoxQueryontextQueryForNames' -H 'Content-Type: application/json' -d '{"queryString":"arachnids, insects, crustaceans"}'

On Fri, Jan 31, 2014 at 2:37 PM, Scott Chamberlain <notifications@github.com

wrote:

Nice, good to hear @jimallman https://github.com/jimallman

Reply to this email directly or view it on GitHubhttps://github.com/OpenTreeOfLife/api.opentreeoflife.org/issues/47#issuecomment-33834855 .