last fixes

R/gen_alternative_terms.R

@@ -1,4 +1,4 @@
-#' gen_alternative_terms
+#' Find similar search terms
 #'
 #' @description Function to find search terms that are similar or related to one another in spelling and also represented in the GENESIS, Zensus 2022 or regionalstatistik.de databases. Important note: The API call is searching for terms with the same characters. To be useful in searching for related terms it is highly recommended to work with "*" placeholders (see examples). The placeholder can be placed before and/or after the search term.
 #'
@@ -32,12 +32,15 @@ gen_alternative_terms <- function(term = NULL,
                                   verbose = TRUE,
                                   ...) {
 
+  # Determine calling function; important for checking parameter values
   caller <- as.character(match.call()[1])
 
+  # Check availability of credentials for the database(s) selected
   database_vector <- test_database_function(database,
                                             error.input = TRUE,
                                             text = verbose)
 
+  # Check parameter values
   check_function_input(term = term,
                        similarity = similarity,
                        pagelength = pagelength,
@@ -46,16 +49,18 @@ gen_alternative_terms <- function(term = NULL,
 
   #-----------------------------------------------------------------------------
 
+  # Loop over databases in database_vector and make respective API calls
   res <- lapply(database_vector, function(db){
 
-    if (verbose) {
+    if (isTRUE(verbose)) {
 
       info <- paste("Started the processing of", db, "database.")
 
       message(info)
 
     }
 
+    # Make API call
     results_raw <- gen_api(endpoint = "catalogue/terms",
                            database = db,
                            username = gen_auth_get(database = db)$username,
@@ -65,21 +70,23 @@ gen_alternative_terms <- function(term = NULL,
 
     #---------------------------------------------------------------------------
 
+    # Test validity of JSON results
     results_json <- test_if_json(results_raw)
 
-    if (length(results_json$List) == 0  & length(database_vector) == 1) {
+    # Begin data processing based on function parameters
+    if (length(results_json$List) == 0 & length(database_vector) == 1) {
 
       stop("No related terms found for your code.", call. = FALSE)
 
-    } else if (length(results_json$List) == 0  & length(database_vector) > 1) {
+    } else if (length(results_json$List) == 0 & length(database_vector) > 1) {
 
       termslist <- "No related terms found for your code."
 
       list_resp <- list("Output" = termslist)
 
     } else {
 
-      # similarity von Woertern berechnen und nach diesen Ordnen?
+      # Calculate similarity of words and order
 
       termslist <- c()
 
@@ -116,6 +123,7 @@ gen_alternative_terms <- function(term = NULL,
 
     }
 
+    # Append attributes to the result object(s)
     attr(list_resp, "Term") <- term
     attr(list_resp, "Database") <- db
     attr(list_resp, "Language") <- results_json$Parameter$language
@@ -126,6 +134,7 @@ gen_alternative_terms <- function(term = NULL,
 
   })
 
+  # Check validity of results
   res <- check_results(res)
 
   return(res)

R/gen_api.R

@@ -1,6 +1,6 @@
-#' gen_api
+#' Upper level basic API request function of {restatis}
 #'
-#' @description Wrapper function to either use cached version of gen_api or un-cached version
+#' @description Upper-level function to interact with the one of the APIs
 #'
 #' @param ... Parameters passed on to the API call
 #' @param use_cache Get the option value on whether the call should be cached or not
@@ -16,6 +16,7 @@
 gen_api <- function(...,
                     use_cache = getOption("restatis.use_cache", TRUE)) {
 
+  # Choose executing function based on cache option
   if (isTRUE(use_cache)) {
 
     return(.gen_api_cached(...))
@@ -30,9 +31,9 @@ gen_api <- function(...,
 
 #-------------------------------------------------------------------------------
 
-#' .gen_api_core
+#' Basic API request function of {restatis}
 #'
-#' @description Low-level function to interact with the one of the APIs
+#' @description (Uncached) Low-level function to interact with the one of the APIs
 #'
 #' @param endpoint Character string. The endpoint of the API that is to be queried.
 #' @param database The database the query should be sent to.
@@ -46,7 +47,7 @@ gen_api <- function(...,
 
   #-----------------------------------------------------------------------------
 
-  # Define URLs
+  # Define URLs depending on database chosen
 
   if (database == "genesis") {
 
@@ -62,40 +63,37 @@ gen_api <- function(...,
 
   }
 
+  # Set user agent
   user_agent <- "https://github.com/CorrelAid/restatis"
 
   #-----------------------------------------------------------------------------
 
   # First try to request with POST
   # If POST errors, try GET
+  # This allows flexibility across different database instances
 
-  tryCatch(
+  tryCatch( # tryCatch to try POST
 
-    error = function(cnd) {
-
-      httr2::request(url) %>%
-        httr2::req_user_agent("https://github.com/CorrelAid/restatis") %>%
-        httr2::req_url_path_append(endpoint) %>%
-        httr2::req_url_query(!!!gen_auth_get(database = database), ...) %>%
-        httr2::req_retry(max_tries = 3) %>%
-        httr2::req_perform()
-
-    }, {
+    expr = {
 
+      # Catch API parameter values for ...
       body_parameters <- list(...)
 
+      # Check if there are any items in ...
       if (length(body_parameters) > 0) {
 
         req <- httr2::request(url) %>%
           httr2::req_body_form(!!!body_parameters)
 
       } else {
 
+        # To make a request work with empty ... we need a fake body
         req <- httr2::request(url) %>%
           httr2::req_body_form(!!!list("foo" = "bar"))
 
       }
 
+      # Perform API call with POST
       req %>%
         httr2::req_user_agent(user_agent) %>%
         httr2::req_url_path_append(endpoint) %>%
@@ -105,9 +103,29 @@ gen_api <- function(...,
         httr2::req_retry(max_tries = 3) %>%
         httr2::req_perform()
 
+    }, error = function(e) {
+
+      tryCatch( # tryCatch to try GET
+
+        expr = {
+
+          # Perform API call with GET (deprecated in GENESIS and Zensus 2022)
+          httr2::request(url) %>%
+            httr2::req_user_agent("https://github.com/CorrelAid/restatis") %>%
+            httr2::req_url_path_append(endpoint) %>%
+            httr2::req_url_query(!!!gen_auth_get(database = database), ...) %>%
+            httr2::req_retry(max_tries = 3) %>%
+            httr2::req_perform()
+
+        }, error = function(e) {
+
+          stop(paste0("The API call(s) have been tried with GET and POST methods, but were unsuccessful (error message: '", e$message, "'). Check your specifications or try again later."),
+               call. = FALSE)
+
+      })
+
     })
 
   #-----------------------------------------------------------------------------
 
-
 }