diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 4bbce75..1b0d65e 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -21,6 +21,7 @@ jobs: group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + DTMAPIR_KEY: ${{ secrets.DTMAPIR_KEY }} permissions: contents: write steps: diff --git a/.gitignore b/.gitignore index 50c8fce..529cd81 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,4 @@ inst/doc .Renviron .Rhistory /.quarto/ -docs \ No newline at end of file +docs diff --git a/DESCRIPTION b/DESCRIPTION index ba8cc9b..b94df85 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: dtmapi Title: Fetching Data from the 'Displacement Tracking Matrix' -Version: 0.1.0 +Version: 0.1.0.9000 Authors@R: c( person("Luong Bang", "Tran", email = "lutran@iom.int", role = c("aut")), person("Assad", "Asil Companioni", email = "aasil@iom.int", role = c("aut", "cre")), diff --git a/NEWS.md b/NEWS.md index f31d9a8..4e13875 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,14 @@ +# dtmapi (development version) +* Stylistic and stylistic-adjacent corrections to documentation. + +* More elaborate explanation on how to set the subscription key, including +options for non-interactive environments and explicitly introducing the concept +of secrets management. + +* Substantial corrections to documentation, including clarification of the environment variable being used (it is `DTM_SUBSCRIPTION_KEY`, not `DTM_API_KEY`). + +* Apparently inconsequential change in API endpoint URL used by `get_all_operations()`: from "https://dtmapi.iom.int/v3/displacement/operation-List" to https://dtmapi.iom.int/v3/displacement/operation-list", but worth implementing to be safe and exact. + # dtmapi 0.1.0 * Version 3 of the DTM API requires the use of a valid subscription key in order @@ -18,4 +29,4 @@ the API. the `dtmapi` package, but it may technically be used by users to conveniently return the currently available subscription key. HOWEVER, beware that the string it returns is plain text and is more easily exposed, e.g. exposed to anyone -visually observing your machine. \ No newline at end of file +visually observing your machine. diff --git a/R/get_all_operations.R b/R/get_all_operations.R index 7e2d5aa..12fc428 100644 --- a/R/get_all_operations.R +++ b/R/get_all_operations.R @@ -13,7 +13,7 @@ get_all_operations <- function() { tryCatch({ - api_url <- "https://dtmapi.iom.int/v3/displacement/operation-List" + api_url <- "https://dtmapi.iom.int/v3/displacement/operation-list" response <- request(api_url) |> diff --git a/R/get_subscription_key.R b/R/get_subscription_key.R index db0fd51..3c31140 100644 --- a/R/get_subscription_key.R +++ b/R/get_subscription_key.R @@ -2,8 +2,8 @@ #' #' The DTM API subscription key is returned, provided that it is available in #' the R session as an environment variable. Users will usually need to set -#' the DTM_SUBSCRIPTION_KEY environment variable through a .Renviron file or -#' by calling `set_subscription_key()`. +#' the DTM_SUBSCRIPTION_KEY environment variable through a .Renviron file (or +#' other means) or by calling `set_subscription_key()`. #' #' On the other hand, if the TESTTHAT environment variable is true, indicating #' that unit tests are being run by the package maintainers, then the diff --git a/R/set_subscription_key.R b/R/set_subscription_key.R index 98e43fc..074a52a 100644 --- a/R/set_subscription_key.R +++ b/R/set_subscription_key.R @@ -1,11 +1,12 @@ #' Set the user's API subscription key in order to make the API calls. #' -#' The API will be stored as an environmental variable named "DTM_API_KEY". +#' The API subscription key will be stored as an environment variable named +#' "DTM_SUBSCRIPTION_KEY". #' @param key #' Either NULL or a string representing the key. NULL is preferable: using it #' will prompt the user to type the subscription key in a graphical user #' interface that masks it. -#' @return Nothing. Creates / overwrites an environmental variable as a side effect. +#' @return Nothing. Creates / overwrites an environment variable as a side effect. #' @export #' @examples #' \dontrun{ diff --git a/README.Rmd b/README.Rmd index c78a167..eafaa34 100644 --- a/README.Rmd +++ b/README.Rmd @@ -52,15 +52,23 @@ the [DTM API Portal](https://dtm-apim-portal.iom.int/signin) and follow the instructions there. The subscription key is secret and should not be exposed. Once it is obtained, -the subscription key should be set for your current R session, assuming that the -`dtmapi` package is installed. To do this, use run the following in R: +the subscription key should be set for your current R session, assuming that the `dtmapi` package is installed. To do this, the environment variable `DTM_SUBSCRIPTION_KEY` needs to be defined. This can be done either interactively or non-interactively. + +The interactive option is to call `set_subscription_key()`, like so: ```{r set_subscription_key_demo, eval = FALSE} dtmapi::set_subscription_key() ``` -At this point, the user will be prompted to input the key (hidden) into a pop-up -field. +At this point, the user will be prompted to input the key (hidden) into a pop-up field. + +Some environments are non-interactive, and so running the above will likely result in an error. In such a case, the subscription key may be set non-interactively, by specifying the `key` parameter, like so: +```{r, eval = FALSE} +# Specifying `key` is required for non-interactive use. +dtmapi::set_subscription_key(key = "mysubscriptionkey") +``` + +However, this option is discouraged and should be avoided as much as possible, because it blatantly exposes the subscription key. The best option would be to engage in good secrets management practices, such as by using a .Renviron file (if applicable). Basic secrets management, and the issue of setting the subscription key in general, is elaborated on in more detail in `vignette("user_guide")`. ## Usage When the subscription key is set, data on internal displacement may be retrieved through any of the following functions: @@ -74,8 +82,7 @@ These all retrieve data from the DTM API and return said data in the form of data frames. Certain parameters have to be specified to any of these, the most important of which are either the `CountryName` or the `OperationName`. For information on the other parameters -and indeed all functions in `dtmapi`, -[see the documentation here.](https://displacement-tracking-matrix.github.io/dtmapi-R/reference/index.html) +and indeed all functions in `dtmapi`, [see the documentation here.](https://displacement-tracking-matrix.github.io/dtmapi-R/reference/index.html) As a representative example of the earlier mentioned functions, see the following use of `get_idp_admin_1_data()`: @@ -117,13 +124,15 @@ head(operations_df) ## User Guide The information given here is further elaborated on in the user guide to -getting started with `dtmapi`, which is available through the panel at -the top of this page. +getting started with `dtmapi`, which is +accessible through `vignette("user_guide")`. ## Source Code -The source code for `dtmapi` is available on [GitHub](https://github.com/Displacement-tracking-Matrix/dtmapi-R). +The source code for `dtmapi` is available on +[GitHub](https://github.com/Displacement-tracking-Matrix/dtmapi-R). Feel free to explore the repository, contribute, or raise any issues you may encounter. ## Contact -For any questions or feedback, please reach out to us at [dtmdataconsolidation@iom.int](mailto:dtmdataconsolidation@iom.int). +For any questions or feedback, please reach out to us at +[dtmdataconsolidation@iom.int](mailto:dtmdataconsolidation@iom.int). diff --git a/README.md b/README.md index 6f5f0b5..ebdb7fd 100644 --- a/README.md +++ b/README.md @@ -53,8 +53,11 @@ the instructions there. The subscription key is secret and should not be exposed. Once it is obtained, the subscription key should be set for your current R session, -assuming that the `dtmapi` package is installed. To do this, use run the -following in R: +assuming that the `dtmapi` package is installed. To do this, the +environment variable `DTM_SUBSCRIPTION_KEY` needs to be defined. This +can be done either interactively or non-interactively. + +The interactive option is to call `set_subscription_key()`, like so: ``` r dtmapi::set_subscription_key() @@ -63,6 +66,22 @@ dtmapi::set_subscription_key() At this point, the user will be prompted to input the key (hidden) into a pop-up field. +Some environments are non-interactive, and so running the above will +likely result in an error. In such a case, the subscription key may be +set non-interactively, by specifying the `key` parameter, like so: + +``` r +# Specifying `key` is required for non-interactive use. +dtmapi::set_subscription_key(key = "mysubscriptionkey") +``` + +However, this option is discouraged and should be avoided as much as +possible, because it blatantly exposes the subscription key. The best +option would be to engage in good secrets management practices, such as +by using a .Renviron file (if applicable). Basic secrets management, and +the issue of setting the subscription key in general, is elaborated on +in more detail in `vignette("user_guide")`. + ## Usage When the subscription key is set, data on internal displacement may be @@ -80,8 +99,6 @@ important of which are either the `CountryName` or the `OperationName`. For information on the other parameters and indeed all functions in `dtmapi`, [see the documentation here.](https://displacement-tracking-matrix.github.io/dtmapi-R/reference/index.html) -`dtmapi`, [see the documentation -here.](https://displacement-tracking-matrix.github.io/dtmapi-R/reference/index.html) As a representative example of the earlier mentioned functions, see the following use of `get_idp_admin_1_data()`: @@ -98,12 +115,12 @@ idp_admin1_df <- get_idp_admin1_data(CountryName = "Sudan", # Display the first few rows of the data frame head(idp_admin1_df) #> id operation admin0Name admin0Pcode admin1Name admin1Pcode -#> 1 4277072 Darfur conflict Sudan SDN Blue Nile SD08 -#> 2 4277073 Darfur conflict Sudan SDN Blue Nile SD08 -#> 3 4277074 Darfur conflict Sudan SDN Blue Nile SD08 -#> 4 4277075 Darfur conflict Sudan SDN Blue Nile SD08 -#> 5 4255941 Armed Clashes in Sudan Sudan SDN Blue Nile SD08 -#> 6 4255942 Armed Clashes in Sudan Sudan SDN Blue Nile SD08 +#> 1 4743857 Darfur conflict Sudan SDN Blue Nile SD08 +#> 2 4743858 Darfur conflict Sudan SDN Blue Nile SD08 +#> 3 4743859 Darfur conflict Sudan SDN Blue Nile SD08 +#> 4 4743860 Darfur conflict Sudan SDN Blue Nile SD08 +#> 5 4722729 Armed Clashes in Sudan Sudan SDN Blue Nile SD08 +#> 6 4722730 Armed Clashes in Sudan Sudan SDN Blue Nile SD08 #> numPresentIdpInd reportingDate yearReportingDate monthReportingDate #> 1 81693 2021-03-30T00:00:00 2021 3 #> 2 130958 2021-12-31T00:00:00 2021 12 @@ -174,8 +191,8 @@ head(operations_df) ## User Guide The information given here is further elaborated on in the user guide to -getting started with `dtmapi`, which is available through the panel at -the top of this page. +getting started with `dtmapi`, which is accessible through +`vignette("user_guide")`. ## Source Code diff --git a/_pkgdown.yml b/_pkgdown.yml index 389cb6f..c2d7902 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -18,4 +18,4 @@ navbar: href: reference/index.html development: - mode: auto + mode: release diff --git a/man/get_subscription_key.Rd b/man/get_subscription_key.Rd index a68c2b3..3c0cbc7 100644 --- a/man/get_subscription_key.Rd +++ b/man/get_subscription_key.Rd @@ -12,8 +12,8 @@ A string representing a given subscription key for the DTM API. \description{ The DTM API subscription key is returned, provided that it is available in the R session as an environment variable. Users will usually need to set -the DTM_SUBSCRIPTION_KEY environment variable through a .Renviron file or -by calling \code{set_subscription_key()}. +the DTM_SUBSCRIPTION_KEY environment variable through a .Renviron file (or +other means) or by calling \code{set_subscription_key()}. } \details{ On the other hand, if the TESTTHAT environment variable is true, indicating diff --git a/man/set_subscription_key.Rd b/man/set_subscription_key.Rd index ed8a466..b685813 100644 --- a/man/set_subscription_key.Rd +++ b/man/set_subscription_key.Rd @@ -21,10 +21,11 @@ will prompt the user to type the subscription key in a graphical user interface that masks it.} } \value{ -Nothing. Creates / overwrites an environmental variable as a side effect. +Nothing. Creates / overwrites an environment variable as a side effect. } \description{ -The API will be stored as an environmental variable named "DTM_API_KEY". +The API subscription key will be stored as an environment variable named +"DTM_SUBSCRIPTION_KEY". } \examples{ \dontrun{ diff --git a/vignettes/user_guide.Rmd b/vignettes/user_guide.Rmd index 214af3b..a84e856 100644 --- a/vignettes/user_guide.Rmd +++ b/vignettes/user_guide.Rmd @@ -52,33 +52,67 @@ library(dtmapi) ## Setting the Subscription Key After creating a subscription key on https://dtm-apim-portal.iom.int, that key -needs to be given to R. There are two main ways to do this. +needs to be given to R. To do this, the `DTM_SUBSCRIPTION_KEY` environment variable needs to be defined as the subscription key. There are three main ways to do this, as described below. -1. By calling `set_subscription_key()` and then typing in the key. +### 1. Using `set_subscription_key()`: interactive, safe option -The user will be prompted to input the key into a pop-up field. +By calling `set_subscription_key()`, after which the user is prompted to input the key into a pop-up field. ```{r set_subscription_key_demo, eval = FALSE} set_subscription_key() ``` -2. By setting up the environment variable directly. +Note that if the environment is not interactive, it is likely for the user to receive an error message instead, such as in the case of using Google Colab. In such cases see the other options described further below. -If one would like to avoid re-inputting the subscription key for each R session, -an alternative approach is to create the environment variable -`DTM_SUBSCRIPTION_KEY`, with the subscription key as its value. Ideally, this -should be (a) done in a *.Renviron* file, and (b) through the use of *R projects* -or other means of organising files (e.g. if one is using VS Code: *workspaces*). +### 2. Using `set_subscription_key()`: the non-interactive, discouraged option -One quick way to get started is by calling the following line of code, if one is -using an R project or equivalent: +If the interactive option above fails for the user, such that there is an error instead of a pop-up, the user may rely on passing their key directly into `set_subscription_key()` by naming the `key` parameter. +```{r, eval = FALSE} +# Specifying `key` is required for non-interactive use. +set_subscription_key(key = "mysubscriptionkey") +``` + +This is basically using `set_subscription_key()` as a wrapper for setting up the environment variable `DTM_SUBSCRIPTION_KEY` using base R's `Sys.setenv()`, as shown below: +```{r, eval = FALSE} +Sys.setenv("DTM_SUBSCRIPTION_KEY" = "mysubscriptionkey") +``` + +Please note that by doing this in, say, a Google Colab script, .R script, or Jupyter notebook, you are leaving a secret (your subscription key) exposed and available for anyone to read with ease. This is why this option is not recommended, but it will allow you to get things working faster if you are not familiar with managing secrets in a non-interactive context. + +### 3. Setting up the environment variable with good secrets management + +If one would like to avoid re-inputting the subscription key for each R session, and they would like to set the subscription in a way that is both non-interactive and safer, then this becomes a matter of knowing the right secrets management practices depending on where R is being used (e.g. whether that is in a local desktop, a cloud-based programming environment, a server, etc.). + +In the vast majority of cases, the approach is the fundamentally the same: anything that directly stores your key should be **separate from the rest of your code**, and your code accesses the key through an **environment variable**. That is the main principle to the most common way to manage your secrets. What differs by where R is being used is _how_ this principle is applied. Below, the user guide will mostly focus on how this is handled when using a code editor such as VSCode, RStudio, or Positron, as this is the most common case. If these do not reflect your circumstance or use-case, then researching how to manage secrets generally for that circumstance should suffice, as the only thing specific about doing so for the `dtmapi` package is just the name of the environment variable, `DTM_SUBSCRIPTION_KEY`. + +**Using a code editor such as VSCode or RStudio on a desktop:** + +Use a `.Renviron` file to set the key. You can create it from scratch, and its contents should look something like this: +``` +DTM_SUBSCRIPTION_KEY = "mysubscriptionkey" +Some_Other_Env_Var = "something else if desired" +``` +For this to work robustly, your `.Renviron` should be in the same *working directory* that you would like to use for your R sessions (i.e. it should be in the same location or folder that you would like your R sessions to use as a default). You can see which folder that currently is by running: + +```{r, eval = FALSE} +getwd() +``` + +This is important to know because, if your R session can start in the same working directory that the `.Renviron` file is located in, then the environment variables specified there are automatically loaded for your R session! + +Usually, your choice of working directory is best managed by creating an _R project_ or equivalent (such as _VS Code workspaces_). That is to say, one should have a dedicated folder for their specific project, the R sessions they run should make that folder the working directory, and `.Renviron` should be placed there as well. For more information, depending on whether you use RStudio, VSCode, or Positron, see: [Using RStudio Projects](https://support.posit.co/hc/en-us/articles/200526207-Using-RStudio-Projects), [What is a VS Code Workspace?](https://code.visualstudio.com/docs/editing/workspaces), or [Launching Positron in a workspace](https://positron.posit.co/migrate-rstudio-rproj.html#launching-positron-in-a-workspace). + +If one is unfamiliar and struggling to create the .Renviron file, then one quick way to proceed with editing the `.Renviron` file or placing it in their project directory (if they have one) is by calling the following line of code (make sure the `usethis` package is installed): ```{r r_environ_demo_project, eval = FALSE} usethis::edit_r_environ("project") ``` -Or, if one is not using an R project or equivalent: + +Or, if one is not using an R project or equivalent, then this is an option as well, though using the general user directory is not recommended as it is likely to get lost: ```{r r_environ_demo_user, eval = FALSE} usethis::edit_r_environ("user") ``` +Remember: NEVER SHARE THE `.RENVIRON` FILE. + ## Get All Countries The `get_all_countries()` function retrieves a list of all countries from the DTM API.