<i>> It might be that you want to replace it with a new, more capable version</i><p>If you're truly replacing your API with a new, more capable version there's a much better option, in my experience.<p>Roll out your new API, and replace your old API's implementation with a proxy that calls through to the new API.<p>The proxy will need very little maintenance, as all it's doing is connecting one fixed, stable API (your old one) to another fixed, stable API (your new one). Lock it down to only your old customers, if you want.<p>The support costs will be basically zero, and your existing paying customers will thank you for respecting their time with a dependable, low-churn API.
Other strategies that could come in handy before completely shutting down the API:<p>- Rate-limit the API, with increasing aggressiveness until you're down to 0 requests per unit of time;<p>- Introduce latency in serving the requests (assuming your edge can handle the increased volume of open connections).<p>Both of these introduce <i>gradual degradation</i> of the old API, without outright killing the business functionality that recalcitrant customers are nevertheless reliant upon. It helps spur a bit of urgency to switch to the new API, while remaining nice. Many (enterprise) customers will wait until the last minute to switch: essentially they are having to put in work without any tangible feature gain—at least from their perspective.<p>Regardless of the strategy, one other point I'd add is to monitor actual use of the API; if important customers are still actively using the old API, it would be unwise to shut it off.
Something that can be extremely useful as well in situations like this, is doing API brownouts, toward the later stages of the process. Disable the API for short stretches of time, on the way to disabling it entirely, to give consumers who might not be keeping up with changes a way to be alerted (they'll notice the downtime).
It would be really cool to see a graph of the API usage over time with markers showing when each "stage" was occurring. I'm wondering if there were significant dips shortly after each stage, or if it was more of a gradual decline?<p>It would also be interesting to know if the API was still being used up until the final stage? Were there any ramifications/ angry customers at the door after that?
> In addition to offering human-understandable communication, I asked the API producer to add the Deprecation HTTP header field to all responses<p>Cute, but, I question the value
I think one thing the author did not mention is telemetry. It is very dangerous to deactivate the service when there are still incoming traffic. Normally people only deactivate the service when there is absolutely zero incoming requests in an extended period of time.<p>Using old API as proxy as new API has its merit in that the callers needs to do little to pick up the logic change. However, often the old API are badly designed. Now you basically have two sets of APIs to maintain. When business requests come in, you might need to enhance the old API and the new API to support it. Of course, one could push the callers to switch to new API, but in a large organization, this often involves a lot of politics.<p>The difficulty of migrating/deactivating an API also depends on the implementation. If the API is a C++ library, it can be hard to tell how often the API gets called as you cannot tell whether the code path that contains your API is executed or not. For a HTTP or RPC service, at least you could put in some logs/metrics to check who is actually sending requests.
This kind of thing is important to consider, and could really change the world for the better in terms of more reliable world... Should we consider adding "user suggestion" as a feature to all APIs whenever possible? Clients could support by showing arbitrary messages to users, servers could say "this api will deprecate on 2024-07-10"<p>But capitalism crushes this to hell, imagine all the extra work to anticipate future problems, when "good enough, barely works" triggers immediate SHIP IT BOYS, then most engineers will just choose "someday shit stops working, oh well its not like this will be deployed in a nuclear reactor we hope they read the eula about that not being allowed"