- 26 Jan 2023
- 3 Minutes to read
Airtable API Deprecation Guidelines
- Updated on 26 Jan 2023
- 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:
- Web API (Includes Enterprise and Webhooks API)
- Blocks SDK + CLI
- Scripting extension
- Automations scripts
- Public betas
- Private betas
- Special cases
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-backward-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 Web 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 Web API endpoint or a helper function from the Blocks SDK is considered a deprecation.
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 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.
*Note: Unlike other areas, both the Blocks SDK and CLI are versioned, and breaking changes are only released as part of major versions. This timeline requirement is for changes independent of versioning (e.g. a change to the blocks model bridge that affects all custom apps independent of SDK version, or a change to our minimum supported SDK version). It is not a requirement to pre-announce new major versions.
|Private Beta||We will determine the deprecation timeline for private beta features on a case-by-case basis.|
In special cases (e.g. urgent security/infrastructural reasons), we may need to move faster (or in some cases for major changes, slower) than the given timeline.
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.
- February 1st, 2023 - API key deprecation (More info coming soon...)
List of Past Deprecations
- 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.)