airtable

README

Airtable Go Client Library

Installation

Make sure you have Golang v1.6 or higher installed. If not, install it now.

Fetch airtable-go:

go get github.com/fabioberger/airtable-go

Import airtable-go into your project:

import "github.com/fabioberger/airtable-go"

Usage

Create an instance of the airtable-go client:

import (
	"os"
	"github.com/fabioberger/airtable-go"
)

airtableAPIKey := os.Getenv("AIRTABLE_API_KEY")
baseID := "apphllLCpWnySSF7q" // replace this with your airtable base's id

client, err := airtable.New(airtableAPIKey, baseID)
if err != nil {
	panic(err)
}

You can now call methods on the client instance. All client methods are documented in the project's GoDoc page. You can also check out the stubbed and integration tests included in this project for working examples of all the client methods and options.

For Airtable specific documentation, see the interactive documentation at https://airtable.com/api.

Tests

Execute the following to run the stubbed out unit tests:

go test -v ./tests/stubbed_tests

In order to run the integration tests, you will need to copy this test Airtable base into your own Airtable account using the "copy base" button in the top right.

Next, set two environment variables corresponding to your Airtable API key and the baseID of your copy of the test Airtable base.

export AIRTABLE_TEST_API_KEY=YOUR_API_KEY
export AIRTABLE_TEST_BASE_ID=YOUR_TEST_BASE_ID

Now you can run the integration tests with:

go test -v ./tests/integration_tests

Versioning

This library uses Semantic Versioning.

Documentation

Index

• type Attachment
• type Client
  • func New(apiKey, baseID string) (*Client, error)
  • func (c *Client) CreateRecord(tableName string, record interface{}) error
  • func (c *Client) DestroyRecord(tableName, recordID string) error
  • func (c *Client) ListRecords(tableName string, recordsHolder interface{}, listParams ...ListParameters) error
  • func (c *Client) RetrieveRecord(tableName string, recordID string, recordHolder interface{}) error
  • func (c *Client) UpdateRecord(tableName, recordID string, updatedFields map[string]interface{}, ...) error
• type Error
  • func (e Error) Error() string
• type ListParameters
  • func (l *ListParameters) URLEncode() string
• type SortParameter

Examples

• Client.CreateRecord
• Client.DestroyRecord
• Client.ListRecords
• Client.RetrieveRecord
• Client.UpdateRecord
• ListParameters
• New

Types

type Attachment

type Attachment struct {
	ID         string `json:"id"`
	URL        string `json:"url"`
	FileName   string `json:"filename"`
	Size       int64  `json:"size"`
	Type       string `json:"type"`
	Thumbnails struct {
		Small thumbnail `json:"small"`
		Large thumbnail `json:"large"`
	} `json:"thumbnails"`
}

Attachment models the response returned by the Airtable API for an attachment field type. It can be used in your record type declarations that include attachment fields.

type Client

type Client struct {
	ShouldRetryIfRateLimited bool
	HTTPClient               *http.Client
	// contains filtered or unexported fields
}

Client exposes the interface for sending requests to the Airtable API. After instantiation, one can further configure the client by setting the `ShouldRetryIfRateLimited` property which defaults to true, or by setting `HTTPClient` to a custom *http.Client instance.

func New

func New(apiKey, baseID string) (*Client, error)

New creates a new instance of the Airtable client

Example

package main

import (
	"fmt"
	"os"

	airtable "github.com/fabioberger/airtable-go"
)

func main() {
	airtableAPIKey := os.Getenv("AIRTABLE_API_KEY")
	baseID := "apphllLCpWnySSF7q"

	client, err := airtable.New(airtableAPIKey, baseID)
	if err != nil {
		panic(err)
	}

	fmt.Println(client)
}

func (*Client) CreateRecord

func (c *Client) CreateRecord(tableName string, record interface{}) error

CreateRecord creates a new record in an Airtable table and updates the `record` struct with the created records field values i.e fields with default values would be populated as well as AirtableID with the record's id.

Example

package main

import (
	airtable "github.com/fabioberger/airtable-go"
)

func main() {
	client, _ := airtable.New("AIRTABLE_API_KEY", "BASE_ID")

	type task struct {
		AirtableID string
		Fields     struct {
			Name  string
			Notes string
		}
	}

	aTask := task{}
	aTask.Fields.Name = "Contact suppliers"
	aTask.Fields.Notes = "Get pricing on both the blue and green variants"

	client.CreateRecord("TABLE_NAME", &aTask)

	// aTask.AirtableID is now set to the newly created Airtable recordID
}

func (*Client) DestroyRecord

func (c *Client) DestroyRecord(tableName, recordID string) error

DestroyRecord deletes a record from an Airtable table by recordID

Example

package main

import (
	airtable "github.com/fabioberger/airtable-go"
)

func main() {
	client, _ := airtable.New("AIRTABLE_API_KEY", "BASE_ID")

	if err := client.DestroyRecord("TABLE_NAME", "RECORD_ID"); err != nil {
		panic(err)
	}
}

func (*Client) ListRecords

func (c *Client) ListRecords(tableName string, recordsHolder interface{}, listParams ...ListParameters) error

ListRecords returns a list of records from a given Airtable table. The caller can optionally pass in a ListParameters struct as the last argument. If passed, it will be url encoded and sent with the request. ListRecords will return all the records matching the supplied ListParameters, making multiple requests to Airtable if the number of matching records exceeds the 100 record limit for any one API request.

Example

package main

import (
	"fmt"

	airtable "github.com/fabioberger/airtable-go"
)

func main() {
	client, _ := airtable.New("AIRTABLE_API_KEY", "BASE_ID")

	type task struct {
		AirtableID string
		Fields     struct {
			Name  string
			Notes string
		}
	}

	tasks := []task{}
	if err := client.ListRecords("TABLE_NAME", &tasks); err != nil {
		panic(err)
	}

	fmt.Println(tasks)
}

func (*Client) RetrieveRecord

func (c *Client) RetrieveRecord(tableName string, recordID string, recordHolder interface{}) error

RetrieveRecord returns a single record from a given Airtable table.

Example

package main

import (
	"fmt"

	airtable "github.com/fabioberger/airtable-go"
)

func main() {
	client, _ := airtable.New("AIRTABLE_API_KEY", "BASE_ID")

	type task struct {
		AirtableID string
		Fields     struct {
			Name  string
			Notes string
		}
	}

	retrievedTask := task{}
	if err := client.RetrieveRecord("TABLE_NAME", "RECORD_ID", &retrievedTask); err != nil {
		panic(err)
	}

	fmt.Println(retrievedTask)
}

func (*Client) UpdateRecord

func (c *Client) UpdateRecord(tableName, recordID string, updatedFields map[string]interface{}, record interface{}) error

UpdateRecord updates an existing record in an Airtable table and updates the new field values in the `record` struct passed in.

Example

package main

import (
	"fmt"

	airtable "github.com/fabioberger/airtable-go"
)

func main() {
	client, _ := airtable.New("AIRTABLE_API_KEY", "BASE_ID")

	type task struct {
		AirtableID string
		Fields     struct {
			Name  string
			Notes string
		}
	}

	aTask := task{}
	aTask.Fields.Name = "Clean kitchen"
	aTask.Fields.Notes = "Make sure to clean all the counter tops"

	UpdatedFields := map[string]interface{}{
		"Name": "Clean entire kitchen",
	}
	if err := client.UpdateRecord("TABLE_NAME", "RECORD_ID", UpdatedFields, &aTask); err != nil {
		panic(err)
	}

	fmt.Println(aTask)
}

type Error

type Error struct {
	Type       string `json:"type"`
	Message    string `json:"message"`
	StatusCode int
}

Error represents an error returned by the Airtable API.

func (Error) Error

func (e Error) Error() string

type ListParameters

type ListParameters struct {
	Fields          []string
	FilterByFormula string
	MaxRecords      int
	Sort            []SortParameter
	View            string
}

ListParameters let's the caller describe the parameters he want's sent with a ListRecords request See the documentation at https://airtable.com/api for more information on how to use these parameters

Example

package main

import (
	"fmt"

	airtable "github.com/fabioberger/airtable-go"
)

func main() {
	client, _ := airtable.New("AIRTABLE_API_KEY", "BASE_ID")

	type task struct {
		AirtableID string
		Fields     struct {
			Name     string
			Notes    string
			Priority int
		}
	}

	listParams := airtable.ListParameters{
		Fields:          []string{"Name", "Notes", "Priority"},
		FilterByFormula: "{Priority} < 2",
		MaxRecords:      50,
		Sort: []airtable.SortParameter{
			airtable.SortParameter{
				Field:          "Priority",
				ShouldSortDesc: true,
			},
		},
		View: "Main View",
	}
	tasks := []task{}
	if err := client.ListRecords("TABLE_NAME", &tasks, listParams); err != nil {
		panic(err)
	}

	fmt.Println(tasks)
}

func (*ListParameters) URLEncode

func (l *ListParameters) URLEncode() string

URLEncode url encodes the ListParameters.

type SortParameter

type SortParameter struct {
	Field          string
	ShouldSortDesc bool
}

SortParameter is a sort object sent as part of the ListParameters that describes how the records should be sorted.