RFC: A new user experience for connectapi

Follow pattern of posit-sdk: base Resources and Resource classes, containers and object inheriting from them.

Resources (collections) have an as.data.frame() method to return a data frame (like the get_content() etc. functions do now). Otherwise they are just interfaces.

Assuming R6, you could chain things together with $, like client$users$get_by_id(1)$update(first_name = "Jane"), but that's not idiomatic R. So we can add some helper functions like this:

users <- function(object) {
  object$users
}

# actually, update is a S3 generic in stats, so you'd do this with methods
update <- function(object, ...) {
  object$update(...)
}

Then you can pipe.

client |>
  users() |>
  create(first_name = "John", last_name = "Doe")

client |>
  users() |>
  get_by_id(1) |>
  update(first_name = "Jane")

client |>
  content() |>
  as.data.frame()

client |>
  content() |>
  get_all() # returns a list

Defer all requests until actually needed. I.e. client |> users() doesn't request all users because you don't need them if you're then going to do create() or get_by_id().

The reason to use R6 would be for memoizing the requests. For example, if you do client |> users() |> get_by_id(1), we still haven't made any HTTP requests. Only if you do client |> users() |> get_by_id(1) |> first_name() would we actually make the request, then cache the response data in the object, so that if we then did last_name(), we wouldn't have to request again. And if we instead did client |> users() |> get_by_id(1) |> update(first_name == "Jane"), we would only make the PATCH request, no GET.

We could also handle this caching at the HTTP layer, and then we wouldn't necessarily benefit from R6. https://enpiar.com/r/httpcache/ is a package I wrote for this a while back that we could use.

Start by comparing the current connectapi client and functions with the posit-sdk Resources and Resource pattern described here. Review the deferred-request, R6 memoization, and HTTP caching alternatives; no files, tests, or accepted design are named, so completion cannot be defined until the RFC is resolved.