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.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.
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] 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-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
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.
For more options, visit https://groups.google.com/d/optout.
