WIP #152: dataset_list

* Warn if ODKC version too low
* Modernised parsing of httr::content()

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: ruODK
 Title: An R Client for the ODK Central API
-Version: 1.4.2
+Version: 1.5.0.9000
 Authors@R: 
     c(person(given = c("Florian", "W."),
              family = "Mayer",

NAMESPACE

@@ -6,6 +6,7 @@ export(attachment_get)
 export(attachment_link)
 export(attachment_list)
 export(audit_get)
+export(dataset_list)
 export(drop_null_coords)
 export(encryption_key_list)
 export(enexpr)

R/dataset_list.R

@@ -0,0 +1,82 @@
+#' List all datasets of one project.
+#'
+#' While the API endpoint will return all datasets for one project,
+#' \code{\link{dataset_list}} will fail with incorrect or missing
+#' authentication.
+#'
+#' A Dataset is a named collection of Entities that have the same properties.
+#' A Dataset can be linked to Forms as Attachments. This will make it available
+#' to clients as an automatically-updating CSV.
+#'
+#' This function is supported from ODK Central v2022.3 and will warn if the
+#' given odkc_version is lower.
+#'
+#' `r lifecycle::badge("maturing")`
+#'
+#' @template param-pid
+#' @template param-url
+#' @template param-auth
+#' @template param-retries
+#' @template param-odkcv
+#' @template param-orders
+#' @template param-tz
+#' @return A tibble with exactly one row for each dataset of the given project
+#'   as per ODK Central API docs.
+#'   Column names are renamed from ODK's `camelCase` to `snake_case`.
+# nolint start
+#' @seealso \url{ https://docs.getodk.org/central-api-dataset-management/#datasets}
+# nolint end
+#' @family dataset-management
+#' @export
+#' @examples
+#' \dontrun{
+#' # See vignette("setup") for setup and authentication options
+#' # ruODK::ru_setup(svc = "....svc", un = "[email protected]", pw = "...")
+#'
+#' ds <- dataset_list(pid = get_default_pid())
+#'
+#' ds |> knitr::kable()
+#' }
+dataset_list <- function(pid = get_default_pid(),
+                           url = get_default_url(),
+                           un = get_default_un(),
+                           pw = get_default_pw(),
+                           retries = get_retries(),
+                         odkc_version = get_default_odkc_version(),
+                         orders = c(
+                           "YmdHMS",
+                           "YmdHMSz",
+                           "Ymd HMS",
+                           "Ymd HMSz",
+                           "Ymd",
+                           "ymd"
+                         ),
+                         tz = get_default_tz()) {
+  yell_if_missing(url, un, pw, pid = pid)
+
+  if (odkc_version |> semver_lt("2022.3")) {
+    ru_msg_warn("dataset_list is supported from v2022.3")
+  }
+
+  httr::RETRY(
+    "GET",
+    httr::modify_url(url, path = glue::glue("v1/projects/{pid}/datasets")),
+    httr::add_headers(
+      "Accept" = "application/json",
+      "X-Extended-Metadata" = "true"
+    ),
+    httr::authenticate(un, pw),
+    times = retries
+  ) |>
+    yell_if_error(url, un, pw) |>
+    httr::content(encoding="utf-8") |>
+    purrr::list_transpose() |>
+    tibble::as_tibble() |>
+    janitor::clean_names() |>
+    dplyr::mutate_at(
+      dplyr::vars(c("created_at", "last_entity")),
+      ~ isodt_to_local(., orders = orders, tz = tz)
+    )
+}
+
+# usethis::use_test("dataset_list") # nolint

_pkgdown.yml

@@ -23,6 +23,14 @@ reference:
   desc: "Functions to manage projects."
   contents:
   - has_concept("project-management")
+- title: Datasets
+  desc: "Functions to manage datasets of entities."
+  contents:
+  - has_concept("dataset-management")
+- title: Entities
+  desc: "Functions to manage entities."
+  contents:
+  - has_concept("entity-management")
 - title: Forms
   desc: >
     Functions to manage forms.

tests/testthat/test-dataset_list.R

@@ -0,0 +1,56 @@
+test_that("dataset_list works", {
+  skip_if(Sys.getenv("ODKC_TEST_URL") == "",
+          message = "Test server not configured"
+  )
+
+  ds <- dataset_list(
+    get_test_pid(),
+    url = get_test_url(),
+    un = get_test_un(),
+    pw = get_test_pw(),
+    odkc_version = get_test_odkc_version()
+  )
+  testthat::expect_true(nrow(ds) > 0)
+  testthat::expect_true("name" %in% names(ds))
+
+  # function returns a tibble
+  testthat::expect_s3_class(ds, "tbl_df")
+
+  # Expected column names
+  cn <- c(
+    "name",
+    "created_at",
+    "project_id",
+    "approval_required",
+    "entities",
+    "last_entity",
+    "conflicts"
+  )
+  testthat::expect_equal(names(ds), cn)
+})
+
+
+test_that("dataset_list warns if odkc_version too low", {
+  skip_if(Sys.getenv("ODKC_TEST_URL") == "",
+          message = "Test server not configured"
+  )
+
+  ds <- dataset_list(
+    get_test_pid(),
+    url = get_test_url(),
+    un = get_test_un(),
+    pw = get_test_pw(),
+    odkc_version = "2022.3"
+  )
+
+  testthat::expect_warning(
+    ds <- dataset_list(
+      get_test_pid(),
+      url = get_test_url(),
+      un = get_test_un(),
+      pw = get_test_pw(),
+      odkc_version = "1.5.3"
+    )
+  )
+
+})