[−][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, detecting
loops, and having a maximum redirect chain of 10 hops. To customize this
behavior, a RedirectPolicy
can used with a ClientBuilder
.
Cookies
The automatic storing and sending of session cookies can be enabled with
the cookie_store
method on ClientBuilder
.
Proxies
A Client
can be configured to make use of HTTP proxies by adding
Proxy
s to a ClientBuilder
.
** NOTE** System proxies will be used in the next breaking change.
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 via the
native-tls
library to connect over HTTPS. - default-tls-vendored: Enables the
vendored
feature ofnative-tls
. - blocking: Provides the blocking client API.
- cookies: Provides cookie session support.
- gzip: Provides response body gzip decompression.
- json: Provides serialization and deserialization for JSON bodies.
- unstable-stream (unstable): Adds support for
futures::Stream
.
Modules
blocking | A blocking Client API. |
cookie | The cookies module contains types for working with request and response cookies. |
header | HTTP header types |
multipart | multipart/form-data |
Structs
Body | An asynchronous request body. |
Certificate | Represent a server X509 certificate. |
Client | An asynchronous |
ClientBuilder | A |
Error | The Errors that may occur when processing a |
Identity | Represent a private key and X509 cert as a client certificate. |
Method | The Request Method (VERB) |
Proxy | Configuration of a proxy that a |
RedirectAction | An action to perform when a redirect status code is found. |
RedirectAttempt | A type that holds information on the next request and previous requests in redirect chain. |
RedirectPolicy | A type that controls the policy on how to handle the following of redirects. |
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 |
Functions
get | Shortcut method to quickly make a |
Type Definitions
Result | A |