Lib.rs

› Web programming › HTTP client
#http #https #client #request #json

minreq

Simple, minimal-dependency HTTP client

by Jens Pitkanen and 4 contributors

19 releases (stable)

✓ Uses Rust 2018 edition

2.1.0 Mar 14, 2020
2.0.0 Nov 23, 2019
1.4.1 Oct 13, 2019
1.4.0 Jul 13, 2019
0.1.2 Mar 18, 2018

#9 in HTTP client

Download history 234/week @ 2019-12-10 301/week @ 2019-12-17 440/week @ 2019-12-24 454/week @ 2019-12-31 478/week @ 2020-01-07 180/week @ 2020-01-14 269/week @ 2020-01-21 223/week @ 2020-01-28 362/week @ 2020-02-04 171/week @ 2020-02-11 258/week @ 2020-02-18 173/week @ 2020-02-25 114/week @ 2020-03-03 283/week @ 2020-03-10 308/week @ 2020-03-17 209/week @ 2020-03-24

1,175 downloads per month
Used in 12 crates (10 directly)

ISC and maybe MPL-2.0

57KB
947 lines

minreq

Crates.io Documentation CI

Simple, minimal-dependency HTTP client. Optional features for https (https), json via Serde (json-using-serde), and unicode domains (punycode).

Without any optional features, my casual testing indicates about 100 KB additional executable size for stripped release builds using this crate.

Documentation

License

This crate is distributed under the terms of the ISC license.

lib.rs:

Minreq

Simple, minimal-dependency HTTP client. The library has a very minimal API, so you'll probably know everything you need to after reading a few examples.

Additional features

Since the crate is supposed to be minimal in terms of dependencies, there are no default features, and optional functionality can be enabled by specifying features for minreq dependency in Cargo.toml:

[dependencies]
minreq = { version = "*", features = ["https", "json-using-serde", "punycode"] }

Below is the list of all available features.

https

This feature uses the (very good) rustls crate to secure the connection when needed. Note that if this feature is not enabled (and it is not by default), requests to urls that start with https:// will fail and return a HttpsFeatureNotEnabled error.

json-using-serde

This feature allows both serialize and deserialize JSON payload using the serde_json crate.

Request and Response expose with_json() and json() for constructing the struct from JSON and extracting the JSON body out, respectively.

punycode

This feature enables requests to non-ascii domains: the punycode crate is used to convert the non-ascii parts into their punycode representations before making the request. If you try to make a request to 㯙㯜㯙 㯟.net or i❤.ws for example, with this feature disabled (as it is by default), your request will fail with a PunycodeFeatureNotEnabled error.

proxy

This feature enables proxy support.

Examples

Get

This is a simple example of sending a GET request and printing out the response's body, status code, and reason phrase. The ? are needed because the server could return invalid UTF-8 in the body, or something could go wrong during the download.

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let response = minreq::get("http://httpbin.org/ip").send()?;
assert!(response.as_str()?.contains("\"origin\":"));
assert_eq!(response.status_code, 200);
assert_eq!(response.reason_phrase, "OK");
# Ok(()) }

Note: you could change the get function to head or put or any other HTTP request method: the api is the same for all of them, it just changes what is sent to the server.

Body (sending)

To include a body, add with_body("<body contents>") before send().

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let response = minreq::post("http://httpbin.org/post")
    .with_body("Foobar")
    .send()?;
assert!(response.as_str()?.contains("Foobar"));
# Ok(()) }

Headers (sending)

To add a header, add with_header("Key", "Value") before send().

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let response = minreq::get("http://httpbin.org/headers")
    .with_header("Accept", "text/plain")
    .with_header("X-Best-Mon", "Sylveon")
    .send()?;
let body_str = response.as_str()?;
assert!(body_str.contains("\"Accept\": \"text/plain\""));
assert!(body_str.contains("\"X-Best-Mon\": \"Sylveon\""));
# Ok(()) }

Headers (receiving)

Reading the headers sent by the servers is done via the headers field of the Response. Note: the header field names (that is, the keys of the HashMap) are all lowercase: this is because the names are case-insensitive according to the spec, and this unifies the casings for easier get()ing.

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let response = minreq::get("http://httpbin.org/ip").send()?;
assert_eq!(response.headers.get("content-type").unwrap(), "application/json");
# Ok(()) }

Timeouts

To avoid timing out, or limit the request's response time, use with_timeout(n) before send(). The given value is in seconds.

NOTE: There is no timeout by default.

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let response = minreq::post("http://httpbin.org/delay/6")
    .with_timeout(10)
    .send()?;
println!("{}", response.as_str()?);
# Ok(()) }

Proxy

To use a proxy server, simply create a Proxy instance and use .with_proxy() on your request.

Supported proxy formats are host:port and user:password@proxy:host. Only HTTP CONNECT proxies are supported at this time.

# fn main() -> Result<(), Box<dyn std::error::Error>> {
#[cfg(feature = "proxy")]
{
    let proxy = minreq::Proxy::new("localhost:8080")?;
    let response = minreq::post("http://httpbin.org/delay/1")
        .with_proxy(proxy)
        .send()?;
    println!("{}", response.as_str()?);
}
# Ok(()) }

Timeouts

By default, a request has no timeout. You can change this in two ways:

  • Use with_timeout on your request to set the timeout per-request like so: 
    minreq::get("/").with_timeout(8).send();
  • Set the environment variable MINREQ_TIMEOUT to the desired amount of seconds until timeout. Ie. if you have a program called foo that uses minreq, and you want all the requests made by that program to timeout in 8 seconds, you launch the program like so: 
    $ MINREQ_TIMEOUT=8 ./foo
    Or add the following somewhere before the requests in the code. 
    std::env::set_var("MINREQ_TIMEOUT", "8");

If the timeout is set with with_timeout, the environment variable will be ignored.

Dependencies

~0–2.6MB
~59K SLoC