GraphQL as api v3

[ohadlevy]

Hi There,

So I’ve been exposed recently to graphql (https://facebook.github.io/relay/docs/en/thinking-in-graphql.html), and while being on a hype etc - it does seem like a good canidate for api v3 we have been discussing in the past.
Seeing a few demos of it online, and it seems to be well received, there was a recent discussion on IRC on this subject and I was wondering if anyone already had experience with it

one of my main motivations (besides of course making it easier to consume) is to reduce the client side code complexity by making multiple api calls, parsing json responses and normalizing data (something in the light of https://dev-blog.apollodata.com/reducing-our-redux-code-with-react-apollo-5091b9de9c2a).

I’ve seen a POC in manageIQ which seems like a good start at https://github.com/chrisarcand/manageiq-graphql

any thoughts?

[iNecas]

I know @TimoGoebel had a look, as he filed an issue in redmine Feature #22109: Foreman should support a graphql api - Foreman

[TimoGoebel]

I really like the idea, actually have started to play with it a bit:

Redmine-Issue:

Tracker #22109: Foreman should support a graphql api - Foreman

My WIP code:

Commits · timogoebel/foreman

The code is not really mature, but it actually produced a working api. It’s basically still missing two things:

1. It needs to handle permissions correctly.
2. It needs a way to define the schema. There are different approaches for this. The first one is to just define the schema manually with the graphql dsl. The second possibility is to define the schema in rails models itself. That might reduce the number of redundant data. graphql_model_mapper is an example of a gem that makes this possible.

I think, graphql could be the single place where we’d have to define if an attribute is e.g. required or not. I think @Marek_Hulan might like this as he suggested to look into some alternatives to how we do this in the react code right now.

[ik5]

On my last work place I used GQL a lot, it has a lot of very good usage, but it is sometimes overkill for others, so it is best to define what usage should it take imo.

For example, doing a REST call like so to get exact structure, many times simpler then GQL:

GET /list/names

However, when wanting to pass additional information, for example pagination, sort information (by fields and ASC/DESC), then GQL is getting simpler.

Also calling several entry points, and getting only the needed objects, and their fields, make it easier in GQL then REST.

[Tomas_Strachota]

I have no experience with GraphQL at all, but I like the idea in general.

@TimoGoebel would migrating to GQL for v3 mean we could get rid of rabl?

[TimoGoebel]

@Tomas_Strachota: Yes, if we drop v1 and v2 ofc.

[Bryan_Kearney]

How would this query language play with the search API which is a defacto query language?

[TimoGoebel]

As far as I know, a developer would not need to use the scoped_search query language anymore to query objects in most cases. But it can still be used for actual (user faced) searching if we want to, graphql is just the wrapper around the query and specifies how the result should look. The graphql docs have an example of how a search query could look.

[Tomas_Strachota]

I guess that it would also mean to re-think how we document the api, right? At the moment ApiPie probably wouldn’t work with GQL. Are there any documentation standards for GQL?
Hammer currently relies heavily on the exported json docs from ApiPie.

[iNecas]

Generic question: should we consider this for

1. UI only internal backend API
2. One stable API serving all UI, CLI and public API itself
3. Two different APIs, one private for for UI, one for public

From what I’ve seen so far, the option 2 can lead to either hard to use in
UI
or unstable for public API. Is GQL addressing this?

Going UI only for now might be a good start before committing to someting
more stable,
that APIv3 should be.

– Ivan

po 8. 1. 2018 v 18:22 odesílatel Tomas Strachota <
noreply@community.theforeman.org> napsal:

[chrisarcand]

I guess that it would also mean to re-think how we document the api, right? At the moment ApiPie probably wouldn’t work with GQL. Are there any documentation standards for GQL?

Yes, and one of the motivating factors behind ManageIQ building our V2 API with it.

GraphQL is introspective, which means it can give metadata about it’s schema via the type system. This means that’s it’s almost entirely self-documenting.

At the moment ApiPie probably wouldn’t work with GQL.

Nope, certainly not.

[chrisarcand]

As @ohadlevy knows, I recently gave a presentation on GraphQL for ManageIQ internally at Red Hat. I’m reviewing this to see if I might make it publicly available for anyone who’s interested in it, here. Thanks for your patience.

[ehelms]

Creating a new version of our API is long overdue based on what we’ve learned over the years about user, UI, CLI and other interface requirements (e.g. Ansible modules) and a big undertaking. That being said, I’m a fan of GraphQL after listening to a few podcasts about it. The more I listened the more what it brings just clicks for what I’ve heard talked about over the years around wishes that our API supported (or made easier) for users and developers.

I’d prefer not to have two separate APIs for UI and API. This is essentially re-creating UI controllers in a Single Page Application world. If anything, we can start a V3 API that is used initially by the UI and is therefore a “lab” with the intent of releasing it as the next supported API version.

I think this is a good first step foray into could this be a good idea. The next step I’d like to see is building out an RFC for the API to ensure we cover all the requirements developed over the years.

[ik5]

Are there any documentation standards for GQL?
here it is: http://graphql.org/

A query looks like this:
Simple:

{ 
   get_all_users {
     user_name
     user_email
   }
}

With Parameters:

{
get_users(skip:0 limit: 25, email_like: “theforeman.org”, sort: “-1”) {
user_name
user_email
}
}

mutation of data (POST, DE:ETE etc…):

mutation {
   save_user(name: "foo", email: "example@theforeman.org") {
      success
   }
}

advanced saving:

mutation {
   save_user1:save_user (name: "foo", email: "example@theforeman.org") {
      success
   }

  save_user2:save_user(name: "bar" email:"bar.example@theforeman.org") {
    success
  }
}

The return is a JSON structure, only with the fields you requested.

[ohadlevy]

As far as I know, a developer would not need to use the scoped_search query language anymore to query objects in most cases. But it can still be used for actual (user faced) searching if we want to, graphql is just the wrapper around the query and specifies how the result should look. The graphql docs have an example of how a search query could look.

I think it would be worthwhile to be able to reuse scoped search language, its de-facto our existing search api, and it fits very nicely to AR models. I agree its harder to reuse it for non AR relations, but to some degree we already solved it via the ext_search option.

Also, if we don’t use it, we need to solve a major usability with hammer, as it expose that search as well.

[mbacovsky]

Are there any documentation standards for GQL?

I looked at the GraphQL tutorial and it seems it has powerful introspection. The service schema can be queried as any other resource. It provides available fields including types, descriptions and references and much more.

Also it seems the queries can be cached so it could solve some problems and performance issues we have with apipie cache.

At a first glance I like what GQL offers and there are several features that could make our CLI more lightweight. Definitely worth giving it a try.

I have a few questions with regard to our CLI expectations.

• performance. Especially of the schema description of huge and complex and dynamic model we end up with. How does it affect server startup? Any experience here?
• extensibility from within plugins - can plugins/facets extend the types and add new attributes?
• localization - our CLI is generated dynamically and we rely on the schema description. Currently we download schema description for the locale the CLI runs with. Would something similar be possible with GQL? Seem so, but again I’m concerned about performance.

I assume these are so specific to our project that we will have to figure out ourselves…

[Bryan_Kearney]

If this comes down to users do scoped search, devs do GQL. Or, users can do either, then I am good. I think folks are using search syntax as a way to automate and I would hate to loose it completely going form v2 to v3.

[TimoGoebel]

I had some more time and played more with graphql. The code now supports authentication and authorization and included example code how scoped search integrates with graphql. It does not yet contain mutations.

wip

[ohadlevy]

I played with your branch - nice using the explorer does make it pretty simple to understand how to generate queries - I like it

Could you add a few more examples? like related data (e.g. host with subnets/models etc)? it would be interesting to compare performance as well.

What are your next steps?

Thanks!

[Walden]

Finally had a chance to look into GrahpQL more and I like what I see so far. Any thoughts on what a timeline for a v3 of the API would look like?