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.
- Async and blocking Clients
- Plain bodies, JSON, urlencoded, [multipart]
- Customizable redirect policy
- HTTP Proxies
- Uses TLS by default
- 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:
§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.
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(¶ms)
.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.
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.
- Additional server certificates can be configured on a
ClientBuilder
with theCertificate
type. - Client certificates can be added to a
ClientBuilder
with theIdentity
type. - Various parts of TLS can also be configured or even disabled on the
ClientBuilder
.
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
].
§Optional Features
The following are a list of Cargo features that can be enabled or disabled:
- http2 (enabled by default): Enables HTTP/2 support.
- 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 ofnative-tls
. - native-tls-alpn: Enables the
alpn
feature ofnative-tls
. - rustls-tls: Enables TLS functionality provided by
rustls
. Equivalent torustls-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 thewebpki-roots
crate. - rustls-tls-native-roots: Enables TLS functionality provided by
rustls
, while using root certificates from therustls-native-certs
crate. - blocking: Provides the blocking client API.
- charset (enabled by default): Improved support for decoding text.
- cookies: Provides cookie session support.
- gzip: Provides response body gzip decompression.
- brotli: Provides response body brotli decompression.
- zstd: Provides response body zstd 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.
- hickory-dns: Enables a hickory-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
§Sponsors
Support this project by becoming a sponsor.
Re-exports§
pub use tls::Certificate;
pub use tls::Identity;
Modules§
- DNS resolution
- HTTP header types
- Redirect Handling
- TLS configuration and types
Structs§
- An asynchronous request body.
- An asynchronous
Client
to make Requests with. - A
ClientBuilder
can be used to create aClient
with custom configuration. - The Errors that may occur when processing a
Request
. - The Request Method (VERB)
- A configuration for filtering out requests that shouldn’t be proxied
- Configuration of a proxy that a
Client
should pass requests to. - A request which can be executed with
Client::execute()
. - A builder to construct the properties of a
Request
. - A Response to a submitted
Request
. - An HTTP status code (
status-code
in RFC 7230 et al.). - An upgraded HTTP connection.
- A parsed URL record.
- Represents a version of the HTTP spec.
Traits§
- A trait to try to convert some type into a
Url
. - Extension trait for http::response::Builder objects
Functions§
- Shortcut method to quickly make a
GET
request.
Type Aliases§
- A
Result
alias where theErr
case isreqwest::Error
.