Hmm.. I don't really see the need for versioning in REST APIs. Webapps don't have versions, because it's smarter to just push small changes continuously. Your API maps functions in this changing application - keeping an old API around isn't like keeping an old version of Word around. If the app changes so a given API call won't work any more, it won't magically keep working because of versioning...
It doesn't add much value to give users a /v2/ to call, if it's not because that /v2/ will keep working independently of changes to the app. If it stops working some time because you're changing your app, you'll still have to inconvenience your users by pulling an old version out of production. On the other hand, there's no point in forcing users to upgrade to a "new" API, if the new API doesn't do anything the old one didn't.
No reason you couldn't just deprecate what will stop working on a method-by-method basis instead. If you pair it with application-keys, you'll know which users are using the methods you're about to deprecate and talk directly to them about transitioning away.
When something less radical changes, you can add new parameters and add new fields in the response just fine, without invalidating the old version - and if you can't, add a new method, e.g. /clients/list_with_invoices/ as the new version of list.
Yea having to version a "REST"ful api usually means its a was not very restful in the first place . Meaning the api is not hypertext driven and is probably a rpc style api with meaningful urls. If it was hypertext driven it would all be transparent to the consumers , it could be v2 or foobar , doesn't matter .
It doesn't add much value to give users a /v2/ to call, if it's not because that /v2/ will keep working independently of changes to the app. If it stops working some time because you're changing your app, you'll still have to inconvenience your users by pulling an old version out of production. On the other hand, there's no point in forcing users to upgrade to a "new" API, if the new API doesn't do anything the old one didn't.
No reason you couldn't just deprecate what will stop working on a method-by-method basis instead. If you pair it with application-keys, you'll know which users are using the methods you're about to deprecate and talk directly to them about transitioning away.
When something less radical changes, you can add new parameters and add new fields in the response just fine, without invalidating the old version - and if you can't, add a new method, e.g. /clients/list_with_invoices/ as the new version of list.