# Crate reqwest [−] [src]

# reqwest

The `reqwest` crate provides a convenient, higher-level HTTP `Client`.

It handles many of the things that most people just expect an HTTP client to do for them.

- Async and blocking Clients
- Plain bodies, JSON, urlencoded, multipart
- Customizable redirect policy
- HTTP Proxies
- Uses system-native TLS
- Cookies

The `reqwest::Client` is asynchronous. For applications wishing to only make a few HTTP requests, the `reqwest::blocking` API may be more convenient.

Additional learning resources include:

- The Rust Cookbook
- Reqwest Repository Examples

## Making a GET request

For a single request, you can use the `get` shortcut method.

    let body = reqwest::get("https://www.rust-lang.org")
        .await?
        .text()
        .await?;

    println!("body = {:?}", body);

NOTE: If you plan to perform multiple requests, it is best to create a `Client` and reuse it, taking advantage of keep-alive connection pooling.

## Making POST requests (or setting request bodies)

There are several ways you can set the body of a request. The basic one is by using the `body()` method of a `RequestBuilder`. This lets you set the exact raw bytes of what the body should be. It accepts various types, including `String`, `Vec<u8>`, and `File`. If you wish to pass a custom type, you can use the `reqwest::Body` constructors.

    let client = reqwest::Client::new();
    let res = client.post("http://httpbin.org/post")
        .body("the exact body that is sent")
        .send()
        .await?;

### Forms

It’s very common to want to send form data in a request body. This can be done with any type that can be serialized into form data.

This can be an array of tuples, or a `HashMap`, or a custom type that implements `Serialize`.

    // This will POST a body of `foo=bar&baz=quux`
    let params = [("foo", "bar"), ("baz", "quux")];
    let client = reqwest::Client::new();
    let res = client.post("http://httpbin.org/post")
        .form(&params)
        .send()
        .await?;

### JSON

There is also a `json` method helper on the `RequestBuilder` that works in a similar fashion the `form` method. It can take any value that can be serialized into JSON. The feature `json` is required.

    // This will POST a body of `{"lang":"rust","body":"json"}`
    let mut map = HashMap::new();
    map.insert("lang", "rust");
    map.insert("body", "json");

    let client = reqwest::Client::new();
    let res = client.post("http://httpbin.org/post")
        .json(&map)
        .send()
        .await?;

## Redirect Policies

By default, a `Client` will automatically handle HTTP redirects, having a maximum redirect chain of 10 hops. To customize this behavior, a `redirect::Policy` can be used with a `ClientBuilder`.

## Cookies

The automatic storing and sending of session cookies can be enabled with the [`cookie_store`][ClientBuilder::cookie_store] method on `ClientBuilder`.

## Proxies

NOTE: System proxies are enabled by default.

System proxies look in environment variables to set HTTP or HTTPS proxies.

`HTTP_PROXY` or `http_proxy` provide http proxies for http connections while `HTTPS_PROXY` or `https_proxy` provide HTTPS proxies for HTTPS connections.

These can be overwritten by adding a `Proxy` to `ClientBuilder` i.e. `let proxy = reqwest::Proxy::http("https://secure.example")?;` or disabled by calling `ClientBuilder::no_proxy()`.

`socks` feature is required if you have configured socks proxy like this:

    export https_proxy=socks5://127.0.0.1:1086

## TLS

By default, a `Client` will make use of system-native transport layer security to connect to HTTPS destinations. This means schannel on Windows, Security-Framework on macOS, and OpenSSL on Linux.

- Additional X509 certificates can be configured on a `ClientBuilder` with the `Certificate` type.
- Client certificates can be add to a `ClientBuilder` with the `Identity` type.
- Various parts of TLS can also be configured or even disabled on the `ClientBuilder`.

## Optional Features

The following are a list of Cargo features that can be enabled or disabled:

- default-tls (enabled by default): Provides TLS support to connect over HTTPS.
- native-tls: Enables TLS functionality provided by `native-tls`.
- native-tls-vendored: Enables the `vendored` feature of `native-tls`.
- rustls-tls: Enables TLS functionality provided by `rustls`. Equivalent to `rustls-tls-webpki-roots`.
- rustls-tls-manual-roots: Enables TLS functionality provided by `rustls`, without setting any root certificates. Roots have to be specified manually.
- rustls-tls-webpki-roots: Enables TLS functionality provided by `rustls`, while using root certificates from the `webpki-roots` crate.
- rustls-tls-native-roots: Enables TLS functionality provided by `rustls`, while using root certificates from the `rustls-native-certs` crate.
- blocking: Provides the blocking client API.
- cookies: Provides cookie session support.
- gzip: Provides response body gzip decompression.
- brotli: Provides response body brotli decompression.
- json: Provides serialization and deserialization for JSON bodies.
- multipart: Provides functionality for multipart forms.
- stream: Adds support for `futures::Stream`.
- socks: Provides SOCKS5 proxy support.
- trust-dns: Enables a trust-dns async resolver instead of default threadpool using `getaddrinfo`.

## Modules

header | HTTP header types
redirect | Redirect Handling

## Structs

Body | An asynchronous request body.
Certificate | Represents a server X509 certificate.
Client | An asynchronous `Client` to make Requests with.
ClientBuilder | A `ClientBuilder` can be used to create a `Client` with custom configuration.
Error | The Errors that may occur when processing a `Request`.
Identity | Represents a private key and X509 cert as a client certificate.
Method | The Request Method (VERB)
Proxy | Configuration of a proxy that a `Client` should pass requests to.
Request | A request which can be executed with `Client::execute()`.
RequestBuilder | A builder to construct the properties of a `Request`.
Response | A Response to a submitted `Request`.
StatusCode | An HTTP status code (`status-code` in RFC 7230 et al.).
Url | A parsed URL record.
Version | Represents a version of the HTTP spec.

## Traits

IntoUrl | A trait to try to convert some type into a `Url`.
ResponseBuilderExt | Extension trait for http::response::Builder objects

## Functions

get | Shortcut method to quickly make a `GET` request.

## Type Definitions

Result | A `Result` alias where the `Err` case is `reqwest::Error`.