Struct ureq::Request

pub struct Request { /* private fields */ }

Request instances are builders that creates a request.

let mut request = ureq::get("https://www.google.com/");

let response = request
    .query("foo", "bar baz") // add ?foo=bar%20baz
    .call();                 // run the request

Implementations

impl Request

pub fn build(&self) -> Request

“Builds” this request which is effectively the same as cloning. This is needed when we use a chain of request builders, but don’t want to send the request at the end of the chain.

let r = ureq::get("/my_page")
    .set("X-Foo-Bar", "Baz")
    .build();

pub fn call(&mut self) -> Response

Executes the request and blocks the caller until done.

Use .timeout_connect() and .timeout_read() to avoid blocking forever.

let r = ureq::get("/my_page")
    .timeout_connect(10_000) // max 10 seconds
    .call();

println!("{:?}", r);

pub fn send_string(&mut self, data: &str) -> Response

Send data as a string.

The Content-Length header is implicitly set to the length of the serialized value. Defaults to utf-8

Charset support

Requires feature ureq = { version = "*", features = ["charset"] }

If a Content-Type header is present and it contains a charset specification, we attempt to encode the string using that character set. If it fails, we fall back on utf-8.

// this example requires features = ["charset"]

let r = ureq::post("/my_page")
    .set("Content-Type", "text/plain; charset=iso-8859-1")
    .send_string("Hällo Wörld!");
println!("{:?}", r);

pub fn send(&mut self, reader: impl Read + 'static) -> Response

Send data from a reader.

The Content-Length header is not set because we can’t know the length of the reader.

use std::io::Cursor;

let text = "Hello there!\n";
let read = Cursor::new(text.to_string().into_bytes());

let resp = ureq::post("/somewhere")
    .set("Content-Type", "text/plain")
    .send(read);

pub fn set(&mut self, header: &str, value: &str) -> &mut Request

Set a header field.

let r = ureq::get("/my_page")
    .set("X-API-Key", "foobar")
    .set("Accept", "text/plain")
    .call();

 if r.ok() {
     println!("yay got {}", r.into_string().unwrap());
 } else {
     println!("Oh no error!");
 }

pub fn header<'a>(&self, name: &'a str) -> Option<&str>

Returns the value for a set header.

let req = ureq::get("/my_page")
    .set("X-API-Key", "foobar")
    .build();
assert_eq!("foobar", req.header("x-api-Key").unwrap());

pub fn has<'a>(&self, name: &'a str) -> bool

Tells if the header has been set.

let req = ureq::get("/my_page")
    .set("X-API-Key", "foobar")
    .build();
assert_eq!(true, req.has("x-api-Key"));

pub fn all<'a>(&self, name: &'a str) -> Vec<&str>

All headers corresponding values for the give name, or empty vector.

let req = ureq::get("/my_page")
    .set("X-Forwarded-For", "1.2.3.4")
    .set("X-Forwarded-For", "2.3.4.5")
    .build();
assert_eq!(req.all("x-forwarded-for"), vec![
    "1.2.3.4",
    "2.3.4.5",
]);

pub fn query(&mut self, param: &str, value: &str) -> &mut Request

Set a query parameter.

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

let r = ureq::get("/my_page")
    .query("format", "json")
    .query("dest", "/login")
    .call();

println!("{:?}", r);

pub fn query_str(&mut self, query: &str) -> &mut Request

Set query parameters as a string.

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

let r = ureq::get("/my_page")
    .query_str("?format=json&dest=/login")
    .call();
println!("{:?}", r);

pub fn timeout_connect(&mut self, millis: u64) -> &mut Request

Timeout for the socket connection to be successful.

The default is 0, which means a request can block forever.

let r = ureq::get("/my_page")
    .timeout_connect(1_000) // wait max 1 second to connect
    .call();
println!("{:?}", r);

pub fn timeout_read(&mut self, millis: u64) -> &mut Request

Timeout for the individual reads of the socket.

The default is 0, which means it can block forever.

let r = ureq::get("/my_page")
    .timeout_read(1_000) // wait max 1 second for the read
    .call();
println!("{:?}", r);

pub fn timeout_write(&mut self, millis: u64) -> &mut Request

Timeout for the individual writes to the socket.

The default is 0, which means it can block forever.

let r = ureq::get("/my_page")
    .timeout_write(1_000)   // wait max 1 second for sending.
    .call();
println!("{:?}", r);

pub fn auth(&mut self, user: &str, pass: &str) -> &mut Request

Basic auth.

These are the same

let r1 = ureq::get("http://localhost/my_page")
    .auth("martin", "rubbermashgum")
    .call();
 println!("{:?}", r1);

let r2 = ureq::get("http://martin:rubbermashgum@localhost/my_page").call();
println!("{:?}", r2);

pub fn auth_kind(&mut self, kind: &str, pass: &str) -> &mut Request

Auth of other kinds such as Digest, Token etc.

let r = ureq::get("http://localhost/my_page")
    .auth_kind("token", "secret")
    .call();
println!("{:?}", r);

pub fn redirects(&mut self, n: u32) -> &mut Request

How many redirects to follow.

Defaults to 5. Set to 0 to avoid redirects and instead get a response object with the 3xx status code.

If the redirect count hits this limit (and it’s > 0), a synthetic 500 error response is produced.

let r = ureq::get("/my_page")
    .redirects(10)
    .call();
println!("{:?}", r);

pub fn get_method(&self) -> &str

Get the method this request is using.

Example:

let req = ureq::post("/somewhere")
    .build();
assert_eq!(req.get_method(), "POST");

pub fn get_url(&self) -> &str

Get the url this request was created with.

This value is not normalized, it is exactly as set. It does not contain any added query parameters.

Example:

let req = ureq::post("https://cool.server/innit")
    .build();
assert_eq!(req.get_url(), "https://cool.server/innit");

pub fn get_host(&self) -> Result<String, Error>

Normalizes and returns the host that will be used for this request.

Example:

let req1 = ureq::post("https://cool.server/innit")
    .build();
assert_eq!(req1.get_host().unwrap(), "cool.server");

let req2 = ureq::post("/some/path")
    .build();
assert_eq!(req2.get_host().unwrap(), "localhost");

pub fn get_scheme(&self) -> Result<String, Error>

Returns the scheme for this request.

Example:

let req = ureq::post("https://cool.server/innit")
    .build();
assert_eq!(req.get_scheme().unwrap(), "https");

pub fn get_query(&self) -> Result<String, Error>

The complete query for this request.

Example:

let req = ureq::post("https://cool.server/innit?foo=bar")
    .query("format", "json")
    .build();
assert_eq!(req.get_query().unwrap(), "?foo=bar&format=json");

pub fn get_path(&self) -> Result<String, Error>

The normalized path of this request.

Example:

let req = ureq::post("https://cool.server/innit")
    .build();
assert_eq!(req.get_path().unwrap(), "/innit");

Trait Implementations

impl Clone for Request

fn clone(&self) -> Request

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Request

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

Formats the value using the given formatter.

impl Default for Request

fn default() -> Request

Returns the “default value” for a type.