search

SpeciesFileGroup / taxonworks_api

Documentation for TaxonWorks APIs
http://api.taxonworks.org
Other
2 stars 6 forks source link

Boolean vs. String params #32

Open mjy opened 4 years ago

mjy commented 4 years ago

Using type: Boolean forces the enum to true or false (true booleans). Technically our back end handles strings, converting them to true or false there. We also handle Capitalized and upcase values as well.

Should we just declare our booleans to be string, so we can provide examples as enums?

LocoDelAssembly commented 4 years ago

https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/#type-declarations

enum? An enumeration of all the possible values of instances of this type. The value is an array containing representations of these possible values; an instance of this type MUST be equal to one of these values.

Given that, I'm not super happy with doing this since rails also support "TrUe" (and maybe some other truthy stuff). On the other hand, we could opt to not specify everything that is supported, and leave anything else as undefined behavior. In this case just enum reasonable variations like you did.

Where is this true/false forcing happening? In the document generation tool?

mjy commented 4 years ago

Rails doesn't support TrUe, Technically we allow TrUe. https://github.com/SpeciesFileGroup/taxonworks/blob/development/lib/queries/taxon_name/filter.rb#L147. IIRC we built in small exceptions to support native conversion of values in Python (or was it R, Javascript), for example from Boolean to string.

true/force downcasing is in documentation, but also validation of the type, so it's more than just rendering.

I think I'm OK with making it RAML boolean for the API purposes, even if we support more in the backend. Just because we do doesn't mean we need to support it.

There are also "Pattern" type matchers that can be used.