1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337
#![deny(missing_docs)] #![deny(missing_debug_implementations)] #![cfg_attr(test, deny(warnings))] #![doc(html_root_url = "https://docs.rs/reqwest/0.9.22")] //! # reqwest //! //! The `reqwest` crate provides a convenient, higher-level HTTP //! [`Client`][client]. //! //! It handles many of the things that most people just expect an HTTP client //! to do for them. //! //! - Plain bodies, [JSON](#json), [urlencoded](#forms), [multipart](multipart) //! - Customizable [redirect policy](#redirect-policy) //! - HTTP [Proxies](#proxies) //! - Uses system-native [TLS](#tls) //! - Cookies //! //! The [`reqwest::Client`][client] is synchronous, making it a great fit for //! applications that only require a few HTTP requests, and wish to handle //! them synchronously. //! //! Additional learning resources include: //! //! - [The Rust Cookbook](https://rust-lang-nursery.github.io/rust-cookbook/web/clients.html) //! - [Reqwest Repository Examples](https://github.com/seanmonstar/reqwest/tree/master/examples) //! //! ## Making a GET request //! //! For a single request, you can use the [`get`][get] shortcut method. //! //! ```rust //! # use reqwest::{Error, Response}; //! //! # fn run() -> Result<(), Error> { //! let body = reqwest::get("https://www.rust-lang.org")? //! .text()?; //! //! println!("body = {:?}", body); //! # Ok(()) //! # } //! ``` //! //! Additionally, reqwest's [`Response`][response] struct implements Rust's //! `Read` trait, so many useful standard library and third party crates will //! have convenience methods that take a `Response` anywhere `T: Read` is //! acceptable. //! //! **NOTE**: If you plan to perform multiple requests, it is best to create a //! [`Client`][client] and reuse it, taking advantage of keep-alive connection //! pooling. //! //! ## Making POST requests (or setting request bodies) //! //! There are several ways you can set the body of a request. The basic one is //! by using the `body()` method of a [`RequestBuilder`][builder]. This lets you set the //! exact raw bytes of what the body should be. It accepts various types, //! including `String`, `Vec<u8>`, and `File`. If you wish to pass a custom //! Reader, you can use the `reqwest::Body::new()` constructor. //! //! ```rust //! # use reqwest::Error; //! # //! # fn run() -> Result<(), Error> { //! let client = reqwest::Client::new(); //! let res = client.post("http://httpbin.org/post") //! .body("the exact body that is sent") //! .send()?; //! # Ok(()) //! # } //! ``` //! //! ### Forms //! //! It's very common to want to send form data in a request body. This can be //! done with any type that can be serialized into form data. //! //! This can be an array of tuples, or a `HashMap`, or a custom type that //! implements [`Serialize`][serde]. //! //! ```rust //! # use reqwest::Error; //! # //! # fn run() -> Result<(), Error> { //! // This will POST a body of `foo=bar&baz=quux` //! let params = [("foo", "bar"), ("baz", "quux")]; //! let client = reqwest::Client::new(); //! let res = client.post("http://httpbin.org/post") //! .form(¶ms) //! .send()?; //! # Ok(()) //! # } //! ``` //! //! ### JSON //! //! There is also a `json` method helper on the [`RequestBuilder`][builder] that works in //! a similar fashion the `form` method. It can take any value that can be //! serialized into JSON. //! //! ```rust //! # use reqwest::Error; //! # use std::collections::HashMap; //! # //! # fn run() -> Result<(), Error> { //! // This will POST a body of `{"lang":"rust","body":"json"}` //! let mut map = HashMap::new(); //! map.insert("lang", "rust"); //! map.insert("body", "json"); //! //! let client = reqwest::Client::new(); //! let res = client.post("http://httpbin.org/post") //! .json(&map) //! .send()?; //! # Ok(()) //! # } //! ``` //! //! ## Redirect Policies //! //! By default, a `Client` will automatically handle HTTP redirects, detecting //! loops, and having a maximum redirect chain of 10 hops. To customize this //! behavior, a [`RedirectPolicy`][redirect] can used with a `ClientBuilder`. //! //! ## Cookies //! //! The automatic storing and sending of session cookies can be enabled with //! the [`cookie_store`][ClientBuilder::cookie_store] method on `ClientBuilder`. //! //! ## Proxies //! //! A `Client` can be configured to make use of HTTP proxies by adding //! [`Proxy`](Proxy)s to a `ClientBuilder`. //! //! ** NOTE** System proxies will be used in the next breaking change. //! //! ## TLS //! //! By default, a `Client` will make use of system-native transport layer //! security to connect to HTTPS destinations. This means schannel on Windows, //! Security-Framework on macOS, and OpenSSL on Linux. //! //! - Additional X509 certificates can be configured on a `ClientBuilder` with the //! [`Certificate`](Certificate) type. //! - Client certificates can be add to a `ClientBuilder` with the //! [`Identity`][Identity] type. //! - Various parts of TLS can also be configured or even disabled on the //! `ClientBuilder`. //! //! ## Optional Features //! //! The following are a list of [Cargo features][cargo-features] that can be //! enabled or disabled: //! //! - **default-tls** *(enabled by default)*: Provides TLS support via the //! `native-tls` library to connect over HTTPS. //! - **default-tls-vendored**: Enables the `vendored` feature of `native-tls`. //! - **rustls-tls**: Provides TLS support via the `rustls` library. //! - **socks**: Provides SOCKS5 proxy support. //! - **trust-dns**: Enables a trust-dns async resolver instead of default //! threadpool using `getaddrinfo`. //! - **hyper-011**: Provides support for hyper's old typed headers. //! //! //! [hyper]: http://hyper.rs //! [client]: ./struct.Client.html //! [response]: ./struct.Response.html //! [get]: ./fn.get.html //! [builder]: ./struct.RequestBuilder.html //! [serde]: http://serde.rs //! [redirect]: ./struct.RedirectPolicy.html //! [Proxy]: ./struct.Proxy.html //! [cargo-features]: https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-features-section extern crate base64; extern crate bytes; extern crate cookie as cookie_crate; extern crate cookie_store; extern crate encoding_rs; #[macro_use] extern crate futures; extern crate http; extern crate hyper; #[cfg(feature = "hyper-011")] pub extern crate hyper_old_types as hyper_011; #[cfg(feature = "default-tls")] extern crate hyper_tls; #[macro_use] extern crate log; extern crate flate2; extern crate mime; extern crate mime_guess; #[cfg(feature = "default-tls")] extern crate native_tls; extern crate serde; extern crate serde_json; extern crate serde_urlencoded; extern crate time; extern crate tokio; extern crate tokio_executor; #[cfg_attr(feature = "default-tls", macro_use)] extern crate tokio_io; extern crate tokio_timer; #[cfg(feature = "trust-dns")] extern crate trust_dns_resolver; extern crate url; extern crate uuid; #[cfg(feature = "socks")] extern crate socks; #[cfg(target_os = "windows")] extern crate winreg; #[cfg(feature = "rustls-tls")] extern crate hyper_rustls; #[cfg(feature = "rustls-tls")] extern crate tokio_rustls; #[cfg(feature = "rustls-tls")] extern crate webpki_roots; #[cfg(feature = "rustls-tls")] extern crate rustls; #[cfg(test)] #[macro_use] extern crate doc_comment; #[cfg(test)] doctest!("../README.md"); pub use hyper::header; pub use hyper::Method; pub use hyper::{StatusCode, Version}; pub use url::Url; pub use url::ParseError as UrlError; pub use self::client::{Client, ClientBuilder}; pub use self::error::{Error, Result}; pub use self::body::Body; pub use self::into_url::IntoUrl; pub use self::proxy::Proxy; pub use self::redirect::{RedirectAction, RedirectAttempt, RedirectPolicy}; pub use self::request::{Request, RequestBuilder}; pub use self::response::Response; #[cfg(feature = "tls")] pub use self::tls::{Certificate, Identity}; // this module must be first because of the `try_` macro #[macro_use] mod error; mod async_impl; mod connect; mod body; mod client; pub mod cookie; #[cfg(feature = "trust-dns")] mod dns; mod into_url; mod proxy; mod redirect; mod request; mod response; #[cfg(feature = "tls")] mod tls; mod wait; pub mod multipart; /// An 'async' implementation of the reqwest `Client`. pub mod async { pub use ::async_impl::{ Body, Chunk, Decoder, Client, ClientBuilder, Request, RequestBuilder, Response, ResponseBuilderExt, multipart }; } /// Shortcut method to quickly make a `GET` request. /// /// See also the methods on the [`reqwest::Response`](./struct.Response.html) /// type. /// /// **NOTE**: This function creates a new internal `Client` on each call, /// and so should not be used if making many requests. Create a /// [`Client`](./struct.Client.html) instead. /// /// # Examples /// /// ```rust /// # fn run() -> Result<(), reqwest::Error> { /// let body = reqwest::get("https://www.rust-lang.org")? /// .text()?; /// # Ok(()) /// # } /// # fn main() { } /// ``` /// /// # Errors /// /// This function fails if: /// /// - native TLS backend cannot be initialized /// - supplied `Url` cannot be parsed /// - there was an error while sending request /// - redirect loop was detected /// - redirect limit was exhausted pub fn get<T: IntoUrl>(url: T) -> ::Result<Response> { Client::builder() .build()? .get(url) .send() } fn _assert_impls() { fn assert_send<T: Send>() {} fn assert_sync<T: Sync>() {} fn assert_clone<T: Clone>() {} assert_send::<Client>(); assert_sync::<Client>(); assert_clone::<Client>(); assert_send::<Request>(); assert_send::<RequestBuilder>(); assert_send::<Response>(); assert_send::<Error>(); assert_sync::<Error>(); }