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 withreq_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. 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 ofpath
. Will be ignored if you have manually set aContent-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 bycurl::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 tojsonlite::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:32849
#> User-Agent: httr2/1.0.5.9000 r-curl/5.2.3 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:32849
#> User-Agent: httr2/1.0.5.9000 r-curl/5.2.3 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:32849
#> User-Agent: httr2/1.0.5.9000 r-curl/5.2.3 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:32849
#> User-Agent: httr2/1.0.5.9000 r-curl/5.2.3 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:32849
#> User-Agent: httr2/1.0.5.9000 r-curl/5.2.3 libcurl/7.81.0
#> Accept: */*
#> Accept-Encoding: deflate, gzip, br, zstd
#> Content-Length: 316
#> Content-Type: multipart/form-data; boundary=------------------------9b64e59e2a08fa58
#>
#> --------------------------9b64e59e2a08fa58
#> Content-Disposition: form-data; name="a"; filename="file17e92fca8f6a"
#> Content-Type: application/octet-stream
#>
#> a
#> b
#> c
#> d
#> e
#> f
#>
#> --------------------------9b64e59e2a08fa58
#> Content-Disposition: form-data; name="b"
#>
#> some data
#> --------------------------9b64e59e2a08fa58--