Struct RequestBuilder

#[must_use = "RequestBuilder does nothing until you 'send' it"]
pub struct RequestBuilder { /* private fields */ }

A builder to construct the properties of a Request.

To construct a RequestBuilder, refer to the Client documentation.

Implementations

impl RequestBuilder

fn from_parts(client: Client, request: Request) -> RequestBuilder

Assemble a builder starting from an existing Client and a Request.

fn header<K, V>(self, key: K, value: V) -> RequestBuilder
where
    HeaderName: TryFrom<K>,
    HeaderValue: TryFrom<V>,
    <HeaderName as TryFrom<K>>::Error: Into<Error>,
    <HeaderValue as TryFrom<V>>::Error: Into<Error>,

Add a Header to this Request.

use reqwest::header::USER_AGENT;

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = reqwest::blocking::Client::new();
let res = client.get("https://www.rust-lang.org")
    .header(USER_AGENT, "foo")
    .send()?;
# Ok(())
# }

fn headers(self, headers: HeaderMap) -> RequestBuilder

Add a set of Headers to the existing ones on this Request.

The headers will be merged in to any already set.

use reqwest::header::{HeaderMap, HeaderValue, USER_AGENT, CONTENT_TYPE};
# use std::fs;

fn construct_headers() -> HeaderMap {
    let mut headers = HeaderMap::new();
    headers.insert(USER_AGENT, HeaderValue::from_static("reqwest"));
    headers.insert(CONTENT_TYPE, HeaderValue::from_static("image/png"));
    headers
}

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let file = fs::File::open("much_beauty.png")?;
let client = reqwest::blocking::Client::new();
let res = client.post("http://httpbin.org/post")
    .headers(construct_headers())
    .body(file)
    .send()?;
# Ok(())
# }

fn basic_auth<U, P>(self, username: U, password: Option<P>) -> RequestBuilder
where
    U: Display,
    P: Display,

Enable HTTP basic authentication.

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = reqwest::blocking::Client::new();
let resp = client.delete("http://httpbin.org/delete")
    .basic_auth("admin", Some("good password"))
    .send()?;
# Ok(())
# }

fn bearer_auth<T>(self, token: T) -> RequestBuilder
where
    T: Display,

Enable HTTP bearer authentication.

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = reqwest::blocking::Client::new();
let resp = client.delete("http://httpbin.org/delete")
    .bearer_auth("token")
    .send()?;
# Ok(())
# }

fn body<T: Into<Body>>(self, body: T) -> RequestBuilder

Set the request body.

Examples

Using a string:

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = reqwest::blocking::Client::new();
let res = client.post("http://httpbin.org/post")
    .body("from a &str!")
    .send()?;
# Ok(())
# }

Using a File:

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let file = std::fs::File::open("from_a_file.txt")?;
let client = reqwest::blocking::Client::new();
let res = client.post("http://httpbin.org/post")
    .body(file)
    .send()?;
# Ok(())
# }

Using arbitrary bytes:

# use std::fs;
# fn run() -> Result<(), Box<dyn std::error::Error>> {
// from bytes!
let bytes: Vec<u8> = vec![1, 10, 100];
let client = reqwest::blocking::Client::new();
let res = client.post("http://httpbin.org/post")
    .body(bytes)
    .send()?;
# Ok(())
# }

fn timeout(self, timeout: Duration) -> RequestBuilder

Enables a request timeout.

The timeout is applied from when the request starts connecting until the response body has finished. It affects only this request and overrides the timeout configured using ClientBuilder::timeout().

fn version(self, version: Version) -> RequestBuilder

Set HTTP version

fn json<T: Serialize + ?Sized>(self, json: &T) -> RequestBuilder

Send a JSON body.

Sets the body to the JSON serialization of the passed value, and also sets the Content-Type: application/json header.

Optional

This requires the optional json feature enabled.

Examples

# use reqwest::Error;
# use std::collections::HashMap;
#
# fn run() -> Result<(), Error> {
let mut map = HashMap::new();
map.insert("lang", "rust");

let client = reqwest::blocking::Client::new();
let res = client.post("http://httpbin.org")
    .json(&map)
    .send()?;
# Ok(())
# }

Errors

Serialization can fail if T's implementation of Serialize decides to fail, or if T contains a map with non-string keys.

fn build(self) -> Result<Request>

Build a Request, which can be inspected, modified and executed with Client::execute().

fn build_split(self) -> (Client, Result<Request>)

Build a Request, which can be inspected, modified and executed with Client::execute().

This is similar to [RequestBuilder::build()], but also returns the embedded Client.

fn send(self) -> Result<Response>

Constructs the Request and sends it the target URL, returning a Response.

Errors

This method fails if there was an error while sending request, redirect loop was detected or redirect limit was exhausted.

fn try_clone(&self) -> Option<RequestBuilder>

Attempts to clone the RequestBuilder.

None is returned if a body is which can not be cloned. This can be because the body is a stream.

Examples

With a static body

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = reqwest::blocking::Client::new();
let builder = client.post("http://httpbin.org/post")
    .body("from a &str!");
let clone = builder.try_clone();
assert!(clone.is_some());
# Ok(())
# }

Without a body

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = reqwest::blocking::Client::new();
let builder = client.get("http://httpbin.org/get");
let clone = builder.try_clone();
assert!(clone.is_some());
# Ok(())
# }

With a non-cloneable body

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = reqwest::blocking::Client::new();
let builder = client.get("http://httpbin.org/get")
    .body(reqwest::blocking::Body::new(std::io::empty()));
let clone = builder.try_clone();
assert!(clone.is_none());
# Ok(())
# }

Trait Implementations

impl Debug for RequestBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Auto Trait Implementations

impl !Freeze for RequestBuilder

impl !RefUnwindSafe for RequestBuilder

impl !Sync for RequestBuilder

impl !UnwindSafe for RequestBuilder

impl Send for RequestBuilder

impl Unpin for RequestBuilder

impl UnsafeUnpin for RequestBuilder

Blanket Implementations

impl<T> Any for RequestBuilder where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for RequestBuilder where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for RequestBuilder where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> From<T> for RequestBuilder

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Instrument for RequestBuilder

impl<T> PolicyExt for RequestBuilder where T: ?Sized,

fn and<P, B, E>(self, other: P) -> And<T, P>
where
    T: Sized + Policy<B, E>,
    P: Policy<B, E>,
fn or<P, B, E>(self, other: P) -> Or<T, P>
where
    T: Sized + Policy<B, E>,
    P: Policy<B, E>,

impl<T> WithSubscriber for RequestBuilder

impl<T, U> Into<U> for RequestBuilder where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for RequestBuilder where U: Into<T>,

type Error = never;
fn try_from(value: U) -> Result<T, never>

impl<T, U> TryInto<U> for RequestBuilder where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>