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.
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.
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.
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.
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?
11 comments
[ 2.9 ms ] story [ 50.0 ms ] threadAlso 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.
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.
In terms of their time?
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?
> 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.