You can traverse the docs as you write the code with the right client app, and this solves 90% of the "docs are bad" complaints about any given GraphQL API.
GraphQL APIs are many things. Poorly documented is not one of them.
How does this differ from controlling the API and frontend with rest/json? You can shape the data in any which way you want including nested relations, i.e get me a user with all their posts.
Unless you are $MEGA_CORP scale it really doesn't feel like its worth the investment.
But with your nested relations example, wouldn't getting a user always return its nested relations?
- what if a post has its own nested relations? some pages might need just a user's posts without the posts nested relations and some pages might need them all.
- what if a page only needs user info and doesn't need the user's posts?
With both similar scenarios, you'll need a way to communicate that to the user endpoint so it knows when and when not to return its nested relations and how deep. You could do that with query params sure but IMO that's a workaround with what the frontend really needs, a declarative way to let the API know that for this specific request, this is the exact data I need and its shape. No more no less. With also the flexibility to get everything in another request. You could also do nested resources with REST /user/posts/categories and /user/posts/etc but then that's multiple calls to get what you need. With GraphQL, these scenarios can be solve with a single API endpoint and single requests to it.
Also the productivity gain from GraphQL is actually more apparent in smaller eng org compared to a massive one. That's because for GraphQL to be at its best it requires the people implementing the schema to work closely with frontend folks. Even better if they are full stack and are the same people.
A central point of REST is that any resource (e.g., user) can support an unlimited number of different representations. This isn't just true on the level of, say, XML vs. JSON but also formats which embed and do not embed subordinate/related entities.
> You could do that with query params sure but IMO that's a workaround with what the frontend really needs, a declarative way to let the API know that for this specific request, this is the exact data I need and its shape.
How are query strings a workaround and not a declarative mechanism?
(I mean, it would be better if HTTP had a verb that was like GET with a body so that you could define one or more media types that could be used to specify details of the resource representation sought, and that's what the QUERY draft [0] is about. And I can see the view that query parameters are a workaround for the lack of a QUERY method. But that's a slightly different story.)
[0] https://www.ietf.org/id/draft-ietf-httpbis-safe-method-w-bod...
I'm aware but how does that work in practice? actual implementation wise. What does the formats to include or exclude related/nested entities look like? how do clients use these formats? also how does supporting embedding multiple levels of nested entities work in this pattern? I asked all of this because I don't think I've seen this implemented well without a convoluted in-house implementation of a query language like GraphQL's shoehorned into query strings. A specification is only as good as the people implementing them.
> How are query strings a workaround and not a declarative mechanism?
In simple cases, they can be. But they are very limited. How do you express in query strings the exact data fields, nested entities, and shape the client wants to retrieve? (this question might be related to the questions above)
> I mean, it would be better if HTTP had a verb that was like GET with a body so that you could define one or more media types that could be used to specify details of the resource representation sought, and that's what the QUERY draft [0] is about.
I didn't know about the QUERY draft. This is very interesting and would be great to have in HTTP. This is a good example of the gaps in HTTP that technologies like GraphQL are trying to fill.
It's graphql, it's self-documenting.
I despise the programmer's hubris around the concept of self-documenting things especially as I'm running into so many examples of programmers who don't actually sit down and read library code these days. And especially despise apologist management that make excuses for them.
We didn't get where we are by not writing manuals and knowing what we're doing under the hood. Abstraction is fine once you're actually aware of what you're boundary conditions are.
Wow, not a fan.
Everything was poorly documented (both in the actual API and GraphQL itself) and fussy, and required a huge amount of code to get anything done. Nesting and union types were really hard to figure out.
Frankly, the more I used it, the less I liked it.
Is it possible that the API design was bad? Sure. But my googling to figure things out didn't make me think they were doing anything out of the ordinary at all for GraphQL.