Movatterモバイル変換

httr makes http easy.

Description

httr is organised around the six most common http verbs:GET(),PATCH(),POST(),HEAD(),PUT(), andDELETE().

Details

Each request returns aresponse() object which provideseasy access to status code, cookies, headers, timings, and other usefulinfo. The content of the request is available as a raw vector(content()), character vector (text_content()),or parsed into an R object (parsed_content()), currently forhtml, xml, json, png and jpeg).

Requests can be modified by various config options likeset_cookies(),add_headers(),authenticate(),use_proxy(),verbose(), andtimeout()

httr supports OAuth 1.0 and 2.0. Useoauth1.0_token() andoauth2.0_token() to get user tokens, andsign_oauth1.0() andsign_oauth2.0() to signrequests. The demos directory has twelve demos of using OAuth: four for 1.0(linkedin, twitter, vimeo, and yahoo) and eight for 2.0 (azure, facebook,github, google, linkedin, reddit, yahoo, and yelp).

Author(s)

Maintainer: Hadley Wickhamhadley@posit.co

Other contributors:

• Posit, PBC [copyright holder, funder]

See Also

Useful links:

• https://httr.r-lib.org/

• https://github.com/r-lib/httr

• Report bugs athttps://github.com/r-lib/httr/issues

Open specified url in browser.

Description

(This isn't really a http verb, but it seems to follow the same format).

Usage

BROWSE(url = NULL, config = list(), ..., handle = NULL)

Arguments

Details

Only works in interactive sessions.

Value

Aresponse() object.

See Also

Other http methods:DELETE(),GET(),HEAD(),PATCH(),POST(),PUT(),VERB()

Examples

BROWSE("http://google.com")BROWSE("http://had.co.nz")

Send a DELETE request.

Description

Send a DELETE request.

Usage

DELETE(  url = NULL,  config = list(),  ...,  body = NULL,  encode = c("multipart", "form", "json", "raw"),  handle = NULL)

Arguments

Value

Aresponse() object.

RFC2616

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.

See Also

Other http methods:BROWSE(),GET(),HEAD(),PATCH(),POST(),PUT(),VERB()

Examples

## Not run: DELETE("http://httpbin.org/delete")POST("http://httpbin.org/delete")## End(Not run)

GET a url.

Description

GET a url.

Usage

GET(url = NULL, config = list(), ..., handle = NULL)

Arguments

Value

Aresponse() object.

RFC2616

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.

See Also

Other http methods:BROWSE(),DELETE(),HEAD(),PATCH(),POST(),PUT(),VERB()

Examples

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 url HEADers.

Description

Get url HEADers.

Usage

HEAD(url = NULL, config = list(), ..., handle = NULL)

Arguments

Value

Aresponse() object.

RFC2616

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.

See Also

Other http methods:BROWSE(),DELETE(),GET(),PATCH(),POST(),PUT(),VERB()

Examples

HEAD("http://google.com")headers(HEAD("http://google.com"))

Send PATCH request to a server.

Description

Send PATCH request to a server.

Usage

PATCH(  url = NULL,  config = list(),  ...,  body = NULL,  encode = c("multipart", "form", "json", "raw"),  handle = NULL)

Arguments

Value

Aresponse() object.

See Also

Other http methods:BROWSE(),DELETE(),GET(),HEAD(),POST(),PUT(),VERB()

POST file to a server.

Description

POST file to a server.

Usage

POST(  url = NULL,  config = list(),  ...,  body = NULL,  encode = c("multipart", "form", "json", "raw"),  handle = NULL)

Arguments

Value

Aresponse() object.

See Also

Other http methods:BROWSE(),DELETE(),GET(),HEAD(),PATCH(),PUT(),VERB()

Examples

## 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)

Send PUT request to server.

Description

Send PUT request to server.

Usage

PUT(  url = NULL,  config = list(),  ...,  body = NULL,  encode = c("multipart", "form", "json", "raw"),  handle = NULL)

Arguments

See Also

Other http methods:BROWSE(),DELETE(),GET(),HEAD(),PATCH(),POST(),VERB()

Examples

## 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)

Retry a request until it succeeds.

Description

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.

Usage

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)

Arguments

Value

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().

Examples

## 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)

OAuth token objects.

Description

These objects represent the complete set of data needed for OAuth access:an app, an endpoint, cached credentials and parameters. They should becreated through their constructor functionsoauth1.0_token()andoauth2.0_token().

Format

An R6 class object.

Methods

• cache(): caches token to disk

• sign(method, url): returns list of url and config

• refresh(): refresh access token (if possible)

• validate(): TRUE if the token is still valid, FALSE otherwise

Caching

OAuth tokens are cached on disk in a file called.httr-oauthsaved in the current working directory. Caching is enabled if:

• The session is interactive, and the user agrees to it, OR

• The.httr-oauth file is already present, OR

• getOption("httr_oauth_cache") isTRUE

You can suppress caching by setting thehttr_oauth_cache option toFALSE.

Tokens are cached based on their endpoint and parameters.

The cache file should not be included in source code control or R packages(because it contains private information), so httr will automatically addthe appropriate entries to.gitignore and.Rbuildignore if needed.

VERB a url.

Description

Use an arbitrary verb.

Usage

VERB(  verb,  url = NULL,  config = list(),  ...,  body = NULL,  encode = c("multipart", "form", "json", "raw"),  handle = NULL)

Arguments

Value

Aresponse() object.

See Also

Other http methods:BROWSE(),DELETE(),GET(),HEAD(),PATCH(),POST(),PUT()

Examples

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)

Add additional headers to a request.

Description

Wikipedia provides a useful list of common http headers:https://en.wikipedia.org/wiki/List_of_HTTP_header_fields.

Usage

add_headers(..., .headers = character())

Arguments

See Also

accept() andcontent_type() forconvenience functions for setting accept and content-type headers.

Other config:authenticate(),config(),set_cookies(),timeout(),use_proxy(),user_agent(),verbose()

Examples

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)

Use http authentication.

Description

It's not obvious how to turn authentication off after using it, soI recommend using custom handles with authentication.

Usage

authenticate(user, password, type = "basic")

Arguments

See Also

Other config:add_headers(),config(),set_cookies(),timeout(),use_proxy(),user_agent(),verbose()

Examples

## Not run: GET("http://httpbin.org/basic-auth/user/passwd")GET(  "http://httpbin.org/basic-auth/user/passwd",  authenticate("user", "passwd"))## End(Not run)

Compute caching information for a response.

Description

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).

Usage

cache_info(r)rerequest(r)

Arguments

Examples

# 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)

Set curl options.

Description

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().

Usage

config(..., token = NULL)

Arguments

Details

Unlike Curl (and RCurl), all configuration options are per request, notper handle.

See Also

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()

Examples

# 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))

Extract content from a request.

Description

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.

Usage

content(x, as = NULL, type = NULL, encoding = NULL, ...)

Arguments

Details

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.

Value

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.

WARNING

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.

See Also

Other response methods:http_error(),http_status(),response(),stop_for_status()

Examples

## 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)

Set content-type and accept headers.

Description

These are convenient wrappers aroudadd_headers().

Usage

content_type(type)content_type_json()content_type_xml()accept(type)accept_json()accept_xml()

Arguments

Details

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.

Examples

## 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.

Description

Access cookies in a response.

Usage

cookies(x)

Arguments

See Also

set_cookies() to send cookies in request.

Examples

## Not run: r <- GET("http://httpbin.org/cookies/set", query = list(a = 1, b = 2))cookies(r)## End(Not run)

Install or uninstall a callback function

Description

Supported callback functions:

‘request’

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.

‘response’

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.

Usage

get_callback(name)set_callback(name, new_callback = NULL)

Arguments

Details

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.

Value

get_callback returns the currently installedcallback, orNULL if none is installed.

set_callback returns the previously installed callback,orNULL if none was installed.

Examples

## 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)

Guess the media type of a path from its extension.

Description

DEPRECATED: please usemime::guess_type instead.

Usage

guess_media(x)

Arguments

Create a handle tied to a particular host.

Description

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.

Usage

handle(url, cookies = TRUE)

Arguments

Note

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()).

Examples

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)

Maintain a pool of handles.

Description

The handle pool is used to automatically reuse Curl handles for the samescheme/host/port combination. This ensures that the http session isautomatically reused, and cookies are maintained across requests to a sitewithout user intervention.

Usage

handle_poolhandle_find(url)handle_reset(url)

Format

An environment.

Does the request have content associated with it?

Description

Does the request have content associated with it?

Usage

has_content(x)

Examples

## Not run: has_content(POST("http://httpbin.org/post", body = FALSE))has_content(HEAD("http://httpbin.org/headers"))## End(Not run)

Extract the headers from a response

Description

Extract the headers from a response

Usage

headers(x)

Arguments

See Also

add_headers() to send additional headers in arequest

Examples

## Not run: r <- GET("http://httpbin.org/get")headers(r)## End(Not run)

HMAC SHA1

Description

As described inhttps://datatracker.ietf.org/doc/rfc2104/.

Usage

hmac_sha1(key, string)

Arguments

Generate a classed http condition.

Description

This function generate S3 condition objects which are passed tostop() orwarning() to generate classes warningsand error. These can be used in conjunction withtryCatch()to respond differently to different type of failure.

Usage

http_condition(x, type, task = NULL, call = sys.call(-1))

Arguments

Value

An S3 object that inherits from (e.g.) condition,type,http_error, http_400 and http_404.

See Also

http://adv-r.had.co.nz/Exceptions-Debugging.html#condition-handlingfor more details about R's condition handling model

Examples

## Not run: # You can use tryCatch to take different actions based on the type# of error. Note that tryCatch will call the first handler that# matches any classes of the condition, not the best matching, so# always list handlers from most specific to least specificf <- function(url) {  tryCatch(stop_for_status(GET(url)),    http_404 = function(c) "That url doesn't exist",    http_403 = function(c) "You need to authenticate!",    http_400 = function(c) "You made a mistake!",    http_500 = function(c) "The server screwed up"  )}f("http://httpbin.org/status/404")f("http://httpbin.org/status/403")f("http://httpbin.org/status/505")## End(Not run)

Check for an http error.

Description

Check for an http error.

Usage

http_error(x, ...)

Arguments

Value

TRUE if the request fails (status code 400 or above),otherwiseFALSE.

See Also

Other response methods:content(),http_status(),response(),stop_for_status()

Examples

## 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)

Give information on the status of a request.

Description

Extract the http status code and convert it into a human readable message.

Usage

http_status(x)

Arguments

Details

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 at⁠http://en.wikipedia.org/wiki/Http_error_codes⁠.

Value

If the status code does not match a known status, an error.Otherwise, a list with components

See Also

Other response methods:content(),http_error(),response(),stop_for_status()

Examples

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

Description

Extract the content type of a response

Usage

http_type(x)

Arguments

Value

A string giving the complete mime type, with all parametersstripped off.

Examples

## 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)

Diagnose common configuration problems

Description

Currently one check: that curl uses nss.

Usage

httr_dr()

List available options.

Description

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.

Usage

httr_options(matches)curl_docs(x)

Arguments

Details

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".

Value

A data frame with three columns:

Examples

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")

Retrieve OAuth 1.0 access token.

Description

See demos for use.

Usage

init_oauth1.0(  endpoint,  app,  permission = NULL,  is_interactive = interactive(),  private_key = NULL)

Arguments

Retrieve OAuth 2.0 access token.

Description

See demos for use.

Usage

init_oauth2.0(  endpoint,  app,  scope = NULL,  user_params = NULL,  type = NULL,  use_oob = getOption("httr_oob_default"),  oob_value = NULL,  is_interactive = interactive(),  use_basic_auth = FALSE,  config_init = list(),  client_credentials = FALSE,  query_authorize_extra = list())oauth2.0_authorize_url(  endpoint,  app,  scope,  redirect_uri = app$redirect_uri,  state = nonce(),  query_extra = list())oauth2.0_access_token(  endpoint,  app,  code,  user_params = NULL,  type = NULL,  use_basic_auth = FALSE,  redirect_uri = app$redirect_uri,  client_credentials = FALSE,  config = list())

Arguments

Create a vector with case insensitive name matching.

Description

Create a vector with case insensitive name matching.

Usage

insensitive(x)

Arguments

Examples

x <- c("abc" = 1, "def" = 2)x["ABC"]y <- insensitive(x)y["ABC"]y[["ABC"]]

Generate a JWT signature given credentials.

Description

As described inhttps://developers.google.com/identity/protocols/oauth2/service-account

Usage

jwt_signature(  credentials,  scope,  aud,  sub = NULL,  iat = as.integer(Sys.time()),  exp = iat + duration,  duration = 60L * 60L)

Arguments

Examples

## Not run: cred <- jsonlite::fromJSON("~/Desktop/httrtest-45693cbfac92.json")jwt_signature(cred, "https://www.googleapis.com/auth/userinfo.profile")## End(Not run)

Modify a url.

Description

Modify a url by first parsing it and then replacing components withthe non-NULL arguments of this function.

Usage

modify_url(  url,  scheme = NULL,  hostname = NULL,  port = NULL,  path = NULL,  query = NULL,  params = NULL,  fragment = NULL,  username = NULL,  password = NULL)

Arguments

Generate an oauth1.0 token.

Description

This is the final object in the OAuth dance - it encapsulates the app,the endpoint, other parameters and the received credentials.

Usage

oauth1.0_token(  endpoint,  app,  permission = NULL,  as_header = TRUE,  private_key = NULL,  cache = getOption("httr_oauth_cache"))

Arguments

Details

SeeToken() for full details about the token object, and thecaching policies used to store credentials across sessions.

Value

AToken1.0 reference class (RC) object.

See Also

Other OAuth:oauth2.0_token(),oauth_app(),oauth_endpoint(),oauth_service_token()

Generate an oauth2.0 token.

Description

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.

Usage

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())

Arguments

Details

SeeToken() for full details about the token object, and thecaching policies used to store credentials across sessions.

Value

AToken2.0 reference class (RC) object.

See Also

Other OAuth:oauth1.0_token(),oauth_app(),oauth_endpoint(),oauth_service_token()

Create an OAuth application.

Description

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.

Usage

oauth_app(appname, key, secret = NULL, redirect_uri = oauth_callback())

Arguments

See Also

Other OAuth:oauth1.0_token(),oauth2.0_token(),oauth_endpoint(),oauth_service_token()

Examples

## Not run: google_app <- oauth_app(  "google",  key = "123456789.apps.googleusercontent.com",  secret = "abcdefghijklmnopqrstuvwxyz")## End(Not run)

The oauth callback url.

Description

The url thatoauth_listener() expects that the client bereferred to.

Usage

oauth_callback()

Describe an OAuth endpoint.

Description

Seeoauth_endpoints() for a list of popular OAuth endpointsbaked into httr.

Usage

oauth_endpoint(request = NULL, authorize, access, ..., base_url = NULL)

Arguments

See Also

Other OAuth:oauth1.0_token(),oauth2.0_token(),oauth_app(),oauth_service_token()

Examples

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_endpoints

Popular oauth endpoints.

Description

Provides some common OAuth endpoints.

Usage

oauth_endpoints(name)

Arguments

Examples

oauth_endpoints("twitter")

Walk the user through the OAuth2 dance without a local webserver.

Description

This performs a similar function tooauth_listener(),but without running a local webserver. This manual process can be usefulin situations where the user is remotely accessing the machine outside abrowser (say via ssh) or when it's not possible to successfully receive acallback (such as when behind a firewall).

Usage

oauth_exchanger(request_url)

Arguments

Details

This function should generally not be called directly by the user.

Create a webserver to listen for OAuth callback.

Description

This opens a web browser pointing torequest_url, and opens awebserver on port 1410 to listen to the reponse. The redirect url shouldeither be set previously (during the OAuth authentication dance) orsupplied as a parameter to the url. Seeoauth1.0_token() andoauth2.0_token() for examples of both techniques.

Usage

oauth_listener(request_url, is_interactive = interactive())

Arguments

Details

This function should not normally be called directly by the user.

Generate OAuth token for service accounts.

Description

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.

Usage

oauth_service_token(endpoint, secrets, scope = NULL, sub = NULL)

Arguments

See Also

Other OAuth:oauth1.0_token(),oauth2.0_token(),oauth_app(),oauth_endpoint()

Examples

## 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)

Generate oauth signature.

Description

For advanced use only. Occassionally needed for sites that use somecomponents of the OAuth spec, but not all of them (e.g. 2-legged oauth)

Usage

oauth_signature(  url,  method = "GET",  app,  token = NULL,  token_secret = NULL,  private_key = NULL,  other_params = NULL)oauth_header(info)

Arguments

Value

A list of oauth parameters.

Parse and print http dates.

Description

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

Usage

parse_http_date(x, failure = structure(NA_real_, class = "Date"))http_date(x)

Arguments

Value

A POSIXct object if succesful, otherwisefailure

Examples

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 a media type.

Description

Parsed according to RFC 2616, as athttps://www.rfc-editor.org/rfc/rfc2616#section-3.7.

Usage

parse_media(x)

Arguments

Details

A simplified minimal EBNF is:

• media-type =⁠type "/" subtype *( ";" parameter )⁠

• type =token

• subtype =token

• parameter =⁠attribute "=" value⁠

• attribute =token

• value =token | quoted-string

• token =⁠1*<any CHAR except CTLs or ()<>@,;:\"/[]?=\{\}⁠

Examples

parse_media("text/plain")parse_media("text/plain; charset=utf-8")parse_media("text/plain; charset=\"utf-8\"")parse_media("text/plain; randomparam=\";=;=\"")

Parse and build urls according to RFC3986.

Description

Seehttps://www.rfc-editor.org/rfc/rfc3986 for details of parsingalgorithm.

Usage

parse_url(url)build_url(url)

Arguments

Value

a list containing:

• scheme

• hostname

• port

• path

• params

• fragment

• query, a list

• username

• password

Examples

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)

Add a progress bar.

Description

Add a progress bar.

Usage

progress(type = c("down", "up"), con = stdout())

Arguments

Examples

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)

The response object.

Description

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

Details

For non-http(s) responses, some parts including the status andheader may not be interpretable the same way as http responses.

See Also

Other response methods:content(),http_error(),http_status(),stop_for_status()

Revoke all OAuth tokens in the cache.

Description

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.

Usage

revoke_all(cache_path = NA)

Arguments

Set (and reset) global httr configuration.

Description

Set (and reset) global httr configuration.

Usage

set_config(config, override = FALSE)reset_config()

Arguments

Value

invisibility, the old global config.

See Also

Other ways to set configuration:config(),with_config()

Examples

GET("http://google.com")set_config(verbose())GET("http://google.com")reset_config()GET("http://google.com")

Set cookies.

Description

Set cookies.

Usage

set_cookies(..., .cookies = character(0))

Arguments

See Also

cookies() to see cookies in response.

Other config:add_headers(),authenticate(),config(),timeout(),use_proxy(),user_agent(),verbose()

Examples

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)

SHA1 hash

Description

Creates a SHA1 hash of data using either HMAC or RSA.

Usage

sha1_hash(key, string, method = "HMAC-SHA1")

Arguments

Sign an OAuth request

Description

Deprecated. Instead create a config object directly usingconfig(token = my_token).

Usage

sign_oauth1.0(app, token = NULL, token_secret = NULL, as_header = TRUE, ...)sign_oauth2.0(access_token, as_header = TRUE)

Extract status code from response.

Description

Extract status code from response.

Usage

status_code(x)

Arguments

Take action on http error.

Description

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.

Usage

stop_for_status(x, task = NULL)warn_for_status(x, task = NULL)message_for_status(x, task = NULL)

Arguments

Value

If request was successful, the response (invisibly). Otherwise,raised a classed http error or warning, as generated byhttp_condition()

See Also

http_status() and⁠http://en.wikipedia.org/wiki/Http_status_codes⁠ for more informationon http status codes.

Other response methods:content(),http_error(),http_status(),response()

Examples

## 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.

Description

Set maximum request time.

Usage

timeout(seconds)

Arguments

Details

This timeout is passed on tocurl::handle_setopt().See there andcurl::curl_options() for more details.

See Also

Other config:add_headers(),authenticate(),config(),set_cookies(),use_proxy(),user_agent(),verbose()

Examples

## Not run: GET("http://httpbin.org/delay/3", timeout(1))GET("http://httpbin.org/delay/1", timeout(2))## End(Not run)

Upload a file withPOST() orPUT().

Description

Upload a file withPOST() orPUT().

Usage

upload_file(path, type = NULL)

Arguments

Examples

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.

Description

Use a proxy to connect to the internet.

Usage

use_proxy(url, port = NULL, username = NULL, password = NULL, auth = "basic")

Arguments

See Also

Other config:add_headers(),authenticate(),config(),set_cookies(),timeout(),user_agent(),verbose()

Examples

# 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())

Set user agent.

Description

Override the default RCurl user agent ofNULL

Usage

user_agent(agent)

Arguments

See Also

Other config:add_headers(),authenticate(),config(),set_cookies(),timeout(),use_proxy(),verbose()

Examples

## Not run: GET("http://httpbin.org/user-agent")GET("http://httpbin.org/user-agent", user_agent("httr"))## End(Not run)

Give verbose output.

Description

A verbose connection provides much more information about the flow ofinformation between the client and server.

Usage

verbose(data_out = TRUE, data_in = FALSE, info = FALSE, ssl = FALSE)

Arguments

Prefixes

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)

See Also

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()

Examples

## 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.

Description

Execute code with configuration set.

Usage

with_config(config = config(), expr, override = FALSE)with_verbose(expr, ...)

Arguments

See Also

Other ways to set configuration:config(),set_config()

Examples

with_config(verbose(), {  GET("http://had.co.nz")  GET("http://google.com")})# Or even easier:with_verbose(GET("http://google.com"))

Control where the response body is written.

Description

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.

Usage

write_disk(path, overwrite = FALSE)write_memory()

Arguments

Examples

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)

S3 object to define response writer.

Description

This S3 object allows you to control how the response body is saved.

Usage

write_function(subclass, ...)

Arguments

Process output in a streaming manner.

Description

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.

Usage

write_stream(f)

Arguments

Examples

GET(  "https://github.com/jeroen/data/raw/gh-pages/diamonds.json",  write_stream(function(x) {    print(length(x))    length(x)  }))