On Fri, Aug 27, 2021 at 6:39 PM ocket 8888 <ocket8...@gmail.com> wrote: > If it's really extremely important that consumers not only choose not to use > an API that is documented as unstable, we could do all sorts of things to > make using it harder until it's stable. A configuration option could disallow > it entirely, or a 'b' could be appended to "beta" API versions e.g. > /api/5.0b/servers, or it could even just be served as "unstable" or something > like e.g. /api/unstable/servers to make it harder to accidentally put in the > wrong version number
I'm not -1 on that idea if that is how we get consensus on this, but moving the API version out of beta would require an extra upgrade for beta clients if we did this. It might be nice to let beta users avoid that extra unnecessary upgrade once the API moves out of beta. > Though making 4.0 unstable would mean less work for consumers of the API > since they now can leave their scripts and whatnot at 4.0 for the time being. > I'd be +1 for either - choosing between the two I'd favor 5.0, but if we > can't agree to do that I'm fine dropping it. I'm also ok with either, if it means we gain consensus, but I would prefer unstable 4.0 just because one of the reasons for doing this is to avoid unnecessary client upgrades. @smalenfant I believe I've seen that idea implemented in other APIs as "API extensions." For example, an API is released as stable (e.g. 2.0), but then as features are added to the API, operators can enable them as extensions (via config), which would add the extended fields and new routes to the API. So the API stays at 2.0, but it gains new additions via the extensions. That might save us from having to add new minor API versions with every addition, but I don't think it really helps us with making breaking changes which would normally require a major version rev (which is the problem we want to fix). Adding new minor API versions isn't quite as much overhead as new major API versions in our current development model, but this proposal would help us minimize the overhead of both types. - Rawlin
