search

DINA-Web / taxonomy

DINA Taxonomy module
MIT License
1 stars 0 forks source link

Standards and conventions for taxonomy API #3

Open kcranston opened 6 years ago

kcranston commented 6 years ago

There are a few desirable properties of the API, and some conflict between them. Want to make sure we have discussed and understand the implications.

  1. Comply with the DINA API web guidelines, which follows the JSON API standard
  2. Follow REST conventions - endpoints are nouns, not verbs
  3. Consistency with other taxonomy APIs, e.g. GBIF species API
  4. Usability - making the API clear and easy to implement (developers) and use (users)

The conflict is most notable in the functionality around search. If we want to follow the DINA guidelines / JSON API spec / REST conventions, then all functionality around search (get a specific taxon, search for taxa, autocomplete, and taxonomic name reconciliation) goes under the single noun endpoint /taxon, e.g.:

/taxon?filter[tnrs]=.... /taxon?filter[year]=1985... /taxon?filter[autocomplete]=....

compare to the GBIF API, which provides verb endpoints (controllers) for a taxon resource:

/species/match /species/suggest

mdoering commented 6 years ago

A quick note, I have not followed all your discussion. The reason the GBIF API offers a different /species, /species/search and /species/match resource is that the returned object type is different for all of them! If /species/match would return the same type as /species we would have collapsed them and use parameters

kcranston commented 6 years ago

Thanks, @mdoering Helpful to know. Sounds like we also want to think more about return values before making a final decision.

cgendreau commented 6 years ago

I'm not sure about /taxon?filter[tnrs]=. Considering you would filter a taxon by rank like /taxon?filter[rank]= I would interpret the element inside brackets as a property of the resource. But autocomplete could be implemented as /suggestion.

antonoberg commented 6 years ago

I dont think its an issue to use filter[somethingWeird] as long as its well documented in api documentation. I think we should not deviate from the json api specification if we dont have to. From a frontend / api consumer perspective its easier to work with fewer resources/set of responses. Fewer resources makes it easier to reuse stuff in the frontend.

The following looks fine to me: /taxon?filter[tnrs]=.... /taxon?filter[year]=1985... /taxon?filter[autocomplete]=....

gnewton commented 6 years ago

I have no problem with the filter approach. I have seen no compelling evidence that it is a problem.

  1. Consistency with other taxonomy APIs, e.g. GBIF species API https://www.gbif.org/developer/species I disagree with this. We do not want to be constrained by this kind of requirement.

  2. Usability - making the API clear and easy to implement (developers) and use (users)

Users do not use APIs. Developers do. I would change this to:

  1. Usability - making the API clear and easy to implement (developers).

On 14 March 2018 at 12:20, antonoberg notifications@github.com wrote:

I dont think its an issue to use filter[somethingWeird] as long as its well documented in api documentation. I think we should not deviate from the json api specification if we dont have to. From a frontend / api consumer perspective its easier to work with fewer resources/set of responses. Fewer resources makes it easier to reuse stuff in the frontend.

The following looks fine to me: /taxon?filter[tnrs]=.... /taxon?filter[year]=1985... /taxon?filter[autocomplete]=....

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/DINA-Web/taxonomy/issues/3#issuecomment-373083196, or mute the thread https://github.com/notifications/unsubscribe-auth/AAwbhjv4QD6PkOS5WtFnv6kC75uwSBCBks5teUNrgaJpZM4SIeGE .