Reqwest

https://docs.rs/reqwest
Admin
Reqwest is a convenient, higher-level HTTP client for Rust, offering both asynchronous and blocking...
Tokens:945,977
Snippets:7,638
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### get function with doc example

Source: https://docs.rs/reqwest/latest/src/reqwest/lib.rs.html?search=

Shortcut method to make a GET request, with a doc example showing usage.

```rust
/// Shortcut method to quickly make a `GET` request.
///
/// See also the methods on the [`reqwest::Response`](./struct.Response.html)
/// type.
///
/// **NOTE**: This function creates a new internal `Client` on each call,
/// and so should not be used if making many requests. Create a
/// [`Client`](./struct.Client.html) instead.
///
/// # Examples
///
/// ```rust
/// # async fn run() -> Result<(), reqwest::Error> {
/// let body = reqwest::get("https://www.rust-lang.org").await?
///     .text().await?;
/// # Ok(())
/// # }
/// ```
///
/// # Errors
///
/// This function fails if:
///
/// - native TLS backend cannot be initialized
/// - supplied `Url` cannot be parsed
/// - there was an error while sending request
/// - redirect limit was exhausted
pub async fn get<T: IntoUrl>(url: T) -> crate::Result<Response> {
    Client::builder().build()?.get(url).send().await
}
```

--------------------------------

### get() example

Source: https://docs.rs/reqwest/latest/reqwest/header/struct.OccupiedEntry.html

Shows how to use the get() method to get a reference to the first value in the entry. Values are stored in insertion order. Panics if there are no values.

```rust
let mut map = HeaderMap::new();
map.insert(HOST, "hello.world".parse().unwrap());

if let Entry::Occupied(mut e) = map.entry("host") {
    assert_eq!(e.get(), &"hello.world");

    e.append("hello.earth".parse().unwrap());

    assert_eq!(e.get(), &"hello.world");
}
```

--------------------------------

### get example: retrieve header values

Source: https://docs.rs/reqwest/latest/reqwest/header/struct.HeaderMap.html

Shows how to use `get` to retrieve a header value, returning the first value if multiple exist. Also demonstrates `insert`, `append`, and `get_all` behavior with the HOST header.

```rust
let mut map = HeaderMap::new();
assert!(map.get("host").is_none());

map.insert(HOST, "hello".parse().unwrap());
assert_eq!(map.get(HOST).unwrap(), &"hello");
assert_eq!(map.get("host").unwrap(), &"hello");

map.append(HOST, "world".parse().unwrap());
assert_eq!(map.get(HOST).unwrap(), &"hello");
```

--------------------------------

### Example: Create a Client and send a GET request

Source: https://docs.rs/reqwest/latest/reqwest/blocking/struct.Client.html?search=std%3A%3Avec

Shows how to create a `Client` with `Client::new()` and send a GET request to `http://httpbin.org/`. The `send()` method returns a `Result`; the `?` operator is used, implying the surrounding function returns a `Result`.

```rust
use reqwest::blocking::Client;
let client = Client::new();
let resp = client.get("http://httpbin.org/").send()?;
```

--------------------------------

### key example

Source: https://docs.rs/reqwest/latest/reqwest/header/enum.Entry.html?search=

Example of using Entry::key to get a reference to the entry's key.

```rust
let mut map = HeaderMap::new();

assert_eq!(map.entry("x-hello").key(), "x-hello");
```

--------------------------------

### get example

Source: https://docs.rs/reqwest/latest/reqwest/header/struct.HeaderMap.html?search=

Returns a reference to the first value associated with the key. Returns None if no values are associated.

```rust
let mut map = HeaderMap::new();
assert!(map.get("host").is_none());

map.insert(HOST, "hello".parse().unwrap());
assert_eq!(map.get(HOST).unwrap(), &"hello");
assert_eq!(map.get("host").unwrap(), &"hello");

map.append(HOST, "world".parse().unwrap());
assert_eq!(map.get("host").unwrap(), &"hello");
```

--------------------------------

### Send a request with reqwest::Client::new().get().send()

Source: https://docs.rs/reqwest/latest/src/reqwest/async_impl/request.rs.html

Example from the send() method documentation. Shows how to create a client, build a GET request, and await the response. Requires an async runtime and error handling with Result.

```rust
# use reqwest::Error;
#
# async fn run() -> Result<(), Error> {
let response = reqwest::Client::new()
    .get("https://hyper.rs")
    .send()
    .await?;
# Ok(())
# }

```

--------------------------------

### Making a GET request with reqwest::get

Source: https://docs.rs/reqwest/latest/index.html

Shows how to make a single GET request using the `reqwest::get` shortcut method. The example awaits the response and then reads the body as text. The note advises creating a `Client` and reusing it for multiple requests to take advantage of keep-alive connection pooling.

```rust
let body = reqwest::get("https://www.rust-lang.org")
    .await?
    .text()
    .await?;

println!("body = {body:?}");
```

--------------------------------

### Blocking GET request example for get function

Source: https://docs.rs/reqwest/latest/src/reqwest/blocking/mod.rs.html

Example from the `get` function documentation, showing a blocking GET request. It is similar to the module-level example but uses a different error handling pattern. The function creates a new internal `Client` on each call, so it should not be used for many requests.

```rust
# fn run() -> Result<(), reqwest::Error> {
let body = reqwest::blocking::get("https://www.rust-lang.org")?
    .text()?;
# Ok(())
# }
# fn main() { }

```

--------------------------------

### Async GET request example

Source: https://docs.rs/reqwest/latest/src/reqwest/lib.rs.html

This example shows how to use `reqwest::get` to make a simple GET request and read the response body as text. It is an async function that returns a `Result`.

```rust
# async fn run() -> Result<(), reqwest::Error> {
let body = reqwest::get("https://www.rust-lang.org").await?
    .text().await?;
# Ok(())
# }

```

--------------------------------

### Client::new

Source: https://docs.rs/reqwest/latest/reqwest/blocking/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new `Client` with default configuration.

```APIDOC
## [METHOD] Client::new

### Description
Creates a new `Client` with default configuration.

### Method
- `Client::new`

### Signature
`pub fn new() -> Client`
```

--------------------------------

### Proxy::all builder example

Source: https://docs.rs/reqwest/latest/reqwest/struct.Proxy.html

Builds a Client with a proxy for all HTTP and HTTPS traffic.

```rust
let client = reqwest::Client::builder()
    .proxy(reqwest::Proxy::all("http://pro.xy")?)
    .build()?;
```

--------------------------------

### GET https://www.rust-lang.org

Source: https://docs.rs/reqwest/latest/reqwest/blocking/index.html?search=std%3A%3Avec

Example of making a blocking GET request using the reqwest::blocking::get shortcut method.

```APIDOC
## [GET] https://www.rust-lang.org

### Description
Shortcut method to quickly make a blocking GET request. Returns a Response that can be read as text.

### Method
GET

### Endpoint
https://www.rust-lang.org

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **body** (String) - The response body as text.

#### Response Example
```rust
let body = reqwest::blocking::get("https://www.rust-lang.org")?
    .text()?;
println!("body = {body:?}");
```
```

--------------------------------

### Example: Using Method constants and methods

Source: https://docs.rs/reqwest/latest/reqwest/struct.Method.html

Demonstrates using Method::GET, from_bytes, is_idempotent, and as_str.

```rust
use http::Method;

assert_eq!(Method::GET, Method::from_bytes(b"GET").unwrap());
assert!(Method::GET.is_idempotent());
assert_eq!(Method::POST.as_str(), "POST");
```

--------------------------------

### StatusCode basic usage example

Source: https://docs.rs/reqwest/latest/reqwest/struct.StatusCode.html?search=

Example showing how to create a `StatusCode` from a `u16`, get its numeric value, and check if it is a success status.

```rust
use http::StatusCode;

assert_eq!(StatusCode::from_u16(200).unwrap(), StatusCode::OK);
assert_eq!(StatusCode::NOT_FOUND.as_u16(), 404);
assert!(StatusCode::OK.is_success());
```

--------------------------------

### classify_fn example

Source: https://docs.rs/reqwest/latest/reqwest/retry/struct.Builder.html?search=std%3A%3Avec

Example of using `classify_fn` to provide a classifier that retries GET requests when the status is SERVICE_UNAVAILABLE, otherwise marks as success.

```rust
builder.classify_fn(|req_rep| {
    match (req_rep.method(), req_rep.status()) {
        (&http::Method::GET, Some(http::StatusCode::SERVICE_UNAVAILABLE)) => {
            req_rep.retryable()
        },
        _ => req_rep.success()
    }
})
```

--------------------------------

### Making a GET request with reqwest::blocking::get

Source: https://docs.rs/reqwest/latest/reqwest/blocking/index.html

Use the `get` shortcut to make a blocking GET request and read the response body as text. The `?` operator propagates errors. This example prints the body.

```rust
let body = reqwest::blocking::get("https://www.rust-lang.org")?
    .text()?;

println!("body = {body:?}");
```

--------------------------------

### expect example (recommended message style)

Source: https://docs.rs/reqwest/latest/reqwest/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows the recommended style for expect messages: describe the reason you expect the Result to be Ok. The example uses an environment variable.

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

--------------------------------

### Get response text with text()

Source: https://docs.rs/reqwest/latest/reqwest/struct.Response.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of using the text() method to get the full response text. Decodes with BOM sniffing and defaults to UTF-8 if charset is not specified.

```rust
let content = reqwest::get("http://httpbin.org/range/26")
    .await?
    .text()
    .await?;

println!("text: {content:?}");
```

--------------------------------

### into_key() example

Source: https://docs.rs/reqwest/latest/reqwest/header/struct.VacantEntry.html

Shows how to take ownership of the key using the into_key() method.

```rust
let mut map = HeaderMap::new();

if let Entry::Vacant(v) = map.entry("x-hello") {
    assert_eq!(v.into_key().as_str(), "x-hello");
}
```

--------------------------------

### host method example

Source: https://docs.rs/reqwest/latest/reqwest/struct.Url.html

Demonstrates the host() method, which returns the parsed representation of the host. Shows that URLs with hosts return Some, while unix and data URLs return None.

```rust
use url::Url;

let url = Url::parse("https://127.0.0.1/index.html")?;
assert!(url.host().is_some());

let url = Url::parse("ftp://rms@example.com")?;
assert!(url.host().is_some());

let url = Url::parse("unix:/run/foo.socket")?;
assert!(url.host().is_none());

let url = Url::parse("data:text/plain,Stuff")?;
assert!(url.host().is_none());
```

--------------------------------

### insert_entry() example

Source: https://docs.rs/reqwest/latest/reqwest/header/struct.VacantEntry.html

Shows how to insert a value and get an OccupiedEntry using the insert_entry() method.

```rust
let mut map = HeaderMap::new();

if let Entry::Vacant(v) = map.try_entry("x-hello").unwrap() {
    let mut e = v.try_insert_entry("world".parse().unwrap()).unwrap();
    e.insert("world2".parse().unwrap());
}

assert_eq!(map["x-hello"], "world2");
```

--------------------------------

### Blocking GET request with reqwest::blocking::get

Source: https://docs.rs/reqwest/latest/reqwest/blocking/fn.get.html

The signature shows the blocking get function takes a type implementing IntoUrl and returns a Result<Response>. The example demonstrates a quick GET request that fetches the body as text. Because get creates a new internal Client per call, it is not recommended for many requests.

```rust
pub fn get<T: IntoUrl>(url: T) -> Result<Response>
```

```rust
let body = reqwest::blocking::get("https://www.rust-lang.org")?
    .text()?;
```

--------------------------------

### basic_auth example

Source: https://docs.rs/reqwest/latest/reqwest/struct.RequestBuilder.html?search=u32+-%3E+bool

Shows how to enable HTTP basic authentication on a request using the basic_auth method. The example creates a client, sends a DELETE request to httpbin.org/delete with username 'admin' and password 'good password', and awaits the response.

```rust
let client = reqwest::Client::new();
let resp = client.delete("http://httpbin.org/delete")
    .basic_auth("admin", Some("good password"))
    .send()
    .await?;
```

--------------------------------

### Proxy::http builder example

Source: https://docs.rs/reqwest/latest/reqwest/struct.Proxy.html

Builds a Client with a proxy for all HTTP traffic.

```rust
let client = reqwest::Client::builder()
    .proxy(reqwest::Proxy::http("https://my.prox")?)
    .build()?;
```

--------------------------------

### get_mut example

Source: https://docs.rs/reqwest/latest/reqwest/header/struct.HeaderMap.html?search=

Returns a mutable reference to the first value associated with the key. Use entry to get all values.

```rust
let mut map = HeaderMap::default();
map.insert(HOST, "hello".to_string());
map.get_mut("host").unwrap().push_str("-world");

assert_eq!(map.get(HOST).unwrap(), &"hello-world");
```

--------------------------------

### Multipart form example

Source: https://docs.rs/reqwest/latest/src/reqwest/async_impl/request.rs.html

Shows how to create a multipart form with text fields and send it via POST. Requires the 'multipart' feature. The Content-Type and Content-Length headers are set automatically.

```rust
/// # use reqwest::Error;
///
/// # async fn run() -> Result<(), Error> {
/// let client = reqwest::Client::new();
/// let form = reqwest::multipart::Form::new()
///     .text("key3", "value3")
///     .text("key4", "value4");
///
///
/// let response = client.post("your url")
///     .multipart(form)
///     .send()
///     .await?;
/// # Ok(())
/// # }
/// ```
```

--------------------------------

### Proxy::all example

Source: https://docs.rs/reqwest/latest/src/reqwest/proxy.rs.html

Creates a proxy for all HTTP and HTTPS traffic using the Proxy::all method. The example builds a reqwest client with the proxy set to 'http://pro.xy'.

```rust
/// # extern crate reqwest;
/// # fn run() -> Result<(), Box<dyn std::error::Error>> {
/// let client = reqwest::Client::builder()
///     .proxy(reqwest::Proxy::all("http://pro.xy")?)
///     .build()?;
/// # Ok(())
/// # }
/// # fn main() {}

```

--------------------------------

### Pin::into_inner example

Source: https://docs.rs/reqwest/latest/reqwest/dns/type.Resolving.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Unwraps a `Pin<&mut u8>` to get the underlying mutable reference. This is safe because the value implements `Unpin`.

```rust
use std::pin::Pin;

let mut val: u8 = 5;
let pinned: Pin<&mut u8> = Pin::new(&mut val);

// Unwrap the pin to get the underlying mutable reference to the value. We can do
// this because `val` doesn't care about being moved, so the `Pin` was just
// a "facade" anyway.
let r = Pin::into_inner(pinned);
assert_eq!(*r, 5);
```

--------------------------------

### Client::new()

Source: https://docs.rs/reqwest/latest/reqwest/struct.Client.html

Constructs a new Client with default configuration. Panics if TLS backend cannot be initialized or resolver cannot load system configuration.

```APIDOC
## Client::new()

### Description
Constructs a new `Client` with default settings. This method panics if a TLS backend cannot be initialized or the resolver cannot load the system configuration. Use `Client::builder()` to handle failures gracefully.

### Method
`new`

### Signature
```rust
pub fn new() -> Client
```

### Parameters
None

### Returns
- `Client` - A new `Client` instance.

### Errors
Panics if TLS backend initialization or system configuration loading fails.
```

--------------------------------

### Create a blocking Client and send a GET request

Source: https://docs.rs/reqwest/latest/reqwest/blocking/struct.Client.html

Shows how to instantiate a reqwest::blocking::Client and send a GET request to httpbin.org. The send() method returns a Result, so the example uses the ? operator, implying it is used within a function that returns a Result.

```rust
use reqwest::blocking::Client;
let client = Client::new();
let resp = client.get("http://httpbin.org/").send()?;

```

--------------------------------

### Example

Source: https://docs.rs/reqwest/latest/reqwest/blocking/multipart?search=

Example demonstrating how to construct a multipart/form-data request using the reqwest blocking client, including adding text fields, files, and custom parts.

```APIDOC
## Example

```rust
use reqwest::blocking::multipart;

let form = multipart::Form::new()
    // Adding just a simple text field...
    .text("username", "seanmonstar")
    // And a file...
    .file("photo", "/path/to/photo.png")?;

// Customize all the details of a Part if needed...
let bio = multipart::Part::text("hallo peeps")
    .file_name("bio.txt")
    .mime_str("text/plain")?;

// Add the custom part to our form...
let form = form.part("biography", bio);

// And finally, send the form
let client = reqwest::blocking::Client::new();
let resp = client
    .post("http://localhost:8080/user")
    .multipart(form)
    .send()?;
```
```

--------------------------------

### Get response body as bytes

Source: https://docs.rs/reqwest/latest/src/reqwest/blocking/response.rs.html?search=std%3A%3Avec

Use to retrieve the full response body as raw bytes. The example fetches a page and prints the bytes.

```rust

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let bytes = reqwest::blocking::get("http://httpbin.org/ip")?.bytes()?;

println!("bytes: {bytes:?}");
# Ok(())
# }
```
```

--------------------------------

### insert() example

Source: https://docs.rs/reqwest/latest/reqwest/header/struct.OccupiedEntry.html

Shows how to use the insert() method to set the value of the entry. All previous values are removed and the first one is returned.

```rust
let mut map = HeaderMap::new();
map.insert(HOST, "hello.world".parse().unwrap());

if let Entry::Occupied(mut e) = map.entry("host") {
    let mut prev = e.insert("earth".parse().unwrap());
    assert_eq!("hello.world", prev);
}

assert_eq!("earth", map["host"]);
```

--------------------------------

### as_mut example

Source: https://docs.rs/reqwest/latest/reqwest/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates using Result::as_mut to get a mutable reference to the contained value, allowing mutation of the Ok or Err variant.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Get response body as bytes with `bytes()`

Source: https://docs.rs/reqwest/latest/reqwest/blocking/struct.Response.html?search=

Example from the `bytes()` method documentation. Fetches a URL and retrieves the response body as `Bytes`, then prints it.

```rust
let bytes = reqwest::blocking::get("http://httpbin.org/ip")?.bytes()?;

println!("bytes: {bytes:?}");
```

--------------------------------

### set_port example

Source: https://docs.rs/reqwest/latest/reqwest/struct.Url.html

Shows how to set and clear the port number of a URL. The example demonstrates that default port numbers are not reflected in serialization, and that setting a port on a cannot-be-a-base URL returns an error.

```rust
use url::Url;


let mut url = Url::parse("ssh://example.net:2048/")?;

url.set_port(Some(4096)).map_err(|_| "cannot be base")?;
assert_eq!(url.as_str(), "ssh://example.net:4096/");

url.set_port(None).map_err(|_| "cannot be base")?;
assert_eq!(url.as_str(), "ssh://example.net/");
```

```rust
use url::Url;


let mut url = Url::parse("https://example.org/")?;

url.set_port(Some(443)).map_err(|_| "cannot be base")?;
assert!(url.port().is_none());
```

```rust
use url::Url;

let mut url = Url::parse("mailto:rms@example.net")?;

let result = url.set_port(Some(80));
assert!(result.is_err());

let result = url.set_port(None);
assert!(result.is_err());
```

--------------------------------

### Get final URL with `url()`

Source: https://docs.rs/reqwest/latest/reqwest/blocking/struct.Response.html?search=

Example from the `url()` method documentation. Fetches a redirecting URL and asserts that the final URL is the redirected target.

```rust
let resp = reqwest::blocking::get("http://httpbin.org/redirect/1")?;
assert_eq!(resp.url().as_str(), "http://httpbin.org/get");
```

--------------------------------

### set_query example

Source: https://docs.rs/reqwest/latest/reqwest/struct.Url.html

Shows how to set the query string of a URL. The query is set to a string and the resulting URL and query are asserted.

```rust
use url::Url;

let mut url = Url::parse("https://example.com/products")?;
assert_eq!(url.as_str(), "https://example.com/products");

url.set_query(Some("page=2"));
assert_eq!(url.as_str(), "https://example.com/products?page=2");
assert_eq!(url.query(), Some("page=2"));
```

--------------------------------

### password method example

Source: https://docs.rs/reqwest/latest/reqwest/struct.Url.html

Demonstrates the password() method, which returns the password as a percent-encoded ASCII string. Shows that passwords are returned even when the username is empty, and None when no password is present.

```rust
use url::Url;

let url = Url::parse("ftp://rms:secret123@example.com")?;
assert_eq!(url.password(), Some("secret123"));

let url = Url::parse("ftp://:secret123@example.com")?;
assert_eq!(url.password(), Some("secret123"));

let url = Url::parse("ftp://rms@example.com")?;
assert_eq!(url.password(), None);

let url = Url::parse("https://example.com")?;
assert_eq!(url.password(), None);
```

--------------------------------

### Modify query string with .query()

Source: https://docs.rs/reqwest/latest/reqwest/blocking/struct.RequestBuilder.html?search=u32+-%3E+bool

Appends query parameters to the URL. The example adds a 'lang' parameter to a GET request. Requires the 'query' feature.

```rust
let client = reqwest::blocking::Client::new();
let res = client.get("http://httpbin.org")
    .query(&[("lang", "rust")])
    .send()?;
```

--------------------------------

### Get response URL with reqwest::blocking::Response::url

Source: https://docs.rs/reqwest/latest/src/reqwest/blocking/response.rs.html?search=u32+-%3E+bool

Retrieves the final URL of the response after redirects. The example asserts that the URL matches the expected string.

```rust
/// assert_eq!(resp.url().as_str(), "http://httpbin.org/get");
/// # Ok(())
/// # }
/// ```
```

--------------------------------

### Url::make_relative examples

Source: https://docs.rs/reqwest/latest/reqwest/struct.Url.html

Creates a relative URL from this base URL. Returns None if the scheme, host, or port differ.

```rust
use url::Url;

let base = Url::parse("https://example.net/a/b.html")?;
let url = Url::parse("https://example.net/a/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("c.png"));

let base = Url::parse("https://example.net/a/b/")?;
let url = Url::parse("https://example.net/a/b/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("c.png"));

let base = Url::parse("https://example.net/a/b/")?;
let url = Url::parse("https://example.net/a/d/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("../d/c.png"));

let base = Url::parse("https://example.net/a/b.html?c=d")?;
let url = Url::parse("https://example.net/a/b.html?e=f")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("?e=f"));

```
Tokens:
Raw