On Fri, Aug 26, 2016 at 10:47 AM, Dominic Cleal <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> > 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 > domi...@cleal.org > On Fri, Aug 26, 2016 at 11:36 PM, Tomas Strachota <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> >> 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. > > [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 >> >> > -- 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.
