Can you elaborate on lack of syntax docs? As far as I understand one of the big big huugge benefits of GraphQL is that you get the strongly typed schema via the introspection query, so you can build queries with some confidence, that as long as the schema (version) is the same it should be syntactically okay. What did Spotify do compared to this?
I think it wasn't just the schema structure, it was the API abstractions implemented in the schema.
If I remember correctly it was something about Shopify discounts, which can be applied multiple times and across different modalities- percent, dollar amount, etc. and what those were called in the API, and how they were represented and to which object they were applied to.
Then once I had figured that out, then understanding how to construct the query.
But of course my problem was more from the point of view of, "I just want to get x done". As the consumer of the API I wasn't as concerned about fully understanding the entire set of abstractions and schemas.
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
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.
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) :) )
