Crate reqwest

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.

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

Additional learning resources include:

Commercial Support

For private advice, support, reviews, access to the maintainer, and the like, reach out for commercial support.

Making a GET request

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

# async fn run() -> Result<(), reqwest::Error> {
let body = reqwest::get("https://www.rust-lang.org")
    .await?
    .text()
    .await?;

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

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 and Vec<u8>. If you wish to pass a custom type, you can use the reqwest::Body constructors.

# use reqwest::Error;
#
# async fn run() -> Result<(), Error> {
let client = reqwest::Client::new();
let res = client.post("http://httpbin.org/post")
    .body("the exact body that is sent")
    .send()
    .await?;
# Ok(())
# }

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.

The feature form is required.

# use reqwest::Error;
#
# #[cfg(feature = "form")]
# async fn run() -> Result<(), Error> {
// 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?;
# Ok(())
# }

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.

# use reqwest::Error;
# use std::collections::HashMap;
#
# #[cfg(feature = "json")]
# async fn run() -> Result<(), Error> {
// 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?;
# Ok(())
# }

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. ALL_PROXY or all_proxy provide proxies for both HTTP and HTTPS connections. If both the all proxy and HTTP or HTTPS proxy variables are set the more specific HTTP or HTTPS proxies take precedence.

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

A Client will use transport layer security (TLS) by default to connect to HTTPS destinations.

See more details in the tls module.

WASM

The Client implementation automatically switches to the WASM one when the target_arch is wasm32, the usage is basically the same as the async api. Some of the features are disabled in wasm : tls, cookie, [blocking], as well as various ClientBuilder methods such as timeout() and connector_layer().

TLS and cookies are provided through the browser environment, so reqwest can issue TLS requests with cookies, but has limited configuration.

Optional Features

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

Unstable Features

Some feature flags require additional opt-in by the application, by setting a reqwest_unstable flag.

These features are unstable, and experimental. Details about them may be changed in patch releases.

You can pass such a flag to the compiler via .cargo/config, or environment variables, such as:

RUSTFLAGS="--cfg reqwest_unstable" cargo build

Sponsors

Support this project by becoming a sponsor.

Modules

Functions