Hacker News Reader

Comment by albertgoeswoof | Hacker News Reader

This is one of the problems with graphql, there are no docs because the schema is all you need. But that assumes the schema is logical and consistent, which it rarely is.

It also means you need to be an expert in the tooling to figure it out, so just dropping in to a graphql api is so frustrating compared to plain old rest

View on HN

Also there is no standard for exposing the schema, and sometimes there isn't a schema at all. Sometimes a vendor will have the schema downloadable from their dev docs, sometimes it will be an endpoint that serves it up, and sometimes they just don't give it to you and expect you to use GraphQL Explorer directly to discover what you can do. When I encountered this I figured surely GraphQL Explorer must be fetching the schema, but I guess this is not always the case, as I never was able to get a complete schema that worked with the tooling. For that vendor, there was no way to generate client code for the schema using one of the many GraphQL client library generator frameworks.

There is a standard, it's called GraphQL: https://spec.graphql.org/October2021/#sec-Schema-Introspecti...

I'm not saying the service isn't a true Scotsman, but a service that calls its API "GraphQL" but doesn't respond to introspection queries isn't really serving GraphQL.

This was also my issue with APIPlatform (php/symfony ecosystem tool to generate REST endpoints for your Doctrine entities). Nice OpenAPI spec autogenerated at first glance but very sterile and hard to use once you really needed to understand the business reasons behind some normalization choices.

this was also the problem with WSDL and REST itself, and so on. of course there are things that make sense to be in-band .. but there are things that have to be communicated out-of-band (just as REST doesn't say anything about what to do with a specific content type OpenAPI and GraphQL doesn't worth much with empty description fields, though I'd argue still much better than getting a .doc file named API_doc-Finalv2(1) :) )

Reply on news.ycombinator.com