[−][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
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
.
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
. - rustls-tls: Provides TLS support via the
rustls
library. - socks: Provides SOCKS5 proxy support.
- 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 |
cookie | The cookies module contains types for working with request and response cookies. |
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 |