Discussion about API versioning in the Vision plugin and the confusion around stable vs experimental versions.

Is there a reason the API version numbers in the Vision plugin don’t match the numbers specified here: https://www.sanity.io/docs/api-versioning . Maybe I’m missing something?

Oh ok, I think I understand.v1 = outdated
vX = current, most recent

Is there a reason v2021-03-25 is there? Is that also essentially v1?

I missed the experimental section of that page, thx for the help!

vX is the experimental version that's likely to change or be unstable. So proceed with caution! The v2021-03-25 version will be your best bet in terms of getting the most recent, stable version.

Thats the version that follows the date incremented version numbers that we use now.

Oh ok, where do we following what is considered the most recent stable version?
I thought the current stable is what was listed at the top of
https://www.sanity.io/docs/api-versioning#71d69d9f4146 . For instance, currently

v2021-06-07

Ah, yeah I see how that's confusing. Using v2021-03-25 in Vision will be what you want. On your frontend when configuring a client you'd use the current date to make sure you're getting the right one. We'll add in a note to the docs to make that more clear!

Sorry, I’m not sure I follow 😞. If v2021-03-25 is the most recent stable, and we’re recommended to use the current date (such as today), would we be getting v2021-06-07 or v2021-03-25?
Is v2021-06-07 the most recent experimental version and v2021-03-25 is the most recent stable?

Sorry, let me see if I can clarify: using v2021-06-07, for example, would use the most recent, stable API version released on or before June 7, 2021. v2021-03-25 would would use the most recent, stable API version released on or before March 25, 2021. You'll only end up using an experimental version if you use vX.

I think the reason it's a bit confusing is that the version number notation is "overloaded"; it's used both in a "filter" capacity in the URL, where it means " give me the most recent <= {date}", and as names for actual versions, where it means "the version released at {date}" :)

In this particular case, both v2021-03-25 and v2021-06-07 requests result in the actual version v2021-03-25 (since there's no newer stable version)

In this particular case, both v2021-03-25 and v2021-06-07 requests result in the actual version v2021-03-25 (since there's no newer stable version)

Ah right, thank you both! I think my confusion came from the docs. I thought there was some relevance to the date of v2021-06-07 but it sounds like that was just an arbitrary date example. The reason I made this thread originally was because the Vision plugin explicitly references v2021-03-25, but the docs reference v2021-06-07 (the arbitrary example date).

Thanks again!!

I have this confusion everytime, may be add some info in brackets?

eg:vX (beta)v2021-03-25 (latest, stable)
v1 (old)