Crate ureq[−][src]

ureq is a minimal request library.

The goals of this library are:

Minimal dependency tree
Obvious API

#[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.
.send_json() body as 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().build().

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

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 .send_string(), to we first check if the user has set a ; charset=<whatwg charset> and attempt to encode the request body using that.

Macros

json	Construct a `serde_json::Value` from a JSON literal.
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.
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.