Creating base get_meta() function to retrieve data set meta data

DESCRIPTION

@@ -2,8 +2,10 @@ Package: eesyapi
 Title: EES-y API
 Version: 0.0.0.9000
 Authors@R: 
+    c(
     person("Rich", "Bielby", , "[email protected]", role = c("aut", "cre"),
-           comment = c(ORCID = "0000-0001-9070-9969"))
+           comment = c(ORCID = "0000-0001-9070-9969")),
+    person("Cam", "Race", , "[email protected]", role = "aut"))
 Description: An R package with useful utility functions for connecting to, and
     processing data from, the DfE's Explore Education Statistics API.
 License: MIT + file LICENSE
@@ -15,4 +17,5 @@ Suggests:
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
 Imports: 
-    httr
+    httr,
+    jsonlite

NAMESPACE

@@ -1,3 +1,5 @@
 # Generated by roxygen2: do not edit by hand
 
 export(eesapi_url)
+export(get_meta)
+export(http_request_error)

R/get_meta.R

@@ -0,0 +1,107 @@
+#' Get a data set's metadata
+#'
+#' @description
+#' Get a list of metadata information for a data set available from the EES API. Provides either
+#' look-up tables from human readable labels to ids used in the API, or the raw response from the
+#' meta endpoint.
+#'
+#' @param dataset_id ID of data set to be connected to
+#' @param dataset_version Version of data set to be connected to
+#' @param api_version EES API version
+#' @param parse Parse result into structured list
+#'
+#' @return Results of query to meta data
+#' @export
+#'
+#' @examples
+#' get_meta("d7329101-f275-d277-bbfe-d8cfaa709833")
+get_meta <- function(dataset_id, dataset_version = NULL, api_version = NULL, parse = TRUE) {
+  # Check that the parse flag is valid
+  if (is.logical(parse) == FALSE) {
+    stop(
+      "You have entered an invalid parse argument, this should be a logical TRUE or FALSE only."
+    )
+  }
+
+  # Use eesyapi_url to retrieve the relevant api url - note that this will perform
+  # validation checks on dataset_id, dataset_version and api_version, so haven't
+  # added any explicit validation of those to the current function.
+  meta_url <- eesyapi::eesapi_url(
+    endpoint = "get-meta",
+    dataset_id = dataset_id,
+    dataset_version = dataset_version
+  )
+
+  response <- httr::GET(meta_url)
+  if (response$status_code > 299) {
+    stop(paste0(
+      "Query returned error, status: ",
+      response$status,
+      "\n      ",
+      eesyapi::http_request_error(response$status)
+    ))
+  } else {
+    if (parse) {
+      result <- response |>
+        httr::content("text") |>
+        jsonlite::fromJSON()
+    } else {
+      result <- response
+    }
+    return(result)
+  }
+}
+
+#' Parse API meta to give the filter columns
+#'
+#' @param api_meta_filters Filter information provided by the API output
+#'
+#' @return data frame containing column names and labels
+#' @export
+#'
+#' @examples
+parse_meta_filter_columns <- function(api_meta_filters) {
+  data.frame(
+    col_name = api_meta_filters$id,
+    col_label = api_meta_filters$label
+  )
+}
+
+#' Parse API meta to give the filter item codes
+#'
+#' @param api_meta_filters Filter information provided by the API output
+#'
+#' @return Data frame containing filter item codes matched to filter item labels and col_name
+#' @export
+#'
+#' @examples
+parse_meta_filter_item_codes <- function(api_meta_filters) {
+  nfilters <- length(api_meta_filters$id)
+  filter_items <- data.frame(
+    col_name = NA,
+    item_code = NA,
+    item_label = NA,
+    isAggregate = NA
+  ) |>
+    dplyr::filter(!is.na(col_name))
+  for (i in 1:nfilters) {
+    filter_items_i <- as.data.frame(
+      api_meta_filters$options[i]
+    ) |>
+      dplyr::rename(
+        item_code = id,
+        item_label = label
+      ) %>%
+      dplyr::mutate(col_name = api_meta_filters$id[i])
+    if (!("isAggregate" %in% names(filter_items_i))) {
+      filter_items_i <- filter_items_i |>
+        dplyr::mutate(isAggregate = NA)
+    }
+    filter_items <- filter_items |>
+      rbind(
+        filter_items_i |>
+          dplyr::select(col_name, item_label, item_code, isAggregate)
+      )
+  }
+  return(filter_items)
+}

R/helper_functions.R

@@ -0,0 +1,20 @@
+#' http request error
+#'
+#' @description
+#' Translate a http error code into an error message.
+#'
+#' @param response_status Response code from an API request
+#'
+#' @return Translation of the response code
+#' @export
+#'
+#' @examples
+#' http_request_error(200)
+http_request_error <- function(response_status) {
+  status_lookup <- list(
+    "200" = "Successful API request.",
+    "400" = "Invalid query, data set ID, data set version or API version submitted to API.",
+    "500" = "Internal server error encountered."
+  )
+  status_lookup[format(round(response_status, -1))][[1]]
+}

tests/testthat/test-get_meta.R

@@ -0,0 +1,23 @@
+test_that("Dataset ID not found", {
+  expect_error(get_meta("this-is-not-a-dataset"))
+})
+
+test_that("Non-logical parse flag given", {
+  expect_error(
+    get_meta("this-is-not-a-dataset", parse = 1),
+    "You have entered an invalid parse argument, this should be a logical TRUE or FALSE only."
+  )
+})
+
+
+# This test uses an existing test data set ID from EES admin. So this test could
+# fail if either the code is broken, the data set gets taken down or the dev
+# site is down. I guess this isn't totally within the usual principles of
+# package testing, but putting in for now partially as a useful check on some
+# of the above collectively.
+test_that("Meta query runs successfully", {
+  expect_equal(
+    get_meta("d7329101-f275-d277-bbfe-d8cfaa709833", parse = FALSE)$status,
+    200
+  )
+})

tests/testthat/test-helper_functions.R

@@ -0,0 +1,14 @@
+test_that("Successful connection message", {
+  expect_equal(http_request_error(200), "Successful API request.")
+})
+
+test_that("Bad URL / query message", {
+  expect_equal(
+    http_request_error(404),
+    "Invalid query, data set ID, data set version or API version submitted to API."
+  )
+})
+
+test_that("Server error message", {
+  expect_equal(http_request_error(503), "Internal server error encountered.")
+})