What's your favorite way to version an API?

Would love to read some answers here. Not an area of great certainty for me.

I'm really impressed with Stripe's versioning system, which is basically real-time data migrations at the API level. My apps never get big enough to need this, but I think it's an amazing approach.

There is a difference in public vs private API changes.

When I am in direct evolutionary control of the private API and its clients, I coordinate the changes so they remain in lock step. It can be a bit nagging sometimes, but it's a lot easier than developing a versioning strategy.

One wrinkle to this is when a client is still active through an API upgrade, it is expecting an old version of the API and perhaps would break. I don't find this to be a large problem at the moment, but it does happen sometimes. There's a pretty simple way around that... send an expected API version along with the request. The API can check it and respond in a way that tells the client to update itself (i.e. refresh).

As for public APIs, I can only conjecture since all my work has been private. But I like this guy's take, which I found linked on Yan Cui's blog. Basically, don't break backward compatibility. It means you have to live with stupid things sometimes, but it keeps your customers happy. Bonus points for incentivizing customers to move to newer/better functionality and then monitoring the old stuff, so you can turn it off when nobody uses it anymore.

Like what Stripe does, there is at least one place where I have different versions of something, and I adapt from older versions to new ones, so I don't have to think about handling the older version anymore but it still works.