search

ropensci / qualtRics

Download ⬇️ Qualtrics survey data directly into R!
https://docs.ropensci.org/qualtRics
Other
215 stars 70 forks source link

what's the verb for a function to change survey options (and similar)? #264

Open jmobrien opened 2 years ago

jmobrien commented 2 years ago

Thought I'd hammer out something for #215 and similar, since it shouldn't be too hard with the new framework. What should we call it, though? Do we need a new verb?

So far, "fetch" seems generally for downloading content from an endpoint, while I suppose "extract" pulls things out of existing downloads (e.g., extract_colmap. ) It's not really an explicit rule so I don't want to overstate the case (list_distirbution_links() and all_surveys() are both "fetches" of sorts, while fetch_id() "extracts" something from a dataframe downloaded fromall_surveys()`.

But if we're about to introduce new things like adjusting options (#215), or adding questions (#228), we're in different territory from anything that came before, so I thought I'd bring the topic up.

juliasilge commented 2 years ago

This is a great question. Do you have a suggestion for these kinds of verbs as a user? I was picturing using deactivate_survey() for #215 but that adds a new verb. I hadn't really thought through what type of naming scheme to use for question creation.

jmobrien commented 2 years ago

I think it might depend on how further development is to proceed. One option would be to focus on specialist functions like deactivate_survey(), which query the API in a particular way. Another option would be to focus on functions that generally try to get most/all of the available utility from any given endpoint.

For the latter view, #266 shows 2 new prototype functions that query the survey-definitions/metadata endpoint, just in slightly different ways:

https://api.qualtrics.com/a92bfbc7e58fe-get-survey-metadata https://api.qualtrics.com/ae7f40bbcb91a-update-metadata

These were easy to build--I just added all the available arguments to the body-generating function, then passed it to the querying function. Really most of the effort was in writing a bit of documentation (only partially done).

If we go this way, it might make sense to stick with some kind of verb schema for what classes of functions do. I used our "fetch" and Qualtrics's own "update" for these, but take them just as examples. (But something like update_survey_questions() could work if we stick with that framework, I suppose.)

The alternative would be a specialist route like activate_survey() and deactivate_survey. In theory, those could be just as easy to build; just pass only the relevant argument(s). (Though, perhaps a bit harder to maintain). Under that approach I suppose names would just follow function. It's really just a design preference b/w a larger number of focused tools vs. a fewer number of consolidated ones matching the API. Both have advantages I'd think. What do you prefer?

jmobrien commented 2 years ago

BTW, related to these draft names--do you think it might be time to fully retire the old V2 description endpoint in metadata()? Seems like it's a regular source of confusion because of the ways the things it returns don't necessarily match the response downloads anymore.

juliasilge commented 2 years ago

I think you're right that specialist functions would be harder to maintain in the long run, and to adjust for various changes in the Qualtrics API. This makes me lean toward some verbs like "fetch" (since it's been in the package already for so long) and "update". 👍

jmobrien commented 2 years ago

Okay, I can just roll with finishing this draft PR then. I may have some questions about that, but I'll post those over there.