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:

• The Rust Cookbook
• Reqwest Repository Examples

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(&params)
    .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][ClientBuilder::cookie_store] method on ClientBuilder.

Proxies

A Client can be configured to make use of HTTP proxies by adding Proxys 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 the Certificate type.
• Client certificates can be add to a ClientBuilder with the [Identity][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 via the native-tls library to connect over HTTPS.
• default-tls-vendored: Enables the vendored feature of native-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.

Modules

async	An 'async' implementation of the reqwest Client.
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 Request.
Certificate	Represent a server X509 certificate.
Client	A 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	Represent 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.
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 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.

Enums

UrlError

Errors that can occur during parsing.

Traits

IntoUrl

A trait to try to convert some type into a Url.

Functions

get	Shortcut method to quickly make a GET request.

Type Definitions

Result

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