[phphphphp]

The version is only optional in the request: when it isn’t provided in the request then the system will default to the version of the API that would have been given had this new system not been implemented, so there is no change in behaviour for existing implementations, there are no footguns or impending explosions. The key point is when they refer to today, they don’t mean “today as of the time of the request” they mean today, as a point in time: November 28th, 2022.

The benefit of this new versioning approach is that they can maintain backwards compatibility for existing implementations while introducing breaking changes for new implementations to benefit from.

In an ideal world, sure, they should have implemented this from the start, but they didn’t, so going forward they have to accommodate both existing implementations (by not breaking anything) and new implementations (by providing features that would break existing implementations).

They’re basically just implementing stripe’s well-understood and battle tested approach for versioning, while maintaining backwards compatibility. I am struggling to see any problems with the approach, in fact, it seems like the only right approach (?)

[mpetrovich]

Oh, so you’re saying that omitting the version from the header will ALWAYS return this specific version, NOT the latest version?

That certainly addresses the footgun I mentioned.

EDIT: From the docs: Requests without the X-GitHub-Api-Version header will default to use the 2022-11-28 version.

[phphphphp]

Yes, exactly, that’s my understanding from the blog post and changelog post. I think perhaps the waters have been muddied a little because of our expectations of API versioning + GitHub’s need to maintain backwards compatibility for existing implementations. The way I understand is that “v3” of the API (which has been around for 10 years) is now version “2022-11-28” and so existing implementations while be using version “2022-11-28” without any required change.

[buro9]

I don't see how that can be true when new versions put a 2y time bomb on old versions.

At some point the default 28th Nov 2022 version is unsupported... So what is served must change... Either it's the latest at the time or the behaviour of receiving a response without providing the header is removed.

[saghm]

I often find it useful to think of things like this as "no version specified" being the lowest version, and then explicit versions start counting after that.

[timrogers]

Author here. You've put it better than I could have put it myself. Thanks!