If we want our TC version to match our API version, it looks like we would rev the version every TC minor release, even though it may not contain breaking changes?
> On Oct 19, 2017, at 2:54 PM, Jeremy Mitchell <[email protected]> wrote: > > With the Golang API rewrite, we were not planning to break any APIs but > rather simply port them to Golang thus we did not see the need to rev the > API version from 1.2. However, maybe this is good opportunity to get our > API version inline with the TC version. > > So, my thought is that our Golang API's look like this: > > GET /api/v2.2/foos <-- this would return foos served by golang because > we've ported this endpoint > GET /api/v2.2/bars <-- this would return a 404 served by golang because > we've have NOT yet ported this endpoint > > and our perl apis are still acessible in 1.2 > > GET /api/1.2/foos <-- this would return foos served by perl > GET /api/1.2/bars <-- this would return bars served by perl > > This has 3 benefits: > > 1. by revving the version, it signals the community that something has > actually changed in our API and in this case, the change may simply be the > fact that we now have nifty golang implemented APIs that you might want to > explore. > 2. it provides the ability to stay on the perl apis by specifying 1.2 if > that is what you want to do. maybe you are not much of a risk taker... > 3. it does actually provide license to break the new golang apis if needed > (to make them better) because the major version has incremented. it's nice > to have that option if needed. > > Also, going forward, I propose the TO API version follows in lockstep with > the TC version...which means the minor version will keep incrementing...GET > /api/v2.2/foos...GET /api/v2.3/foos..which means functionality can be added > to the API "in a backwards-compatible manner" > > Remember, at some point TO will only be the TO API so why wouldn't this > component follow the versioning that the other components do? Just my > thoughts. > > Jeremy > > On Tue, Oct 17, 2017 at 12:02 PM, Robert Butts <[email protected]> > wrote: > >> I'm fully +1 on Semantic Versioning. We discussed it briefly on the list a >> long time ago, but we haven't really been doing it. >> >> That said, versioning requires a lot of code/work that simply doesn't exist >> today. That's the reason we haven't been doing it properly. >> >> The Go Traffic Ops has Semantic Versioning built-in to the Routing, but >> Perl support is close to nil. Perl currently has an easy way to say >> "include all the routes in this version number", But there's no way to say >> "this route is 1.2 only, and this route is 1.3 only" -- we'd have to >> duplicate TrafficOpsRoutes.pm, with only a few lines changed, and likewise >> duplicate changed functions. It needs a framework. Or we could just wait >> until Perl goes away. >> >> That said, Go, especially the client, doesn't completely support Minor >> Versions like it should, either. Consider adding a new field to Delivery >> Services. Per Semantic Versioning, that field MUST not be returned by the >> old version `GET`, and MUST not be set if passed by a `POST`. The Go server >> supports that in the Routing, via different endpoints, but there's no >> Struct framework or pattern. And the client completely doesn't support it. >> In Go, we probably need a set of anonymously-nested structs, `type >> DeliveryServices12 struct { Foo int }; type DeliveryServices13 struct >> {DeliveryServices12; Bar string}`. But that simply doesn't exist today, and >> will take development time to write. >> >> Option 2: Absolute Versioning. Instead of Semantic Versioning, we could >> have a single version, and break compatibility with each new version. So, >> all new features (breaking or not) would go in a new version, and all >> clients must check the version, and refuse to operate on a different >> version. So you'd be required to have a client version matching the server >> version; users are not allowed to talk to new servers with old clients. >> >> Option 3: No Versioning. We get rid of the version number. Endpoints are at >> `/api/foo`. Over the last few years, we have _repeatedly_ broken the API >> for the same version. A 1.2 client from three years ago will fail >> catastrophically if connected to a Traffic Ops serving `/api/1.2` today. In >> practice, as we've been developing, we have no version, the version number >> is meaningless and confusing. If we're going to continue breaking >> compatibility without updating the version number, we should get rid of it. >> Then at least the version itself won't be confusing and painful. >> >> What's the consensus here? Does everyone agree with Semantic Versioning? Do >> we want to commit to requiring it? Is there a consensus? Or should we take >> a vote, whether to require Semantic Versioning, Absolute Versioning, or No >> Version? >> >> >> On Thu, Oct 12, 2017 at 7:39 AM, Dave Neuman <[email protected]> wrote: >> >>> Traffic ops currently does not handle versioning very well. I think we >> do >>> support 1.1 and 1.2 versions of the API, but I think there are only a few >>> (maybe asns and deliveryservices) that are actually different. >>> Versioning is something we look to improve as we move to the golang >> version >>> of the API. >>> >>> On Thu, Oct 12, 2017 at 6:50 AM, Eric Friedrich (efriedri) < >>> [email protected]> wrote: >>> >>>> Does Traffic Ops expose a semantic version number as part of its API? >>>> >>>> http://semver.org/ >>>> "Given a version number MAJOR.MINOR.PATCH, increment the: >>>> >>>> 1. MAJOR version when you make incompatible API changes, >>>> 2. MINOR version when you add functionality in a >> backwards-compatible >>>> manner, and >>>> 3. PATCH version when you make backwards-compatible bug fixes. >>>> >>>> “ >>>> >>>> We have some TO clients and would like to improve their backwards >>>> compatibility. Without this version number, it is not easy to determine >>>> which fields in the API are supported by any given version. >>>> >>>> Thanks, >>>> Eric >>>> >>>> >>> >>
