3 ms·

I'm not sure how I feel about that. Then you're going to be ok with making backwards-incompatible changes, but a lot of people may change to them immediately be

I'm not sure how I feel about that. Then you're going to be ok with making backwards-incompatible changes, but a lot of people may change to them immediately because they're not using the versioned url. If you were to go that way, I would recommend strongly encouraging developers to use the /v1/. "It's 3 extra characters to make sure that your app doesn't break one day because we upgrade the API." Obviously, you probably should make backwards-incompatible changes infrequently and only after communicating well with your developer community--otherwise developers will feel like they can't keep. But still, some people will miss the announcements or not have time to adapt in time.

moxiemk1 16y ago
I would hope that if the maintainer of an api was planning on making a not-backwards-compatible version change they would put a hell of a lot of time informing people about it. That way, people who need to stay on old can add in the string, and those who can adapt will. The v1 just doesn't seem to belong in that part of the url to me. Maybe if you had v1.api.example.com/coolstuff/1 - that I'd be more comfortable with.
vyrotek 16y ago
You're right, but this is the side effect of 'releasing early' and responding to custom feedback. You're usually safe to make drastic changes when its just the web application but APIs are a different story. The world of APIs is about stability and backwards compatibility, but sometimes this just isn't possible. If you remove a feature or drastically change how something behaves then it isn't possible to make it backwards compatible. If it is a drastic enough change then even the version numbers won't save you. Perhaps you completely changed how some data is persisted or queried. Its really hard to justify keeping old/broken things around when you probably just wrote and released that a month ago and now you've taken a different approach. In the end, it seems how APIs are versioned and supported completely depends on the maturity of your product. I imagine that eventually you want to get to the point where you're only adding to the API and not removing or reworking entire calls. And perhaps then you won't need the version numbers at all. But for now, they might be your only safety-net for your customers.

moxiemk1 16y ago

I would hope that if the maintainer of an api was planning on making a not-backwards-compatible version change they would put a hell of a lot of time informing people about it. That way, people who need to stay on old can add in the string, and those who can adapt will. The v1 just doesn't seem to belong in that part of the url to me. Maybe if you had v1.api.example.com/coolstuff/1 - that I'd be more comfortable with.

vyrotek 16y ago

You're right, but this is the side effect of 'releasing early' and responding to custom feedback. You're usually safe to make drastic changes when its just the web application but APIs are a different story. The world of APIs is about stability and backwards compatibility, but sometimes this just isn't possible. If you remove a feature or drastically change how something behaves then it isn't possible to make it backwards compatible. If it is a drastic enough change then even the version numbers won't save you. Perhaps you completely changed how some data is persisted or queried. Its really hard to justify keeping old/broken things around when you probably just wrote and released that a month ago and now you've taken a different approach. In the end, it seems how APIs are versioned and supported completely depends on the maturity of your product. I imagine that eventually you want to get to the point where you're only adding to the API and not removing or reworking entire calls. And perhaps then you won't need the version numbers at all. But for now, they might be your only safety-net for your customers.