[][src]Crate ureq

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:

JSON

By enabling the ureq = { version = "*", features = ["json"] } feature, the library supports serde 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.

Macros

json

Construct a serde_json::Value from a JSON literal.

Structs

Agent

Agents keep state between requests.

Cookie

Representation of an HTTP cookie.

Header

Wrapper type for a header field. https://tools.ietf.org/html/rfc7230#section-3.2

Proxy

Proxy server definition

Request

Request instances are builders that creates a request.

Response

Response instances are created as results of firing off requests.

SerdeMap

Represents a JSON key/value type.

Enums

Error

Errors that are translated to "synthetic" responses.

SerdeValue

Represents any valid JSON value.

Functions

agent

Agents are used to keep state between requests.

connect

Make an CONNECT request.

delete

Make a DELETE request.

get

Make a GET request.

head

Make a HEAD request.

options

Make an OPTIONS request.

patch

Make an PATCH request.

post

Make a POST request.

put

Make a PUT request.

request

Make a request setting the HTTP method via a string.

serde_to_value

Convert a T into serde_json::Value which is an enum that can represent any valid JSON data.

trace

Make a TRACE request.