Airtable API Wrapper for Ruby

For when Airrecord is just too much.

Note on library status

This is a fork of an abandoned previous wrapper. There’s still plenty to do to get it up to speed with the current Airtable API.

Installation

Add this line to your application’s Gemfile:

gem 'airtable2'

And then execute:

$ bundle

Usage

Creating a Client

First, be sure to register for an airtable account, setup a base, and create a token with the desired permissions for your base. Now, setup your Airtable client:

# Pass in api key to client
@client = Airtable::Client.new('your.token.goes.here')

Simple Usage

Reading

Now we can access our base

# Retrieve with a specific ID
@base = @client.base('appExAmPlE')
# or
@base = @client.bases.first

and its tables

# Retrieve with a specific ID
@table = @base.table('tblExAmPle')
# or
@table = @base.tables.first

and a table’s records,

# Retrieve with a specific ID
@record = @table.record('recExAmPle')
# or
@record = @table.records.first

so you can navigate the belongs_to/has_many relationships the way God intended:

@record = @client.bases.first.tables.first.records.first
@base = @record.table.base

Note that objects’ child records are memoized to avoid unnecessary API calls. If sensitive to stale data, be sure to use the objects instantiated most recently.

To get the fields of a table, its simply

@fields = @table.fields

Writing

Create a table in a base like so

@table = @base.create_table({ name: 'Names', description: 'A list of names', fields: [{ name: 'name', type: 'singleLineText' }] })

You can update at a table’s metadata with the update method:

@table.update({ description: 'Updated description' })

You can add a column to a table…

@field = @table.add_field({'description': 'Whether I have visited this apartment yet.', 'name': 'Visited', 'type': 'checkbox', 'options': { 'color': 'greenBright', 'icon': 'check'} })

…and update it

@field = @field.update({'description': 'Whether I have rented this apartment yet.', 'name': 'Rented'})

A single record or an array of records can be inserted using the create_records method on a table (max 10 at a time):

# Single
@table.create_records({ 'Name': 'name value', 'Age': 35 })
# Array
@table.create_records([{ 'Name': 'name value', 'Age': 35 }, { 'Name': 'another name value', 'Age': 40 }])

You can upsert records by calling upsert_records and providing the field names to match to (also max 10 at a time):

# Array
records_to_upsert = [{ 'Name': 'name value', 'Age': 35 }, { 'Name': 'another name value', 'Age': 40 }]
@table.upsert_records(records_to_upsert, ['Name'])

A single record or an array of records can be destroyed by passing their ids to the delete_records method on a table (max 10 at a time):

@records = @table.records
# Single
@table.delete_records(@records.first.id)
# Array
@table.delete_records(@records.map(&:ids))

Or as a convenience, you can delete all records with the dump method, which will abide by the API’s rate limiting.

@table.dump

Complete documentation

YARD-generated documentation is hosted on GitHub Pages.

Contributing

  1. Fork it ( github.com/aseroff/airtable-ruby/fork )

  2. Create your feature branch (git checkout -b my-new-feature)

  3. Commit your changes (git commit -am 'Add some feature')

  4. Push to the branch (git push origin my-new-feature)

  5. Create a new Pull Request