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
The code is not really mature, but it actually produced a working api. It’s basically still missing two things:
It needs to handle permissions correctly.
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.
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 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.
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.
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.
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.
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…
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.
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.