Introduce preliminary updates for version 3 of the API

.github/workflows/R-CMD-check.yaml

@@ -0,0 +1,52 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+name: R-CMD-check.yaml
+
+permissions: read-all
+
+jobs:
+  R-CMD-check:
+    runs-on: ${{ matrix.config.os }}
+
+    name: ${{ matrix.config.os }} (${{ matrix.config.r }})
+
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - {os: macos-latest,   r: 'release'}
+          - {os: windows-latest, r: 'release'}
+          - {os: ubuntu-latest,   r: 'devel', http-user-agent: 'release'}
+          - {os: ubuntu-latest,   r: 'release'}
+          - {os: ubuntu-latest,   r: 'oldrel-1'}
+
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      R_KEEP_PKG_SOURCE: yes
+      DTMAPIR_KEY: ${{ secrets.DTMAPIR_KEY}}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: ${{ matrix.config.r }}
+          http-user-agent: ${{ matrix.config.http-user-agent }}
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+
+      - uses: r-lib/actions/check-r-package@v2
+        with:
+          upload-snapshots: true
+          build_args: 'c("--no-manual","--compact-vignettes=gs+qpdf")'

.gitignore

@@ -2,3 +2,5 @@
 inst/doc
 /doc/
 /Meta/
+.Renviron
+.Rhistory

DESCRIPTION

@@ -1,8 +1,10 @@
 Package: dtmapi
 Title: Fetching Data from the 'Displacement Tracking Matrix'
-Version: 0.0.3
-Authors@R: 
-  person("Luong Bang", "Tran", email = "lutran@iom.int", role = c("aut", "cre"))
+Version: 0.1.0
+Authors@R: c( 
+  person("Luong Bang", "Tran", email = "lutran@iom.int", role = c("aut", "cre")),
+  person("Assad", "Asil Companioni", email = "aasil@iom.int", role = c("aut"))
+  )
 Description: Allows humanitarian community, academia, media, government, and non-governmental organizations to utilize the data collected by the 'Displacement Tracking Matrix' (<https://dtm.iom.int>), a unit in the International Organization for Migration. This also provides non-sensitive Internally Displaced Person figures, aggregated at the country, Admin 1 (states, provinces, or equivalent), and Admin 2 (smaller administrative areas) levels.
 URL: https://github.com/Displacement-Tracking-Matrix/dtmapi-R, https://displacement-tracking-matrix.github.io/dtmapi-R/
 License: MIT + file LICENSE
@@ -11,10 +13,10 @@ Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
 Imports:
     httr2,
-    jsonlite,
-    magrittr
+    testthat (>= 3.1.0),
+    askpass
 Suggests: 
     knitr,
     rmarkdown,
-    testthat (>= 3.1.0)
+    withr
 VignetteBuilder: knitr

NAMESPACE

@@ -5,10 +5,15 @@ export(get_all_operations)
 export(get_idp_admin0_data)
 export(get_idp_admin1_data)
 export(get_idp_admin2_data)
+export(get_subscription_key)
+export(set_subscription_key)
+importFrom(askpass,askpass)
+importFrom(httr2,req_headers_redacted)
 importFrom(httr2,req_perform)
 importFrom(httr2,req_url_query)
 importFrom(httr2,request)
+importFrom(httr2,resp_body_json)
 importFrom(httr2,resp_body_string)
 importFrom(httr2,resp_status)
-importFrom(jsonlite,fromJSON)
-importFrom(magrittr,"%>%")
+importFrom(httr2,secret_decrypt)
+importFrom(testthat,is_testing)

R/get_all_countries.R

@@ -1,39 +1,36 @@
-library(httr2)
-library(jsonlite)
-library(magrittr)  # For the `%>%` operator
-
 #' Fetch All Countries
 #'
 #' Retrieve all countries for which DTM data is publicly available through the API.
 #'
 #' @return A data frame containing the list of all countries.
 #' @export
 #' @examples
-#' # Fetch all countries
+#' \dontrun{
 #' countries_df <- get_all_countries()
 #' head(countries_df)
-#' @importFrom httr2 request req_perform resp_status resp_body_string
-#' @importFrom magrittr %>%
-#' @importFrom jsonlite fromJSON
+#' }
+#' @importFrom httr2 request req_perform resp_status resp_body_json req_headers_redacted
+
 get_all_countries <- function() {
 
   tryCatch({
-    # Retrieve the API URL
-    api_url <- "https://dtmapi.iom.int/api/Common/GetAllCountryList"
+    api_url <- "https://dtm-apim.iom.int/v3/CountryList"
 
-    # Send GET request to the API using httr2
-    response <- request(api_url) %>% req_perform()
+    response <- 
+      request(api_url) |>
+      req_headers_redacted("Cache-Control" = "no-cache",
+                           "Ocp-Apim-Subscription-Key" = get_subscription_key()
+                          ) |>
+      req_perform()
 
     # Check if the request was successful
     if (resp_status(response) != 200) {
       stop("Failed to fetch data. Status code: ", resp_status(response))
     }
 
-    # Parse the JSON content and extract the result as a data frame
-    data <- resp_body_string(response)
-    df <- fromJSON(data, flatten = TRUE)$result
+    json_data <- resp_body_json(response, simplifyVector = TRUE)
+    df <- as.data.frame(json_data$result) # as.data.frame() for consistency's sake.
 
-    # Return the data frame
     return(df)
 
   }, error = function(e) {

R/get_all_operations.R

@@ -1,37 +1,37 @@
-library(httr2)
-library(jsonlite)
-library(magrittr)  # For the `%>%` operator
-
 #' Fetch All Operations
 #'
 #' Retrieve all operations for which DTM data is publicly available through the API.
 #'
 #' @return A data frame containing the list of all operations.
 #' @export
 #' @examples
+#' \dontrun{
 #' # Fetch all operations
 #' operations_df <- get_all_operations()
 #' head(operations_df)
-#' @importFrom httr2 request req_perform resp_status resp_body_string
-#' @importFrom magrittr %>%
-#' @importFrom jsonlite fromJSON
+#' }
+#' @importFrom httr2 request req_perform resp_status resp_body_json req_headers_redacted
+
 get_all_operations <- function() {
 
   tryCatch({
-    # Load configuration
-    api_url <- "https://dtmapi.iom.int/api/Common/GetAllOperationList"
+    api_url <- "https://dtm-apim.iom.int/v3/OperationList"
 
-    # Send GET request to the API using httr2
-    response <- request(api_url) %>% req_perform()
+    response <- 
+      request(api_url) |>
+      req_headers_redacted("Cache-Control" = "no-cache",
+                           "Ocp-Apim-Subscription-Key" = get_subscription_key()
+                          ) |>
+      req_perform()
 
     # Check if the request was successful
     if (resp_status(response) != 200) {
       stop("Failed to fetch data. Status code: ", resp_status(response))
     }
 
     # Parse the JSON content and extract the result as a data frame
-    data <- resp_body_string(response)
-    df <- fromJSON(data, flatten = TRUE)$result
+    json_data <- resp_body_json(response, simplifyVector = TRUE)
+    df <- as.data.frame(json_data$result) # as.data.frame() for consistency's sake.
 
     # Return the data frame
     return(df)

R/get_idp_admin0_data.R

@@ -1,7 +1,3 @@
-library(httr2)
-library(jsonlite)
-library(magrittr)  # For the `%>%` operator
-
 #' Fetch IDP Admin0 Data
 #'
 #' Retrieve IDP data at Admin 0 level based on specified parameters.
@@ -17,12 +13,15 @@ library(magrittr)  # For the `%>%` operator
 #' @return A data frame containing the IDP Admin0 data matching the specified criteria.
 #' @export
 #' @examples
+#' \dontrun{
 #' # Fetch IDP data at Admin Level 0
-#' idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10)
+#' idp_admin0_df <- get_idp_admin0_data(CountryName = "Ethiopia",
+#'                                      FromRoundNumber = 1, 
+#'                                      ToRoundNumber = 10)
 #' head(idp_admin0_df)
-#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string
-#' @importFrom magrittr %>%
-#' @importFrom jsonlite fromJSON
+#' }
+#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json req_headers_redacted
+
 get_idp_admin0_data <- function(
     Operation = NULL,
     CountryName = NULL,
@@ -32,11 +31,9 @@ get_idp_admin0_data <- function(
     FromRoundNumber = 0,
     ToRoundNumber = 0
 ) {
-  # Retrieve the API URL
-  api_url <- "https://dtmapi.iom.int/api/idpAdmin0Data/GetAdmin0Datav2"
+  api_url <- "https://dtm-apim.iom.int/v3/IdpAdmin0Data"
 
-  # Set up query parameters
-  params <- list(
+  query_params <- list(
     Operation = Operation,
     CountryName = CountryName,
     Admin0Pcode = Admin0Pcode,
@@ -47,23 +44,22 @@ get_idp_admin0_data <- function(
   )
 
   tryCatch({
-    # Send GET request to the API with parameters using httr2
-    response <- request(api_url) %>%
-      req_url_query(!!!params) %>%
+    response <- 
+      request(api_url) |>
+      req_headers_redacted("Cache-Control" = "no-cache",
+                           "Ocp-Apim-Subscription-Key" = get_subscription_key()
+                          ) |>
+      req_url_query(!!!query_params) |>
       req_perform()
 
-    # Check if the request was successful
     if (resp_status(response) != 200) {
       stop("Failed to fetch data. Status code: ", resp_status(response))
     }
 
-    # Parse the JSON content
-    data <- resp_body_string(response, encoding = "UTF-8")
-    json_data <- fromJSON(data, flatten = TRUE)
+    # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe.
+    json_data <- resp_body_json(response, simplifyVector = TRUE)
 
-    # Check if the request was successful and extract the result
     if (json_data$isSuccess) {
-      # Return the result as a data frame
       return(as.data.frame(json_data$result))
     } else {
       # Handle API-specific errors

R/get_idp_admin1_data.R

@@ -1,7 +1,3 @@
-library(httr2)
-library(jsonlite)
-library(magrittr)  # For the `%>%` operator
-
 #' Fetch IDP Admin1 Data
 #'
 #' Retrieve IDP data at Admin 1 level based on specified parameters.
@@ -19,12 +15,13 @@ library(magrittr)  # For the `%>%` operator
 #' @return A data frame containing the IDP Admin1 data matching the specified criteria.
 #' @export
 #' @examples
+#' \dontrun{
 #' # Fetch IDP data at Admin Level 1
-#' idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile")
+#' idp_admin1_df <- get_idp_admin1_data(CountryName = "Sudan", Admin1Name = "Blue Nile")
 #' head(idp_admin1_df)
-#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string
-#' @importFrom magrittr %>%
-#' @importFrom jsonlite fromJSON
+#' }
+#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json req_headers_redacted
+
 get_idp_admin1_data <- function(
     Operation = NULL,
     CountryName = NULL,
@@ -36,11 +33,9 @@ get_idp_admin1_data <- function(
     FromRoundNumber = 0,
     ToRoundNumber = 0
 ) {
-  # Retrieve the API URL
-  api_url <- "https://dtmapi.iom.int/api/idpAdmin1Data/GetAdmin1Datav2"
+  api_url <- "https://dtm-apim.iom.int/v3/IdpAdmin1Data"
 
-  # Set up query parameters
-  params <- list(
+  query_params <- list(
     Operation = Operation,
     CountryName = CountryName,
     Admin0Pcode = Admin0Pcode,
@@ -53,23 +48,22 @@ get_idp_admin1_data <- function(
   )
 
   tryCatch({
-    # Send GET request to the API with parameters using httr2
-    response <- request(api_url) %>%
-      req_url_query(!!!params) %>%
+    response <- 
+      request(api_url) |>
+      req_headers_redacted("Cache-Control" = "no-cache",
+                           "Ocp-Apim-Subscription-Key" = get_subscription_key()
+                          ) |>
+      req_url_query(!!!query_params) |>
       req_perform()
 
-    # Check if the request was successful
     if (resp_status(response) != 200) {
       stop("Failed to fetch data. Status code: ", resp_status(response))
     }
 
-    # Parse the JSON content
-    data <- resp_body_string(response, encoding = "UTF-8")
-    json_data <- fromJSON(data, flatten = TRUE)
+    # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe.
+    json_data <- resp_body_json(response, simplifyVector = TRUE)
 
-    # Check if the request was successful and extract the result
     if (json_data$isSuccess) {
-      # Return the result as a data frame
       return(as.data.frame(json_data$result))
     } else {
       # Handle API-specific errors