In CorrelAid/kbtbr: A Wrapper for the KoBoToolbox API

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>", 
  echo = TRUE
)

# setup vcr
library(vcr)
vcr_dir <- "./assets"
if (!nzchar(Sys.getenv("KBTBR_TOKEN"))) {
    if (dir.exists(vcr_dir)) {
        # Fake API token to fool our package
        Sys.setenv("KBTBR_TOKEN" = "fakebearertoken")
    } else {
        # If there's no mock files nor API token, impossible to run tests
        stop("No API key nor cassettes, tests cannot be run.",
            call. = FALSE
        )
    }
}
invisible(vcr::vcr_configure(
    dir = vcr_dir,
    filter_request_headers = list(Authorization = "fakebearertoken")
))
vcr::check_cassette_names()

KoboClient is an R6 class that manages the connection between R and the server that hosts the KoboToolbox. Most users should not need the KoboClient class because Kobo takes care of the end-user services. Kobo uses KoboClient under the hood.

KoboClient is effectively an HTTP client and inherits its features from the crul library, in particular from crul::HttpClient.

Getting started

Initialization

To start a session, one needs to know the URL to the KoboToolbox server and the API token, a unique key that allows interaction with the Kobo server. You can get the API key in your account settings.

One possibility is to store the token as an environment variable. The KoboClient will check if the variable KBTBR_TOKEN is set during the initialization. Otherwise, one can pass the token to the initialization function.

The first step to start a session is to create an object from the R6 class by calling the $new method.

library(kbtbr)
base_url <- "https://kobo.correlaid.org"
my_session <- KoboClient$new(base_url, kobo_token = "faketoken")
class(my_session)

The power of inheritance

Thanks to the inheritance mechanism, my_session can provide all the features of crul::HttpClient that is the parent R6 class.

For example,

my_session$print()

will show you several properties set in the HTTP client, like the headers, the URL and other properties. The $print() method is not implemented in the KoboClient class, but it is automatically inherited from its parent class.

KoboClient is called a child of crul::HttpClient, the parent, and by the inheritance mechanism can have all of its features (methods and fields) of the parent, but it can also provide more features or specialize some of the parent methods. In our case, for example, some features are added to work effectively with the KoboToolbox API: it stores the API token as private variable, or some method are further specialized like the $get method described in the next section.

get Method

The get method is based on the method $get() of the parent class. Hence, the get method will query the APIs and return an R6 object of class crul::HttpResponse.

vcr::use_cassette("get-assets", {
  assets <- my_session$get(path = "api/v2/assets/", query = list(format = "json"))
})

assets <- my_session$get(path = "api/v2/assets/")

str(assets, max.level = 1)

The use of KoboClient in the Kobo class

The Kobo class uses KoboClient for its HTTP requests. Kobo can create a session by initializing a KoboClient instance itself based on base_url_v2. This is probably the easiest way to initialize a Kobo instance.

kobo <- Kobo$new(base_url)

Alternatively, the user can pass a session - a KoboClient instance associated with an API base URL - via the session_v2 argument of Kobo$new(). The Kobo instance will then use this session for all the communication with the servers.

# passing a KoboClient instance / a session to Kobo
my_session <- KoboClient$new(base_url)
kobo <- Kobo$new(session_v2 = my_session)

If the user specifies base_url_v1 as an argument to Kobo$new() to make use of functionality based on KoBoToolbox API v1, the initializer of Kobo will initialize a second KoboClient instance to communicate with the v1 version of the API. The Kobo instance will then have two sessions, one for v2 and one for v1.

# specifying session for API v2 directly, but letting Kobo initialize the one for API v1
kobo <- Kobo$new(session_v2 = my_session, base_url_v1 = "kc.correlaid.org")
kobo

vcr::use_cassette("get-assets", {
  assets <- kobo$get_assets()
})

assets <- kobo$get_assets()

colnames(assets)

CorrelAid/kbtbr documentation built on Dec. 9, 2022, 8:13 a.m.