3 ms·

That definitely seems like the common-sense approach. There was an interesting article posted on here recently though, which argued that API versioning is an an

by philbo 15y ago

That definitely seems like the common-sense approach. There was an interesting article posted on here recently though, which argued that API versioning is an anti-pattern. It makes some good points, although I'm not sure I entirely agree with the conclusion drawn, since it places all of the responsibility on the authors of the client-side code: https://secure.designinghypermediaapis.com/nodes/bujxbmhffepq https://secure.designinghypermediaapis.com/nodes/bujxbmhffep...

tommi 15y ago
I agree on the disagreement. On removing functionality: "This can be handled in the opposite way we dealt with new functionality: if you don't see something, don't display it." In my experience that is just too simplistic idea to cover all cases hence the need for versioning.
kijin 15y ago
That looks like a too rigid view of what REST requires. It's possible to view different versions of an API as different representations of the same data. For example, an HTTP server is permitted to return different responses, or even return an error, depending on the contents of the client's "Accept:" header. If versioning was done with a header instead of the URL, it would achieve essentially the same results. The client would be saying "I want /user/123/posts/recent, and I want it in the APIv3 format." If an API method changes so much that it is no longer recognizable as a different representation of the same data, the URL should probably change to reflect the new content. The old URL would then return data only when the old version is requested, and "406 Not Acceptable" when the new version is requested. So I don't see any reason why API versioning can't be RESTful. It's just slightly more difficult to do it RESTfully, compared to adding the version in the URL. In any case, I'd rather take practicality over RESTful purity.

by philbo 15y ago

tommi 15y ago

I agree on the disagreement. On removing functionality: "This can be handled in the opposite way we dealt with new functionality: if you don't see something, don't display it." In my experience that is just too simplistic idea to cover all cases hence the need for versioning.

kijin 15y ago

That looks like a too rigid view of what REST requires. It's possible to view different versions of an API as different representations of the same data. For example, an HTTP server is permitted to return different responses, or even return an error, depending on the contents of the client's "Accept:" header. If versioning was done with a header instead of the URL, it would achieve essentially the same results. The client would be saying "I want /user/123/posts/recent, and I want it in the APIv3 format." If an API method changes so much that it is no longer recognizable as a different representation of the same data, the URL should probably change to reflect the new content. The old URL would then return data only when the old version is requested, and "406 Not Acceptable" when the new version is requested. So I don't see any reason why API versioning can't be RESTful. It's just slightly more difficult to do it RESTfully, compared to adding the version in the URL. In any case, I'd rather take practicality over RESTful purity.