[mpetrovich]

Making the version optional is a bad idea, IMO. It lets consumers use your API without versioning, which is like telling them, “here, create a time bomb that may or may not explode when the next breaking api change is released.”

There’s zero practical user benefit to NOT specifying the version, so why not enforce it? You’re creating a footgun otherwise.

Furthermore as others have pointed out, this is a purely cosmetic change. Using /api/$UNIQUE_STR in the URL vs. X-GitHub-Version: $UNIQUE_STR in the header are functionally equivalent, so…

Why bother making this change then? What was suboptimal about the previous way? What benefit does this bring?

EDIT: Serves me right for not reading the docs more carefully. From the docs [1]:

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

See phphphphp’s reply below for context.

[1] https://docs.github.com/en/rest/overview/api-versions?apiVer...

[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.

[timrogers]

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

[prepend]

Because they use calendar versioning the user benefit to not specifying is not having to keep track of a million different dates.

I work with a lot of APIs that just have “/v1” or “/v2” as part of the endpoint so it’s easy to specify. Setting a header parameter to a specific date is a PITA and I certainly don’t want to look up the curl syntax whenever I do simple work.

I think if they made it required, it would annoy people. So they didn’t.

[mpetrovich]

I agree with you, so then why not stick with the previous /api/v2 url approach?

And it would annoy me far more if my app that talks to GitHub inexplicably breaks in a few years because of a release I wasn’t aware of.

These changes make no sense to me.

[skeeter2020]

>> Setting a header parameter to a specific date is a PITA

Really? Don't you do this all the time for everything beyond a simple GET? From my experience it's far preferable than URL versioning because you can version on an individual endpoint. Right now I'm consuming Versions 0.9, 1.0 and 2.0 from a vendor; it would be way nicer to set individual headers than somehow mananging multiple endpoints.

[RileyJames]

Is there an easy way to set a ‘sticky’ curl header, or change/set the default headers?

I did a quick search and couldn’t see any docs on this use case.

[pbreit]

Why version at all? They went 10 years without versioning. The reasons stated for needing versioning are weak at best ("like deleting a response field, making an optional parameter required, or deleting an endpoint entirely"). Just retain backwards compatibility. Once you have versioning, people feel more comfortable making incompatible updates which is a terrible direction.

[sitkack]

> Just retain backwards compatibility.

I'll take the bait, like C++?

> comfortable making incompatible updates

Incompatible how? You specify the version, your semantics are of that version.

[WorldMaker]

I think that's an interesting question here. Especially with how much was invested into GitHub's GraphQL and the once implication that the GraphQL API would entirely replace the REST API. (And the GraphQL API still having its own, different versioning scheme now and after the change mentioned in this blog post.)

The blog post suggests that we might find out some of the API changes that warranted this change as early as next month, but it would have been great for this blog post to include some examples of changes that were coming.

[thrwawy74]

You could make the argument that having it in the URL is better than using a custom header, because customer headers may see mangling/blocking in corporate environments (indiscriminantly).

I don't think it's a strong point.