send_api_request: Send Database API request

In fishsciences/telemetry: Telemetry helper functions

Send Database API request

Description

This is a flexible function for interacting with any of the numerous /api/* endpoints. It functions by taking key = value pairs required for each of the endpoints and crafting the appropriate JSON payload to submit to the server. All end points require a "unToken" to authorize the request - if this is not provided in the key = value pairs, it will automatically be picked up from the "token" parameter, which defaults to the "unToken" element in the session object.

Usage

send_api_request(
  session,
  ...,
  end_point,
  token = session$unToken,
  curl_handle = session$curl,
  api_baseurl = session$base_url,
  api_url = paste0(api_baseurl, end_point),
  .curlOpts = list(),
  simplify = grepl("list", end_point),
  confirm_delete = FALSE,
  debug_json = FALSE
)

api_upload_data(
  session,
  registration_data,
  other_data_column_names,
  end_point = "/api/data/upload",
  token = session$unToken,
  curl_handle = session$curl,
  api_baseurl = session$base_url,
  api_url = paste0(api_baseurl, end_point),
  .curlOpts = list(),
  debug_json = FALSE
)

Arguments

session	list, and active session object created by start_session()
...	key = value pairs of parameters for each end point request. These vary by endpoint. For a list of the required variables for each end point, use list_endpoint_variable(). See details for more information.
end_point	chracter, the end point for the API
token	character, the unToken for an active session
curl_handle	an existing curl handle for an active session. If not provided, one will be created just for this call.
api_baseurl	character, the base URL for the API
api_url	character, the full URL to the endpoint
.curlOpts	additional arguments passed to RCurl::getURL()
simplify	logical, whether the result should be coerced to a data.frame. Most often useful for the /api/list/* endpoints
confirm_delete	logical, confirm when the endpoint is one of /api/admin/delete/*. Defaults to FALSE, which will require interactive confirmation to proceed. For non-interactive sessions, this must be set to TRUE to complete a delete operation.
debug_json	logial, if TRUE the function returns the JSON payload as a string and does not send the request. This is primarily for debugging API behavior and checking the JSON payloads for correctness. The JSON will include white space for pretty printing, e.g. cat(payload)
registration_data	data.frame containing registration data to upload. Must have columns named "unAntName", "unTagName", "regDataTime"
other_data_column_names	character vector, the names of other columns from the registration_data to include in the "data" slot of the data payload. Will be marshalled to JSON before the upload.

Details

There are some particularities around how the database expects some elements to be created. See the vignette "Telemetry API Administration" for details.

For /api/create/network and /api/create/batch, the antenna and tag data must first be coerced into the proper format (a nested list) via create_antenna_data() and create_batch_tag_data(), respectively.

Value

json or data.frame result (depending on value of simplify, or if debug_json = TRUE the JSON payload.

Author(s)

Matt Espe

Examples

## Not run: 
send_api_request(my_session,
                createUserInfo = "nothing here",
                unUserName = "Matt",
                createUserPass = "qwerty",
                unToken = my_session$unToken,
                end_point = "/api/admin/create/user")                 


## End(Not run)
## Not run: 
test_df = data.frame(unAntName = "NATO-StanNetwork-1",
                     unTagName = 99999,
                     regDataTime = format(Sys.time(), "%FT%T%z"),
                     temp = 39.0,
                     test2 = 2)
  api_upload_data(my_session, test_df, c("temp"))

## End(Not run)

fishsciences/telemetry documentation built on May 31, 2024, 10:13 a.m.