I'd probably discourage incompatible changes in v2 at this point because
its use is widespread enough (despite the long-standing experimental
label) that this would be disruptive to many people. Incompatible
changes should probably be made to v3 and we should aim to increment
versions faster next time.
···
On Thu, Jul 10, 2014 at 10:27:27AM +0100, Dominic Cleal wrote:
> I'm resurrecting my suggestion to remove the experimental label and call
> API v2 "stable" for Foreman 1.6, then to change the default in 1.7 to v2
I’d probably discourage incompatible changes in v2 at this point because
its use is widespread enough (despite the long-standing experimental
label) that this would be disruptive to many people. Incompatible
changes should probably be made to v3 and we should aim to increment
versions faster next time.
···
On 07/10/2014 11:27 AM, Dominic Cleal wrote:
> Before 1.5, the following thread proposed changing the _default_ API
> version to v2, but it wasn't resolved:
> https://groups.google.com/forum/#!msg/foreman-dev/uEMN-Bl3o0U/_9T3qpBFN2MJ
>
> I'm resurrecting my suggestion to remove the experimental label and call
> API v2 "stable" for Foreman 1.6, then to change the default in 1.7 to v2
> - tracker filed here with more specifics:
> http://projects.theforeman.org/issues/6562
>
> I'd probably discourage incompatible changes in v2 at this point because
> its use is widespread enough (despite the long-standing experimental
> label) that this would be disruptive to many people. Incompatible
> changes should probably be made to v3 and we should aim to increment
> versions faster next time.
>
My apologies for the late response. It's been on my todo list, to
reply. I am very strongly of the belief that if you allow
"unversioned" access to a REST API, that if an API consumer accesses
that unversioned API, then one should default to the earliest version
of the API. (More specifically, one should not "break" the unversioned
API, if one made the choice to support an unversioned API in the first
place. If API consumers want access to newer features of the API they
must specifically ask for them.)
-Brian
···
On Thu, Jul 10, 2014 at 5:27 AM, Dominic Cleal wrote:
> Before 1.5, the following thread proposed changing the _default_ API
> version to v2, but it wasn't resolved:
> https://groups.google.com/forum/#!msg/foreman-dev/uEMN-Bl3o0U/_9T3qpBFN2MJ
>
> I'm resurrecting my suggestion to remove the experimental label and call
> API v2 "stable" for Foreman 1.6, then to change the default in 1.7 to v2
> - tracker filed here with more specifics:
> http://projects.theforeman.org/issues/6562
>
> I'd probably discourage incompatible changes in v2 at this point because
> its use is widespread enough (despite the long-standing experimental
> label) that this would be disruptive to many people. Incompatible
> changes should probably be made to v3 and we should aim to increment
> versions faster next time.
>
> --
> Dominic Cleal
> Red Hat Engineering
This sounds fair to me, when you say "discourage incompatible changes in v2
at this point" you mean when 1.6 is released, not now, right?
I think if we are going to do this, API v2 should be audited and reviewed
in depth before locking it, also Hammer will need a thorough review to see
what parts of the API are missing for them.
···
On Thu, Jul 10, 2014 at 11:38 AM, Michael Moll wrote:
Hello,
On Thu, Jul 10, 2014 at 10:27:27AM +0100, Dominic Cleal wrote:
I’m resurrecting my suggestion to remove the experimental label and call
API v2 “stable” for Foreman 1.6, then to change the default in 1.7 to v2
I’d probably discourage incompatible changes in v2 at this point because
its use is widespread enough (despite the long-standing experimental
label) that this would be disruptive to many people. Incompatible
changes should probably be made to v3 and we should aim to increment
versions faster next time.
···
On 10/07/14 13:45, Martin Bačovský wrote:
> On 07/10/2014 11:27 AM, Dominic Cleal wrote:
>> Before 1.5, the following thread proposed changing the _default_ API
>> version to v2, but it wasn't resolved:
>> https://groups.google.com/forum/#!msg/foreman-dev/uEMN-Bl3o0U/_9T3qpBFN2MJ
>>
>> I'm resurrecting my suggestion to remove the experimental label and call
>> API v2 "stable" for Foreman 1.6, then to change the default in 1.7 to v2
>> - tracker filed here with more specifics:
>> http://projects.theforeman.org/issues/6562
>>
>> I'd probably discourage incompatible changes in v2 at this point because
>> its use is widespread enough (despite the long-standing experimental
>> label) that this would be disruptive to many people. Incompatible
>> changes should probably be made to v3 and we should aim to increment
>> versions faster next time.
>>
> Would be fix for http://projects.theforeman.org/issues/4181 considered
> "incompatible change"? It should change the API doc (and consequently
> apipie bindings params) to not include the root nodes for PUT and POST.
> The API itself accepts both formats. Hammer should stay unaffected.
Accepting both formats, with and without root nodes, is a bug in my opinion. We should accept the agreed upon format only and neither document nor support the other. (If it just happens to work, that's probably still bad if a customer comes to rely on it.)
···
----- Original Message -----
> On 07/10/2014 11:27 AM, Dominic Cleal wrote:
> > Before 1.5, the following thread proposed changing the _default_ API
> > version to v2, but it wasn't resolved:
> > https://groups.google.com/forum/#!msg/foreman-dev/uEMN-Bl3o0U/_9T3qpBFN2MJ
> >
> > I'm resurrecting my suggestion to remove the experimental label and call
> > API v2 "stable" for Foreman 1.6, then to change the default in 1.7 to v2
> > - tracker filed here with more specifics:
> > http://projects.theforeman.org/issues/6562
> >
> > I'd probably discourage incompatible changes in v2 at this point because
> > its use is widespread enough (despite the long-standing experimental
> > label) that this would be disruptive to many people. Incompatible
> > changes should probably be made to v3 and we should aim to increment
> > versions faster next time.
> >
> Would be fix for http://projects.theforeman.org/issues/4181 considered
> "incompatible change"? It should change the API doc (and consequently
> apipie bindings params) to not include the root nodes for PUT and POST.
> The API itself accepts both formats. Hammer should stay unaffected.
>
> Martin
>
I'm not opposed to doing this - rather, I have very little opinion on
the subject, so it's fine by me.
···
On 22/07/14 03:47, Brian Gupta wrote:
> On Thu, Jul 10, 2014 at 5:27 AM, Dominic Cleal wrote:
>> Before 1.5, the following thread proposed changing the _default_ API
>> version to v2, but it wasn't resolved:
>> https://groups.google.com/forum/#!msg/foreman-dev/uEMN-Bl3o0U/_9T3qpBFN2MJ
>>
>> I'm resurrecting my suggestion to remove the experimental label and call
>> API v2 "stable" for Foreman 1.6, then to change the default in 1.7 to v2
>> - tracker filed here with more specifics:
>> http://projects.theforeman.org/issues/6562
>>
>> I'd probably discourage incompatible changes in v2 at this point because
>> its use is widespread enough (despite the long-standing experimental
>> label) that this would be disruptive to many people. Incompatible
>> changes should probably be made to v3 and we should aim to increment
>> versions faster next time.
>>
>> --
>> Dominic Cleal
>> Red Hat Engineering
>
> My apologies for the late response. It's been on my todo list, to
> reply. I am very strongly of the belief that if you allow
> "unversioned" access to a REST API, that if an API consumer accesses
> that unversioned API, then one should default to the earliest version
> of the API. (More specifically, one should not "break" the unversioned
> API, if one made the choice to support an unversioned API in the first
> place. If API consumers want access to newer features of the API they
> must specifically ask for them.)
···
----- Original Message -----
> From: "Daniel Lobato"
> To: foreman-dev@googlegroups.com
> Sent: Thursday, July 10, 2014 1:28:12 PM
> Subject: Re: [foreman-dev] Change API v2 to stable in Foreman 1.6(?)
>
> This sounds fair to me, when you say "discourage incompatible changes in v2
> at this point" you mean when 1.6 is released, not now, right?
> I think if we are going to do this, API v2 should be audited and reviewed
> in depth before locking it, also Hammer will need a thorough review to see
> what parts of the API are missing for them.
>
>
> On Thu, Jul 10, 2014 at 11:38 AM, Michael Moll wrote:
>
> > Hello,
> >
> > On Thu, Jul 10, 2014 at 10:27:27AM +0100, Dominic Cleal wrote:
> > > I'm resurrecting my suggestion to remove the experimental label and call
> > > API v2 "stable" for Foreman 1.6, then to change the default in 1.7 to v2
> >
> > > I'd probably discourage incompatible changes in v2 at this point because
> > > its use is widespread enough (despite the long-standing experimental
> > > label) that this would be disruptive to many people. Incompatible
> > > changes should probably be made to v3 and we should aim to increment
> > > versions faster next time.
> >
> > +1 to both points.
> >
> > Regards
> > --
> > Michael Moll
> >
> > --
> > You received this message because you are subscribed to the Google Groups
> > "foreman-dev" group.
> > To unsubscribe from this group and stop receiving emails from it, send an
> > email to foreman-dev+unsubscribe@googlegroups.com.
> > For more options, visit https://groups.google.com/d/optout.
> >
>
>
>
> --
> Daniel Lobato
>
> @elobatoss
> blog.daniellobato.me
> daniellobato.me
>
> GPG: http://keys.gnupg.net/pks/lookup?op=get&search=0x7A92D6DD38D6DE30
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
I don't mind to make v3, but I think it would cause maintaining two versions, v2 and v3. For example, let's say we make v3 for Hammer with the 'child nodes' rather than _id and _name.
Then, we want to merge PR #1454 - fixes #5780 - API v2 - RESTful way to add/remove many-to-many association one at a time rather than passing all id's #1454
This is a new non-breaking change, so v2 users will want it, but hammer using v3 will also want it.
One solution is to have v3 controllers inherit from v2, but I purposely avoided this in v2 not to inherit from v1.
Joseph
···
----- Original Message -----
> From: "Dominic Cleal"
> To: foreman-dev@googlegroups.com
> Sent: Thursday, July 10, 2014 2:17:56 PM
> Subject: Re: [foreman-dev] Change API v2 to stable in Foreman 1.6(?)
>
> On 10/07/14 12:10, Joseph Magen wrote:
> > By "incompatible changes" in v2, I assume that you mean not to change *_id
> > and *_name to a child node
> >
> >>
> >> {
> >> "name": "fdev2.sat.lab.tlv.redhat.com",
> >> "id": 394,
> >> "environment_id": 1,
> >> "environment_name": "production",
> >>
> >> becomes this
> >>
> >> {
> >> "name": "fdev2.sat.lab.tlv.redhat.com",
> >> "id": 394,
> >> "environment": {
> >> "name": "production",
> >> "id": 1
> >> },
>
> I don't mean this specifically, I mean any change that would reasonably
> lead to a major break in a client application, such as renaming and
> restructuring fields. This would be an example, yes.
>
> > Alternatively, we could have duplicate data in the response so as not to
> > break anything like this
> >
> >> "name": "fdev2.sat.lab.tlv.redhat.com",
> >> "id": 394,
> >> "environment_id": 1,
> >> "environment_name": "production",
> >> "environment": {
> >> "name": "production",
> >> "id": 1
> >> },
> >
> > What do you suggest?
>
> That seems OK, but I expect it'd be cleaner to make such changes in a
> new version.
>
> --
> Dominic Cleal
> Red Hat Engineering
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
> This sounds fair to me, when you say "discourage incompatible changes in
> v2 at this point" you mean when 1.6 is released, not now, right?
I mean now, since I believe it's in widespread use, including in Hammer.
When 1.6 is released, incompatible changes would be prohibited as they
are with v1.
I say that because v2 has been in its current limbo state for many
releases and new features in Foreman have only been added to v2, which I
believe has forced many people to begin using it despite the
"experimental" label - including our own tools, such as Hammer and the
installer.
> I think if we are going to do this, API v2 should be audited and
> reviewed in depth before locking it, also Hammer will need a thorough
> review to see what parts of the API are missing for them.
To what end? If fields etc are missing, they can be added at any point,
that's not an incompatible change. If you intend to redesign parts of
it, I'd still discourage that at this stage.
> By "incompatible changes" in v2, I assume that you mean not to change *_id and *_name to a child node
>
>>
>> {
>> "name": "fdev2.sat.lab.tlv.redhat.com",
>> "id": 394,
>> "environment_id": 1,
>> "environment_name": "production",
>>
>> becomes this
>>
>> {
>> "name": "fdev2.sat.lab.tlv.redhat.com",
>> "id": 394,
>> "environment": {
>> "name": "production",
>> "id": 1
>> },
I don't mean this specifically, I mean any change that would reasonably
lead to a major break in a client application, such as renaming and
restructuring fields. This would be an example, yes.
> Alternatively, we could have duplicate data in the response so as not to break anything like this
>
>> "name": "fdev2.sat.lab.tlv.redhat.com",
>> "id": 394,
>> "environment_id": 1,
>> "environment_name": "production",
>> "environment": {
>> "name": "production",
>> "id": 1
>> },
>
> What do you suggest?
That seems OK, but I expect it'd be cleaner to make such changes in a
new version.
Naturally, like we do with v1 and v2 today, but what other options are
there? We can leave v2 in experimental for another release or two, but
IMO the situation begins to become absurd. I think it's about time to
press on and encourage users to make use of what's there - release
early, release often.
···
On 10/07/14 12:36, Joseph Magen wrote:
> I don't mind to make v3, but I think it would cause maintaining two versions, v2 and v3.
It's not the same, as we aren't back-porting any changes to v1. If we aren't backporting, then I'm in favor. I agree to release early and often. I have 3 open PR's related to V2. They are are non-breaking changes but also not critical either. I could include them in v3 only.
···
----- Original Message -----
> From: "Dominic Cleal"
> To: foreman-dev@googlegroups.com
> Sent: Thursday, July 10, 2014 2:45:41 PM
> Subject: Re: [foreman-dev] Change API v2 to stable in Foreman 1.6(?)
>
> On 10/07/14 12:36, Joseph Magen wrote:
> > I don't mind to make v3, but I think it would cause maintaining two
> > versions, v2 and v3.
>
> Naturally, like we do with v1 and v2 today, but what other options are
> there? We can leave v2 in experimental for another release or two, but
> IMO the situation begins to become absurd. I think it's about time to
> press on and encourage users to make use of what's there - release
> early, release often.
>
> --
> Dominic Cleal
> Red Hat Engineering
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
If they are non breaking… why not add to v2? Keep enhancing v2 until
there is a major overhaul.
Havng said that, if there is a desire to overhaul the json… IMHO should
do that quickly and then freeze v2.
– bk
···
On 07/10/2014 07:49 AM, Joseph Magen wrote:
> It's not the same, as we aren't back-porting any changes to v1. If we aren't backporting, then I'm in favor. I agree to release early and often. I have 3 open PR's related to V2. They are are non-breaking changes but also not critical either. I could include them in v3 only.
I'd like to see v2 on theforeman.org (docs, etc.) include katello since it is now entirely part of the project. Are all the current api and json issues in both foreman and katello resolved? If we're going to freeze input and output format, in addition to params, I too would like to see a full inventory and review (again of both foreman and katello).
···
----- Original Message -----
>
>
> On 07/10/2014 07:49 AM, Joseph Magen wrote:
> > It's not the same, as we aren't back-porting any changes to v1. If we
> > aren't backporting, then I'm in favor. I agree to release early and often.
> > I have 3 open PR's related to V2. They are are non-breaking changes but
> > also not critical either. I could include them in v3 only.
>
> If they are non breaking.. why not add to v2? Keep enhancing v2 until
> there is a major overhaul.
>
> Havng said that, if there is a desire to overhaul the json.. IMHO should
> do that quickly and then freeze v2.
>
> -- bk
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
We do make small additions for fields etc to v1 today. If they're
non-breaking changes then I guess it's up to your judgement as to which
version they should be added to.
···
--
Dominic Cleal
Red Hat Engineering
On 10/07/14 12:49, Joseph Magen wrote:
It’s not the same, as we aren’t back-porting any changes to v1. If we aren’t backporting, then I’m in favor. I agree to release early and often. I have 3 open PR’s related to V2. They are are non-breaking changes but also not critical either. I could include them in v3 only.
I don’t mind to make v3, but I think it would cause maintaining two
versions, v2 and v3.
Naturally, like we do with v1 and v2 today, but what other options are
there? We can leave v2 in experimental for another release or two, but
IMO the situation begins to become absurd. I think it’s about time to
press on and encourage users to make use of what’s there - release
early, release often.
>
>
> > It's not the same, as we aren't back-porting any changes to v1. If we
> > aren't backporting, then I'm in favor. I agree to release early and often.
> > I have 3 open PR's related to V2. They are are non-breaking changes but
> > also not critical either. I could include them in v3 only.
>
> If they are non breaking… why not add to v2? Keep enhancing v2 until
> there is a major overhaul.
>
> Havng said that, if there is a desire to overhaul the json… IMHO should
> do that quickly and then freeze v2.
+1 no need to introduce v3 just to be able to add new features. All we need
is love and making sure we are happy with the base concepts and conventions around v2,
so that we don't have to introduce the v3 anytime soon: 2 versions at a time are enough,
so the best timing for the v3 would be once the v1 is obsolete.
– Ivan
···
----- Original Message -----
> On 07/10/2014 07:49 AM, Joseph Magen wrote:
The best may be to start out by having v3 inherit from v2 since they will be similar, unlike v1 and v2 which had different root nodes.
···
----- Original Message -----
> From: "Dominic Cleal"
> To: foreman-dev@googlegroups.com
> Sent: Thursday, July 10, 2014 2:56:10 PM
> Subject: Re: [foreman-dev] Change API v2 to stable in Foreman 1.6(?)
>
> We do make small additions for fields etc to v1 today. If they're
> non-breaking changes then I guess it's up to your judgement as to which
> version they should be added to.
>
> --
> Dominic Cleal
> Red Hat Engineering
>
> On 10/07/14 12:49, Joseph Magen wrote:
> > It's not the same, as we aren't back-porting any changes to v1. If we
> > aren't backporting, then I'm in favor. I agree to release early and often.
> > I have 3 open PR's related to V2. They are are non-breaking changes but
> > also not critical either. I could include them in v3 only.
> >
> >
> >
> >
> > ----- Original Message -----
> >> From: "Dominic Cleal"
> >> To: foreman-dev@googlegroups.com
> >> Sent: Thursday, July 10, 2014 2:45:41 PM
> >> Subject: Re: [foreman-dev] Change API v2 to stable in Foreman 1.6(?)
> >>
> >> On 10/07/14 12:36, Joseph Magen wrote:
> >>> I don't mind to make v3, but I think it would cause maintaining two
> >>> versions, v2 and v3.
> >>
> >> Naturally, like we do with v1 and v2 today, but what other options are
> >> there? We can leave v2 in experimental for another release or two, but
> >> IMO the situation begins to become absurd. I think it's about time to
> >> press on and encourage users to make use of what's there - release
> >> early, release often.
> >>
> >> --
> >> Dominic Cleal
> >> Red Hat Engineering
> >>
> >> --
> >> You received this message because you are subscribed to the Google Groups
> >> "foreman-dev" group.
> >> To unsubscribe from this group and stop receiving emails from it, send an
> >> email to foreman-dev+unsubscribe@googlegroups.com.
> >> For more options, visit https://groups.google.com/d/optout.
> >>
> >
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
