4 ms·

Clear deprecation policies are great, but I also think that every public API needs to be explicitly versioned. This is commonly achieved by including the versio

by kijin 15y ago

Clear deprecation policies are great, but I also think that every public API needs to be explicitly versioned. This is commonly achieved by including the version in the URL (api.example.com/v3/whatever), but a suitable header (API-Version: 20120420) would also work. Once published, a specific version of an API should never change in a backward-incompatible way, only become superseded by newer versions. Likewise, you don't change or deprecate individual methods, you merely stop supporting older versions. That would make it much easier for developers to keep track of API changes.

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 kijin 15y ago

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.