% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/req-cache.R
\name{req_cache}
\alias{req_cache}
\title{Automatically cache requests}
\usage{
req_cache(
  req,
  path,
  use_on_error = FALSE,
  debug = getOption("httr2_cache_debug", FALSE),
  max_age = Inf,
  max_n = Inf,
  max_size = 1024^3
)
}
\arguments{
\item{req}{A httr2 \link{request} object.}

\item{path}{Path to cache directory. Will be created automatically if it
does not exist.

For quick and easy caching within a session, you can use \code{tempfile()}.
To cache requests within a package, you can use something like
\code{file.path(tools::R_user_dir("pkgdown", "cache"), "httr2")}.

httr2 doesn't provide helpers to manage the cache, but if you want to
empty it, you can use something like
\code{unlink(dir(cache_path, full.names = TRUE))}.}

\item{use_on_error}{If the request errors, and there's a cache response,
should \code{req_perform()} return that instead of generating an error?}

\item{debug}{When \code{TRUE} will emit useful messages telling you about
cache hits and misses. This can be helpful to understand whether or
not caching is actually doing anything for your use case.}

\item{max_n, max_age, max_size}{Automatically prune the cache by specifying
one or more of:
\itemize{
\item \code{max_age}: to delete files older than this number of seconds.
\item \code{max_n}: to delete files (from oldest to newest) to preserve at
most this many files.
\item \code{max_size}: to delete files (from oldest to newest) to preserve at
most this many bytes.
}

The cache pruning is performed at most once per minute.}
}
\value{
A modified HTTP \link{request}.
}
\description{
Use \code{req_cache()} to automatically cache HTTP requests. Most API requests
are not cacheable, but static files often are.

\code{req_cache()} caches responses to GET requests that have status code 200 and
at least one of the standard caching headers (e.g. \code{Expires},
\code{Etag}, \code{Last-Modified}, \code{Cache-Control}), unless caching has been expressly
prohibited with \code{Cache-Control: no-store}. Typically, a request will still
be sent to the server to check that the cached value is still up-to-date,
but it will not need to re-download the body value.

To learn more about HTTP caching, I recommend the MDN article
\href{https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching}{HTTP caching}.
}
\examples{
# GitHub uses HTTP caching for all raw files.
url <- paste0(
  "https://raw.githubusercontent.com/allisonhorst/palmerpenguins/",
  "master/inst/extdata/penguins.csv"
)
# Here I set debug = TRUE so you can see what's happening
req <- request(url) |> req_cache(tempdir(), debug = TRUE)

# First request downloads the data
resp <- req |> req_perform()

# Second request retrieves it from the cache
resp <- req |> req_perform()
}
