> > 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
> > <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 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>
>> and
>> the initial repo at 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.
···
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
[2] 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-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
