ureq is a minimal request library.

The goals of this library are:

• Minimal dependency tree
• Obvious API
• Blocking API
• Convenience over correctness
• No use of unsafe

// requires feature: `ureq = { version = "*", features = ["json"] }`
use ureq::json;

fn main() -> std::io::Result<()> {
  // sync post request of some json.
  let resp = ureq::post("https://myapi.example.com/ingest")
      .set("X-My-Header", "Secret")
      .send_json(json!({
          "name": "martin",
          "rust": true
      }));

  // .ok() tells if response is 200-299.
  if resp.ok() {
    println!("success: {}", resp.into_string()?);
  } else {
    // This can include errors like failure to parse URL or connect timeout.
    // They are treated as synthetic HTTP-level error statuses.
    println!("error {}: {}", resp.status(), resp.into_string()?);
  }
  Ok(())
}

Plain requests

Most standard methods (GET, POST, PUT etc), are supported as functions from the top of the library (ureq::get, ureq::post, ureq::put, etc).

These top level http method functions create a Request instance which follows a build pattern. The builders are finished using:

• .call() without a request body.
• .send() with a request body as Read (chunked encoding support for non-known sized readers).
• .send_string() body as string.
• .send_bytes() body as bytes.
• .send_form() key-value pairs as application/x-www-form-urlencoded.

JSON

By enabling the ureq = { version = "*", features = ["json"] } feature, the library supports serde json.

• request.send_json() send body as serde json.
• response.into_json() transform response to json.

Agents

To maintain a state, cookies, between requests, you use an agent. Agents also follow the build pattern. Agents are created with ureq::agent().

Content-Length

The library will set the content length on the request when using .send_string() or .send_json(). In other cases the user can optionally request.set("Content-Length", 1234).

For responses, if the Content-Length header is present, the methods that reads the body (as string, json or read trait) are all limited to the length specified in the header.

Transfer-Encoding: chunked

Dechunking is a response body is done automatically if the response headers contains a Transfer-Encoding header.

Sending a chunked request body is done by setting the header prior to sending a body.

let resp = ureq::post("http://my-server.com/ingest")
    .set("Transfer-Encoding", "chunked")
    .send_string("Hello world");

Character encoding

By enabling the ureq = { version = "*", features = ["charset"] } feature, the library supports sending/receiving other character sets than utf-8.

For response.into_string() we read the header Content-Type: text/plain; charset=iso-8859-1 and if it contains a charset specification, we try to decode the body using that encoding. In the absence of, or failing to interpret the charset, we fall back on utf-8.

Similarly when using request.send_string(), we first check if the user has set a ; charset=<whatwg charset> and attempt to encode the request body using that.

Synthetic errors

Rather than exposing a custom error type through results, this library has opted for representing potential connection/TLS/etc errors as HTTP response codes. These invented codes are called "synthetic."

The idea is that from a library user's point of view the distinction of whether a failure originated in the remote server (500, 502) etc, or some transient network failure, the code path of handling that would most often be the same.

As a result, reading from a Response may yield an error message generated by the ureq library. To handle these errors, use the response.synthetic_error() method.