4 ms·
Compare to REST, GraphQL have many advantages. However, IMO the tooling is still not there yet (Especially the caching, batching/data loaders are PITA). One of
by knlam 6y ago
Compare to REST, GraphQL have many advantages. However, IMO the tooling is still not there yet (Especially the caching, batching/data loaders are PITA).
One of the biggest selling point rarely come up is that you get the API docs for free through the playground. No more Swagger bad API
- capableweb 6y agoYou might get reference documentation for free but you don't get real, proper documentation that actually teaches the user anything. So basically the biggest selling point (for you) for GraphQL is the same as biggest selling point for Swagger? The quality of those reference docs is more based on the developer writing them, rather than the technology who allows it.
- diveanon 6y agoCan you define "real proper documentation"?
- capableweb 6y agoI'm only contrasting it to reference documentation. So in the case of GraphQL, you get reference documentation that shows you exactly how it can be used. But it won't show you _why_ you'll use it, or _what_ it can be used for. It also doesn't show what invariants you're working with, or in what way the endpoints are otherwise restricted with. Real proper documentation is not just a list of endpoints and their attributes but explanations of those as well as other things.
- diveanon 6y agoI don't see how that is in any way specific to REST or GQL.
- capableweb 6y agoThe original comment said "One of the biggest selling point rarely come up is that you get the API docs for free" while comparing it to Swagger. Both GraphQL and Swagger gives the same ability to generate API reference documentation. So how is that the "biggest selling point" of GraphQL when it's not even new in the ecosystem?
- diveanon 6y agoBecause swagger docs are defined via proprietary yaml definitions whereas graphiql exposes a more useful interface that is actually derived from your code, which in most cases is automatically generated from your DB model. I've written a lot of swagger docs over the years, GQL is a massive improvement.