Move from a response type to a separate get-csv endpoint

R/api_url.R

@@ -9,17 +9,16 @@
 #' \strong{Endpoints} \tab \strong{id required} \cr
 #' get-publications \tab Neither  \cr
 #' get-data-catalogue \tab publication_id  \cr
-#' get-summary, get-meta, get-data, post-data \tab dataset_id  \cr
+#' get-summary, get-meta, get-csv, get-data, post-data \tab dataset_id  \cr
 #' }
 #'
 #' @param endpoint Name of endpoint, can be "get-publications", "get-data-catalogue",
-#' "get-summary", "get-meta", "get-data" or "post-data"
+#' "get-summary", "get-meta", "get-csv", "get-data" or "post-data"
 #' @param publication_id ID of the publication to be connected to. This is required if the
 #' endpoint is "get-data-catalogue"
 #' @param dataset_id ID of data set to be connected to. This is required if the endpoint is one
-#' of "get-summary", "get-meta", "get-data" or "post-data"
+#' of "get-summary", "get-meta", "get-csv", "get-data" or "post-data"
 #' @inheritParams api_url_query
-#' @param response_format Requested format of response, JSON by default, can also be CSV
 #' @param dataset_version Version of data set to be connected to
 #' @param page_size Number of results to return in a single query
 #' @param page Page number of query results to return
@@ -35,6 +34,7 @@
 #' api_url("get-data-catalogue", publication_id = eesyapi::example_id("publication"))
 #' api_url("get-summary", dataset_id = eesyapi::example_id("dataset"))
 #' api_url("get-meta", dataset_id = eesyapi::example_id("dataset"))
+#' api_url("get-csv", dataset_id = eesyapi::example_id("dataset"))
 #' api_url(
 #'   "get-data",
 #'   dataset_id = eesyapi::example_id("dataset"),
@@ -50,7 +50,6 @@
 #' )
 api_url <- function(
     endpoint = "get-publications",
-    response_format = "JSON",
     publication_id = NULL,
     dataset_id = NULL,
     indicators = NULL,
@@ -85,7 +84,7 @@ api_url <- function(
     endpoint %in% c(
       "get-publications", "get-data-catalogue",
       "get-summary", "get-meta",
-      "get-data", "post-data"
+      "get-csv", "get-data", "post-data"
     )
   }
 
@@ -94,7 +93,8 @@ api_url <- function(
       stop(
         paste(
           "You have entered an invalid endpoint, this should one of:",
-          "get-summary, get-meta, get-data or post-data"
+          "get-publication, get-data-catalogue, get-summary, get-meta,",
+          "get-csv, get-data or post-data"
         )
       )
     }
@@ -105,7 +105,7 @@ api_url <- function(
   }
 
   # Check that if endpoint requires a data set then dataset_id is not null
-  if (endpoint %in% c("get-summary", "get-meta", "get-data", "post-data")) {
+  if (endpoint %in% c("get-summary", "get-meta", "get-csv", "get-data", "post-data")) {
     eesyapi::validate_ees_id(dataset_id, level = "dataset")
     if (is_valid_dataset_info(dataset_id, dataset_version) == FALSE) {
       stop(
@@ -130,12 +130,6 @@ api_url <- function(
       )
     )
   }
-
-  # Validate response format
-  if (!response_format %in% c("JSON", "CSV")) {
-    stop("response_format must be either JSON or CSV")
-  }
-
   # End of validation
 
   endpoint_base <- list(
@@ -190,48 +184,45 @@ api_url <- function(
       )
     }
     if (endpoint == "get-data") {
-      # Shortcut if just getting a CSV
-      # Currently no support for anything more so ignoring most of the params
-      if (response_format == "CSV") {
-        url <- paste0(
-          endpoint_base_version,
-          "data-sets/",
-          dataset_id,
-          "/csv"
-        )
-      } else {
-        # Do full querying if JSON format
-
-        # Force default page size if page is given by user and page_size isn't
-        if (!is.null(page) && is.null(page_size)) {
-          page_size <- 1000
-        }
-        # Force first page if page size is given by user and page isn't
-        if (!is.null(page_size) && is.null(page)) {
-          page <- 1
-        }
-        if (verbose) {
-          message(paste("paging:", page, page_size))
-        }
-        url <- url |>
-          paste0(
-            eesyapi::api_url_query(
-              indicators = indicators,
-              time_periods = time_periods,
-              geographic_levels = geographic_levels,
-              locations = locations,
-              filter_items = filter_items
-            ),
-            ifelse(
-              !is.null(page) & !is.null(page_size),
-              paste0("&", eesyapi::api_url_pages(page_size = page_size, page = page)),
-              ""
-            )
-          )
+      # Force default page size if page is given by user and page_size isn't
+      if (!is.null(page) && is.null(page_size)) {
+        page_size <- 1000
+      }
+      # Force first page if page size is given by user and page isn't
+      if (!is.null(page_size) && is.null(page)) {
+        page <- 1
+      }
+      if (verbose) {
+        message(paste("paging:", page, page_size))
       }
+      url <- url |>
+        paste0(
+          eesyapi::api_url_query(
+            indicators = indicators,
+            time_periods = time_periods,
+            geographic_levels = geographic_levels,
+            locations = locations,
+            filter_items = filter_items
+          ),
+          ifelse(
+            !is.null(page) & !is.null(page_size),
+            paste0("&", eesyapi::api_url_pages(page_size = page_size, page = page)),
+            ""
+          )
+        )
+    }
+    if (endpoint == "get-csv") {
+      url <- paste0(
+        endpoint_base_version,
+        "data-sets/",
+        dataset_id,
+        "/csv"
+      )
     }
   }
-  if (endpoint %in% c("get-publications", "get-data-catalogue", "get-summary", "get-meta")) {
+  if (endpoint %in% c(
+    "get-publications", "get-data-catalogue", "get-summary", "get-meta", "get-csv"
+  )) {
     if (
       any(!is.null(c(time_periods, geographic_levels, locations, filter_items, indicators)))
     ) {

R/download_dataset.R

@@ -14,8 +14,10 @@
 #' function will likely break whenever there is renaming of variables or items
 #' in the data.
 #'
-#' It is recommended to subscribe to the data set you're querying and then keep
-#' track of any updates, including minor updates to the data.
+#' It is recommended to take the time to set up custom queries using the
+#' `query_dataset()` function instead. If you are using this function for more
+#' than exploratory purposes, make sure you subscribe to the data set you're
+#' downloading and then keep track of any updates to the data.
 #'
 #' @param dataset_id ID of data set
 #' @param dataset_version Version number of data set
@@ -26,11 +28,11 @@
 #' @export
 #'
 #' @examples
-#' download_dataset(example_id("dataset", group = "public-api-testing"))
+#' download_dataset(example_id("dataset"))
 download_dataset <- function(
     dataset_id,
     dataset_version = NULL,
-    api_version = NULL, # TODO: check how this is handled
+    api_version = NULL,
     verbose = FALSE) {
   # Validation ----------------------------------------------------------------
   if (!is.null(dataset_version)) {
@@ -42,12 +44,15 @@ download_dataset <- function(
     )
   }
 
+  if (!is.logical(verbose)) {
+    stop("verbose must be a logical value, either TRUE or FALSE")
+  }
+
   eesyapi::validate_ees_id(dataset_id, level = "dataset")
 
   # Generate query ------------------------------------------------------------
   query_url <- eesyapi::api_url(
-    endpoint = "get-data",
-    response_format = "CSV",
+    endpoint = "get-csv",
     dataset_id = dataset_id,
     verbose = verbose
   )

tests/testthat/test-api_url.R

@@ -50,9 +50,19 @@ test_that("api_url", {
   )
 
   expect_error(
-    api_url(
-      response_format = "wingdings"
-    ),
-    "response_format must be either JSON or CSV"
+    api_url("get-csv"),
+    "The variable dataset_id is NULL, please provide a valid dataset_id."
+  )
+
+  expect_warning(
+    api_url("get-csv", dataset_id = example_id("dataset"), indicators = "qwerty")
   )
+
+  expect_equal(
+    api_url("get-csv", dataset_id = example_id("dataset")),
+    paste0(
+      "https://dev.statistics.api.education.gov.uk/api/v1.0/data-sets/",
+      example_id("dataset"),
+      "/csv"
+    ))
 })

tests/testthat/test-download_dataset.R

@@ -1,15 +1,12 @@
 test_that("Returns a data frame and has no errors", {
-  expect_true(
-    class(
-      download_dataset(
-        example_id("dataset", group = "public-api-testing")
-      )
-    ) == "data.frame"
-  )
+  expect_true(class(download_dataset(example_id("dataset"))) == "data.frame")
+  expect_no_error(download_dataset(example_id("dataset")))
+})
 
-  expect_no_error(
-    download_dataset(
-      example_id("dataset", group = "public-api-testing")
-    )
+test_that("Unnecessary or incorrect inputs cause errors", {
+  expect_error(download_dataset("ark-of-the-covenent"))
+  expect_error(
+    download_dataset(example_id("dataset"), verbose = "chatty"),
+    "verbose must be a logical value, either TRUE or FALSE"
   )
 })