On 08/28/2016 01:49 AM, Joseph Magen wrote:
On Fri, Aug 26, 2016 at 10:47 AM, Dominic Cleal <domi...@cleal.org
<mailto:domi...@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
<https://github.com/isratrade/rfcs/blob/master/0000-foreman-api-v3.md>>
and
> the initial repo atgithub.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 happens when we get to version 21 of the api which in my
calculations will occur around 2325? :)
What do you think?
--
Dominic Cleal
domi...@cleal.org <mailto:domi...@cleal.org>
On Fri, Aug 26, 2016 at 11:36 PM, Tomas Strachota
<tstrach...@redhat.com <mailto:tstrach...@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+unsubscr...@googlegroups.com
<mailto:foreman-dev+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
