Crate ureq

ureq is a minimal request library.

The goals of this library are:

• Minimal dependency tree
• Obvious API

// requires feature: `ureq = { version = "*", features = ["json"] }`
#[macro_use]
extern crate ureq;

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

    // .ok() tells if response is 200-299.
    if resp.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.
• .send_string() body as string.

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.

Macros

map	Create a HashMap from a shorthand notation.

Structs

Agent	Agents keep state between requests.
Cookie	Representation of an HTTP cookie.
Header	Wrapper type for a header line.
Request	Request instances are builders that creates a request.
Response	Response instances are created as results of firing off requests.

Enums

Error

Errors that are translated to "synthetic" responses.

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.
trace	Make a TRACE request.