[−][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.
- Plain bodies, JSON, urlencoded, multipart
- Customizable redirect policy
- HTTP Proxies
- Uses system-native TLS
- Cookies (only rudimentary support, full support is TODO)
The rudimentary cookie support means that the cookies need to be manually configured for every single request. In other words, there's no cookie jar support as of now. The tracking issue for this feature is available on GitHub.
The reqwest::Client
is synchronous, making it a great fit for
applications that only require a few HTTP requests, and wish to handle
them synchronously.
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")? .text()?; println!("body = {:?}", body);
Additionally, reqwest's Response
struct implements Rust's
Read
trait, so many useful standard library and third party crates will
have convenience methods that take a Response
anywhere T: Read
is
acceptable.
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
Reader, you can use the reqwest::Body::new()
constructor.
let client = reqwest::Client::new(); let res = client.post("http://httpbin.org/post") .body("the exact body that is sent") .send()?;
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()?;
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.
// 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()?;
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
.
Proxies
A Client
can be configured to make use of HTTP proxies by adding
Proxy
s to a ClientBuilder
.
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 certicates 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
. - rustls-tls: Provides TLS support via the
rustls
library. - trust-dns: Enables a trust-dns async resolver instead of default
threadpool using
getaddrinfo
. - hyper-011: Provides support for hyper's old typed headers.
Re-exports
pub extern crate hyper_old_types as hyper_011; |
Modules
async | An 'async' implementation of the reqwest |
header | HTTP header types |
multipart | multipart/form-data |
Structs
Body | The body of a |
Certificate | Represent a server X509 certificate. |
Client | A |
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. |
Enums
UrlError | Errors that can occur during parsing. |
Traits
IntoUrl | A trait to try to convert some type into a |
Functions
get | Shortcut method to quickly make a |
Type Definitions
Result | A |