search

greenelab / adage-backend

The backend for Adage web app
https://adage.greenelab.com
BSD 3-Clause "New" or "Revised" License
2 stars 2 forks source link

Rename some endpoint parameters #30

Closed vincerubinetti closed 4 years ago

vincerubinetti commented 4 years ago

It looks like we already renamed the /mlmodels endpoint to /models. I think it would be a good idea to rename any instance of an mlmodel parameter to model for consistency and simplicity, for the same reasons given in this issue.

I understand that there is a collision of terminology with "model" in that there are "models" in the backend that have nothing to do with the machine learning models. But if I needed a url parameter called component, I wouldn't burden the user with mlcomponent just because "component" is a concept in front-end development. I'd accept the component parameter, then transform it immediately, under the hood, to machineLearningComponent so I could have the distinction I needed. Any experienced frontend developer seeing that parameter name wouldn't assume it's a React component, because it's exposed to the user, and users don't know anything about React. And if some front end dev needed to edit the code, the explicitness of the machineLearningComponent variable should be enough to avoid confusion.

The user should always come before the developer. It seems you're worried that 1) a backend developer looking at the endpoint syntax would think "model" refers to a database model or 2) someone trying to edit the backend code would become confused by the overlap of terms.

For 1), I think 95% of our users will either not know anything about backend development, or are already in the headspace of data science to understand what "model" is referring to. For 2), I think it should still be possible to write the code in such a way that there's no confusion, perhaps in the way I described above.

This particular mlmodel issue is not a big deal to me. But the bigger picture is that I strongly feel that name collisions with under-the-hood stuff should never have any impact on how we design something for a user.

Another parameter that could be renamed is related-genes. What it really is is simply a list of genes that you want to look up the enriched signatures for. When searching for genes, we don't call the search parameter related-genes. Perhaps it could be renamed to search or search-genes or just genes.

dongbohu commented 4 years ago

Not implemented due to the special meaning of model in Django.