Foreman API versioning

Development
1

I'm looking for feedback on the better way to maintain API versioning in Foreman. Some options include

  1. Copy all controllers and views from /v1 to /v2 directories
  2. V2 controllers inherit v1 and render /v1 views (if not changed) or /v2 views (if changed)
  3. Use routes.rb for directing to either /v1 to /v2 for each controller#action. Only create v2 if there are changes.

Thanks for your feedback.

Joseph

2

Hi,

For me 3. is the favorite, for this reasons:

a. reduction of code duplicities
b. it's immediately visible, what was added in the v2
c. the argument against controller inheritance might be, that it doesn't
conform to the substitutability principle [1], although I don't like
theorizing about OO very much. Let's make an assumption there will be yet
another version of the API (might happen), where this might cause some
troubles as well.

The counter-argument against 2) and 3) might be what happens, when we
obsolete the version one API. Personally I would leave the copying of the
code till that time.

– Ivan

··· On Monday, 10 December 2012 09:40:51 UTC+1, Joseph Magen wrote: > > I'm looking for feedback on the better way to maintain API versioning in > Foreman. Some options include > > 1) Copy all controllers and views from /v1 to /v2 directories > 2) V2 controllers inherit v1 and render /v1 views (if not changed) or /v2 > views (if changed) > 3) Use routes.rb for directing to either /v1 to /v2 for each > controller#action. Only create v2 if there are changes. > > Thanks for your feedback. > > Joseph > >
3

>
>
>
>>
>> I'm looking for feedback on the better way to maintain API versioning in
>> Foreman. Some options include
>>
>> 1) Copy all controllers and views from /v1 to /v2 directories
>> 2) V2 controllers inherit v1 and render /v1 views (if not changed) or
>> /v2 views (if changed)
>> 3) Use routes.rb for directing to either /v1 to /v2 for each
>> controller#action. Only create v2 if there are changes.
>>
>> Thanks for your feedback.
>>
>> Joseph
>>
>>
> Hi,
>
> For me 3. is the favorite, for this reasons:
>
> a. reduction of code duplicities
> b. it's immediately visible, what was added in the v2
> c. the argument against controller inheritance might be, that it doesn't
> conform to the substitutability principle [1], although I don't like
> theorizing about OO very much. Let's make an assumption there will be yet
> another version of the API (might happen), where this might cause some
> troubles as well.
>
> The counter-argument against 2) and 3) might be what happens, when we
> obsolete the version one API. Personally I would leave the copying of the
> code till that time.
>
>
And I forgot the link, although it's not so important:

[1] - http://en.wikipedia.org/wiki/Liskov_substitution_principle

– Ivan

··· On Monday, 10 December 2012 10:10:14 UTC+1, iNecas wrote: > On Monday, 10 December 2012 09:40:51 UTC+1, Joseph Magen wrote: >
4

I suspect that if we are going to be making a lot of changes long
term, that #1 is probably the most flexible? But that is my guess.
What are the pros and cons of each method? Also how maintainable will
these various methods be if and when we have 5+ different API versions
we are supporting? (IE: Let's think of the long term).

Thanks,
-Brian

··· On Mon, Dec 10, 2012 at 3:40 AM, Joseph Magen wrote: > I'm looking for feedback on the better way to maintain API versioning in Foreman. Some options include > > 1) Copy all controllers and views from /v1 to /v2 directories > 2) V2 controllers inherit v1 and render /v1 views (if not changed) or /v2 views (if changed) > 3) Use routes.rb for directing to either /v1 to /v2 for each controller#action. Only create v2 if there are changes. > > Thanks for your feedback. > > Joseph > > >
5

Hi Brian,

#1 is the most flexible but it also requires the most maintenance. Every bug fix in v1 will also need to be copied to v2 (and v3 if it exists). And also the tests in v1, v2, v3 … would also have to be modified.

My hunch is to do #3 which seems to be the most DRY.
/v1 - all controllers/views
/v2 - only add new ones

v2.rb routes file points to /v1 for all controllers#actions that are NOT new.

In either case, if there changes in v2, there will be a new controller and view under /v2. So, I guess the question is how to maintain controllers / views that don't change. It may be intuitive that a v4 route puts to a v1 controller if v1 hasn't changed.

Joseph

··· ----- Original Message ----- From: "Brian Gupta" To: foreman-dev@googlegroups.com Cc: katello-internal@redhat.com Sent: Monday, December 10, 2012 10:49:36 AM Subject: Re: [foreman-dev] Foreman API versioning

I suspect that if we are going to be making a lot of changes long
term, that #1 is probably the most flexible? But that is my guess.
What are the pros and cons of each method? Also how maintainable will
these various methods be if and when we have 5+ different API versions
we are supporting? (IE: Let’s think of the long term).

Thanks,
-Brian

On Mon, Dec 10, 2012 at 3:40 AM, Joseph Magen jmagen@redhat.com wrote:

I’m looking for feedback on the better way to maintain API versioning in Foreman. Some options include

  1. Copy all controllers and views from /v1 to /v2 directories
  2. V2 controllers inherit v1 and render /v1 views (if not changed) or /v2 views (if changed)
  3. Use routes.rb for directing to either /v1 to /v2 for each controller#action. Only create v2 if there are changes.

Thanks for your feedback.

Joseph

6

I may have missed this, but is there a rule as to what will constitute a
v3? Will it be:

  1. A bug in v2.
  2. Adding a new field to an axisting v2 model
  3. Adding a new model?
  4. Time passes.

– bk

··· On 12/10/2012 04:09 AM, Joseph Magen wrote: > Hi Brian, > > #1 is the most flexible but it also requires the most maintenance. Every bug fix in v1 will also need to be copied to v2 (and v3 if it exists). And also the tests in v1, v2, v3 .. would also have to be modified. > > My hunch is to do #3 which seems to be the most DRY. > /v1 - all controllers/views > /v2 - only add new ones > > v2.rb routes file points to /v1 for all controllers#actions that are NOT new. > > In either case, if there changes in v2, there will be a new controller and view under /v2. So, I guess the question is how to maintain controllers / views that don't change. It may be intuitive that a v4 route puts to a v1 controller if v1 hasn't changed. > > > Joseph > > > ----- Original Message ----- > From: "Brian Gupta" > To: foreman-dev@googlegroups.com > Cc: katello-internal@redhat.com > Sent: Monday, December 10, 2012 10:49:36 AM > Subject: Re: [foreman-dev] Foreman API versioning > > I suspect that if we are going to be making a lot of changes long > term, that #1 is probably the most flexible? But that is my guess. > What are the pros and cons of each method? Also how maintainable will > these various methods be if and when we have 5+ different API versions > we are supporting? (IE: Let's think of the long term). > > Thanks, > -Brian > > On Mon, Dec 10, 2012 at 3:40 AM, Joseph Magen wrote: >> I'm looking for feedback on the better way to maintain API versioning in Foreman. Some options include >> >> 1) Copy all controllers and views from /v1 to /v2 directories >> 2) V2 controllers inherit v1 and render /v1 views (if not changed) or /v2 views (if changed) >> 3) Use routes.rb for directing to either /v1 to /v2 for each controller#action. Only create v2 if there are changes. >> >> Thanks for your feedback. >> >> Joseph >> >> >>
7

My take is that new controllers (models) and input/response changes (new fields) will be in the next version. Bug fixes will remain in the current version.

··· ----- Original Message ----- From: "Bryan Kearney" To: foreman-dev@googlegroups.com Sent: Monday, December 10, 2012 3:32:45 PM Subject: Re: [foreman-dev] Foreman API versioning

I may have missed this, but is there a rule as to what will constitute a
v3? Will it be:

  1. A bug in v2.
  2. Adding a new field to an axisting v2 model
  3. Adding a new model?
  4. Time passes.

– bk

On 12/10/2012 04:09 AM, Joseph Magen wrote:

Hi Brian,

#1 is the most flexible but it also requires the most maintenance. Every bug fix in v1 will also need to be copied to v2 (and v3 if it exists). And also the tests in v1, v2, v3 … would also have to be modified.

My hunch is to do #3 which seems to be the most DRY.
/v1 - all controllers/views
/v2 - only add new ones

v2.rb routes file points to /v1 for all controllers#actions that are NOT new.

In either case, if there changes in v2, there will be a new controller and view under /v2. So, I guess the question is how to maintain controllers / views that don’t change. It may be intuitive that a v4 route puts to a v1 controller if v1 hasn’t changed.

Joseph

----- Original Message -----
From: “Brian Gupta” brian.gupta@brandorr.com
To: foreman-dev@googlegroups.com
Cc: katello-internal@redhat.com
Sent: Monday, December 10, 2012 10:49:36 AM
Subject: Re: [foreman-dev] Foreman API versioning

I suspect that if we are going to be making a lot of changes long
term, that #1 is probably the most flexible? But that is my guess.
What are the pros and cons of each method? Also how maintainable will
these various methods be if and when we have 5+ different API versions
we are supporting? (IE: Let’s think of the long term).

Thanks,
-Brian

On Mon, Dec 10, 2012 at 3:40 AM, Joseph Magen jmagen@redhat.com wrote:

I’m looking for feedback on the better way to maintain API versioning in Foreman. Some options include

  1. Copy all controllers and views from /v1 to /v2 directories
  2. V2 controllers inherit v1 and render /v1 views (if not changed) or /v2 views (if changed)
  3. Use routes.rb for directing to either /v1 to /v2 for each controller#action. Only create v2 if there are changes.

Thanks for your feedback.

Joseph

8

I had a slightly different take, in that API versions would need a
major version bump only if there were breaking changes that would
cause integrations with existing APIs to fail.

-Brian

··· On Mon, Dec 10, 2012 at 10:33 AM, Joseph Magen wrote: > My take is that new controllers (models) and input/response changes (new fields) will be in the next version. Bug fixes will remain in the current version. > > > ----- Original Message ----- > From: "Bryan Kearney" > To: foreman-dev@googlegroups.com > Sent: Monday, December 10, 2012 3:32:45 PM > Subject: Re: [foreman-dev] Foreman API versioning > > I may have missed this, but is there a rule as to what will constitute a > v3? Will it be: > > 1) A bug in v2. > 2) Adding a new field to an axisting v2 model > 3) Adding a new model? > 4) Time passes. > > -- bk > > > On 12/10/2012 04:09 AM, Joseph Magen wrote: >> Hi Brian, >> >> #1 is the most flexible but it also requires the most maintenance. Every bug fix in v1 will also need to be copied to v2 (and v3 if it exists). And also the tests in v1, v2, v3 .. would also have to be modified. >> >> My hunch is to do #3 which seems to be the most DRY. >> /v1 - all controllers/views >> /v2 - only add new ones >> >> v2.rb routes file points to /v1 for all controllers#actions that are NOT new. >> >> In either case, if there changes in v2, there will be a new controller and view under /v2. So, I guess the question is how to maintain controllers / views that don't change. It may be intuitive that a v4 route puts to a v1 controller if v1 hasn't changed. >> >> >> Joseph >> >> >> ----- Original Message ----- >> From: "Brian Gupta" >> To: foreman-dev@googlegroups.com >> Cc: katello-internal@redhat.com >> Sent: Monday, December 10, 2012 10:49:36 AM >> Subject: Re: [foreman-dev] Foreman API versioning >> >> I suspect that if we are going to be making a lot of changes long >> term, that #1 is probably the most flexible? But that is my guess. >> What are the pros and cons of each method? Also how maintainable will >> these various methods be if and when we have 5+ different API versions >> we are supporting? (IE: Let's think of the long term). >> >> Thanks, >> -Brian >> >> On Mon, Dec 10, 2012 at 3:40 AM, Joseph Magen wrote: >>> I'm looking for feedback on the better way to maintain API versioning in Foreman. Some options include >>> >>> 1) Copy all controllers and views from /v1 to /v2 directories >>> 2) V2 controllers inherit v1 and render /v1 views (if not changed) or /v2 views (if changed) >>> 3) Use routes.rb for directing to either /v1 to /v2 for each controller#action. Only create v2 if there are changes. >>> >>> Thanks for your feedback. >>> >>> Joseph >>> >>> >>>
9

I agree with Brian's take, but I suggest using this approach for going from v2 to v3. Most of v2 will adding nested routes / controllers, not changing v1 functionality. Since adding functionality usually doesn't break anything, it could be added to v1. However, I prefer to add it to v2. Here is what I suggest:

api/v1 - the same (non-exhaustive) functionality as the json responses in the UI controllers, so that integrations are not broken when adding "/api" to the URL.

api/v2 - "exhaustive" functionality so that what users can do through the UI, they can do through the API.

api/v3 - new functionality that breaks v2

··· ----- Original Message ----- From: "Brian Gupta" To: foreman-dev@googlegroups.com Sent: Monday, December 10, 2012 7:46:34 PM Subject: Re: [foreman-dev] Foreman API versioning

I had a slightly different take, in that API versions would need a
major version bump only if there were breaking changes that would
cause integrations with existing APIs to fail.

-Brian

On Mon, Dec 10, 2012 at 10:33 AM, Joseph Magen jmagen@redhat.com wrote:

My take is that new controllers (models) and input/response changes (new fields) will be in the next version. Bug fixes will remain in the current version.

----- Original Message -----
From: “Bryan Kearney” bryan.kearney@gmail.com
To: foreman-dev@googlegroups.com
Sent: Monday, December 10, 2012 3:32:45 PM
Subject: Re: [foreman-dev] Foreman API versioning

I may have missed this, but is there a rule as to what will constitute a
v3? Will it be:

  1. A bug in v2.
  2. Adding a new field to an axisting v2 model
  3. Adding a new model?
  4. Time passes.

– bk

On 12/10/2012 04:09 AM, Joseph Magen wrote:

Hi Brian,

#1 is the most flexible but it also requires the most maintenance. Every bug fix in v1 will also need to be copied to v2 (and v3 if it exists). And also the tests in v1, v2, v3 … would also have to be modified.

My hunch is to do #3 which seems to be the most DRY.
/v1 - all controllers/views
/v2 - only add new ones

v2.rb routes file points to /v1 for all controllers#actions that are NOT new.

In either case, if there changes in v2, there will be a new controller and view under /v2. So, I guess the question is how to maintain controllers / views that don’t change. It may be intuitive that a v4 route puts to a v1 controller if v1 hasn’t changed.

Joseph

----- Original Message -----
From: “Brian Gupta” brian.gupta@brandorr.com
To: foreman-dev@googlegroups.com
Cc: katello-internal@redhat.com
Sent: Monday, December 10, 2012 10:49:36 AM
Subject: Re: [foreman-dev] Foreman API versioning

I suspect that if we are going to be making a lot of changes long
term, that #1 is probably the most flexible? But that is my guess.
What are the pros and cons of each method? Also how maintainable will
these various methods be if and when we have 5+ different API versions
we are supporting? (IE: Let’s think of the long term).

Thanks,
-Brian

On Mon, Dec 10, 2012 at 3:40 AM, Joseph Magen jmagen@redhat.com wrote:

I’m looking for feedback on the better way to maintain API versioning in Foreman. Some options include

  1. Copy all controllers and views from /v1 to /v2 directories
  2. V2 controllers inherit v1 and render /v1 views (if not changed) or /v2 views (if changed)
  3. Use routes.rb for directing to either /v1 to /v2 for each controller#action. Only create v2 if there are changes.

Thanks for your feedback.

Joseph

10

> I agree with Brian's take, but I suggest using this approach for going
> from v2 to v3. Most of v2 will adding nested routes / controllers, not
> changing v1 functionality. Since adding functionality usually doesn't
> break anything, it could be added to v1. However, I prefer to add it to
> v2. Here is what I suggest:
>
> api/v1 - the same (non-exhaustive) functionality as the json responses in
> the UI controllers, so that integrations are not broken when adding "/api"
> to the URL.
>
> api/v2 - "exhaustive" functionality so that what users can do through the
> UI, they can do through the API.
>

I would say that by making v2 exhaustive, you are breaking v1.

Ohad

··· On Tue, Dec 11, 2012 at 9:32 AM, Joseph Magen wrote:

api/v3 - new functionality that breaks v2

----- Original Message -----
From: “Brian Gupta” brian.gupta@brandorr.com
To: foreman-dev@googlegroups.com
Sent: Monday, December 10, 2012 7:46:34 PM
Subject: Re: [foreman-dev] Foreman API versioning

I had a slightly different take, in that API versions would need a
major version bump only if there were breaking changes that would
cause integrations with existing APIs to fail.

-Brian

On Mon, Dec 10, 2012 at 10:33 AM, Joseph Magen jmagen@redhat.com wrote:

My take is that new controllers (models) and input/response changes (new
fields) will be in the next version. Bug fixes will remain in the current
version.

----- Original Message -----
From: “Bryan Kearney” bryan.kearney@gmail.com
To: foreman-dev@googlegroups.com
Sent: Monday, December 10, 2012 3:32:45 PM
Subject: Re: [foreman-dev] Foreman API versioning

I may have missed this, but is there a rule as to what will constitute a
v3? Will it be:

  1. A bug in v2.
  2. Adding a new field to an axisting v2 model
  3. Adding a new model?
  4. Time passes.

– bk

On 12/10/2012 04:09 AM, Joseph Magen wrote:

Hi Brian,

#1 is the most flexible but it also requires the most maintenance.
Every bug fix in v1 will also need to be copied to v2 (and v3 if it
exists). And also the tests in v1, v2, v3 … would also have to be
modified.

My hunch is to do #3 which seems to be the most DRY.
/v1 - all controllers/views
/v2 - only add new ones

v2.rb routes file points to /v1 for all controllers#actions that are
NOT new.

In either case, if there changes in v2, there will be a new controller
and view under /v2. So, I guess the question is how to maintain
controllers / views that don’t change. It may be intuitive that a v4 route
puts to a v1 controller if v1 hasn’t changed.

Joseph

----- Original Message -----
From: “Brian Gupta” brian.gupta@brandorr.com
To: foreman-dev@googlegroups.com
Cc: katello-internal@redhat.com
Sent: Monday, December 10, 2012 10:49:36 AM
Subject: Re: [foreman-dev] Foreman API versioning

I suspect that if we are going to be making a lot of changes long
term, that #1 is probably the most flexible? But that is my guess.
What are the pros and cons of each method? Also how maintainable will
these various methods be if and when we have 5+ different API versions
we are supporting? (IE: Let’s think of the long term).

Thanks,
-Brian

On Mon, Dec 10, 2012 at 3:40 AM, Joseph Magen jmagen@redhat.com > wrote:

I’m looking for feedback on the better way to maintain API versioning
in Foreman. Some options include

  1. Copy all controllers and views from /v1 to /v2 directories
  2. V2 controllers inherit v1 and render /v1 views (if not changed) or
    /v2 views (if changed)
  1. Use routes.rb for directing to either /v1 to /v2 for each
    controller#action. Only create v2 if there are changes.

Thanks for your feedback.

Joseph