Airtable för utvecklare och DevOps - Planer, API, Webhooks och Go/Python-exempel

Airtable är bäst att tänka på som en lågkodningsplattform för applikationer, byggd runt en samarbetsbar “databasliknande” kalkylbladssnitt - utmärkt för snabbt att skapa operativa verktyg (inre spårare, lättviktiga CRM:er, innehållspipelines, AI-bedömningsköer) där icke-utvecklare behöver ett vänligt gränssnitt, men utvecklare också behöver en API-yta för automatisering och integration.

Airtable egen material beskriver Web API:t som RESTful, använder JSON, och standard HTTP-statuskoder.

De två begränsningarna som starkast formar ingenjörsbeslut är:

Fria planens hårdnivåer: 1 000 poster per bas, 1 000 API-anrop per arbetsområde per månad, 1 GB bifogningslagring per bas, och bara två veckors versions/snapshot-historik.
Dessa siffror är så låga att du bör betrakta “Fritt Airtable” som en prototyp, demo, hobbyprojekt eller mycket liten intern arbetsflöde, inte som en produktionsdatabas som kontinuerligt frågas av tjänster.

Offentliga Web API:s begränsningar: Airtable tillämpar 5 förfrågningar per sekund per bas och även 50 förfrågningar per sekund för all trafik som använder personliga åtkomsttoken från en viss användare eller tjänstekonto. Om du överskrider dessa, kommer du att få HTTP 429 och (enligt Airtable:s vägledning) måste vänta cirka 30 sekunder innan du försöker igen.
Konsekvensen är arkitektonisk: batch så mycket som möjligt, cachera läsningar, föredra webhooks framför polling för ändringssökning, och bygg omprovning/avsteg in i varje klient.

Om du vill ha Airtable i ett anpassat system, är en effektiv “DevOps + backend” produktionsmönster:

Airtable som den operativa UI:n + lättviktiga källan till sanningen för en begränsad dataset (routningsregler, mänskliga granskningsköer, redaktörsplaner, kundonboardingsteg).
Ett separat system (PostgreSQL/lagerobjektlagring) som den hållbara primära lagringen för skala, översyn, säkerhetskopior, analyser och högre QPS-läsningar/skrivningar.
En synkroniseringslager som hämtar sidor av poster (offset-pagination), pushar ändringar i batchar, och eventuellt använder Airtable Webhooks för att minska polling.

För det bredare perspektivet - objektlagring, PostgreSQL, Elasticsearch och AI-nativa datalager - se artikeln Data Infrastructure for AI Systems.

Vad är Airtable och varför använda det som en lågkodningsdatabas

Airtables huvudsakliga abstraktion är basen: en behållare för relaterade tabeller och arbetsflödesartefakter (vyer, gränssnitt, automatiseringar). I praktiken mappar en bas ofta till en affärsdomänsgräns - Content Ops, Incident Postmortems, LLM-bedömningar, Kundförfrågningar.

Inom en bas modellerar du data som:

Tabeller: analogi till entiteter/kollektioner.
Poster: rader.
Fält: kolumner med rika typer (val, bifogningar, länkar, formler, osv.).
Du skapar sedan flera “linsar” över samma tabell med vyer - filtrerade/sorterade/grupperade representationer optimerade för specifika uppgifter. Airtables dokumentation betonar att vyer hjälper dig att “se de poster som mest relevant för dig” och kan anpassas för olika användare.

Utvecklare väljer Airtable när de behöver:

En mänskligt vänlig UI för affärsanvändare att skapa/uppdatera operativ data snabbt (utan att vänta på en anpassad administratörsapp).
En programmerbar backend-yta via Airtable Web API för import, synkronisering och automatisering. API:t använder REST-semantik och JSON, vilket gör det enkelt att integrera från Go/Python-tjänster.
Glömma sammankoppling av SaaS/arbetsflöden via integreringar och automatiseringar, där vissa steg kan implementeras helt i Airtable och andra hanteras i kod. Airtable-automatiseringar beskrivs som utlösare-åtgärdsarbetsflöden (t.ex. “när post skapas → skicka meddelande / uppdatera post / kör skript”).

Airtable är särskilt produktiv för DevOps + AI-team när den används som:

En ändringskontrollerad konfigurationslista: t.ex. funktionsspel metadata, tjänstesektion, eskaleringssystem, distributionsskapande.
En mänsklig granskningskö: t.ex. LLM-utdata som väntar på validering, säkerhetsgranskning, promptitereringsuppgifter.
En metadataindex för tillgångar som finns någon annan: S3-URI:er, Git-kommit SHA:er, dataset-ID:er - minimerar bifogningslagringspress på Airtable själv (viktigt på Free).

Airtable kärnfunktioner: baser, tabeller, fält, vyer, gränssnitt, tillägg, automatiseringar och integreringar

Airtables “kraft” är inte bara tabeller; det är den omgivande arbetsflödesyta som gör att en bas beter sig som en lättviktig appplattform.

Baser och tabeller för strukturerad samarbete

En bas är där teamen äger strukturerad data och processstatus. Den praktiska ingenjörsimplikationen är schema styrning: om affärsanvändare kan omge fält eller tabeller, kan dina API-klienter krascha om du inte designar för förändring.

Två taktiker minskar skador:

Använd stabila ID:er i kod där möjligt. Airtable noterar explicit att tabellnamn och tabell-ID:er kan användas utbytt, och rekommenderar tabell-ID:er så att du inte behöver ändra förfrågningar när namn ändras.
Dokumentera “API-kopplade fält” i fältdeskrivningar och behandla förändringar som kontrollerade händelser (PR-granskning / förändringsförfrågan).

Vyer och arbetsflödes “linsar”

Vyer låter dig filtrera/sortera/gruppera poster för specifika processer (triagevy, “behöver granskning”, “klar att skicka”). Airtable betonar vyer som mekanismen för att visa endast de “viktigaste” delmängderna av poster för olika användare.
Från en integreringssynpunkt kan du designa en vy som en stabil kontrakt: din synkroniseringsjobb läser endast poster i “Export”-vyen, till exempel, istället för att försöka replikera all filtreringslogik i kod. (API:t stöder också att välja poster via vy och via formelfilter; se API-avsnittet nedan.)

Tillägg, appmarknad och “använd dina egna verktyg”

Airtable stöder “Tillägg” (tidigare “Blocks”), som lägger till funktioner inuti basen (diagram, skript, importer, osv.). Airtables egen översikt beskriver tillägg som tillägg byggda av Airtable och tredjepart.
Viktigt: Tillägg stöds inte på den fria planen, så något arbetsflöde som beroende på dem börjar på Team eller högre.

Automatiseringar: utlösare, åtgärder och skript för integreringslänk

Automatiseringar är utlösare-åtgärdsarbetsflöden: Airtable listar utlösare inklusive “när en post skapas/uppdateras”, “när en post kommer in i en vy”, schemalagda tidsutlösare och “när en webhook tas emot”, bland annat.
Åtgärder inkluderar skapa/uppdatera poster, skicka meddelanden, och (viktigt för utvecklare) kör kod: åtgärden “Kör ett skript” kör skript “i bakgrunden av basen” och positioneras som rätt val för skript som du vill köras automatiskt.

Emellertid är “Kör ett skript” explicit markerat som ogiltigt på den fria planen, vilket är viktigt om din arkitekturantagelse är “använd Airtable-automatiseringar för att anropa våra inre API:er”.

Web API och integreringar som ingenjörsgränssnitt

Airtables Web API möjliggör externa system att läsa/skriva poster med standard HTTP-anrop. Airtable-dokumentationen ger konkreta URL-mönster som:

https://api.airtable.com/v0/{your_app_id}/Flavors?filterByFormula=Rating%3D5 (exempel på formelfiltrering).

Airtable tillhandahåller också en metadata-lager (nyttigt för DevOps “konfiguration som kod” mönster), inklusive att lista baser via GET https://api.airtable.com/v0/meta/bases och skapa en bas via POST https://api.airtable.com/v0/meta/bases (kräver schema-scope).

Authentiseringssynpunkt, har Airtable flyttat bort från åldriga API-nycklar: dess officiella nedläggningsplan inkluderar API-nyckeln nedläggning effektiv från 1 februari 2024.

Airtable prisplaner och de fria planens begränsningar för utvecklare

Airtables plannamn och rättigheter ändras över tid, men Airtables nuvarande planer dokumentation tillhandahåller explicita, ingenjörsrelevant kvoter och begränsningar.

Airtable planstabell: viktiga begränsningar som påverkar API-integreringar

Team och Business planpriser i Airtables planer dokumentation anges per samarbetsmedlem (månatlig vs årlig fakturering).

Fria planens djupdykning: begränsningar och praktiska konsekvenser för DevOps och backend-system

På Free får du:

1 000 poster per bas.
Detta är den första “arkitekturstyrkans funktion”: en gång du överskrider cirka 1 000 poster för en domän, måste du antingen skiva upp i flera baser (vilket komplikerar integreringar), arkivera aggressivt, eller flytta primära dataset till någon annan plats (Postgres/lager) och hålla endast “aktiva” operativa delar i Airtable.

1 000 API-anrop per arbetsområde per månad.
Detta är så lågt att naiva synkroniseringsstrategier (polla varje minut) kommer att bränna kvot snabbt. Airtables API-anropsgrenar dokumentation beskriver explicit API:t som RESTful och påpekar att list-postoperationer returnerar sidor upp till 100; om du pollar upprepade gånger, kan du snabbt uttömma månatliga anrop.
En Free-planintegration bör därför standardförsäkra: händelsedrivna uppdateringar via webhooks (när det är möjligt),
eller användardrivna/mannualsynkronisering,
eller en mycket lågfrekvent batchjobb (dagligen),
plus cachelagring för att undvika upprepade läsningar. Airtable rekommenderar explicit cachelagring/proxy-strategier som sätt att hantera hastighetsbegränsningar.

1 GB bifogningslagring per bas.
För AI/LLM-arbetsflöden är detta en fälla om du lagrar PDF:er, bilder eller dataset som bifogningar. Föredra att lagra bifogningar i objektlagring och hålla endast URL:er och metadata i Airtable.

2 veckor av versions/snapshot-historik.
Från en DevOps riskperspektiv minskar begränsad historik din förmåga att återställa från olyckliga massändringar. Om Airtable är operativt kritisk, bör du implementera externa säkerhetskopior/snapshot (API-exportjobb) istället för att endast förlita dig på versionshistorik.

Free har också samarbetsgräns och funktioner borttagningar som påverkar leverans:

Ogränsade läsbara samarbetsmedlemmar, men endast 5 samarbetsmedlemmar med Redaktör/Skapare behörighet och 50 kommentatorer.
Inga tillägg på Free.
Vissa automatiseringsfunktioner är begränsade: åtgärden “Kör ett skript” är markerad som ogiltig på Free.

Airtable alternativ och konkurrenter: Notion vs Google Sheets vs Coda vs ClickUp vs PostgreSQL + UI

Airtable är inte det förutsatta svaret för varje “tabeller + arbetsflöde” användningsscenariot. Det rätta valet beror på om din primära behov är:

en databasliknande operativ lagring med UI (Airtable / Coda),
en dokumentförst arbetsplats med databaser inbäddade (Notion),
ren kalkylbladssamverkan (Google Sheets),
uppgiftsprojektledning (ClickUp),
eller en sann backend-databas med ett syftar till admin-gränssnitt (PostgreSQL + Retool/Appsmith/etc.).

Konkurrentjämförelsetabell: ingenjörsavvägningar (API, UI, skala)

En användbar regel: om du förväntar dig högfrekventa läsningar/skrivningar, komplexa frågebehov eller strikt ändringskontroll, vill du typiskt “Postgres-först”. Om du förväntar dig tyngd redigering utanför utvecklare och snabb arbetsflödesiteration, är Airtable lockande - särskilt för inre verktyg - så länge du designar runt API och plangränser.

Airtable DevOps-mönster och slutna API-integreringar med Go och Python

Detta avsnitt ger en komplett, produktionsinriktad väg från konfiguration → säker auth → CRUD-klienter → paginering → hastighetsbegränsningshantering → batchning → webhooks → distributionsnoteringar.

SEO-integrationsdiagram: Airtable API-arkitektur för DevOps-vänliga system

Konfiguration och autentisering: stabila ID:er, token och minsta behörighet

Föredra tabell-ID:er i kod för att minska brytande förändringar

Airtable noterar att tabellnamn och tabell-ID:er kan användas utbytt och rekommenderar tabell-ID:er för att undvika förfrågningssändringar när namn ändras.
I praktiken är detta en av de högsta leverans “Ops-hygien” beslut du kan göra för en Airtable-baserad integration.

För att hitta ID:er, tillhandahåller Airtable vägledning för att hitta bas- och tabell-ID:er från URL:er (och via API-dokumentation).

Använd Personliga åtkomsttoken (PATs), inte åldriga API-nycklar

Airtables officiella nedläggningslista inkluderar “1 februari 2024 - API-nyckeln nedläggs.”
PATs beskrivs av Airtable som att tillåta dig att skapa flera token med olika omfång - från smala (enkel omfång + en enda bas) till breda (alla arbetsområden/baser/omfång som tillåts av användaren).

Den operativa bästa praxis är: skapa flera PATs per integrationsyta (t.ex. en token för läsningssynkronisering, en annan för skrivvägar) och rotera dem som någon annan hemlighet.

För enterprise-stil resiliens (integreringen ska inte dö när en anställd lämnar), beskriver Airtable servicekonton som är designade för API-integreringar, oberoende av någon specifik användare.

Minimala miljövariabler för både Go- och Python-exemplen

# Krävs
export AIRTABLE_TOKEN="pat_xxx..."          # Personlig åtkomsttoken
export AIRTABLE_BASE_ID="appXXXXXXXXXXXXXX" # Bas-ID
export AIRTABLE_TABLE="tblYYYYYYYYYYYYYY"   # Föredra tabell-ID; tabellnamn fungerar också

# Valfritt (filtrering/beteende)
export AIRTABLE_PAGE_SIZE="100"             # 100 är max för listrecords
export AIRTABLE_TIMEOUT_SECONDS="30"

API-fundament som formar klientdesign: paginering, hastighetsbegränsningar, batchning

Paginering: listrecords returnerar upp till 100 poster per förfrågan

Airtable dokumenterar att “listrecords”-svar är paged upp till 100 poster i taget; om tabellen har mer än 100, måste du göra flera förfrågningar och använda den returnerade offset som nästa förfrågans frågeparameter.
Parametern pageSize kan minska sidstorleken, men 100 är max.

Filtrering och sortering: filterByFormula och sort-frågeparametrar

Airtable tillhandahåller konkreta exempel på användning av filterByFormula och sort[...]-parametrar, inklusive en kanonisk URL-form som:

https://api.airtable.com/v0/{your_app_id}/Flavors?filterByFormula=Rating%3D5

Hastighetsbegränsningar och återförsöksstrategi: behandla 429 som normal

Airtables API-anropsgrenar dokumentation säger:

5 förfrågningar per sekund per bas,
50 förfrågningar per sekund per användare/tjänstekonto med PAT-trafik,
och om du överskrider får du en 429 och måste vänta 30 sekunder innan efterföljande förfrågningar lyckas.

Airtables felsökningsguide stärker att 429 kan betyda att du har överskridit den 5 req/base/sekund hastighetsbegränsningen och råder att vänta innan du försöker igen.

Batchning: designa runt “up to 10 poster per förfrågan”

Airtable dokumenterar explicit batchning som en hastighetsbegränsningsstrategi: API:t “stöder batchning”, hanterar “up to 10 poster per förfrågan.”
Och Airtables “Uppdatera flera poster”-slutpunkt demonstrerar batchförfråganformen (records: [...]) och stöder också performUpsert med fieldsToMergeOn.

SEO-sekvensdiagram: Airtable API-anropsserie för list → paginera → batchuppdatera → webhook-payloadhämtning

Go-exempel: produktionsklar Airtable REST-klient med paginering, återförsök och batchning

Detta Go-program demonstrerar:

PAT-autentisering via Authorization: Bearer ... (Bearer-autentisering krävs).
Listrecords-paginering med offset och pageSize (100 max).
Hastighetsbegränsningshantering för 429 med Retry-After-fallback och Airtables “vänta 30 sekunder” vägledning.
Batchuppdatering med den officiella PATCH https://api.airtable.com/v0/{baseId}/{tableIdOrName} formen.
Enkel-postuppdateringslutpunktform (PATCH/PUT-semantik).
Filtreringsexempel (filterByFormula) URL-mönster.

Körkrav: Go 1.21+ rekommenderas; sätt AIRTABLE_TOKEN, AIRTABLE_BASE_ID, AIRTABLE_TABLE.

// Fil: main.go
package main

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"strconv"
	"time"
)

type AirtableClient struct {
	BaseID     string
	Token      string
	HTTPClient *http.Client
}

type airtableError struct {
	Error interface{} `json:"error"`
}

type Record struct {
	ID          string                 `json:"id"`
	CreatedTime string                 `json:"createdTime,omitempty"`
	Fields      map[string]interface{} `json:"fields"`
}

type listRecordsResponse struct {
	Records []Record `json:"records"`
	Offset  string   `json:"offset,omitempty"`
}

func mustEnv(key string) string {
	v := os.Getenv(key)
	if v == "" {
		fmt.Fprintf(os.Stderr, "missing env var: %s\n", key)
		os.Exit(2)
	}
	return v
}

func (c *AirtableClient) doJSON(ctx context.Context, method, rawURL string, body any, out any) (*http.Response, error) {
	var reqBody io.Reader
	if body != nil {
		b, err := json.Marshal(body)
		if err != nil {
			return nil, fmt.Errorf("marshal body: %w", err)
		}
		reqBody = bytes.NewReader(b)
	}

	req, err := http.NewRequestWithContext(ctx, method, rawURL, reqBody)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+c.Token) // Bearer required
	req.Header.Set("Content-Type", "application/json")

	// Basic retry loop that treats 429 as normal. Airtable guidance: wait ~30s.
	var lastResp *http.Response
	for attempt := 0; attempt < 6; attempt++ {
		resp, err := c.HTTPClient.Do(req)
		if err != nil {
			return nil, err
		}
		lastResp = resp

		if resp.StatusCode != http.StatusTooManyRequests {
			if out == nil {
				return resp, nil
			}
			defer resp.Body.Close()
			if resp.StatusCode < 200 || resp.StatusCode >= 300 {
				b, _ := io.ReadAll(resp.Body)
				return resp, fmt.Errorf("http %d: %s", resp.StatusCode, string(b))
			}
			if err := json.NewDecoder(resp.Body).Decode(out); err != nil {
				return resp, fmt.Errorf("decode response: %w", err)
			}
			return resp, nil
		}

		// 429 handling
		resp.Body.Close()
		wait := 30 * time.Second // Airtable says wait 30 seconds before subsequent requests succeed
		if ra := resp.Header.Get("Retry-After"); ra != "" {
			if secs, err := strconv.Atoi(ra); err == nil && secs > 0 {
				wait = time.Duration(secs) * time.Second
			}
		}
		time.Sleep(wait)

		// Rewind body for retry if needed (only safe because we used bytes.NewReader).
		if reqBody != nil {
			if seeker, ok := reqBody.(io.Seeker); ok {
				_, _ = seeker.Seek(0, io.SeekStart)
			}
		}
	}
	return lastResp, errors.New("too many retries after 429")
}

// ListRecords paginates with offset; pageSize max 100
func (c *AirtableClient) ListRecords(ctx context.Context, table string, pageSize int, filterByFormula string) ([]Record, error) {
	if pageSize <= 0 || pageSize > 100 {
		pageSize = 100
	}

	var out []Record
	var offset string

	for {
		u := url.URL{
			Scheme: "https",
			Host:   "api.airtable.com",
			Path:   fmt.Sprintf("/v0/%s/%s", c.BaseID, table),
		}
		q := u.Query()
		q.Set("pageSize", strconv.Itoa(pageSize))
		if offset != "" {
			q.Set("offset", offset)
		}
		if filterByFormula != "" {
			// Example pattern in Airtable docs
			q.Set("filterByFormula", filterByFormula)
		}
		u.RawQuery = q.Encode()

		var page listRecordsResponse
		_, err := c.doJSON(ctx, http.MethodGet, u.String(), nil, &page)
		if err != nil {
			return nil, err
		}
		out = append(out, page.Records...)
		if page.Offset == "" {
			return out, nil
		}
		offset = page.Offset
	}
}

// UpdateMultiple demonstrates the official batch PATCH shape.
func (c *AirtableClient) UpdateMultiple(ctx context.Context, table string, records []Record) ([]Record, error) {
	type reqBody struct {
		Records []Record `json:"records"`
	}

	u := fmt.Sprintf("https://api.airtable.com/v0/%s/%s", c.BaseID, table)
	var resp struct {
		Records []Record `json:"records"`
	}
	_, err := c.doJSON(ctx, http.MethodPatch, u, reqBody{Records: records}, &resp)
	if err != nil {
		return nil, err
	}
	return resp.Records, nil
}

// UpsertMultiple uses performUpsert (fieldsToMergeOn) on the batch update endpoint.
func (c *AirtableClient) UpsertMultiple(ctx context.Context, table string, mergeOn []string, records []Record) error {
	body := map[string]any{
		"performUpsert": map[string]any{
			"fieldsToMergeOn": mergeOn,
		},
		"records": records,
	}
	u := fmt.Sprintf("https://api.airtable.com/v0/%s/%s", c.BaseID, table)
	_, err := c.doJSON(ctx, http.MethodPatch, u, body, nil)
	return err
}

// UpdateRecord demonstrates single-record PATCH/PUT endpoint semantics.
func (c *AirtableClient) UpdateRecord(ctx context.Context, table, recordID string, fields map[string]any) (Record, error) {
	u := fmt.Sprintf("https://api.airtable.com/v0/%s/%s/%s", c.BaseID, table, recordID)
	body := map[string]any{"fields": fields}
	var resp Record
	_, err := c.doJSON(ctx, http.MethodPatch, u, body, &resp)
	return resp, err
}

func chunk[T any](items []T, n int) [][]T {
	if n <= 0 {
		return [][]T{items}
	}
	var out [][]T
	for i := 0; i < len(items); i += n {
		j := i + n
		if j > len(items) {
			j = len(items)
		}
		out = append(out, items[i:j])
	}
	return out
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()

	token := mustEnv("AIRTABLE_TOKEN")
	baseID := mustEnv("AIRTABLE_BASE_ID")
	table := mustEnv("AIRTABLE_TABLE")

	c := &AirtableClient{
		BaseID: baseID,
		Token:  token,
		HTTPClient: &http.Client{
			Timeout: 30 * time.Second,
		},
	}

	// Example: list all records filtered by formula (adapt formula to your schema).
	records, err := c.ListRecords(ctx, table, 100, "")
	if err != nil {
		panic(err)
	}
	fmt.Printf("listed %d records\n", len(records))

	// Example: batch update in chunks (Airtable supports batching as a strategy, up to 10 records per request).
	// Here we update at most 10 at a time.
	var updates []Record
	for i := 0; i < len(records) && i < 3; i++ {
		updates = append(updates, Record{
			ID: records[i].ID,
			Fields: map[string]any{
				"Visited": true,
			},
		})
	}
	for _, part := range chunk(updates, 10) {
		updated, err := c.UpdateMultiple(ctx, table, part)
		if err != nil {
			panic(err)
		}
		fmt.Printf("updated %d records\n", len(updated))
	}
}

Python-exempel: Airtable-integrering med requests och en webhook-mottagare

Detta Python-implementering inkluderar:

Direkta REST-anrop med Bearer-autentisering.
Paginering med offset och pageSize (100 max).
429-hantering enligt Airtable:s vägledning (vänta ~30 sekunder).
Batchuppdatering med den officiella uppdatera-flera-poster-slutpunktenformen och performUpsert.
Webhook-mottagarebeteende som bekräftar: webhook-pingar innehåller inte ändringspayload, så du måste hämta payloads separat, och payloads behålls för 7 dagar; webhooks kan upphöra efter 7 dagar om inte uppdaterade.

Notera: Airtable:s “Lista webhook-payloads”-slutpunkt detaljer refereras i Airtable:s webhooksguide, men den mest pålitligt indexade publika texten är guiden själv och gemenskapsexempel. Guidens beteendekonstrainer (ingen payload i ping, behållning, förfall) är de kritiska operativa fakta.

# Fil: airtable_client.py
import os
import time
import json
import typing as t
import requests
from urllib.parse import urlencode

AIRTABLE_TOKEN = os.environ["AIRTABLE_TOKEN"]
AIRTABLE_BASE_ID = os.environ["AIRTABLE_BASE_ID"]
AIRTABLE_TABLE = os.environ["AIRTABLE_TABLE"]

SESSION = requests.Session()
SESSION.headers.update({
    "Authorization": f"Bearer {AIRTABLE_TOKEN}",  # Bearer auth required
    "Content-Type": "application/json",
})

def _airtable_request(method: str, url: str, *, params=None, json_body=None, max_retries: int = 5) -> requests.Response:
    for attempt in range(max_retries + 1):
        resp = SESSION.request(method, url, params=params, json=json_body, timeout=30)
        if resp.status_code != 429:
            return resp

        # Airtable guidance: wait ~30s after 429
        retry_after = resp.headers.get("Retry-After")
        wait = 30
        if retry_after and retry_after.isdigit():
            wait = int(retry_after)
        time.sleep(wait)

    raise RuntimeError(f"Too many retries after 429 for {method} {url}")

def list_records(page_size: int = 100, filter_by_formula: str | None = None) -> list[dict]:
    # pageSize max is 100
    page_size = min(max(page_size, 1), 100)
    base_url = f"https://api.airtable.com/v0/{AIRTABLE_BASE_ID}/{AIRTABLE_TABLE}"

    all_records: list[dict] = []
    offset: str | None = None

    while True:
        params = {"pageSize": page_size}
        if offset:
            params["offset"] = offset
        if filter_by_formula:
            # Example pattern documented by Airtable
            params["filterByFormula"] = filter_by_formula

        resp = _airtable_request("GET", base_url, params=params)
        resp.raise_for_status()
        data = resp.json()
        all_records.extend(data.get("records", []))
        offset = data.get("offset")
        if not offset:
            break

    return all_records

def update_multiple_records(records: list[dict], perform_upsert_fields: list[str] | None = None) -> dict:
    """
    Uses PATCH https://api.airtable.com/v0/{baseId}/{tableIdOrName}
    with body { "records": [ { "id": "...", "fields": {...} }, ... ] }
    and optional performUpsert, per Airtable docs.
    """
    url = f"https://api.airtable.com/v0/{AIRTABLE_BASE_ID}/{AIRTABLE_TABLE}"
    body: dict[str, t.Any] = {"records": records}
    if perform_upsert_fields:
        body["performUpsert"] = {"fieldsToMergeOn": perform_upsert_fields}

    resp = _airtable_request("PATCH", url, json_body=body)
    resp.raise_for_status()
    return resp.json()

def webhook_receiver_example():
    """
    Minimal pattern; in production, use Flask/FastAPI and validate signatures.
    Airtable webhooks guide notes:
      - Notification ping DOES NOT include the change payload
      - Payload must be fetched from the GET payloads endpoint
      - Payloads retained 7 days
      - Webhooks created via PAT/OAuth expire after 7 days unless refreshed/listed
    """
    pass

if __name__ == "__main__":
    rows = list_records(page_size=100)
    print(f"Fetched {len(rows)} records")
    # Example: update first 2 records (chunk in 10s; Airtable supports batching up to 10 records/request as a strategy).
    updates = []
    for r in rows[:2]:
        updates.append({"id": r["id"], "fields": {"Visited": True}})
    if updates:
        result = update_multiple_records(updates)
        print(json.dumps(result, indent=2))

Webhook-mottagare: cursor-persistering och “ingen payload i ping”

För en produktionswebhook-mottagare är dina huvudsakliga uppgifter:

Returnera en snabb framgångsrik svar (t.ex. HTTP 204).
Persistera webhook-cursorn så att du inte återprocesserar gamla payloads.
Hämta payloads efter pings; webhooks-guiden varnar att pingordningen inte är garanterad, men payloadlistor har stabil ordning.
Förstå behållning och förfall: payloads behålls 7 dagar; webhooks skapade med PAT/OAuth förfallar efter 7 dagar om inte uppdaterade (att lista payloads kan förlänga livslängd).
Designa din synkroniseringsarbetare så att den inte missar händelser om en ping förloras: “hämta payloads via cursor”-metoden är din hållbara mekanism.

Om du inte vill hantera Webhooks API-komplexiteten, föreslår Airtable självt att vissa användningsscenarier kan vara “mer enkla” med en Automatisering med “Kör ett skript” för att göra en POST-förfrågan till din slutpunkt.

Distributionnoteringar: CI/CD, infrastruktur som kod, säkerhet och säkerhetskopior

CI/CD och versions säkerhet

Behandla Airtable-integreringar som någon annan produktionsberoende:

Testa din mappningslager (Airtable-fält ↔ domännmodell).
Lägg till kontraktstester mot en dedikerad “sandbox bas” så att schemaändringar upptäcks tidigt.
Övervaka 429:or och latens; 429 är normal under burstbelastningar eftersom Airtable tillämpar 5 req/sec/base.

Infrastruktur som kod: distribuera integrationen, inte kalkylbladet

Airtable själv är SaaS, men din integrationstjänst kan distribueras med Terraform (AWS Lambda + API Gateway webhook-mottagare, GCP Cloud Run, Kubernetes, osv.). IaC-fokus är vanligtvis:

Nätverk för inkommande webhook-mottagare
Hemlighetsdistribution (PAT i en hemlighetshanterare; injiceras vid körning)
Planerade jobb (cron) för periodiska synkroniseringsjobb
Övervakning (loggar/mått)

Säkerhet: håll token på serversidan, använd minsta behörighet, rotera

Airtable Enterprise API-dokumentation varnar att förfrågningar som exponerar token inte bör göras klientsidan eftersom token skulle exponeras; den säkra normen är serversida förfrågningar.
Airtable:s officiella JS-klient README också varnar om att sätta API-nycklar på webbsidor och föreslår att använda separata konton/delad åtkomst om du måste.
Kombinera detta med PAT-scope (endast nödvändiga åtgärder + endast nödvändiga baser) och du får en praktisk minsta behörighetspostur.

Säkerhetskopior och katastrofåterställning: förlita dig inte på kort versionshistorik

Free-plan versionshistorik är två veckor, Team/Business är ett år.
Om Airtable är affärskritisk, implementera:

API-baserade exportssnapshot till objektlagring (dagligen)
Replikering till en hållbar databas (Postgres/lager)
Cursorbaserad webhook-ingrepp där tillämpligt, förstå att payloadbehållning är 7 dagar.

URL-längd och filtreringskomplexitet: planera för POST-fallback

Airtable tillämpar en 16 000-karaktärslängd gräns för Web API-förfrågningar och rekommenderar omgångar; särskilt säger den att det finns en POST-version av GET-listtabellposter-slutpunkten för att sätta alternativ i förfrågningens kropp istället för frågeparametrar.
Detta är viktigt om din DevOps-pipeline bygger komplexa filterByFormula-uttryck eller långa sorts/fältlistor.

Genom att designa runt Free-planens tak, standardhastighetsbegränsningar och cursorbaserad ändringskapning, kan Airtable vara en mycket effektiv “ops UI + integrationsyta” för DevOps- och AI-fokuserade team - särskilt när parat med en hållbar lagring för skala och översyn.