Application Programming Interface (API)

Karen Cranston edited this page Jan 11, 2015 · 4 revisions

Introduction to the database

The NESCent working group, Synthesizing and databasing fossil calibrations: divergence dating and beyond, has developed a database of fossil calibrations for use in molecular divergence time analysis. The database is coupled to a publication stream for fossil calibration papers in Palaeontologia Electronica. These papers follow the best practice guidelines for justifying fossil calibrations (Parham et al).

The Fossil Calibrations database is nearing launch. In addition to its Web UI, we're building a simple API to provide access to calibration data in CSV and JSON formats. We're seeking feedback from potential users on how you'd like to use this API.

The primary organization unit in the database is a calibration, which contains information about age, phylogenetic placement and supporting fossils. The API is therefore organized around search and download of calibrations. The first version will focus on filtering/searching of calibrations by their age and position in the tree, but there are still key decisions to be made.

Please contact Karen Cranston for login information, if you have not already received this information by email

RESTful approach

One approach is to adopt RESTful URLs and parameters, mapping resources and queries onto documented, structured paths. For example,

    /api/v1/calibrations?geologicalTime=Neogene

This query would return the calibrations in the database, associated with the geological time period 'Neogene'. The list of geological times would be available at /api/v1/geologicalTimes/. Another example,

    /api/v1/calibrations.csv?clade=Primates

would fetch all calibrations attached to nodes within the Primates clade, and return them in CSV format.

The other proposed parameters are documented at http://docs.fcdb.apiary.io/

CQL approach

Another approach is to adopt a standard query language, like CQL. This still requires knowing the nouns, but handles the structure more simply:

    /api/v1/calibrations?q="geologicalTime = Neogene"
    /api/v1/calibrations?q="minAge > 10 and maxAge < 35”

In this case, the query string would need to be URI escaped to handle spaces/quotes. Additional searches (e.g. fulltext, by publication, etc.) wouldn’t require any new URLs once they are implemented.

Questions

Questions for potential users:

  1. How would you imagine primarily using this database?
  2. Do you prefer one of the two formats (documented parameters or CQL), and why?
  3. Do the initial search modes (age and tree position) make this a usable API? If not, why not? What are we missing?

You can email comments to Karen Cranston, or add them to this GitHub issue.