News for hackers. Stuff that matters.
Re:APIs Are Forever, Wait No...They Can Go Away at Any Time by kijin on Friday April 20, 2012 @09:48PM (#3870580)
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.

Re:APIs Are Forever, Wait No...They Can Go Away at Any Time by philbo on Saturday April 21, 2012 @09:36AM (#3871709)
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/bujxbmhffep...

Re:APIs Are Forever, Wait No...They Can Go Away at Any Time by tommi on Saturday April 21, 2012 @10:51AM (#3871894)
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.

Re:APIs Are Forever, Wait No...They Can Go Away at Any Time by kijin on Saturday April 21, 2012 @12:52PM (#3872219)
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.