Dealing with Deprecating APIs

From time to time we have to make backwards incompatible changes to our APIs. To make sure everything keeps working for our customers we have a date based API versioning system which works pretty well. However, this does mean that at any point in time we have a lot of customers using older versions of the API, which in turn means they're not getting the latest and greatest data from us.

We've been testing various approaches to persuade people to upgrade, some with more success than others.

Emailing

Whenever we release a major new feature we email all our existing customers. Getting access to a new data attribute is often a big incentive for people, but unless they're actively in the process of integrating Clearbit emails are easily archived and forgotten about. Customers are wary of breaking something that's already working, so they often postpone upgrades indefinitely.

Notices

Our docs only reflect the latest version of the API, and after a couple of cases of people on older APIs getting very confused about mismatches between the docs and their live API we've added a big warning which is fairly hard to miss.

X-API-Warn

We always return the API version you're on with the X-API-Version response header, but today we've taken that a step further by including a X-API-Warn header for requests to deprecated APIs. Whenever we encounter this header in any of the API clients we print the contents to STDERR, which looks something like this:

WARNING! You are using a deprecated version of the API which may return less data.
For more information on upgrading see https://clearbit.com/docs#versioning

The idea is that this message will appear in server logs prompting people to upgrade.

We're always searching for better ways to tackle this problem, so if you've any approaches that work come join us in the Slack room. Or even better come work with us!