Send data in request body — req

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 request.

body

A literal string or raw vector to send as body.

type

MIME content type. You shouldn't generally need to specify this as the defaults are usually pretty good, e.g. req_body_file() will guess it from the extension of of path. 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);
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 an element of ... is a vector containing multiple values:

"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 functions work, you can alternatively supply a function that takes a character vector and returns a 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()
#> POST /post HTTP/1.1
#> Host: 127.0.0.1:35453
#> User-Agent: httr2/1.0.1 r-curl/5.2.1 libcurl/7.81.0
#> Accept: */*
#> Accept-Encoding: deflate, gzip, br, zstd
#> Content-Type: application/x-www-form-urlencoded
#> Content-Length: 28
#> 
#> x=A%20simple%20text%20string

req |>
  req_body_json(list(x = "A simple text string")) |>
  req_dry_run()
#> POST /post HTTP/1.1
#> Host: 127.0.0.1:35453
#> User-Agent: httr2/1.0.1 r-curl/5.2.1 libcurl/7.81.0
#> Accept: */*
#> Accept-Encoding: deflate, gzip, br, zstd
#> Content-Type: application/json
#> Content-Length: 28
#> 
#> {"x":"A simple text string"}

# For total control over the body, send a string or raw vector
req |>
  req_body_raw("A simple text string") |>
  req_dry_run()
#> POST /post HTTP/1.1
#> Host: 127.0.0.1:35453
#> User-Agent: httr2/1.0.1 r-curl/5.2.1 libcurl/7.81.0
#> Accept: */*
#> Accept-Encoding: deflate, gzip, br, zstd
#> Content-Length: 20
#> 
#> A simple text string

# 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()
#> POST /post HTTP/1.1
#> Host: 127.0.0.1:35453
#> User-Agent: httr2/1.0.1 r-curl/5.2.1 libcurl/7.81.0
#> Accept: */*
#> Accept-Encoding: deflate, gzip, br, zstd
#> Content-Length: 12
#> 
#> a
#> b
#> c
#> d
#> e
#> f

# 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()
#> POST /post HTTP/1.1
#> Host: 127.0.0.1:35453
#> User-Agent: httr2/1.0.1 r-curl/5.2.1 libcurl/7.81.0
#> Accept: */*
#> Accept-Encoding: deflate, gzip, br, zstd
#> Content-Length: 315
#> Content-Type: multipart/form-data; boundary=------------------------dd6e869515330a8a
#> 
#> --------------------------dd6e869515330a8a
#> Content-Disposition: form-data; name="a"; filename="file1861f56b5f3"
#> Content-Type: application/octet-stream
#> 
#> a
#> b
#> c
#> d
#> e
#> f
#> 
#> --------------------------dd6e869515330a8a
#> Content-Disposition: form-data; name="b"
#> 
#> some data
#> --------------------------dd6e869515330a8a--