BETYdb API

[dlebauer]

Our API is implemented, but has not been widely used, so it would benefit from feedback and pull requests.

• repo: https://github.com/PecanProject/bety/
• documentation by example: https://authorea.com/users/5574/articles/7062/
• PEcAn interface to BETYdb (uses DBI interface: https://github.com/PecanProject/pecan/tree/master/db/R)

Most of the tables will return results with many uninformative foreign key integers. But the traits object will return more useful information, e.g. https://betydb.org/traits/219.xml

Our lead Ruby on Rails / database developer is @gsrohde, while @robkooper, @mdietze, and I work on PEcAn, a suite of R packages that use BETYdb for ecosystem modeling. We will try to keep up with your requests and help in any way we can because it will be very valuable to us to have this working well at all, and to provide access via your tools in particular.

[sckott]

Thanks @dlebauer

We can definitely give feedback as we test it out in this pkg.

Looking forward to playing!

[robkooper]

One option might be to download our VM. The VM contains a copy of the database as well as the BETY webinterface. Once you have the VM up and running on your local machine you can access the database under http://localhost:6480/bety

You can download the VM from http://isda.ncsa.illinois.edu/download/index.php?project=PEcAn&sort=version&version=1.3.4

[sckott]

Thanks @robkooper . I'll try that to start playing around. Is that VM open to the general public? That is, can the readme for this repo suggest folks do the same if they want to play around?

[mdietze]

Yep, the VM is public:

http://isda.ncsa.illinois.edu/download/index.php?project=PEcAn&sort=category

On Apr 15, 2014, at 3:01 PM, Scott Chamberlain notifications@github.com<mailto:notifications@github.com> wrote:

Thanks @robkooperhttps://github.com/robkooper . I'll try that to start playing around. Is that VM open to the general public? That is, can the readme for this repo suggest folks do the same if they want to play around?

— Reply to this email directly or view it on GitHubhttps://github.com/ropensci/rotraits/issues/3#issuecomment-40520616.

[dlebauer]

The VM is the fastest, easiest way to get a demo server up and running.

If you want to fiddle with the BETY interface itself ... there are also Instructions for installing the BETY database and Ruby interface natively on a server (e.g., localhost on your development machine).

[sckott]

So, @dlebauer @robkooper @mdietze So it seems like the API to Bety is already available publicly following this page https://github.com/PecanProject/bety/wiki/Data-access#json-csv-and-xml-api - Shouldn't I just use that with authentication? Is there anything different in the VM?

[dlebauer]

You can use the production site with or without authentication. But the VM provides a sandbox for testing, e.g. you can create users with different levels of access, as well as experiment with the internals of our API. FWIW, all data on the VM is public.

[dlebauer]

@sckott let's chat so we can define the functions' input and output

[sckott]

sounds good

[sckott]

@dlebauer got first fxn for bety - see the readme - any feedback? I went with returning as a dplyr tbl_df type data.frame for easy viewing and then can be directly passed to other dplyr functions. that okay?

Also, Are there more docs for the API besides https://www.authorea.com/users/5574/articles/7062 ? There are some parameters you use in the examples, but there isn't a clear list of definitions of each parameter, and which parameters are allowed with each endpoint (/traits, /species, etc.)

[sckott]

@dlebauer okay, updated with more fxns - see the vignette https://github.com/ropensci/traits/blob/master/vignettes/betydb.Rmd

Does it make sense to have two functions for each endpoint? e.g. for /citations have bety_citations() and bety_citation() where the latter requires an ID and other parameters and will give back a list with variable output given input params - while the former always gives back a data.frame

[dlebauer]

Thanks! This is a good place to start. My next step will be to test these out to see what they are doing, and have asked @phenolphtalein to explain your questions and update the documentation in PecanProject/bety#207.

My initial impression is that we should not expose any uses of keys in the arguments of exported functions, in order to prevent humans from having to reference records by arbitrary integers (as opposed to fields that have meaning, like genus and species).

I am not familiar with the API beyond what is in the documentation and where the [results of a search for "json" occur in the source code]. It has rarely been used. This was originally implemented by @mulrooney and extended by @gsrohde.

[sckott]

@dlebauer It's quite common, in my experience, for APIs to allow retrieval of whatever the thing is they provide by its unique ID. For example, GBIF does this for each species, dataset, and occurrence. All taxonomic of course do this. But if you don't want to allow it, then that's cool. Up to you. If you want to allow it, a workflow might be where a user searches e.g., for species, then gets ids for the ones they want, then they can pass those ids to a function to get data by ID.