5 ms·

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

3 points by gabrielsroka 6y ago

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?

the_arun 6y ago
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.
- gabrielsroka 6y ago
  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.
  - deleted 6y ago
    [deleted]
deleted 6y ago
[deleted]
Centigonal 6y ago
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.
- gabrielsroka 6y ago
  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.
jaredcnance 6y ago
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.
- gabrielsroka 6y ago
  > pay the cost of migration In terms of their time?
  - jaredcnance 6y ago
    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.
sloaken 6y ago
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?
- gabrielsroka 6y ago
  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.

3 points by gabrielsroka 6y ago

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?

the_arun 6y ago

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.

gabrielsroka 6y ago
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.
- deleted 6y ago
  [deleted]

deleted 6y ago

[deleted]

Centigonal 6y ago

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.

gabrielsroka 6y ago
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.

jaredcnance 6y ago

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.

gabrielsroka 6y ago
> pay the cost of migration In terms of their time?
- jaredcnance 6y ago
  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.

sloaken 6y ago

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?

gabrielsroka 6y ago
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.