[−][src]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"] }` use ureq::json; // 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 asRead
..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.
Structs
Agent | Agents keep state between requests. |
Cookie | Representation of an HTTP cookie. |
Header | Wrapper type for a header line. |
Proxy | Proxy server definition |
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. |