DOCSEARCHbyAlgolia
Submit Docs

airtable.js

repository·master·Indexed 24 days ago

https://github.com/airtable/airtable.js

The official Airtable JavaScript library for interacting with the Airtable RESTful API. It allows developers to access and manipulate data in Airtable bases using table and column names. The library supports Node.js (10+) and browser environments, providing a Promise-based API for querying records, updating fields, and managing base data.

Tokens
3.6K
Snippets
6
Records
28
Agent score
74%

What's inside airtable.js

  1. Use Promises with Airtable.js methods

    master

    Since version 0.5.0, all methods that previously accepted a done callback will return a Promise if no callback is provided. This allows you to use .then() or async/await syntax.

    Callback style:

    table.select().firstPage(result => { ... })

    Promise style:

    table.select().firstPage().then(result => { ... })

  3. Use Airtable.js in the browser

    master

    To use Airtable.js in a browser environment, use the pre-built file located at build/airtable.browser.js.

    Security Warning: When using Airtable.js in the browser, your API_KEY is exposed to the client. It is highly recommended to create a separate Airtable account with limited access and share only the specific base required for the web application.

  5. Fetch records using the Query class

    master

    The Query class is used to fetch records from an Airtable table with specific filters, sorting, or pagination. A Query object is created with a Table instance and QueryParams, but it does not perform the network request until one of its execution methods is called.

    You can fetch records using three primary patterns:

    1. all(): Fetches every single record matching the query by automatically iterating through all available pages. This returns a single collection of all records.
    2. firstPage(): Fetches only the first page of results. This is useful when you only need a subset of data or want to manually control pagination.
    3. eachPage(): An iterator-style method that calls a callback for every page of results. It provides a processNextPage function that you must call to retrieve the subsequent page.

  6. Replace `list()` and `forEach()` with `select()`

    master

    The table.list() and table.forEach() methods are deprecated. Developers should migrate to using table.select() combined with the Query object's pagination methods (firstPage() or eachPage()).

    Deprecated Methods:

    • table.list()
    • table.forEach()

    Recommended Pattern: Use table.select(params) to get a Query instance, then use .eachPage() to iterate through all records or .firstPage() to get just the first set.

  7. Configure Airtable.js

    master

    Airtable.js can be configured globally, via environment variables, or per connection instance.

    Configuration Options

    • apiKey: Your secret API token (Personal Access Token or OAuth access token).
    • endpointUrl: The API endpoint URL. Useful for overriding when using an API proxy (e.g., for debugging). Can be set via the AIRTABLE_ENDPOINT_URL environment variable.
    • requestTimeout: The timeout in milliseconds for requests. The default is 300000 (5 minutes).

    Global Configuration

    You can set options globally using Airtable.configure:

    Airtable.configure({ apiKey: 'YOUR_SECRET_API_TOKEN' })

    Alternatively, set them via process environment variables (e.g., for 12-factor apps):

    export AIRTABLE_API_KEY=YOUR_SECRET_API_TOKEN

    Per-connection Configuration

    You can override settings for a specific instance when initializing the client:

    const airtable = new Airtable({endpointUrl: 'https://api-airtable-com-8hw7i1oz63iz.runscope.net/'})

  8. Use environment variables for Airtable configuration

    master

    The library provides a default_config() method that pulls certain settings from environment variables if they are not explicitly provided in the constructor or via configure():

    • AIRTABLE_API_KEY: Your Airtable API key.
    • AIRTABLE_ENDPOINT_URL: The base URL for the Airtable API (defaults to https://api.airtable.com).

  9. Use `eachPage()` to iterate through results page by page

    master

    The eachPage() method allows you to process records page by page. This is memory-efficient for large datasets. The callback function receives two arguments:

    1. records: The collection of records for the current page.
    2. processNextPage: A function you must call to trigger the fetch for the next page. If you do not call this, the iteration will stop.

    If an error occurs during any page fetch, the done callback (or the Promise rejection) will be triggered.

  10. Validate query parameters with `Query.validateParams`

    master

    Before passing a configuration object to a query constructor, you can use the static Query.validateParams method to ensure the parameters are valid and to filter out unsupported keys. This is helpful for catching configuration errors early.

    It returns an object containing:

    • validParams: An object containing only the keys that passed validation.
    • ignoredKeys: A list of keys that were not recognized by the validator.
    • errors: A list of error messages for keys that failed validation.

  11. Interact with individual records using the Record class

    master
    The Record class provides methods to manipulate, update, and delete specific rows within an Airtable table. Each record instance has an id and a fields object containing the cell values. Most methods support both a callback pattern and a Promise-based pattern (via callbackToPromise).