ZuraGuerra / elixir-airtable-client

Client and caching proxy for airtable.com

Airtable

Planned Features and open questions

• replicate API features with basic REST features:
  • list
  • create
  • retrieve
  • update
  • replace
  • delete
• WIP: add filters/queries to list()
• retrieve all results for a larger set - iterate over offsets, respecting the rate limit of 5/s

Out-of scope

• act as caching proxies to overcome rate limiting
  • in-memory only first
• change notofications
  • plain callbacks via {module, function, args} tuples

These things will be done in a different project as this module with concentrate on the basic REST features themselves.

Intention

Base your own API wrapper by calling this application with specific API keys, table keys and stuff and also convert Airtable.Result.Item structs into whatever is your best matching thing. Usually you'd want to parse fields contents if said items further:

defmodule MyApp.Airtable.Film do

  defstruct title: nil, rental_id: nil, pegi: nil, teaser: nil

  def from_airtable_item(%Airtable.Result.Item{id: id, fields: map}) do
    struct(Film, map) # this will probably more complex in reality
  end

  def list do
    api_key   = Application.get_env(:airtable, :api_key)
    film_base = Application.get_env(:airtable, :film_base)
    with {:ok, %Airtable.Result.Likst{records: records}} <- Airtable.list(api_key, film_base, "films") do
      Enum.map(records, &from_airtable_item/1)
    end
  end
    
end

Installation

If available in Hex, the package can be installed by adding airtable to your list of dependencies in mix.exs:

def deps do
  [
    {:airtable, "~> 0.4.0"}
  ]
end

Usage

create

{:ok, %Airtable.Result.Item{id: id1, fields: %{"foo" => 1, "bar" => 2}}} = Airtable.create("<API_KEY>", "<TABLE_KEY>", "<TABLE_NAME>", fields: %{"foo" => 1, "bar" => 2})
{:ok, %Airtable.Result.Item{id: id2, fields: %{"foo" => 3, "bar" => 4}}} = Airtable.create("<API_KEY>", "<TABLE_KEY>", "<TABLE_NAME>", fields: %{"foo" => 3, "bar" => 4})

list

{:ok, result} = Airtable.list("<API_KEY>", "<table_key>", "<table_name>")

yields

{:ok ,
  %Airtable.Result.List{
    records: [
      %Airtable.Result.Item{id: ^id1, fields: %{"foo" => 1, "bar" => 2}},
      %Airtable.Result.Item{id: ^id2, fields: %{"foo" => 3, "bar" => 4}},
    ]
  }
}

list certain fields only

iex> Airtable.list("API_KEY", "app_BASE", "Filme", fields: ["title", "year"])
{:ok,
  %Airtable.Result.List{
    offset: nil,
    records: [
      %Airtable.Result.Item{
        fields: %{"year" => "2004", "title" => "Kill Bill Volume 2"},
        id: "recbummibaer12xx"
      },
      %Airtable.Result.Item{
        fields: %{"titke" => "A blonde dream"}, # <-- null and empty "" values will be removed by Airtable itself!
        id: "recfoobarbazbumm"
      },
      ...
    ]
  }
}

get (retrieve)

{:ok, get_result} = Airtable.get("<API_KEY>", "<TABLE_KEY>", "<TABLE_NAME>", id1)

yields:

{:ok, %Airtable.Result.Item{id: id1, fields: %{"foor" => 1, "bar" => 2}}}

replace

This will overwrite all fields in the existing row. Keys not goven in fields map will be nil-ified.

{:ok, get_result} = Airtable.replace("<API_KEY>", "<TABLE_KEY>", "<TABLE_NAME>", id1, fields: %{"foo" => 5, "bar" => 6})

yields:

{:ok, %Airtable.Result.Item{id: id1, fields: %{"foor" => 5, "bar" => 6}}}

update

This will update only those fields present in the argument fields map. Alle others will be kept.

{:ok, get_result} = Airtable.update("<API_KEY>", "<TABLE_KEY>", "<TABLE_NAME>", id1, fields: %{"foo" => 7})

yields:

{:ok, %Airtable.Result.Item{id: id1, fields: %{"foor" => 7, "bar" => 6}}}

delete

{:ok, id1} = Airtable.delete("<API_KEY>", "<TABLE_KEY>", "<TABLE_NAME>", id1)

Documentation

A full description of all available calls is on HexDocs: https://hexdocs.pm/airtable