1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
% 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()
}
|
