The old customer lookup endpoint has to go. It runs on a database you are retiring, it has a security finding against it, and your team has built a better replacement. The problem is that eleven other teams call the old one, and several of them do not know they do.
How you announce this decides whether it takes three months or two years.
Before you write a word, find out who actually uses it. Not who you think uses it. Look at the access logs or the gateway metrics for the last few weeks and list every calling service, with an owner for each. The announcement will reach people who read it. The logs will tell you who did not.
Write one notice that a busy person can act on. What is going away, by name. The date it stops working. Why, in one or two sentences. Exactly what to use instead, with a link to a migration guide that includes a real before and after example. And who to ask. If the replacement behaves differently, say how plainly, so nobody finds out in production.
Pick a date that is realistic for the slowest team, not the fastest. Then keep it. A deadline that moves twice teaches everyone that your deadlines are suggestions.
Send it where people will see it, and then send it to people directly. A post in the engineering channel is a record. A short message to each owner on your list, saying your service still calls this and here is the plan, is what actually gets work scheduled.
Remind people on a predictable schedule, with numbers. Eight of eleven callers have moved. Three remain, and here they are. Visible progress is persuasive, and it is much kinder than a surprise.
Offer help to the stragglers instead of chasing them. A small team with no spare time may need someone to pair with them for an afternoon. That afternoon is cheaper than keeping the old endpoint alive for another year.
When the day comes, switch it off as promised and post that you did. The final message is how people learn to believe the next one.
– Asael Shinder
Top comments (1)
Would you also put a Sunset header on the old endpoint's responses? From my experience building Voiden, an open-source API client, the people who never read the channel still look at what their request returns. A header shows up right next to the response they're already reading.