Quickly make an API from Airtable
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
src
.gitignore
.travis.yml
CHANGELOG.md
CONTRIBUTING.md
LICENSE.md
README.md
index.js
index.test.js
package.json

README.md

micro-airtable-api

Build Status

Quickly make an API from an Airtable. Use it as a database or CMS without any hassle.

Airtable offers a great API, but using it on the client-side exposes your API key, giving anyone read-write permissions to your data. micro-airtable-api proxies an Airtable API, hiding your API key and letting you control access (eg. marking an API as read-only).

Use Airtable as a cheap-and-easy CMS for simple blogs and sites 🎉

🚧 This project has not been thoroughly tested. Use at your own risk!

Usage

The simplest way to get started with your own Airtable proxy is via now. Setup and deploy with a single command:

$ now rosszurowski/micro-airtable-api -e AIRTABLE_BASE_ID=asdf123 -e AIRTABLE_API_KEY=xyz123

> Deployment complete! https://micro-airtable-api-asfdasdf.now.sh

Once deployed, you can read or edit your data at:

https://micro-airtable-api-asdasd.now.sh/v0/TableName

To update to a new version with potential bugfixes, all you have to do is run the now command again and change the URL you call in your app!

CLI

If you'd like to run a proxy on a different service, you can use the micro-airtable-api command-line. Install the package globally and run it:

$ npm i -g micro-airtable-api
$ AIRTABLE_BASE_ID=asdf123 AIRTABLE_API_KEY=xyz123 micro-airtable-api

> micro-airtable-api listening on http://localhost:3000

JS API

For more advanced configuration or to integrate with an existing http or express server, you can also install the package locally and pass the handler into your webserver:

$ npm i micro-airtable-api
const http = require('http');
const createAirtableProxy = require('micro-airtable-api');

const config = {
  airtableApiKey: 'YourApiKey',
  airtableBaseId: 'YourBaseId',
};

const server = http.createServer(createAirtableProxy(config));

Setup Notes

You can find your Base ID in the Airtable API docs and API key in your Airtable account settings.

Read below for all configurable options.

Configuration

micro-airtable-api is configurable both through the JS API and the CLI.

const http = require('http');
const createAirtableProxy = require('micro-airtable-api');

const config = {};

http.createServer(createAirtableProxy(config));

config.airtableBaseId (required)

The Base ID of the Airtable you want to connect to. You can find this in your Airtable API docs.

config.airtableApiKey (required)

Your personal account API key. You can find this in your account settings.

config.allowedMethods

An array of HTTP methods supported by the API. Use this to restrict how users can interact with your API. Defaults to all methods.

This maps directly to operations on Airtable:

  • GET allows reading lists of records or individual records
  • POST allows creating new records
  • PATCH allows updating specific fields existing records
  • PUT allows updating an entire existing record
  • DELETE allows removing records.

You can read Airtable's API documentation for more details about how to use these methods.

To create a read-only API, to use as a CMS:

createAirtableProxy({
  airtableBaseId: '...',
  airtableApiKeyId: '...',
  allowedMethods: ['GET'],
});

To create a write-only API, to use for collecting survey responses:

// A write-only API (eg. surveys)
createAirtableProxy({
  airtableBaseId: '...',
  airtableApiKeyId: '...',
  allowedMethods: ['POST'],
});

You can set table-specific permissions by passing in an object with table names as the keys.

If you were setting up a blog through Airtable, you could do the following:

createAirtableProxy({
  airtableBaseId: '...',
  airtableApiKeyId: '...',
  allowedMethods: {
    'Blog Posts': ['GET'],
    'Blog Comments': ['POST', 'PATCH', 'PUT', 'DELETE'],
  },
});

Note, the OPTIONS method is always allowed for CORS purposes.

CLI Options

The CLI exposes the above configuration options through environment variables for easy deployment.

$ AIRTABLE_BASE_ID=asdf123 AIRTABLE_API_KEY=xyz123 micro-airtable-api
  • AIRTABLE_BASE_ID (required) Same as config.airtableBaseId above
  • AIRTABLE_API_KEY (required) Same as config.airtableApiKey above
  • ALLOWED_METHODS Similar to config.allowedMethods above, except a comma-separated list instead of an array. For example, allow creating new records but not deleting by passing in a string without the delete method: ALLOWED_METHODS=GET,POST,PATCH,PUT. The CLI does not support table-specific permissions. Use the JS API if this is something you need.
  • READ_ONLY A shortcut variable to restrict the API to only GET requests. Equivalent to ALLOWED_METHODS=GET. Users of the API will be able to list all records and individual records, but not create, update, or delete.
  • PORT Sets the port for the local server. Defaults to 3000.

Contributing

Issues and PRs are welcome! If you'd like to contribute code, check out our guide on how to contribute.

License

MIT