Struct RequestBuilder

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

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) -> Self

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<HeaderValue>>

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<HeaderValue>>

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) -> Self

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. Both key and value are percent-encoded according to the URL specification.

Examples

// Creates a URL with an encoded query parameter:
// https://httpbin.org/get?my_query=with%20value
let req = ureq::get("https://httpbin.org/get")
    .query("my_query", "with value");

pub fn query_raw<K, V>(self, key: K, value: V) -> Self

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

Add a query parameter to the URL without percent-encoding.

Always appends a new parameter, also when using the name of an already existing one. Neither key nor value are percent-encoded, which allows you to use pre-encoded values or bypass encoding.

Important note: When using this method, you must ensure that your query parameters don’t contain characters that would make the URI invalid, such as spaces or control characters. You are responsible for any pre-encoding needed for URI validity. If you’re unsure, use the regular query() method instead.

Examples

// Creates a URL with a raw query parameter:
// https://httpbin.org/get?my_query=pre-encoded%20value
let req = ureq::get("https://httpbin.org/get")
    .query_raw("my_query", "pre-encoded%20value");

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

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

Set multi query parameters.

Both keys and values are percent-encoded according to the URL specification.

For example, to set ?format=json&dest=%2Flogin

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

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

pub fn query_pairs_raw<I, K, V>(self, iter: I) -> Self

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

Set multi query parameters without percent-encoding.

Neither keys nor values are percent-encoded, which allows you to use pre-encoded values or bypass encoding.

Important note: When using this method, you must ensure that your query parameters don’t contain characters that would make the URI invalid, such as spaces or control characters. You are responsible for any pre-encoding needed for URI validity. If you’re unsure, use the regular query_pairs() method instead.

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

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

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

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

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) -> Self

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) -> Self

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) -> Self

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)?;

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

Send body data as JSON.

Requires the json feature.

The data typically derives Serialize and is converted to a string before sending (does allocate). Will set the content-type header application/json.

use serde::Serialize;

#[derive(Serialize)]
struct MyData {
    thing: String,
}

let body = MyData {
    thing: "yo".to_string(),
};

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

Trait Implementations

impl Debug for RequestBuilder<WithBody>

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

Formats the value using the given formatter.

impl Debug for RequestBuilder<WithoutBody>

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

Formats the value using the given formatter.