My AshGraphql journey
I'm trying to integrate Ash into an existing Phoenix project. I can see amazing work has been put into this project. Even so, my journey so far has been painful.
I needed to design a GraphQL query that returns a list of things. They first question that arose was: What does the GraphQL query look like for a given Ash GraphQL query definition? Let's say I want to define a query that returns a list of tickets (as from the documentation example). So see in the Ash GraphQL Getting Started page, I can define a query like this:
A reasonable guess is that this generates a GraphQL query called
list_tickets. And writing a test for it shows that in fact, it does. I know that in GraphQL, the successful response JSON will include a key list_tickets that contains the array of tickets. Ok so far, but it would be helpful to see an example of the GraphQL query, so that I can be confident, and not assume.
Now, what if I need the list_tickets query to take a few query parameters? Where in the documentation does it give me information to make that happen? Looking at the example above again, what does the :read argument mean? I see above it in the example, there is another query, read_one :most_important_ticket, :most_important, and the second argument is :most_important. What does this mean?
To be continued in the comments...11 Replies
...Continued from original post
I assume that information is in API docs, so I look at the left navigation menu to look for anything related to GraphQL. I don't see anything, but I notice the blue banner, "See the full range of Ash libraries for authentication, soft deletion, GraphQL and more". I click on that and enable AshGraphql. This adds some AshGraphql-related items in the left navigation, but none them cover AshGraphQL queries. Finally, I search for "graphql" in the documentations' search function, and come across an entry for "ash_graphql > AshGraphql Api > graphql", and there I find the API doc for AshGraphql queries. Drilling into that page, I find the documentation on that second argument of
list/2. It's an action. Okay. So an action is one of those things defined under the actions section in my resource. And one of the actions is :read. So it sounds like I need to define a new action.
So, I define an action to use with my GraphQL. Now what do the arguments look like in the actual GraphQL query? Are they wrapped under a single GQL type, or are they separate GQL arguments? The documentation doesn't say. After some experimentation, it turns out it's the latter.
Now I want to add pagination. What is the GraphQL response data shape for that case? What are the GQL query arguments? Where is the documentation that talks about that? I can't find it.
I think Ash's documentation system is impressive, and there is a ton of documentation. It looks like a ton of work was put into all of this. It's just that even so, I'm still having trouble getting the information I need. Is there a tip or technique to make the process smoother? I am happy to help add to the documentation.Definitely need more guides that explain how the graphql is generated from resource actions. We're doing a lot of that work for phoenix & ash core right now, but ash_graphql is going to need that same treatment for sure.
I think it hasn't been as much of a problem because as you build out your actions you can explore them in the playground, and with Ash the API is generally playing second fiddle to the resource interface. Thats not to say that its not important to know how it generates what it generates, and that we don't need docs because we obviously do 😄
Realistically, a document explaining what read actions/mutations look like given certain conditions on the action (they are quite consistent, so there isn't that much to know on that front) is I think the main thing we need.
And it can go through how pagination changes the response, the treatment we do for enum types (and now union types since there is a union type in core that is supported in ash_graphql), how we determine the filter/sort types, all that stuff.
and to answer a concrete question, in:
list :list_tickets, :read :list_tickets is the name of the generated graphql query, and :read is the action that we call on the resource. That action is what drives all of the generation
ah, nvm you already realized that as you said in your comment 😄Yeah, those suggestions sound great. I'd be happy to contribute adding documentations for those, as long as I have the time budget for it.
Well, I'm more than happy for PRs on that front, and even if its as simple as starting a document in
documentation/topics/graphql-generation.md with some basic learnings. Doesn't have to be an all or nothing type thing.Okay, great. That gives me a place to start. Thanks so much for this amazing framework!
Thanks for the kind words 🙇 We're finally starting to get to the really cool stuff with things like
ash_authentication, but after focusing on the tech for a few years we're definitely in a phase where we need to focus on the people and experience as well 😄I just wanted to chime in here to mention that the playground (GraphiQL) is very helpful here. Using introspection it shows you all available queries and mutations, arguments and response types, and allows you to create queries with autocomplete. Setting it up is documented in the getting started guide at https://www.ash-hq.org/docs/guides/ash_graphql/latest/tutorials/getting-started-with-graphql#using-plug
@Zach Daniel When you suggested creating documentation in
documentation/topics/graphql-generation.md, is that for the Ash project, or the AshGraphql project? I have a document ready to make into a PR.The ash graphql project 🙂
Excited to see it!!!
Here's the new documentation page!!!
https://ash-hq.org/docs/guides/ash_graphql/latest/topics/graphql-generation
Looks great! Great work 🥳