req_url {httr2}R Documentation

Modify request URL

Description

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

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")

[Package httr2 version 1.1.2 Index]