I think ReST as a guideline rather than a strictly adhered to ideology makes a lot more sense. I'm really not keen on APIs that contrive natural actions into creating encapsulated resources. While they may be equivalent, it feels like changing the problem domain to match the technology with no clear gain.

Similar deal with the whole versioning thing. I'm not suggesting we can't improve, but putting versioning in the header seems to solve a problem I've never had while complicating a lot of other things. Checking with curl becomes more complicated, checking which version of the API you're targeting becomes more complicated, and looking up documentation (which is oddly lacking for a lot of ReST APIs) is a hell of a lot more complicated.

I'd rather design APIs how I'd actually use them in practice, not what makes them theoretically more "correct." And I'll take a locked-in version that ships today over waiting for the ideal API that's still in the works.

I hypothesize that part of the reason a full REST(w/HATEOAS) isn't popular (maybe "popular" isn't the right word here. maybe "pervasive"?) is the increase in work to move from a Type-I to a REST interface [1]. This is not insignificant in terms of up front costs. Longer term being more restful might indeed ease refactoring and versioning, but by then you may have more help working on the api (after growth). In addition then is of course down the road and things fall by the wayside.

When I try to think of some of the nicest APIs I have actually used, I don't recall them being 100% REST compliant.

I am still not sold on putting versioning in the headers. Url based versioning has the benefit that the version being used is readily apparent (visible), as well as easing scalability due to the ability of frontend proxies to route based on url partials. The pragmatist in me says url versions are 'ok'. Maybe not the best, but as a trade-off "good enough" if it makes implementing them easier.

[1]: http://nordsc.com/ext/classification_of_http_based_apis.html

Having versioning information in the headers should be as obvious as having it in the url when you are writing code that interfaces with the rest api.

Url based versioning is only more visible if you are accessing the api through a browser, in which case it's probably fine for the api to return the latest version since humans are pretty good at making sense out of new representations.

I'm not sure I understand the benefit of url partials based routing. A REST api should be easily loadbalanced using a simple round robin setup since no state lives longer than a single request.

Edit: Ok yeah, url partial based routing will allow you to implement v2 as an entirely new system.