# httr

## Status

[![Lifecycle:
superseded](https://img.shields.io/badge/lifecycle-superseded-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html#superseded)

httr is superseded: only changes necessary to keep it on CRAN will be
made. We recommend using [httr2](https://httr2.r-lib.org) instead.

------------------------------------------------------------------------

The aim of httr is to provide a wrapper for the
[curl](https://cran.r-project.org/package=curl) package, customised to
the demands of modern web APIs.

Key features:

- Functions for the most important http verbs:
  [`GET()`](https://httr.r-lib.org/reference/GET.md),
  [`HEAD()`](https://httr.r-lib.org/reference/HEAD.md),
  [`PATCH()`](https://httr.r-lib.org/reference/PATCH.md),
  [`PUT()`](https://httr.r-lib.org/reference/PUT.md),
  [`DELETE()`](https://httr.r-lib.org/reference/DELETE.md) and
  [`POST()`](https://httr.r-lib.org/reference/POST.md).

- 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()`](https://httr.r-lib.org/reference/content.md) 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()`](https://httr.r-lib.org/reference/stop_for_status.md).

- Config functions make it easier to modify the request in common ways:
  [`set_cookies()`](https://httr.r-lib.org/reference/set_cookies.md),
  [`add_headers()`](https://httr.r-lib.org/reference/add_headers.md),
  [`authenticate()`](https://httr.r-lib.org/reference/authenticate.md),
  [`use_proxy()`](https://httr.r-lib.org/reference/use_proxy.md),
  [`verbose()`](https://httr.r-lib.org/reference/verbose.md),
  [`timeout()`](https://httr.r-lib.org/reference/timeout.md),
  [`content_type()`](https://httr.r-lib.org/reference/content_type.md),
  [`accept()`](https://httr.r-lib.org/reference/content_type.md),
  [`progress()`](https://httr.r-lib.org/reference/progress.md).

- Support for OAuth 1.0 and 2.0 with
  [`oauth1.0_token()`](https://httr.r-lib.org/reference/oauth1.0_token.md)
  and
  [`oauth2.0_token()`](https://httr.r-lib.org/reference/oauth2.0_token.md).
  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](https://cran.r-project.org/package=curl) and
[libcurl](https://curl.se/). Thanks! httr is inspired by http libraries
in other languages, such as
[Resty](http://beders.github.io/Resty/Resty/Examples.md),
[Requests](https://requests.readthedocs.io/en/latest/) and
[httparty](https://github.com/jnunemaker/httparty/tree/master).

## Installation

To get the current released version from CRAN:

``` r
install.packages("httr")
```

To get the current development version from github:

``` r
# install.packages("pak")
pak::pak("r-lib/httr")
```

## Code of Conduct

Please note that the httr project is released with a [Contributor Code
of Conduct](https://httr.r-lib.org/CODE_OF_CONDUCT.html). By
contributing to this project, you agree to abide by its terms.

# Package index

## HTTP verbs

- [`GET()`](https://httr.r-lib.org/reference/GET.md) : GET a url.
- [`POST()`](https://httr.r-lib.org/reference/POST.md) : POST file to a
  server.
- [`PUT()`](https://httr.r-lib.org/reference/PUT.md) : Send PUT request
  to server.
- [`DELETE()`](https://httr.r-lib.org/reference/DELETE.md) : Send a
  DELETE request.
- [`PATCH()`](https://httr.r-lib.org/reference/PATCH.md) : Send PATCH
  request to a server.
- [`HEAD()`](https://httr.r-lib.org/reference/HEAD.md) : Get url
  HEADers.
- [`VERB()`](https://httr.r-lib.org/reference/VERB.md) : VERB a url.
- [`RETRY()`](https://httr.r-lib.org/reference/RETRY.md) : Retry a
  request until it succeeds.
- [`BROWSE()`](https://httr.r-lib.org/reference/BROWSE.md) : Open
  specified url in browser.

## Request configuration

- [`config()`](https://httr.r-lib.org/reference/config.md) : Set curl
  options.

- [`set_config()`](https://httr.r-lib.org/reference/set_config.md)
  [`reset_config()`](https://httr.r-lib.org/reference/set_config.md) :
  Set (and reset) global httr configuration.

- [`with_config()`](https://httr.r-lib.org/reference/with_config.md)
  [`with_verbose()`](https://httr.r-lib.org/reference/with_config.md) :
  Execute code with configuration set.

- [`add_headers()`](https://httr.r-lib.org/reference/add_headers.md) :
  Add additional headers to a request.

- [`authenticate()`](https://httr.r-lib.org/reference/authenticate.md) :
  Use http authentication.

- [`content_type()`](https://httr.r-lib.org/reference/content_type.md)
  [`content_type_json()`](https://httr.r-lib.org/reference/content_type.md)
  [`content_type_xml()`](https://httr.r-lib.org/reference/content_type.md)
  [`accept()`](https://httr.r-lib.org/reference/content_type.md)
  [`accept_json()`](https://httr.r-lib.org/reference/content_type.md)
  [`accept_xml()`](https://httr.r-lib.org/reference/content_type.md) :
  Set content-type and accept headers.

- [`progress()`](https://httr.r-lib.org/reference/progress.md) : Add a
  progress bar.

- [`set_cookies()`](https://httr.r-lib.org/reference/set_cookies.md) :
  Set cookies.

- [`timeout()`](https://httr.r-lib.org/reference/timeout.md) : Set
  maximum request time.

- [`upload_file()`](https://httr.r-lib.org/reference/upload_file.md) :

  Upload a file with
  [`POST()`](https://httr.r-lib.org/reference/POST.md) or
  [`PUT()`](https://httr.r-lib.org/reference/PUT.md).

- [`use_proxy()`](https://httr.r-lib.org/reference/use_proxy.md) : Use a
  proxy to connect to the internet.

- [`user_agent()`](https://httr.r-lib.org/reference/user_agent.md) : Set
  user agent.

- [`verbose()`](https://httr.r-lib.org/reference/verbose.md) : Give
  verbose output.

- [`write_disk()`](https://httr.r-lib.org/reference/write_disk.md)
  [`write_memory()`](https://httr.r-lib.org/reference/write_disk.md) :
  Control where the response body is written.

- [`write_stream()`](https://httr.r-lib.org/reference/write_stream.md) :
  Process output in a streaming manner.

## Response accessors

- [`content()`](https://httr.r-lib.org/reference/content.md) : Extract
  content from a request.
- [`cookies()`](https://httr.r-lib.org/reference/cookies.md) : Access
  cookies in a response.
- [`headers()`](https://httr.r-lib.org/reference/headers.md) : Extract
  the headers from a response
- [`http_error()`](https://httr.r-lib.org/reference/http_error.md) :
  Check for an http error.
- [`http_status()`](https://httr.r-lib.org/reference/http_status.md) :
  Give information on the status of a request.
- [`http_type()`](https://httr.r-lib.org/reference/http_type.md) :
  Extract the content type of a response
- [`parse_http_date()`](https://httr.r-lib.org/reference/parse_http_date.md)
  [`http_date()`](https://httr.r-lib.org/reference/parse_http_date.md) :
  Parse and print http dates.
- [`status_code()`](https://httr.r-lib.org/reference/status_code.md) :
  Extract status code from response.
- [`stop_for_status()`](https://httr.r-lib.org/reference/stop_for_status.md)
  [`warn_for_status()`](https://httr.r-lib.org/reference/stop_for_status.md)
  [`message_for_status()`](https://httr.r-lib.org/reference/stop_for_status.md)
  : Take action on http error.

## Authentication

- [`oauth1.0_token()`](https://httr.r-lib.org/reference/oauth1.0_token.md)
  : Generate an oauth1.0 token.
- [`oauth2.0_token()`](https://httr.r-lib.org/reference/oauth2.0_token.md)
  : Generate an oauth2.0 token.
- [`oauth_app()`](https://httr.r-lib.org/reference/oauth_app.md) :
  Create an OAuth application.
- [`oauth_endpoint()`](https://httr.r-lib.org/reference/oauth_endpoint.md)
  : Describe an OAuth endpoint.
- [`oauth_endpoints()`](https://httr.r-lib.org/reference/oauth_endpoints.md)
  : Popular oauth endpoints.
- [`oauth_service_token()`](https://httr.r-lib.org/reference/oauth_service_token.md)
  : Generate OAuth token for service accounts.
- [`authenticate()`](https://httr.r-lib.org/reference/authenticate.md) :
  Use http authentication.
- [`revoke_all()`](https://httr.r-lib.org/reference/revoke_all.md) :
  Revoke all OAuth tokens in the cache.

## Url parsing and manipulation

- [`modify_url()`](https://httr.r-lib.org/reference/modify_url.md) :
  Modify a url.
- [`parse_url()`](https://httr.r-lib.org/reference/parse_url.md)
  [`build_url()`](https://httr.r-lib.org/reference/parse_url.md) : Parse
  and build urls according to RFC3986.

## Developer facing

- [`cache_info()`](https://httr.r-lib.org/reference/cache_info.md)
  [`rerequest()`](https://httr.r-lib.org/reference/cache_info.md) :
  Compute caching information for a response.
- [`handle()`](https://httr.r-lib.org/reference/handle.md) : Create a
  handle tied to a particular host.
- [`httr_dr()`](https://httr.r-lib.org/reference/httr_dr.md) : Diagnose
  common configuration problems
- [`httr_options()`](https://httr.r-lib.org/reference/httr_options.md)
  [`curl_docs()`](https://httr.r-lib.org/reference/httr_options.md) :
  List available options.
- [`get_callback()`](https://httr.r-lib.org/reference/get_callback.md)
  [`set_callback()`](https://httr.r-lib.org/reference/get_callback.md) :
  Install or uninstall a callback function
- [`response`](https://httr.r-lib.org/reference/response.md) : The
  response object.

# Articles

### All vignettes

- [Best practices for API
  packages](https://httr.r-lib.org/articles/api-packages.md):
- [Getting started with
  httr](https://httr.r-lib.org/articles/quickstart.md):
- [Managing secrets](https://httr.r-lib.org/articles/secrets.md):