Struct ureq::Request

pub struct Request { /* private fields */ }

Request instances are builders that creates a request.

let response = ureq::get("http://example.com/get")
    .query("foo", "bar baz")  // add ?foo=bar+baz
    .call()?;                 // run the request

Implementations

impl Request

pub fn timeout(self, timeout: Duration) -> Self

Sets overall timeout for the request, overriding agent’s configuration if any.

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

Sends the request with no body and blocks the caller until done.

Use this with GET, HEAD, OPTIONS or TRACE. It sends neither Content-Length nor Transfer-Encoding.

let resp = ureq::get("http://example.com/")
    .call()?;

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

Send data a json value.

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

let resp = ureq::post("http://httpbin.org/post")
    .send_json(ureq::json!({
      "name": "martin",
      "rust": true,
    }))?;

pub fn send_bytes(self, data: &[u8]) -> Result<Response, Error>

Send data as bytes.

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

let resp = ureq::put("http://httpbin.org/put")
    .send_bytes(&[0; 1000])?;

pub fn send_string(self, data: &str) -> Result<Response, Error>

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 resp = ureq::post("http://httpbin.org/post")
    .set("Content-Type", "text/plain; charset=iso-8859-1")
    .send_string("Hällo Wörld!")?;

pub fn send_form(self, data: &[(&str, &str)]) -> Result<Response, Error>

Send a sequence of (key, value) pairs as form-urlencoded data.

The Content-Type header is implicitly set to application/x-www-form-urlencoded. The Content-Length header is implicitly set to the length of the serialized value.

let resp = ureq::post("http://httpbin.org/post")
    .send_form(&[
      ("foo", "bar"),
      ("foo2", "bar2"),
    ])?;

pub fn send(self, reader: impl Read) -> Result<Response, Error>

Send data from a reader.

If no Content-Length and Transfer-Encoding header has been set, it uses the chunked transfer encoding.

The caller may set the Content-Length header to the expected byte size of the reader if is known.

The input from the reader is buffered into chunks of size 16,384, the max size of a TLS fragment.

use std::io::Cursor;
let read = Cursor::new(vec![0x20; 100]);
let resp = ureq::post("http://httpbin.org/post")
    .send(read)?;

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

Set a header field.

let resp = ureq::get("http://httpbin.org/bytes/1000")
    .set("Accept", "text/plain")
    .set("Range", "bytes=500-999")
    .call()?;

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

Returns the value for a set header.

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

pub fn header_names(&self) -> Vec<String>

A list of the set header names in this request. Lowercased to be uniform.

let req = ureq::get("/my_page")
    .set("X-API-Key", "foobar")
    .set("Content-Type", "application/json");
assert_eq!(req.header_names(), vec!["x-api-key", "content-type"]);

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

Tells if the header has been set.

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

pub fn all(&self, name: &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");

assert_eq!(req.all("x-forwarded-for"), vec![
    "1.2.3.4",
    "2.3.4.5",
]);

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

Set a query parameter.

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

let resp = ureq::get("http://httpbin.org/get")
    .query("format", "json")
    .query("dest", "/login")
    .call()?;

pub fn query_pairs<'a, P>(self, pairs: P) -> Self

where P: IntoIterator<Item = (&'a str, &'a str)>,

Set multi query parameters.

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

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

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

pub fn method(&self) -> &str

Returns the value of the request method. Something like GET, POST, PUT etc.

let req = ureq::put("http://httpbin.org/put");

assert_eq!(req.method(), "PUT");

pub fn url(&self) -> &str

Get the url str that will be used for this request.

The url might differ from that originally provided when constructing the request if additional query parameters have been added using Request::query().

In case the original url provided to build the request is not possible to parse to a Url, this function returns the original, and it will error once the Request object is used.

let req = ureq::get("http://httpbin.org/get")
    .query("foo", "bar");

assert_eq!(req.url(), "http://httpbin.org/get?foo=bar");

let req = ureq::get("SO WRONG")
    .query("foo", "bar"); // does nothing

assert_eq!(req.url(), "SO WRONG");

pub fn request_url(&self) -> Result<RequestUrl, Error>

Get the parsed url that will be used for this request. The parsed url has functions to inspect the parts of the url further.

The url might differ from that originally provided when constructing the request if additional query parameters have been added using Request::query().

Returns a Result since a common use case is to construct the Request using a &str in which case the url needs to be parsed to inspect the parts. If the Request url is not possible to parse, this function produces the same error that would otherwise happen when call or send_* is called.

let req = ureq::get("http://httpbin.org/get")
    .query("foo", "bar");

assert_eq!(req.request_url()?.host(), "httpbin.org");

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

Formats the value using the given formatter.