diff --git a/src/intro.md b/src/intro.md index 896ba34..7b64e53 100644 --- a/src/intro.md +++ b/src/intro.md @@ -62,6 +62,7 @@ community. It needs and welcomes help. For details see | [Query the GitHub API][ex-rest-get] | [![reqwest-badge]][reqwest] [![serde-badge]][serde] | [![cat-net-badge]][cat-net] [![cat-encoding-badge]][cat-encoding] | | [Consume a paginated RESTful API][ex-paginated-api] | [![reqwest-badge]][reqwest] [![serde-badge]][serde] | [![cat-net-badge]][cat-net] [![cat-encoding-badge]][cat-encoding] | | [Check if an API resource exists][ex-rest-head] | [![reqwest-badge]][reqwest] | [![cat-net-badge]][cat-net] | +| [Set custom headers and URL parameters for a REST request][ex-rest-custom-params] | [![reqwest-badge]][reqwest] [![hyper-badge]][hyper] [![url-badge]][url] | [![cat-net-badge]][cat-net] | | [Create and delete Gist with GitHub API][ex-rest-post] | [![reqwest-badge]][reqwest] [![serde-badge]][serde] | [![cat-net-badge]][cat-net] [![cat-encoding-badge]][cat-encoding] | | [POST a file to paste-rs][ex-file-post] | [![reqwest-badge]][reqwest] | [![cat-net-badge]][cat-net] | | [Listen on unused port TCP/IP][ex-random-port-tcp] | [![std-badge]][std] | [![cat-net-badge]][cat-net] | @@ -143,6 +144,8 @@ Keep lines sorted. [env_logger]: https://docs.rs/env_logger/ [flate2-badge]: https://img.shields.io/crates/v/flate2.svg?label=flate2 [flate2]: https://docs.rs/flate2/ +[hyper-badge]: https://img.shields.io/crates/v/hyper.svg?label=hyper +[hyper]: https://docs.rs/hyper/ [lazy_static-badge]: https://img.shields.io/crates/v/lazy_static.svg?label=lazy_static [lazy_static]: https://docs.rs/lazy_static/ [log-badge]: https://img.shields.io/crates/v/log.svg?label=log @@ -203,6 +206,7 @@ Keep lines sorted. [ex-rand-range]: basics.html#ex-rand-range [ex-random-port-tcp]: net.html#ex-random-port-tcp [ex-rayon-iter-mut]: concurrency.html#ex-rayon-iter-mut +[ex-rest-custom-params]: net.html#ex-rest-custom-params [ex-rest-get]: net.html#ex-rest-get [ex-rest-head]: net.html#ex-rest-head [ex-rest-post]: net.html#ex-rest-post diff --git a/src/net.md b/src/net.md index 19a27c5..060a46c 100644 --- a/src/net.md +++ b/src/net.md @@ -12,6 +12,7 @@ | [Query the GitHub API][ex-rest-get] | [![reqwest-badge]][reqwest] [![serde-badge]][serde] | [![cat-net-badge]][cat-net] [![cat-encoding-badge]][cat-encoding] | | [Consume a paginated RESTful API][ex-paginated-api] | [![reqwest-badge]][reqwest] [![serde-badge]][serde] | [![cat-net-badge]][cat-net] [![cat-encoding-badge]][cat-encoding] | | [Check if an API resource exists][ex-rest-head] | [![reqwest-badge]][reqwest] | [![cat-net-badge]][cat-net] | +| [Set custom headers and URL parameters for a REST request][ex-rest-custom-params] | [![reqwest-badge]][reqwest] [![hyper-badge]][hyper] [![url-badge]][url] | [![cat-net-badge]][cat-net] | | [Create and delete Gist with GitHub API][ex-rest-post] | [![reqwest-badge]][reqwest] [![serde-badge]][serde] | [![cat-net-badge]][cat-net] [![cat-encoding-badge]][cat-encoding] | | [POST a file to paste-rs][ex-file-post] | [![reqwest-badge]][reqwest] | [![cat-net-badge]][cat-net] | | [Listen on unused port TCP/IP][ex-random-port-tcp] | [![std-badge]][std] | [![cat-net-badge]][cat-net] | @@ -454,6 +455,85 @@ fn run() -> Result<()> { # quick_main!(run); ``` +[ex-rest-custom-params]: #ex-rest-custom-params + +## Set custom headers and URL parameters for a REST request + +[![reqwest-badge]][reqwest] [![hyper-badge]][hyper] [![url-badge]][url] [![cat-net-badge]][cat-net] + +Sets both standard and custom HTTP headers as well as URL parameters +for HTTP GET request. Firstly creates a custom header of type `XPoweredBy` +with [`hyper::header!`] macro. Secondly calls [`Url::parse_with_params`] +in order to build a complex URL with specified key value pairs. +Lastly sets standard headers [`header::UserAgent`] and [`header::Authorization`] +as well as custom one `XPoweredBy` with [`RequestBuilder::header`] prior to making +the request with [`RequestBuilder::send`]. + +The code is run against service which responds with +a JSON dict containing all request headers for easy verification. + +```rust,no_run +# #[macro_use] +# extern crate error_chain; +extern crate url; +extern crate reqwest; +#[macro_use] +extern crate hyper; +#[macro_use] +extern crate serde_derive; + +use std::collections::HashMap; +use url::Url; +use reqwest::header::{UserAgent, Authorization, Bearer}; + +// Custom header type +header! { (XPoweredBy, "X-Powered-By") => [String] } + +// Helper for verification +#[derive(Deserialize, Debug)] +pub struct HeadersEcho { + pub headers: HashMap, +} +# +# error_chain! { +# foreign_links { +# Reqwest(reqwest::Error); +# UrlParse(url::ParseError); +# } +# } + +fn run() -> Result<()> { + let client = reqwest::Client::new()?; + + // Make request to webservice that will respond with JSON dict containing + // the headders set on HTTP GET request. + let url = Url::parse_with_params("http://httpbin.org/headers", + &[("lang", "rust"), ("browser", "servo")])?; + + let mut response = client + .get(url) + .header(UserAgent("Rust-test".to_owned())) + .header(Authorization(Bearer { token: "DEadBEEfc001cAFeEDEcafBAd".to_owned() })) + .header(XPoweredBy("Guybrush Threepwood".to_owned())) + .send()?; + + // JSON response should match the headers set on request + let out: HeadersEcho = response.json()?; + assert_eq!(out.headers["Authorization"], + "Bearer DEadBEEfc001cAFeEDEcafBAd"); + assert_eq!(out.headers["User-Agent"], "Rust-test"); + assert_eq!(out.headers["X-Powered-By"], "Guybrush Threepwood"); + // Resonse contains full URL used to make the request + assert_eq!(response.url().as_str(), + "http://httpbin.org/headers?lang=rust&browser=servo"); + + println!("{:?}", out); + Ok(()) +} +# +# quick_main!(run); +``` + [ex-rest-post]: #ex-rest-post ## Create and delete Gist with GitHub API @@ -757,6 +837,8 @@ After sending data in telnet press `ctrl-]` and type `quit`. +[hyper-badge]: https://img.shields.io/crates/v/hyper.svg?label=hyper +[hyper]: https://docs.rs/hyper/ [reqwest-badge]: https://img.shields.io/crates/v/reqwest.svg?label=reqwest [reqwest]: https://docs.rs/reqwest/ [serde-badge]: https://img.shields.io/crates/v/serde.svg?label=serde @@ -773,6 +855,7 @@ After sending data in telnet press `ctrl-]` and type `quit`. [`io::copy`]: https://doc.rust-lang.org/std/io/fn.copy.html [`File`]: https://doc.rust-lang.org/std/fs/struct.File.html [`Url`]: https://docs.rs/url/1.*/url/struct.Url.html +[`Url::parse_with_params`]: https://docs.rs/url/1.*/url/struct.Url.html#method.parse_with_params [`parse`]: https://docs.rs/url/1.*/url/struct.Url.html#method.parse [`url::Position`]: https://docs.rs/url/*/url/enum.Position.html [`origin`]: https://docs.rs/url/1.*/url/struct.Url.html#method.origin @@ -783,10 +866,14 @@ After sending data in telnet press `ctrl-]` and type `quit`. [`Response::url`]: https://docs.rs/reqwest/*/reqwest/struct.Response.html#method.url [`Response::json`]: https://docs.rs/reqwest/*/reqwest/struct.Response.html#method.json [`RequestBuilder::basic_auth`]: https://docs.rs/reqwest/*/reqwest/struct.RequestBuilder.html#method.basic_auth +[`header::UserAgent`]: https://docs.rs/hyper/*/hyper/header/struct.UserAgent.html +[`header::Authorization`]: https://docs.rs/hyper/*/hyper/header/struct.Authorization.html +[`hyper::header!`]: https://docs.rs/hyper/*/hyper/macro.header.html [`Client::delete`]: https://docs.rs/reqwest/*/reqwest/struct.Client.html#method.delete [`Client::post`]: https://docs.rs/reqwest/*/reqwest/struct.Client.html#method.post [`RequestBuilder::body`]: https://docs.rs/reqwest/0.6.2/reqwest/struct.RequestBuilder.html#method.body [`RequestBuilder::json`]: https://docs.rs/reqwest/*/reqwest/struct.RequestBuilder.html#method.json +[`RequestBuilder::header`]: https://docs.rs/reqwest/*/reqwest/struct.RequestBuilder.html#method.header [`RequestBuilder::send`]: https://docs.rs/reqwest/*/reqwest/struct.RequestBuilder.html#method.send [`read_to_string`]: https://doc.rust-lang.org/std/io/trait.Read.html#method.read_to_string [`String`]: https://doc.rust-lang.org/std/string/struct.String.html