Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/r-lib/httr2
Make HTTP requests and process their responses. A modern reimagining of httr.
https://github.com/r-lib/httr2
http r
Last synced: 27 days ago
JSON representation
Make HTTP requests and process their responses. A modern reimagining of httr.
- Host: GitHub
- URL: https://github.com/r-lib/httr2
- Owner: r-lib
- License: other
- Created: 2018-11-22T15:32:29.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2024-09-30T20:29:03.000Z (about 1 month ago)
- Last Synced: 2024-10-01T16:36:40.532Z (about 1 month ago)
- Topics: http, r
- Language: R
- Homepage: https://httr2.r-lib.org
- Size: 15.1 MB
- Stars: 237
- Watchers: 13
- Forks: 57
- Open Issues: 36
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - r-lib/httr2 - Make HTTP requests and process their responses. A modern reimagining of httr. (R)
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# httr2 
[](https://github.com/r-lib/httr2/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/r-lib/httr2?branch=main)
httr2 (pronounced hitter2) is a ground-up rewrite of [httr](https://httr.r-lib.org) that provides a pipeable API with an explicit request object that solves more problems felt by packages that wrap APIs (e.g. built-in rate-limiting, retries, OAuth, secure secrets, and more).
## Installation
You can install httr2 from CRAN with:
``` r
install.packages("httr2")
```
## Usage
To use httr2, start by creating a **request**:
```{r}
library(httr2)
req <- request("https://r-project.org")
req
```
You can tailor this request with the `req_` family of functions:
```{r}
# 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()`:
```{r}
req |> req_dry_run()
```
Use `req_perform()` to perform the request, retrieving a **response**:
```{r}
resp <- req_perform(req)
resp
```
The `resp_` functions help you extract various useful components of the response:
```{r}
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](https://jeroen.cran.dev/curl/), [openssl](https://github.com/jeroen/openssl/), [jsonlite](https://jeroen.cran.dev/jsonlite/), and [jose](https://github.com/r-lib/jose/), which are all maintained by [Jeroen Ooms](https://github.com/jeroen).
A big thanks also go to [Jenny Bryan](https://jennybryan.org) and [Craig Citro](https://www.craigcitro.org) who have given me much useful feedback on both the design of the internals and the user facing API.