Low level functions to initialize an API call

Users should not need to call these functions directly. They are called internally by the api_get, api_post, api_patch, and api_delete family of functions.

Usage

api_init(api_name, endpoint)

api_pagination(req, pages = list())

api_filters(req, filters = list(), decorate_filters = TRUE)

api_parameters(req, parameters = list())

api_includes(req, includes = NULL, valid_includes = NULL)

api_appends(req, appends = NULL, valid_appends = NULL)

api_body(req, body)

api_body_multi(req, body, nm = "body")

api_body_df(req, body)

api_body_multipart_file(req, file_path, aux_data)

Arguments

api_name: the name of the API to call
endpoint: the API endpoint to make the request to
req: a request object created by api_init()
pages: a named list of page arguments, common choices are size, number, and omit
filters: a named list of filters (i.e. key-value pairs) to apply to the request
decorate_filters: Logical, default TRUE, adds the word filter and square brackets to the query string. For Plumber APIs set to FALSE.
parameters: a named list of query parameters to pass to the request, see the lookups endpoint for an example
includes: a character vector of relationships to include in the response these are data from other tables or resources
valid_includes: a character vector of valid includes to check against
appends: a character vector of dynamically created values to append to the response
valid_appends: a character vector of valid appends to check against
body: a list or tibble that will be passed as the body of the request to the API
nm: the name of the object to be passed as the body of the request
file_path: The file path to the file to be uploaded.
aux_data: A named list containing the Name-data pairs used to send data in the body. Each element in the list will become a separate part of the multipart form.

Value

a httr2 request object

An updated httr2 request object with the multipart body attached.

Details

The init function sets the base URL and the endpoint for the request. It also sets the Accept and Content-Type headers to application/json. Last, it sets the Authorization header to the stored token if one exists or prompts the user (in an interactive session) to provide credentials.

Pagination is a technique used to limit the amount of data in a front end application. This function allows users to add page related queries to an API request. The allowable values are always the same: size, number, and omit. The size argument is the number of records to return, the number argument is the page number, and the omit argument is the number of records to skip. The values provided in the list should be integerish, whole numbers and only ever provide a single value for each named element of the list.

Filters can be used to limit or exclude the values returned from an API endpoint. The basic inputs are a request, as created by api_init() and a named list of filters. The Swagger documentation describes the available filters for each endpoint. All filters look like filter[column]=value. This function will help users with formatting and save a little typing. Filters also have some special features:

Filters also have special operators:

'!' If a vector starts with ! then values will be omitted, for example filter column=!1
'~' If list starts with ~ then values will be compared partially, for example filter column=~1 will match 1, 11, 12, ..., 21, etc.

When combining '!' and '~' the '!' must always come first.

Add parameters to a request. This function is used to add additional query parameters to an API request. The Swagger documentation provides schema definitions that users can search to find the available parameters for a specific endpoint (bottom of the page).

Includes adds other data to the response. For example, if you want to include the species and units tables in the response, you would use api_includes(req, c("species", "units")). The response would include the species and units information in the json, but when parsed a list_col for each includes is the result.

The Swagger documentation provides schema definitions that users can search to find the available includes for a specific endpoint (bottom of the page).

Appends adds other data to the response. That is, the response will include the appended data as new columns in the response. For example, if you want to append the polygons for a project to the project description you would use api_appends(req, c("project.polygon")).

The api_body_multipart_file function builds a multipart HTTP request body containing a file and other necessary auxiliary data, and attaches it to an httr2 request object. It's designed for APIs that require both a file upload and additional data. An example of this would be the geography endpoint of the counts data where a geojson file is required to upload spatial data for gmus and subunits.

Examples

if (FALSE) { # \dontrun{
# The package author would have added this line to make the counts api
# available to the user
spdgt.auth::add_api("counts", "https://api.mywebsite.com")

spdgt.auth:::api_init("counts", "me") |>
  api_perform(dry_run = TRUE)
} # }
if (FALSE) { # \dontrun{
# Apply page size and number restrictions and add a novel argument with
# multiple arguments
httr2::request("www.mywebsite.com") |>
  spdgt.auth:::api_pagination(pages = list(size = 1, number = 3))
} # }
if (FALSE) { # \dontrun{
spdgt.auth:::api_init("counts", "projects/age-classes") |>
 spdgt.auth:::api_filters(filters = list(species_id = 1)) |>
 api_perform(dry_run = TRUE)

 # Apply multiple filters
 spdgt.auth:::api_init("counts", "projects/age-classes") |>
   spdgt.auth:::api_filters(
     filters = list(species_id = 1, age_class_id = 2)
   ) |>
   api_perform(dry_run = TRUE)

 # Exclude species_id 1
 spdgt.auth:::api_init("counts", "projects/age-classes") |>
   spdgt.auth:::api_filters(filters = list(species_id = "!1")) |>
   api_perform(dry_run = TRUE)

 # Search for all species_id that contain 1
 spdgt.auth:::api_init("counts", "projects/age-classes") |>
   spdgt.auth:::api_filters(filters = list(species_id = "~1")) |>
   api_perform(dry_run = TRUE)

 # Exclude all species_id that contain 1
 spdgt.auth:::api_init("counts", "projects/age-classes") |>
  spdgt.auth:::api_filters(filters = list(species_id = "!~1")) |>
  api_perform(dry_run = TRUE)
 } # }
if (FALSE) { # \dontrun{
spdgt.auth:::api_init("counts", "api/lookup") |>
 spdgt.auth:::api_parameters(parameters = list(project_id = 1)) |>
 spdgt.auth::api_perform(dry_run = TRUE)
} # }
if (FALSE) { # \dontrun{
spdgt.auth:::api_init("counts", "projects/age-classes") |>
  spdgt.auth:::api_includes(
    includes = c("species", "units"),
    valid_includes = c("species", "units", "other_valid_value")
   ) |>
  api_perform(dry_run = TRUE)

# Includes and filters
spdgt.auth:::api_init("counts", "projects/age-classes") |>
 spdgt.auth:::api_includes(c("species", "units"), c("species", "units")) |>
 spdgt.auth:::api_filters(filters = list(species_id = 1)) |>
 api_perform(dry_run = TRUE)
} # }
if (FALSE) { # \dontrun{
# Append valid values for activities and vegetation to sightability model
# covariate values
spdgt.auth:::api_init("counts", "models/covars") |>
 spdgt.auth:::api_appends(
   appends = c("available_activities", "available_vegetation"),
   valid_appends = c("available_activities", "available_vegetation")
 ) |>
 api_perform(dry_run = TRUE)
} # }
if (FALSE) { # \dontrun{
# Create a data frame
df <- tibble::tibble(
 project_id = 1,
 species_id = 1,
 age_class = "Adult",
 age_min_months = 18,
 age_max_months = 30,
 is_first_reproduction = TRUE
)

# Basic metadata column for some measure
df_meta <- tibble::tibble(
  project_id = 1,
  species_id = 1,
  metadata = list(
    age_class = "Adult"
  )
)

df_meta_tbl <- tibble::tibble(
  project_id = 1,
  species_id = 1,
  metadata = list(
    tibble::tibble(
      hind_foot = c(3, 4)
    )
  )
)

# Nested data that is not metadata using a list
lst <- list(
  project_id = 1,
  species_id = 1,
  proportions = list(
    list(stratum = 1, proportion = 0.3),
    list(stratum = 2, proportion = 0.5)
  )
)

# Metadata in a list
lst_meta <- list(
  project_id = 1,
  species_id = 1,
  metadata = list(
    age_class = "Adult"
  )
)

# Add the data frame to the request
spdgt.auth:::api_init("counts", "projects/age-classes/") |>
  httr2::req_method("POST") |>
  spdgt.auth:::api_body(body = df) |>
  api_perform(dry_run = TRUE, verbosity = 3)
} # }
if (FALSE) { # \dontrun{
# Create a data frame
df <- tibble::tibble(
 project_id = 1:2,
 species_id = 1:2,
 age_class = rep("Adult", 2),
 age_min_months = rep(18, 2),
 age_max_months = rep(30, 2),
 is_first_reproduction = rep(TRUE, 2),
 metadata = list(
    tibble::tibble(
     comment = "testing",
     data = "dataset",
     measurements = tibble::tibble(
       x = 2,
       y = 3
     )
   )
 )
)

df2 <- tibble::tibble(
 project_id = 1:2,
 species_id = 1:2,
 age_class = rep("Adult", 2),
 age_min_months = rep(18, 2),
 age_max_months = rep(30, 2),
 is_first_reproduction = rep(TRUE, 2),
 hind_leg_length = 30,
 something_else = 22,
 another_value = 6
) |>
dplyr::nest_by(
  project_id, species_id, age_class, age_min_months, age_max_months,
  is_first_reproduction,
  .key = "metadata"
)

# Add the data frame to the request
spdgt.auth:::api_init("counts", "projects/age-classes/multiple") |>
  httr2::req_method("POST") |>
  spdgt.auth:::api_body_multi(body = df, nm = "estimates") |>
  api_perform(dry_run = TRUE)
} # }
if (FALSE) { # \dontrun{
# Create a data frame
df <- data.frame(
 project_id = 1:2,
 species_id = 1:2,
 age_class = rep("Adult", 2),
 age_min_months = rep(18, 2),
 age_max_months = rep(30, 2),
 is_first_reproduction = rep(TRUE, 2)
)


# Add the data frame to the request
api_init(
    "counts",
    endpoint = "projects/age-classes/multiple"
  ) |>
  httr2::req_method("POST") |>
  api_body_df(body = df) |>
  api_perform(dry_run = TRUE)
} # }