Struct RequestBuilder

pub struct RequestBuilder<B> { /* private fields */ }

Available on crate feature dep_ureq only.

Transparent wrapper around http::request::Builder.

The purpose is to provide the .call() and .send() and additional helpers for query parameters like .query() functions to make an API for sending requests.

Implementations

impl<Any> RequestBuilder<Any>

pub fn method_ref(&self) -> Option<&Method>

Get the HTTP Method for this request.

By default this is GET. If builder has error, returns None.

Examples

use ureq::http::Method;

let req = ureq::get("http://httpbin.org/get");
assert_eq!(req.method_ref(),Some(&Method::GET));

let req = ureq::post("http://httpbin.org/post");
assert_eq!(req.method_ref(),Some(&Method::POST));

pub fn header<K, V>(self, key: K, value: V) -> RequestBuilder<Any>

where HeaderName: TryFrom<K>, <HeaderName as TryFrom<K>>::Error: Into<Error>, HeaderValue: TryFrom<V>, <HeaderValue as TryFrom<V>>::Error: Into<Error>,

Appends a header to this request builder.

This function will append the provided key/value as a header to the set of headers. It does not replace headers.

Examples

let req = ureq::get("https://httpbin.org/get")
    .header("X-Custom-Foo", "bar");

pub fn headers_ref(&self) -> Option<&HeaderMap>

Get header on this request builder.

When builder has error returns None.

Example

let req = ureq::get("http://httpbin.org/get")
    .header("Accept", "text/html")
    .header("X-Custom-Foo", "bar");
let headers = req.headers_ref().unwrap();
assert_eq!( headers["Accept"], "text/html" );
assert_eq!( headers["X-Custom-Foo"], "bar" );

pub fn headers_mut(&mut self) -> Option<&mut HeaderMap>

Get headers on this request builder.

When builder has error returns None.

Example

let mut req =  ureq::get("http://httpbin.org/get");
{
  let headers = req.headers_mut().unwrap();
  headers.insert("Accept", HeaderValue::from_static("text/html"));
  headers.insert("X-Custom-Foo", HeaderValue::from_static("bar"));
}
let headers = req.headers_ref().unwrap();
assert_eq!( headers["Accept"], "text/html" );
assert_eq!( headers["X-Custom-Foo"], "bar" );

pub fn query<K, V>(self, key: K, value: V) -> RequestBuilder<Any>

where K: AsRef<str>, V: AsRef<str>,

Add a query parameter to the URL.

Always appends a new parameter, also when using the name of an already existing one.

Examples

let req = ureq::get("https://httpbin.org/get")
    .query("my_query", "with_value");

pub fn query_pairs<I, K, V>(self, iter: I) -> RequestBuilder<Any>

where I: IntoIterator<Item = (K, V)>, K: AsRef<str>, V: AsRef<str>,

Set multi query parameters.

For example, to set ?format=json&dest=/login

let query = vec![
    ("format", "json"),
    ("dest", "/login"),
];

let response = ureq::get("http://httpbin.org/get")
   .query_pairs(query)
   .call()?;

pub fn uri<T>(self, uri: T) -> RequestBuilder<Any>

where Uri: TryFrom<T>, <Uri as TryFrom<T>>::Error: Into<Error>,

Overrides the URI for this request.

Typically this is set via ureq::get(<uri>) or Agent::get(<uri>). This lets us change it.

Examples

let req = ureq::get("https://www.google.com/")
    .uri("https://httpbin.org/get");

pub fn uri_ref(&self) -> Option<&Uri>

Get the URI for this request

By default this is /.

Examples

let req = ureq::get("http://httpbin.org/get");
assert_eq!(req.uri_ref().unwrap(), "http://httpbin.org/get");

pub fn version(self, version: Version) -> RequestBuilder<Any>

Set the HTTP version for this request.

By default this is HTTP/1.1. ureq only handles HTTP/1.1 and HTTP/1.0.

Examples

use ureq::http::Version;

let req = ureq::get("https://www.google.com/")
    .version(Version::HTTP_10);

pub fn version_ref(&self) -> Option<&Version>

Get the HTTP version for this request

By default this is HTTP/1.1.

Examples

use ureq::http::Version;

let req = ureq::get("http://httpbin.org/get");
assert_eq!(req.version_ref().unwrap(), &Version::HTTP_11);

pub fn config(self) -> ConfigBuilder<RequestScope<Any>>

Override agent level config on the request level.

The agent config is copied and modified on request level.

Example

use ureq::Agent;

let agent: Agent = Agent::config_builder()
    .https_only(false)
    .build()
    .into();

let request = agent.get("http://httpbin.org/get")
    .config()
    // override agent default for this request
    .https_only(true)
    .build();

// Make the request
let result = request.call();

// The https_only was set on request level
assert!(matches!(result.unwrap_err(), ureq::Error::RequireHttpsOnly(_)));

pub fn extension<T>(self, extension: T) -> RequestBuilder<Any>

where T: Clone + Any + Send + Sync + 'static,

Adds an extension to this builder

Examples

let req = ureq::get("http://httpbin.org/get")
    .extension("My Extension");

assert_eq!(req.extensions_ref().unwrap().get::<&'static str>(),
           Some(&"My Extension"));

pub fn extensions_ref(&self) -> Option<&Extensions>

Get a reference to the extensions for this request builder.

If the builder has an error, this returns None.

Example

let req = ureq::get("http://httpbin.org/get")
    .extension("My Extension").extension(5u32);
let extensions = req.extensions_ref().unwrap();
assert_eq!(extensions.get::<&'static str>(), Some(&"My Extension"));
assert_eq!(extensions.get::<u32>(), Some(&5u32));

pub fn extensions_mut(&mut self) -> Option<&mut Extensions>

Get a mutable reference to the extensions for this request builder.

If the builder has an error, this returns None.

Example

let mut req = ureq::get("http://httpbin.org/get");
let mut extensions = req.extensions_mut().unwrap();
extensions.insert(5u32);
assert_eq!(extensions.get::<u32>(), Some(&5u32));

impl RequestBuilder<WithoutBody>

pub fn call(self) -> Result<Response<Body>, Error>

Sends the request and blocks the caller until we receive a response.

It sends neither Content-Length nor Transfer-Encoding.

let res = ureq::get("http://httpbin.org/get")
    .call()?;

pub fn force_send_body(self) -> RequestBuilder<WithBody>

Force sending a body.

This is an escape hatch to interact with broken services.

According to the spec, methods such as GET, DELETE and TRACE should not have a body. Despite that there are broken API services and servers that use it.

Example using DELETE while sending a body.

let res = ureq::delete("http://httpbin.org/delete")
    // this "unlocks" send() below
    .force_send_body()
    .send("DELETE with body is not correct")?;

impl RequestBuilder<WithBody>

pub fn content_type<V>(self, content_type: V) -> RequestBuilder<WithBody>

where HeaderValue: TryFrom<V>, <HeaderValue as TryFrom<V>>::Error: Into<Error>,

Set the content-type header.

let res = ureq::post("http://httpbin.org/post")
    .content_type("text/html; charset=utf-8")
    .send("<html><body>åäö</body></html>")?;

pub fn send(self, data: impl AsSendBody) -> Result<Response<Body>, Error>

Send body data and blocks the caller until we receive response.

let res = ureq::post("http://httpbin.org/post")
    .send(&[0_u8; 1000])?;

pub fn send_empty(self) -> Result<Response<Body>, Error>

Send an empty body.

The method is POST, PUT or PATCH, which normally has a body. Using this function makes it explicit you want to send an empty body despite the method.

This is equivalent to .send(&[]).

let res = ureq::post("http://httpbin.org/post")
    .send_empty()?;

pub fn send_form<I, K, V>(self, iter: I) -> Result<Response<Body>, Error>

where I: IntoIterator<Item = (K, V)>, K: AsRef<str>, V: AsRef<str>,

Send form encoded data.

Constructs a form submission with the content-type header application/x-www-form-urlencoded. Keys and values will be URL encoded.

let form = [
    ("name", "martin"),
    ("favorite_bird", "blue-footed booby"),
];

let response = ureq::post("http://httpbin.org/post")
   .send_form(form)?;

Trait Implementations

impl Debug for RequestBuilder<WithBody>

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

Formats the value using the given formatter.

impl Debug for RequestBuilder<WithoutBody>

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

Formats the value using the given formatter.