TO API Versioning

[Hank Beatty <hb...@apache.org>]

I recently ran into an issue where one of my scripts that uses the TO 
API stopped working correctly. It was failing in such a way that if I 
had not been in there updating something else I never would have known 
it was not working correctly. This failure was due to a change in the TO 
API version 1.2. I wrote the script using version 1.2 and the version 
I'm testing against now is also 1.2.

I would like to suggest that we chose a versioning philosophy for the TO 
API. The site http://semver.org/ offers a good philosophy to follow. 
This also happens to be the one ATS uses.

Let's please choose a versioning philosophy so that issues like the one 
I describe above can be avoided.

Thanks,
Hank

Re: TO API Versioning

[Dave Neuman <ne...@apache.org>]

Maybe this is a topic that we should discuss at the meetup in May?

On Mon, Mar 20, 2017 at 11:20 AM, Hank Beatty <hb...@apache.org> wrote:

> I recently ran into an issue where one of my scripts that uses the TO API
> stopped working correctly. It was failing in such a way that if I had not
> been in there updating something else I never would have known it was not
> working correctly. This failure was due to a change in the TO API version
> 1.2. I wrote the script using version 1.2 and the version I'm testing
> against now is also 1.2.
>
> I would like to suggest that we chose a versioning philosophy for the TO
> API. The site http://semver.org/ offers a good philosophy to follow. This
> also happens to be the one ATS uses.
>
> Let's please choose a versioning philosophy so that issues like the one I
> describe above can be avoided.
>
> Thanks,
> Hank
>

Re: TO API Versioning

[Robert Butts <ro...@gmail.com>]

+1 on Semantic Versioning.

-1 on breaking the existing API again. There's no point versioning if we
make breaking changes without changing the version.


On Fri, Mar 31, 2017 at 2:42 PM, Amir Yeshurun <am...@qwilt.com> wrote:

> +1 for choosing a versioning philosophy
>
> On Mon, Mar 27, 2017 at 5:15 PM Dewayne Richardson <de...@gmail.com>
> wrote:
>
> > Yes, the versioning wasn't consistent because we switched out the
> database
> > to Postgres which had several impacts to the API. The issue with API
> routes
> > being too granular in the versioning is tricky because the consumers of
> the
> > API will need to change as the versions of Traffic Ops moves forward.
> Now
> > that we are on Postgres we plan on a new versioning scheme with /api/v2/*
> > which we will shortly introduce.  The goal with /api/v2 will be to keep
> the
> > response format the same, with the intention of deprecating the /api/1.x
> > routes.
> >
> > Another goal we have is to build an API test tool (now that more CRUD
> > routes are available), which will help with consistency in the API as
> well
> > as help us with regression testing (more to come on this front).
> >
> > -Dewayne
> >
> > On Mon, Mar 20, 2017 at 11:20 AM, Hank Beatty <hb...@apache.org>
> wrote:
> >
> > > I recently ran into an issue where one of my scripts that uses the TO
> API
> > > stopped working correctly. It was failing in such a way that if I had
> not
> > > been in there updating something else I never would have known it was
> not
> > > working correctly. This failure was due to a change in the TO API
> version
> > > 1.2. I wrote the script using version 1.2 and the version I'm testing
> > > against now is also 1.2.
> > >
> > > I would like to suggest that we chose a versioning philosophy for the
> TO
> > > API. The site http://semver.org/ offers a good philosophy to follow.
> > This
> > > also happens to be the one ATS uses.
> > >
> > > Let's please choose a versioning philosophy so that issues like the
> one I
> > > describe above can be avoided.
> > >
> > > Thanks,
> > > Hank
> > >
> >
>

Re: TO API Versioning

[Amir Yeshurun <am...@qwilt.com>]

+1 for choosing a versioning philosophy

On Mon, Mar 27, 2017 at 5:15 PM Dewayne Richardson <de...@gmail.com>
wrote:

> Yes, the versioning wasn't consistent because we switched out the database
> to Postgres which had several impacts to the API. The issue with API routes
> being too granular in the versioning is tricky because the consumers of the
> API will need to change as the versions of Traffic Ops moves forward.  Now
> that we are on Postgres we plan on a new versioning scheme with /api/v2/*
> which we will shortly introduce.  The goal with /api/v2 will be to keep the
> response format the same, with the intention of deprecating the /api/1.x
> routes.
>
> Another goal we have is to build an API test tool (now that more CRUD
> routes are available), which will help with consistency in the API as well
> as help us with regression testing (more to come on this front).
>
> -Dewayne
>
> On Mon, Mar 20, 2017 at 11:20 AM, Hank Beatty <hb...@apache.org> wrote:
>
> > I recently ran into an issue where one of my scripts that uses the TO API
> > stopped working correctly. It was failing in such a way that if I had not
> > been in there updating something else I never would have known it was not
> > working correctly. This failure was due to a change in the TO API version
> > 1.2. I wrote the script using version 1.2 and the version I'm testing
> > against now is also 1.2.
> >
> > I would like to suggest that we chose a versioning philosophy for the TO
> > API. The site http://semver.org/ offers a good philosophy to follow.
> This
> > also happens to be the one ATS uses.
> >
> > Let's please choose a versioning philosophy so that issues like the one I
> > describe above can be avoided.
> >
> > Thanks,
> > Hank
> >
>

Re: TO API Versioning

[Dewayne Richardson <de...@gmail.com>]

Yes, the versioning wasn't consistent because we switched out the database
to Postgres which had several impacts to the API. The issue with API routes
being too granular in the versioning is tricky because the consumers of the
API will need to change as the versions of Traffic Ops moves forward.  Now
that we are on Postgres we plan on a new versioning scheme with /api/v2/*
which we will shortly introduce.  The goal with /api/v2 will be to keep the
response format the same, with the intention of deprecating the /api/1.x
routes.

Another goal we have is to build an API test tool (now that more CRUD
routes are available), which will help with consistency in the API as well
as help us with regression testing (more to come on this front).

-Dewayne

On Mon, Mar 20, 2017 at 11:20 AM, Hank Beatty <hb...@apache.org> wrote:

> I recently ran into an issue where one of my scripts that uses the TO API
> stopped working correctly. It was failing in such a way that if I had not
> been in there updating something else I never would have known it was not
> working correctly. This failure was due to a change in the TO API version
> 1.2. I wrote the script using version 1.2 and the version I'm testing
> against now is also 1.2.
>
> I would like to suggest that we chose a versioning philosophy for the TO
> API. The site http://semver.org/ offers a good philosophy to follow. This
> also happens to be the one ATS uses.
>
> Let's please choose a versioning philosophy so that issues like the one I
> describe above can be avoided.
>
> Thanks,
> Hank
>