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>

Available on crate feature json only.

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.

impl From<Builder> for Request

Available on crate feature http-interop only.

Converts an http::request::Builder into a Request.

let http_request_builder = http::Request::builder().method("GET").uri("http://example.com");
let request: ureq::Request = http_request_builder.into();
request.call()?;

Fallibility

http::request::Builder contains a Result that is normally checked when the builder is “built” into a http::Request. This From implementation does not check it however, and returns a GET Request that defaults to "https://example.com" in case it contains Err. In order to test for errors, utilize the provided conversion from http::request::Parts:

ureq::is_test(true);
let http_builder = http::Request::builder().method("GET").uri("http://example.com");
let request = http_builder.body(()).expect("Builder error"); // Check the error
let (parts, ()) = request.into_parts();
let request: ureq::Request = parts.into();

Converting from http::Request

Notably ureq does not implement the conversion from http::Request because it contains the body of a request together with the actual request data. However, http provides http::Request::into_parts() to split out a request into http::request::Parts and a body, for which the conversion is implemented and can be used as follows:

let http_request = http::Request::builder().method("GET").uri("http://example.com").body(vec![0u8]).unwrap();
let (http_parts, body) = http_request.into_parts();
let request: ureq::Request = http_parts.into();
request.send_bytes(&body)?;

fn from(value: Builder) -> Self

Converts to this type from the input type.

impl From<Parts> for Request

Available on crate feature http-interop only.

Converts http::request::Parts into a Request.

An http::Request can be split out into its http::request::Parts and body as follows:

let http_request = http::Request::builder().method("GET").uri("http://example.com").body(vec![0u8]).unwrap();
let (http_parts, body) = http_request.into_parts();
let request: ureq::Request = http_parts.into();
request.send_bytes(&body)?;

fn from(value: Parts) -> Self

Converts to this type from the input type.

impl From<Request> for Builder

Available on crate feature http-interop only.

Converts a Request into an http::request::Builder.

The method and URI are preserved. The HTTP version will always be set to HTTP/1.1.

let request = ureq::get("https://my-website.com");
let http_request_builder: http::request::Builder = request.into();

http_request_builder.body(())?;

fn from(value: Request) -> Self

Converts to this type from the input type.