For anyone interested in what the resulting code would look like for
my TO API minor versioning proposal, I prototyped a new `foos`
endpoint that supports several different minor versions (as if the
endpoint had seen minor changes across several different releases of
Traffic Control -- not that we
+1
On Tue, Apr 30, 2019 at 1:00 PM Dave Neuman wrote:
> +1 to Rawlin's latest proposal.
> If we can get consensus then let's close the PRs for previous solutions and
> move forward with this one.
>
> Thanks,
> Dave
>
>
> On Fri, Apr 26, 2019 at 3:58 PM Rawlin Peters
> wrote:
>
> > On Wed, Apr 2
+1 to Rawlin's latest proposal.
If we can get consensus then let's close the PRs for previous solutions and
move forward with this one.
Thanks,
Dave
On Fri, Apr 26, 2019 at 3:58 PM Rawlin Peters
wrote:
> On Wed, Apr 24, 2019 at 10:53 AM Robert Butts wrote:
> > We might even be able to do a li
On Wed, Apr 24, 2019 at 10:53 AM Robert Butts wrote:
> We might even be able to do a little better than that, and only have one
> handler, no separate versions in the routes/handlers. So, the route would
> look something like:
>
> func Update(w http.ResponseWriter, r *http.Request) {
> inf, userEr
of ways to handle that without worrying about versioning
> > strategy.
> >
> > > We can't instantly
> > upgrade every component of the CDN
> >
> > oh yeah...
> >
> > Fr
gt; > I still prefer converting to PATCH instead of POST moving forward
> >
> > You mean "PATCH instead of PUT"? I'd like to see us support both,
> > personally, but I still see the the data-loss thing as a separate issue.
> > There are lots of wa
h yeah...
> ____
> From: Rawlin Peters
> Sent: Tuesday, April 23, 2019 1:41 PM
> To: dev@trafficcontrol.apache.org
> Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
>
> On Tue, Apr 23, 2019 at 1:
versioning
> strategy.
>
> > We can't instantly
> upgrade every component of the CDN
>
> oh yeah...
> ____
> From: Rawlin Peters
> Sent: Tuesday, April 23, 2019 1:41 PM
> To: dev@trafficcontrol.apache.org
> Subject: R
ng strategy.
> We can't instantly
upgrade every component of the CDN
oh yeah...
From: Rawlin Peters
Sent: Tuesday, April 23, 2019 1:41 PM
To: dev@trafficcontrol.apache.org
Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
On Tue, Ap
On Tue, Apr 23, 2019 at 1:04 PM Gray, Jonathan
wrote:
>
> As a developer it sounds just as messy as the other solutions, but it may be
> workable. If you internally are chaining the object mashalling and db
> queries, how do you handle new mandatory fields that have no default? I
> still pref
> > > > > with the semantic versioning approach we are enabling
clients
> > to be
> > > > > > lazy about updating their _unknown and custom_ client code
at
> > the cost
> > > > > > of developer product
r of whether this approach is simple
> > enough for us
> > > > > > to continue with semantic versioning. It's a matter of whether
> > we want
> > > > > > to have to continue to deal with older clients that prevent us
> > from
> > > > > > making certain changes in the API because w
p the pacing of
> major releases, but I don't see that as a big problem either. Because of
> slow release cadence, a lot of people are building things against master
> instead of stable releases, which is part of the problem as I see it.
>
> ___
blem either. Because of slow release cadence, a lot
of people are building things against master instead of stable releases, which
is part of the problem as I see it.
From: Gray, Jonathan
Sent: Friday, April 19, 2019 8:37 PM
To: dev@trafficcontrol.apache
gt; > >If you're deploying the head of master, API minor versioning
doesn't
> > > > > really solve that consistent API problem unless we start
saying that
> > > > > every single new field added to an API endpoint is a new
minor version
> &
ely to blame for
> our
> > > > > lack of progress on our migration to Golang, but it's one more
> thing
> > > > > that is slowing us down and definitely hasn't helped improve
> progress.
> > > > > --
> > > > > Thanks,
> > > > > Jeff
> > > > &
proposed does. The
> > only
> > > > > difference from not versioning, is that fields will have a new
> > tag,
> > > > > "NewField *int `json:"newField, db:"new_field", api:"1.5"`, and
> > endpoints
> > > > > will have an extra lin
7;re deploying the head of master, API minor versioning
> doesn't
> > > > > really solve that consistent API problem unless we start saying
> that
> > > > > every single new field added to an API endpoint is a new minor
> version
> > &g
t; at the
> > > cost
> > > > > of developer productivity and progress on our project.
> > > > >
> > > > > I'm not saying that semantic versioning is solely to blame
> > for our
> > > > > lack of
1.5"`, and
> > endpoints
> > > > > will have an extra line, "json := api.NewJSON("1.4")".
> That's
> > it. That
> > > > > would be the entirety of the API code (or very nearly,
> Rawlin is
>
gt; > > > > >If you're deploying the head of master, API minor versioning
> doesn't
> > > > > really solve that consistent API problem unless we start
> saying that
> > > > > every single new field added to an
@comcast.com>
> > > > wrote:
> > > >
> > > > > >If you're deploying the head of master, API minor versioning
> doesn't
> > > > > really solve that consistent API problem unless we start
> saying that
> > > > >
mes in a day.
> > > >
> > > > >If someone goes
> > > > to the trouble to understand how our APIs work and develops their
own
> > > > client code, why is it so unreasonable to expect them to also
> > > > understand ho
;
> > > > wrote:
> > > >
> > > > > >If you're deploying the head of master, API minor versioning
> doesn't
> > > > > really solve that consistent API problem unless we start saying
> that
> > > > > every single new field added to an API endpoint
t; that changes potentially a dozen times in a day.
> > > >
> > > > >If someone goes
> > > > to the trouble to understand how our APIs work and develops their own
> > > > client code, why is it so unreasonable to expect them to also
> >
omments
> > > > and
> > > > > boilerplate.
> > > > >
> > > > > How do you feel about that? Would that be simple enough?
> > > > >
> > > > >
> > > > > On Thu, Apr 18, 2019 at 3:15 PM Fieck, Brennan <
> >
> wrote:
> > > >
> > > > > >If you're deploying the head of master, API minor versioning
> doesn't
> > > > > really solve that consistent API problem unless we start saying
> that
> > > > > every single new field added to an
zen times in a day.
> > > >
> > > > >If someone goes
> > > > to the trouble to understand how our APIs work and develops their own
> > > > client code, why is it so unreasonable to expect them to also
> > > > understand how an update of Traffic
> > I agree with this so hard. I'd love to just say "TO vX uses the vX API,
> > > major changes to the biggest TC component are a major change to TC",
> but at
> > > any given time we support and provide bug/security fixes for versions
> X and
> > &
bug/security fixes for versions X and
> > X-1. I'll settle for eliminating minor API versions, though. Developers can
> > be expected to understand that changing versions of a thing can change
> > aspects of the ways in which you can interact with said thing. A major
> > ve
ixes for versions X
> and
> > X-1. I'll settle for eliminating minor API versions, though. Developers
> can
> > be expected to understand that changing versions of a thing can change
> > aspects of the ways in which you can interact with said thing. A major
> > version change means major changes and a
: Robert Butts
Sent: Thursday, April 18, 2019 3:22 PM
To: dev@trafficcontrol.apache.org
Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
>This is about simplifying our code in the API
@jeff.elsloo That's what the tag solution I proposed does. The only
difference from not ver
nges and a minor version change means minor
> changes.
> ____
> From: Jeff Elsloo
> Sent: Thursday, April 18, 2019 2:59 PM
> To: dev@trafficcontrol.apache.org
> Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
>
> > Maybe I'
A major version change means major
changes and a minor version change means minor changes.
From: Jeff Elsloo
Sent: Thursday, April 18, 2019 2:59 PM
To: dev@trafficcontrol.apache.org
Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
> Maybe
On Thu, Apr 18, 2019 at 11:37 AM Robert Butts wrote:
> Something doesn't cease to be an issue, because you redefine it to be the
> user's fault. It's exactly the same issue, removing minor versions just
> makes it much more difficult to debug.
It's not the user's fault, it's the faulty client's f
> Maybe I'm the only one, and everyone else can vote me out, but I don't see
that as acceptable. It's our responsibility as developers to create a safe
user experience, and unacceptable to declare real bugs to be the user's
fault for not using it right. When our Production CDN goes down because an
If you're deploying the head of master, API minor versioning doesn't
really solve that consistent API problem unless we start saying that
every single new field added to an API endpoint is a new minor version
instead of just incrementing an API's version once per TC release.
Even if we do minor ve
That's great! Thank you!
On 4/18/19 1:51 PM, Robert Butts wrote:
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 Per
>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 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 wan
>Without minor versions, #3497 would not even an issue. It's only an issue
because of the attempt to support minor versioning.
That's simply not true. It's exactly the same issue. Removing minor
versioning just hides the issue. You have declared:
>only certain clients that don't handle new unknow
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
> 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
> fiel
the API version is confusingly behind by
> > > about 2
> > > > > major revisions. It should just be
> > > > > >>>> the same for simplicity's sake.
> > > > > >>>>
> > > > > >>>>
; > redesigned.
> > > > >>>>
> > > > >>>> * The API Needs to be Redesigned *
> > > > >>>> I'm going to go down this rabbit hole for a second, if you're
> > > > already con
ndset"
> that
> > > plagues our oldest endpoints. The
> > > >>>> "Mojolicious Mindset" refers to the use of URL path
> > > fragments as request parameters, e.g.
> > > >>>> '/users/{{ID}}&#
gt; instead
> > of one, and it means two lines in the
> > >>>> route definitions, and it means two seperate handlers
> > instead of one (albiet a more complex
> > >>>> one).
> > >>>> Consider also that we have all of the following
> > endpoints
tabase,
and is therefore free from
some of the constraints that bind a database.
The way things are now, in order to e.g. create a server definition
I must make several
preliminary requests to determine the integral, unique,
non-deterministic identifiers of other
t;to a lack of good documentation - so developers
> aren't aware of the endpoints available to them
> > >>>>>>- and partly because of the "Mojolicious Mindset"
> that plagues our oldest endpoints. The
> > >>>>>> &quo
sers' and
> >>>>>>'/users/{{ID}}' means documenting two endpoints instead
of one, and it means two lines in the
> >>>>>>route definitions, and it means two seperate handlers
instead of one (albiet a more complex
> >>>>>>
ur in
> >>>>>> multiple endpoints. This is due in part
> >>>>>>to a lack of good documentation - so developers aren't
> >>>>>> aware of the endpoints available to them
> >>>>>>- and partly bec
some of the constraints that bind a database.
The way things are now, in order to e.g. create a server definition
I must make several
preliminary requests to determine the integral, unique,
non-deterministic identifiers of other
objects. I think we all agree that
pdate them by
>>>> creating an alternative representation with the same
identifiying information) but is instead
>>>> used as the primary "edit this" method. `POST` is for
processing entities in a data payload, but
>>>&g
> >>>> Consider also that we have all of the following endpoints for
> >>>> manipulating Cache Groups:
> >>>>
> >>>> * /api/1.x/cachegroup/{{parameter ID}}/parameter
> >>>> * /api/1.x/cachegroup_fallbacks
> &
* /api/1.x/cachegroups/{{parameter
> ID}}/parameter_available
> >>>> * /api/1.x/cachegroups_trimmed
> >>>>
> >>>> These could all be collapsed neatly into one or two
> endpoints, but were instead implemented
>
creating an alternative representation with the same
identifiying information) but is instead
>>>> used as the primary "edit this" method. `POST` is for
processing entities in a data payload, but
>>>> is instead used for object creation.
r
database is structured. But
that's part of the problem - an API needn't replicate the database,
and is therefore free from
some of the constraints that bind a database.
The way things are now, in order to e.g. create a server definition I
must make several
ailed us. `PUT` should be used to _create_
> >> objects (or possibly update them by
> >> creating an alternative representation with the same identifiying
> >> information) but is instead
> >> used as the primary "edit this" method. `P
ver definition I
must make several
preliminary requests to determine the integral, unique,
non-deterministic identifiers of other
objects. I think we all agree that ideally these integral IDs would
have no part in the output
of the API, and many people I've spoken to wo
Hi all,
Looks like we had a fairly lively discussion here, and I'm late to the
party. I've been contemplating everyone's positions, but I agree with
the points Rawlin laid out in the initial email. We have been doing a
lot of great work on the API front, but after observing much of the
development
I was referring to Brennan's proposal:
> Sure, but TO API v1 would only be implemented by TO v1 and TO API v2 only
> implemented by TO v2.
I agree about the deprecation overlap. We need to support both API v1
and v2 at the same time for at least one major release.
- Rawlin
On Thu, Feb 14, 2019
> From: Rawlin Peters
> Sent: Thursday, February 14, 2019 12:59 PM
> To: dev@trafficcontrol.apache.org
> Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
>
> Scripts written against TO API v1 should always work against TO API
> v1, n
TO API v1 would only be implemented by TO v1 and TO API v2 only
> implemented by TO v2.
>
> From: Rawlin Peters
> Sent: Thursday, February 14, 2019 12:59 PM
> To: dev@trafficcontrol.apache.org
> Subject: Re: [EXTERNAL] Re: Traffic Ops
_
From: Rawlin Peters
Sent: Thursday, February 14, 2019 12:59 PM
To: dev@trafficcontrol.apache.org
Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
Scripts written against TO API v1 should always work against TO API
v1, no matter if Traffic Ops is v2.2, v3.0, or
Sure, but TO API v1 would only be implemented by TO v1 and TO API v2 only
implemented by TO v2.
From: Rawlin Peters
Sent: Thursday, February 14, 2019 12:59 PM
To: dev@trafficcontrol.apache.org
Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
scripts to
> work with v2.
>
> From: Rawlin Peters
> Sent: Thursday, February 14, 2019 10:53 AM
> To: dev@trafficcontrol.apache.org
> Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
>
> There is a lot of stuff to digest here, and I ag
work with v2.
From: Rawlin Peters
Sent: Thursday, February 14, 2019 10:53 AM
To: dev@trafficcontrol.apache.org
Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
There is a lot of stuff to digest here, and I agree that the v1 API is
desp
th v2.
From: Rawlin Peters
Sent: Thursday, February 14, 2019 10:53 AM
To: dev@trafficcontrol.apache.org
Subject: Re: [EXTERNAL] Re: Traffic Ops API versioning issues
There is a lot of stuff to digest here, and I agree that the v1 API is
desperately in need of a go
oblem it solves is an emergent property
> of of API problem #1 above.
> With fewer endpoints we'd have much more specific handling, and the
> need for and advantages of
> the "CRUDER" will vanish.
>
> 3. Needing multiple queries to obtain a single piece
Unfortunately I missed your graphQL presentation at the summit, but I
do think that warrants some serious consideration as well. I don't
know if we'd be able to do _only_ graphQL for the TO API at this
point, but we should consider running an experimental graphQL server
side-by-side to vet it. Once
On Wed, Feb 13, 2019 at 6:12 PM Robert Butts wrote:
>
> >It doesn't seem like the idea of full TO API SemVer was ever fully
> discussed and voted on
>
> >Since it seems like we never truly committed to SemVer with minor versions
> for the TO API
>
> There was consensus:
> https://lists.apache.org/
I'm still digesting this for a better response. If you're considering what
both the big next thing for the API is and at the same time are considering
linking it to the ATC release, I'll just put this back on the radar
https://github.com/apache/trafficcontrol/issues/2630. There was good
discu
> The "CRUDER" is a great innovation, to be sure, as it saves us quite a bit of
> time and prevents
duplicating code, but the problem it solves is an emergent property of
of API problem #1 above.
> With fewer endpoints we'd have much more specific handling, and the need for
> and advanta
I'd take it further, though in my opinion it shouldn't be done until we're
ready to do away with Perl entirely.
I've been working on this draft for a while now, and I sort of wanted to wait
until I made a wiki page for a proposed API v2 spec before sending it, but what
the heck. The conversation
r to e.g. create a server definition I
must make several
preliminary requests to determine the integral, unique,
non-deterministic identifiers of other
objects. I think we all agree that ideally these integral IDs would
have no part in the output
of the API, and many peopl
>It doesn't seem like the idea of full TO API SemVer was ever fully
discussed and voted on
>Since it seems like we never truly committed to SemVer with minor versions
for the TO API
There was consensus:
https://lists.apache.org/thread.html/8f8a850c68424021a0fe06967894383a24e463f1b0cee4d652d04590@
On Wed, Feb 13, 2019 at 1:20 PM Gray, Jonathan
wrote:
>
> I'm +1 on keeping full API SemVer.
> On 2/13/19, 12:16 PM, "Robert Butts" wrote:
>
> We would be abandoning Semantic Versioning.
This is why I wanted to open this up for broader discussion within the
community. It doesn't seem like
I'm +1 on keeping full API SemVer. It allows an API consumer I have a stronger
contract around the semantics of what we should be produce and consume. The
piece that's still missing to me is issue #2872 so as a client I can safely
verify my API contract is still valid after TO has been upgrade
78 matches
Mail list logo
