API Deprecations Hit Small Teams Hardest: A Q&A With Two Maintainers
Archi3 min read
Contents
API Deprecations Hit Small Teams Hardest: A Q&A With Two Maintainers#
When a widely used API is deprecated, the announcement usually goes to everyone. The cost does not. Two maintainers who have handled three deprecations in four years agreed to walk through who actually pays. They asked that their companies not be named; both work on developer tools, one at a five-person startup, one at a 200-person platform.
"The first ticket came from a team of two"#
Who notices a deprecation first?
The small team. Within an hour of our notice, a two-person shop opened the first ticket. They had no upgrade path because their integration was written two years ago by a contractor who had left. A larger customer sat on the same notice for six weeks before anyone read it.
Why does size matter so much?
Because a deprecation is a scheduling problem before it is a technical one. A large company has someone whose job is to track vendor notices. A three-person team has a founder who is also doing support, payroll, and the on-call rotation. The notice is not the work. The work is finding the person who knows what breaks.
Is the technical work harder for small teams?
Sometimes simpler, sometimes not. If you call one endpoint in one place, the fix is an afternoon. If your product was built around a behavior that the new version drops, you are rewriting a core assumption. The painful cases are not the big companies. They are the small teams whose entire product is a thin layer over someone else's API.
The hidden cost is the audit, not the patch#
What does the first week of a deprecation actually look like?
For us it was three days of reading changelogs and tracing calls. We found 41 call sites. Eleven were in code nobody had touched in a year. The patch itself took two days. Finding out what to patch took five.
What should vendors do differently?
Publish the migration guide before the announcement, not with it. List every behavior change with a before-and-after example. And give a date, not a range. "Later this year" forces every small team to assume the worst week.
What did your smallest affected customer say?
That they had budgeted for one engineer-week and spent three. They did not ask for an extension. They asked for a list of which of their calls would break, because they could not afford to find out in production.
Who gets the extension, and who does not#
Do vendors treat small teams differently?
Yes, but not on purpose. Extension requests get evaluated by account size. A large customer with a renewal coming up gets a conversation. A small team gets a form reply. The teams that need the most time have the least negotiating room.
Is that fair?
It is predictable. The fix is not charity. A vendor can publish a compatibility shim for six months and let small teams migrate on their own schedule. That costs the vendor one engineer and saves dozens of teams a week each.
What about the teams that cannot migrate at all?
Those are the ones to watch. If a product depends on an API that is being removed, the vendor is effectively deciding whether that product continues. Most of the time the vendor does not know it is making that decision.
The part nobody budgets for#
What is the most common mistake on the customer side?
Assuming the notice is for someone else. The second most common is assuming the new version is a drop-in. Read the changelog for what was removed, not what was added.
Any advice for a small team facing a deprecation now?
Inventory your calls before you plan the work. Count them. Then ask the vendor which ones are affected. If the answer is vague, assume all of them. Budget for the audit, not the patch. The patch is the easy part.
And for vendors?
Tell us who you think is affected. Publish a list of endpoints and behaviors, not a paragraph. And give the smallest customers the longest runway, because they are the ones who cannot absorb a surprise.
More articles