From e52b5b090ae28102af87bcc99c0ce6d43e69935d Mon Sep 17 00:00:00 2001
From: Caleb Leinz <caleb.leinz@atlasspace.com>
Date: Wed, 31 Jul 2024 10:35:13 -0700
Subject: [PATCH] docs: Mention chaining requests in README

---
 README.md                           | 34 +++++++++++++++++++++++++++--
 examples/fetch_site_from_request.rs | 19 ++++++++++++++++
 src/lib.rs                          |  2 +-
 3 files changed, 52 insertions(+), 3 deletions(-)
 create mode 100644 examples/fetch_site_from_request.rs

diff --git a/README.md b/README.md
index e73a66d..74a2add 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         .secret_from_env()?
         .build()?;
 
-    let mut atlas_client = Client::from_config(atlas_config);
+    let atlas_client = Client::from_config(atlas_config);
 
     // Query Freedom for a list of all Satellites, printing the names of the satellite which
     // passed deserialization
@@ -37,12 +37,42 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
+## Chaining API returns
+
+Many of the data types exposed in this library can be navigated to through other
+resources, for instance a task request object holds links to the site object the
+task was scheduled at.
+
+Rather than making a call to fetch the request, then parse the site ID, then
+request the site from the ID, you can instead fetch the site directly from the
+return of the request call
+
+```rust, no_run
+use freedom_api::prelude::*;
+use freedom_config::Config;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let atlas_config = Config::from_env()?;
+    let atlas_client = Client::from_config(atlas_config);
+
+    let site_from_request: Site = atlas_client
+        .get_request_by_id(42)
+        .await?
+        .get_site(&atlas_client)
+        .await?;
+
+
+    Ok(())
+}
+```
+
 ## Api Return Type
 
 ### Async Trait
 
 When looking at the return type of the API methods, they may appear daunting. This is mostly
-resulting from async lifetimes brought about by useage of [`async_trait`](https://docs.rs/async-trait/latest/async_trait/).
+resulting from async lifetimes brought about by usage of [`async_trait`](https://docs.rs/async-trait/latest/async_trait/).
 Once the [async trait feature](https://blog.rust-lang.org/inside-rust/2023/05/03/stabilizing-async-fn-in-trait.html)
 is release in stable rust. This complexity will be alleviated.
 
diff --git a/examples/fetch_site_from_request.rs b/examples/fetch_site_from_request.rs
new file mode 100644
index 0000000..3e471a8
--- /dev/null
+++ b/examples/fetch_site_from_request.rs
@@ -0,0 +1,19 @@
+use freedom_api::prelude::*;
+use freedom_config::Config;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let atlas_config = Config::from_env()?;
+    let atlas_client = Client::from_config(atlas_config);
+
+    let site_from_request: Site = atlas_client
+        .get_request_by_id(42)
+        .await?
+        .into_inner()
+        .get_site(&atlas_client)
+        .await?;
+
+    println!("{:?}", site_from_request);
+
+    Ok(())
+}
diff --git a/src/lib.rs b/src/lib.rs
index ac2d7db..e344db0 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -24,7 +24,7 @@ pub mod prelude {
         error::{BuilderError, Error, RuntimeError},
     };
     pub use freedom_models::{
-        account::*, satellite::*, satellite_configuration::*, task::*, user::*,
+        account::*, satellite::*, satellite_configuration::*, site::*, task::*, user::*,
     };
 }