Skip to contents

A generic helper for creating GET requests to the API

api_get.Rd

A GET request is used to retrieve data from the database. The request can be paginated, filtered, and include additional data via includes and/or appends.

Usage

api_get(
  api_name,
  endpoint,
  pages = list(),
  parameters = list(),
  filters = list(),
  decorate_filters = TRUE,
  includes = NULL,
  valid_includes = NULL,
  appends = NULL,
  valid_appends = NULL,
  dry_run = FALSE,
  verbosity = 0,
  timeout = 300
)

api_get_id(
  api_name,
  endpoint,
  id,
  includes = NULL,
  valid_includes = NULL,
  appends = NULL,
  valid_appends = NULL,
  dry_run = FALSE,
  verbosity = 0,
  timeout = 300
)

Arguments

api_name

the name of the API to call

endpoint

the API endpoint to make the request to

pages

a named list of page arguments, common choices are size, number, and omit

parameters

a named list of query parameters to pass to the request, see the lookups endpoint for an example

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.

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

dry_run

if TRUE, the call is printed to the console instead of being sent to the API, which is useful for debugging

verbosity

How much information to print to the console. Defaults to 0.

  • 0: no output

  • 1: show headers

  • 2: show headers and body

  • 3: show headers, body, and curl status messages

timeout

request timeout in seconds (default is 300)

id

the id of the resource to retrieve

Value

An httr2 response object.

Details

For examples of implementation see spdgt.core package.

See also

api_post(), api_patch(), api_delete() for other HTTP methods, api_export() for file exports, parse_json2tibble() to parse responses. See vignette("requests") for filter operator syntax, pagination options, and include/append usage.

Examples

if (FALSE) { # \dontrun{
resp <- api_get("counts", "projects")
parse_json2tibble(resp)

# With filters and pagination
resp <- api_get("counts", "projects/age-classes",
  filters = list(species_id = 1),
  pages = list(size = 100)
)

# Retrieve a single record by ID
resp <- api_get_id("counts", "projects", id = 42)
} # }