Crate reqwest

source ·
Expand description

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. For applications wishing to only make a few HTTP requests, the reqwest::blocking API may be more convenient.

Additional learning resources include:

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 and Vec<u8>. 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 added 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.
  • native-tls-alpn: Enables the alpn 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.
  • deflate: Provides response body deflate 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.

Unstable Features

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

  • http3 (unstable): Enables support for sending HTTP/3 requests.

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

Re-exports

Modules

Structs

  • Body
    An asynchronous request body.
  • 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.
  • Method
    The Request Method (VERB)
  • NoProxy
    A configuration for filtering out requests that shouldn’t be proxied
  • 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.).
  • Upgraded
    An upgraded HTTP connection.
  • Url
    A parsed URL record.
  • Version
    Represents a version of the HTTP spec.

Traits

Functions

  • get
    Shortcut method to quickly make a GET request.

Type Aliases

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