On 08/28/2016 07:49 AM, Joseph Magen wrote:
On Fri, Aug 26, 2016 at 10:47 AM, Dominic Cleal <[email protected]
<mailto:[email protected]>> 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
<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.
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
[email protected] <mailto:[email protected]>
On Fri, Aug 26, 2016 at 11:36 PM, Tomas Strachota <[email protected]
<mailto:[email protected]>> 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]
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).
[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 [email protected]
<mailto:[email protected]>.
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 [email protected].
For more options, visit https://groups.google.com/d/optout.
