Home

Notes on design:

Function names:

• camelCase (insert debate here but camelCase and period.separator appear popluar: http://stackoverflow.com/questions/1944910/what-is-your-preferred-style-for-naming-variables-in-r)
• Prefix API end points with "idig", eg "idigSearch". This will mean there is a 1-1 correspondence between the API and the R methods.
• Add in methods that are language-specific by tacking on stuff to the end of the endpoint eg "idigSearchGetAll"

Query Objects:

Let's do objects but let's make people generate valid idigbio query JSON for now. That way everyone's code will be making query objects and if we want to help making query object easier later, we're not going to have to re-spec the idigSearch method to take a query object instead of a list/JSON. EG:

query <= idigQuery(text='{"family": ["asteraceae","fagaceae"]}') results <= idigSearch(query)

It's more clunky than I'd like but it keeps things tied directly to the API, is simple for us to impliment (just call jsonlite::toJSON) and if we want to add convenince methods for building queries, no existing code will need to change.

I wrote the below before changing my mind: I think I want to do a query object. Nested lists are just going to be trouble. The object can have a "fromJson" method that just takes JSON text for those who are chaining APIs or who want to just write JSON. Otherwise, probably a 1:1 matching of https://github.com/iDigBio/idigbio-search-api/blob/master/app/lib/query-shim.js is best. And update the iDigBio Query format documentation to include the query shim methods so that there is 1:1:1 correspondence between a query format snipped, a query shim method, and an R query object method.

Tests:

Yes. Look @ Francois's stuff for JSON definitions between Python and R