I'd like to see the subset of the answers from people who have actually maintained a successful and widely used API. I'm skeptical that most clients are sophisticated enough to deal with the pure REST dream.
Specifically, changing the JSON representation of, say, a list of account activity, is perfectly compatible with REST. "Oh, you want /account-activity, here it is, why yes, it does happen to be a list of links to /account-activity/messages and /account-activity/transactions instead of the flat list of things with a 'type' field like it was last week, but I'm directing you to the resource, so it's all good"
From my experience, you can go a long way by just adding new HTTP end-points and extending the JSON with new attributes with no versionning. By the time you really want to change things it probably mean that you understand the domain well enough to make a new better service.
I worked on and supported a pseudo-API at PayPal for 7 or 8 years..."Web Accept" and "IPN". 10s or 100s of thousands of integrations. 10s or 100s of millions of payments.
No versioning.
It works really well. Once you add versioning, it's too tempting to add breaking changes and just keep versioning. It becomes a total mess for everyone.
I'm tempted to both agree with you and curse at you.
Yes, I agree with the idea of enforcing backward compatibility as much as possible and, when that fails, make it a social problem (documentation, email, advance notice...).
But being in the midst of one of those PayPal integration... oh my, what a mess!
* The sea of DEPRECATED in the documentation (hide it away?)
* The pervasive inconsistency in everything
* The choice of x-www-form-urlencoded for IPN data... (I'm
trying to figure out some charset bug at the moment)
PayPals API certainly isn't the worst but it's pretty awful. So much pain doing PayPal integrations. I assumed it just kind of happened but I'm shocked if you guys thought it was good... See Stripe for an example of not to abuse your API users.
It's not perfect but I'd like to point out that it was born in 2000 and still works fine today 13 years later. I think all the sample code I wrote is still in the PayPal docs somewhere.
The most painful PayPal integrations for me were the SOAP ones.
No. There's nothing RESTful about changing the data format without notice - on the contrary: REST implies that media types should be well defined, and that includes specifying those issues.
There's nothing in REST that opposes versioning either. All it says is that you shouldn't use the URLs for it, since then if the client wants to upgrade, it'll break all his stored links.
Versioning can be handled just fine by having the client request the media type with the version he needs, e.g.:
Accept: application/users-list+v1
And if it asks for that, you should definitively give it the v1 format, not throw the v2 and let it deal with that.
We found that our API and web controllers were doing the exact same thing, so with rails we're just hitting the same endpoints but just using respond_to to differentiate whether we respond with a jbuilder view (json) or standard HTML.
The client passes in a version number and VersionCake intelligently renders the appropriate view version or degrades to a prior version when the specified versioned view doesn't exist.
Happy user of VersionCake here! I am using it to support older versions of our iPhone apps while our backend can improve and expand without problems. Thanks for your work!
That's exactly what I thought. I can't help feeling this is yet another "do it this way" post by a person that is big on theory but probably very low on real life in-the-field practice. You can't advise 301 when you had to actually implement it. IMO this post does more harm than good by misleading its readers. It reminds me a lot of (sometimes very well known) people that feel entitled to teach you how to write javascript SPAs after trying their hand at the most simple case, like a todo app. The incentive to be seen, known, collect points here or there is totally biasing the game.
Pure REST can be a roadblock in the pragmatic real world. I've impemented "REST" API calls in client platforms that could do GET and POST and that's it. No PUT, DELETE, etc. But since the API allowed deletes via a POST action, it was possible for me to achieve what I needed to do within those constraints.
No matter how large, successful and technical your client is, they'll undoubtedly have their least HTTP-literate monkey developing against your API. It gets awkward having to explain basic things to someone you started out assuming was your peer.
Specifically, changing the JSON representation of, say, a list of account activity, is perfectly compatible with REST. "Oh, you want /account-activity, here it is, why yes, it does happen to be a list of links to /account-activity/messages and /account-activity/transactions instead of the flat list of things with a 'type' field like it was last week, but I'm directing you to the resource, so it's all good"