RFC for foreman_api_v3

Development
1

Hi all,

I created a RFC for a plugin called foreman_api_v3
<https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md&gt; and
the initial repo at GitHub - isratrade/foreman_api_v3. If the community
accepts, I am happy to move this repo to theforeman/foreman_api_v3

I choose to make this a plugin rather than a PR so it is optional for users
and doesn't affect the core code. The initial repo only includes the GET
index and show actions. The PUT/PATCH/POST/DELETE actions need to be
added. Also, there are currently no functional tests in the repo, so a lot
more work needs to be done.

Note that I inherited V2 so that V3 controllers look like this

module Api
module V3
class DomainsController < V2::DomainsController

but the response is changed.

  def index
    super
    render json: @domains,
           fields: @fields_hash,
           include: @include_array,
           each_serializer: DomainSerializer
  end

For some background, the Foreman API v2 is more than 3 years old. When I
implemented v2, I used conventions that I thought were good at the time.
The katello had some slightly different conventions, and we weren't always
in sync. This created some challenges for Satellite6 as a single RH
product.

The goal of JSON API is to create a standardization that is *Flexible,
Consistent, and Fast *-- we can all agree with these goals.

Here's some more links that could be helpful in addition to
http://jsonapi.org/

JSON API <http://jsonapi.org/&gt; is a great solution to not waste hours on
reinventing the wheel in terms of your API responses design. It is a
great, extensible response standard which can save your time - both on the
backend side and the client side. Your clients can leverage you’re using an
established standard to implement an integration with your API in a cleaner
and faster way.

Building a Rails API with the JSON API Spec

I look forward to hearing you feedback and receiving contributions to the
repo.

Joseph Magen (@isratrade)
Red Hat

2

Please consider calling it something else that won't cause confusion for
users with Foreman's own API versioning.

··· On 26/08/16 06:58, Joseph Magen wrote: > I created a RFC for a plugin called foreman_api_v3 > and > the initial repo at github.com/isratrade/foreman_api_v3 > . If the community accepts, > I am happy to move this repo to theforeman/foreman_api_v3 > > I choose to make this a plugin rather than a PR so it is optional for > users and doesn't affect the core code.

–
Dominic Cleal
dominic@cleal.org

3

> I created a RFC for a plugin called foreman_api_v3
> <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md> and
> the initial repo at github.com/isratrade/foreman_api_v3. If the community
> accepts, I am happy to move this repo to theforeman/foreman_api_v3

Joseph, can you describe in more detail what the change is all about?
From reading the README I can't tell what is going on. This is a great
candidate for RFC by the way.

> For some background, the Foreman API v2 is more than 3 years old. When I
> implemented v2, I used conventions that I thought were good at the time.
> The katello had some slightly different conventions, and we weren't always
> in sync. This created some challenges for Satellite6 as a single RH
> product.
>
> The goal of JSON API is to create a standardization that is *Flexible,
> Consistent, and Fast *-- we can all agree with these goals.
>
> Here's some more links that could be helpful in addition to
> http://jsonapi.org/
>
> http://blog.arkency.com/2016/02/how-and-why-should-you-use-json-api-in-your-rails-api/
>
> JSON API <http://jsonapi.org/> is a great solution to not waste hours on
> reinventing the wheel in terms of your API responses design. It is a
> great, extensible response standard which can save your time - both on the
> backend side and the client side. Your clients can leverage you’re using an
> established standard to implement an integration with your API in a cleaner
> and faster way.

This should go into the RFC really ^^^

··· -- Later, Lukas #lzap Zapletal
4

Given more testing, and full functionality, I don't see why not making
this part of Foreman itself vs a plugin. Using json:api sounds great to
me, so thanks for doing it.

Having said that (and derailing a bit), I would want v3 not only to
comply with json:api but also to be documented with http://swagger.io/
instead. This gives us:

··· On 08/26, Joseph Magen wrote: > Hi all, > > I created a RFC for a plugin called foreman_api_v3 > and > the initial repo at github.com/isratrade/foreman_api_v3. If the community > accepts, I am happy to move this repo to theforeman/foreman_api_v3 > > I choose to make this a plugin rather than a PR so it is optional for users > and doesn't affect the core code. The initial repo only includes the GET > `index` and `show` actions. The PUT/PATCH/POST/DELETE actions need to be > added. Also, there are currently no functional tests in the repo, so a lot > more work needs to be done.

–
Daniel Lobato Garcia

@dLobatog
blog.daniellobato.me
daniellobato.me

GPG: http://keys.gnupg.net/pks/lookup?op=get&search=0x7A92D6DD38D6DE30
Keybase: https://keybase.io/elobato

5

> Hi all,
>
> I created a RFC for a plugin called foreman_api_v3
> <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md&gt; and
> the initial repo at GitHub - isratrade/foreman_api_v3
> <https://github.com/isratrade/foreman_api_v3&gt;. If the community accepts,
> I am happy to move this repo to theforeman/foreman_api_v3
>
> I choose to make this a plugin rather than a PR so it is optional for
> users and doesn't affect the core code. The initial repo only includes
> the GET index and show actions. The PUT/PATCH/POST/DELETE actions
> need to be added. Also, there are currently no functional tests in the
> repo, so a lot more work needs to be done.
>
> Note that I inherited V2 so that V3 controllers look like this
>
> module Api
> module V3
> class DomainsController < V2::DomainsController
>
> but the response is changed.
>
> def index
> super
> render json: @domains,
> fields: @fields_hash,
> include: @include_array,
> each_serializer: DomainSerializer
> end
>
> For some background, the Foreman API v2 is more than 3 years old. When I
> implemented v2, I used conventions that I thought were good at the time.
> The katello had some slightly different conventions, and we weren't
> always in sync. This created some challenges for Satellite6 as a single
> RH product.
>
> The goal of JSON API is to create a standardization that is *Flexible,
> Consistent, and Fast *-- we can all agree with these goals.
>

Thanks for sending that, Joseph. Jsonapi.org is nice specification and I
like how it structures the data. The ability to include additional
resources into the response is very handy and making the katello and
foreman api consistent would be good too. But that alone wouldn't be
enough to make switch to jsonapi. In my opinion main painpoints of the
current api v2 are elsewhere. Firstly I miss adding associated resources
without having to send all what's currently included. Second main issue
is inconsistent error responses (we've improved with that but it's still
not ideal).
Jsonapi.org has cures for both [1] [2], so I'm not against at all that
but we mustn't stop just at changing the output format.

Speaking about the format change, since getting consistent with katello
is one of motivations for the change, I'd like to hear from somebody
with expertise in that field how difficult would be to bend the UI code
to use the new format. Just to make sure we actually won't
unintentionally put more obstacles in katello's way.

If we decide that jsonapi is the way to go for v3 I think it would be
better to implement it as part of the foreman core. We can clearly mark
it as devel preview with no guarantees, let it evolve alongside with v2
and freeze when we're happy with it.

[1] JSON:API — Latest Specification (v1.1)
[2] JSON:API — Latest Specification (v1.1)

··· On 08/26/2016 07:58 AM, Joseph Magen wrote:

Here’s some more links that could be helpful in addition
to http://jsonapi.org/

How and why should you use JSON API in your Rails API? | Arkency Blog

JSON API http://jsonapi.org/ is a great solution to not waste hours
on reinventing the wheel in terms of your API responses design. It is a
great, extensible response standard which can save your time - both on
the backend side and the client side. Your clients can leverage you’re
using an established standard to implement an integration with your API
in a cleaner and faster way.

*Building a Rails API with the JSON API Spec
*Building a Rails API with the JSON API Spec | PPT

I look forward to hearing you feedback and receiving contributions to
the repo.

Joseph Magen (@isratrade)
Red Hat

6

> Having said that (and derailing a bit), I would want v3 not only to
> comply with json:api but also to be documented with http://swagger.io/
> instead. This gives us:
>
> - automated, better docs than what we have (example
> http://petstore.swagger.io/#!/pet/updatePet)
> - automated tests to ensure docs do what they say
> - generates an SDK for the API in many languages
> automatically through https://github.com/swagger-api/swagger-codegen
>

If you are going to move away from REST that far, why stick with it at
all and not switch to something like grpc?
-d

7

>> Hi all,
>>
>> I created a RFC for a plugin called foreman_api_v3
>> <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md&gt; and
>> the initial repo at GitHub - isratrade/foreman_api_v3. If the community
>> accepts, I am happy to move this repo to theforeman/foreman_api_v3
>>
>> I choose to make this a plugin rather than a PR so it is optional for users
>> and doesn't affect the core code. The initial repo only includes the GET
>> index and show actions. The PUT/PATCH/POST/DELETE actions need to be
>> added. Also, there are currently no functional tests in the repo, so a lot
>> more work needs to be done.
>
> Given more testing, and full functionality, I don't see why not making
> this part of Foreman itself vs a plugin. Using json:api sounds great to
> me, so thanks for doing it.
>
> Having said that (and derailing a bit), I would want v3 not only to
> comply with json:api but also to be documented with http://swagger.io/
> instead. This gives us:

I'm not very familiar with swagger. Would that mean replacing apipie
completely or exporting from apipie to swagger's format?

··· On 08/26/2016 10:39 AM, Daniel Lobato Garcia wrote: > On 08/26, Joseph Magen wrote:

–
Daniel Lobato Garcia

@dLobatog
blog.daniellobato.me
daniellobato.me

GPG: http://keys.gnupg.net/pks/lookup?op=get&search=0x7A92D6DD38D6DE30
Keybase: elobato (Daniel Lobato Garcia) | Keybase

8

> > I created a RFC for a plugin called foreman_api_v3
> > <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md&gt;
> and
> > the initial repo at GitHub - isratrade/foreman_api_v3
> > <https://github.com/isratrade/foreman_api_v3&gt;. If the community accepts,
> > I am happy to move this repo to theforeman/foreman_api_v3
> >
> > I choose to make this a plugin rather than a PR so it is optional for
> > users and doesn't affect the core code.
>
> Please consider calling it something else that won't cause confusion for
> users with Foreman's own API versioning.
>

I can rename the plugin to foreman_jsonapi and change to version to v21
(meaning v2.1 since it inherits from v2), so it would look like this

GET api/api/v21/hosts

What do you think?

> –
> Dominic Cleal
> dominic@cleal.org
>

>
>> Hi all,
>>
>> I created a RFC for a plugin called foreman_api_v3
>> <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md&gt;
>> and
>> the initial repo at GitHub - isratrade/foreman_api_v3
>> <https://github.com/isratrade/foreman_api_v3&gt;. If the community accepts,
>> I am happy to move this repo to theforeman/foreman_api_v3
>>
>> I choose to make this a plugin rather than a PR so it is optional for
>> users and doesn't affect the core code. The initial repo only includes
>> the GET index and show actions. The PUT/PATCH/POST/DELETE actions
>> need to be added. Also, there are currently no functional tests in the
>> repo, so a lot more work needs to be done.
>>
>> Note that I inherited V2 so that V3 controllers look like this
>>
>> module Api
>> module V3
>> class DomainsController < V2::DomainsController
>>
>> but the response is changed.
>>
>> def index
>> super
>> render json: @domains,
>> fields: @fields_hash,
>> include: @include_array,
>> each_serializer: DomainSerializer
>> end
>>
>> For some background, the Foreman API v2 is more than 3 years old. When I
>> implemented v2, I used conventions that I thought were good at the time.
>> The katello had some slightly different conventions, and we weren't
>> always in sync. This created some challenges for Satellite6 as a single
>> RH product.
>>
>> The goal of JSON API is to create a standardization that is *Flexible,
>> Consistent, and Fast *-- we can all agree with these goals.
>>
>>
> Thanks for sending that, Joseph. Jsonapi.org is nice specification and I
> like how it structures the data. The ability to include additional
> resources into the response is very handy and making the katello and
> foreman api consistent would be good too. But that alone wouldn't be enough
> to make switch to jsonapi. In my opinion main painpoints of the current api
> v2 are elsewhere. Firstly I miss adding associated resources without having
> to send all what's currently included. Second main issue is inconsistent
> error responses (we've improved with that but it's still not ideal).
> Jsonapi.org has cures for both [1] [2], so I'm not against at all that but
> we mustn't stop just at changing the output format.
>

Please explain the other pain points in v2 besides [1] [2]

Speaking about the format change, since getting consistent with katello is
> one of motivations for the change, I'd like to hear from somebody with
> expertise in that field how difficult would be to bend the UI code to use
> the new format.

Just to make sure we actually won't unintentionally put more obstacles in
> katello's way.
>

I assume you mean using RABL to generate the new output format when keeping
the same v2 controllers. IMHO, this would be a bigger headache for both
Koreman and Katello. This would still lead to v3 since there are breaking
changes. Maybe I don't understand your question fully.

> If we decide that jsonapi is the way to go for v3 I think it would be
> better to implement it as part of the foreman core. We can clearly mark it
> as devel preview with no guarantees, let it evolve alongside with v2 and
> freeze when we're happy with it.
>

I don't see the advantage of implementing a new api as part of core until
if/when it is stable and has community adoption.

··· On Fri, Aug 26, 2016 at 10:47 AM, Dominic Cleal wrote: > On 26/08/16 06:58, Joseph Magen wrote: On Fri, Aug 26, 2016 at 11:36 PM, Tomas Strachota wrote: > On 08/26/2016 07:58 AM, Joseph Magen wrote:

[1] JSON:API — Latest Specification (v1.1)
[2] JSON:API — Latest Specification (v1.1)

Here’s some more links that could be helpful in addition

to http://jsonapi.org/

http://blog.arkency.com/2016/02/how-and-why-should-you-use-j
son-api-in-your-rails-api/

JSON API http://jsonapi.org/ is a great solution to not waste hours
on reinventing the wheel in terms of your API responses design. It is a
great, extensible response standard which can save your time - both on
the backend side and the client side. Your clients can leverage you’re
using an established standard to implement an integration with your API
in a cleaner and faster way.

*Building a Rails API with the JSON API Spec
*http://www.slideshare.net/SonjaPeterson2/building-a-rails-
api-with-the-json-api-spec

I look forward to hearing you feedback and receiving contributions to
the repo.

Joseph Magen (@isratrade)
Red Hat

9

> > I created a RFC for a plugin called foreman_api_v3
> > <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md&gt;
> and
> > the initial repo at GitHub - isratrade/foreman_api_v3. If the
> community
> > accepts, I am happy to move this repo to theforeman/foreman_api_v3
>
> Joseph, can you describe in more detail what the change is all about?
> From reading the README I can't tell what is going on. This is a great
> candidate for RFC by the way.
>
> > For some background, the Foreman API v2 is more than 3 years old. When I
> > implemented v2, I used conventions that I thought were good at the time.
> > The katello had some slightly different conventions, and we weren't
> always
> > in sync. This created some challenges for Satellite6 as a single RH
> > product.
> >
> > The goal of JSON API is to create a standardization that is *Flexible,
> > Consistent, and Fast *-- we can all agree with these goals.
> >
> > Here's some more links that could be helpful in addition to
> > http://jsonapi.org/
> >
> > http://blog.arkency.com/2016/02/how-and-why-should-you-use-
> json-api-in-your-rails-api/
> >
> > JSON API <http://jsonapi.org/&gt; is a great solution to not waste hours
> on
> > reinventing the wheel in terms of your API responses design. It is a
> > great, extensible response standard which can save your time - both on
> the
> > backend side and the client side. Your clients can leverage you’re using
> an
> > established standard to implement an integration with your API in a
> cleaner
> > and faster way.
>
> This should go into the RFC really ^^^
>

I updated the PR. Thanks Lukas

··· On Fri, Aug 26, 2016 at 10:39 AM, Lukas Zapletal wrote:

–
Later,
Lukas #lzap Zapletal

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

10

Please reply all from this point on given there was a cross post made
originally that shouldn't have been.

Eric

··· On Fri, Aug 26, 2016 at 3:48 PM, Tomas Strachota wrote:

On 08/26/2016 10:39 AM, Daniel Lobato Garcia wrote:

On 08/26, Joseph Magen wrote:

Hi all,

I created a RFC for a plugin called foreman_api_v3
https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md
and
the initial repo at GitHub - isratrade/foreman_api_v3. If the
community
accepts, I am happy to move this repo to theforeman/foreman_api_v3

I choose to make this a plugin rather than a PR so it is optional for
users
and doesn’t affect the core code. The initial repo only includes the GET
index and show actions. The PUT/PATCH/POST/DELETE actions need to be
added. Also, there are currently no functional tests in the repo, so a
lot
more work needs to be done.

Given more testing, and full functionality, I don’t see why not making
this part of Foreman itself vs a plugin. Using json:api sounds great to
me, so thanks for doing it.

Having said that (and derailing a bit), I would want v3 not only to
comply with json:api but also to be documented with http://swagger.io/
instead. This gives us:

I’m not very familiar with swagger. Would that mean replacing apipie
completely or exporting from apipie to swagger’s format?

–
Daniel Lobato Garcia

@dLobatog
blog.daniellobato.me
daniellobato.me

GPG: http://keys.gnupg.net/pks/lookup?op=get&search=0x7A92D6DD38D6DE30
Keybase: elobato (Daniel Lobato Garcia) | Keybase

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

–
Eric D. Helms
Red Hat Engineering
Ph.D. Student - North Carolina State University

11

>
>
> > I created a RFC for a plugin called foreman_api_v3
> >
> <rfcs/0000-foreman-api-v3.md at master · isratrade/rfcs · GitHub
> <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md&gt;&gt;
> and
> > the initial repo atgithub.com/isratrade/foreman_api_v3
> <http://github.com/isratrade/foreman_api_v3&gt;
> > <GitHub - isratrade/foreman_api_v3
> <https://github.com/isratrade/foreman_api_v3&gt;&gt;. If the community
> accepts,
> > I am happy to move this repo to theforeman/foreman_api_v3
> >
> > I choose to make this a plugin rather than a PR so it is
> optional for
> > users and doesn't affect the core code.
>
> Please consider calling it something else that won't cause
> confusion for
> users with Foreman's own API versioning.
>
>
> I can rename the plugin to foreman_jsonapi and change to version to
> v21 (meaning v2.1 since it inherits from v2), so it would look like this
>
> GET api/api/v21/hosts

what happens when we get to version 21 of the api which in my
calculations will occur around 2325? :slight_smile:

··· On 08/28/2016 01:49 AM, Joseph Magen wrote: > On Fri, Aug 26, 2016 at 10:47 AM, Dominic Cleal > wrote: > On 26/08/16 06:58, Joseph Magen wrote:

What do you think?

--
Dominic Cleal
dominic@cleal.org <mailto:dominic@cleal.org>

On Fri, Aug 26, 2016 at 11:36 PM, Tomas Strachota > <tstrachota@redhat.com mailto:tstrachota@redhat.com> wrote:

On 08/26/2016 07:58 AM, Joseph Magen wrote:

    Hi all,

    I created a RFC for a plugin called foreman_api_v3
    <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md
    <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md>>
    and
    the initial repo at github.com/isratrade/foreman_api_v3
    <http://github.com/isratrade/foreman_api_v3>
    <https://github.com/isratrade/foreman_api_v3
    <https://github.com/isratrade/foreman_api_v3>>. If the
    community accepts,
    I am happy to move this repo to theforeman/foreman_api_v3

    I choose to make this a plugin rather than a PR so it is
    optional for
    users and doesn't affect the core code. The initial repo only
    includes
    the GET `index` and `show` actions. The PUT/PATCH/POST/DELETE
    actions
    need to be added. Also, there are currently no functional
    tests in the
    repo, so a lot more work needs to be done.

    Note that I inherited V2 so that V3 controllers look like this

    module Api
      module V3
        class DomainsController < V2::DomainsController

    but the response is changed.

          def index
            super
            render json: @domains,
                   fields: @fields_hash,
                   include: @include_array,
                   each_serializer: DomainSerializer
          end

    For some background, the Foreman API v2 is more than 3 years
    old. When I
    implemented v2, I used conventions that I thought were good at
    the time.
    The katello had some slightly different conventions, and we
    weren't
    always in sync. This created some challenges for Satellite6 as
    a single
    RH product.

    The goal of JSON API is to create a standardization that is
    *Flexible,
    Consistent, and Fast *-- we can all agree with these goals.


Thanks for sending that, Joseph. Jsonapi.org is nice specification
and I like how it structures the data. The ability to include
additional resources into the response is very handy and making
the katello and foreman api consistent would be good too. But that
alone wouldn't be enough to make switch to jsonapi. In my opinion
main painpoints of the current api v2 are elsewhere. Firstly I
miss adding associated resources without having to send all what's
currently included. Second main issue is inconsistent error
responses (we've improved with that but it's still not ideal).
Jsonapi.org has cures for both [1] [2], so I'm not against at all
that but we mustn't stop just at changing the output format.

Please explain the other pain points in v2 besides [1] [2]

Speaking about the format change, since getting consistent with
katello is one of motivations for the change, I'd like to hear
from somebody with expertise in that field how difficult would be
to bend the UI code to use the new format. 

Just to make sure we actually won't unintentionally put more
obstacles in katello's way.

I assume you mean using RABL to generate the new output format when
keeping the same v2 controllers. IMHO, this would be a bigger headache
for both Koreman and Katello. This would still lead to v3 since there
are breaking changes. Maybe I don’t understand your question fully.

If we decide that jsonapi is the way to go for v3 I think it would
be better to implement it as part of the foreman core. We can
clearly mark it as devel preview with no guarantees, let it evolve
alongside with v2 and freeze when we're happy with it.

I don’t see the advantage of implementing a new api as part of core
until if/when it is stable and has community adoption.

[1] http://jsonapi.org/format/#crud-updating-relationships
<http://jsonapi.org/format/#crud-updating-relationships>
[2] http://jsonapi.org/format/#errors
<http://jsonapi.org/format/#errors>

    Here's some more links that could be helpful in addition
    to http://jsonapi.org/

    http://blog.arkency.com/2016/02/how-and-why-should-you-use-json-api-in-your-rails-api/
    <http://blog.arkency.com/2016/02/how-and-why-should-you-use-json-api-in-your-rails-api/>

    *JSON API <http://jsonapi.org/> is a great solution to not
    waste hours
    on reinventing the wheel in terms of your API responses
    design.* It is a
    great, extensible response standard which can save your time -
    both on
    the backend side and the client side. Your clients can
    leverage you’re
    using an established standard to implement an integration with
    your API
    in a cleaner and faster way.

    *Building a Rails API with the JSON API Spec
    *http://www.slideshare.net/SonjaPeterson2/building-a-rails-api-with-the-json-api-spec
    <http://www.slideshare.net/SonjaPeterson2/building-a-rails-api-with-the-json-api-spec>

    I look forward to hearing you feedback and receiving
    contributions to
    the repo.

    Joseph Magen (@isratrade)
    Red Hat

–
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
mailto:foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

12

>
>
> > I created a RFC for a plugin called foreman_api_v3
> >
> <rfcs/0000-foreman-api-v3.md at master · isratrade/rfcs · GitHub <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md&gt;&gt;
> and
> > the initial repo at GitHub - isratrade/foreman_api_v3
> <http://github.com/isratrade/foreman_api_v3&gt;
> > <https://github.com/isratrade/foreman_api_v3
> <https://github.com/isratrade/foreman_api_v3&gt;&gt;. If the community
> accepts,
> > I am happy to move this repo to theforeman/foreman_api_v3
> >
> > I choose to make this a plugin rather than a PR so it is optional for
> > users and doesn't affect the core code.
>
> Please consider calling it something else that won't cause confusion for
> users with Foreman's own API versioning.
>
>
> I can rename the plugin to foreman_jsonapi and change to version to
> v21 (meaning v2.1 since it inherits from v2), so it would look like this
>
> GET api/api/v21/hosts
>
> What do you think?
>
>
>
>
> –
> Dominic Cleal
> dominic@cleal.org <mailto:dominic@cleal.org>
>
>
>
>
>
> Hi all,
>
> I created a RFC for a plugin called foreman_api_v3
> <rfcs/0000-foreman-api-v3.md at master · isratrade/rfcs · GitHub
> <https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md&gt;&gt;
> and
> the initial repo at GitHub - isratrade/foreman_api_v3
> <http://github.com/isratrade/foreman_api_v3&gt;
> <https://github.com/isratrade/foreman_api_v3
> <https://github.com/isratrade/foreman_api_v3&gt;&gt;. If the community
> accepts,
> I am happy to move this repo to theforeman/foreman_api_v3
>
> I choose to make this a plugin rather than a PR so it is
> optional for
> users and doesn't affect the core code. The initial repo only
> includes
> the GET index and show actions. The PUT/PATCH/POST/DELETE
> actions
> need to be added. Also, there are currently no functional tests
> in the
> repo, so a lot more work needs to be done.
>
> Note that I inherited V2 so that V3 controllers look like this
>
> module Api
> module V3
> class DomainsController < V2::DomainsController
>
> but the response is changed.
>
> def index
> super
> render json: @domains,
> fields: @fields_hash,
> include: @include_array,
> each_serializer: DomainSerializer
> end
>
> For some background, the Foreman API v2 is more than 3 years
> old. When I
> implemented v2, I used conventions that I thought were good at
> the time.
> The katello had some slightly different conventions, and we weren't
> always in sync. This created some challenges for Satellite6 as a
> single
> RH product.
>
> The goal of JSON API is to create a standardization that is
> *Flexible,
> Consistent, and Fast *-- we can all agree with these goals.
>
>
> Thanks for sending that, Joseph. Jsonapi.org is nice specification
> and I like how it structures the data. The ability to include
> additional resources into the response is very handy and making the
> katello and foreman api consistent would be good too. But that alone
> wouldn't be enough to make switch to jsonapi. In my opinion main
> painpoints of the current api v2 are elsewhere. Firstly I miss
> adding associated resources without having to send all what's
> currently included. Second main issue is inconsistent error
> responses (we've improved with that but it's still not ideal).
> Jsonapi.org has cures for both [1] [2], so I'm not against at all
> that but we mustn't stop just at changing the output format.
>
>
> Please explain the other pain points in v2 besides [1] [2]

That was all. I can't think of anything else at the moment besides the
inconsistency that you mentioned.

>
> Speaking about the format change, since getting consistent with
> katello is one of motivations for the change, I'd like to hear from
> somebody with expertise in that field how difficult would be to bend
> the UI code to use the new format.
>
> Just to make sure we actually won't unintentionally put more
> obstacles in katello's way.
>
>
> I assume you mean using RABL to generate the new output format when
> keeping the same v2 controllers. IMHO, this would be a bigger headache
> for both Koreman and Katello. This would still lead to v3 since there
> are breaking changes. Maybe I don't understand your question fully.
>

I didn't mean anything about implementation side of the api (rabl vs.
serializers vs. something else). My note was rather about the output
format. Katello's UI relies fully on data from api. Therefore I wanted
to check how difficult it would be to switch the UI to the new api
format. Even if it's far in the future it would probably happen once.

Any change like this will need to go into v3, that's sure.

>
>
> If we decide that jsonapi is the way to go for v3 I think it would
> be better to implement it as part of the foreman core. We can
> clearly mark it as devel preview with no guarantees, let it evolve
> alongside with v2 and freeze when we're happy with it.
>
>
> I don't see the advantage of implementing a new api as part of core
> until if/when it is stable and has community adoption.
>

I think that it can actually attract the community more when it's in the
core and users/devs can start experimenting with it just by changing the
version in url. The result is more or less the same. The only difference
is in entry barriers (installing a plugin vs. changing number in url).

··· On 08/28/2016 07:49 AM, Joseph Magen wrote: > On Fri, Aug 26, 2016 at 10:47 AM, Dominic Cleal > wrote: > On 26/08/16 06:58, Joseph Magen wrote: > On Fri, Aug 26, 2016 at 11:36 PM, Tomas Strachota > wrote: > On 08/26/2016 07:58 AM, Joseph Magen wrote: 
[1] http://jsonapi.org/format/#crud-updating-relationships
<http://jsonapi.org/format/#crud-updating-relationships>
[2] http://jsonapi.org/format/#errors
<http://jsonapi.org/format/#errors>

    Here's some more links that could be helpful in addition
    to http://jsonapi.org/

    http://blog.arkency.com/2016/02/how-and-why-should-you-use-json-api-in-your-rails-api/
    <http://blog.arkency.com/2016/02/how-and-why-should-you-use-json-api-in-your-rails-api/>

    *JSON API <http://jsonapi.org/> is a great solution to not waste
    hours
    on reinventing the wheel in terms of your API responses design.*
    It is a
    great, extensible response standard which can save your time -
    both on
    the backend side and the client side. Your clients can leverage
    you’re
    using an established standard to implement an integration with
    your API
    in a cleaner and faster way.

    *Building a Rails API with the JSON API Spec
    *http://www.slideshare.net/SonjaPeterson2/building-a-rails-api-with-the-json-api-spec
    <http://www.slideshare.net/SonjaPeterson2/building-a-rails-api-with-the-json-api-spec>

    I look forward to hearing you feedback and receiving
    contributions to
    the repo.

    Joseph Magen (@isratrade)
    Red Hat

–
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
mailto:foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

13

Personally I like the API being a plugin that's treated like core in terms
of tests-must-pass, etc. The benefits I can think of at a quick glance:

  • all changes to routes and parameters in one uncluttered place
    (uncluttered meaning not a mix of other "core" PRs)
  • all changes to json body output format in one uncluttered place (big
    headache currently when data relied on changes)
  • plugin github ack/nack/mergers dedicated devs committed to not breaking
    api (these devs know the space and mission statement)

Negatives are:

  • have to submit two PRs, one to foreman one to api plugin, when changes
    impacting both
  • would other plugins (katello, rex, etc.) be encouraged/required to have
    separate github repo for their APIs too?

Writing a new api via a plugin is not a new idea as several of the
katello/Satellite-6 devs/users/customers have thought about doing this for
some time. I know Joseph's plugin arises from his work but it's great to
see this. I also like that it's based on jsonapi.org which would act as the
arbitrer of disagreements in style and such. Thanks Joseph for starting
this work!

··· On Mon, Aug 29, 2016 at 7:33 AM, Tomas Strachota wrote: 
If we decide that jsonapi is the way to go for v3 I think it would
be better to implement it as part of the foreman core. We can
clearly mark it as devel preview with no guarantees, let it evolve
alongside with v2 and freeze when we're happy with it.

I don’t see the advantage of implementing a new api as part of core
until if/when it is stable and has community adoption.

I think that it can actually attract the community more when it’s in the
core and users/devs can start experimenting with it just by changing the
version in url. The result is more or less the same. The only difference is
in entry barriers (installing a plugin vs. changing number in url).

14

It’s Y2K all over again.

David

··· On Mon, Aug 29, 2016 at 9:23 AM, Justin Sherrill wrote:

On 08/28/2016 01:49 AM, Joseph Magen wrote:

On Fri, Aug 26, 2016 at 10:47 AM, Dominic Cleal dominic@cleal.org wrote:

On 26/08/16 06:58, Joseph Magen wrote:

I created a RFC for a plugin called foreman_api_v3
https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md
and
the initial repo at GitHub - isratrade/foreman_api_v3
https://github.com/isratrade/foreman_api_v3. If the community
accepts,
I am happy to move this repo to theforeman/foreman_api_v3

I choose to make this a plugin rather than a PR so it is optional for
users and doesn’t affect the core code.

Please consider calling it something else that won’t cause confusion for
users with Foreman’s own API versioning.

I can rename the plugin to foreman_jsonapi and change to version to v21
(meaning v2.1 since it inherits from v2), so it would look like this

GET api/api/v21/hosts

what happens when we get to version 21 of the api which in my calculations
will occur around 2325? :slight_smile:

What do you think?

–
Dominic Cleal
dominic@cleal.org

On Fri, Aug 26, 2016 at 11:36 PM, Tomas Strachota < > tstrachota@redhat.comtstrachota@redhat.com> wrote:

On 08/26/2016 07:58 AM, Joseph Magen wrote:

Hi all,

I created a RFC for a plugin called foreman_api_v3
https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md
and
the initial repo at GitHub - isratrade/foreman_api_v3
https://github.com/isratrade/foreman_api_v3. If the community accepts,
I am happy to move this repo to theforeman/foreman_api_v3

I choose to make this a plugin rather than a PR so it is optional for
users and doesn’t affect the core code. The initial repo only includes
the GET index and show actions. The PUT/PATCH/POST/DELETE actions
need to be added. Also, there are currently no functional tests in the
repo, so a lot more work needs to be done.

Note that I inherited V2 so that V3 controllers look like this

module Api
module V3
class DomainsController < V2::DomainsController

but the response is changed.

  def index
    super
    render json: @domains,
           fields: @fields_hash,
           include: @include_array,
           each_serializer: DomainSerializer
  end

For some background, the Foreman API v2 is more than 3 years old. When I
implemented v2, I used conventions that I thought were good at the time.
The katello had some slightly different conventions, and we weren’t
always in sync. This created some challenges for Satellite6 as a single
RH product.

The goal of JSON API is to create a standardization that is *Flexible,
Consistent, and Fast *-- we can all agree with these goals.

Thanks for sending that, Joseph. Jsonapi.org is nice specification and I
like how it structures the data. The ability to include additional
resources into the response is very handy and making the katello and
foreman api consistent would be good too. But that alone wouldn’t be enough
to make switch to jsonapi. In my opinion main painpoints of the current api
v2 are elsewhere. Firstly I miss adding associated resources without having
to send all what’s currently included. Second main issue is inconsistent
error responses (we’ve improved with that but it’s still not ideal).
Jsonapi.org has cures for both [1] [2], so I’m not against at all that
but we mustn’t stop just at changing the output format.

Please explain the other pain points in v2 besides [1] [2]

Speaking about the format change, since getting consistent with katello is

one of motivations for the change, I’d like to hear from somebody with
expertise in that field how difficult would be to bend the UI code to use
the new format.

Just to make sure we actually won’t unintentionally put more obstacles in

katello’s way.

I assume you mean using RABL to generate the new output format when
keeping the same v2 controllers. IMHO, this would be a bigger headache for
both Koreman and Katello. This would still lead to v3 since there are
breaking changes. Maybe I don’t understand your question fully.

If we decide that jsonapi is the way to go for v3 I think it would be
better to implement it as part of the foreman core. We can clearly mark it
as devel preview with no guarantees, let it evolve alongside with v2 and
freeze when we’re happy with it.

I don’t see the advantage of implementing a new api as part of core until
if/when it is stable and has community adoption.

[1] JSON:API — Latest Specification (v1.1)
[2] JSON:API — Latest Specification (v1.1)

Here’s some more links that could be helpful in addition

to http://jsonapi.org/

http://blog.arkency.com/2016/02/how-and-why-should-you-use-j
son-api-in-your-rails-api/

JSON API http://jsonapi.org/ is a great solution to not waste hours
on reinventing the wheel in terms of your API responses design. It is a
great, extensible response standard which can save your time - both on
the backend side and the client side. Your clients can leverage you’re
using an established standard to implement an integration with your API
in a cleaner and faster way.

*Building a Rails API with the JSON API Spec
*http://www.slideshare.net/SonjaPeterson2/building-a-rails-a
pi-with-the-json-api-spec

I look forward to hearing you feedback and receiving contributions to
the repo.

Joseph Magen (@isratrade)
Red Hat

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

15

Per the feedback, I made the following 2 changes:

  1. renamed the plugin to foreman_jsonapi
    <https://github.com/isratrade/foreman_jsonapi&gt;
  2. changed the version to v21. Now that the version is not in the gem name
    and directory structure, it will be much easy to change the version to v3
    (or whatever, v22, v25, v31, etc) at a later time.
··· On Mon, Aug 29, 2016 at 2:54 PM, Tom McKay wrote:

On Mon, Aug 29, 2016 at 7:33 AM, Tomas Strachota tstrachota@redhat.com > wrote:

If we decide that jsonapi is the way to go for v3 I think it would
be better to implement it as part of the foreman core. We can
clearly mark it as devel preview with no guarantees, let it evolve
alongside with v2 and freeze when we're happy with it.

I don’t see the advantage of implementing a new api as part of core
until if/when it is stable and has community adoption.

I think that it can actually attract the community more when it’s in the
core and users/devs can start experimenting with it just by changing the
version in url. The result is more or less the same. The only difference is
in entry barriers (installing a plugin vs. changing number in url).

Personally I like the API being a plugin that’s treated like core in terms
of tests-must-pass, etc. The benefits I can think of at a quick glance:

  • all changes to routes and parameters in one uncluttered place
    (uncluttered meaning not a mix of other “core” PRs)
  • all changes to json body output format in one uncluttered place (big
    headache currently when data relied on changes)
  • plugin github ack/nack/mergers dedicated devs committed to not breaking
    api (these devs know the space and mission statement)

Negatives are:

  • have to submit two PRs, one to foreman one to api plugin, when changes
    impacting both
  • would other plugins (katello, rex, etc.) be encouraged/required to have
    separate github repo for their APIs too?

Writing a new api via a plugin is not a new idea as several of the
katello/Satellite-6 devs/users/customers have thought about doing this for
some time. I know Joseph’s plugin arises from his work but it’s great to
see this. I also like that it’s based on jsonapi.org which would act as
the arbitrer of disagreements in style and such. Thanks Joseph for starting
this work!

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