Decommission APIs used by old versions of your mobile app

June 9th, 2021 Written by Gabrielle Earnshaw

Switch off without losing users

You can’t guarantee that users will ever update to the latest version of an app, so you can expect that a few users will remain on every historic version of your app.

APIs that support your app are likely to evolve. Maintaining and running old versions of an API is expensive. You need to pay for the platform it runs on, you need to pay for the maintenance needed to keep it secure and working. Sooner or later, you should decommission it.

However, when you turn an API off, any historic versions of your app still using it will stop working. This could also be expensive. You could lose users who are contributing to your revenue stream. Or, you might get poor ratings in the App Stores, making it harder and more expensive for you to acquire new users.

To decide if or when to decommission an API, you need to balance the cost of keeping the API alive with the cost of losing users. This article covers the things you need to consider when assessing when and how you should decommission your API.

Understand why users haven’t upgraded

There may be good reasons why your users haven’t upgraded to the latest version yet.

  1. They might have automatic updates switched off, and haven’t chosen to manually update yet.
  2. They might know they need to update, but they don’t know how. If you ask users to update, make the UX as simple as possible.
  3. Updating the app might mean that they lose access to features they use. They might have been removed from the app, or they might be behind a paywall in later versions.
  4. Their device might have an OS that doesn’t support the app’s latest version. E.g., if they are an iPhone user on iOS 12 and your latest app version supports iOS 14 and above, they won’t be able to update to it. They would need to update their OS to be able to update.
  5. They might be on an old version of the OS because they are using old hardware that doesn’t support the latest version. These users would need new hardware to update.

If too many of your users can’t upgrade, you might choose to wait before decommissioning the API.

Understand how users will be impacted if they don’t upgrade and their app breaks

To understand the cost of allowing old versions of your app to break, you need to understand how that will impact users. You might lose them as users, and your reputation could be damaged.

  1. Users won’t be able to use the app any more.
  2. They might feel cheated if they paid for the app, or if they have a current subscription.
  3. They might lose access to data that they have built up in the app.

If the stakes are high and lots of users would be affected, you should wait before decommissioning the API.

Find out how many users are hitting your API

The cost you incur when you switch off an API is proportional to the number of users that will be affected. You can find out how many people will be affected by using analytics.

  1. Use analytics on the API to find out how many hits it is getting. You might not be able to tell specifically if they are app users, but you’ll know that if the number is too high, you should keep the API alive for now.
  2. Use app analytics to see exactly how many users are using old versions of the app that hit the old API.
    If no-one is hitting the API, you can decommission it safely. If more users than you can afford to lose are still hitting the API, you should wait until fewer users are relying on it before switching it off.

Tell users they need to update

Your best option is to encourage users to update before the app stops working. Even for those that don’t, you can reduce the impact if they know what has happened and how they can resolve it. Here are some ways you can communicate with your users.

  1. Add functionality to the app to send users a message, or force users to update. The catch-22 here is that you can’t add this retrospectively — if users update to this version, you wouldn’t need to tell them to update. So you can only use this method if you added it before users installed the version they’re on.
  2. If you have web content in your app, you could update the web copy to show a message to users.
  3. If you support notifications, you could send a notification warning users that they need to update. Not everyone will have notifications switched on, so you won’t be able to reach all of your users like this.
  4. Use other, out-of-app channels to warn users to upgrade, such as email or social media channels.

Switch off the API

If no-one is using your API, you can switch it off safely. If it is still supporting some users when you decommission it, you should take precautions to protect your services.

  1. Make sure that attempted calls to the old API can’t damage or degrade your service.
  2. Make sure that attempted calls to the old API won’t cost you any money.
  3. Make sure that attempted calls to the old API don’t expose any kind of security loophole.

If you’re not confident that your services are protected, you should take steps to ensure that they are before decommissioning your API.


Deciding when to decommission an API is a balance between the cost of keeping it alive, versus the cost of switching it off. I’ve explained the things you need to consider from an app perspective to help you switch off at the right time. Thanks for reading, I hope you found it useful.

Blog originally posted on Medium and can be found here.


Learn more about how we use well-crafted design and engineering to build apps that are reliable, accessible, and engaging.

Written by Gabrielle Earnshaw