Skip to contents

A generic helper for creating POST requests to the API

api_post.Rd

A POST request is generally used to store new data to the database. If the desire is to update or edit existing data a PATCH request should be used.

Usage

api_post(
  api_name,
  endpoint,
  body = NULL,
  add_user_id = FALSE,
  add_project_id = FALSE,
  dry_run = FALSE,
  verbosity = 0,
  timeout = 300
)

api_post_multi(
  api_name,
  endpoint,
  body = NULL,
  nm = "body",
  add_user_id = FALSE,
  add_project_id = FALSE,
  dry_run = FALSE,
  verbosity = 0,
  timeout = 300
)

api_post_df(
  api_name,
  endpoint,
  body = NULL,
  nm = "body",
  add_user_id = FALSE,
  add_project_id = FALSE,
  dry_run = FALSE,
  verbosity = 0,
  timeout = 300
)

api_post_progress(
  api_name,
  endpoint = "cache",
  key,
  dry_run = FALSE,
  verbosity = 0,
  timeout = 300
)

api_post_file(
  api_name,
  endpoint,
  file_path,
  aux_data,
  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

body

a list or tibble that will be passed as the body of the request to the API

add_user_id

a logical indicating if the user_id should be added to the body. Default is FALSE.

add_project_id

a logical indicating if the project_id should be added to the body. Default is FALSE.

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)

nm

the name of the object to be passed as the body of the request

key

the key returned from an api_post_multi call, this is used to poll the progress of the background job that is adding data to the database, async

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

httr2 response

Details

This function is intended to help with overhead, but the actual request will require formulating the body exactly as the API expects the request.

The function api_post_progress can be used to get the status of a large multiple record POST. When api_post_multi is called the response will contain a key and that key can be provided to api_post_progress to get the status of the request.

See also

api_get() to retrieve data, api_patch() to update records, api_delete() to remove records, parse_json2tibble() and parse_multi2tibble() to parse responses

Examples

if (FALSE) { # \dontrun{
body <- tibble::tibble(project_id = 1, species_id = 1, age_class = "Adult")
resp <- api_post("counts", "projects/age-classes", body = body)
parse_json2tibble(resp)

# Batch insert
resp <- api_post_multi("counts", "projects/age-classes/multiple",
  body = multi_row_tibble,
  nm = "age_classes"
)
parse_multi2tibble(resp)

# Check progress on a large batch insert
result <- parse_json2list(resp)
api_post_progress("counts", key = result$key)

# Upload a file
api_post_file("counts", "geography/import",
  file_path = "regions.geojson",
  aux_data = list(project_id = "1", type = "region")
)
} # }