First steps with Airtable

airtable_intro.md

Using AirTable

Airtable has an API that follows REST standards. Authentication requires the authentication token, which can be generated on the account page of the web application.

The API is documented here. (Interestingly, it automatically customizes the examples to reflect your existing databases.)

The API provides methods to

• create,
• read,
• update, and
• destroy

records.

Limits

The API is limited to 5 requests per second. If you exceed this rate, you will receive a 429 status code and will need to wait 30 seconds before subsequent requests will succeed.

Authentication

You can authenticate to the API by providing your API key in the HTTP authorization bearer token header. Alternatively, a slightly lower-security approach is to provide your API key with the api_key query parameter

The following examples will assume that the YOUR_API_KEY environmental variable is available in the shell session.

Performing actions on a table

List records

To list records in Experiments, issue a GET request to the Experiments endpoint.

curl "https://api.airtable.com/v0/appSzxZJK94yvza3a/Experiments?maxRecords=3&view=Grid%20view" \
-H "Authorization: Bearer $YOUR_API_KEY"

The following parameters are available:

• fields
• filterByFormula
• maxRecords
• pageSize
• sort
• view

Note: These parameters need to be URL encoded. Airtable offers a web tool to perform the encoding.

Pagination

The server returns one page of records at a time. Each page will contain pageSize records, which is 100 by default.

Retrieve a record

This command will retrieve information about record recF1bps9BZQFQOoW, which corresponds to Exp-1:

curl  https://api.airtable.com/v0/appSzxZJK94yvza3a/Experiments/recF1bps9BZQFQOoW \
-H "Authorization: Bearer $YOUR_API_KEY"

Attachment records

In attachment objects included in the retrieved record (Attachments), only id, url, and filename are always returned. Other attachment properties may not be included.

Create a record

You can include all, some, or none of the field values.

For example, this command adds two (existing) samples to the experiment table:

curl -v -XPOST https://api.airtable.com/v0/appSzxZJK94yvza3a/Experiments \
-H "Authorization: Bearer $YOUR_API_KEY" \
-H "Content-type: application/json" \
 -d '{
  "fields": {
    "Samples": [
      "rec8syc5ksmhc4X82",
      "recR2YZojJt6ufDMV"
    ],
    "Owner": [
      {
        "id": "usr4TynRB66MLi8yx",
        "email": "[email protected]",
        "name": "Thomas Sandmann"
      },
      {
        "id": "usrzB0XCskOLO6WAq",
        "email": "[email protected]",
        "name": "Thomas Sandmann"
      }
    ]
  }
}'

Attachment records

To create new attachments in Attachments, set the field value to an array of attachment objects. When creating an attachment, url is required, and filename is optional.

Airtable will download the file at the given url and keep its own copy of it. All other attachment object properties will be generated server-side soon afterward.

Update a record

Updating some fields

To update some (but not all) fields of a Experiments record, issue a PATCH request to the record endpoint. Any fields that are not included will not be updated.

curl -v -XPATCH https://api.airtable.com/v0/appSzxZJK94yvza3a/Experiments/recF1bps9BZQFQOoW \
-H "Authorization: Bearer $YOUR_API_KEY" \
-H "Content-type: application/json" \
 -d '{
  "fields": {
    "Samples": [
      "rec8syc5ksmhc4X82",
      "recR2YZojJt6ufDMV"
    ]
  }
}'

Updating all fields

To update all fields of a Experiments record, issue a PUT request to the record endpoint. Any fields that are not included will be cleared.

Delete a record

This command will delete record recF1bps9BZQFQOoW:

curl -v -XDELETE "https://api.airtable.com/v0/appSzxZJK94yvza3a/Experiments/recF1bps9BZQFQOoW" \
-H "Authorization: Bearer $YOUR_API_KEY"

Versioning

As the API matures, things will change:

• a change in major version is backwards-incompatible (e.g. 1.x.x to 2.x.x)
• a change in minor version is backwards-compatible, but adds new functionality (e.g. x.1.x to x.2.x)
• a change in patch version is a bug fix (e.g. x.x.1 to x.x.2)

Resource URLs include only the major version number in the URL: https://api.airtable.com/v0/appXYZ would be the route for 0.1.0, 0.2.4, 0.2.5 etc. All these routes would be backwards-compatible.

When a 1.0.0 version is introduced, it will have a separate route, https://api.airtable.com/v1/appXYZ.