>When API version 1.3 came out, why could I not call 1.3 for every API route even if the route didn't change?
That was a Perl mistake, and a bug. >Why not point the 1.3 to the 1.1 for example? Go does, and we manually do in Perl now, too. On Thu, Apr 18, 2019 at 11:47 AM Hank Beatty <hbea...@apache.org> wrote: > +1 > > I agree with Jonathan but, I ran into my issue going from one TC release > to the next. I want to have the API not break as long as that API is > supported. > > I also don't want to have to use multiple versions of the API in my > script unless I absolutely have to for some reason on my end. I want to > be able to define the API version at the top of my script and use that > version all the way through my script. > > I don't really care if more fields are returned. I may not be using all > of the fields anyway. I do care if some of the fields disappear but, the > API version I am using is supposed to not have changed. > > I guess what I am realizing is my issues with the API may not be about > how it is versioned at all but, about testing to make sure the supported > versions have not changed in the way they work. I brought up versioning > because it seemed that would help with the breaking changes issue. > > There used to be a matrix of the API routes (that I can't seem to find > now). When API version 1.3 came out, why could I not call 1.3 for every > API route even if the route didn't change? Why not point the 1.3 to the > 1.1 for example? > > Perhaps part of the issue is not deprecating things fast enough and not > incrementing the major version fast enough? If we release a new major > version of TC every 6 mos. as we are trying for but, not always > succeeding, we could deprecate faster and scripts would be supported for > a year. If we could get to a point where we could support a 2 major > release versions of TC this would mean a script would be supported for 2 > years. > > Which brings me back to my original thoughts on API versioning: > > 1. The URL for the API should follow the TC major version (e.g. > http://.../api/v3/...) > 2. TC 3.x.x would support v2 (with a warning message that it is > obsolete) and v3 of the API. > 3. TC 4.x.x would support v3 (with a warning message that it is > obsolete) and v4 of the API. > 4. A user of the API should not have to call v1.2, v1.3, and v1.4 in the > same script. This would be taken care of with 1, 2, and 3 above. > 5. In the documentation, define "backward compatible" as new fields will > be introduced within a major version and will be presented in a GET but, > not available for a POST (and specify a default in the documentation). > 6. If a user really wants to know the specific version (x.x.x) of the > API there should be an API route (e.g. https://.../api/v3/version). > > I changed 5 a bit from my original thoughts. > > I am not helping to develop the API, unfortunately. This is what I see > as a user of the API. > > -Hank > > On 4/18/19 12:37 PM, Gray, Jonathan wrote: > > At the end of the day, what I want is a consistent API that I can code > against in the head of master that's treated like a contract. As an API > user outside of the ATC repo it's incredibly frustrating to have my stuff > break all the time. It basically encourages never developing using the > latest API versions (regardless of how they're defined and even then things > still break retroactively) or a non-official OSS release alltogether. It's > a catch22 to be forced to either not vendor the go/python/bash libraries > which leads to constant develop/recompile/deploys in lockstep with ATC or > vendor and still have to do these things when stuff breaks anyway in the > API. Really debating the native client libraries at all is just a red > herring because the root issue is the HTTP API itself which is the real > thing to care about since not all integrations use one of the client > libraries, nor can be forced to do so, and may require a rigid API > definition. > > > > Jonathan G > > > > > > On 4/18/19, 10:12 AM, "Rawlin Peters" <rawlin.pet...@gmail.com> wrote: > > > > > The UPDATE statements need modified to fix #3497 even if we get > rid of > > > versioning. Unless we decide to permanently break all clients > older than > > > the newest server field, with every new server upgrade. The only > other > > > option is to fix the updates. Unless you know of a way to fix > missing > > > fields without changing the update statements, that I'm not > seeing? > > > > By removing minor versioning, only certain clients that don't handle > > new unknown fields would potentially be broken, and I believe only > the > > TO Go client has that problem in our repo. However, the TO Go client > > happens to use the same Go structs as traffic_ops_golang, so > whenever > > new fields are added to the API, all the client has to do is > recompile > > with the up-to-date structs. Unless we made breaking changes to the > > client, in most cases all that would be needed for those clients is > a > > recompile. Traffic Portal, the Python TO client, and I'm pretty sure > > the Java TO client all handle unknown fields properly. > > > > Without minor versions, #3497 would not even an issue. It's only an > > issue because of the attempt to support minor versioning. If we just > > support the major version, all client requests would be treated as > v1, > > and there would only ever be one SQL UPDATE statement per major > > version. We wouldn't need to "upgrade" 1.2 requests into a 1.4 > struct > > (thus preventing the bug in #3497) by selecting and inserting all > 1.4 > > values from the DB into the struct before handling the request or > > dynamically generating the SQL UPDATE statement to use based on the > > requested minor version. > > > > > So, this solution actually gives us > > > this bug fix almost for free. All that's required is another > small function > > > to iterate over the object fields to create the update query. > It's by far > > > the easiest and simplest fix for #3497; unless we also > permanently break > > > all older clients on every server upgrade along with the minor > version > > > removal. > > > > Switching all the endpoints over to your "apiver" library would not > be > > as trivial to implement or remove as you make it sound. It would > > require lots of added API test coverage and a non-trivial amount of > > code modifications to all API endpoints. Certain UPDATE queries > might > > be easy to generate from a given struct if the struct only uses a > > single table, but I don't think something like that would work for a > > field like `cachegroup.LocalizationMethods` which doesn't come from > > the cachegroups table and is updated separately from the rest of the > > cachegroup fields. > > > > - Rawlin > > > > >
