Skip to content

Commit

Permalink
docs(client): add POST request example to client guide
Browse files Browse the repository at this point in the history
Add a new section to the "Getting Started with a Client" guide that
demonstrates how to make POST requests using hyper. The new section
includes examples for sending plain text, binary data, and JSON in
the request body, along with appropriate Content-Type headers.

This addition helps users understand how to construct and send POST
requests, complementing the existing GET request example.
  • Loading branch information
akneni committed Aug 18, 2024
1 parent e1cc8f0 commit 11d913c
Showing 1 changed file with 72 additions and 0 deletions.
72 changes: 72 additions & 0 deletions _stable/client/basic.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,78 @@ println!("Response status: {}", res.status());
# fn main() {}
```

## POST
Now that we've seen how to make a GET request, let's look at how to make a POST request. This is useful when you need to send data to the server, such as when submitting a form or uploading a file.

To make a POST request, we'll need to change a few things from our GET request:

1. We'll set the method to POST.
2. We'll need to provide a request body.
3. We'll need to specify the type of data in our body by adding a `hyper::header::CONTENT_TYPE` header.

For the body, we have a couple of options. We can use a simple string, a JSON string, or we can use raw bytes. Let's look at all three:

```rust
# extern crate http_body_util;
# extern crate hyper;
# extern crate hyper_util;
# extern crate tokio;
# use http_body_util::Empty;
# use hyper::body::Bytes;
# use hyper::Request;
# use hyper_util::rt::TokioIo;
# use tokio::net::TcpStream;
# async fn run() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
# let url = "http://httpbin.org/ip".parse::<hyper::Uri>()?;
# let host = url.host().expect("uri has no host");
# let port = url.port_u16().unwrap_or(80);
# let addr = format!("{}:{}", host, port);
# let stream = TcpStream::connect(addr).await?;
# let io = TokioIo::new(stream);
# let (mut sender, conn) = hyper::client::conn::http1::handshake(io).await?;
# tokio::task::spawn(async move {
# if let Err(err) = conn.await {
# println!("Connection failed: {:?}", err);
# }
# });

// The authority of our URL will be the hostname of the httpbin remote
let authority = url.authority().unwrap().clone();

// For plain text
let req_body = Full::<Bytes>::from("Some plain text as a body.");
let req = Request::builder()
.method(hyper::Method::POST)
.header(hyper::header::HOST, authority.as_str())
.header(hyper::header::CONTENT_TYPE, "text/plain")
.body(req_body)?;

// For binary data
let binary_data = vec![0u8; 128]; // Example binary data
let req_body = Full::<Bytes>::from(binary_data);
let req = Request::builder()
.method(hyper::Method::POST)
.header(hyper::header::HOST, authority.as_str())
.header(hyper::header::CONTENT_TYPE, "application/octet-stream")
.body(req_body)?;

// For JSON data (as previously mentioned)
let json_data = r#"{"key": "value"}"#;
let req_body = Full::<Bytes>::from(json_data);
let req = Request::builder()
.method(hyper::Method::POST)
.header(hyper::header::HOST, authority.as_str())
.header(hyper::header::CONTENT_TYPE, "application/json")
.body(req_body)?;

let res = sender.send_request(req).await?;

println!("Response status: {}", res.status());
# Ok(())
# }
# fn main() {}
```

## Response bodies

We know that sending a GET `Request` to `httpbin.org/ip` will return our IP address in
Expand Down

0 comments on commit 11d913c

Please sign in to comment.