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 > > > > > > > > >
