get orders function modification

finddx · Dec 7, 2023 · 42c9229 · 42c9229
1 parent 642e6ba
commit 42c9229
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 70 deletions.
diff --git a/R/get_orders.R b/R/get_orders.R
@@ -1,51 +1,68 @@
 # WARNING - Generated by {fusen} from dev/OpenSpecimenAPI.Rmd: do not edit by hand
 
-#' Get OpenSpecimen Orders
+#' Get Orders
 #'
-#' This function retrieves a list of orders from the OpenSpecimen API using the provided authentication response and optional query parameters.   https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/259457077/Retrieve+list+of+Orders
-
-#'
-#' @param auth_response The authentication response obtained from `auth_os`.
-#' @param include_stats Logical, whether to include statistics (default is TRUE).
-#' @param start_at Integer, the starting position for pagination (optional).
-#' @param max_results Integer, the maximum number of results to retrieve (optional).
+#' Use this function to retrieve distribution orders in the OpenSpecimen application.
+#' The function sends an HTTP GET request to the OpenSpecimen server to fetch details of distribution orders.
 #'
-#' @return A data frame containing the parsed order data.
+#' @param auth_response Authentication response object obtained from the OpenSpecimen API.
+#' @param include_stats If TRUE, includes statistics in the response (optional, default is TRUE).
+#' @param start_at Starting row of the result (optional).
+#' @param max_results Maximum number of records to fetch (optional).
 #'
-#' @importFrom httr GET add_headers status_code
-#' @note This function allows you to retrieve orders from OpenSpecimen and parse the response data into a data frame.   https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/259457077/Retrieve+list+of+Orders
-
+#' @return A data frame containing the details of distribution orders, or NULL if an error occurs.
 #'
-#' @export
 #' @examples
+#' \dontrun{
+#' # Example usage:
+#' auth_response <- authenticate_user(username = "your_username", password = "your_password")
+#' orders <- get_orders(auth_response)
+#' }
+#'
 #' #get_orders()
-get_orders <- function(auth_response, 
-                       include_stats = TRUE, 
-                       start_at = NULL, 
-                       max_results = NULL) {
-  # Create the request object
-  auth_token <- auth_response$auth_response$token
-  url <- auth_response$url
-  query_request <- list(includeStats = include_stats, 
-                        startAt = start_at,
-                        maxResults = max_results)
+#' @seealso \code{\link{auth_os}}, \code{\link{parse_os_response}}, \code{\link{parse_os_order_data}}
+#'
+#' @export
+get_orders <- function(auth_response, include_stats = TRUE, start_at = NULL, max_results = NULL) {
+
+  # URL to get distribution orders
+  # For more details, refer to: https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1115667/Get+Distribution+Orders
+  url <- paste0(auth_response$url, "/distribution-orders")
 
   # Specify the content type as JSON in the header
-  headers <- add_headers(
+  headers <- httr::add_headers(
     "Content-Type" = "application/json",
-    "X-OS-API-TOKEN" = auth_token
+    "X-OS-API-TOKEN" = auth_response$auth_response$token
   )
 
-  # Make the GET request for the orders
-  response <- GET(
-    url = paste0(url,"/distribution-orders"),
-    query = query_request,
-    config = headers
+  # Construct query parameters based on provided arguments
+  query_params <- list(
+    includeStats = include_stats,
+    startAt = start_at,
+    maxResults = max_results
   )
 
+  # Remove NULL parameters
+  query_params <- query_params[!sapply(query_params, is.null)]
+
+  # Append query parameters to the URL
+  if (length(query_params) > 0) {
+    url <- httr::modify_url(url, query = query_params)
+  }
 
-  parse_os_response(response, parse_data_function = "parse_os_order_data")
+  # Make the GET request for the orders
+  response <- httr::GET(url = url, config = headers)
 
+  # Parse the response and return the results
+  results <- parse_os_response(response, parse_data_function = "parse_os_order_data")
 
+  # If inherits data.frame, return results, else return NULL
+  if (inherits(results, "data.frame")) {
+    return(results)
+  } else {
+    return(NULL)
+  }
 }
 
+
+
diff --git a/dev/OpenSpecimenAPI.Rmd b/dev/OpenSpecimenAPI.Rmd
@@ -565,53 +565,71 @@ test_that("parse_os_order_data works", {
 # get_orders
 
 ```{r function-get_orders}
-#' Get OpenSpecimen Orders
+#' Get Orders
 #'
-#' This function retrieves a list of orders from the OpenSpecimen API using the provided authentication response and optional query parameters.   https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/259457077/Retrieve+list+of+Orders
-
+#' Use this function to retrieve distribution orders in the OpenSpecimen application.
+#' The function sends an HTTP GET request to the OpenSpecimen server to fetch details of distribution orders.
 #'
-#' @param auth_response The authentication response obtained from `auth_os`.
-#' @param include_stats Logical, whether to include statistics (default is TRUE).
-#' @param start_at Integer, the starting position for pagination (optional).
-#' @param max_results Integer, the maximum number of results to retrieve (optional).
+#' @param auth_response Authentication response object obtained from the OpenSpecimen API.
+#' @param include_stats If TRUE, includes statistics in the response (optional, default is TRUE).
+#' @param start_at Starting row of the result (optional).
+#' @param max_results Maximum number of records to fetch (optional).
 #'
-#' @return A data frame containing the parsed order data.
+#' @return A data frame containing the details of distribution orders, or NULL if an error occurs.
 #'
-#' @importFrom httr GET add_headers status_code
-#' @note This function allows you to retrieve orders from OpenSpecimen and parse the response data into a data frame.   https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/259457077/Retrieve+list+of+Orders
-
+#' @examples
+#' \dontrun{
+#' # Example usage:
+#' auth_response <- authenticate_user(username = "your_username", password = "your_password")
+#' orders <- get_orders(auth_response)
+#' }
+#'
+#' @seealso \code{\link{auth_os}}, \code{\link{parse_os_response}}, \code{\link{parse_os_order_data}}
 #'
 #' @export
-get_orders <- function(auth_response, 
-                       include_stats = TRUE, 
-                       start_at = NULL, 
-                       max_results = NULL) {
-  # Create the request object
-  auth_token <- auth_response$auth_response$token
-  url <- auth_response$url
-  query_request <- list(includeStats = include_stats, 
-                        startAt = start_at,
-                        maxResults = max_results)
+get_orders <- function(auth_response, include_stats = TRUE, start_at = NULL, max_results = NULL) {
+  
+  # URL to get distribution orders
+  # For more details, refer to: https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1115667/Get+Distribution+Orders
+  url <- paste0(auth_response$url, "/distribution-orders")
   
   # Specify the content type as JSON in the header
-  headers <- add_headers(
+  headers <- httr::add_headers(
     "Content-Type" = "application/json",
-    "X-OS-API-TOKEN" = auth_token
+    "X-OS-API-TOKEN" = auth_response$auth_response$token
   )
   
-  # Make the GET request for the orders
-  response <- GET(
-    url = paste0(url,"/distribution-orders"),
-    query = query_request,
-    config = headers
+  # Construct query parameters based on provided arguments
+  query_params <- list(
+    includeStats = include_stats,
+    startAt = start_at,
+    maxResults = max_results
   )
   
+  # Remove NULL parameters
+  query_params <- query_params[!sapply(query_params, is.null)]
   
-  parse_os_response(response, parse_data_function = "parse_os_order_data")
+  # Append query parameters to the URL
+  if (length(query_params) > 0) {
+    url <- httr::modify_url(url, query = query_params)
+  }
   
+  # Make the GET request for the orders
+  response <- httr::GET(url = url, config = headers)
   
+  # Parse the response and return the results
+  results <- parse_os_response(response, parse_data_function = "parse_os_order_data")
+  
+  # If inherits data.frame, return results, else return NULL
+  if (inherits(results, "data.frame")) {
+    return(results)
+  } else {
+    return(NULL)
+  }
 }
 
+
+
 ```
 
 ```{r example-get_orders}

diff --git a/man/get_orders.Rd b/man/get_orders.Rd