| Title: | Tools for Working with URLs and HTTP |
|---|---|
| Description: | Useful tools for working with HTTP organised by HTTP verbs (GET(), POST(), etc). Configuration functions make it easy to control additional request components (authenticate(), add_headers() and so on). |
| Authors: | Hadley Wickham [aut, cre], Posit Software, PBC [cph, fnd] |
| Maintainer: | Hadley Wickham <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.4.7.9000 |
| Built: | 2025-11-24 05:03:56 UTC |
| Source: | https://github.com/r-lib/httr |
Wikipedia provides a useful list of common http headers:https://en.wikipedia.org/wiki/List_of_HTTP_header_fields.
add_headers(..., .headers = character())add_headers(..., .headers= character())
... | named header values. To stop an existing header from beingset, pass an empty string: |
.headers | a named character vector |
accept() andcontent_type() forconvenience functions for setting accept and content-type headers.
Other config:authenticate(),config(),set_cookies(),timeout(),use_proxy(),user_agent(),verbose()
add_headers(a = 1, b = 2)add_headers(.headers = c(a = "1", b = "2"))## Not run: GET("http://httpbin.org/headers")# Add arbitrary headersGET( "http://httpbin.org/headers", add_headers(version = version$version.string))# Override default headers with empty stringsGET("http://httpbin.org/headers", add_headers(Accept = ""))## End(Not run)add_headers(a=1, b=2)add_headers(.headers= c(a="1", b="2"))## Not run:GET("http://httpbin.org/headers")# Add arbitrary headersGET("http://httpbin.org/headers", add_headers(version= version$version.string))# Override default headers with empty stringsGET("http://httpbin.org/headers", add_headers(Accept=""))## End(Not run)
It's not obvious how to turn authentication off after using it, soI recommend using custom handles with authentication.
authenticate(user, password, type = "basic")authenticate(user, password, type="basic")
user | user name |
password | password |
type | type of HTTP authentication. Should be one of the followingtypes supported by Curl: basic, digest, digest_ie, gssnegotiate,ntlm, any. It defaults to "basic", the most common type. |
Other config:add_headers(),config(),set_cookies(),timeout(),use_proxy(),user_agent(),verbose()
## Not run: GET("http://httpbin.org/basic-auth/user/passwd")GET( "http://httpbin.org/basic-auth/user/passwd", authenticate("user", "passwd"))## End(Not run)## Not run:GET("http://httpbin.org/basic-auth/user/passwd")GET("http://httpbin.org/basic-auth/user/passwd", authenticate("user","passwd"))## End(Not run)
(This isn't really a http verb, but it seems to follow the same format).
BROWSE(url = NULL, config = list(), ..., handle = NULL)BROWSE(url=NULL, config= list(),..., handle=NULL)
url | the url of the page to retrieve |
config | All configuration options are ignored because the requestis handled by the browser, notRCurl. |
... | Further named parameters, such as |
handle | The handle to use with this request. If notsupplied, will be retrieved and reused from the |
Only works in interactive sessions.
Aresponse() object.
Other http methods:DELETE(),GET(),HEAD(),PATCH(),POST(),PUT(),VERB()
BROWSE("http://google.com")BROWSE("http://had.co.nz")BROWSE("http://google.com")BROWSE("http://had.co.nz")
cache_info() gives details of cacheability of a response,rerequest() re-performs the original request doing as little workas possible (if not expired, returns response as is, or performsrevalidation if Etag or Last-Modified headers are present).
cache_info(r)rerequest(r)cache_info(r)rerequest(r)
r | A response |
# Never cached, always causes redownloadr1 <- GET("https://www.google.com")cache_info(r1)r1$datererequest(r1)$date# Expires in a yearr2 <- GET("https://www.google.com/images/srpr/logo11w.png")cache_info(r2)r2$datererequest(r2)$date## Not run: # Has last-modified and etag, so does revalidationr3 <- GET("http://httpbin.org/cache")cache_info(r3)r3$datererequest(r3)$date# Expires after 5 secondsr4 <- GET("http://httpbin.org/cache/5")cache_info(r4)r4$datererequest(r4)$dateSys.sleep(5)cache_info(r4)rerequest(r4)$date## End(Not run)# Never cached, always causes redownloadr1<- GET("https://www.google.com")cache_info(r1)r1$datererequest(r1)$date# Expires in a yearr2<- GET("https://www.google.com/images/srpr/logo11w.png")cache_info(r2)r2$datererequest(r2)$date## Not run:# Has last-modified and etag, so does revalidationr3<- GET("http://httpbin.org/cache")cache_info(r3)r3$datererequest(r3)$date# Expires after 5 secondsr4<- GET("http://httpbin.org/cache/5")cache_info(r4)r4$datererequest(r4)$dateSys.sleep(5)cache_info(r4)rerequest(r4)$date## End(Not run)
Generally you should only need to use this function to set CURL optionsdirectly if there isn't already a helpful wrapper function, likeset_cookies(),add_headers() orauthenticate(). To use this function effectively requiressome knowledge of CURL, and CURL options. Usehttr_options() tosee a complete list of available options. To see the libcurl documentationfor a given option, usecurl_docs().
config(..., token = NULL)config(..., token=NULL)
... | named Curl options. |
token | An OAuth token (1.0 or 2.0) |
Unlike Curl (and RCurl), all configuration options are per request, notper handle.
set_config() to set global config defaults, andwith_config() to temporarily run code with set options.
All known available options are listed inhttr_options()
Other config:add_headers(),authenticate(),set_cookies(),timeout(),use_proxy(),user_agent(),verbose()
Other ways to set configuration:set_config(),with_config()
# There are a number of ways to modify the configuration of a request# * you can add directly to a requestHEAD("https://www.google.com", verbose())# * you can wrap with with_config()with_config(verbose(), HEAD("https://www.google.com"))# * you can set global with set_config()old <- set_config(verbose())HEAD("https://www.google.com")# and re-establish the previous settings withset_config(old, override = TRUE)HEAD("https://www.google.com")# orreset_config()HEAD("https://www.google.com")# If available, you should use a friendly httr wrapper over RCurl# options. But you can pass Curl options (as listed in httr_options())# in configHEAD("https://www.google.com/", config(verbose = TRUE))# There are a number of ways to modify the configuration of a request# * you can add directly to a requestHEAD("https://www.google.com", verbose())# * you can wrap with with_config()with_config(verbose(), HEAD("https://www.google.com"))# * you can set global with set_config()old<- set_config(verbose())HEAD("https://www.google.com")# and re-establish the previous settings withset_config(old, override=TRUE)HEAD("https://www.google.com")# orreset_config()HEAD("https://www.google.com")# If available, you should use a friendly httr wrapper over RCurl# options. But you can pass Curl options (as listed in httr_options())# in configHEAD("https://www.google.com/", config(verbose=TRUE))
There are currently three ways to retrieve the contents of a request:as a raw object (as = "raw"), as a character vector,(as = "text"), and as parsed into an R object where possible,(as = "parsed"). Ifas is not specified,contentdoes its best to guess which output is most appropriate.
content(x, as = NULL, type = NULL, encoding = NULL, ...)content(x, as=NULL, type=NULL, encoding=NULL,...)
x | request object |
as | desired type of output: |
type | MIME type (aka internet media type) used to overridethe content type returned by the server. Seehttps://en.wikipedia.org/wiki/Internet_media_type for a list ofcommon types. |
encoding | For text, overrides the charset or the Latin1 (ISO-8859-1)default, if you know that the server is returning the incorrect encodingas the charset in the content-type. Use for text and parsed outputs. |
... | Other parameters passed on to the parsing functions, if |
content currently knows about the following mime types:
text/html:xml2::read_html()
text/xml:xml2::read_xml()
text/csv:readr::read_csv()
text/tab-separated-values:readr::read_tsv()
application/json:jsonlite::fromJSON()
application/x-www-form-urlencoded:parse_query
image/jpeg:jpeg::readJPEG()
image/png:png::readPNG()
as = "parsed" is provided as a convenience only: if the type youare trying to parse is not available, useas = "text" and parseyourself.
For "raw", a raw vector.
For "text", a character vector of length 1. The character vector is alwaysre-encoded to UTF-8. If this encoding fails (usually because the pagedeclares an incorrect encoding),content() will returnNA.
For "auto", a parsed R object.
When usingcontent() in a package, DO NOT use onas = "parsed".Instead, check the mime-type is what you expect, and then parse yourself.This is safer, as you will fail informatively if the API changes, andyou will protect yourself against changes to httr.
Other response methods:http_error(),http_status(),response(),stop_for_status()
## Not run: r <- POST("http://httpbin.org/post", body = list(a = 1, b = 2))content(r) # automatically parses JSONcat(content(r, "text"), "\n") # text contentcontent(r, "raw") # raw bytes from serverrlogo <- content(GET("https://httpbin.org/image/png"))plot(0:1, 0:1, type = "n")rasterImage(rlogo, 0, 0, 1, 1)## End(Not run)## Not run:r<- POST("http://httpbin.org/post", body= list(a=1, b=2))content(r)# automatically parses JSONcat(content(r,"text"),"\n")# text contentcontent(r,"raw")# raw bytes from serverrlogo<- content(GET("https://httpbin.org/image/png"))plot(0:1,0:1, type="n")rasterImage(rlogo,0,0,1,1)## End(Not run)
These are convenient wrappers aroudadd_headers().
content_type(type)content_type_json()content_type_xml()accept(type)accept_json()accept_xml()content_type(type)content_type_json()content_type_xml()accept(type)accept_json()accept_xml()
type | A mime type or a file extension. If a file extension (i.e. startswith |
accept_json/accept_xml andcontent_type_json/content_type_xml are useful shortcuts toask for json or xml responses or tell the server you are sending json/xml.
## Not run: GET("http://httpbin.org/headers")GET("http://httpbin.org/headers", accept_json())GET("http://httpbin.org/headers", accept("text/csv"))GET("http://httpbin.org/headers", accept(".doc"))GET("http://httpbin.org/headers", content_type_xml())GET("http://httpbin.org/headers", content_type("text/csv"))GET("http://httpbin.org/headers", content_type(".xml"))## End(Not run)## Not run:GET("http://httpbin.org/headers")GET("http://httpbin.org/headers", accept_json())GET("http://httpbin.org/headers", accept("text/csv"))GET("http://httpbin.org/headers", accept(".doc"))GET("http://httpbin.org/headers", content_type_xml())GET("http://httpbin.org/headers", content_type("text/csv"))GET("http://httpbin.org/headers", content_type(".xml"))## End(Not run)
Access cookies in a response.
cookies(x)cookies(x)
x | A response. |
set_cookies() to send cookies in request.
## Not run: r <- GET("http://httpbin.org/cookies/set", query = list(a = 1, b = 2))cookies(r)## End(Not run)## Not run:r<- GET("http://httpbin.org/cookies/set", query= list(a=1, b=2))cookies(r)## End(Not run)
Send a DELETE request.
DELETE( url = NULL, config = list(), ..., body = NULL, encode = c("multipart", "form", "json", "raw"), handle = NULL)DELETE( url=NULL, config= list(),..., body=NULL, encode= c("multipart","form","json","raw"), handle=NULL)
url | the url of the page to retrieve |
config | Additional configuration settings such as httpauthentication ( |
... | Further named parameters, such as |
body | One of the following:
|
encode | If the body is a named list, how should it be encoded? Can beone of form (application/x-www-form-urlencoded), multipart,(multipart/form-data), or json (application/json). For "multipart", list elements can be strings or objects created by |
handle | The handle to use with this request. If notsupplied, will be retrieved and reused from the |
Aresponse() object.
The DELETE method requests that the origin server delete the resourceidentified by the Request-URI. This method MAY be overridden by humanintervention (or other means) on the origin server. The client cannot beguaranteed that the operation has been carried out, even if the status codereturned from the origin server indicates that the action has beencompleted successfully. However, the server SHOULD NOT indicate successunless, at the time the response is given, it intends to delete theresource or move it to an inaccessible location.
A successful response SHOULD be 200 (OK) if the response includes an entitydescribing the status, 202 (Accepted) if the action has not yet beenenacted, or 204 (No Content) if the action has been enacted but theresponse does not include an entity.
If the request passes through a cache and the Request-URI identifies one ormore currently cached entities, those entries SHOULD be treated as stale.Responses to this method are not cacheable.
Other http methods:BROWSE(),GET(),HEAD(),PATCH(),POST(),PUT(),VERB()
## Not run: DELETE("http://httpbin.org/delete")POST("http://httpbin.org/delete")## End(Not run)## Not run:DELETE("http://httpbin.org/delete")POST("http://httpbin.org/delete")## End(Not run)
GET a url.
GET(url = NULL, config = list(), ..., handle = NULL)GET(url=NULL, config= list(),..., handle=NULL)
url | the url of the page to retrieve |
config | Additional configuration settings such as httpauthentication ( |
... | Further named parameters, such as |
handle | The handle to use with this request. If notsupplied, will be retrieved and reused from the |
Aresponse() object.
The GET method means retrieve whatever information (in the form of anentity) is identified by the Request-URI. If the Request-URI refers to adata-producing process, it is the produced data which shall be returned asthe entity in the response and not the source text of the process, unlessthat text happens to be the output of the process.
The semantics of the GET method change to a "conditional GET" if therequest message includes an If-Modified-Since, If-Unmodified-Since,If-Match, If-None-Match, or If-Range header field. A conditional GET methodrequests that the entity be transferred only under the circumstancesdescribed by the conditional header field(s). The conditional GET method isintended to reduce unnecessary network usage by allowing cached entities tobe refreshed without requiring multiple requests or transferring dataalready held by the client.
The semantics of the GET method change to a "partial GET" if the requestmessage includes a Range header field. A partial GET requests that onlypart of the entity be transferred, as described inhttps://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35The partial GET method is intended to reduce unnecessary network usage byallowing partially-retrieved entities to be completed without transferringdata already held by the client.
Other http methods:BROWSE(),DELETE(),HEAD(),PATCH(),POST(),PUT(),VERB()
GET("http://google.com/")## Not run: GET("http://google.com/", path = "search")GET("http://google.com/", path = "search", query = list(q = "ham"))## End(Not run)# See what GET is doing with httpbin.org## Not run: url <- "http://httpbin.org/get"GET(url)GET(url, add_headers(a = 1, b = 2))GET(url, set_cookies(a = 1, b = 2))GET(url, add_headers(a = 1, b = 2), set_cookies(a = 1, b = 2))GET(url, authenticate("username", "password"))GET(url, verbose())## End(Not run)# You might want to manually specify the handle so you can have multiple# independent logins to the same website.## Not run: google <- handle("http://google.com")GET(handle = google, path = "/")GET(handle = google, path = "search")## End(Not run)GET("http://google.com/")## Not run:GET("http://google.com/", path="search")GET("http://google.com/", path="search", query= list(q="ham"))## End(Not run)# See what GET is doing with httpbin.org## Not run:url<-"http://httpbin.org/get"GET(url)GET(url, add_headers(a=1, b=2))GET(url, set_cookies(a=1, b=2))GET(url, add_headers(a=1, b=2), set_cookies(a=1, b=2))GET(url, authenticate("username","password"))GET(url, verbose())## End(Not run)# You might want to manually specify the handle so you can have multiple# independent logins to the same website.## Not run:google<- handle("http://google.com")GET(handle= google, path="/")GET(handle= google, path="search")## End(Not run)
Supported callback functions:
This callback is called before an HTTP requestis performed, with therequest object as an argument.If the callback returns a value other thanNULL, the HTTPrequest is not performed at all, and the return value of the callbackis returned. This mechanism can be used to replay previouslyrecorded HTTP responses.
This callback is called after an HTTP requestis performed. The callback is called with two arguments: therequest object and theresponse object of the HTTPrequest. If this callback returns a value other thanNULL,then this value is returned byhttr.
get_callback(name)set_callback(name, new_callback = NULL)get_callback(name)set_callback(name, new_callback=NULL)
name | Character scalar, name of the callback to query or set. |
new_callback | The callback function to install, a function object;or |
Note that it is not possible to install multiple callbacks of the sametype. The installed callback overwrites the previously intalled one.To uninstall a callback function, set it toNULL withset_callback().
See thehttrmock package for a proper example that usescallbacks.
get_callback returns the currently installedcallback, orNULL if none is installed.
set_callback returns the previously installed callback,orNULL if none was installed.
## Not run: ## Log all HTTP requests to the screeenreq_logger <- function(req) { cat("HTTP request to", sQuote(req$url), "\n")}old <- set_callback("request", req_logger)g1 <- GET("https://httpbin.org")g2 <- GET("https://httpbin.org/ip")set_callback("request", old)## Log all HTTP requests and response status codes as wellreq_logger2 <- function(req) { cat("HTTP request to", sQuote(req$url), "... ")}res_logger <- function(req, res) { cat(res$status_code, "\n")}old_req <- set_callback("request", req_logger2)old_res <- set_callback("response", res_logger)g3 <- GET("https://httpbin.org")g4 <- GET("https://httpbin.org/ip")set_callback("request", old_req)set_callback("response", old_res)## Return a recorded response, without performing the HTTP requestreplay <- function(req) { if (req$url == "https://httpbin.org") g3}old_req <- set_callback("request", replay)grec <- GET("https://httpbin.org")grec$date == g3$dateset_callback("request", old_req)## End(Not run)## Not run:## Log all HTTP requests to the screeenreq_logger<-function(req){ cat("HTTP request to", sQuote(req$url),"\n")}old<- set_callback("request", req_logger)g1<- GET("https://httpbin.org")g2<- GET("https://httpbin.org/ip")set_callback("request", old)## Log all HTTP requests and response status codes as wellreq_logger2<-function(req){ cat("HTTP request to", sQuote(req$url),"... ")}res_logger<-function(req, res){ cat(res$status_code,"\n")}old_req<- set_callback("request", req_logger2)old_res<- set_callback("response", res_logger)g3<- GET("https://httpbin.org")g4<- GET("https://httpbin.org/ip")set_callback("request", old_req)set_callback("response", old_res)## Return a recorded response, without performing the HTTP requestreplay<-function(req){if(req$url=="https://httpbin.org") g3}old_req<- set_callback("request", replay)grec<- GET("https://httpbin.org")grec$date== g3$dateset_callback("request", old_req)## End(Not run)
This handle preserves settings and cookies across multiple requests. It isthe foundation of all requests performed through the httr package, althoughit will mostly be hidden from the user.
handle(url, cookies = TRUE)handle(url, cookies=TRUE)
url | full url to site |
cookies | DEPRECATED |
Because of the way argument dispatch works in R, using handle() in thehttp methods (SeeGET()) will cause problems when trying topass configuration arguments (See examples below). Directly specifying thehandle when using http methods is not recommended in general, since theselection of the correct handle is taken care of when the user passes an url(Seehandle_pool()).
handle("http://google.com")handle("https://google.com")h <- handle("http://google.com")GET(handle = h)# Should see cookies sent back to serverGET(handle = h, config = verbose())h <- handle("http://google.com", cookies = FALSE)GET(handle = h)$cookies## Not run: # Using the preferred way of configuring the http methods# will not work when using handle():GET(handle = h, timeout(10))# Passing named arguments will work properly:GET(handle = h, config = list(timeout(10), add_headers(Accept = "")))## End(Not run)handle("http://google.com")handle("https://google.com")h<- handle("http://google.com")GET(handle= h)# Should see cookies sent back to serverGET(handle= h, config= verbose())h<- handle("http://google.com", cookies=FALSE)GET(handle= h)$cookies## Not run:# Using the preferred way of configuring the http methods# will not work when using handle():GET(handle= h, timeout(10))# Passing named arguments will work properly:GET(handle= h, config= list(timeout(10), add_headers(Accept="")))## End(Not run)
Get url HEADers.
HEAD(url = NULL, config = list(), ..., handle = NULL)HEAD(url=NULL, config= list(),..., handle=NULL)
url | the url of the page to retrieve |
config | Additional configuration settings such as httpauthentication ( |
... | Further named parameters, such as |
handle | The handle to use with this request. If notsupplied, will be retrieved and reused from the |
Aresponse() object.
The HEAD method is identical to GET except that the server MUST NOT returna message-body in the response. The metainformation contained in the HTTPheaders in response to a HEAD request SHOULD be identical to theinformation sent in response to a GET request. This method can be used forobtaining metainformation about the entity implied by the request withouttransferring the entity-body itself. This method is often used for testinghypertext links for validity, accessibility, and recent modification.
The response to a HEAD request MAY be cacheable in the sense that theinformation contained in the response MAY be used to update a previouslycached entity from that resource. If the new field values indicate that thecached entity differs from the current entity (as would be indicated by achange in Content-Length, Content-MD5, ETag or Last-Modified), then thecache MUST treat the cache entry as stale.
Other http methods:BROWSE(),DELETE(),GET(),PATCH(),POST(),PUT(),VERB()
HEAD("http://google.com")headers(HEAD("http://google.com"))HEAD("http://google.com")headers(HEAD("http://google.com"))
Extract the headers from a response
headers(x)headers(x)
x | A request object |
add_headers() to send additional headers in arequest
## Not run: r <- GET("http://httpbin.org/get")headers(r)## End(Not run)## Not run:r<- GET("http://httpbin.org/get")headers(r)## End(Not run)
Check for an http error.
http_error(x, ...)http_error(x,...)
x | Object to check. Default methods are provided for strings(which perform an |
... | Other arguments passed on to methods. |
TRUE if the request fails (status code 400 or above),otherwiseFALSE.
Other response methods:content(),http_status(),response(),stop_for_status()
## Not run: # You can pass a url:http_error("http://www.google.com")http_error("http://httpbin.org/status/404")# Or a requestr <- GET("http://httpbin.org/status/201")http_error(r)## End(Not run)# Or an (integer) status codehttp_error(200L)http_error(404L)## Not run:# You can pass a url:http_error("http://www.google.com")http_error("http://httpbin.org/status/404")# Or a requestr<- GET("http://httpbin.org/status/201")http_error(r)## End(Not run)# Or an (integer) status codehttp_error(200L)http_error(404L)
Extract the http status code and convert it into a human readable message.
http_status(x)http_status(x)
x | a request object or a number. |
http servers send a status code with the response to each request. This codegives information regarding the outcome of the execution of the requeston the server. Roughly speaking, codes in the 100s and 200s mean the requestwas successfully executed; codes in the 300s mean the page was redirected;codes in the 400s mean there was a mistake in the way the client sent therequest; codes in the 500s mean the server failed to fulfillan apparently valid request. More details on the codes can be found athttp://en.wikipedia.org/wiki/Http_error_codes.
If the status code does not match a known status, an error.Otherwise, a list with components
category | the broad category of the status |
message | the meaning of the status code |
Other response methods:content(),http_error(),response(),stop_for_status()
http_status(100)http_status(404)## Not run: x <- GET("http://httpbin.org/status/200")http_status(x)http_status(GET("http://httpbin.org/status/300"))http_status(GET("http://httpbin.org/status/301"))http_status(GET("http://httpbin.org/status/404"))# errors out on unknown statushttp_status(GET("http://httpbin.org/status/320"))## End(Not run)http_status(100)http_status(404)## Not run:x<- GET("http://httpbin.org/status/200")http_status(x)http_status(GET("http://httpbin.org/status/300"))http_status(GET("http://httpbin.org/status/301"))http_status(GET("http://httpbin.org/status/404"))# errors out on unknown statushttp_status(GET("http://httpbin.org/status/320"))## End(Not run)
Extract the content type of a response
http_type(x)http_type(x)
x | A response |
A string giving the complete mime type, with all parametersstripped off.
## Not run: r1 <- GET("http://httpbin.org/image/png")http_type(r1)headers(r1)[["Content-Type"]]r2 <- GET("http://httpbin.org/ip")http_type(r2)headers(r2)[["Content-Type"]]## End(Not run)## Not run:r1<- GET("http://httpbin.org/image/png")http_type(r1)headers(r1)[["Content-Type"]]r2<- GET("http://httpbin.org/ip")http_type(r2)headers(r2)[["Content-Type"]]## End(Not run)
Currently one check: that curl uses nss.
httr_dr()httr_dr()
This function lists all available options forconfig().It provides both the short R name which you use with httr, and the longerCurl name, which is useful when searching the documentation.curl_docopens a link to the libcurl documentation for an option in your browser.
httr_options(matches)curl_docs(x)httr_options(matches)curl_docs(x)
matches | If not missing, this restricts the output so that eitherthe httr or curl option matches this regular expression. |
x | An option name (either short or full). |
RCurl and httr use slightly different names to libcurl: the initialCURLOPT_ is removed, all underscores are converted to periods andthe option is given in lower case. Thus "CURLOPT_SSLENGINE_DEFAULT"becomes "sslengine.default".
A data frame with three columns:
httr | The short name used in httr |
libcurl | The full name used by libcurl |
type | The type of R object that the option accepts |
httr_options()httr_options("post")# Use curl_docs to read the curl documentation for each option.# You can use either the httr or curl option name.curl_docs("userpwd")curl_docs("CURLOPT_USERPWD")httr_options()httr_options("post")# Use curl_docs to read the curl documentation for each option.# You can use either the httr or curl option name.curl_docs("userpwd")curl_docs("CURLOPT_USERPWD")
Modify a url by first parsing it and then replacing components withthe non-NULL arguments of this function.
modify_url( url, scheme = NULL, hostname = NULL, port = NULL, path = NULL, query = NULL, params = NULL, fragment = NULL, username = NULL, password = NULL)modify_url( url, scheme=NULL, hostname=NULL, port=NULL, path=NULL, query=NULL, params=NULL, fragment=NULL, username=NULL, password=NULL)
url | the url to modify |
scheme,hostname,port,path,query,params,fragment,username,password | components of the url to change |
See the demos for instructions on how to create an OAuth app for linkedin,twitter, vimeo, facebook, github and google. When wrapping an API from apackage, the author may want to include a default app to facilitate early andcasual use and then provide a method for heavy or advanced users to supplytheir own app or key and secret.
oauth_app(appname, key, secret = NULL, redirect_uri = oauth_callback())oauth_app(appname, key, secret=NULL, redirect_uri= oauth_callback())
appname | name of the application. This is not used for OAuth, but isused to make it easier to identify different applications. |
key | consumer key, also sometimes called the client ID |
secret | consumer secret, also sometimes called the client secret.Despite its name, this does not necessarily need to be protected like apassword, i.e. the user still has to authenticate themselves and grant theapp permission to access resources on their behalf. For example, seeGoogle's docs forOAuth2 for installed applications. |
redirect_uri | The URL that user will be redirected to afterauthorisation is complete. You should generally leave this as the defaultunless you're using a non-standard auth flow (like with shiny). |
Other OAuth:oauth1.0_token(),oauth2.0_token(),oauth_endpoint(),oauth_service_token()
## Not run: google_app <- oauth_app( "google", key = "123456789.apps.googleusercontent.com", secret = "abcdefghijklmnopqrstuvwxyz")## End(Not run)## Not run:google_app<- oauth_app("google", key="123456789.apps.googleusercontent.com", secret="abcdefghijklmnopqrstuvwxyz")## End(Not run)
Seeoauth_endpoints() for a list of popular OAuth endpointsbaked into httr.
oauth_endpoint(request = NULL, authorize, access, ..., base_url = NULL)oauth_endpoint(request=NULL, authorize, access,..., base_url=NULL)
request | url used to request initial (unauthenticated) token.If using OAuth2.0, leave as |
authorize | url to send client to for authorisation. Set to |
access | url used to exchange unauthenticated for authenticated token. |
... | other additional endpoints. |
base_url | option url to use as base for |
Other OAuth:oauth1.0_token(),oauth2.0_token(),oauth_app(),oauth_service_token()
linkedin <- oauth_endpoint("requestToken", "authorize", "accessToken", base_url = "https://api.linkedin.com/uas/oauth")github <- oauth_endpoint(NULL, "authorize", "access_token", base_url = "https://github.com/login/oauth")facebook <- oauth_endpoint( authorize = "https://www.facebook.com/dialog/oauth", access = "https://graph.facebook.com/oauth/access_token")oauth_endpointslinkedin<- oauth_endpoint("requestToken","authorize","accessToken", base_url="https://api.linkedin.com/uas/oauth")github<- oauth_endpoint(NULL,"authorize","access_token", base_url="https://github.com/login/oauth")facebook<- oauth_endpoint( authorize="https://www.facebook.com/dialog/oauth", access="https://graph.facebook.com/oauth/access_token")oauth_endpoints
Provides some common OAuth endpoints.
oauth_endpoints(name)oauth_endpoints(name)
name | One of the following endpoints: linkedin, twitter,vimeo, google, facebook, github, azure. |
oauth_endpoints("twitter")oauth_endpoints("twitter")
Service accounts provide a way of using OAuth2 without user intervention.They instead assume that the server has access to a private key usedto sign requests. The OAuth app is not needed for service accounts:that information is embedded in the account itself.
oauth_service_token(endpoint, secrets, scope = NULL, sub = NULL)oauth_service_token(endpoint, secrets, scope=NULL, sub=NULL)
endpoint | An OAuth endpoint, created by |
secrets | Secrets loaded from JSON file, downloaded from console. |
scope | a character vector of scopes to request. |
sub | The email address of the user for which the application isrequesting delegated access. |
Other OAuth:oauth1.0_token(),oauth2.0_token(),oauth_app(),oauth_endpoint()
## Not run: endpoint <- oauth_endpoints("google")secrets <- jsonlite::fromJSON("~/Desktop/httrtest-45693cbfac92.json")scope <- "https://www.googleapis.com/auth/bigquery.readonly"token <- oauth_service_token(endpoint, secrets, scope)## End(Not run)## Not run:endpoint<- oauth_endpoints("google")secrets<- jsonlite::fromJSON("~/Desktop/httrtest-45693cbfac92.json")scope<-"https://www.googleapis.com/auth/bigquery.readonly"token<- oauth_service_token(endpoint, secrets, scope)## End(Not run)
This is the final object in the OAuth dance - it encapsulates the app,the endpoint, other parameters and the received credentials.
oauth1.0_token( endpoint, app, permission = NULL, as_header = TRUE, private_key = NULL, cache = getOption("httr_oauth_cache"))oauth1.0_token( endpoint, app, permission=NULL, as_header=TRUE, private_key=NULL, cache= getOption("httr_oauth_cache"))
endpoint | An OAuth endpoint, created by |
app | An OAuth consumer application, created by |
permission | optional, a string of permissions to ask for. |
as_header | If |
private_key | Optional, a key provided by |
cache | A logical value or a string. |
SeeToken() for full details about the token object, and thecaching policies used to store credentials across sessions.
AToken1.0 reference class (RC) object.
Other OAuth:oauth2.0_token(),oauth_app(),oauth_endpoint(),oauth_service_token()
This is the final object in the OAuth dance - it encapsulates the app,the endpoint, other parameters and the received credentials. It is areference class so that it can be seamlessly updated (e.g. using$refresh()) when access expires.
oauth2.0_token( endpoint, app, scope = NULL, user_params = NULL, type = NULL, use_oob = getOption("httr_oob_default"), oob_value = NULL, as_header = TRUE, use_basic_auth = FALSE, cache = getOption("httr_oauth_cache"), config_init = list(), client_credentials = FALSE, credentials = NULL, query_authorize_extra = list())oauth2.0_token( endpoint, app, scope=NULL, user_params=NULL, type=NULL, use_oob= getOption("httr_oob_default"), oob_value=NULL, as_header=TRUE, use_basic_auth=FALSE, cache= getOption("httr_oauth_cache"), config_init= list(), client_credentials=FALSE, credentials=NULL, query_authorize_extra= list())
endpoint | An OAuth endpoint, created by |
app | An OAuth consumer application, created by |
scope | a character vector of scopes to request. |
user_params | Named list holding endpoint specific parameters to pass tothe server when posting the request for obtaining or refreshing theaccess token. |
type | content type used to override incorrect server response |
use_oob | if FALSE, use a local webserver for the OAuth dance.Otherwise, provide a URL to the user and prompt for a validationcode. Defaults to the of the |
oob_value | if provided, specifies the value to use for the redirect_uriparameter when retrieving an authorization URL. Defaults to "urn:ietf:wg:oauth:2.0:oob".Requires |
as_header | If |
use_basic_auth | if |
cache | A logical value or a string. |
config_init | Additional configuration settings sent to |
client_credentials | Default to |
credentials | Advanced use only: allows you to completely customisetoken generation. |
query_authorize_extra | Default to |
SeeToken() for full details about the token object, and thecaching policies used to store credentials across sessions.
AToken2.0 reference class (RC) object.
Other OAuth:oauth1.0_token(),oauth_app(),oauth_endpoint(),oauth_service_token()
As defined in RFC2616,https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3, there arethree valid formats:
Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123
Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
parse_http_date(x, failure = structure(NA_real_, class = "Date"))http_date(x)parse_http_date(x, failure= structure(NA_real_, class="Date"))http_date(x)
x | For For |
failure | What to return on failure? |
A POSIXct object if succesful, otherwisefailure
parse_http_date("Sun, 06 Nov 1994 08:49:37 GMT")parse_http_date("Sunday, 06-Nov-94 08:49:37 GMT")parse_http_date("Sun Nov 6 08:49:37 1994")http_date(Sys.time())parse_http_date("Sun, 06 Nov 1994 08:49:37 GMT")parse_http_date("Sunday, 06-Nov-94 08:49:37 GMT")parse_http_date("Sun Nov 6 08:49:37 1994")http_date(Sys.time())
Seehttps://www.rfc-editor.org/rfc/rfc3986 for details of parsingalgorithm.
parse_url(url)build_url(url)parse_url(url)build_url(url)
url | For |
a list containing:
scheme
hostname
port
path
params
fragment
query, a list
username
password
parse_url("http://google.com/")parse_url("http://google.com:80/")parse_url("http://google.com:80/?a=1&b=2")url <- parse_url("http://google.com/")url$scheme <- "https"url$query <- list(q = "hello")build_url(url)parse_url("http://google.com/")parse_url("http://google.com:80/")parse_url("http://google.com:80/?a=1&b=2")url<- parse_url("http://google.com/")url$scheme<-"https"url$query<- list(q="hello")build_url(url)
Send PATCH request to a server.
PATCH( url = NULL, config = list(), ..., body = NULL, encode = c("multipart", "form", "json", "raw"), handle = NULL)PATCH( url=NULL, config= list(),..., body=NULL, encode= c("multipart","form","json","raw"), handle=NULL)
url | the url of the page to retrieve |
config | Additional configuration settings such as httpauthentication ( |
... | Further named parameters, such as |
body | One of the following:
|
encode | If the body is a named list, how should it be encoded? Can beone of form (application/x-www-form-urlencoded), multipart,(multipart/form-data), or json (application/json). For "multipart", list elements can be strings or objects created by |
handle | The handle to use with this request. If notsupplied, will be retrieved and reused from the |
Aresponse() object.
Other http methods:BROWSE(),DELETE(),GET(),HEAD(),POST(),PUT(),VERB()
POST file to a server.
POST( url = NULL, config = list(), ..., body = NULL, encode = c("multipart", "form", "json", "raw"), handle = NULL)POST( url=NULL, config= list(),..., body=NULL, encode= c("multipart","form","json","raw"), handle=NULL)
url | the url of the page to retrieve |
config | Additional configuration settings such as httpauthentication ( |
... | Further named parameters, such as |
body | One of the following:
|
encode | If the body is a named list, how should it be encoded? Can beone of form (application/x-www-form-urlencoded), multipart,(multipart/form-data), or json (application/json). For "multipart", list elements can be strings or objects created by |
handle | The handle to use with this request. If notsupplied, will be retrieved and reused from the |
Aresponse() object.
Other http methods:BROWSE(),DELETE(),GET(),HEAD(),PATCH(),PUT(),VERB()
## Not run: b2 <- "http://httpbin.org/post"POST(b2, body = "A simple text string")POST(b2, body = list(x = "A simple text string"))POST(b2, body = list(y = upload_file(system.file("CITATION"))))POST(b2, body = list(x = "A simple text string"), encode = "json")# body can also be provided as a json string directly to deal# with specific case, like an empty element in the json string.# passing as string directlyPOST(b2, body = '{"a":1,"b":{}}', encode = "raw")# or building the json string beforejson_body <- jsonlite::toJSON(list(a = 1, b = NULL), auto_unbox = TRUE)POST(b2, body = json_body, encode = "raw")# Various types of empty body:POST(b2, body = NULL, verbose())POST(b2, body = FALSE, verbose())POST(b2, body = "", verbose())## End(Not run)## Not run:b2<-"http://httpbin.org/post"POST(b2, body="A simple text string")POST(b2, body= list(x="A simple text string"))POST(b2, body= list(y= upload_file(system.file("CITATION"))))POST(b2, body= list(x="A simple text string"), encode="json")# body can also be provided as a json string directly to deal# with specific case, like an empty element in the json string.# passing as string directlyPOST(b2, body='{"a":1,"b":{}}', encode="raw")# or building the json string beforejson_body<- jsonlite::toJSON(list(a=1, b=NULL), auto_unbox=TRUE)POST(b2, body= json_body, encode="raw")# Various types of empty body:POST(b2, body=NULL, verbose())POST(b2, body=FALSE, verbose())POST(b2, body="", verbose())## End(Not run)
Add a progress bar.
progress(type = c("down", "up"), con = stdout())progress(type= c("down","up"), con= stdout())
type | Type of progress to display: either number of bytes uploadedor downloaded. |
con | Connection to send output too. Usually |
cap_speed <- config(max_recv_speed_large = 10000)## Not run: # If file size is known, you get a progress bar:x <- GET("http://httpbin.org/bytes/102400", progress(), cap_speed)# Otherwise you get the number of bytes downloaded:x <- GET("http://httpbin.org/stream-bytes/102400", progress(), cap_speed)## End(Not run)cap_speed<- config(max_recv_speed_large=10000)## Not run:# If file size is known, you get a progress bar:x<- GET("http://httpbin.org/bytes/102400", progress(), cap_speed)# Otherwise you get the number of bytes downloaded:x<- GET("http://httpbin.org/stream-bytes/102400", progress(), cap_speed)## End(Not run)
Send PUT request to server.
PUT( url = NULL, config = list(), ..., body = NULL, encode = c("multipart", "form", "json", "raw"), handle = NULL)PUT( url=NULL, config= list(),..., body=NULL, encode= c("multipart","form","json","raw"), handle=NULL)
url | the url of the page to retrieve |
config | Additional configuration settings such as httpauthentication ( |
... | Further named parameters, such as |
body | One of the following:
|
encode | If the body is a named list, how should it be encoded? Can beone of form (application/x-www-form-urlencoded), multipart,(multipart/form-data), or json (application/json). For "multipart", list elements can be strings or objects created by |
handle | The handle to use with this request. If notsupplied, will be retrieved and reused from the |
Other http methods:BROWSE(),DELETE(),GET(),HEAD(),PATCH(),POST(),VERB()
## Not run: POST("http://httpbin.org/put")PUT("http://httpbin.org/put")b2 <- "http://httpbin.org/put"PUT(b2, body = "A simple text string")PUT(b2, body = list(x = "A simple text string"))PUT(b2, body = list(y = upload_file(system.file("CITATION"))))PUT(b2, body = list(x = "A simple text string"), encode = "json")## End(Not run)## Not run:POST("http://httpbin.org/put")PUT("http://httpbin.org/put")b2<-"http://httpbin.org/put"PUT(b2, body="A simple text string")PUT(b2, body= list(x="A simple text string"))PUT(b2, body= list(y= upload_file(system.file("CITATION"))))PUT(b2, body= list(x="A simple text string"), encode="json")## End(Not run)
The response object captures all information from a request. It includesfields:
url the url the request was actually sent to (after redirects)
handle the handle associated with the url
status_code the http status code
header a named list of headers returned by the server
cookies a named list of cookies returned by the server
content the body of the response, as raw vector. Seecontent() for various ways to access the content.
time request timing information
config configuration for the request
For non-http(s) responses, some parts including the status andheader may not be interpretable the same way as http responses.
Other response methods:content(),http_error(),http_status(),stop_for_status()
Safely retry a request until it succeeds, as defined by theterminate_onparameter, which by default means a response for whichhttp_error()isFALSE. Will also retry on error conditions raised by the underlying curl code,but if the last retry still raises one,RETRY will raise it again withstop().It is designed to be kind to the server: after each failurerandomly waits up to twice as long. (Technically it uses exponentialbackoff with jitter, using the approach outlined inhttps://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/.)If the server returns status code 429 and specifies aretry-after value, thatvalue will be used instead, unless it's smaller thanpause_min.
RETRY( verb, url = NULL, config = list(), ..., body = NULL, encode = c("multipart", "form", "json", "raw"), times = 3, pause_base = 1, pause_cap = 60, pause_min = 1, handle = NULL, quiet = FALSE, terminate_on = NULL, terminate_on_success = TRUE)RETRY( verb, url=NULL, config= list(),..., body=NULL, encode= c("multipart","form","json","raw"), times=3, pause_base=1, pause_cap=60, pause_min=1, handle=NULL, quiet=FALSE, terminate_on=NULL, terminate_on_success=TRUE)
verb | Name of verb to use. |
url | the url of the page to retrieve |
config | Additional configuration settings such as httpauthentication ( |
... | Further named parameters, such as |
body | One of the following:
|
encode | If the body is a named list, how should it be encoded? Can beone of form (application/x-www-form-urlencoded), multipart,(multipart/form-data), or json (application/json). For "multipart", list elements can be strings or objects created by |
times | Maximum number of requests to attempt. |
pause_base,pause_cap | This method uses exponential back-off with fulljitter - this means that each request will randomly wait between |
pause_min | Minimum time to wait in the backoff; generallyonly necessary if you need pauses less than one second (which maynot be kind to the server, use with caution!). |
handle | The handle to use with this request. If notsupplied, will be retrieved and reused from the |
quiet | If |
terminate_on | Optional vector of numeric HTTP status codes that if foundon the response will terminate the retry process. If |
terminate_on_success | If |
The last response. Note that if the request doesn't succeed aftertimes times this will be a failed request, i.e. you still needto usestop_for_status().
## Not run: # Succeeds straight awayRETRY("GET", "http://httpbin.org/status/200")# Never succeedsRETRY("GET", "http://httpbin.org/status/500")# Invalid hostname generates curl error condition and is retried but eventually# raises an error condition.RETRY("GET", "http://invalidhostname/")## End(Not run)## Not run:# Succeeds straight awayRETRY("GET","http://httpbin.org/status/200")# Never succeedsRETRY("GET","http://httpbin.org/status/500")# Invalid hostname generates curl error condition and is retried but eventually# raises an error condition.RETRY("GET","http://invalidhostname/")## End(Not run)
Use this function if you think that your token may have been compromised,e.g. you accidentally uploaded the cache file to github. It's not possibleto automatically revoke all tokens - this function will warn when it can't.
revoke_all(cache_path = NA)revoke_all(cache_path=NA)
cache_path | Path to cache file. Defaults to |
Set (and reset) global httr configuration.
set_config(config, override = FALSE)reset_config()set_config(config, override=FALSE)reset_config()
config | Settings as generated by |
override | if |
invisibility, the old global config.
Other ways to set configuration:config(),with_config()
GET("http://google.com")set_config(verbose())GET("http://google.com")reset_config()GET("http://google.com")GET("http://google.com")set_config(verbose())GET("http://google.com")reset_config()GET("http://google.com")
Set cookies.
set_cookies(..., .cookies = character(0))set_cookies(..., .cookies= character(0))
... | a named cookie values |
.cookies | a named character vector |
cookies() to see cookies in response.
Other config:add_headers(),authenticate(),config(),timeout(),use_proxy(),user_agent(),verbose()
set_cookies(a = 1, b = 2)set_cookies(.cookies = c(a = "1", b = "2"))## Not run: GET("http://httpbin.org/cookies")GET("http://httpbin.org/cookies", set_cookies(a = 1, b = 2))## End(Not run)set_cookies(a=1, b=2)set_cookies(.cookies= c(a="1", b="2"))## Not run:GET("http://httpbin.org/cookies")GET("http://httpbin.org/cookies", set_cookies(a=1, b=2))## End(Not run)
Extract status code from response.
status_code(x)status_code(x)
x | A response |
Converts http errors to R errors or warnings - these should alwaysbe used whenever you're creating requests inside a function, sothat the user knows why a request has failed.
stop_for_status(x, task = NULL)warn_for_status(x, task = NULL)message_for_status(x, task = NULL)stop_for_status(x, task=NULL)warn_for_status(x, task=NULL)message_for_status(x, task=NULL)
x | a response, or numeric http code (or other object with |
task | The text of the message: either |
If request was successful, the response (invisibly). Otherwise,raised a classed http error or warning, as generated byhttp_condition()
http_status() andhttp://en.wikipedia.org/wiki/Http_status_codes for more informationon http status codes.
Other response methods:content(),http_error(),http_status(),response()
## Not run: x <- GET("http://httpbin.org/status/200")stop_for_status(x) # nothing happenswarn_for_status(x)message_for_status(x)x <- GET("http://httpbin.org/status/300")stop_for_status(x)warn_for_status(x)message_for_status(x)x <- GET("http://httpbin.org/status/404")stop_for_status(x)warn_for_status(x)message_for_status(x)# You can provide more information with the task argumentwarn_for_status(x, "download spreadsheet")message_for_status(x, "download spreadsheet")## End(Not run)## Not run:x<- GET("http://httpbin.org/status/200")stop_for_status(x)# nothing happenswarn_for_status(x)message_for_status(x)x<- GET("http://httpbin.org/status/300")stop_for_status(x)warn_for_status(x)message_for_status(x)x<- GET("http://httpbin.org/status/404")stop_for_status(x)warn_for_status(x)message_for_status(x)# You can provide more information with the task argumentwarn_for_status(x,"download spreadsheet")message_for_status(x,"download spreadsheet")## End(Not run)
Set maximum request time.
timeout(seconds)timeout(seconds)
seconds | number of seconds to wait for a response until giving up.Can not be less than 1 ms. |
This timeout is passed on tocurl::handle_setopt().See there andcurl::curl_options() for more details.
Other config:add_headers(),authenticate(),config(),set_cookies(),use_proxy(),user_agent(),verbose()
## Not run: GET("http://httpbin.org/delay/3", timeout(1))GET("http://httpbin.org/delay/1", timeout(2))## End(Not run)## Not run:GET("http://httpbin.org/delay/3", timeout(1))GET("http://httpbin.org/delay/1", timeout(2))## End(Not run)
POST() orPUT().Upload a file withPOST() orPUT().
upload_file(path, type = NULL)upload_file(path, type=NULL)
path | path to file |
type | mime type of path. If not supplied, will be guess by |
citation <- upload_file(system.file("CITATION"))## Not run: POST("http://httpbin.org/post", body = citation)POST("http://httpbin.org/post", body = list(y = citation))## End(Not run)citation<- upload_file(system.file("CITATION"))## Not run:POST("http://httpbin.org/post", body= citation)POST("http://httpbin.org/post", body= list(y= citation))## End(Not run)
Use a proxy to connect to the internet.
use_proxy(url, port = NULL, username = NULL, password = NULL, auth = "basic")use_proxy(url, port=NULL, username=NULL, password=NULL, auth="basic")
url,port | location of proxy |
username,password | login details for proxy, if needed |
auth | type of HTTP authentication to use. Should be one of thefollowing: basic, digest, digest_ie, gssnegotiate, ntlm, any. |
Other config:add_headers(),authenticate(),config(),set_cookies(),timeout(),user_agent(),verbose()
# See http://www.hidemyass.com/proxy-list for a list of public proxies# to test with# GET("http://had.co.nz", use_proxy("64.251.21.73", 8080), verbose())# See http://www.hidemyass.com/proxy-list for a list of public proxies# to test with# GET("http://had.co.nz", use_proxy("64.251.21.73", 8080), verbose())
Override the default RCurl user agent ofNULL
user_agent(agent)user_agent(agent)
agent | string giving user agent |
Other config:add_headers(),authenticate(),config(),set_cookies(),timeout(),use_proxy(),verbose()
## Not run: GET("http://httpbin.org/user-agent")GET("http://httpbin.org/user-agent", user_agent("httr"))## End(Not run)## Not run:GET("http://httpbin.org/user-agent")GET("http://httpbin.org/user-agent", user_agent("httr"))## End(Not run)
Use an arbitrary verb.
VERB( verb, url = NULL, config = list(), ..., body = NULL, encode = c("multipart", "form", "json", "raw"), handle = NULL)VERB( verb, url=NULL, config= list(),..., body=NULL, encode= c("multipart","form","json","raw"), handle=NULL)
verb | Name of verb to use. |
url | the url of the page to retrieve |
config | Additional configuration settings such as httpauthentication ( |
... | Further named parameters, such as |
body | One of the following:
|
encode | If the body is a named list, how should it be encoded? Can beone of form (application/x-www-form-urlencoded), multipart,(multipart/form-data), or json (application/json). For "multipart", list elements can be strings or objects created by |
handle | The handle to use with this request. If notsupplied, will be retrieved and reused from the |
Aresponse() object.
Other http methods:BROWSE(),DELETE(),GET(),HEAD(),PATCH(),POST(),PUT()
r <- VERB( "PROPFIND", "http://svn.r-project.org/R/tags/", add_headers(depth = 1), verbose())stop_for_status(r)content(r)## Not run: VERB("POST", url = "http://httpbin.org/post")VERB("POST", url = "http://httpbin.org/post", body = "foobar")## End(Not run)r<- VERB("PROPFIND","http://svn.r-project.org/R/tags/", add_headers(depth=1), verbose())stop_for_status(r)content(r)## Not run:VERB("POST", url="http://httpbin.org/post")VERB("POST", url="http://httpbin.org/post", body="foobar")## End(Not run)
A verbose connection provides much more information about the flow ofinformation between the client and server.
verbose(data_out = TRUE, data_in = FALSE, info = FALSE, ssl = FALSE)verbose(data_out=TRUE, data_in=FALSE, info=FALSE, ssl=FALSE)
data_out | Show data sent to the server. |
data_in | Show data recieved from the server. |
info | Show informational text from curl. This is mainly usefulfor debugging https and auth problems, so is disabled by default. |
ssl | Show even data sent/recieved over SSL connections? |
verbose() uses the following prefixes to distinguish betweendifferent components of the http messages:
* informative curl messages
-> headers sent (out)
>> data sent (out)
*> ssl data sent (out)
<- headers received (in)
<< data received (in)
<* ssl data received (in)
with_verbose() makes it easier to use verbose modeeven when the requests are buried inside another function call.
Other config:add_headers(),authenticate(),config(),set_cookies(),timeout(),use_proxy(),user_agent()
## Not run: GET("http://httpbin.org", verbose())GET("http://httpbin.org", verbose(info = TRUE))f <- function() { GET("http://httpbin.org")}with_verbose(f())with_verbose(f(), info = TRUE)# verbose() makes it easy to see exactly what POST requests sendPOST_verbose <- function(body, ...) { POST("https://httpbin.org/post", body = body, verbose(), ...) invisible()}POST_verbose(list(x = "a", y = "b"))POST_verbose(list(x = "a", y = "b"), encode = "form")POST_verbose(FALSE)POST_verbose(NULL)POST_verbose("")POST_verbose("xyz")## End(Not run)## Not run:GET("http://httpbin.org", verbose())GET("http://httpbin.org", verbose(info=TRUE))f<-function(){ GET("http://httpbin.org")}with_verbose(f())with_verbose(f(), info=TRUE)# verbose() makes it easy to see exactly what POST requests sendPOST_verbose<-function(body,...){ POST("https://httpbin.org/post", body= body, verbose(),...) invisible()}POST_verbose(list(x="a", y="b"))POST_verbose(list(x="a", y="b"), encode="form")POST_verbose(FALSE)POST_verbose(NULL)POST_verbose("")POST_verbose("xyz")## End(Not run)
Execute code with configuration set.
with_config(config = config(), expr, override = FALSE)with_verbose(expr, ...)with_config(config= config(), expr, override=FALSE)with_verbose(expr,...)
config | Settings as generated by |
expr | code to execute under specified configuration |
override | if |
... | Other arguments passed on to |
Other ways to set configuration:config(),set_config()
with_config(verbose(), { GET("http://had.co.nz") GET("http://google.com")})# Or even easier:with_verbose(GET("http://google.com"))with_config(verbose(),{ GET("http://had.co.nz") GET("http://google.com")})# Or even easier:with_verbose(GET("http://google.com"))
The default behaviour is to usewrite_memory(), which cachesthe response locally in memory. This is useful when talking to APIs asit avoids a round-trip to disk. If you want to save a file that's biggerthan memory, usewrite_disk() to save it to a known path.
write_disk(path, overwrite = FALSE)write_memory()write_disk(path, overwrite=FALSE)write_memory()
path | Path to content to. |
overwrite | Will only overwrite existing |
tmp <- tempfile()r1 <- GET("https://www.google.com", write_disk(tmp))readLines(tmp)# The defaultr2 <- GET("https://www.google.com", write_memory())# Save a very large file## Not run: GET( "http://www2.census.gov/acs2011_5yr/pums/csv_pus.zip", write_disk("csv_pus.zip"), progress())## End(Not run)tmp<- tempfile()r1<- GET("https://www.google.com", write_disk(tmp))readLines(tmp)# The defaultr2<- GET("https://www.google.com", write_memory())# Save a very large file## Not run:GET("http://www2.census.gov/acs2011_5yr/pums/csv_pus.zip", write_disk("csv_pus.zip"), progress())## End(Not run)
This is the most general way of processing the response from the server -you receive the raw bytes as they come in, and you can do whatever you wantwith them.
write_stream(f)write_stream(f)
f | Callback function. It should have a single argument, a rawvector containing the bytes recieved from the server. This will usuallybe 16k or less. The return value of the function is ignored. |
GET( "https://github.com/jeroen/data/raw/gh-pages/diamonds.json", write_stream(function(x) { print(length(x)) length(x) }))GET("https://github.com/jeroen/data/raw/gh-pages/diamonds.json", write_stream(function(x){ print(length(x)) length(x)}))