collapse = TRUE,
  comment = "#>"

The goal of this document is show you the basics of httr2. You'll learn how to create and submit HTTP requests and work with the HTTP responses that you get back. httr2 is designed to map closely to the underlying HTTP protocol, which I'll explain as we go along. For more details, I also recommend "An overview of HTTP" from MDN.


Create a request

In httr2, you start by creating a request. If you're familiar with httr, this a big change: with httr you could only submit a request, immediately receiving a response. Having an explicit request object makes it easier to build up a complex request piece by piece and works well with the pipe.

Every request starts with a URL:

req <- request("")

We can see exactly what this request will send to the server with a dry run:

req %>% req_dry_run()

The first line of the request contains three important pieces of information:

The following lines specify the HTTP headers, a series of name-value pairs separated by :. The headers in this request were automatically added by httr2, but you can override them or add your own with req_headers():

req %>%
    Name = "Hadley", 
    `Shoe-Size` = "11", 
    Accept = "application/json"
  ) %>% 

Header names are case-insensitive, and servers will ignore headers that they don't understand.

The headers finish with a blank line which is followed by the body. The requests above (like all GET requests) don't have a body, so let's add one to see what happens. The req_body_*() functions provide a variety of ways to add data to the body. Here we'll use req_body_json() to add some data encoded as JSON:

req %>%
  req_body_json(list(x = 1, y = "a")) %>% 

What's changed?

Different servers want data encoded differently so httr2 provides a selection of common formats. For example, req_body_form() uses the encoding used when you submit a form from a web browser:

req %>%
  req_body_form(list(x = "1", y = "a")) %>% 

And req_body_multipart() uses the multipart encoding which is particularly important when you need to send larger amounts of data or complete files:

req %>%
  req_body_multipart(list(x = "1", y = "a")) %>% 

If you need to send data encoded in a different form, you can use req_body_raw() to add the data to the body and set the Content-Type header.

Perform a request and fetch the response

To actually perform a request and fetch the response back from the server, call req_perform():

req <- request("")
resp <- req %>% req_perform()

You can see a simulation of what httr2 actually received with resp_raw():

resp %>% resp_raw()

An HTTP response has a very similar structure to an HTTP request. The first line gives the version of HTTP used, and a status code that's optionally followed by a short description. Then we have the headers, followed by a blank line, followed by a body. The majority of responses will have a body, unlike requests.

You can extract data from the response using the resp_() functions:

Responses with status codes 4xx and 5xx are HTTP errors. httr2 automatically turns these into R errors:

request("") %>% req_perform()
request("") %>% req_perform()

This is another important difference to httr, which required that you explicitly call httr::stop_for_status() to turn HTTP errors into R errors. You can revert to the httr behaviour with req_error(req, is_error = ~ FALSE).

Control the request process

A number of req_ functions don't directly affect the HTTP request but instead control the overall process of submitting a request and handling the response. These include:

For more details see their documentation, as well as examples of the usage in real APIs in vignette("wrapping-apis.Rmd").

Try the httr2 package in your browser

Any scripts or data that you put into this service are public.

httr2 documentation built on Sept. 28, 2021, 5:10 p.m.