Ask HN: What's a reasonable deprecation period for an API? | Hacker News Reader

Ask HN: What's a reasonable deprecation period for an API?

3 pointsgabrielsroka9 comments

We're going from v1 to v2. How much time is good to give our users? How do you usually notify users? Do you collect email addresses ahead of time?

View on HN

It depends on the amount of work that your customers need to do to migrate, the size of your user base, and your ability to communicate (and incentivize) the changes with them. The best option is to provide enough value that it is worth it to your users to pay the cost of migration. That’s not necessarily an easy thing to do.

> pay the cost of migration

In terms of their time?

Depends on the nature of the change. Some migrations require additional infrastructure to migrate safely. But I imagine most changes you’re talking about are the cost in terms of time spent.

Depends on your users. A company I work with has clients who sign agreements annually, so their standard deprecation period is... one year. If people are building commercial products or internal tools on your API, you've got to give them longer IMO.

Also it makes sense to phase deprecation. Start by no longer issuing new API keys. If your API has a messages or comments field in the return object, you can add a notice that it's deprecated with a link to the new API to discourage new development.

The biggest thing (IMO) is to make the transition process painless. If there's functionality that v1 has that v2 doesn't, users who like that functionality will cling to v1. If there's an endpoint in v1 with no clear equivalent in v2, that's gonna slow adoption unless there's a clear transition process documented somewhere.

Thanks for your clear and concise answer. I think everything you said makes sense.

At the end of the day, we can check our logs to see who's using it and that's about it.

For v2, we can start doing some of those things you mentioned -- we didn't do them for v1.

The answer depends on how many customers you are willing to loss.

From a client perspective, everything is running well, you decide to change and it will cost them $X and Y (time) to match it. If there is not great value to the customer to change, then they might seek out a competitor.

Can you not make a compatibility library that lets them use the old interface on the new API?

Can you not run both systems, just not allow new customers on the old API?

Those are good points.

> compatibility library

Even if we do, they still have to use it, which is still a change (albeit a smaller one).

> run both systems

Unfortunately, no.

What is the motivation for your users going from v1 to v2? If there is a business advantage, they will & you can deprecate old version sooner. If not, it takes more time & effort.

v1 is an old design that won't scale. We need to deprecate it. v2 will be newer and better for us and our end users.

Reply on news.ycombinator.com