Create a PATCH request

A PATCH request is used to alter an existing record in the database. If the desire is to store new data to the database a POST request should be used.

Usage

api_patch(
  api_name,
  endpoint,
  id,
  body = NULL,
  dry_run = FALSE,
  verbosity = 0,
  timeout = 300
)

api_patch_multi(
  api_name,
  endpoint,
  id,
  body = 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

id

the id of the record to be edited

body

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

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)

Value

a response object

Details

Similar to POST a single and multiple entry version of this function is available.

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.

See also

api_get() to retrieve data, api_post() to create records, api_delete() to remove records

Examples

if (FALSE) { # \dontrun{
updates <- tibble::tibble(age_class = "Sub-Adult")
api_patch("counts", "projects/age-classes", id = 42, body = updates)

# Batch update
api_patch_multi("counts", "projects/age-classes/multiple",
  id = c(42, 43),
  body = tibble::tibble(age_class = c("Sub-Adult", "Juvenile"))
)
} # }