[beefsack]

It's an interesting idea but I can't see how it'd work cleanly in practise. The consumer won't even know what version they're using themselves, which makes documentation and API client updates more difficult than it should be.

I don't see why it's so hard to chuck a version in the URL. There's no great need to update the version when adding new features, only when changing existing functionality.

[gdb]

(I work at Stripe.)

> It's an interesting idea but I can't see how it'd work cleanly in practise. The consumer won't even know what version they're using themselves, which makes documentation and API client updates more difficult than it should be.

To some extent, this is a design goal: most of the time, you should not need to know or care what version of the API you're on (your API's history is pretty irrelevant to a new consumer). Most API consumers just want to test out some calls, make sure they work at the time, and know that they won't break in the future. If you want to discover or set your version, you can do so easily.

> I don't see why it's so hard to chuck a version in the URL. There's no great need to update the version when adding new features, only when changing existing functionality.

It'd actually be much easier for us just chuck a version in the URL. But that would comes at the expense of ease for our users.

I think of our approach as making versions be data rather than code. It means that users using standard plugins can often upgrade without having to fork. (We also have many of our client libraries discover properties directly from the API, meaning that they very rarely need upgrading). It also means that new users never have to go and figure out "what's the current version of the API? hm, the guide I'm reading is telling me to use one that's 4 versions out-of-date — I guess I'll copy-paste the code and then modify all the URLs". (If you instead encapsulate the version in your client library, you may as well just make it a database setting.) As a general rule, a code change for a user is much more expensive than frobbing an account setting (given that it's possible to test).

[1] http://docs.aws.amazon.com/Route53/latest/APIReference/API_C...

[ivanceras]

I think he means, that when a client make a request, the API server will now what version of the API it is calling, then whatever data the api call created/updated, the version of the the API being used will also be stored into the data.

[matthewarkin]

One thing is that Stripe's documentation only shows the latest version, not the version of the API you are on. So for instance the API docs will show that the way you create a refund is charge->refunds->create(), but if your first request was before multiple refunds were a thing that api call would error since the api is expecting charge->refund().

[micro-ram]

Agreed. This bit me once.