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

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

httr2

httr2 (pronounced "hitter2") is a comprehensive HTTP client that provides a modern, pipeable API for working with web APIs. It builds on top of {curl} to provide features like explicit request objects, built-in rate limiting & retry tooling, comprehensive OAuth support, and secure handling of secrets and credentials.

Installation

You can install httr2 from CRAN with:

install.packages("httr2")

Usage

To use httr2, start by creating a request:

library(httr2)

req <- request("https://r-project.org")
req

You can tailor this request with the req_ family of functions:

# Add custom headers
req |> req_headers("Accept" = "application/json")

# Add a body, turning it into a POST
req |> req_body_json(list(x = 1, y = 2))

# Modify the path in the url
req |> req_url_path(path = "path/to/my/file")

# Automatically retry if the request fails
req |> req_retry(max_tries = 5)

# Change the HTTP method
req |> req_method("PATCH")

And see exactly what httr2 will send to the server with req_dry_run():

req |> req_dry_run()

Use req_perform() to perform the request, retrieving a response:

resp <- req_perform(req)
resp

The resp_ functions help you extract various useful components of the response:

resp |> resp_content_type()
resp |> resp_status_desc()
resp |> resp_body_html()

Major differences to httr

• You can now create and modify a request without performing it. This means that there's now a single function to perform the request and fetch the result: req_perform(). req_perform() replaces httr::GET(), httr::POST(), httr::DELETE(), and more.

• HTTP errors are automatically converted into R errors. Use req_error() to override the defaults (which turn all 4xx and 5xx responses into errors) or to add additional details to the error message.

• You can automatically retry if the request fails or encounters a transient HTTP error (e.g. a 429 rate limit request). req_retry() defines the maximum number of retries, which errors are transient, and how long to wait between tries.

• OAuth support has been totally overhauled to directly support many more flows and to make it much easier to both customise the built-in flows and to create your own.

• You can manage secrets (often needed for testing) with secret_encrypt() and friends. You can obfuscate mildly confidential data with obfuscate(), preventing it from being scraped from published code.

• You can automatically cache all cacheable results with req_cache(). Relatively few API responses are cacheable, but when they are it typically makes a big difference.

Acknowledgements

httr2 wouldn't be possible without curl, openssl, jsonlite, and jose, which are all maintained by Jeroen Ooms. A big thanks also go to Jenny Bryan and Craig Citro who have given me much useful feedback on both the design of the internals and the user facing API.

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