API v1 and v2 status and what about v3?

Development
1

Hello,

I just happened to read an issue [1] about v2 and v1 documentation
inconsistency. Long story short, we changed IPAM attribute of Subnet from
boolean to string in 1.7.0 [2] and changed only v2 API description.

Now my questions are, how big mistake was it? Is v2 considered stable so we
can't change it?

We still ship v1 as default (which is likely to remain the same for 1.8). When
do we officially move to v2? And when first similar requirement comes, does it
mean that we should add v3?

Last but not least, how long do we want to support v1? The proper fix for the
issue [1] is probably adding compatibility layer for v1 that converts bool to
new string values. Similar changes will require some effort until v1 support
ends.

[1] Bug #9720: APIv1 subnets "ipam" documentation is inconsistent with v2 - Foreman
[2] https://github.com/theforeman/foreman/pull/1565

Thanks

··· -- Marek
2

> From: "Marek Hulan" <mhulan@redhat.com>
> To: foreman-dev@googlegroups.com
> Sent: Sunday, March 29, 2015 4:57:23 PM
> Subject: [foreman-dev] API v1 and v2 status and what about v3?
>
> Hello,
>
> I just happened to read an issue [1] about v2 and v1 documentation
> inconsistency. Long story short, we changed IPAM attribute of Subnet from
> boolean to string in 1.7.0 [2] and changed only v2 API description.
>
> Now my questions are, how big mistake was it? Is v2 considered stable so we
> can't change it?
>
> We still ship v1 as default (which is likely to remain the same for 1.8).
> When
> do we officially move to v2? And when first similar requirement comes, does
> it
> mean that we should add v3?
>

As long as patching to v2 are evolutionary and do not break code, then patches are committed to v2. I see v3 as changing major items such as the response formats or other formats within the jsonapi.org spec.

··· ----- Original Message -----

Last but not least, how long do we want to support v1? The proper fix for the
issue [1] is probably adding compatibility layer for v1 that converts bool to
new string values. Similar changes will require some effort until v1 support
ends.

[1] Bug #9720: APIv1 subnets "ipam" documentation is inconsistent with v2 - Foreman
[2] https://github.com/theforeman/foreman/pull/1565

Thanks

–
Marek

–
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.

3

> Hello,
>
> I just happened to read an issue [1] about v2 and v1 documentation
> inconsistency. Long story short, we changed IPAM attribute of Subnet from
> boolean to string in 1.7.0 [2] and changed only v2 API description.
>
> Now my questions are, how big mistake was it? Is v2 considered stable so we
> can't change it?

v2 has been considered stable since 1.6.0.

> We still ship v1 as default (which is likely to remain the same for 1.8). When
> do we officially move to v2?

Whenever somebody proposes it? Nobody has so far, so it hasn't been
done. There was some dissent about the idea on this list when it was
last discussed, so maybe nobody decided to after that. (The idea being
that people explicitly choose a version rather than assuming.)

> Last but not least, how long do we want to support v1? The proper fix for the
> issue [1] is probably adding compatibility layer for v1 that converts bool to
> new string values. Similar changes will require some effort until v1 support
> ends.

You could say the same applies to v2, but I personally tend to overlook
model changes as natural evolution, and instead avoid changing the
behaviour of the API itself (URLs, format, metadata etc).

··· On 29/03/15 14:57, Marek Hulan wrote:

–
Dominic Cleal
Red Hat Engineering