> Not to keep the can of worms open, but could a happy medium an alternative here be to add a new section to our API responses at the same level as "response" that we could add new/breaking stuff to in the current API version?
idk, I don't really think that helps too much. It seems like it shifts the problem from the `response` of the response being unstable to just the response being unstable. Sure you can use the stable object, but what does that gain you over just using the stable API? I guess granularity on a per-endpoint basis. What do you do for non-breaking changes, just also add them to the outer response? What about for collections? Like if we add a `tags` array to servers, then if you request `/servers` do you essentially get a response with two copies of the data you wanted, but one of the copies has a single extra field on each element? Or would it have to include only an identifier and we force clients that want to use it to do an O(2n) hash mapping on the results to be able to associate the right extra data with the right original structure? Either way the upgrade path wouldn't be too much more complex than just changing a number in one place and then usages for affected things - you only skip that single number. In the worse case where you have to do the mapping upgrading would actually be harder than using API number only. On Wed, Sep 8, 2021 at 4:07 PM Gray, Jonathan <jonathan_g...@comcast.com.invalid> wrote: > > we'll still have saved ourselves from the pain of having yet another > major TO API version > > That seems like the elephant in the room eventually that’s going to need > to change eventually. > > > Not to keep the can of worms open, but could a happy medium an > alternative here be to add a new section to our API responses at the same > level as "response" that we could add new/breaking stuff to in the current > API version? > > The main problem we’ve suffered with is the golang json marshaller being > incredibly strict about what is produces and consumes with strong typing. > If anything doesn’t match up precisely to the structs on the other side of > the marshaller, or use incredibly slow reflection, it just throws errors. > I’d normally be moderately ok with a slushbucket extensions subkey to do > whatever in, but golang can’t out of the box handle it in a performant way. > > Jonathan G > > From: Dave Neuman <neu...@apache.org> > Date: Wednesday, September 8, 2021 at 3:58 PM > To: dev@trafficcontrol.apache.org <dev@trafficcontrol.apache.org> > Subject: Re: [EXTERNAL] Proposal: stable vs unstable TO API versions > Yeah, Jonathan hit the nail on the head, there are some specific things > coming that we know are breaking changes, and it would be nice to add those > to 4.0 instead of having to roll yet another API version before 4.0 is even > released. I am +1 with doing this just for 4.0 and then retrospecting > after. > > Not to keep the can of worms open, but could a happy medium an alternative > here be to add a new section to our API responses at the same level as > "response" that we could add new/breaking stuff to in the current API > version? That way, clients that don't need or know about the new breaking > thing could just use the `response` section which is stable and new clients > can use the `unreleased` (or whatever) section? It's just json so > everytime you need to change it you can just add a new field under > unreleased and then once a feature/whatever is stable and we are ready to > make a new API version, we just move stuff from `unreleased` up to > `response`? Just a thought, trying to come up with something that allows > us to iterate quickly without potentially causing customer issues and/or > getting ourselves in a situation where upgrades are broken. > > --Dave > > > On Wed, Sep 8, 2021 at 3:40 PM Rawlin Peters <raw...@apache.org> wrote: > > > > It seems you have a very specific set of goals with this proposal > rather > > than a general practice here, and possibly a very limited duration for > this > > proposal > > > > I would still love to see this implemented as a general practice (new > > API versions being considered unstable until officially stabilized), > > but I'm willing to concede that we just try it out for a release cycle > > (specifically for the 3 breaking changes we have planned) before > > having a retrospective to determine if it was a successful practice or > > not and whether or not we should continue with it. Even if we choose > > not to continue the practice, we'll still have saved ourselves from > > the pain of having yet another major TO API version. > > > > - Rawlin > > >
