[−][src]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.
- 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:
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(¶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
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 theCertificate
type. - Client certificates can be add to a
ClientBuilder
with theIdentity
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 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.
- 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.
- 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
blocking | A blocking Client API. |
cookie | HTTP Cookies |
header | HTTP header types |
multipart | multipart/form-data |
redirect | Redirect Handling |
Structs
Body | An asynchronous request body. |
Certificate | Represents a server X509 certificate. |
Client | An asynchronous |
ClientBuilder | A |
Error | The Errors that may occur when processing a |
Identity | Represents a private key and X509 cert as a client certificate. |
Method | The Request Method (VERB) |
Proxy | Configuration of a proxy that a |
Request | A request which can be executed with |
RequestBuilder | A builder to construct the properties of a |
Response | A Response to a submitted |
StatusCode | An HTTP status code ( |
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 |
ResponseBuilderExt | Extension trait for http::response::Builder objects |
Functions
get | Shortcut method to quickly make a |
Type Definitions
Result | A |