- 22 Aug 2022
- 3 Minutes to read
Airtable API Deprecation Guidelines
- Updated on 22 Aug 2022
- 3 Minutes to read
Airtable has many APIs that developers use to build customized software. As with any software, these APIs will evolve over time as we aim to make things better for our developers and community. With such evolution, there are times when components may need to be removed or improved. Our team strives to avoid breaking changes whenever possible, and these guidelines are written to make such cases easier to navigate. To minimize disruption to users' builds, our internal developers follow these guidelines when making breaking changes or deprecations.
These guidelines are for “breaking changes” or “deprecations” (explained in more detail below) made to any of the following surface areas:
- REST API
- Metadata API
- Enterprise API
- Webhooks API
- Blocks SDK + CLI
- Scripting extension
- Automations scripts
What do we mean by breaking change and deprecation?
There is some overlap between the terms “breaking change” and “deprecation." Below is a more detailed description of what we mean by the two:
- Breaking change - A non-backwards-compatible change to existing behavior. For example, changing the format of parameters to an existing function in the scripting extension or removing certain properties from the output of a REST API endpoint. Note that adding new data in a forwards-compatible way is not considered a breaking change (e.g. adding new keys and values to an object returned from an API endpoint).
- Deprecation - A planned breaking change where functionality will be removed in the future. For example, the planned removal of a REST API endpoint or a helper function from the Blocks SDK is considered a depreciation.
How will we roll out deprecations?
We aim to give developers time to migrate over to the new API. Where possible, we will provide a gradual rollout and migration path rather than a direct removal or breaking change.
In addition, when changing a behavior, our goal will be to support both the old and new behaviors simultaneously for a period of time before completely removing the old API. We will include this period of time in our announcement for each specific deprecation or breaking change.
How much advance notice will we give?
Where possible, we will announce any breaking changes or deprecations publicly well ahead of their planned release. The exact amount of advance notice we plan to give varies for different components. The following timelines are the minimum notice we will provide for a breaking change or deprecation.
|Webhooks API||6 months|
*Note: The SDK and CLI use semantic versioning where breaking changes are only released as part of new major versions, which will not be pre-announced. This timeline is for changes that affect the SDK and CLI outside of versioning.
|Features currently in Public Beta for >2 months||1 month|
|Features currently in Public Beta for <2 months||2 weeks|
|Features currently in Private Beta||We will determine the deprecation timeline for private beta features on a case-by-case basis.|
Are there any exceptions to the above timelines?
- As stated in the last two rows of the section above, we will provide a shorter amount of notice for public beta features. For deprecation of such public beta features that have been running for more than two months, we aim to provide one month’s notice. We will provide two weeks’ notice if the beta has been running for less than two months.
- In special cases (e.g. urgent security or infrastructure reasons), we may need to move faster than the provided timelines above. For such cases, we will do our best to contact affected developers with the stated timeline and reasoning for our decision to accelerate.
Where can I find out about upcoming changes?
We will do our best to communicate community changes via the following channels where applicable:
- The "Upcoming Deprecations" section of this document.
- Direct email outreach to affected users where possible.
- The documentation and changelog (if it exists) for each feature.
- The quarterly developer newsletter and Airtable Developers Twitter account.
- For features that have a subforum on the community forum, we'll also make a post there.
Are there any exceptions to these guidelines?
No guideline can cover every possible situation. Our intent is to provide developers with insight and tools to mitigate disruptions to building with Airtable.
This is a living document and will evolve over time. While not every situation will fit neatly into these guidelines, our goal is always to find the best solution for our community and provide as much background and communication as possible. Airtable is committed to being a stable system that, as much as possible, never breaks for its users.
Exceptions will generally be announced in all relevant release notes.
- May 26th, 2022 - Beta Webhooks API (We will stop allowing the creation of new beta-style webhook subscriptions)
- August 25th, 2022 - Beta Webhooks API (All existing beta-style webhook subscriptions will stop functioning. You will no longer receive notification pings and you will not be able to retrieve payloads.)
List of Past Deprecations
[None at this time]