What are people's thoughts about making API v2 the default in the Foreman 1.5 release. This means that all API calls in which the version is NOT specified will go to V2.
API will still be available, but now users would need to specify V1 in the URL or header as such:
api/v1/hosts
or
curl -H 'Accept:application/json,version=1'
What action items remain for API v2? From what I recall, we still need to:
finalize and document the method for adding/removing many-to-many relationships
add feature to add/remove one many-to-many relationship without needing to pass the whole array
finalize nested routes
finalize child nodes on #show template
find by name when name is unique only by scope
create option to show all results without pagination rather than passing per_page=10000
A feature that probably won't make it for 1.5 but shouldn't prevent API v2 from becoming the default is
customized responses - specify fields and/or relationships(fields) to be included in response
> What are people's thoughts about making API v2 the default in the Foreman 1.5 release. This means that all API calls in which the version is NOT specified will go to V2.
>
> API will still be available, but now users would need to specify V1 in the URL or header as such:
>
> api/v1/hosts
> or
> curl -H 'Accept:application/json,version=1'
>
> What action items remain for API v2? From what I recall, we still need to:
>
> 1) finalize and document the method for adding/removing many-to-many relationships
> 2) add feature to add/remove one many-to-many relationship without needing to pass the whole array
> 3) finalize nested routes
> 4) finalize child nodes on #show template
What do you mean here? My concern is with backwards-incompatible changes.
> 5) find by name when name is unique only by scope
Ditto, is there a bug #?
> 6) create option to show all results without pagination rather than passing per_page=10000
>
> A feature that probably won't make it for 1.5 but shouldn't prevent API v2 from becoming the default is
>
> 7) customized responses - specify fields and/or relationships(fields) to be included in response
As above, I don't see issues with addressing these items later, provided
they're not backwards incompatible.
I think it's about time APIv2 at least lost its experimental label,
though we don't necessarily need to make it the default at the same time.
Ensure the documentation is updated to no longer refer to it as
experimental, and to document the upgrade path for v1 users.
> From: "Dominic Cleal" <dcleal@redhat.com>
> To: foreman-dev@googlegroups.com
> Sent: Monday, April 7, 2014 2:21:54 PM
> Subject: Re: [foreman-dev] API v2 as default for Foreman 1.5 release?
>
> > What are people's thoughts about making API v2 the default in the Foreman
> > 1.5 release. This means that all API calls in which the version is NOT
> > specified will go to V2.
> >
> > API will still be available, but now users would need to specify V1 in the
> > URL or header as such:
> >
> > api/v1/hosts
> > or
> > curl -H 'Accept:application/json,version=1'
> >
> > What action items remain for API v2? From what I recall, we still need to:
> >
> > 1) finalize and document the method for adding/removing many-to-many
> > relationships
> > 2) add feature to add/remove one many-to-many relationship without needing
> > to pass the whole array
> > 3) finalize nested routes
> > 4) finalize child nodes on #show template
>
> What do you mean here? My concern is with backwards-incompatible changes.
What backwards-incompatible issues on V2? There shouldn't be any as V2 has been experimental and can have breaking changes.
Issue #4 is just to finalize which child nodes we want to include on each #show templates. The easy answer is "all has_many relationships" as child nodes, but for some objects, it doesn't sense such as trends, reports, etc.
>
> > 5) find by name when name is unique only by scope
>
> Ditto, is there a bug #?
It's more of a feature. In some places, there is no find_by_name since the name is not unique, but it is unique would be unique for a nested route. What comes to mind is objects with ancestry
> > 6) create option to show all results without pagination rather than passing
> > per_page=10000
> >
> > A feature that probably won't make it for 1.5 but shouldn't prevent API v2
> > from becoming the default is
> >
> > 7) customized responses - specify fields and/or relationships(fields) to be
> > included in response
>
> As above, I don't see issues with addressing these items later, provided
> they're not backwards incompatible.
>
> I think it's about time APIv2 at least lost its experimental label,
> though we don't necessarily need to make it the default at the same time.
What's the pros vs. cons of having V2 the default in Foreman 1.5?
···
----- Original Message -----
> On 07/04/14 12:15, Joseph Magen wrote:
Ensure the documentation is updated to no longer refer to it as
experimental, and to document the upgrade path for v1 users.
>> From: "Dominic Cleal" <dcleal@redhat.com>
>> To: foreman-dev@googlegroups.com
>> Sent: Monday, April 7, 2014 2:21:54 PM
>> Subject: Re: [foreman-dev] API v2 as default for Foreman 1.5 release?
>>
>>> 4) finalize child nodes on #show template
>>
>> What do you mean here? My concern is with backwards-incompatible changes.
>
> What backwards-incompatible issues on V2? There shouldn't be any as V2 has been experimental and can have breaking changes.
> Issue #4 is just to finalize which child nodes we want to include on each #show templates. The easy answer is "all has_many relationships" as child nodes, but for some objects, it doesn't sense such as trends, reports, etc.
Yes, it's experimental right now… but if it becomes the default as
you're proposing, we won't then be able to make a backwards-incompatible
change. Are you proposing these items need to be done before we can
change the default?
>>> 6) create option to show all results without pagination rather than passing
>>> per_page=10000
>>>
>>> A feature that probably won't make it for 1.5 but shouldn't prevent API v2
>>> from becoming the default is
>>>
>>> 7) customized responses - specify fields and/or relationships(fields) to be
>>> included in response
>>
>> As above, I don't see issues with addressing these items later, provided
>> they're not backwards incompatible.
>>
>> I think it's about time APIv2 at least lost its experimental label,
>> though we don't necessarily need to make it the default at the same time.
>
> What's the pros vs. cons of having V2 the default in Foreman 1.5?
The only difference might be so we can tell people that although v1 is
the default in 1.5, we now consider v2 stable enough to migrate to
without breaking changes. So we recommend migration, but don't cause
existing apps/scripts to break as we changed the default (most people
won't be using /api/v1 because it's too new, and are unlikely to specify
the Accept header).
I don't really mind which approach, but would suggest the more gradual
step first.
We should also have a statement regarding the status of v1, whether
we're calling it deprecated, stable & default, stable & not default etc.
···
On 07/04/14 12:41, Joseph Magen wrote:
> ----- Original Message -----
>> On 07/04/14 12:15, Joseph Magen wrote:
>> What are people's thoughts about making API v2 the default in the Foreman 1.5 release. This means that all API calls in which the version is NOT specified will go to V2.
>>
>> API will still be available, but now users would need to specify V1 in the URL or header as such:
>>
>> api/v1/hosts
>> or
>> curl -H 'Accept:application/json,version=1'
>>
>> What action items remain for API v2? From what I recall, we still need to:
>>
>> 1) finalize and document the method for adding/removing many-to-many relationships
>> 2) add feature to add/remove one many-to-many relationship without needing to pass the whole array
>> 3) finalize nested routes
>> 4) finalize child nodes on #show template
>
> What do you mean here? My concern is with backwards-incompatible changes.
>
>> 5) find by name when name is unique only by scope
>
> Ditto, is there a bug #?
>
>> 6) create option to show all results without pagination rather than passing per_page=10000
>>
>> A feature that probably won't make it for 1.5 but shouldn't prevent API v2 from becoming the default is
>>
>> 7) customized responses - specify fields and/or relationships(fields) to be included in response
>
> As above, I don't see issues with addressing these items later, provided
> they're not backwards incompatible.
>
> I think it's about time APIv2 at least lost its experimental label,
> though we don't necessarily need to make it the default at the same time.
>
+1 to the both above. It's no longer experimental for sure. If the
remaining issues don't break compatibility with v2 as it is now, we can
make it default. I agree with Dominic that the second step can wait for
a bit.
···
On 04/07/2014 01:21 PM, Dominic Cleal wrote:
> On 07/04/14 12:15, Joseph Magen wrote:
Ensure the documentation is updated to no longer refer to it as
experimental, and to document the upgrade path for v1 users.
