Creating and setting tags are still too difficult

[gadenbuie]

I'm going to echo https://github.com/rstudio/connectapi/issues/136 and say that I've found creating and setting tags to be difficult. I'll caveat and say that this is just my experience and I may just not have found the connectapi happy path.

What I'd like to do

What'd I'd really like to be able to do is to consistently work with tags in a list format like this:

tags <- list("Team" = c("Red Team", "Blue Team"))

Ideally, users could create a new tag by providing a nested list

connectapi::create_tag(client, list(Team = "Green Team"))

or to use the same syntax add tags to content

connectapi::set_content_tags(content, list(Team = "Red Team"))

Connect disallows sibling tags or categories to have the same name, so the tag id is redundant. If it's necessary to lookup the tag id or use the full tag data for a certain action, you could also have a helper function to get a single tag:

connectapi::get_tag(client, list(Team = "Blue Team"))

This function could error or could return an empty list if the tag doesn't exist.

Current API

Here are some struggles I've had with the current API. First, it's quite a bit of extra work to determine if a tag exists in the first place. There is get_tag_data() but I'd still need do several passes over the tag data to work out the content tree hierarchy. Alternatively, I could use get_tags() and do some tree walking, but at this point I'm like I'm about to start writing too much code and that I'd really like connectapi to do this work for me.

Okay, assuming I need to create a tag, I tried calling

connectapi::create_tag(client, "Orange Team")
#> RStudio Connect Tag Tree (filtered)
#> └── Orange Team

but it turns out this creates a category rather than a tag (and also I'll need a parent, which I hadn't yet realized). After fixing the category name manually in Connect's UI, I tried

connectapi::create_tag(client, "Orange Team", "Team")
#> Error in connectapi::create_tag(client, "Orange Team", "Team") : 
#>   `parent` must be an ID or a connect_tag_tree object

which means that I now need to figure out the id of the "Team" category, which I can do by inspecting get_tags(). But again this is more code than I want to maintain in my own package. Once I find the id, it's not terrible to create a new tag:

connectapi::create_tag(client, "Orange Team", 3)
#> RStudio Connect Tag Tree (filtered)
#> └── Team
#>    └── Orange Team

But now I have to a go through a similar amount of work to add the newly created tag to a content item. Because create_tag() will error if they tag name already exists under the parent, my main code path has to go back to get_tags() to get the tag object, which I need to filter down to a connect_tag_tree that can be used with set_content_tags(). Again, this feels like a lot of extra code to write and maintain where connectapi could be more helpful.

[colearendt]

Thanks so much for the thorough review here! Does this writeup help at all? create_tag_tree() does some of what you want

https://rstudio.github.io/connectapi/articles/connectapi_tags.html

I'll take a look at what it would take to create the list-based interface you articulated - I agree that that could be nice! I don't think it is a stretch from the underlying tag_tree structure that we built within connectapi.

[gadenbuie]

Oh, I hadn't found that article. Working with tags does seem to be a whole lot easier than I was making it 🤔

[colearendt]

It sounds like we definitely still have some discoverability issues though 🙈 😅 Perhaps reducing the number of functions or changing some of the verbiage would make it easier to discover the happy path. Naming is hard!