4 ms·

I recently had to consume a GraphQL API (Shopify's) after being interested in it for some time. Wow, not a fan. Everything was poorly documented (both in the

by larrik 4y ago

I recently had to consume a GraphQL API (Shopify's) after being interested in it for some time. 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.

mikewhy 4y ago
> Everything was poorly documented It's graphql, it's self-documenting.
- larrik 4y ago
  That's probably true after you are comfortable in it, but as someone trying to wrangle it for the first time it was rather mystifying for anything outside of trivial usecases.
  - mikewhy 4y ago
    They have an interactive playground with auto complete. You can point and click to build a query.
- salawat 4y ago
  If you're the executing machine maybe. 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.
pandesal 4y ago
GraphQL APIs that are public will usually have a less than optimal dev experience because it has to consider general and unknown use cases. GraphQL shines when you control the API and the frontends that consume it. This is mostly because the schema design will reflect the exact use cases the frontend needs. So the data and its shape and its mutations are exactly what the frontend needs. You can't really do that for public APIs because you don't really know or predict the use cases for 3rd party frontends.
- imran-iq 4y ago
  > GraphQL shines when you control the API and the frontends that consume it. 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.
  - mikewhy 4y ago
    The company I'm with is decidedly smaller than mega corp and graphql has been a huge boon for productivity. The API team will hit product with some word vomit that the page they want to build is impossible due to service A not being able to talk to service B, meanwhile the frontend team just implements a resolver and is done with it.
  - pandesal 4y ago
    You can definitely shape the data in any way you want with REST. You can find parallels with GraphQL features and REST and you can argue for either way because its 1:1 comparison. Comparing technologies requires looking both at a 1:1 level and as a whole. 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.
TameAntelope 4y ago
Every single time I've heard "GraphQL is poorly documented", it's from someone who doesn't know about Insomnia [0] (or something like it) and autocompletion. 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. [0] https://insomnia.rest/products/insomnia https://insomnia.rest/products/insomnia
- dimgl 4y ago
  I gotta say, if you need another tool to make your tool somewhat usable, that tool probably isn't very good in the first place? Lol
  - TameAntelope 4y ago
    You can't use a nail without a hammer.
  - dylanowen 4y ago
    You can read your open api spec or wsdl without a tool but why would you? It's the same for the graphql schema.
- larrik 4y ago
  Well, it's completely true that I hadn't heard of Insomnia. I wish I had.

by larrik 4y ago

mikewhy 4y ago

> Everything was poorly documented It's graphql, it's self-documenting.

larrik 4y ago
That's probably true after you are comfortable in it, but as someone trying to wrangle it for the first time it was rather mystifying for anything outside of trivial usecases.
- mikewhy 4y ago
  They have an interactive playground with auto complete. You can point and click to build a query.
salawat 4y ago
If you're the executing machine maybe. 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.

pandesal 4y ago

GraphQL APIs that are public will usually have a less than optimal dev experience because it has to consider general and unknown use cases. GraphQL shines when you control the API and the frontends that consume it. This is mostly because the schema design will reflect the exact use cases the frontend needs. So the data and its shape and its mutations are exactly what the frontend needs. You can't really do that for public APIs because you don't really know or predict the use cases for 3rd party frontends.

imran-iq 4y ago
> GraphQL shines when you control the API and the frontends that consume it. 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.
- mikewhy 4y ago
  The company I'm with is decidedly smaller than mega corp and graphql has been a huge boon for productivity. The API team will hit product with some word vomit that the page they want to build is impossible due to service A not being able to talk to service B, meanwhile the frontend team just implements a resolver and is done with it.
- pandesal 4y ago
  You can definitely shape the data in any way you want with REST. You can find parallels with GraphQL features and REST and you can argue for either way because its 1:1 comparison. Comparing technologies requires looking both at a 1:1 level and as a whole. 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.

TameAntelope 4y ago

Every single time I've heard "GraphQL is poorly documented", it's from someone who doesn't know about Insomnia [0] (or something like it) and autocompletion. 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. [0] https://insomnia.rest/products/insomnia https://insomnia.rest/products/insomnia

dimgl 4y ago
I gotta say, if you need another tool to make your tool somewhat usable, that tool probably isn't very good in the first place? Lol
- TameAntelope 4y ago
  You can't use a nail without a hammer.
- dylanowen 4y ago
  You can read your open api spec or wsdl without a tool but why would you? It's the same for the graphql schema.
larrik 4y ago
Well, it's completely true that I hadn't heard of Insomnia. I wish I had.