brent/ferrtable
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update docs

Browse source
This commit is contained in:
Brent Schroeter 2025-09-16 22:46:37 -07:00
parent c8337c182a
commit 2e9f787154
2 changed files with 138 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

101
README.md
View file

@ -1,11 +1,16 @@
# Ferrtable: Ferris the Crab's Favorite Airtable Client # Ferrtable: Ferris the Crab's Favorite Airtable Client
A power vacuum churns where the venerable Ferrtable provides async Rust bindings for a subset of the
[airtable-api](https://crates.io/crates/airtable-api) (archived but not [Airtable web API](https://airtable.com/developers/web/api/introduction).
forgotten) once stood tall. The world calls for a new leader to carry the Notably, it allows records to be read from and written to arbitrary Rust types
fallen torch. From the dust rises Ferrtable: to abase SQL supremacy, to turn that implement the `Clone`, `serde::Deserialize`, and `serde::Serialize` traits.
all the tables, to rise inexorably to the top of the field, and to set the
record straight. This crate follows in the footsteps of the
[airtable-api](https://crates.io/crates/airtable-api) crate from Oxide Computer
Company, which appears to have be archived and unmaintained since 2022.
By comparison, Ferrtable aims to provide a more flexible and expressive client
interface as well as greater control over paginated responses with the help of
async [streams](https://doc.rust-lang.org/book/ch17-04-streams.html).
## Status: Work in Progress ## Status: Work in Progress
@ -23,64 +28,64 @@ use futures::prelude::*;
// Deserialize, and Serialize. // Deserialize, and Serialize.
#[derive(Clone, Debug, Deserialize, Serialize)] #[derive(Clone, Debug, Deserialize, Serialize)]
struct MyRecord { struct MyRecord {
#[serde(rename = "Name")] #[serde(rename = "Name")]
name: String, name: String,
#[serde(rename = "Notes")] #[serde(rename = "Notes")]
notes: String, notes: String,
#[serde(rename = "Assignee")] #[serde(rename = "Assignee")]
assignee: Option<String>, assignee: Option<String>,
#[serde(rename = "Status")] #[serde(rename = "Status")]
status: Status, status: Status,
#[serde(rename = "Attachments")] #[serde(rename = "Attachments")]
attachments: Vec<ferrtable::cell_values::AttachmentRead>, attachments: Vec<ferrtable::cell_values::AttachmentRead>,
} }
#[derive(Clone, Debug, Deserialize, Serialize)] #[derive(Clone, Debug, Deserialize, Serialize)]
enum Status { enum Status {
Todo, Todo,
#[serde(rename = "In progress")] #[serde(rename = "In progress")]
InProgress, InProgress,
Done, Done,
} }
#[tokio::main] #[tokio::main]
async fn main() { async fn main() {
let client = ferrtable::Client::new_from_access_token("******").unwrap(); let client = ferrtable::Client::new_from_access_token("******").unwrap();
client client
.create_records([MyRecord { .create_records([MyRecord {
name: "Steal Improbability Drive".to_owned(), name: "Steal Improbability Drive".to_owned(),
notes: "Just for fun, no other reason.".to_owned(), notes: "Just for fun, no other reason.".to_owned(),
assignee: None, assignee: None,
status: Status::InProgress, status: Status::InProgress,
attachments: vec![], attachments: vec![],
}]) }])
.with_base_id("***".to_owned()) .with_base_id("***".to_owned())
.with_table_id("***".to_owned()) .with_table_id("***".to_owned())
.build() .build()
.unwrap() .unwrap()
.execute() .execute()
.await .await
.unwrap(); .unwrap();
let mut rec_stream = client let mut rec_stream = client
.list_records() .list_records()
.with_base_id("***".to_owned()) .with_base_id("***".to_owned())
.with_table_id("***".to_owned()) .with_table_id("***".to_owned())
.with_filter("{status} = 'Todo' || {status} = 'In Progress'".to_owned()) .with_filter("{status} = 'Todo' || {status} = 'In Progress'".to_owned())
.build() .build()
.unwrap() .unwrap()
.stream_items::<MyRecord>(); .stream_items::<MyRecord>();
while let Some(result) = rec_stream.next().await { while let Some(result) = rec_stream.next().await {
let rec = result.unwrap(); let rec = result.unwrap();
dbg!(rec.fields); dbg!(rec.fields);
} }
} }
``` ```

85
ferrtable/src/lib.rs
View file

@ -1,3 +1,88 @@
//! # Ferrtable: Ferris the Crab's Favorite Airtable Client
//!
//! ## Status: Work in Progress
//!
//! Only a limited set of operations are currently supported. Any version bumps
//! before version 0.1 may include breaking changes to the crate API.
//!
//! ## Usage
//!
//! ```ignore
//! use futures::prelude::*;
//!
//! // Ferrtable allows us to use any record types that implement Clone,
//! // Deserialize, and Serialize.
//! #[derive(Clone, Debug, Deserialize, Serialize)]
//! struct MyRecord {
//! #[serde(rename = "Name")]
//! name: String,
//!
//! #[serde(rename = "Notes")]
//! notes: String,
//!
//! #[serde(rename = "Assignee")]
//! assignee: Option<String>,
//!
//! #[serde(rename = "Status")]
//! status: Status,
//!
//! #[serde(rename = "Attachments")]
//! attachments: Vec<ferrtable::cell_values::AttachmentRead>,
//! }
//!
//! #[derive(Clone, Debug, Deserialize, Serialize)]
//! enum Status {
//! Todo,
//!
//! #[serde(rename = "In progress")]
//! InProgress,
//!
//! Done,
//! }
//!
//! #[tokio::main]
//! async fn main() {
//! let client = ferrtable::Client::new_from_access_token("******").unwrap();
//!
//! client
//! .create_records([MyRecord {
//! name: "Steal Improbability Drive".to_owned(),
//! notes: "Just for fun, no other reason.".to_owned(),
//! assignee: None,
//! status: Status::InProgress,
//! attachments: vec![],
//! }])
//! .with_base_id("***".to_owned())
//! .with_table_id("***".to_owned())
//! .build()
//! .unwrap()
//! .execute()
//! .await
//! .unwrap();
//!
//! let mut rec_stream = client
//! .list_records()
//! .with_base_id("***".to_owned())
//! .with_table_id("***".to_owned())
//! .with_filter("{status} = 'Todo' || {status} = 'In Progress'".to_owned())
//! .build()
//! .unwrap()
//! .stream_items::<MyRecord>();
//!
//! while let Some(result) = rec_stream.next().await {
//! let rec = result.unwrap();
//! dbg!(rec.fields);
//! }
//! }
//! ```
//!
//! ## Features
//!
//! ### `chrono`
//!
//! Deserializes certain Airtable timestamp fields as `chrono::DateTime` values
//! instead of [`String`]s. Disabled by default.
pub mod cell_values; pub mod cell_values;
pub mod client; pub mod client;
pub mod errors; pub mod errors;