req_url: Modify request URL

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

Modify request URL

Description

• req_url() replaces the entire URL.

• req_url_relative() navigates to a relative URL.

• req_url_query() modifies individual query components.

• req_url_path() modifies just the path.

• req_url_path_append() adds to the path.

Usage

req_url(req, url)

req_url_relative(req, url)

req_url_query(
  .req,
  ...,
  .multi = c("error", "comma", "pipe", "explode"),
  .space = c("percent", "form")
)

req_url_path(req, ...)

req_url_path_append(req, ...)

Arguments

req, .req	A httr2 request object.
url	A new URL; either an absolute URL for req_url() or a relative URL for req_url_relative().
...	For req_url_query(): <dynamic-dots> Name-value pairs that define query parameters. Each value must be either an atomic vector or NULL (which removes the corresponding parameters). If you want to opt out of escaping, wrap strings in I(). For req_url_path() and req_url_path_append(): A sequence of path components that will be combined with /.
.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.
.space	How should spaces in query params be escaped? The default, "percent", uses standard percent encoding (i.e. ⁠%20⁠), but you can opt-in to "form" encoding, which uses + instead.

Value

A modified HTTP request.

See Also

• To modify a URL without creating a request, see url_modify() and friends.

• To use a template like GET /user/{user}, see req_template().

Examples

# Change complete url
req <- request("http://example.com")
req |> req_url("http://google.com")

# Use a relative url
req <- request("http://example.com/a/b/c")
req |> req_url_relative("..")
req |> req_url_relative("/d/e/f")

# Change url components
req |>
  req_url_path_append("a") |>
  req_url_path_append("b") |>
  req_url_path_append("search.html") |>
  req_url_query(q = "the cool ice")

# Modify individual query parameters
req <- request("http://example.com?a=1&b=2")
req |> req_url_query(a = 10)
req |> req_url_query(a = NULL)
req |> req_url_query(c = 3)

# Use .multi to control what happens with vector parameters:
req |> req_url_query(id = 100:105, .multi = "comma")
req |> req_url_query(id = 100:105, .multi = "explode")

# If you have query parameters in a list, use !!!
params <- list(a = "1", b = "2")
req |>
  req_url_query(!!!params, c = "3")

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