Some other projects have beta APIs until they graduate. They seem to be tied to a feature and not a specific software version. It makes obvious the feature is new.
Maybe some of APIs are getting too complicated by adding fields instead of tying it to a feature (deliveryservice is one). I’m not sure how to explain it, but seems like we could add an array of feature associated with a delivery service. Range request, signing, etc… kind of like they are modules. The modules would have their own definition/descriptions of fields needed. The UI could leverage the definition to derive what to ask the user. It sure if that is feasible or make sense. Steve On Fri, Aug 27, 2021 at 6:39 PM ocket 8888 <ocket8...@gmail.com> wrote: > *since they can now leave their scripts and whatnot at 3.0 for the time > being. > > On Fri, Aug 27, 2021 at 4:37 PM ocket 8888 <ocket8...@gmail.com> wrote: > > > Another possibility is leaving our current API versions as-is and making > a > > 5.0 that is "unstable" while 4.0 becomes our new "stable". I think that > > would be the easiest path forward for development, and whatever > > infrastructure was already anticipating an upgrade. 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 still not exactly sold on Cache Config Snapshots, but that's not > > really what this is about. > > > > I don't think, from an API consumer's perspective this really changes > much > > (which is sort of the point). When API versions are under development, > the > > policy of a consumer is to not acknowledge the version's existence. > That's > > the same thing that's happening here, just that we no longer let that > stop > > us from cutting ATC releases (which actually alleviates much of my > concern > > about a versioned API from back in the day). 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, we could add a warning alert to all > > endpoints (that can return alerts) that warns that the API version being > > used is unstable, or add a "Warning" HTTP header so that even endpoints > > that don't support alerts are covered (although no known clients of the > API > > check for that header). > > > > On Fri, Aug 27, 2021 at 3:19 PM Rawlin Peters <raw...@apache.org> wrote: > > > >> Hey folks, > >> > >> I'd like to propose that we start moving towards a TO API development > >> model where we consider the latest major version of the API > >> "unstable," while the 2nd latest major version is considered "stable." > >> What that means is that we would be free to make breaking changes to > >> the "unstable" version, while the "stable" version would maintain > >> backwards-compatibility. Eventually, once we feel that the latest > >> version of the TO API has stabilized, we will declare it "stable" and > >> deprecate the old stable version. > >> > >> I see multiple benefits to this: > >> 1. reduce the number of major API versions developers need to support, > >> making it easier to add new features > >> 2. developers can make incremental changes (breaking and non-breaking) > >> to the unstable API version in every release without having to > >> introduce new major or minor versions, making the resulting API much > >> better overall once it is stabilized > >> 3. reduce the number of unnecessary client upgrades, where the API > >> version changed but none of the routes the client uses were actually > >> changed > >> 4. clients that don't need the latest API features don't have to upgrade > >> 5. helps us release more frequently, because we aren't slowed down by > >> adding unnecessary code for a new TO API major/minor version with > >> every release > >> 6. gives us more flexibility in what features need to be completed > >> before we cut a release (because they'd be targeting the unstable API > >> anyways, we can cut a release without causing a bunch of re-work for > >> new features that missed the API version bus) > >> > >> Alas, all good things come at a price. For clients that need to use > >> the unstable version of the TO API (like Traffic Portal), their > >> upgrades may need to be closely coordinated with the Traffic Ops > >> upgrade. For TP, this is nothing new, because it is generally always > >> upgraded at the same time as TO. However, for other components that > >> may want to use the unstable API (e.g. `t3c`), this means certain > >> upgrades (not all, mind you, only those where a route the component > >> uses is actually broken) would have to be closely coordinated with > >> Traffic Ops. That said, for `t3c` at least, moving forward with Cache > >> Config Snapshots (https://github.com/apache/trafficcontrol/pull/4708) > >> would greatly alleviate that concern, since the snapshot route would > >> be kept backwards-compatible. > >> > >> Please let me know what you think of this proposal. If we can come to > >> a consensus on this, we may be able to declare TO API 3.0 "stable" and > >> 4.0 "unstable," meaning we can avoid a potential 5.0 API version in > >> whatever release comes after ATC 6.0. > >> > >> - Rawlin > >> > > >
