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.
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.
Anyway, good luck and happy to chat more.