[−][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(&params)
    .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][ClientBuilder::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 the Certificate type.
Client certificates can be add to a ClientBuilder with the Identity 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 of native-tls.
rustls-tls: Enables TLS functionality provided by rustls. Equivalent to rustls-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 the webpki-roots crate.
rustls-tls-native-roots: Enables TLS functionality provided by rustls, while using root certificates from the rustls-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.
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 `Client` to make Requests with.
ClientBuilder	A `ClientBuilder` can be used to create a `Client` with custom configuration.
Error	The Errors that may occur when processing a `Request`.
Identity	Represents a private key and X509 cert as a client certificate.
Method	The Request Method (VERB)
Proxy	Configuration of a proxy that a `Client` should pass requests to.
Request	A request which can be executed with `Client::execute()`.
RequestBuilder	A builder to construct the properties of a `Request`.
Response	A Response to a submitted `Request`.
StatusCode	An HTTP status code (`status-code` in RFC 7230 et al.).
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 `Url`.
ResponseBuilderExt	Extension trait for http::response::Builder objects

Functions

get	Shortcut method to quickly make a `GET` request.

Type Definitions

Result

A Result alias where the Err case is reqwest::Error.