From 24a13216739d1e454d683ba198960ead55d988e0 Mon Sep 17 00:00:00 2001
From: Andrea Longo <feorlen@users.noreply.github.com>
Date: Fri, 23 May 2025 10:17:32 -0600
Subject: [PATCH] Update the README with additional information (#159)

Clarify and add additional information about the Rust SDK, in preparation for automated inclusion in the public documentation.

- Minor rework of existing text
- Incorporate documentation from src/lib.rs in the readme

---------

Co-authored-by: Andrea Longo <95028+feorlen@users.noreply.github.com>
---
 README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 47 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5accd94..7ba3f9c 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,58 @@
 # MinIO Rust SDK for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Sourcegraph](https://sourcegraph.com/github.com/minio/minio-rs/-/badge.svg)](https://sourcegraph.com/github.com/minio/minio-rs?badge) [![Apache V2 License](https://img.shields.io/badge/license-Apache%20V2-blue.svg)](https://github.com/minio/minio-rs/blob/master/LICENSE)
 
-MinIO Rust SDK is Simple Storage Service (aka S3) client to perform bucket and object operations to any Amazon S3 compatible object storage service.
+The MinIO Rust SDK is a Simple Storage Service (aka S3) client for performing bucket and object operations to any Amazon S3 compatible object storage service.
+It provides a strongly-typed, async-first interface to the MinIO and Amazon S3-compatible object storage APIs.
+
+Each supported S3 operation has a corresponding request builder (for example: [`BucketExists`], [`PutObject`], [`UploadPartCopy`]), which allows users to configure request parameters using a fluent builder pattern.
+
+All request builders implement the [`S3Api`] trait, which provides the async [`send`](crate::s3::types::S3Api::send) method to execute the request and return a typed response.
+
+
+## Basic Usage
+
+```no_run
+use minio::s3::Client;
+use minio::s3::types::S3Api;
+use minio::s3::response::BucketExistsResponse;
+
+#[tokio::main]
+async fn main() {
+    let client: Client = Default::default(); // configure your client
+
+    let exists: BucketExistsResponse = client
+        .bucket_exists("my-bucket")
+        .send()
+        .await
+        .expect("request failed");
+
+    println!("Bucket exists: {}", exists.exists);
+}
+```
+
+## Features
+
+- Request builder pattern for ergonomic API usage
+- Full async/await support via [`tokio`]
+- Strongly-typed responses
+- Transparent error handling via `Result<T, Error>`
+
+
+## Design
+
+- Each API method on the [`Client`] returns a builder struct
+- Builders implement [`ToS3Request`] for request conversion and [`S3Api`] for execution
+- Responses implement [`FromS3Response`] for consistent deserialization
 
-For a complete list of APIs and examples, please take a look at the [MinIO Rust Client API Reference](https://minio-rs.min.io/)
 
 ## Examples
 
-Run the examples from the command line with:
+You can run the examples from the command line with:
 
 `cargo run --example <example_name>`
 
+The examples below cover several common operations.
+You can find the complete list of examples in the `examples` directory.
+
 ### file_uploader.rs
 
 * [Upload a file to MinIO](examples/file_uploader.rs)
@@ -23,5 +66,6 @@ Run the examples from the command line with:
 
 * [Prompt a file on MinIO](examples/object_prompt.rs)
 
+
 ## License
 This SDK is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0), see [LICENSE](https://github.com/minio/minio-rs/blob/master/LICENSE) for more information.