[#56] | Implement pagination

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: kbtbr
 Type: Package
 Title: A Wrapper for the KoBoToolbox API
-Version: 0.1.0.9000
+Version: 0.1.0.9002
 Authors@R: c(person("Dimitri", "Marinelli", role = c("aut")),
             person("Lada", "Rudnitckaia", role = "aut"),
             person("Malte", "Kyhos", role = "aut"),

R/kobo-paginator.R

@@ -0,0 +1,83 @@
+#' @title KoboPaginator
+#' @description
+#' A class that implements link-header style pagination, as is used in
+#' the Kobotoolbox API.
+#' @export
+KoboPaginator <- R6::R6Class(
+  public = list(
+    client = NULL,
+    #' @description
+    #' @param client KoboClient. An instance of a KoboClient that can
+    #'  be used for the paginated requestes.
+    initialize = function(client) {
+      private$client <- assert_class(client, "KoboClient")
+    },
+    #' @description
+    #' @param path
+    #' @param query
+    #' @param ... Additional parameters passed to internally
+    #'  called `KoboClient$get()`.
+    get = function(path, query, ...) {
+      assert_string(path)
+      assert_string(query)
+      private$page(path, query, ...)
+    },
+    #' @description
+    #' Set the initial response
+    #' @details
+    #' Usually, the page method would revoke a first response in the
+    #' normal way, using its `next` element to walk over all subsequent
+    #' pages. In some settings, the user might provide this initial response
+    #' object already.
+    set_first_response = function(response, force_reset = FALSE) {
+      assert_list(response)
+      if (!(force_reset || is.null(private$resps))) {
+        stop("There are already existing responses. Use 'force_reset = TRUE' to reset/delete them.")
+      }
+      private$resps <- list(response)
+    },
+    get_responses = function() {
+      return(private$resps)
+    }
+  ),
+  private = list(
+    resps = NULL,
+    page = function(path, query, sleep = 0.5, ...) {
+      tmp <- list()
+
+      # Retrieve initial response
+
+      # Initialize Pagination
+      tmp[[1]] <- private$resps[[1]] %||% self$client$get(path, query, ...)
+      next_link <- tmp[[1]][["next"]]
+      cnt <- 1
+
+      repeat {
+        if (is.null(next_link)) {
+          message(sprintf("Iterated over %s pages.", cnt))
+          break
+        }
+
+        # New iteration
+        Sys.sleep(sleep)
+        cnt <- cnt + 1
+        tmp_path <- private$resolve_next(next_link)
+
+        tmp[[cnt]] <- self$client$get(tmp_path, query, ...)
+        tmp[[cnt]]$raise_for_status()
+        next_link <- tmp[[cnt]][["next"]]
+      }
+
+      private$resps <- tmp
+    },
+    resolve_next = function(link) {
+      # Subtract base path etc. from
+      resolved <- gsub(
+        pattern = paste0("^", self$client$get_base_url()),
+        replacement = "",
+        x = link
+      )
+      return(resolved)
+    }
+  )
+)

R/kobo.R

@@ -6,15 +6,13 @@
 #' interactions with the various endpoints.
 #' @export
 Kobo <- R6::R6Class("Kobo",
-  # private = list(
-  # ),
   public = list(
 
     # Public Fields ============================================================
 
     #' @field session_v2 [kbtbr::KoboClient] session for v2 of the API
     session_v2 = NULL,
-    #' @field session_v1 `KoboClient` session for v1 of the API
+    #' @field session_v1 [KoboClient] session for v1 of the API
     session_v1 = NULL,
 
     # Public Methods ===========================================================
@@ -28,9 +26,9 @@ Kobo <- R6::R6Class("Kobo",
     #'  For example: https://kc.correlaid.org.
     #' @param kobo_token character. The API token. Defaults to requesting
     #'  the systen environment `KBTBR_TOKEN`.
-    #' @param session_v2 [KoboClient] To pass directly
+    #' @param session_v2 [KoboClient]. Alternatively, pass directly
     #' a [KoboClient] instance for the API version v2.
-    #' @param session_v1 [KoboClient] In addition to session_v2 one can pass
+    #' @param session_v1 KoboClient. In addition to session_v2 one can pass
     #' also a [KoboClient] instance for the API version v1.
     initialize = function(base_url_v2 = NULL, base_url_v1 = NULL,
                           kobo_token = Sys.getenv("KBTBR_TOKEN"),
@@ -68,7 +66,7 @@ Kobo <- R6::R6Class("Kobo",
     #' @param format character. the format to request from the server. either 'json' or 'csv'. defaults to 'json'
     #' @param parse whether or not to parse the HTTP response. defaults to TRUE.
     #' @return a list encoding of the json server reply if parse=TRUE.
-    #'   Otherwise, it returns the server response as a crul::HttpResponse
+    #'   Otherwise, it returns the server response as a [crul::HttpResponse]
     #'   object.
     get = function(path, query = list(), version = "v2", format = "json",
                    parse = TRUE) {
@@ -107,9 +105,12 @@ Kobo <- R6::R6Class("Kobo",
         )
       }
 
+      # Select client
+      obj <- private$select_prep_client(path, version)
+      res <- obj$client$get(obj$path, query)
       res$raise_for_status()
 
-      if (format == "json" & parse) {
+      if (parse && format == "json") {
         res$raise_for_ct_json()
         return(res$parse("UTF-8") %>% jsonlite::fromJSON())
       } else if (format == "csv" & parse) {
@@ -123,6 +124,13 @@ Kobo <- R6::R6Class("Kobo",
       }
       return(res)
     },
+    get_paginated = function(path, query, version = "v2",
+                             format = "json",
+                             parse = TRUE) {
+      obj <- private$select_prep_client(path, version)
+      paginator <- KoboPaginator$new(client = obj$client)
+      res <- paginator$get(path, query)
+    },
 
     #' @description
     #' Wrapper for the POST method of internal session objects.
@@ -302,5 +310,35 @@ Kobo <- R6::R6Class("Kobo",
       )
       self$post("assets/", body = body)
     }
-  ) # <end public>
+  ), # <end public>
+  private = list(
+
+    # Private Methods ==========================================================
+
+    #' @description
+    #' Logic to select and prepare a client
+    select_prep_client = function(path, version) {
+      checkmate::assert_choice(version, c("v1", "v2"))
+
+      if (version == "v2") {
+        obj <- list(
+          client = self$session_v2,
+          path = paste0("api/v2/", path)
+        )
+      } else if (version == "v1") {
+        if (checkmate::test_null(self$session_v1)) {
+          usethis::ui_stop(paste(
+            "Session for API v1 is not initalized.",
+            "Please re-initalize the Kobo client with the",
+            "base_url_v1 argument."
+          ))
+        }
+        obj <- list(
+          client = self$session_v1,
+          path = paste0("api/v1/", path)
+        )
+      }
+      return(obj)
+    }
+  )
 )

tests/testthat/test-kobo.R

@@ -118,7 +118,9 @@ test_that("Kobo can get submissions for a survey", {
   expect_true(tibble::is_tibble(response_df))
   expect_equal(nrow(response_df), 4)
 })
+
 # ERRORS -----------
+
 vcr::use_cassette("kobo-get-404", {
   test_that("non existing route throws 404 error", {
     kobo <- Kobo$new(base_url_v2 = BASE_URL, kobo_token = Sys.getenv("KBTBR_TOKEN"))