httr2/ 0000755 0001762 0000144 00000000000 14524675723 011334 5 ustar ligges users httr2/NAMESPACE 0000644 0001762 0000144 00000006625 14520200264 012540 0 ustar ligges users # Generated by roxygen2: do not edit by hand
S3method("$",httr2_headers)
S3method("[",httr2_headers)
S3method("[[",httr2_headers)
S3method(print,httr2_cmd)
S3method(print,httr2_headers)
S3method(print,httr2_oauth_client)
S3method(print,httr2_obfuscated)
S3method(print,httr2_request)
S3method(print,httr2_response)
S3method(print,httr2_token)
S3method(print,httr2_url)
S3method(str,httr2_obfuscated)
export("%>%")
export(curl_help)
export(curl_translate)
export(example_github_client)
export(example_url)
export(iterate_with_cursor)
export(iterate_with_link_url)
export(iterate_with_offset)
export(jwt_claim)
export(jwt_encode_hmac)
export(jwt_encode_sig)
export(last_request)
export(last_response)
export(local_mock)
export(local_mocked_responses)
export(multi_req_perform)
export(oauth_cache_path)
export(oauth_client)
export(oauth_client_req_auth)
export(oauth_client_req_auth_body)
export(oauth_client_req_auth_header)
export(oauth_client_req_auth_jwt_sig)
export(oauth_flow_auth_code)
export(oauth_flow_auth_code_listen)
export(oauth_flow_auth_code_parse)
export(oauth_flow_auth_code_pkce)
export(oauth_flow_auth_code_url)
export(oauth_flow_bearer_jwt)
export(oauth_flow_client_credentials)
export(oauth_flow_device)
export(oauth_flow_password)
export(oauth_flow_refresh)
export(oauth_redirect_uri)
export(oauth_token)
export(oauth_token_cached)
export(obfuscate)
export(obfuscated)
export(req_auth_basic)
export(req_auth_bearer_token)
export(req_body_file)
export(req_body_form)
export(req_body_json)
export(req_body_json_modify)
export(req_body_multipart)
export(req_body_raw)
export(req_cache)
export(req_cookie_preserve)
export(req_dry_run)
export(req_error)
export(req_headers)
export(req_method)
export(req_oauth)
export(req_oauth_auth_code)
export(req_oauth_bearer_jwt)
export(req_oauth_client_credentials)
export(req_oauth_device)
export(req_oauth_password)
export(req_oauth_refresh)
export(req_options)
export(req_perform)
export(req_perform_iterative)
export(req_perform_parallel)
export(req_perform_sequential)
export(req_perform_stream)
export(req_progress)
export(req_proxy)
export(req_retry)
export(req_stream)
export(req_template)
export(req_throttle)
export(req_timeout)
export(req_url)
export(req_url_path)
export(req_url_path_append)
export(req_url_query)
export(req_user_agent)
export(req_verbose)
export(request)
export(resp_body_html)
export(resp_body_json)
export(resp_body_raw)
export(resp_body_string)
export(resp_body_xml)
export(resp_check_content_type)
export(resp_check_status)
export(resp_content_type)
export(resp_date)
export(resp_encoding)
export(resp_has_body)
export(resp_header)
export(resp_header_exists)
export(resp_headers)
export(resp_is_error)
export(resp_link_url)
export(resp_raw)
export(resp_retry_after)
export(resp_status)
export(resp_status_desc)
export(resp_url)
export(resp_url_path)
export(resp_url_queries)
export(resp_url_query)
export(response)
export(response_json)
export(resps_data)
export(resps_failures)
export(resps_requests)
export(resps_successes)
export(secret_decrypt)
export(secret_decrypt_file)
export(secret_encrypt)
export(secret_encrypt_file)
export(secret_has_key)
export(secret_make_key)
export(secret_read_rds)
export(secret_write_rds)
export(signal_total_pages)
export(throttle_status)
export(url_build)
export(url_parse)
export(with_mock)
export(with_mocked_responses)
export(with_verbosity)
import(R6)
import(rlang)
importFrom(glue,glue)
importFrom(lifecycle,deprecated)
importFrom(magrittr,"%>%")
httr2/LICENSE 0000644 0001762 0000144 00000000053 14052737620 012326 0 ustar ligges users YEAR: 2021
COPYRIGHT HOLDER: httr2 authors
httr2/tools/ 0000755 0001762 0000144 00000000000 14514566210 012461 5 ustar ligges users httr2/tools/examples.R 0000644 0001762 0000144 00000001040 14514566210 014415 0 ustar ligges users if (getRversion() < "4.1") {
dir.create("man/macros", showWarnings = FALSE, recursive = TRUE)
cat(
paste(
"\\renewcommand{\\examples}{\\section{Examples}{",
"These examples are designed to work in R >= 4.1 so that we can take",
"advantage of modern syntax like the base pipe (\\verb{|>}) and the ",
"function shorthand (\\verb{\\(x) x + 1}). They might not work on the ",
"version of R that you're using.",
"\\preformatted{#1}}}",
collapse = ""
),
file = "man/macros/examples.Rd"
)
}
httr2/README.md 0000644 0001762 0000144 00000010700 14523473134 012600 0 ustar ligges users
# httr2
[](https://github.com/r-lib/httr2/actions)
[](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
#>
#> GET https://r-project.org
#> Body: empty
```
You can tailor this request with the `req_` family of functions:
``` r
# Add custom headers
req %>% req_headers("Accept" = "application/json")
#>
#> GET https://r-project.org
#> Headers:
#> • Accept: 'application/json'
#> Body: empty
# Add a body, turning it into a POST
req %>% req_body_json(list(x = 1, y = 2))
#>
#> POST https://r-project.org
#> Body: json encoded data
# Automatically retry if the request fails
req %>% req_retry(max_tries = 5)
#>
#> GET https://r-project.org
#> Body: empty
#> Policies:
#> • retry_max_tries: 5
# Change the HTTP method
req %>% req_method("PATCH")
#>
#> PATCH https://r-project.org
#> Body: empty
```
And see exactly what httr2 will send to the server with `req_dry_run()`:
``` r
req %>% req_dry_run()
#> GET / HTTP/1.1
#> Host: r-project.org
#> User-Agent: httr2/0.2.3.9000 r-curl/5.1.0 libcurl/8.3.0
#> Accept: */*
#> Accept-Encoding: deflate, gzip
```
Use `req_perform()` to perform the request, retrieving a **response**:
``` r
resp <- req_perform(req)
resp
#>
#> GET https://www.r-project.org/
#> Status: 200 OK
#> Content-Type: text/html
#> Body: In memory (6446 bytes)
```
The `resp_` functions help you extract various useful components of the
response:
``` r
resp %>% resp_content_type()
#> [1] "text/html"
resp %>% resp_status_desc()
#> [1] "OK"
resp %>% resp_body_html()
#> {html_document}
#>
#> [1] \n\n
\n ...
```
## 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://research.google/people/CraigCitro/) who have given me
much useful feedback on both the design of the internals and the user
facing API.
httr2/man/ 0000755 0001762 0000144 00000000000 14524445373 012103 5 ustar ligges users httr2/man/secrets.Rd 0000644 0001762 0000144 00000010206 14475517553 014046 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/secret.R
\name{secrets}
\alias{secret_make_key}
\alias{secret_encrypt}
\alias{secret_decrypt}
\alias{secret_write_rds}
\alias{secret_read_rds}
\alias{secret_decrypt_file}
\alias{secret_encrypt_file}
\alias{secret_has_key}
\title{Secret management}
\usage{
secret_make_key()
secret_encrypt(x, key)
secret_decrypt(encrypted, key)
secret_write_rds(x, path, key)
secret_read_rds(path, key)
secret_decrypt_file(path, key, envir = parent.frame())
secret_encrypt_file(path, key)
secret_has_key(key)
}
\arguments{
\item{x}{Object to encrypt. Must be a string for \code{secret_encrypt()}.}
\item{key}{Encryption key; this is the password that allows you to "lock"
and "unlock" the secret. The easiest way to specify this is as the
name of an environment variable. Alternatively, if you already have
a base64url encoded string, you can wrap it in \code{I()}, or you can pass
the raw vector in directly.}
\item{encrypted}{String to decrypt}
\item{path}{Path to \code{.rds} file}
\item{envir}{The decrypted file will be automatically deleted when
this environment exits. You should only need to set this argument if you
want to pass the unencrypted file to another function.}
}
\value{
\itemize{
\item \code{secret_decrypt()} and \code{secret_encrypt()} return strings.
\item \code{secret_write_rds()} returns \code{x} invisibly; \code{secret_read_rds()}
returns the saved object.
\item \code{secret_make_key()} returns a string with class \code{AsIs}.
\item \code{secret_has_key()} returns \code{TRUE} or \code{FALSE}.
}
}
\description{
httr2 provides a handful of functions designed for working with confidential
data. These are useful because testing packages that use httr2 often
requires some confidential data that needs to be available for testing,
but should not be available to package users.
\itemize{
\item \code{secret_encrypt()} and \code{secret_decrypt()} work with individual strings
\item \code{secret_encrypt_file()} encrypts a file in place and
\code{secret_decrypt_file()} decrypts a file in a temporary location.
\item \code{secret_write_rds()} and \code{secret_read_rds()} work with \code{.rds} files
\item \code{secret_make_key()} generates a random string to use as a key.
\item \code{secret_has_key()} returns \code{TRUE} if the key is available; you can
use it in examples and vignettes that you want to evaluate on your CI,
but not for CRAN/package users.
}
These all look for the key in an environment variable. When used inside of
testthat, they will automatically \code{\link[testthat:skip]{testthat::skip()}} the test if the env var
isn't found. (Outside of testthat, they'll error if the env var isn't
found.)
}
\section{Basic workflow}{
\enumerate{
\item Use \code{secret_make_key()} to generate a password. Make this available
as an env var (e.g. \verb{\{MYPACKAGE\}_KEY}) by adding a line to your
\code{.Renviron}.
\item Encrypt strings with \code{secret_encrypt()}, files with
\code{secret_encrypt_file()}, and other data with \code{secret_write_rds()},
setting \code{key = "{MYPACKAGE}_KEY"}.
\item In your tests, decrypt the data with \code{secret_decrypt()},
\code{secret_decrypt_file()}, or \code{secret_read_rds()} to match how you encrypt
it.
\item If you push this code to your CI server, it will already "work" because
all functions automatically skip tests when your \verb{\{MYPACKAGE\}_KEY}
env var isn't set. To make the tests actually run, you'll need to set
the env var using whatever tool your CI system provides for setting
env vars. Make sure to carefully inspect the test output to check that
the skips have actually gone away.
}
}
\examples{
key <- secret_make_key()
path <- tempfile()
secret_write_rds(mtcars, path, key = key)
secret_read_rds(path, key)
# While you can manage the key explicitly in a variable, it's much
# easier to store in an environment variable. In real life, you should
# NEVER use `Sys.setenv()` to create this env var because you will
# also store the secret in your `.Rhistory`. Instead add it to your
# .Renviron using `usethis::edit_r_environ()` or similar.
Sys.setenv("MY_KEY" = key)
x <- secret_encrypt("This is a secret", "MY_KEY")
x
secret_decrypt(x, "MY_KEY")
}
httr2/man/req_perform_stream.Rd 0000644 0001762 0000144 00000002223 14514566210 016256 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-perform-stream.R
\name{req_perform_stream}
\alias{req_perform_stream}
\alias{req_stream}
\title{Perform a request and handle data as it streams back}
\usage{
req_perform_stream(req, callback, timeout_sec = Inf, buffer_kb = 64)
}
\arguments{
\item{req}{A \link{request}.}
\item{callback}{A single argument callback function. It will be called
repeatedly with a raw vector whenever there is at least \code{buffer_kb}
worth of data to process. It must return \code{TRUE} to continue streaming.}
\item{timeout_sec}{Number of seconds to processs stream for.}
\item{buffer_kb}{Buffer size, in kilobytes.}
}
\value{
An HTTP \link{response}.
}
\description{
After preparing a request, call \code{req_perform_stream()} to perform the request
and handle the result with a streaming callback. This is useful for
streaming HTTP APIs where potentially the stream never ends.
}
\examples{
show_bytes <- function(x) {
cat("Got ", length(x), " bytes\n", sep = "")
TRUE
}
resp <- request(example_url()) |>
req_url_path("/stream-bytes/100000") |>
req_perform_stream(show_bytes, buffer_kb = 32)
}
httr2/man/req_oauth.Rd 0000644 0001762 0000144 00000002070 14514574463 014362 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oauth.R
\name{req_oauth}
\alias{req_oauth}
\title{OAuth authentication}
\usage{
req_oauth(req, flow, flow_params, cache)
}
\arguments{
\item{req}{A \link{request}.}
\item{flow}{An \code{oauth_flow_} function used to generate the access token.}
\item{flow_params}{Parameters for the flow. This should be a named list
whose names match the argument names of \code{flow}.}
\item{cache}{An object that controls how the token is cached. This should
be a list containing three functions:
\itemize{
\item \code{get()} retrieves the token from the cache, returning \code{NULL} if not
cached yet.
\item \code{set()} saves the token to the cache.
\item \code{clear()} removes the token from the cache
}}
}
\value{
An \link{oauth_token}.
}
\description{
This is a low-level helper for automatically authenticating a request with
an OAuth flow, caching the access token and refreshing it where possible.
You should only need to use this function if you're implementing your own
OAuth flow.
}
\keyword{internal}
httr2/man/req_oauth_bearer_jwt.Rd 0000644 0001762 0000144 00000004536 14514566210 016566 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oauth-flow-jwt.R
\name{req_oauth_bearer_jwt}
\alias{req_oauth_bearer_jwt}
\alias{oauth_flow_bearer_jwt}
\title{OAuth with a bearer JWT (JSON web token)}
\usage{
req_oauth_bearer_jwt(
req,
client,
claim,
signature = "jwt_encode_sig",
signature_params = list(),
scope = NULL,
token_params = list()
)
oauth_flow_bearer_jwt(
client,
claim,
signature = "jwt_encode_sig",
signature_params = list(),
scope = NULL,
token_params = list()
)
}
\arguments{
\item{req}{A \link{request}.}
\item{client}{An \code{\link[=oauth_client]{oauth_client()}}.}
\item{claim}{A list of claims. If all elements of the claim set are static
apart from \code{iat}, \code{nbf}, \code{exp}, or \code{jti}, provide a list and
\code{\link[=jwt_claim]{jwt_claim()}} will automatically fill in the dynamic components.
If other components need to vary, you can instead provide a zero-argument
callback function which should call \code{jwt_claim()}.}
\item{signature}{Function use to sign \code{claim}, e.g. \code{\link[=jwt_encode_sig]{jwt_encode_sig()}}.}
\item{signature_params}{Additional arguments passed to \code{signature}, e.g.
\code{size}, \code{header}.}
\item{scope}{Scopes to be requested from the resource owner.}
\item{token_params}{List containing additional parameters passed to the
\code{token_url}.}
}
\value{
\code{req_oauth_bearer_jwt()} returns a modified HTTP \link{request} that will
use OAuth; \code{oauth_flow_bearer_jwt()} returns an \link{oauth_token}.
}
\description{
Authenticate using a \strong{Bearer JWT} (JSON web token) as an authorization
grant to get an access token, as defined by \href{https://datatracker.ietf.org/doc/html/rfc7523#section-2.1}{Section 2.1 of RFC 7523}.
It is often used for service accounts, accounts that are used primarily in
automated environments.
Learn more about the overall OAuth authentication flow in \code{vignette("oauth")}.
}
\examples{
req_auth <- function(req) {
req_oauth_bearer_jwt(
req,
client = oauth_client("example", "https://example.com/get_token"),
claim = jwt_claim()
)
}
request("https://example.com") |>
req_auth()
}
\seealso{
Other OAuth flows:
\code{\link{req_oauth_auth_code}()},
\code{\link{req_oauth_client_credentials}()},
\code{\link{req_oauth_password}()},
\code{\link{req_oauth_refresh}()}
}
\concept{OAuth flows}
httr2/man/req_headers.Rd 0000644 0001762 0000144 00000003431 14523473134 014650 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-headers.R
\name{req_headers}
\alias{req_headers}
\title{Modify request headers}
\usage{
req_headers(.req, ..., .redact = NULL)
}
\arguments{
\item{.req}{A \link{request}.}
\item{...}{<\code{\link[rlang:dyn-dots]{dynamic-dots}}> Name-value pairs of headers
and their values.
\itemize{
\item Use \code{NULL} to reset a value to httr2's default
\item Use \code{""} to remove a header
\item Use a character vector to repeat a header.
}}
\item{.redact}{Headers to redact. If \code{NULL}, the default, the added headers
are not redacted.}
}
\value{
A modified HTTP \link{request}.
}
\description{
\code{req_headers()} allows you to set the value of any header.
}
\examples{
req <- request("http://example.com")
# Use req_headers() to add arbitrary additional headers to the request
req |>
req_headers(MyHeader = "MyValue") |>
req_dry_run()
# Repeated use overrides the previous value:
req |>
req_headers(MyHeader = "Old value") |>
req_headers(MyHeader = "New value") |>
req_dry_run()
# Setting Accept to NULL uses curl's default:
req |>
req_headers(Accept = NULL) |>
req_dry_run()
# Setting it to "" removes it:
req |>
req_headers(Accept = "") |>
req_dry_run()
# If you need to repeat a header, provide a vector of values
# (this is rarely needed, but is important in a handful of cases)
req |>
req_headers(HeaderName = c("Value 1", "Value 2", "Value 3")) |>
req_dry_run()
# If you have headers in a list, use !!!
headers <- list(HeaderOne = "one", HeaderTwo = "two")
req |>
req_headers(!!!headers, HeaderThree = "three") |>
req_dry_run()
# Use `.redact` to hide a header in the output
req |>
req_headers(Secret = "this-is-private", Public = "but-this-is-not", .redact = "Secret") |>
req_dry_run()
}
httr2/man/req_oauth_password.Rd 0000644 0001762 0000144 00000004440 14514566210 016276 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oauth-flow-password.R
\name{req_oauth_password}
\alias{req_oauth_password}
\alias{oauth_flow_password}
\title{OAuth with username and password}
\usage{
req_oauth_password(
req,
client,
username,
password = NULL,
scope = NULL,
token_params = list(),
cache_disk = FALSE,
cache_key = username
)
oauth_flow_password(
client,
username,
password = NULL,
scope = NULL,
token_params = list()
)
}
\arguments{
\item{req}{A \link{request}.}
\item{client}{An \code{\link[=oauth_client]{oauth_client()}}.}
\item{username}{User name.}
\item{password}{Password. You avoid entering the password directly when
calling this function as it will be captured by \code{.Rhistory}. Instead,
leave it unset and the default behaviour will prompt you for it
interactively.}
\item{scope}{Scopes to be requested from the resource owner.}
\item{token_params}{List containing additional parameters passed to the
\code{token_url}.}
\item{cache_disk}{Should the access token be cached on disk? This reduces
the number of times that you need to re-authenticate at the cost of
storing access credentials on disk.
Learn more in \code{vignette("oauth")}}
\item{cache_key}{If you want to cache multiple tokens per app, use this
key to disambiguate them.}
}
\value{
\code{req_oauth_password()} returns a modified HTTP \link{request} that will
use OAuth; \code{oauth_flow_password()} returns an \link{oauth_token}.
}
\description{
This function implements the OAuth \strong{resource owner password flow}, as
defined by \href{https://datatracker.ietf.org/doc/html/rfc6749#section-4.3}{Section 4.3 of RFC 6749}. It allows the user to supply their password
once, exchanging it for an access token that can be cached locally.
Learn more about the overall OAuth authentication flow in \code{vignette("oauth")}.
}
\examples{
req_auth <- function(req) {
req_oauth_password(req,
client = oauth_client("example", "https://example.com/get_token"),
username = "username"
)
}
if (interactive()) {
request("https://example.com") |>
req_auth()
}
}
\seealso{
Other OAuth flows:
\code{\link{req_oauth_auth_code}()},
\code{\link{req_oauth_bearer_jwt}()},
\code{\link{req_oauth_client_credentials}()},
\code{\link{req_oauth_refresh}()}
}
\concept{OAuth flows}
httr2/man/resp_content_type.Rd 0000644 0001762 0000144 00000002667 14523473134 016144 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/resp-headers.R
\name{resp_content_type}
\alias{resp_content_type}
\alias{resp_encoding}
\title{Extract response content type and encoding}
\usage{
resp_content_type(resp)
resp_encoding(resp)
}
\arguments{
\item{resp}{An HTTP response object, as created by \code{\link[=req_perform]{req_perform()}}.}
}
\value{
A string. If no content type is specified \code{resp_content_type()}
will return a character \code{NA}; if no encoding is specified,
\code{resp_encoding()} will return \code{"UTF-8"}.
}
\description{
\code{resp_content_type()} returns the just the type and subtype of the
from the \code{Content-Type} header. If \code{Content-Type} is not provided; it
returns \code{NA}. Used by \code{\link[=resp_body_json]{resp_body_json()}}, \code{\link[=resp_body_html]{resp_body_html()}}, and
\code{\link[=resp_body_xml]{resp_body_xml()}}.
\code{resp_encoding()} returns the likely character encoding of text
types, as parsed from the \code{charset} parameter of the \code{Content-Type}
header. If that header is not found, not valid, or no charset parameter
is found, returns \code{UTF-8}. Used by \code{\link[=resp_body_string]{resp_body_string()}}.
}
\examples{
resp <- response(headers = "Content-type: text/html; charset=utf-8")
resp |> resp_content_type()
resp |> resp_encoding()
# No Content-Type header
resp <- response()
resp |> resp_content_type()
resp |> resp_encoding()
}
httr2/man/req_perform.Rd 0000644 0001762 0000144 00000007117 14520200264 014701 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-perform.R
\name{req_perform}
\alias{req_perform}
\title{Perform a request to get a response}
\usage{
req_perform(
req,
path = NULL,
verbosity = NULL,
mock = getOption("httr2_mock", NULL),
error_call = current_env()
)
}
\arguments{
\item{req}{A \link{request}.}
\item{path}{Optionally, path to save body of request. This is useful for
large responses since it avoids storing the response in memory.}
\item{verbosity}{How much information to print? This is a wrapper
around \code{req_verbose()} that uses an integer to control verbosity:
\itemize{
\item 0: no output
\item 1: show headers
\item 2: show headers and bodies
\item 3: show headers, bodies, and curl status messages.
}
Use \code{\link[=with_verbosity]{with_verbosity()}} to control the verbosity of requests that
you can't affect directly.}
\item{mock}{A mocking function. If supplied, this function is called
with the request. It should return either \code{NULL} (if it doesn't want to
handle the request) or a \link{response} (if it does). See \code{\link[=with_mock]{with_mock()}}/
\code{local_mock()} for more details.}
\item{error_call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[rlang:abort]{abort()}} for more information.}
}
\value{
\itemize{
\item If the HTTP request succeeds, and the status code is ok (e.g. 200),
an HTTP \link{response}.
\item If the HTTP request succeeds, but the status code is an error
(e.g a 404), an error with class \code{c("httr2_http_404", "httr2_http")}.
By default, all 400 and 500 status codes will be treated as an error,
but you can customise this with \code{\link[=req_error]{req_error()}}.
\item If the HTTP request fails (e.g. the connection is dropped or the
server doesn't exist), an error with class \code{"httr2_failure"}.
}
}
\description{
After preparing a \link{request}, call \code{req_perform()} to perform it, fetching
the results back to R as a \link{response}.
The default HTTP method is \code{GET} unless a body (set by \link{req_body_json} and
friends) is present, in which case it will be \code{POST}. You can override
these defaults with \code{\link[=req_method]{req_method()}}.
}
\section{Requests}{
Note that one call to \code{req_perform()} may perform multiple HTTP requests:
\itemize{
\item If the \code{url} is redirected with a 301, 302, 303, or 307, curl will
automatically follow the \code{Location} header to the new location.
\item If you have configured retries with \code{\link[=req_retry]{req_retry()}} and the request
fails with a transient problem, \code{req_perform()} will try again after
waiting a bit. See \code{\link[=req_retry]{req_retry()}} for details.
\item If you are using OAuth, and the cached token has expired, \code{req_perform()}
will get a new token either using the refresh token (if available)
or by running the OAuth flow.
}
}
\section{Progress bar}{
\code{req_perform()} will automatically add a progress bar if it needs to wait
between requests for \code{\link[=req_throttle]{req_throttle()}} or \code{\link[=req_retry]{req_retry()}}. You can turn the
progress bar off (and just show the total time to wait) by setting
\code{options(httr2_progress = FALSE)}.
}
\examples{
request("https://google.com") |>
req_perform()
}
\seealso{
\code{\link[=req_perform_parallel]{req_perform_parallel()}} to perform multiple requests in parallel.
\code{\link[=req_perform_iterative]{req_perform_iterative()}} to perform multiple requests iteratively.
}
httr2/man/req_throttle.Rd 0000644 0001762 0000144 00000002135 14514566210 015100 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-throttle.R
\name{req_throttle}
\alias{req_throttle}
\title{Rate limit a request by automatically adding a delay}
\usage{
req_throttle(req, rate, realm = NULL)
}
\arguments{
\item{req}{A \link{request}.}
\item{rate}{Maximum rate, i.e. maximum number of requests per second.
Usually easiest expressed as a fraction,
\code{number_of_requests / number_of_seconds}, e.g. 15 requests per minute
is \code{15 / 60}.}
\item{realm}{An unique identifier that for throttle pool. If not supplied,
defaults to the hostname of the request.}
}
\value{
A modified HTTP \link{request}.
}
\description{
Use \code{req_throttle()} to ensure that repeated calls to \code{\link[=req_perform]{req_perform()}} never
exceed a specified rate.
}
\examples{
# Ensure we never send more than 30 requests a minute
req <- request(example_url()) |>
req_throttle(rate = 30 / 60)
resp <- req_perform(req)
throttle_status()
resp <- req_perform(req)
throttle_status()
}
\seealso{
\code{\link[=req_retry]{req_retry()}} for another way of handling rate-limited APIs.
}
httr2/man/req_options.Rd 0000644 0001762 0000144 00000002061 14514566210 014724 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-options.R
\name{req_options}
\alias{req_options}
\title{Set arbitrary curl options in request}
\usage{
req_options(.req, ...)
}
\arguments{
\item{.req}{A \link{request}.}
\item{...}{<\code{\link[rlang:dyn-dots]{dynamic-dots}}> Name-value pairs. The name
should be a valid curl option, as found in \code{\link[curl:curl_options]{curl::curl_options()}}.}
}
\value{
A modified HTTP \link{request}.
}
\description{
\code{req_options()} is for expert use only; it allows you to directly set
libcurl options to access features that are otherwise not available in
httr2.
}
\examples{
# req_options() allows you to access curl options that are not otherwise
# exposed by httr2. For example, in very special cases you may need to
# turn off SSL verification. This is generally a bad idea so httr2 doesn't
# provide a convenient wrapper, but if you really know what you're doing
# you can still access this libcurl option:
req <- request("https://example.com") |>
req_options(ssl_verifypeer = 0)
}
httr2/man/oauth_cache_path.Rd 0000644 0001762 0000144 00000000650 14475517553 015657 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oauth.R
\name{oauth_cache_path}
\alias{oauth_cache_path}
\title{httr2 OAuth cache location}
\usage{
oauth_cache_path()
}
\description{
When opted-in to, httr2 caches OAuth tokens in this directory. By default,
it uses a OS-standard cache directory, but, if needed, you can override the
location by setting the \code{HTTR2_OAUTH_CACHE} env var.
}
httr2/man/throttle_status.Rd 0000644 0001762 0000144 00000000571 14427520571 015641 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-throttle.R
\name{throttle_status}
\alias{throttle_status}
\title{Display internal throttle status}
\usage{
throttle_status()
}
\value{
A data frame with two columns: the \code{realm} and time the
\code{last_request} was made.
}
\description{
Sometimes useful for debugging.
}
\keyword{internal}
httr2/man/req_oauth_client_credentials.Rd 0000644 0001762 0000144 00000003147 14514566210 020272 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oauth-flow-client-credentials.R
\name{req_oauth_client_credentials}
\alias{req_oauth_client_credentials}
\alias{oauth_flow_client_credentials}
\title{OAuth with client credentials}
\usage{
req_oauth_client_credentials(req, client, scope = NULL, token_params = list())
oauth_flow_client_credentials(client, scope = NULL, token_params = list())
}
\arguments{
\item{req}{A \link{request}.}
\item{client}{An \code{\link[=oauth_client]{oauth_client()}}.}
\item{scope}{Scopes to be requested from the resource owner.}
\item{token_params}{List containing additional parameters passed to the
\code{token_url}.}
}
\value{
\code{req_oauth_client_credentials()} returns a modified HTTP \link{request} that will
use OAuth; \code{oauth_flow_client_credentials()} returns an \link{oauth_token}.
}
\description{
Authenticate using OAuth \strong{client credentials flow}, as defined by
\href{https://datatracker.ietf.org/doc/html/rfc6749#section-4.4}{Section 4.4 of RFC 6749}. It is used to allow the client to access resources that
it controls directly, not on behalf of an user.
Learn more about the overall OAuth authentication flow in \code{vignette("oauth")}.
}
\examples{
req_auth <- function(req) {
req_oauth_client_credentials(
req,
client = oauth_client("example", "https://example.com/get_token")
)
}
request("https://example.com") |>
req_auth()
}
\seealso{
Other OAuth flows:
\code{\link{req_oauth_auth_code}()},
\code{\link{req_oauth_bearer_jwt}()},
\code{\link{req_oauth_password}()},
\code{\link{req_oauth_refresh}()}
}
\concept{OAuth flows}
httr2/man/oauth_redirect_uri.Rd 0000644 0001762 0000144 00000000652 14513321046 016241 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oauth-flow-auth-code.R
\name{oauth_redirect_uri}
\alias{oauth_redirect_uri}
\title{Default redirect url for OAuth}
\usage{
oauth_redirect_uri()
}
\description{
The default redirect uri used by \code{\link[=req_oauth_auth_code]{req_oauth_auth_code()}}. Defaults to
\verb{http://localhost} unless the \code{HTTR2_OAUTH_REDIRECT_URL} envvar is set.
}
httr2/man/resp_status.Rd 0000644 0001762 0000144 00000004413 14514566210 014741 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/resp-status.R
\name{resp_status}
\alias{resp_status}
\alias{resp_status_desc}
\alias{resp_is_error}
\alias{resp_check_status}
\title{Extract HTTP status from response}
\usage{
resp_status(resp)
resp_status_desc(resp)
resp_is_error(resp)
resp_check_status(resp, info = NULL, error_call = caller_env())
}
\arguments{
\item{resp}{An HTTP response object, as created by \code{\link[=req_perform]{req_perform()}}.}
\item{info}{A character vector of additional information to include in
the error message. Passed to \code{\link[rlang:abort]{rlang::abort()}}.}
\item{error_call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[rlang:abort]{abort()}} for more information.}
}
\value{
\itemize{
\item \code{resp_status()} returns a scalar integer
\item \code{resp_status_desc()} returns a string
\item \code{resp_is_error()} returns \code{TRUE} or \code{FALSE}
\item \code{resp_check_status()} invisibly returns the response if it's ok;
otherwise it throws an error with class \verb{httr2_http_\{status\}}.
}
}
\description{
\itemize{
\item \code{resp_status()} retrieves the numeric HTTP status code
\item \code{resp_status_desc()} retrieves the brief textual description.
\item \code{resp_is_error()} returns \code{TRUE} if the status code represents an error
(i.e. a 4xx or 5xx status).
\item \code{resp_check_status()} turns HTTPs errors into R errors.
}
These functions are mostly for internal use because in most cases you
will only ever see a 200 response:
\itemize{
\item 1xx are handled internally by curl.
\item 3xx redirects are automatically followed. You will only see them if you
have deliberately suppressed redirects with
\code{req |> req_options(followlocation = FALSE)}.
\item 4xx client and 5xx server errors are automatically turned into R errors.
You can stop them from being turned into R errors with \code{\link[=req_error]{req_error()}},
e.g. \code{req |> req_error(is_error = ~ FALSE)}.
}
}
\examples{
# An HTTP status code you're unlikely to see in the wild:
resp <- response(418)
resp |> resp_is_error()
resp |> resp_status()
resp |> resp_status_desc()
}
httr2/man/example_url.Rd 0000644 0001762 0000144 00000001233 14511623677 014707 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test.R
\name{example_url}
\alias{example_url}
\alias{example_github_client}
\title{Code for examples}
\usage{
example_url()
example_github_client()
}
\description{
\code{example_url()} runs a simple websever using the webfakes package with the
following endpoints:
\itemize{
\item all the ones from the \code{\link[webfakes:httpbin_app]{webfakes::httpbin_app()}}
\item \verb{/iris}: paginate through the iris dataset. It has the query parameters
\code{page} and \code{limit} to control the pagination.
}
\code{example_github_client()} is an OAuth client for GitHub.
}
\keyword{internal}
httr2/man/req_proxy.Rd 0000644 0001762 0000144 00000001374 14514566210 014420 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-options.R
\name{req_proxy}
\alias{req_proxy}
\title{Use a proxy for a request}
\usage{
req_proxy(
req,
url,
port = NULL,
username = NULL,
password = NULL,
auth = "basic"
)
}
\arguments{
\item{req}{A \link{request}.}
\item{url, port}{Location of proxy.}
\item{username, password}{Login details for proxy, if needed.}
\item{auth}{Type of HTTP authentication to use. Should be one of the
following: \code{basic}, digest, digest_ie, gssnegotiate, ntlm, any.}
}
\description{
Use a proxy for a request
}
\examples{
# Proxy from https://www.proxynova.com/proxy-server-list/
\dontrun{
request("http://hadley.nz") |>
req_proxy("20.116.130.70", 3128) |>
req_perform()
}
}
httr2/man/with_mocked_responses.Rd 0000644 0001762 0000144 00000002754 14514566210 016771 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-mock.R
\name{with_mocked_responses}
\alias{with_mocked_responses}
\alias{with_mock}
\alias{local_mocked_responses}
\alias{local_mock}
\title{Temporarily mock requests}
\usage{
with_mocked_responses(mock, code)
local_mocked_responses(mock, env = caller_env())
}
\arguments{
\item{mock}{A function, a list, or \code{NULL}.
\itemize{
\item \code{NULL} disables mocking and returns httr2 to regular operation.
\item A list of responses will be returned in sequence. After all responses
have been used up, will return 503 server errors.
\item For maximum flexibility, you can supply a function that that takes a
single argument, \code{req}, and returns either \code{NULL} (if it doesn't want to
handle the request) or a \link{response} (if it does).
}}
\item{code}{Code to execute in the temporary environment.}
\item{env}{Environment to use for scoping changes.}
}
\value{
\code{with_mock()} returns the result of evaluating \code{code}.
}
\description{
Mocking allows you to selectively and temporarily replace the response
you would typically receive from a request with your own code. It's
primarily used for testing.
}
\examples{
# This function should perform a response against google.com:
google <- function() {
request("http://google.com") |>
req_perform()
}
# But I can use a mock to instead return my own made up response:
my_mock <- function(req) {
response(status_code = 403)
}
try(with_mock(my_mock, google()))
}
httr2/man/req_method.Rd 0000644 0001762 0000144 00000001311 14514566210 014506 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-method.R
\name{req_method}
\alias{req_method}
\title{Set HTTP method in request}
\usage{
req_method(req, method)
}
\arguments{
\item{req}{A \link{request}.}
\item{method}{Custom HTTP method}
}
\value{
A modified HTTP \link{request}.
}
\description{
Use this function to use a custom HTTP method like \code{HEAD},
\code{DELETE}, \code{PATCH}, \code{UPDATE}, or \code{OPTIONS}. The default method is
\code{GET} for requests without a body, and \code{POST} for requests with a body.
}
\examples{
request(example_url()) |> req_method("PATCH")
request(example_url()) |> req_method("PUT")
request(example_url()) |> req_method("HEAD")
}
httr2/man/resps_successes.Rd 0000644 0001762 0000144 00000003443 14523472232 015603 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/iterate-responses.R
\name{resps_successes}
\alias{resps_successes}
\alias{resps_failures}
\alias{resps_requests}
\alias{resps_data}
\title{Tools for working with lists of responses}
\usage{
resps_successes(resps)
resps_failures(resps)
resps_requests(resps)
resps_data(resps, resp_data)
}
\arguments{
\item{resps}{A list of responses (possibly including errors).}
\item{resp_data}{A function that takes a response (\code{resp}) and
returns the data foind inside that response as a vector or data frame.}
}
\description{
These function provide a basic toolkit for operating with lists of
responses and possibly errors, as returned by \code{\link[=req_perform_parallel]{req_perform_parallel()}},
\code{\link[=req_perform_sequential]{req_perform_sequential()}} and \code{\link[=req_perform_iterative]{req_perform_iterative()}}.
\itemize{
\item \code{resps_successes()} returns a list successful responses.
\item \code{resps_failures()} returns a list failed responses (i.e. errors).
\item \code{resps_requests()} returns the list of requests that corresponds to
each request.
\item \code{resps_data()} returns all the data in a single vector or data frame.
It requires the vctrs package to be installed.
}
}
\examples{
reqs <- list(
request(example_url()) |> req_url_path("/ip"),
request(example_url()) |> req_url_path("/user-agent"),
request(example_url()) |> req_template("/status/:status", status = 404),
request("INVALID")
)
resps <- req_perform_parallel(reqs, on_error = "continue")
# find successful responses
resps |> resps_successes()
# collect all their data
resps |> resps_successes() |> resps_data(\(resp) resp_body_json(resp))
# find requests corresponding to failure responses
resps |> resps_failures() |> resps_requests()
}
httr2/man/oauth_token_cached.Rd 0000644 0001762 0000144 00000003112 14514574463 016200 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oauth.R
\name{oauth_token_cached}
\alias{oauth_token_cached}
\title{Retrieve an OAuth token using the cache}
\usage{
oauth_token_cached(
client,
flow,
flow_params = list(),
cache_disk = FALSE,
cache_key = NULL,
reauth = FALSE
)
}
\arguments{
\item{client}{An \code{\link[=oauth_client]{oauth_client()}}.}
\item{flow}{An \code{oauth_flow_} function used to generate the access token.}
\item{flow_params}{Parameters for the flow. This should be a named list
whose names match the argument names of \code{flow}.}
\item{cache_disk}{Should the access token be cached on disk? This reduces
the number of times that you need to re-authenticate at the cost of
storing access credentials on disk.
Learn more in \code{vignette("oauth")}}
\item{cache_key}{If you want to cache multiple tokens per app, use this
key to disambiguate them.}
\item{reauth}{Set to \code{TRUE} to force re-authentication via flow, regardless
of whether or not token is expired.}
}
\description{
This function wraps around a \code{oauth_flow_} function to retrieve a token
from the cache, or to generate and cache a token if needed. Use this for
manual token management that still takes advantage of httr2's caching
system. You should only need to use this function if you're passing
the token
}
\examples{
\dontrun{
token <- oauth_token_cached(
client = example_github_client(),
flow = oauth_flow_auth_code,
flow_params = list(
auth_url = "https://github.com/login/oauth/authorize"
),
cache_disk = TRUE
)
token
}
}
\keyword{internal}
httr2/man/req_body.Rd 0000644 0001762 0000144 00000007407 14523511035 014172 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-body.R
\name{req_body}
\alias{req_body_raw}
\alias{req_body_file}
\alias{req_body_json}
\alias{req_body_json_modify}
\alias{req_body_form}
\alias{req_body_multipart}
\title{Send data in request body}
\usage{
req_body_raw(req, body, type = NULL)
req_body_file(req, path, type = NULL)
req_body_json(
req,
data,
auto_unbox = TRUE,
digits = 22,
null = "null",
type = "application/json",
...
)
req_body_json_modify(req, ...)
req_body_form(.req, ..., .multi = c("error", "comma", "pipe", "explode"))
req_body_multipart(.req, ...)
}
\arguments{
\item{req, .req}{A \link{request}.}
\item{body}{A literal string or raw vector to send as body.}
\item{type}{MIME content type. You shouldn't generally need to specify this as
the defaults are usually pretty good, e.g. \code{req_body_file()} will guess it
from the extension of of \code{path}. Will be ignored if you have manually set
a \code{Content-Type} header.}
\item{path}{Path to file to upload.}
\item{data}{Data to include in body.}
\item{auto_unbox}{Should length-1 vectors be automatically "unboxed" to
JSON scalars?}
\item{digits}{How many digits of precision should numbers use in JSON?}
\item{null}{Should \code{NULL} be translated to JSON's null (\code{"null"})
or an empty list (\code{"list"}).}
\item{...}{<\code{\link[rlang:dyn-dots]{dynamic-dots}}> Name-data pairs used to send
data in the body.
\itemize{
\item For \code{req_body_form()}, the values must be strings (or things easily
coerced to strings);
\item For \code{req_body_multipart()} the values must be strings or objects
produced by \code{\link[curl:multipart]{curl::form_file()}}/\code{\link[curl:multipart]{curl::form_data()}}.
\item For \code{req_body_json_modify()}, any simple data made from atomic vectors
and lists.
}
\code{req_body_json()} uses this argument differently; it takes additional
arguments passed on to \code{\link[jsonlite:fromJSON]{jsonlite::toJSON()}}.}
\item{.multi}{Controls what happens when an element of \code{...} is a vector
containing multiple values:
\itemize{
\item \code{"error"}, the default, throws an error.
\item \code{"comma"}, separates values with a \verb{,}, e.g. \verb{?x=1,2}.
\item \code{"pipe"}, separates values with a \code{|}, e.g. \code{?x=1|2}.
\item \code{"explode"}, turns each element into its own parameter, e.g. \code{?x=1&x=2}.
}
If none of these functions work, you can alternatively supply a function
that takes a character vector and returns a string.}
}
\value{
A modified HTTP \link{request}.
}
\description{
\itemize{
\item \code{req_body_file()} sends a local file.
\item \code{req_body_raw()} sends a string or raw vector.
\item \code{req_body_json()} sends JSON encoded data. Named components of this data
can later be modified with \code{req_body_json_modify()}.
\item \code{req_body_form()} sends form encoded data.
\item \code{req_body_multipart()} creates a multi-part body.
}
Adding a body to a request will automatically switch the method to POST.
}
\examples{
req <- request(example_url()) |>
req_url_path("/post")
# Most APIs expect small amounts of data in either form or json encoded:
req |>
req_body_form(x = "A simple text string") |>
req_dry_run()
req |>
req_body_json(list(x = "A simple text string")) |>
req_dry_run()
# For total control over the body, send a string or raw vector
req |>
req_body_raw("A simple text string") |>
req_dry_run()
# There are two main ways that APIs expect entire files
path <- tempfile()
writeLines(letters[1:6], path)
# You can send a single file as the body:
req |>
req_body_file(path) |>
req_dry_run()
# You can send multiple files, or a mix of files and data
# with multipart encoding
req |>
req_body_multipart(a = curl::form_file(path), b = "some data") |>
req_dry_run()
}
httr2/man/jwt_claim.Rd 0000644 0001762 0000144 00000004640 14475517553 014354 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/jwt.R
\name{jwt_claim}
\alias{jwt_claim}
\alias{jwt_encode_sig}
\alias{jwt_encode_hmac}
\title{Create and encode a JWT}
\usage{
jwt_claim(
iss = NULL,
sub = NULL,
aud = NULL,
exp = unix_time() + 5L * 60L,
nbf = unix_time(),
iat = unix_time(),
jti = NULL,
...
)
jwt_encode_sig(claim, key, size = 256, header = list())
jwt_encode_hmac(claim, secret, size = size, header = list())
}
\arguments{
\item{iss}{Issuer claim. Identifies the principal that issued the JWT.}
\item{sub}{Subject claim. Identifies the principal that is the subject of
the JWT (i.e. the entity that the claims apply to).}
\item{aud}{Audience claim. Identifies the recipients that the JWT is
intended. Each principle intended to process the JWT must be identified
with a unique value.}
\item{exp}{Expiration claim. Identifies the expiration time on or after which
the JWT MUST NOT be accepted for processing. Defaults to 5 minutes.}
\item{nbf}{Not before claim. Identifies the time before which the JWT
MUST NOT be accepted for processing. Defaults to current time.}
\item{iat}{Issued at claim. Identifies the time at which the JWT was
issued. Defaults to current time.}
\item{jti}{JWT ID claim. Provides a unique identifier for the JWT.
If omitted, uses a random 32-byte sequence encoded with base64url.}
\item{...}{Any additional claims to include in the claim set.}
\item{claim}{Claim set produced by \code{\link[=jwt_claim]{jwt_claim()}}.}
\item{key}{RSA or EC private key either specified as a path to a file,
a connection, or a string (PEM/SSH format), or a raw vector (DER format).}
\item{size}{Size, in bits, of sha2 signature, i.e. 256, 384 or 512.
Only for HMAC/RSA, not applicable for ECDSA keys.}
\item{header}{A named list giving additional fields to include in the
JWT header.}
\item{secret}{String or raw vector with a secret passphrase.}
}
\value{
An S3 list with class \code{jwt_claim}.
}
\description{
\code{jwt_claim()} is a wrapper around \code{\link[jose:jwt_claim]{jose::jwt_claim()}} that creates a JWT
claim set with a few extra default values. \code{jwt_encode_sig()} and
\code{jwt_encode_hmac()} are thin wrappers around \code{\link[jose:jwt_encode]{jose::jwt_encode_sig()}} and
\code{\link[jose:jwt_encode]{jose::jwt_encode_hmac()}} that exist primarily to make specification
in other functions a little simpler.
}
\examples{
claim <- jwt_claim()
str(claim)
}
httr2/man/req_perform_parallel.Rd 0000644 0001762 0000144 00000007115 14524445373 016573 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/multi-req.R
\name{req_perform_parallel}
\alias{req_perform_parallel}
\title{Perform a list of requests in parallel}
\usage{
req_perform_parallel(
reqs,
paths = NULL,
pool = NULL,
on_error = c("stop", "return", "continue"),
progress = TRUE
)
}
\arguments{
\item{reqs}{A list of \link{request}s.}
\item{paths}{An optional list of paths, if you want to download the request
bodies to disks. If supplied, must be the same length as \code{reqs}.}
\item{pool}{Optionally, a curl pool made by \code{\link[curl:multi]{curl::new_pool()}}. Supply
this if you want to override the defaults for total concurrent connections
(100) or concurrent connections per host (6).}
\item{on_error}{What should happen if one of the requests fails?
\itemize{
\item \code{stop}, the default: stop iterating with an error.
\item \code{return}: stop iterating, returning all the successful responses
received so far, as well as an error object for the failed request.
\item \code{continue}: continue iterating, recording errors in the result.
}}
\item{progress}{Display a progress bar? Use \code{TRUE} to turn on a basic
progress bar, use a string to give it a name, or see \link{progress_bars} to
customise it in other ways.}
}
\value{
A list, the same length as \code{reqs}, containing \link{response}s and possibly
error objects, if \code{on_error} is \code{"return"} or \code{"continue"} and one of the
responses errors. If \code{on_error} is \code{"return"} and it errors on the ith
request, the ith element of the result will be an error object, and the
remaining elements will be \code{NULL}. If \code{on_error} is \code{"continue"}, it will
be a mix of requests and error objects.
Only httr2 errors are captured; see \code{\link[=req_error]{req_error()}} for more details.
}
\description{
This variation on \code{\link[=req_perform_sequential]{req_perform_sequential()}} performs multiple requests in
parallel. Exercise caution when using this function; it's easy to pummel a
server with many simultaneous requests. Only use it with hosts designed to
serve many files at once, which are typically web servers, not API servers.
\code{req_perform_parallel()} has a few limitations:
\itemize{
\item Will not retrieve a new OAuth token if it expires part way through
the requests.
\item Does not perform throttling with \code{\link[=req_throttle]{req_throttle()}}.
\item Does not attempt retries as described by \code{\link[=req_retry]{req_retry()}}.
\item Only consults the cache set by \code{\link[=req_cache]{req_cache()}} before/after all requests.
}
If any of these limitations are problematic for your use case, we recommend
\code{\link[=req_perform_sequential]{req_perform_sequential()}} instead.
}
\examples{
# Requesting these 4 pages one at a time would take 2 seconds:
request_base <- request(example_url())
reqs <- list(
request_base |> req_url_path("/delay/0.5"),
request_base |> req_url_path("/delay/0.5"),
request_base |> req_url_path("/delay/0.5"),
request_base |> req_url_path("/delay/0.5")
)
# But it's much faster if you request in parallel
system.time(resps <- req_perform_parallel(reqs))
# req_perform_parallel() will fail on error
reqs <- list(
request_base |> req_url_path("/status/200"),
request_base |> req_url_path("/status/400"),
request("FAILURE")
)
try(resps <- req_perform_parallel(reqs))
# but can use on_error to capture all successful results
resps <- req_perform_parallel(reqs, on_error = "continue")
# Inspect the successful responses
resps |> resps_successes()
# And the failed responses
resps |> resps_failures() |> resps_requests()
}
httr2/man/signal_total_pages.Rd 0000644 0001762 0000144 00000000651 14520200264 016213 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/iterate-helpers.R
\name{signal_total_pages}
\alias{signal_total_pages}
\title{Signal total number pages}
\usage{
signal_total_pages(n)
}
\arguments{
\item{n}{Total number of pages.}
}
\description{
To be called within a \code{next_req} callback function used with
\code{\link[=req_perform_iterative]{req_perform_iterative()}}
}
\keyword{internal}
httr2/man/last_response.Rd 0000644 0001762 0000144 00000001242 14514566210 015243 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-perform.R
\name{last_response}
\alias{last_response}
\alias{last_request}
\title{Retrieve most recent request/response}
\usage{
last_response()
last_request()
}
\value{
An HTTP \link{response}/\link{request}.
}
\description{
These functions retrieve the most recent request made by httr2 and
the response it received, to facilitate debugging problems \emph{after} they
occur. If the request did not succeed (or no requests have been made)
\code{last_response()} will be \code{NULL}.
}
\examples{
invisible(request("http://httr2.r-lib.org") |> req_perform())
last_request()
last_response()
}
httr2/man/req_auth_bearer_token.Rd 0000644 0001762 0000144 00000002066 14523473134 016721 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-auth.R
\name{req_auth_bearer_token}
\alias{req_auth_bearer_token}
\title{Authenticate request with bearer token}
\usage{
req_auth_bearer_token(req, token)
}
\arguments{
\item{req}{A \link{request}.}
\item{token}{A bearer token}
}
\value{
A modified HTTP \link{request}.
}
\description{
A bearer token gives the bearer access to confidential resources
(so you should keep them secure like you would with a user name and
password). They are usually produced by some large authentication scheme
(like the various OAuth 2.0 flows), but you are sometimes given then
directly.
}
\examples{
req <- request("http://example.com") |> req_auth_bearer_token("sdaljsdf093lkfs")
req
# httr2 does its best to redact the Authorization header so that you don't
# accidentally reveal confidential data. Use `redact_headers` to reveal it:
print(req, redact_headers = FALSE)
}
\seealso{
See \href{https://datatracker.ietf.org/doc/html/rfc6750}{RFC 6750} for more details about bearer token usage
with OAuth 2.0.
}
httr2/man/iterate_with_offset.Rd 0000644 0001762 0000144 00000005421 14524445373 016432 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/iterate-helpers.R
\name{iterate_with_offset}
\alias{iterate_with_offset}
\alias{iterate_with_cursor}
\alias{iterate_with_link_url}
\title{Iteration helpers}
\usage{
iterate_with_offset(
param_name,
start = 1,
offset = 1,
resp_pages = NULL,
resp_complete = NULL
)
iterate_with_cursor(param_name, resp_param_value)
iterate_with_link_url(rel = "next")
}
\arguments{
\item{param_name}{Name of query parameter.}
\item{start}{Starting value.}
\item{offset}{Offset for each page. The default is set to \code{1} so you get
(e.g.) \code{?page=1}, \code{?page=2}, ... If \code{param_name} refers to an element
index (rather than a page index) you'll want to set this to a larger number
so you get (e.g.) \code{?items=20}, \code{?items=40}, ...}
\item{resp_pages}{A callback function that takes a response (\code{resp}) and
returns the total number of pages, or \code{NULL} if unknown. It will only
be called once.}
\item{resp_complete}{A callback function that takes a response (\code{resp})
and returns \code{TRUE} if there are no further pages.}
\item{resp_param_value}{A callback function that takes a response (\code{resp})
and returns the next cursor value. Return \code{NULL} if there are no further
pages.}
\item{rel}{The "link relation type" to use to retrieve the next page.}
}
\description{
These functions are intended for use with the \code{next_req} argument to
\code{\link[=req_perform_iterative]{req_perform_iterative()}}. Each implements iteration for a common
pagination pattern:
\itemize{
\item \code{iterate_with_offset()} increments a query parameter, e.g. \code{?page=1},
\code{?page=2}, or \code{?offset=1}, \code{offset=21}.
\item \code{iterate_with_cursor()} updates a query parameter with the value of a
cursor found somewhere in the response.
\item \code{iterate_with_link_url()} follows the url found in the \code{Link} header.
See \code{resp_link_url()} for more details.
}
}
\examples{
req <- request(example_url()) |>
req_url_path("/iris") |>
req_throttle(10) |>
req_url_query(limit = 50)
# If you don't know the total number of pages in advance, you can
# provide a `resp_complete()` callback
is_complete <- function(resp) {
length(resp_body_json(resp)$data) == 0
}
resps <- req_perform_iterative(
req,
next_req = iterate_with_offset("page_index", resp_complete = is_complete),
max_reqs = Inf
)
\dontrun{
# Alternatively, if the response returns the total number of pages (or you
# can easily calculate it), you can use the `resp_pages()` callback which
# will generate a better progress bar.
resps <- req_perform_iterative(
req |> req_url_query(limit = 1),
next_req = iterate_with_offset(
"page_index",
resp_pages = function(resp) resp_body_json(resp)$pages
),
max_reqs = Inf
)
}
}
httr2/man/req_dry_run.Rd 0000644 0001762 0000144 00000002515 14514566210 014717 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-perform.R
\name{req_dry_run}
\alias{req_dry_run}
\title{Perform a dry run}
\usage{
req_dry_run(req, quiet = FALSE, redact_headers = TRUE)
}
\arguments{
\item{req}{A \link{request}.}
\item{quiet}{If \code{TRUE} doesn't print anything.}
\item{redact_headers}{Redact confidential data in the headers? Currently
redacts the contents of the Authorization header to prevent you from
accidentally leaking credentials when debugging/reprexing.}
}
\value{
Invisibly, a list containing information about the request,
including \code{method}, \code{path}, and \code{headers}.
}
\description{
This shows you exactly what httr2 will send to the server, without
actually sending anything. It requires the httpuv package because it
works by sending the real HTTP request to a local webserver, thanks to
the magic of \code{\link[curl:curl_echo]{curl::curl_echo()}}.
}
\examples{
# httr2 adds default User-Agent, Accept, and Accept-Encoding headers
request("http://example.com") |> req_dry_run()
# the Authorization header is automatically redacted to avoid leaking
# credentials on the console
req <- request("http://example.com") |> req_auth_basic("user", "password")
req |> req_dry_run()
# if you need to see it, use redact_headers = FALSE
req |> req_dry_run(redact_headers = FALSE)
}
httr2/man/with_verbosity.Rd 0000644 0001762 0000144 00000001766 14514566210 015456 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils.R
\name{with_verbosity}
\alias{with_verbosity}
\title{Temporarily set verbosity for all requests}
\usage{
with_verbosity(code, verbosity = 1)
}
\arguments{
\item{code}{Code to execture}
\item{verbosity}{How much information to print? This is a wrapper
around \code{req_verbose()} that uses an integer to control verbosity:
\itemize{
\item 0: no output
\item 1: show headers
\item 2: show headers and bodies
\item 3: show headers, bodies, and curl status messages.
}
Use \code{\link[=with_verbosity]{with_verbosity()}} to control the verbosity of requests that
you can't affect directly.}
}
\value{
The result of evaluating \code{code}.
}
\description{
\code{with_verbosity()} is useful for debugging httr2 code buried deep inside
another package because it allows you to see exactly what's been sent
and requested.
}
\examples{
fun <- function() {
request("https://httr2.r-lib.org") |> req_perform()
}
with_verbosity(fun())
}
httr2/man/req_cookie_preserve.Rd 0000644 0001762 0000144 00000002105 14520446372 016417 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-cookies.R
\name{req_cookie_preserve}
\alias{req_cookie_preserve}
\title{Preserve cookies across requests}
\usage{
req_cookie_preserve(req, path)
}
\arguments{
\item{req}{A \link{request}.}
\item{path}{A path to a file where cookies will be read from before and updated after the request.}
}
\description{
By default, httr2 uses a clean slate for every request meaning that cookies
are not automatically preserved across requests. To preserve cookies, you
must set a cookie file which will be read before and updated after each
request.
}
\examples{
path <- tempfile()
httpbin <- request(example_url()) |>
req_cookie_preserve(path)
# Manually set two cookies
httpbin |>
req_template("/cookies/set/:name/:value", name = "chocolate", value = "chip") |>
req_perform() |>
resp_body_json()
httpbin |>
req_template("/cookies/set/:name/:value", name = "oatmeal", value = "raisin") |>
req_perform() |>
resp_body_json()
# The cookie path has a straightforward format
cat(readChar(path, nchars = 1e4))
}
httr2/man/req_oauth_refresh.Rd 0000644 0001762 0000144 00000004557 14514566210 016103 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oauth-flow-refresh.R
\name{req_oauth_refresh}
\alias{req_oauth_refresh}
\alias{oauth_flow_refresh}
\title{OAuth with a refresh token}
\usage{
req_oauth_refresh(
req,
client,
refresh_token = Sys.getenv("HTTR2_REFRESH_TOKEN"),
scope = NULL,
token_params = list()
)
oauth_flow_refresh(
client,
refresh_token = Sys.getenv("HTTR2_REFRESH_TOKEN"),
scope = NULL,
token_params = list()
)
}
\arguments{
\item{req}{A \link{request}.}
\item{client}{An \code{\link[=oauth_client]{oauth_client()}}.}
\item{refresh_token}{A refresh token. This is equivalent to a password
so shouldn't be typed into the console or stored in a script. Instead,
we recommend placing in an environment variable; the default behaviour
is to look in \code{HTTR2_REFRESH_TOKEN}.}
\item{scope}{Scopes to be requested from the resource owner.}
\item{token_params}{List containing additional parameters passed to the
\code{token_url}.}
}
\value{
\code{req_oauth_refresh()} returns a modified HTTP \link{request} that will
use OAuth; \code{oauth_flow_refresh()} returns an \link{oauth_token}.
}
\description{
Authenticate using a \strong{refresh token}, following the process described in
\href{https://datatracker.ietf.org/doc/html/rfc6749#section-6}{Section 6 of RFC 6749}.
This technique is primarily useful for testing: you can manually retrieve
a OAuth token using another OAuth flow (e.g. with \code{\link[=oauth_flow_auth_code]{oauth_flow_auth_code()}}),
extract the refresh token from the result, and then save in an environment
variable for use in automated tests.
When requesting an access token, the server may also return a new refresh
token. If this happens, \code{oauth_flow_refresh()} will warn, and you'll have
retrieve a new update refresh token and update the stored value. If you find
this happening a lot, it's a sign that you should be using a different flow
in your automated tests.
Learn more about the overall OAuth authentication flow in \code{vignette("oauth")}.
}
\examples{
client <- oauth_client("example", "https://example.com/get_token")
req <- request("https://example.com")
req |> req_oauth_refresh(client)
}
\seealso{
Other OAuth flows:
\code{\link{req_oauth_auth_code}()},
\code{\link{req_oauth_bearer_jwt}()},
\code{\link{req_oauth_client_credentials}()},
\code{\link{req_oauth_password}()}
}
\concept{OAuth flows}
httr2/man/multi_req_perform.Rd 0000644 0001762 0000144 00000002535 14524437112 016122 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/multi-req.R
\name{multi_req_perform}
\alias{multi_req_perform}
\title{Perform a list of requests in parallel}
\usage{
multi_req_perform(reqs, paths = NULL, pool = NULL, cancel_on_error = FALSE)
}
\arguments{
\item{reqs}{A list of \link{request}s.}
\item{paths}{An optional list of paths, if you want to download the request
bodies to disks. If supplied, must be the same length as \code{reqs}.}
\item{pool}{Optionally, a curl pool made by \code{\link[curl:multi]{curl::new_pool()}}. Supply
this if you want to override the defaults for total concurrent connections
(100) or concurrent connections per host (6).}
\item{cancel_on_error}{Should all pending requests be cancelled when you
hit an error? Set this to \code{TRUE} to stop all requests as soon as you
hit an error. Responses that were never performed be \code{NULL} in the result.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
Please use \code{\link[=req_perform_parallel]{req_perform_parallel()}} instead, and note:
\itemize{
\item \code{cancel_on_error = FALSE} is now \code{on_error = "continue"}
\item \code{cancel_on_error = TRUE} is now \code{on_error = "return"}
}
}
\keyword{internal}
httr2/man/obfuscate.Rd 0000644 0001762 0000144 00000003024 14427520571 014340 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/secret.R
\name{obfuscate}
\alias{obfuscate}
\alias{obfuscated}
\title{Obfuscate mildly secret information}
\usage{
obfuscate(x)
obfuscated(x)
}
\arguments{
\item{x}{A string to \code{obfuscate}, or mark as \code{obfuscated}.}
}
\value{
\code{obfuscate()} prints the \code{obfuscated()} call to include in your
code. \code{obfuscated()} returns an S3 class marking the string as obfuscated
so it can be unobfuscated when needed.
}
\description{
Use \code{obfuscate("value")} to generate a call to \code{obfuscated()}, which will
unobfuscate the value at the last possible moment. Obfuscated values only
work in limited locations:
\itemize{
\item The \code{secret} argument to \code{\link[=oauth_client]{oauth_client()}}
\item Elements of the \code{data} argument to \code{\link[=req_body_form]{req_body_form()}}, \code{req_body_json()},
and \code{req_body_multipart()}.
}
Working together this pair of functions provides a way to obfuscate mildly
confidential information, like OAuth client secrets. The secret can not be
revealed from your inspecting source code, but a skilled R programmer could
figure it out with some effort. The main goal is to protect against scraping;
there's no way for an automated tool to grab your obfuscated secrets.
}
\examples{
obfuscate("good morning")
# Every time you obfuscate you'll get a different value because it
# includes 16 bytes of random data which protects against certain types of
# brute force attack
obfuscate("good morning")
}
httr2/man/response.Rd 0000644 0001762 0000144 00000003116 14475517553 014236 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/resp.R
\name{response}
\alias{response}
\alias{response_json}
\title{Create a new HTTP response}
\usage{
response(
status_code = 200,
url = "https://example.com",
method = "GET",
headers = list(),
body = raw()
)
response_json(
status_code = 200,
url = "https://example.com",
method = "GET",
headers = list(),
body = list()
)
}
\arguments{
\item{status_code}{HTTP status code. Must be a single integer.}
\item{url}{URL response came from; might not be the same as the URL in
the request if there were any redirects.}
\item{method}{HTTP method used to retrieve the response.}
\item{headers}{HTTP headers. Can be supplied as a raw or character vector
which will be parsed using the standard rules, or a named list.}
\item{body}{Response, if any, contained in the response body.
For \code{response_json()}, a R data structure to serialize to JSON.}
}
\value{
An HTTP response: an S3 list with class \code{httr2_response}.
}
\description{
Generally, you should not need to call this function directly; you'll
get a real HTTP response by calling \code{\link[=req_perform]{req_perform()}} and friends. This
function is provided primarily for testing, and a place to describe
the key components of a response.
\code{response()} creates a generic response; \code{response_json()} creates a
response with a JSON body, automatically adding the correct Content-Type
header.
}
\examples{
response()
response(404, method = "POST")
response(headers = c("Content-Type: text/html", "Content-Length: 300"))
}
\keyword{internal}
httr2/man/req_error.Rd 0000644 0001762 0000144 00000007025 14523473134 014371 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-error.R
\name{req_error}
\alias{req_error}
\title{Control handling of HTTP errors}
\usage{
req_error(req, is_error = NULL, body = NULL)
}
\arguments{
\item{req}{A \link{request}.}
\item{is_error}{A predicate function that takes a single argument (the
response) and returns \code{TRUE} or \code{FALSE} indicating whether or not an
R error should signalled.}
\item{body}{A callback function that takes a single argument (the response)
and returns a character vector of additional information to include in the
body of the error. This vector is passed along to the \code{message} argument
of \code{\link[rlang:abort]{rlang::abort()}} so you can use any formatting that it supports.}
}
\value{
A modified HTTP \link{request}.
}
\description{
\code{req_perform()} will automatically convert HTTP errors (i.e. any 4xx or 5xx
status code) into R errors. Use \code{req_error()} to either override the
defaults, or extract additional information from the response that would
be useful to expose to the user.
}
\section{Error handling}{
\code{req_perform()} is designed to succeed if and only if you get a valid HTTP
response. There are two ways a request can fail:
\itemize{
\item The HTTP request might fail, for example if the connection is dropped
or the server doesn't exist. This type of error will have class
\code{c("httr2_failure", "httr2_error")}.
\item The HTTP request might succeed, but return an HTTP status code that
represents a error, e.g. a \verb{404 Not Found} if the specified resource is
not found. This type of error will have (e.g.) class
\code{c("httr2_http_404", "httr2_http", "httr2_error")}.
}
These error classes are designed to be used in conjunction with R's
condition handling tools (\url{https://adv-r.hadley.nz/conditions.html}).
For example, if you want to return a default value when the server returns
a 404, use \code{tryCatch()}:
\if{html}{\out{
}}
Learn more about error chaining at \link[rlang:topic-error-chaining]{rlang::topic-error-chaining}.
}
\examples{
# Performing this request usually generates an error because httr2
# converts HTTP errors into R errors:
req <- request(example_url()) |>
req_url_path("/status/404")
try(req |> req_perform())
# You can still retrieve it with last_response()
last_response()
# But you might want to suppress this behaviour:
resp <- req |>
req_error(is_error = \(resp) FALSE) |>
req_perform()
resp
# Or perhaps you're working with a server that routinely uses the
# wrong HTTP error codes only 500s are really errors
request("http://example.com") |>
req_error(is_error = \(resp) resp_status(resp) == 500)
# Most typically you'll use req_error() to add additional information
# extracted from the response body (or sometimes header):
error_body <- function(resp) {
resp_body_json(resp)$error
}
request("http://example.com") |>
req_error(body = error_body)
# Learn more in https://httr2.r-lib.org/articles/wrapping-apis.html
}
\seealso{
\code{\link[=req_retry]{req_retry()}} to control when errors are automatically retried.
}
httr2/man/req_verbose.Rd 0000644 0001762 0000144 00000003546 14523473253 014713 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-options.R
\name{req_verbose}
\alias{req_verbose}
\title{Show extra output when request is performed}
\usage{
req_verbose(
req,
header_req = TRUE,
header_resp = TRUE,
body_req = FALSE,
body_resp = FALSE,
info = FALSE,
redact_headers = TRUE
)
}
\arguments{
\item{req}{A \link{request}.}
\item{header_req, header_resp}{Show request/response headers?}
\item{body_req, body_resp}{Should request/response bodies? When the response
body is compressed, this will show the number of bytes received in
each "chunk".}
\item{info}{Show informational text from curl? This is mainly useful
for debugging https and auth problems, so is disabled by default.}
\item{redact_headers}{Redact confidential data in the headers? Currently
redacts the contents of the Authorization header to prevent you from
accidentally leaking credentials when debugging/reprexing.}
}
\value{
A modified HTTP \link{request}.
}
\description{
\code{req_verbose()} uses the following prefixes to distinguish between
different components of the HTTP requests and responses:
\itemize{
\item \verb{* } informative curl messages
\item \verb{->} request headers
\item \verb{>>} request body
\item \verb{<-} response headers
\item \verb{<<} response body
}
}
\examples{
# Use `req_verbose()` to see the headers that are sent back and forth when
# making a request
resp <- request("https://httr2.r-lib.org") |>
req_verbose() |>
req_perform()
# Or use one of the convenient shortcuts:
resp <- request("https://httr2.r-lib.org") |>
req_perform(verbosity = 1)
}
\seealso{
\code{\link[=req_perform]{req_perform()}} which exposes a limited subset of these options
through the \code{verbosity} argument and \code{\link[=with_verbosity]{with_verbosity()}} which allows you
to control the verbosity of requests deeper within the call stack.
}
httr2/man/resp_headers.Rd 0000644 0001762 0000144 00000002657 14514566210 015041 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/resp-headers.R
\name{resp_headers}
\alias{resp_headers}
\alias{resp_header}
\alias{resp_header_exists}
\title{Extract headers from a response}
\usage{
resp_headers(resp, filter = NULL)
resp_header(resp, header, default = NULL)
resp_header_exists(resp, header)
}
\arguments{
\item{resp}{An HTTP response object, as created by \code{\link[=req_perform]{req_perform()}}.}
\item{filter}{A regular expression used to filter the header names.
\code{NULL}, the default, returns all headers.}
\item{header}{Header name (case insensitive)}
\item{default}{Default value to use if header doesn't exist.}
}
\value{
\itemize{
\item \code{resp_headers()} returns a list.
\item \code{resp_header()} returns a string if the header exists and \code{NULL} otherwise.
\item \code{resp_header_exists()} returns \code{TRUE} or \code{FALSE}.
}
}
\description{
\itemize{
\item \code{resp_headers()} retrieves a list of all headers.
\item \code{resp_header()} retrieves a single header.
\item \code{resp_header_exists()} checks if a header is present.
}
}
\examples{
resp <- request("https://httr2.r-lib.org") |> req_perform()
resp |> resp_headers()
resp |> resp_headers("x-")
resp |> resp_header_exists("server")
resp |> resp_header("server")
# Headers are case insensitive
resp |> resp_header("SERVER")
# Returns NULL if header doesn't exist
resp |> resp_header("this-header-doesnt-exist")
}
httr2/man/figures/ 0000755 0001762 0000144 00000000000 14523473134 013542 5 ustar ligges users httr2/man/figures/lifecycle-defunct.svg 0000644 0001762 0000144 00000002424 14475517553 017664 0 ustar ligges users
httr2/man/figures/lifecycle-maturing.svg 0000644 0001762 0000144 00000002430 14475517553 020057 0 ustar ligges users
httr2/man/figures/logo.png 0000644 0001762 0000144 00000111032 14523473134 015206 0 ustar ligges users PNG
IHDR ޫh cHRM z&