The aim of httr is to provide a wrapper for the curl package, customised to the demands of modern web APIs.
Functions for the most important http verbs:
Automatic connection sharing across requests to the same website (by default, curl handles are managed automatically), cookies are maintained across requests, and a up-to-date root-level SSL certificate store is used.
Requests return a standard reponse object that captures the http status line, headers and body, along with other useful information.
Response content is available with
content()as a raw vector (
as = "raw"), a character vector (
as = "text"), or parsed into an R object (
as = "parsed"), currently for html, xml, json, png and jpeg.
You can convert http errors into R errors with
Config functions make it easier to modify the request in common ways:
Support for OAuth 1.0 and 2.0 with
oauth2.0_token(). The demo directory has eight OAuth demos: four for 1.0 (twitter, vimeo, withings and yahoo) and four for 2.0 (facebook, github, google, linkedin). OAuth credentials are automatically cached within a project.
To get the current released version from CRAN:
To get the current development version from github:
# install.packages("devtools") devtools::install_github("r-lib/httr")
Help us keep the lights on
v1.3.1 - Aug 21, 2017
- Re-enable on-disk caching (accidentally disabled in #457) (#475)
v1.3.0 - Aug 16, 2017
safe_callback()has been removed.
oauth_listener()has been deprecated, as the R session does not actually need to be interactive.
get_callback()set and query callback functions that are called right before and after performing an HTTP request (@gaborcsardi, #409)
RETRY()now retries if an error occurs during the request (@asieira, #404), and gains two new arguments:
terminate_ongives you greater control over which status codes should it stop retrying. (@asieira, #404)
pause_minallows for sub-second delays. (Use with caution! Generally the default is preferred.) (@r2evans)
If the server returns HTTP status code 429 and specifies a
retry-aftervalue, that value will now be used instead of exponential backoff with jitter, unless it's smaller than
pause_min. (@nielsoledam, #472)
New oauth cache files are always added to
.gitignoreand, if it exists,
.Rbuildignore. Specifically, this now happens when option
httr_oauth_cache = TRUEor user specifies cache file name explicitly. (@jennybc, #436)
oauth_encode()now handles UTF-8 characters correctly. (@yutannihilation, #424)
oauth_app()allows you to specify the
redirect_urlif you need to customise it.
subparameter so you can request access on behalf of another user (#410), and accepts a character vector of
scopesas was described in the documentation (#389).
oauth_signature()now normalises the URL as described in the OAuth1.0a spec (@leeper, #435)
oauth2.0_access_token()functions pull out parts of the OAuth process for reuse elsewhere (#457).
oauth2.0_token()gains three new arguments:
config_initallows you to supply additional config for the initial request. This is needed for some APIs (e.g. reddit) which rate limit based on
client_credentials, allows you to use the OAauth2 Client Credential Grant. See RFC 6749 for details. (@cderv, #384)
credentialsargument that allows you to customise the auth flow. For advanced used only (#457)
oauth_listener()has been deprecated, as the R session does not need to be interactive.
Minor bug fixes and improvements
BROWSER()prints a message telling you to browse to the URL if called in a non-interactive session.
find_cert_bundle()will now correctly find cert bundle in "R_HOME/etc" (@jiwalker-usgs, #386).
You can now send lists containing
bodyof requests with `encoding = "multipart". This makes it possible to specify the mime-type of individual components (#430).
modify_url()recognised more forms of empty queries. This eliminates a source of spurious trailing
More forms of empty query are recognized as such. Eliminates a source of spurious trailing
?=in URLs produced by
modify_url(). (@jennybc, #452)
length()method of the internal
pathclass is no longer exported (#395).
v1.2.1 - Jul 3, 2016
- Fix bug with new cache creation code: need to check that cache isn't an empty file.
v1.2.0 - Jun 16, 2016
oauth_signature()no longer prepends 'oauth_' to additional parameters. (@jimhester, #373)
print()methods now invisibly return
DELETE()gains a body parameter (#326).
encode = "raw"allows you to do your own encoding for requests with bodies.
http_type()returns the content/mime type of a request, sans parameters.
Bug fixes and minor improvements
- No longer uses use custom requests for standard
POSTrequests (#356, #357). This has the side-effect of properly following redirects after
POST, fixing some login issues (eg hadley/rvest#133).
- Long deprecated
PATCH()has been removed.
- The cross-session OAuth cache is now created with permission 0600, and should give a better error if it can't be created (#365).
RETRY()function allows you to retry a request multiple times until it succeeds (#353).
- The default user agent string is now computed once and cached. This is a small performance improvement, but important for local connections (#322, @richfitz).
oauth_callback()gains trailing slash for facebook compatibility (#324).
conargument to control where progress bar is rendered (#359).
use_basic_authoption is used to obtain a token, token refreshes will now use basic authentication too.
- Suppress unhelpful "No encoding supplied: defaulting to UTF-8." when printing a response (#327).
- All auto parser functions now have consistent arguments. This fixes problem
...is pass on to another function (#330).
parse_media()can once again parse multiple parameters (#362, #366).
- Correctly cast
- Fix in readfunction to close connection when done.
v1.1.0 - Jan 28, 2016
messageargument with new
taskargument that optionally describes the current task. This allows API wrappers to provide more informative error messages on failure (#277, #302).
warn_for_status()return the response if there were no errors. This makes them easier to use in pipelines (#278).
url_successful()have been deprecated in favour of the more flexible
http_error(), which works with urls, responses and integer status codes (#299).
oauth1.0_token()gains RSA-SHA1 signature support with the
private_keyargument (@nathangoulding, #316).
oauth2.0_token()throws an error if it fails to get an access token (#250) and gains two new arguments:
user_paramsallows you to pass arbitrary additional parameters to the token access endpoint when acquiring or refreshing a token (@cornf4ke, #312)
use_basic_authallows you to pick use http authentication when getting a token (#310, @grahamrp).
oauth_service_token()checks that its arguments are the correct types (#282) and anways returns a
requestobject (#313, @nathangoulding).
refresh_oauth2.0()checks for known OAuth2.0 errors and clears the locally cached token in the presense of any (@nathangoulding, #315).
Bug fixes and minor improvements
- httr no longer bundles
cacert.pem, and instead it relies on the bundle in openssl. This bundle is only used a last-resort on windows with R <3.2.0.
- Switch to 'openssl' package for hashing, hmac, signatures, and base64.
- httr no longer depends on stringr (#285, @jimhester).
content(x)uses xml2 for XML documents and readr for csv and tsv.
content(, type = "text")defaults to UTF-8 encoding if not otherwise specified.
has_content()correctly tests for the presence/absence of body content (#91).
parse_url()correctly parses urls like
TRUEto fix for 'progress callback must return boolean' warning (@jeroenooms, #252).
upload_file()supports very large files (> 2.5 Gb) (@jeroenooms, #257).