A generic helper for creating POST requests to the API

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.

Missing values

Every request body this family builds follows one rule, whatever the column type and whichever builder is used:

In R	On the wire	Meaning
`NA`, any type	`null`	clear the field
column or element absent	not sent	leave the field alone
`NaN`, `Inf`, `-Inf`	error	refused before the request is sent
`NULL` list element	`null`	clear the field

The two things an update can mean are therefore said differently: an NA clears the field, and a column you leave out of the body is left alone. Note that clearing a field the API marks as required is rejected with a 422 — an NA you did not intend is an error rather than a silent no-op.

NaN and Inf have no JSON representation. Rather than guess at one they are refused, naming the offending fields, because both plausible guesses are wrong: null writes a missing value nobody asked for, and "NaN" fails validation at the API with a message that names the field but not the row.

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")
)
} # }