airrecord 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 90f1c342a1a2ed5bc00e4039374d9eea8e03ea79
-  data.tar.gz: b31904546125ec0e92805f37876b69cb8b8d8604
+  metadata.gz: fa2416d29667f3621c84a16cf761cf065a98be8e
+  data.tar.gz: bbc197ae2c88828c9b90580e45d4cb011729ee21
 SHA512:
-  metadata.gz: 032d7be64c9e5bca336acad19c9a9a0839f184c70f53f7837c6191d03ca0df3484626579e5cdfbc6922b2956a4bbac7adee572679026be261689b9148264ee7a
-  data.tar.gz: 5905798573a9174a9f369cd50cbcef85c9c5e39b69bdfb3c001f048dca4c1b910787a62fe0c5d4fa956f1c67bf322dfa1d9a31070e763b678a334fa63dc53fc4
+  metadata.gz: 94ba94acd00c8262b7d77b75641721cfe4f61d2c9f8bd93b567154e128eb03ade3c3ddfda2d0e9db4b09b5bfd1d3c151901e6144f57f5238b73ce702843b75ea
+  data.tar.gz: 83392e39f08594d19976e2803c11c0e7ef4e34aec2a731bb569a845808d6311a67d9787393e884e44e67d2776aaf1934cc04270ec65a4043218938e012ec5ad1

data/README.md

@@ -1,81 +1,276 @@
 # Airrecord
 
-Airrecord is an alternative to
-[`airtable-ruby`](https://github.com/airtable/airtable-ruby). Airrecord takes an
-approach to approaching Airtable more like a database from Ruby's point of view,
-inviting inspiration from ActiveRecord's API.
+Airrecord is an alternative Airtable Ruby libary to
+[`airtable-ruby`](https://github.com/airtable/airtable-ruby). Airrecord attempts
+to enforce a more [database-like API to
+Airtable](http://sirupsen.com/minimum-viable-airtable/).
+
+You can add this line to your Gemfile to use Airrecord:
 
 ```ruby
 gem 'airrecord'
 ```
 
-This library is provided to enforce a mental model of a database, as described
-in [this post](http://sirupsen.com/minimum-viable-airtable/). Furthermore as an
-alternative to the [official
-library](https://github.com/airtable/airtable-ruby).
-
-## Examples
-
-There's a simple API that allows more ad-hoc querying of Airtable:
+A quick example to give an idea of the API that Airrecord provides:
 
 ```ruby
-teas = Airrecord.table("key1", "app1", "Teas")
+Airrecord.api_key = "key1"
 
-teas.records.each do |record|
-  puts "#{record.id}: #{record[:name]}"
-end
+class Tea < Airrecord::Table
+  self.base_key = "app1"
+  self.table_name = "Teas"
 
-p teas.find(teas.records.first.id)
-```
+  has_many :brews, class: 'Brew', column: "Brews"
 
-Then there's the API which allows you to define tables as classes and
-relationships between them. This maps with ActiveRecord models. This makes
-working with relationships much easier, and allows you to define domain-specific
-logic on the models.
+  def location
+    [self[:village], self[:country], self[:region]].compact.join(", ")
+  end
+end
 
-```ruby
 class Brew < Airrecord::Table
-  self.api_key = "key1"
   self.base_key = "app1"
-  self.table_name = "Hot Brews"
+  self.table_name = "Brews"
 
   belongs_to :tea, class: 'Tea', column: 'Tea'
 end
 
+teas = Tea.all
+tea = teas.first
+tea[:country] # access atribute
+tea.location # instance methods
+tea[:brews] # associated brews
+```
+
+## Documentation
+
+### Authentication
+
+To obtain your API client, navigate to the [Airtable's API
+page](https://airtable.com/api), select your base and obtain your API key and
+application token.
+
+![](https://cloud.githubusercontent.com/assets/97400/23580721/a0815df4-00bb-11e7-9abf-140a01625678.png)
+
+You can provide a global API key with:
+
+```ruby
+Airrecord.api_key = "your api key"
+```
+
+The app token has to be set on the definitions of the tables (see API below).
+You can override the API key per table.
+
+### Table
+
+The Airrecord API is centered around definitions of `Airrecord::Table` from
+which the definitions of your tables inherit. This is analogous to
+`ActiveRecord::Base`. For example, we may have a Base to track teas we have
+tried.
+
+```ruby
+Airrecord.api_key = "your api key" # see authentication section
+
 class Tea < Airrecord::Table
-  self.api_key = "key1"
   self.base_key = "app1"
   self.table_name = "Teas"
 
-  has_many :hot_brews, class: 'Brew', column: "Hot Brews"
-
   def location
     [self[:village], self[:country], self[:region]].compact.join(", ")
   end
 end
+```
+
+This gives us a class that maps to records in a table. Class methods are
+available to fetch records on the table.
+
+### Listing Records
+
+Retrieval of multiple records is done through `#all`. To get all records in a
+table:
+
+```ruby
+Tea.all # array of Tea instances
+```
+
+You can use all options supported by the API (they are documented on the [API page for your base](https://airtable.com/api)). By default `#all` will traverse all pages, see below on how to control pagination.
+
+To use `filterbyFormula` to filter returned records:
+
+```ruby
+# Retrieve all teas from China
+Tea.all(filter: "{Country} == "China")
+
+# Retrieve all teas created in the past week
+Tea.all(filter: "DATETIME_DIFF(CREATED_TIME(), TODAY(), 'days') < 7")
+```
 
-tea = Tea.all[2]
-brew = tea[:hot_brews].first
-brew[:tea].id == tea.id
+This filtering can, of course, also be done in Ruby directly after calling
+`#all` without `filter`, however, it may be more efficient to let Airtable
+filter if you have a lot of records.
 
-tea = Tea.new(Name: "omg tea", Type: ["Oolong"])
-tea.create
+You can use `view` to only fetch records from a specific view. This is less
+ad-hoc than `filterByFormula`:
 
-tea[:name] = "super omg tea"
-tea.save
+```ruby
+# Retrieve all teas in the green tea view
+Tea.all(view: "Green")
+
+# Retrieve all Japanese teas
+Tea.all(view: "Japan")
+```
+
+The `sort` option can be used to sort results returned from the Airtable API.
 
-tea = Tea.find(tea.id)
-puts tea[:name]
-# => "super omg tea"
+```ruby
+# Sort teas by the Name column in ascending order
+Tea.all(sort: { Name: "asc" })
 
-brew = Brew.new(Tea: [tea], Rating: "3 - Fine")
-brew.create
+# Sort teas by Type (green, black, oolong, ..) in descending order
+Tea.all(sort: { Type: "desc" })
 
-tea = Tea.find(tea.id)
-puts tea[:hot_brews].first[:rating]
-# => "3 - Fine"
+# Sort teas by price in descending order
+Tea.all(sort: { Price: "desc" })
 ```
 
+Note again that the key _must_ be the full column name. Snake-cased variants do
+not work here.
+
+As mentioned above, by default Airrecord will return results from all pages.
+This can be slow if you have 1000s of records. You may wish to use the `view`
+and/or `filter` option to sort in the results early, instead of doing 10s of
+calls. Airrecord will _always_ fetch the maximum possible amount of records
+(100). This means that fetching 1,000 records will take 10 (at least) roundtrips. You can disable pagination (which fetches the first page) by passing `paginate: false`. This is especially useful if you're looking to fetch a set of recent records from a view or formula in tandem with a `sort`:
+
+```ruby
+# Only fetch the first page. Sorting is undefined.
+Tea.all(paginate: false)
+
+# Give me only the most recent teas
+Tea.all(sort: { "Created At": "desc" }, paginate: false)
+```
+
+### Creating
+
+Creating a new record is done through `#create`.
+
+```ruby
+tea = Tea.new("Name" => "Feng Gang", "Type" => "Green", "Country" => "China")
+tea.create # creates the record
+tea.id # id of the new record
+tea[:name] # "Feng Gang", accessed through snake-cased name
+```
+
+Note that when instantiating the new record the column names (keys of the passed
+named parameters) need to match the exact column names in Airtable, otherwise
+Airrecord will throw an error that no column matches it.
+
+In the future I hope to provide more convient names for these (snake-cased),
+however, this is error-prone without a proper schema API from Airtable which has
+still not been released.
+
+### Updating
+
+Updating a record is done by changing the attributes and persistent to
+Airtable with `#save`.
+
+```ruby
+tea = Tea.find("someid")
+tea[:name] = "Feng Gang Organic"
+
+# Since the Village column is not set, we do not have access to a snake-cased
+variant since the mapping is not determined. For all we know, the correct column
+name could be "VilLlaGe". Therefore, we must use the proper column name.
+tea["Village"] = "Feng Gang"
+
+tea.save # persist to Airtable
+```
+
+### Deleting
+
+An instantiated record can be deleted through `#destroy`:
+
+```ruby
+tea = Tea.find("rec839")
+tea.destroy # deletes record
+```
+
+### Associations
+
+Airrecord supports managing associations between tables by linking
+`Airrecord::Table` classes. To continue with our tea example, we may have
+another table in the base to track brews of a specific tea (temperature,
+steeping time, rating, ..). A tea thus has many brews:
+
+```ruby
+class Tea < Airrecord::Table
+  self.base_key = "app1"
+  self.table_name = "Teas"
+
+  has_many :brews, class: 'Brew', column: "Brews"
+end
+
+class Brew < Airrecord::Table
+  self.base_key = "app1"
+  self.table_name = "Brews"
+
+  belongs_to :tea, class: 'Tea', column: 'Tea'
+end
+```
+
+This gives us access to a bunch of convenience methods to handle the assocation
+between the two tables. Note that the two tables need to be in the same base
+(i.e. have the same base key) otherwise this will _not_ work as Airtable does
+_not_ support associations across Bases.
+
+### Retrieving associated records
+
+To retrieve records from associations to a record:
+
+```ruby
+tea = Tea.find('rec84')
+tea[:brews] # brews associated with tea
+```
+
+This in turn works the other way too:
+
+```ruby
+brew = Brew.find('rec849')
+brew[:tea] # the associated tea instance
+```
+
+### Creating associated records
+
+You can easily associate records with each other:
+
+```ruby
+tea = Tea.find('rec849829')
+# This will create a brew associated with the specific tea
+Brew.create("Tea" => tea, "Temperature" => "80", "Time" => "4m", "Rating" => "5")
+```
+
+### Ad-hoc API
+
+Airrtable provides a simple, ad-hoc API that will instantiate an anonymous
+`Airrecord::Table` for you on the fly with the configured key, app, and table.
+
+```ruby
+teas = Airrecord.table("key1", "app1", "Teas")
+
+teas.records.each do |record|
+  puts "#{record.id}: #{record[:name]}"
+end
+
+p teas.find(teas.records.first.id)
+```
+
+### Snake-cased helper methods
+
+When retrieving an existing record from Airtable, snake-cased helper names are
+available to index attributes. These are _only_ available on retrieved records,
+and _only_ if the column was set. If it's `nil`, it will not exist. That means
+if you want to set column that has a `nil` value for a column type, you'll have
+to fully type it out.
+
 ## Contributing
 
 Contributions will be happily accepted in the form of Github Pull Requests!

data/lib/airrecord.rb

@@ -6,5 +6,7 @@ require "airrecord/client"
 require "airrecord/table"
 
 module Airrecord
+  extend self
   Error = Class.new(StandardError)
+  attr_accessor :api_key
 end

data/lib/airrecord/table.rb

@@ -13,7 +13,8 @@ module Airrecord
       attr_accessor :base_key, :table_name, :api_key, :associations
 
       def client
-        @@client ||= Client.new(api_key)
+        @@clients ||= {}
+        @@clients[api_key] ||= Client.new(api_key)
       end
 
       def has_many(name, options)
@@ -27,6 +28,10 @@ module Airrecord
         has_many(name, options.merge(single: true))
       end
 
+      def api_key
+        @api_key || Airrecord.api_key
+      end
+
       def find(id)
         response = client.connection.get("/v0/#{base_key}/#{client.escape(table_name)}/#{id}")
         parsed_response = client.parse(response.body)

data/lib/airrecord/version.rb

@@ -1,3 +1,3 @@
 module Airrecord
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: airrecord
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Simon Eskildsen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-02-25 00:00:00.000000000 Z
+date: 2017-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday