minreq

To use minreq in your Rust project, add it to your Cargo.toml. It is a minimal-dependency HTTP client that supports various optional features for JSON, proxies, and TLS implementations.

[dependencies]
minreq = "3.0.0"

You can enable specific capabilities in minreq by selecting the corresponding features in your Cargo.toml.

JSON Support

• json-using-serde: Enables parsing JSON responses.

URL and Domain Handling

• punycode: Enables support for Unicode domains.
• urlencoding: Enables percent-encoding for query parameters.

Proxy Support

• proxy: Enables support for HTTP proxies.

HTTPS/TLS Implementations

Choose one of the following TLS backends:

• https-rustls (aliased as https): Uses rustls.
• https-rustls-probe: Uses rustls with probing.
• https-native-tls: Uses the system's native TLS implementation.
• https-openssl: Uses a vendored version of OpenSSL.
• https-openssl-probe: Uses OpenSSL with probing.

# Example: Enabling JSON and rustls
minreq = {
    version = "3.0.0",
    features = ["json-using-serde", "https-rustls"]
}

If you use Request::send_lazy(), you receive a ResponseLazy object instead of a standard Response.

ResponseLazy implements std::io::Read, allowing you to stream the response body as it arrives from the network. This is useful for handling large payloads without loading the entire body into memory at once.

To use it, you can read from it into a buffer or use read_to_end to collect it into a Vec<u8>.

use std::io::Read;

// send_lazy() returns ResponseLazy
let mut response = minreq::get("http://example.com").send_lazy()?;

// Stream the body into a vector
let mut buffer = Vec::new();
response.read_to_end(&mut buffer)?;

By default, minreq requests have no timeout. You can set a timeout in two ways:

1. Per-request: Use .with_timeout(n) where n is the number of seconds.
2. Environment Variable: Set MINREQ_TIMEOUT to the desired number of seconds. This is useful for setting a global timeout for an entire application.

If both are used, the .with_timeout() value takes precedence.

// Per-request timeout
minreq::get("http://example.com").with_timeout(8).send();

You can create a new Request using convenient top-level functions that correspond to HTTP methods. These functions initialize a Request with the specified method and URL, but do not send it immediately.

Available aliases:

• get(url)
• head(url)
• post(url)
• put(url)
• delete(url)
• connect(url)
• options(url)
• trace(url)
• patch(url)

let request = minreq::post("http://example.com");

The current major version (v3) of minreq targets Rust 1.63 (based on Debian bookworm).

Important Note: This MSRV policy applies to minreq with no optional features enabled. Enabling specific optional features may require a more recent Rust version. Always check the project's MSRV CI job if you are working in a constrained environment.

To send a request with a body (e.g., POST or PUT), use .with_body("contents") before calling .send().

let response = minreq::post("http://example.com")
    .with_body("Foobar")
    .send()?;

To route requests through a proxy, enable the proxy feature, create a Proxy instance, and pass it to the request using .with_proxy(proxy).

Supported formats:

• host:port
• user:password@proxy:host

Note: Only HTTP CONNECT proxies are supported.

#[cfg(feature = "proxy")]
{
    let proxy = minreq::Proxy::new("localhost:1080")?;
    let response = minreq::post("http://example.com")
        .with_proxy(proxy)
        .send()?;
    println!("{}", response.as_str()?);
}

Access headers sent by the server via the .header("key") method on the Response object. Note that header keys are case-insensitive and are stored as lowercase strings internally.

let response = minreq::get("http://example.com").send()?;
assert!(response.header("content-type").unwrap().starts_with("text/html"));

Use .with_header("Key", "Value") before .send() to add custom HTTP headers to your request.

let response = minreq::get("http://example.com")
    .with_header("Accept", "text/html")
    .send()?;

Use minreq::get(url) to initiate a GET request. Call .send()? to execute it and receive a Response object. You can access the response body as a string using .as_str()?, the status code via .status_code, and the reason phrase via .reason_phrase.

let response = minreq::get("http://example.com").send()?;
assert!(response.as_str()?.contains("</html>"));
assert_eq!(200, response.status_code);
assert_eq!("OK", response.reason_phrase);