Expand description
The practical HTTP client that is fun to use.
cHTTP is an HTTP client that provides a clean and easy-to-use interface around the venerable libcurl.
Sending requests
Sending requests is as easy as calling a single function. Let’s make a simple GET request to an example website:
use chttp;
let mut response = chttp::get("https://example.org")?;
println!("{}", response.body_mut().text()?);
Requests are performed synchronously, up until the response headers are received. The returned response struct
includes the response body as an open stream implementing Read
.
Sending a POST request is also easy, and takes an additional argument for the request body:
use chttp;
let response = chttp::post("https://example.org", "make me a salad")?;
cHTTP provides several other simple functions for common HTTP request types:
chttp::put("https://example.org", "have a salad")?;
chttp::head("https://example.org")?;
chttp::delete("https://example.org")?;
Custom requests
cHTTP is not limited to canned HTTP verbs; you can customize requests by creating your own Request
object and then
send
ing that.
use chttp::{self, http};
let request = http::Request::post("https://example.org")
.header("Content-Type", "application/json")
.body(r#"{
"speed": "fast",
"cool_name": true
}"#)?;
let response = chttp::send(request)?;
Request options
How requests are sent can be customized using the Options
struct, which provides various
fields for setting timeouts, proxies, and other connection and protocol configuration. These options can be included
right along your request as an extension object:
use chttp::{self, http, Options};
use std::time::Duration;
let request = http::Request::get("https://example.org")
.extension(Options::default()
// Set a 5 second timeout.
.with_timeout(Some(Duration::from_secs(5))))
.body(())?;
let response = chttp::send(request)?;
Custom clients
The free-standing functions for sending request delegate to a shared client instance that is lazily instantiated with the default options. You can also create custom client instances of your own, which allows you to set default options for all requests and group related connections together. Each client has its own connection pool and event loop, so separating certain requests into separate clients can ensure that they are isolated from each other.
See the documentation for Client
and
ClientBuilder
for more details on creating custom clients.
Logging
cHTTP logs quite a bit of useful information at various levels using the log crate.
If you set the log level to Trace
for the chttp::wire
target, cHTTP will also log all incoming and outgoing data
while in flight. This may come in handy if you are debugging code and need to see the exact data being sent to the
server and being received.
Re-exports
pub extern crate http;
pub use body::Body;
pub use client::Client;
pub use error::Error;
pub use options::*;