docs: Mention chaining requests in README

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,6 +37,37 @@ 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?
+        .into_inner()
+        .get_site(&atlas_client)
+        .await?;
+
+
+    Ok(())
+}
+```
+
 ## Api Return Type
 
 ### Async Trait

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(())
+}

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::*,
     };
 }