If you don't specify a version, the default will be the 2022-11-28 version, so naturally I wonder what happens in ~two years when that version gets retired.
Author here! We think that, most likely, we will end up defaulting to the oldest version. We’ll share specific plans on that when we announce our first version deprecation.
Just so you know, we don’t intend to deprecate `2022-11-28` in two years-ish - we plan to keep versions around for much longer than that. But we offer a commitment of at least 2 years for peace of mind.
You might consider behavior more like Stripe's here (disclaimer, former member of the stripe API platform team).
As you're likely aware, Stripe defaults to the latest version for each user, and then stores that as the user's default API Version until they upgrade it at the account level.
This works pretty well, and overall I'd recommend it. It may be better to give each API Key its own default API version, since different applications may expect different versions, and API keys can be a simple way to differentiate applications.
Some of Stripe's client libraries also enforce sending a specific API version header to ensure the types are correct; my guess is that in practice, this is how most requests have their version dictated now, making the account-level setting a little anachronistic.
Everything gets trickiest when it comes to webhook bodies, since the way the payload is rendered may be different across versions, so you can have one app create an object on version A and then a different app consume the webhook under version B and see the created object with a different shape. I'm not familiar enough with GitHub's API to know how best to handle this sort of thing.
> It may be better to give each API Key its own default API version, since different applications may expect different versions, and API keys can be a simple way to differentiate applications
That would not work if I (leipert) build a client against version 2022-11-28 and you (rattray) create an API token to use with that client on a later date though, right?
Correct – and when creating the API Key, you'd want the API to give helpful hints about what other parts of the application use (which is trickier than it sounds).
It works for stripe because it’s one account per company, for GitHub you’d probably set it at the organization level, which would be a bit confusing for personal accounts as you say. I think you could still do it for personal accounts if you allow some kind of override.
The commitment to a 2 year grace period for deprecated API versions would only start at the release date of the succeeding API version, right? Many consumers are maybe only interested in the time they have to switch, not the general lifetime of a specific version.
