Crate ureq[][src]

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:

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.

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.