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
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
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.
- 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§
- A blocking Client API.
- HTTP Cookies
- DNS resolution
- HTTP header types
- multipart/form-data
- 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
.