Swiftpack.co - Package - r-lib/httr

httr

Build Status Coverage Status CRAN_Status_Badge

The aim of httr is to provide a wrapper for the curl package, customised to the demands of modern web APIs.

Key features:

  • Functions for the most important http verbs: GET(), HEAD(), PATCH(), PUT(), DELETE() and POST().

  • Automatic connection sharing across requests to the same website (by default, curl handles are managed automatically), cookies are maintained across requests, and a up-to-date root-level SSL certificate store is used.

  • Requests return a standard reponse object that captures the http status line, headers and body, along with other useful information.

    • Response content is available with content() as a raw vector (as = "raw"), a character vector (as = "text"), or parsed into an R object (as = "parsed"), currently for html, xml, json, png and jpeg.

    • You can convert http errors into R errors with stop_for_status().

  • Config functions make it easier to modify the request in common ways: set_cookies(), add_headers(), authenticate(), use_proxy(), verbose(), timeout(), content_type(), accept(), progress().

  • Support for OAuth 1.0 and 2.0 with oauth1.0_token() and oauth2.0_token(). The demo directory has eight OAuth demos: four for 1.0 (twitter, vimeo, withings and yahoo) and four for 2.0 (facebook, github, google, linkedin). OAuth credentials are automatically cached within a project.

httr wouldn't be possible without the hard work of the authors of curl and libcurl. Thanks! httr is inspired by http libraries in other languages, such as Resty, Requests and httparty.

Installation

To get the current released version from CRAN:

install.packages("httr")

To get the current development version from github:

# install.packages("devtools")
devtools::install_github("r-lib/httr")

Github

link
Stars: 675
Help us keep the lights on

Dependencies

Used By

Total: 0

Releases

v1.3.1 - Aug 21, 2017

  • Re-enable on-disk caching (accidentally disabled in #457) (#475)

v1.3.0 - Aug 16, 2017

API changes

  • Deprecated safe_callback() has been removed.

  • is_interactive argument to init_oauth1.0(), init_oauth2.0() and oauth_listener() has been deprecated, as the R session does not actually need to be interactive.

New features

  • New set_callback() and get_callback() set and query callback functions that are called right before and after performing an HTTP request (@gaborcsardi, #409)

  • RETRY() now retries if an error occurs during the request (@asieira, #404), and gains two new arguments:

    • terminate_on gives you greater control over which status codes should it stop retrying. (@asieira, #404)

    • pause_min allows for sub-second delays. (Use with caution! Generally the default is preferred.) (@r2evans)

    • If the server returns HTTP status code 429 and specifies a retry-after value, that value will now be used instead of exponential backoff with jitter, unless it's smaller than pause_min. (@nielsoledam, #472)

OAuth

  • New oauth cache files are always added to .gitignore and, if it exists, .Rbuildignore. Specifically, this now happens when option httr_oauth_cache = TRUE or user specifies cache file name explicitly. (@jennybc, #436)

  • oauth_encode() now handles UTF-8 characters correctly. (@yutannihilation, #424)

  • oauth_app() allows you to specify the redirect_url if you need to customise it.

  • oauth_service_token() gains a sub parameter so you can request access on behalf of another user (#410), and accepts a character vector of scopes as was described in the documentation (#389).

  • oauth_signature() now normalises the URL as described in the OAuth1.0a spec (@leeper, #435)

  • New oauth2.0_authorize_url() and oauth2.0_access_token() functions pull out parts of the OAuth process for reuse elsewhere (#457).

  • oauth2.0_token() gains three new arguments:

    • config_init allows you to supply additional config for the initial request. This is needed for some APIs (e.g. reddit) which rate limit based on user_agent (@muschellij2, #363).

    • client_credentials, allows you to use the OAauth2 Client Credential Grant. See RFC 6749 for details. (@cderv, #384)

    • A credentials argument that allows you to customise the auth flow. For advanced used only (#457)

  • is_interactive argument to init_oauth1.0(), init_oauth2.0() and oauth_listener() has been deprecated, as the R session does not need to be interactive.

Minor bug fixes and improvements

  • BROWSER() prints a message telling you to browse to the URL if called in a non-interactive session.

  • find_cert_bundle() will now correctly find cert bundle in "R_HOME/etc" (@jiwalker-usgs, #386).

  • You can now send lists containing curl::form_data() in the body of requests with `encoding = "multipart". This makes it possible to specify the mime-type of individual components (#430).

  • modify_url() recognised more forms of empty queries. This eliminates a source of spurious trailing ? and ?= (@jennybc, #452)

  • More forms of empty query are recognized as such. Eliminates a source of spurious trailing ? and ?= in URLs produced by modify_url(). (@jennybc, #452)

  • The length() method of the internal path class is no longer exported (#395).

v1.2.1 - Jul 3, 2016

  • Fix bug with new cache creation code: need to check that cache isn't an empty file.

v1.2.0 - Jun 16, 2016

New features

  • oauth_signature() no longer prepends 'oauth_' to additional parameters. (@jimhester, #373)
  • All print() methods now invisibly return x (#355).
  • DELETE() gains a body parameter (#326).
  • New encode = "raw" allows you to do your own encoding for requests with bodies.
  • New http_type() returns the content/mime type of a request, sans parameters.

Bug fixes and minor improvements

  • No longer uses use custom requests for standard POST requests (#356, #357). This has the side-effect of properly following redirects after POST, fixing some login issues (eg hadley/rvest#133).
  • Long deprecated multipart argument to POST(), PUT() and PATCH() has been removed.
  • The cross-session OAuth cache is now created with permission 0600, and should give a better error if it can't be created (#365).
  • New RETRY() function allows you to retry a request multiple times until it succeeds (#353).
  • The default user agent string is now computed once and cached. This is a small performance improvement, but important for local connections (#322, @richfitz).
  • oauth_callback() gains trailing slash for facebook compatibility (#324).
  • progress() gains con argument to control where progress bar is rendered (#359).
  • When use_basic_auth option is used to obtain a token, token refreshes will now use basic authentication too.
  • Suppress unhelpful "No encoding supplied: defaulting to UTF-8." when printing a response (#327).
  • All auto parser functions now have consistent arguments. This fixes problem where ... is pass on to another function (#330).
  • parse_media() can once again parse multiple parameters (#362, #366).
  • Correctly cast config in POST().
  • Fix in readfunction to close connection when done.

v1.1.0 - Jan 28, 2016

New features

  • stop_for_status(), warn_for_status() and (new) message_for_status() replace message argument with new task argument that optionally describes the current task. This allows API wrappers to provide more informative error messages on failure (#277, #302). stop_for_status() and warn_for_status() return the response if there were no errors. This makes them easier to use in pipelines (#278).
  • url_ok() and url_successful() have been deprecated in favour of the more flexible http_error(), which works with urls, responses and integer status codes (#299).

OAuth

  • oauth1.0_token() gains RSA-SHA1 signature support with the private_key argument (@nathangoulding, #316).
  • oauth2.0_token() throws an error if it fails to get an access token (#250) and gains two new arguments:
    • user_params allows you to pass arbitrary additional parameters to the token access endpoint when acquiring or refreshing a token (@cornf4ke, #312)
    • use_basic_auth allows you to pick use http authentication when getting a token (#310, @grahamrp).
  • oauth_service_token() checks that its arguments are the correct types (#282) and anways returns a request object (#313, @nathangoulding).
  • refresh_oauth2.0() checks for known OAuth2.0 errors and clears the locally cached token in the presense of any (@nathangoulding, #315).

Bug fixes and minor improvements

  • httr no longer bundles cacert.pem, and instead it relies on the bundle in openssl. This bundle is only used a last-resort on windows with R <3.2.0.
  • Switch to 'openssl' package for hashing, hmac, signatures, and base64.
  • httr no longer depends on stringr (#285, @jimhester).
  • build_url() collapses vector path with / (#280, @artemklevtsov).
  • content(x) uses xml2 for XML documents and readr for csv and tsv.
  • content(, type = "text") defaults to UTF-8 encoding if not otherwise specified.
  • has_content() correctly tests for the presence/absence of body content (#91).
  • parse_url() correctly parses urls like file:///a/b/c work (#309).
  • progress() returns TRUE to fix for 'progress callback must return boolean' warning (@jeroenooms, #252).
  • upload_file() supports very large files (> 2.5 Gb) (@jeroenooms, #257).