API Versioning: How to Evolve Your API Without Breaking Existing Clients

𝐃𝐚𝐧𝐢𝐞𝐥 𝐥𝐚𝐧𝐝𝐬 𝐢𝐧 𝐑𝐨𝐦𝐞 𝐟𝐨𝐫 𝐚 𝐜𝐨𝐧𝐟𝐞𝐫𝐞𝐧𝐜𝐞. 𝐏𝐡𝐨𝐧𝐞 𝐚𝐭 4%.

He reaches the hotel, pulls out his charger, and stops.

The plug doesn’t fit the socket.

Nothing is broken. The phone works. The socket works. They just no longer speak the same shape

Software has the same problem every day.

A team improves their API. They rename a field, change a format, remove something “nobody uses.” It works perfectly on their side.

Then thousands of people who haven’t updated their app open it on Monday morning, and it stops working. Payments fail. Screens go blank. Support lines fill up.

The new socket was better. It just didn’t fit the plugs already out in the world.

Good engineers know that once an API is public, it becomes a promise. You can improve it, but you can’t quietly break the people already relying on it.

So instead of forcing everyone to change overnight, we give them an adapter: the old version keeps working while the new one is introduced, and nobody is left standing in a hotel room with a dying phone.

What’s the most painful breaking change you’ve had to recover from?