req_body: Send data in request body

In r-lib/httr2: Perform HTTP Requests and Process the Responses

Send data in request body

Description

• req_body_file() sends a local file.

• req_body_raw() sends a string or raw vector.

• req_body_json() sends JSON encoded data. Named components of this data can later be modified with req_body_json_modify().

• req_body_form() sends form encoded data.

• req_body_multipart() creates a multi-part body.

Adding a body to a request will automatically switch the method to POST.

Usage

req_body_raw(req, body, type = NULL)

req_body_file(req, path, type = NULL)

req_body_json(
  req,
  data,
  auto_unbox = TRUE,
  digits = 22,
  null = "null",
  type = "application/json",
  ...
)

req_body_json_modify(req, ...)

req_body_form(.req, ..., .multi = c("error", "comma", "pipe", "explode"))

req_body_multipart(.req, ...)

Arguments

req, .req	A httr2 request object.
body	A literal string or raw vector to send as body.
type	MIME content type. Will be ignored if you have manually set a Content-Type header.
path	Path to file to upload.
data	Data to include in body.
auto_unbox	Should length-1 vectors be automatically "unboxed" to JSON scalars?
digits	How many digits of precision should numbers use in JSON?
null	Should NULL be translated to JSON's null ("null") or an empty list ("list").
...	<dynamic-dots> Name-data pairs used to send data in the body. For req_body_form(), the values must be strings (or things easily coerced to strings). Vectors are convertd to strings using the value of .multi. For req_body_multipart() the values must be strings or objects produced by curl::form_file()/curl::form_data(). For req_body_json_modify(), any simple data made from atomic vectors and lists. req_body_json() uses this argument differently; it takes additional arguments passed on to jsonlite::toJSON().
.multi	Controls what happens when a value is a vector: "error", the default, throws an error. "comma", separates values with a ⁠,⁠, e.g. ⁠?x=1,2⁠. "pipe", separates values with a |, e.g. ?x=1|2. "explode", turns each element into its own parameter, e.g. ?x=1&x=2 If none of these options work for your needs, you can instead supply a function that takes a character vector of argument values and returns a a single string.

Value

A modified HTTP request.

Examples

req <- request(example_url()) |>
  req_url_path("/post")

# Most APIs expect small amounts of data in either form or json encoded:
req |>
  req_body_form(x = "A simple text string") |>
  req_dry_run()

req |>
  req_body_json(list(x = "A simple text string")) |>
  req_dry_run()

# For total control over the body, send a string or raw vector
req |>
  req_body_raw("A simple text string") |>
  req_dry_run()

# There are two main ways that APIs expect entire files
path <- tempfile()
writeLines(letters[1:6], path)

# You can send a single file as the body:
req |>
  req_body_file(path) |>
  req_dry_run()

# You can send multiple files, or a mix of files and data
# with multipart encoding
req |>
  req_body_multipart(a = curl::form_file(path), b = "some data") |>
  req_dry_run()

r-lib/httr2 documentation built on Jan. 11, 2025, 10:21 a.m.