ropensci / rotl

Interface to Open Tree of Life API
https://docs.ropensci.org/rotl
Other
39 stars 18 forks source link

create function to get help associated with an endpoint #67

Closed fmichonneau closed 8 years ago

fmichonneau commented 8 years ago

In addition to the help we provide, it might be of interest to users to get the help straight from the API.

A simple curl call to an endpoint returns a JSON that explains what the input parameters are and the values they can take:

$ curl https://api.opentreeoflife.org/v3/tnrs/match_names
{
  "extends" : "graphdb",
  "name" : "match_names",
  "description" : "Accepts one or more taxonomic names and returns information about potential matches for these names to known taxa in OTT. This service uses taxonomic contexts to disambiguate homonyms and misspelled names; a context may be specified using the `context_name` parameter. If no context is specified, then the context will be inferred: the shallowest taxonomic context that contains all unambiguous names in the input set will be used. A name is considered unambiguous if it is not a synonym and has only one exact match to any taxon name in the entire taxonomy.\n\n[Taxonomic contexts](#contexts) are uncontested higher taxa that have been selected to allow limits to be applied to the scope of TNRS searches (e.g. 'match names only within flowering plants'). Once a context has been identified (either user-specified or inferred), all taxon name matches will performed only against taxa within that context.\n\nFor a list of available taxonomic contexts, see the [contexts](#contexts) service.",
  "parameters" : [ {
    "name" : "context_name",
    "description" : "The name of the taxonomic context to be searched",
    "optional" : true,
    "type" : "string"
  }, {
    "name" : "names",
    "description" : "An array of taxon names to be queried. Currently limited to 10,000 names for exact matches, or 250 names when inexact matches are requested.",
    "optional" : false,
    "type" : "strings"
  }, {
    "name" : "ids",
    "description" : "An array of ids to use for identifying names. These will be assigned to each name in the `names` array. If `ids` is provided, then `ids` and `names` must be identical in length.",
    "optional" : true,
    "type" : "strings"
  }, {
    "name" : "do_approximate_matching",
    "description" : "A boolean indicating whether or not to perform approximate string (a.k.a. \"fuzzy\") matching. Will greatly improve speed if this is turned OFF (false). By default, it is off (false).",
    "optional" : true,
    "type" : "boolean"
  }, {
    "name" : "include_suppressed",
    "description" : "Ordinarily, some quasi-taxa, such as incertae sedis buckets and other non-OTUs, are suppressed from TNRS results.  If this parameter is true, these quasi-taxa are allowed as possible TNRS results.",
    "optional" : true,
    "type" : "boolean"
  } ]
fmichonneau commented 8 years ago

It's probably not needed.