Airtable is changing the way businesses work. More than 200.000 businesses are using Airtable and over 15 million bases have been created. With a $5 billion valuation, it seems investors and users believe Airtable will continue to have a big impact. We absolutely love Airtable, but there is one vital area of the product that is currently lagging behind: the API.
Let's take a deep dive into Airtable's API and talk about what it does well, and things that could be improved. This article is meant to highlight the shortcomings of the Airtable API. We hope the Airtable team can make the API as good as the product.
As the name suggests, the regular API is RESTful. It can be used to Create, Read, Update and Delete records from your Airtable bases. If you want to retrieve information about your with your bases, tables, and views, you'll need to make use of the Metadata API.
This API gives you the ability to retrieve information about the structure of your bases and tables. Airtable has opened up its Metadata API recently. Accessing it currently requires a developer token, which you can request here (unfortunately, Airtable has temporarily paused the creation of new developer tokens due to overwhelming interest).
What's great about the Airtable API
Before we get into our critiques of the Airtable API, we'll list some things that the Airtable API does really well.
The API documentation
Airtable's API documentation is great. When using the regular API, documentation will be dynamically generated for each of your bases. This makes the documentation far more personal and easier to understand because the names of your columns will be shown directly in the docs. Below is an example of Airtable's API personalization.
Two other great features of Airtable's API are the value and call examples. The API docs pull data from existing records to showcase what values could be used for a specific parameter. Below you can see some parameter value examples based on the contents of your base.
Call examples work in a similar fashion. Using existing data from your base, an example API call is generated on the right-hand side of the docs, as shown below.
Not every RESTful API has support for interacting with multiple entries. Fortunately, Airtable will allow up to 10 records for the create, update, and delete calls.
The data formatting of the attachment field type
One of the field types that Airtable keeps great formatting data on is the attachment field.
The typecast parameter
When creating or updating records that make use of the Single select or Multiple select properties you might run into the issue of posting a string that does not exactly match an existing option. By default, the Airtable API will throw an INVALID_MULTIPLE_CHOICE_OPTIONS error. However, you can make use of the typecast parameter to create a new option if no exact match was found.
What we wish the Airtable API did better
Despite the amazing features listed above, there are a few improvements we would love to see in the Airtable API. The issues that we'll be discussing apply to both API's.
It's important to know how the data you're working with is formatted. Below are a few data types listed that are missing important information about their formatting.
Data formatting issues in the Metadata API
Linked records. When working with linked records in Airtable, you're essentially creating a relationship between two tables. When making an API call to the Metadata API, unfortunately, no additional information about this relationship is provided. The image below shows what information is included in such a call. The table to which this table is linked is critical information to include in this call. Without this data, one can not properly use the returned entry.
Lookups. Similar to linked records, API calls to records with lookup fields contain no more information than the lookup's type, id, and name. When you're working with lookups, it's important to know what field it is you're looking up, from which relationship that field comes, and what aggregation formula is used to look up the records (AVERAGE, COUNT, SUM, etc.)
Single/multiple select properties. When working with single and multiple select properties, once again, no more information than the type, id, and name of the column is provided. Ideally, all of the options created in the field would be included in an API call.
Dates. When retrieving a record from the Metadata API, the only information available about a date field is its name. Seeing as dates can be formatted in dozens of ways, this is vital information of a date type. Below is a part of Metadata API call response.
Currency. Similar to dates, no further information about a currency field's formatting (currency symbol, decimals) is provided. As with dates, there are many different currency symbols, making this an important detail of a currency field type. The following is a part of Metadata API call response.
Data formatting issues in the regular API
Dates. When retrieving a record with a date field from the regular API, only the date field its name and value are available. It would be very useful to have information about the date & time format, as well as the time zone. As you can see in the image below, the createdTime field already has richer data.
Currency. As with the Metadata API, when retrieving information about a currency, the currency symbol and decimals are missing.
Duration. The same goes for time units in duration datatypes. A duration can be anywhere from milliseconds to hours. Unfortunately, no unit information about durations is provided.
API rate limits
For performance and security reasons, every API needs to have a request limit. Unfortunately, Airtable's API is limited to a mere 5 requests per second, per base. That might be sufficient in some cases, but in others, it isn't.
We would love it if Airtable made it possible to request an increase in the API rate limit like Stripe and Coda do.
When working with data, consistency is incredibly important. Unfortunately, the Airtable API lacks consistency in some cases. For example, the API only returns fields that aren't empty. Ideally, when retrieving a table's records, all of the fields would be included in the response, regardless of whether they contain data.
If your business uses Airtable as its main database, some of these issues could keep you from relying on Airtable as your single source of truth. This leads to inefficient workarounds. Because the Airtable API is not providing all the needed information in some important cases, companies are forced to replicate their database on a different service that doesn't lack vital information about the formatting of certain field types.
All in all, Airtable is an amazing product. There are many successful businesses with Airtable as the primary tool in their software stack. We would love the API to keep up with the success of the product, and we hope the highlighted shortcomings in this article can be used to achieve that.
At Softr we help businesses easily create websites and web apps using their Airtable bases as a database. To do this, we use the Airtable API intensively. Unfortunately, we are held back because of some of the issues discussed in this article. Once the quality of the Airtable API catches up to the quality of the product, we will be able to improve the quality of Softr in turn.