Advanced: The KoboClient class
2022-02-14
Source:vignettes/koboclient-class.Rmd
koboclient-class.Rmd
## NULL
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)
#> [1] "KoboClient" "HttpClient" "R6"
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()
#> <crul connection>
#> url: https://kobo.correlaid.org
#> curl options:
#> proxies:
#> auth:
#> headers:
#> Authorization: Token faketoken
#> Accept: application/json
#> progress: FALSE
#> hooks:
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
.
assets <- my_session$get(path = "api/v2/assets/")
str(assets, max.level = 1)
#> Classes 'HttpResponse', 'R6' <HttpResponse>
#> Public:
#> clone: function (deep = FALSE)
#> content: 7b 22 63 6f 75 6e 74 22 3a 36 35 2c 22 6e 65 78 74 22 3a ...
#> handle: NULL
#> initialize: function (method, url, opts, handle, status_code, request_headers,
#> method: get
#> modified: NA
#> opts: NULL
#> parse: function (encoding = NULL, ...)
#> print: function (x, ...)
#> raise_for_ct: function (type, charset = NULL, behavior = "stop")
#> raise_for_ct_html: function (charset = NULL, behavior = "stop")
#> raise_for_ct_json: function (charset = NULL, behavior = "stop")
#> raise_for_ct_xml: function (charset = NULL, behavior = "stop")
#> raise_for_status: function ()
#> request: RequestSignature, R6
#> request_headers: list
#> response_headers: list
#> response_headers_all: list
#> status_code: 200
#> status_http: function (verbose = FALSE)
#> success: function ()
#> times: NULL
#> url: https://kobo.correlaid.org/api/v2/assets/?format=json
#> Private:
#> raise_for_ct_factory: function (type)
#> raise_for_ct_user: function ()
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
#> <Kobo>
#> Public:
#> clone: function (deep = FALSE)
#> clone_asset: function (clone_from, new_name, asset_type)
#> create_asset: function (name, asset_type, description = "", sector = list(label = "",
#> deploy_asset: function (uid)
#> get: function (path, query = list(), version = "v2", format = "json",
#> get_asset: function (id)
#> get_assets: function ()
#> get_submissions: function (id)
#> get_surveys: function (show_all_cols = FALSE)
#> import_xls_form: function (name, file_path)
#> initialize: function (base_url_v2 = NULL, base_url_v1 = NULL, kobo_token = Sys.getenv("KBTBR_TOKEN"),
#> post: function (path, body, version = "v2")
#> session_v1: KoboClient, HttpClient, R6
#> session_v2: KoboClient, HttpClient, R6
assets <- kobo$get_assets()
colnames(assets)
#> [1] "url" "date_modified"
#> [3] "date_created" "owner"
#> [5] "summary" "owner__username"
#> [7] "parent" "uid"
#> [9] "tag_string" "settings"
#> [11] "kind" "name"
#> [13] "asset_type" "version_id"
#> [15] "has_deployment" "deployed_version_id"
#> [17] "deployment__identifier" "deployment__active"
#> [19] "deployment__submission_count" "permissions"
#> [21] "downloads" "data"