Documentation ¶
Overview ¶
Package airtable provides a high-level client to the Airtable API that allows the consumer to drop to a low-level request client when needed.
Example ¶
package main import ( "fmt" "strings" "time" "github.com/brianloveswords/airtable" ) type PublicDomainBookRecord struct { airtable.Record // provides ID, CreatedTime Fields struct { Title string `json:"Book Title"` Author string Publication time.Time `json:"Publication Date"` FullText string Rating int Tags airtable.MultiSelect } } // String shows the book record like "<title> by <author> [<rating>]" func (r *PublicDomainBookRecord) String() string { f := r.Fields return fmt.Sprintf("%s by %s %s", f.Title, f.Author, r.Rating()) } // Rating outputs a rating like [***··] func (r *PublicDomainBookRecord) Rating() string { var ( max = 5 rating = r.Fields.Rating stars = strings.Repeat("*", rating) dots = strings.Repeat("·", max-rating) ) return fmt.Sprintf("[%s%s]", stars, dots) } func main() { // Create the Airtable client with your APIKey and BaseID for the // base you want to interact with. client := airtable.Client{ APIKey: "keyXXXXXXXXXXXXXX", BaseID: "appwNa5g4gHCVZQPm", } books := client.Table("Public Domain Books") bestBooks := []PublicDomainBookRecord{} books.List(&bestBooks, &airtable.Options{ // The whole response would be huge because of FullText so we // should just get the title and author. NOTE: even though the // field is called "Book Title" in the JSON, we should use field // by the name we defined it in our struct. Fields: []string{"Title", "Author", "Rating"}, // Only get books with a rating that's 4 or higher. Filter: `{Rating} >= 4`, // Let's sort from highest to lowest rating, then by author Sort: airtable.Sort{ {"Rating", airtable.SortDesc}, {"Author", airtable.SortAsc}, }, }) fmt.Println("Best Public Domain Books:") for _, bookRecord := range bestBooks { fmt.Println(bookRecord.String()) } // Let's prune our library of books we aren't super into. badBooks := []PublicDomainBookRecord{} books.List(&badBooks, &airtable.Options{ Fields: []string{"Title", "Author", "Rating"}, Filter: `{Rating} < 3`, }) for _, badBook := range badBooks { fmt.Println("deleting", badBook) books.Delete(&badBook) } }
Output:
Index ¶
- Constants
- Variables
- func NewRecord(recordPtr interface{}, data Fields)
- func RateLimiter(n int) ratelimit.Limiter
- type Attachment
- type AttachmentThumbnail
- type Client
- type ErrClientRequest
- type Fields
- type FormulaResult
- type MultiSelect
- type Options
- type QueryEncoder
- type Record
- type RecordLink
- type Sort
- type SortType
- type Table
Examples ¶
Constants ¶
const ( SortDesc = "desc" SortAsc = "asc" )
SortDesc and SortAsc are used in the Sort type to indicate the direction of the sort.
Variables ¶
var ( DefaultRootURL = "https://api.airtable.com" DefaultVersion = "v0" DefaultHTTPClient = http.DefaultClient DefaultLimiter = RateLimiter(5) // per second )
Functions ¶
func NewRecord ¶
func NewRecord(recordPtr interface{}, data Fields)
NewRecord is a convenience method for applying a map of fields to a record container when the Fields struct is anonymous.
Example ¶
package main import ( "fmt" "github.com/brianloveswords/airtable" ) func main() { type BookRecord struct { airtable.Record Fields struct { Title string Author string Rating int Tags airtable.MultiSelect } } binti := &BookRecord{} airtable.NewRecord(binti, airtable.Fields{ "Title": "Binti", "Author": "Nnedi Okorafor", "Rating": 4, "Tags": airtable.MultiSelect{"sci-fi", "fantasy"}, }) fmt.Println(binti.Fields.Author) }
Output: Nnedi Okorafor
Example (WithoutNewRecord) ¶
package main import ( "fmt" "github.com/brianloveswords/airtable" ) func main() { // You can avoid using NewRecord if you use a named struct instead // of an anonymous struct for the Fields field in record struct. type Book struct { Title string Author string Rating int Tags airtable.MultiSelect } type BookRecord struct { airtable.Record Fields Book } binti := &BookRecord{ Fields: Book{ Title: "Binti", Author: "Nnedi Okorafor", Rating: 4, Tags: airtable.MultiSelect{"sci-fi", "fantasy"}, }, } fmt.Println(binti.Fields.Author) }
Output: Nnedi Okorafor
func RateLimiter ¶
RateLimiter makes a new rate limiter using n as the number of requests per second that is allowed. If 0 is passed, the limiter will be unlimited.
Types ¶
type Attachment ¶
type Attachment []struct { ID string URL string `json:"url"` Filename string `json:"filename"` Size float64 Type string Thumbnails struct { Small AttachmentThumbnail Large AttachmentThumbnail } }
Attachment type. When creating a new attachment, only URL and optionally Filename should be provided.
type AttachmentThumbnail ¶
AttachmentThumbnail holds the details of an individual thumbnail
type Client ¶
type Client struct { APIKey string BaseID string Version string RootURL string HTTPClient *http.Client Limiter ratelimit.Limiter }
Client represents an interface to communicate with the Airtable API.
- APIKey: api key to use for each request. Requests will panic if this is not set.
- BaseID: base this client will operate against. Requests will panic if this not set.
- Version: version of the API to use.
- RootURL: root URL to use.
- HTTPClient: http.Client instance to use. http.DefaultClient
- Limit: max requests to make per second.
func (*Client) Request ¶
Request makes an HTTP request to the Airtable API without a body. See RequestWithBody for documentation.
func (*Client) RequestWithBody ¶
func (c *Client) RequestWithBody( method string, endpoint string, options QueryEncoder, body io.Reader, ) ([]byte, error)
RequestWithBody makes an HTTP request to the Airtable API. endpoint will be combined with the client's RootlURL, Version and BaseID, to create the complete URL. endpoint is expected to already be encoded; if necessary, use url.PathEscape before passing RequestWithBody.
If client is missing APIKey or BaseID, this method will panic.
type ErrClientRequest ¶
ErrClientRequest is returned when the client runs into problems making a request.
func (ErrClientRequest) Error ¶
func (e ErrClientRequest) Error() string
type Fields ¶
type Fields map[string]interface{}
Fields is used in NewRecord for constructing new records.
type FormulaResult ¶
FormulaResult can be a string, number or error.
func (*FormulaResult) UnmarshalJSON ¶
func (f *FormulaResult) UnmarshalJSON(b []byte) error
UnmarshalJSON tries to figure out if this is an error, a string or a number.
func (*FormulaResult) Value ¶
func (f *FormulaResult) Value() (v interface{}, ok bool)
Value returns the underlying value if the formula results is a string or a number, otherwise return nil pointer and false
type Options ¶
type Options struct { // Sort the response. See the package example for usage usage Sort Sort // Which fields to include. Useful when you want to exclude certain // fields if you aren't using them to save on network cost. Fields []string // Maximum amount of record to return. If MaxRecords <= 100, it is // guaranteed the results will fit in one network request. MaxRecords uint // Formula used to filer the results. See the airtable formula // reference for more details on how to create a formula: // https://support.airtable.com/hc/en-us/articles/203255215-Formula-Field-Reference Filter string // Name of the view to use. If set, only the records in that view // will be returned. The records will be sorted and filtered // according to the order of the view. View string // Airtable API performs automatic data conversion from string // values if typecast parameter is passed in. Automatic conversion // is disabled by default to ensure data integrity, but it may be // helpful for integrating with 3rd party data sources. Typecast bool // contains filtered or unexported fields }
Options is used in the Table.List method to adjust and control the response
type QueryEncoder ¶
type QueryEncoder interface {
Encode() string
}
QueryEncoder encodes options to a query string.
type Record ¶
Record is a convenience struct for anonymous inclusion in user-constructed record structs.
type Table ¶
type Table struct {
// contains filtered or unexported fields
}
Table represents an table in a base and provides methods for interacting with records in the table.
func (*Table) Create ¶
Create makes a new record in the table using the record pointed to by recordPtr. On success, updates the ID and CreatedTime of the object pointed to by recordPtr.
recordPtr MUST have a Fields field that is a struct that can be marshaled to JSON or this method will panic.
func (*Table) Delete ¶
Delete removes a record from the table. On success, ID and CreatedTime of the object pointed to by recordPtr are removed.
func (*Table) Get ¶
Get looks up a record from the table by ID and stores in in the object pointed to by recordPtr.
func (*Table) List ¶
List queries the table for list of records and stores it in the object pointed to by listPtr. By default, List will recurse to get all of the records until there are no more left to get, but this can be overriden by using the MaxRecords option. See Options for a complete list of the options that are supported.
listPtr must be a pointer to a slice of records, which are structs that contain, at a minimum, `ID string` and `Fields struct {...}` fields. For example:
type BookRecord struct { airtable.Record // provides ID and CreatedTime Fields struct { Title string Author string } } listPtr := &[]BookRecord{}
This will be validated and cause a panic at runtime if listPtr is the wrong type.