Struct RequestBuilder

Source

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

Expand description

Transparent wrapper around http::request::Builder.

The purpose is to provide the .call() and .send() functions to make a simpler API for sending requests.

Implementations§

Source §

impl<Any> RequestBuilder<Any>

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

Source

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.

§Examples

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

Source

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.

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

Source

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

Source

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

Source

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(_)));

Source §

impl RequestBuilder<WithoutBody>

Source

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

Source

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

Source §

impl RequestBuilder<WithBody>

Source

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

Source

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

Source

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

Source

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

Source

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

Methods from Deref<Target = Builder>§

Source

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


let mut req = Request::builder();
assert_eq!(req.method_ref(),Some(&Method::GET));

req = req.method("POST");
assert_eq!(req.method_ref(),Some(&Method::POST));

Source

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

Get the URI for this request

By default this is /.

§Examples


let mut req = Request::builder();
assert_eq!(req.uri_ref().unwrap(), "/" );

req = req.uri("https://www.rust-lang.org/");
assert_eq!(req.uri_ref().unwrap(), "https://www.rust-lang.org/" );

Source

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

Get the HTTP version for this request

By default this is HTTP/1.1.

§Examples


let mut req = Request::builder();
assert_eq!(req.version_ref().unwrap(), &Version::HTTP_11 );

req = req.version(Version::HTTP_2);
assert_eq!(req.version_ref().unwrap(), &Version::HTTP_2 );

Source

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

Get header on this request builder. when builder has error returns None

§Example

let req = Request::builder()
    .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" );

Source

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 = Request::builder();
{
  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" );

Source

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 = Request::builder().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));

Source

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 = Request::builder().extension("My Extension");
let mut extensions = req.extensions_mut().unwrap();
assert_eq!(extensions.get::<&'static str>(), Some(&"My Extension"));
extensions.insert(5u32);
assert_eq!(extensions.get::<u32>(), Some(&5u32));