rename execute() to stream_items() where appropriate

README.md

@@ -76,7 +76,7 @@ async fn main() {
     .with_filter("{status} = 'Todo' || {status} = 'In Progress'".to_owned())
     .build()
     .unwrap()
-    .execute::<MyRecord>()
+    .stream_items::<MyRecord>();
 
   while let Some(result) = rec_stream.next().await {
     let rec = result.unwrap();

ferrtable-test/src/main.rs

@@ -1,5 +1,5 @@
 use ferrtable::Client;
-use futures::prelude::*;
+use futures::StreamExt as _;
 use serde::{Deserialize, Serialize};
 
 use crate::settings::Settings;
@@ -45,15 +45,20 @@ async fn main() {
         .unwrap();
 
     println!("Testing Client::list_records()...");
-    let mut records = client
+    let records = client
         .list_records()
         .with_base_id(settings.base_id.clone())
         .with_table_id(settings.table_id.clone())
         .build()
         .unwrap()
-        .execute::<TestRecord>();
+        .stream_items::<TestRecord>()
-    while let Some(res) = records.next().await {
+        .collect::<Vec<_>>()
-        dbg!(res.unwrap().fields);
+        .await
+        .into_iter()
+        .collect::<Result<Vec<_>, _>>()
+        .unwrap();
+    for rec in records {
+        dbg!(rec.fields);
     }
 
     println!("All tests succeeded.");

ferrtable/src/client.rs

@@ -44,11 +44,34 @@ impl Client {
         })
     }
 
-    /// Constructs a builder for inserting up to 10 records at a time into a
+    /// Creates multiple records. Note that table names and table ids can be
-    /// table.
+    /// used interchangeably. We recommend using table IDs so you don't need
+    /// to modify your API request when your table name changes.
     ///
-    /// Specify the base and table IDs with its `.with_base_id()` and
+    /// Your request body should include an array of up to 10 record objects.
-    /// `.with_table_id()` methods.
+    ///
+    /// Returns a unique array of the newly created record ids if the call
+    /// succeeds.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// client
+    ///     .create_records([
+    ///         HashMap<&str, &str>::from([
+    ///             ("name", "Steal Improbability Drive"),
+    ///             ("notes", "Just for fun, no other reason."),
+    ///             ("status", "In progress"),
+    ///         ]),
+    ///     ])
+    ///     .with_base_id("***".to_owned())
+    ///     .with_table_id("***".to_owned())
+    ///     .build()
+    ///     .unwrap()
+    ///     .execute()
+    ///     .await
+    ///     .unwrap();
+    /// ```
     pub fn create_records<I, T>(&self, records: I) -> CreateRecordsQueryBuilder<T>
     where
         T: Serialize,
@@ -59,10 +82,28 @@ impl Client {
             .with_records(records.into_iter().collect())
     }
 
-    /// Constructs a builder for listing records in a table or view.
+    /// List records in a table. Note that table names and table ids can be used
+    /// interchangeably. We recommend using table IDs so you don't need to modify
+    /// your API request when your table name changes.
     ///
-    /// Specify the base and table IDs with its `.with_base_id()` and
+    /// # Examples
-    /// `.with_table_id()` methods.
+    ///
+    /// ## Consuming as Stream
+    ///
+    /// ```no_run
+    /// let mut rec_stream = client
+    ///     .list_records()
+    ///     .with_base_id("***")
+    ///     .with_table_id("***")
+    ///     .build()
+    ///     .unwrap()
+    ///     .stream_items::<HashMap<String, serde_json::Value>>();
+    ///
+    /// while let Some(result) = rec_stream.next().await {
+    ///     let rec = result.unwrap();
+    ///     dbg!(rec.fields);
+    /// }
+    /// ```
     pub fn list_records(&self) -> ListRecordsQueryBuilder {
         ListRecordsQueryBuilder::default().with_client(self.clone())
     }

ferrtable/src/list_records.rs

@@ -88,35 +88,7 @@ macro_rules! handle_stream_err {
 }
 
 impl ListRecordsQuery {
-    /// Execute the API request.
+    pub fn stream_items<T>(
-    ///
-    /// Currently, failures return a one-size-fits-all error wrapping the
-    /// underlying `reqwest::Error`. This may be improved in future releases
-    /// to better differentiate between network, serialization, deserialization,
-    /// and API errors.
-    ///
-    /// Pagination is handled automatically, and items are returned as a
-    /// seemingly continuous stream of Results. If an error is encountered while
-    /// fetching a page, the Err will be yielded immediately and no further
-    /// items will be returned.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// let mut rec_stream = client
-    ///   .list_records()
-    ///   .with_base_id("***")
-    ///   .with_table_id("***")
-    ///   .build()
-    ///   .unwrap()
-    ///   .execute::<HashMap<String, String>>()
-    ///
-    /// while let Some(result) = rec_stream.next().await {
-    ///   let rec = result.unwrap();
-    ///   dbg!(rec.fields);
-    /// }
-    /// ```
-    pub fn execute<T>(
         self,
     ) -> Pin<Box<impl Stream<Item = Result<AirtableRecord<T>, ExecutionError>>>>
     where