print method for HttpClient
objects
Usage
HttpClient$print(x, ...)
...
ignored
Method new()
Create a new HttpClient object
Usage
HttpClient$new(
url,
opts,
proxies,
auth,
headers,
handle,
progress,
hooks,
verbose
)
Arguments
url
(character) A url. One of url
or handle
required.
opts
any curl options
proxies
a proxy()
object
auth
an auth()
object
headers
named list of headers, see http-headers
handle
a handle()
progress
only supports httr::progress()
, see progress
hooks
a named list, see hooks
verbose
a special handler for verbose curl output,
accepts a function only. default is NULL
. if used, verbose
and debugfunction
curl options are ignored if passed to opts
on $new()
and ignored if ...
passed to a http method call
urls
(character) one or more URLs
Returns
A new HttpClient
object
Make a GET request
Usage
HttpClient$get(path = NULL, query = list(), disk = NULL, stream = NULL, ...)
Arguments
path
URL path, appended to the base URL
query
query terms, as a named list. any numeric values are
passed through format()
to prevent larger numbers from being
scientifically formatted
disk
a path to write to. if NULL (default), memory used.
See curl::curl_fetch_disk()
for help.
stream
an R function to determine how to stream data. if
NULL (default), memory used. See curl::curl_fetch_stream()
for help
...
For retry
, the options to be passed on to the method
implementing the requested verb, including curl options. Otherwise,
curl options, only those in the acceptable set from curl::curl_options()
except the following: httpget, httppost, post, postfields, postfieldsize,
and customrequest
Method post()
Make a POST request
Usage
HttpClient$post(
path = NULL,
query = list(),
body = NULL,
disk = NULL,
stream = NULL,
encode = "multipart",
...
)
Arguments
path
URL path, appended to the base URL
query
query terms, as a named list. any numeric values are
passed through format()
to prevent larger numbers from being
scientifically formatted
body
body as an R list
disk
a path to write to. if NULL (default), memory used.
See curl::curl_fetch_disk()
for help.
stream
an R function to determine how to stream data. if
NULL (default), memory used. See curl::curl_fetch_stream()
for help
encode
one of form, multipart, json, or raw
...
For retry
, the options to be passed on to the method
implementing the requested verb, including curl options. Otherwise,
curl options, only those in the acceptable set from curl::curl_options()
except the following: httpget, httppost, post, postfields, postfieldsize,
and customrequest
Method put()
Make a PUT request
Usage
HttpClient$put(
path = NULL,
query = list(),
body = NULL,
disk = NULL,
stream = NULL,
encode = "multipart",
...
)
Arguments
path
URL path, appended to the base URL
query
query terms, as a named list. any numeric values are
passed through format()
to prevent larger numbers from being
scientifically formatted
body
body as an R list
disk
a path to write to. if NULL (default), memory used.
See curl::curl_fetch_disk()
for help.
stream
an R function to determine how to stream data. if
NULL (default), memory used. See curl::curl_fetch_stream()
for help
encode
one of form, multipart, json, or raw
...
For retry
, the options to be passed on to the method
implementing the requested verb, including curl options. Otherwise,
curl options, only those in the acceptable set from curl::curl_options()
except the following: httpget, httppost, post, postfields, postfieldsize,
and customrequest
Method patch()
Make a PATCH request
Usage
HttpClient$patch(
path = NULL,
query = list(),
body = NULL,
disk = NULL,
stream = NULL,
encode = "multipart",
...
)
Arguments
path
URL path, appended to the base URL
query
query terms, as a named list. any numeric values are
passed through format()
to prevent larger numbers from being
scientifically formatted
body
body as an R list
disk
a path to write to. if NULL (default), memory used.
See curl::curl_fetch_disk()
for help.
stream
an R function to determine how to stream data. if
NULL (default), memory used. See curl::curl_fetch_stream()
for help
encode
one of form, multipart, json, or raw
...
For retry
, the options to be passed on to the method
implementing the requested verb, including curl options. Otherwise,
curl options, only those in the acceptable set from curl::curl_options()
except the following: httpget, httppost, post, postfields, postfieldsize,
and customrequest
Method delete()
Make a DELETE request
Usage
HttpClient$delete(
path = NULL,
query = list(),
body = NULL,
disk = NULL,
stream = NULL,
encode = "multipart",
...
)
Arguments
path
URL path, appended to the base URL
query
query terms, as a named list. any numeric values are
passed through format()
to prevent larger numbers from being
scientifically formatted
body
body as an R list
disk
a path to write to. if NULL (default), memory used.
See curl::curl_fetch_disk()
for help.
stream
an R function to determine how to stream data. if
NULL (default), memory used. See curl::curl_fetch_stream()
for help
encode
one of form, multipart, json, or raw
...
For retry
, the options to be passed on to the method
implementing the requested verb, including curl options. Otherwise,
curl options, only those in the acceptable set from curl::curl_options()
except the following: httpget, httppost, post, postfields, postfieldsize,
and customrequest
Make a HEAD request
Usage
HttpClient$head(path = NULL, query = list(), ...)
Arguments
path
URL path, appended to the base URL
query
query terms, as a named list. any numeric values are
passed through format()
to prevent larger numbers from being
scientifically formatted
...
For retry
, the options to be passed on to the method
implementing the requested verb, including curl options. Otherwise,
curl options, only those in the acceptable set from curl::curl_options()
except the following: httpget, httppost, post, postfields, postfieldsize,
and customrequest
Method verb()
Use an arbitrary HTTP verb supported on this class
Supported verbs: "get", "post", "put", "patch", "delete", "head". Also
supports retry
Usage
HttpClient$verb(verb, ...)
Arguments
verb
an HTTP verb supported on this class: "get",
"post", "put", "patch", "delete", "head". Also supports retry.
...
For retry
, the options to be passed on to the method
implementing the requested verb, including curl options. Otherwise,
curl options, only those in the acceptable set from curl::curl_options()
except the following: httpget, httppost, post, postfields, postfieldsize,
and customrequest
Examples
\dontrun{
(x <- HttpClient$new(url = "https://hb.opencpu.org"))
x$verb('get')
x$verb('GET')
x$verb('GET', query = list(foo = "bar"))
x$verb('retry', 'GET', path = "status/400")
}
Method retry()
Retry a request
Usage
HttpClient$retry(
verb,
...,
pause_base = 1,
pause_cap = 60,
pause_min = 1,
times = 3,
terminate_on = NULL,
retry_only_on = NULL,
onwait = NULL
)
Arguments
verb
an HTTP verb supported on this class: "get",
"post", "put", "patch", "delete", "head". Also supports retry.
...
For retry
, the options to be passed on to the method
implementing the requested verb, including curl options. Otherwise,
curl options, only those in the acceptable set from curl::curl_options()
except the following: httpget, httppost, post, postfields, postfieldsize,
and customrequest
pause_base, pause_cap, pause_min
basis, maximum, and minimum for
calculating wait time for retry. Wait time is calculated according to the
exponential backoff with full jitter algorithm. Specifically, wait time is
chosen randomly between pause_min
and the lesser of pause_base * 2
and
pause_cap
, with pause_base
doubling on each subsequent retry attempt.
Use pause_cap = Inf
to not terminate retrying due to cap of wait time
reached.
times
the maximum number of times to retry. Set to Inf
to
not stop retrying due to exhausting the number of attempts.
terminate_on, retry_only_on
a vector of HTTP status codes. For
terminate_on
, the status codes for which to terminate retrying, and for
retry_only_on
, the status codes for which to retry the request.
onwait
a callback function if the request will be retried and
a wait time is being applied. The function will be passed two parameters,
the response object from the failed request, and the wait time in seconds.
Note that the time spent in the function effectively adds to the wait time,
so it should be kept simple.
Details
Retries the request given by verb
until successful
(HTTP response status < 400), or a condition for giving up is met.
Automatically recognizes Retry-After
and X-RateLimit-Reset
headers
in the response for rate-limited remote APIs.
Examples
\dontrun{
x <- HttpClient$new(url = "https://hb.opencpu.org")
# retry, by default at most 3 times
(res_get <- x$retry("GET", path = "status/400"))
# retry, but not for 404 NOT FOUND
(res_get <- x$retry("GET", path = "status/404", terminate_on = c(404)))
# retry, but only for exceeding rate limit (note that e.g. Github uses 403)
(res_get <- x$retry("GET", path = "status/429", retry_only_on = c(403, 429)))
}
Method handle_pop()
reset your curl handle
Usage
HttpClient$handle_pop()
Method url_fetch()
get the URL that would be sent (i.e., before executing
the request) the only things that change the URL are path and query
parameters; body and any curl options don't change the URL
Usage
HttpClient$url_fetch(path = NULL, query = list())
Arguments
path
URL path, appended to the base URL
query
query terms, as a named list. any numeric values are
passed through format()
to prevent larger numbers from being
scientifically formatted
Examples
x <- HttpClient$new(url = "https://hb.opencpu.org")
x$url_fetch()
x$url_fetch('get')
x$url_fetch('post')
x$url_fetch('get', query = list(foo = "bar"))
Method clone()
The objects of this class are cloneable with this method.
Usage
HttpClient$clone(deep = FALSE)
Arguments
deep
Whether to make a deep clone.