4 ms·

I’ve only been a consumer of a GraphQL API, so I don’t know what it’s like to maintain, but I mostly enjoyed using it. Of course the documentation on some kind

by awongh 2y ago

I’ve only been a consumer of a GraphQL API, so I don’t know what it’s like to maintain, but I mostly enjoyed using it. Of course the documentation on some kinds of query syntax was too sparse, (this is for Shopify) but I could see how it might be nice for certain kinds of cases. If you run a platform it might be a good option to offer in your API. For shopify afaik there are equivalent calls in both REST and graphql so you have options.

pas 2y ago
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?
- albertgoeswoof 2y ago
  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
  - pas 2y ago
    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) :) )
  - rezonant 2y ago
    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.
    - tadfisher 2y ago
      There is a standard, it's called GraphQL: https://spec.graphql.org/October2021/#sec-Schema-Introspection 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.
  - amne 2y ago
    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.
- awongh 2y ago
  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.
vdfs 2y ago
> equivalent calls in both REST and graphql so you have options. It's not that simple, new features are add to GraphQL only, some other things are REST only,some APIs work differently (like product search by title, in REST it have to be an exact match, in GQL it can be partial match)
- rezonant 2y ago
  This has been my experience when integrating with a vendor's APIs where they've been bit by the GraphQL bug. They have a full featured, stable and easy to use REST API, and then a poorly implemented GraphQL solution that doesn't cover all the use cases of the original API, and new features only appear in the GraphQL schema, so you have to be stuck using both and it's a horrible experience. I'm also not personally a fan of having my API queries on the frontend span multiple lines for things that with a good REST design with OpenAPI are a single method call, but all too often the calls I would need to make to the vendor's GraphQL API were exactly this: did not make use of any of GraphQL's query features, and were effectively just RPC calls.

by awongh 2y ago

pas 2y ago

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?

albertgoeswoof 2y ago
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
- pas 2y ago
  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) :) )
- rezonant 2y ago
  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.
  - tadfisher 2y ago
    There is a standard, it's called GraphQL: https://spec.graphql.org/October2021/#sec-Schema-Introspection 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.
- amne 2y ago
  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.
awongh 2y ago
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.

vdfs 2y ago

> equivalent calls in both REST and graphql so you have options. It's not that simple, new features are add to GraphQL only, some other things are REST only,some APIs work differently (like product search by title, in REST it have to be an exact match, in GQL it can be partial match)

rezonant 2y ago
This has been my experience when integrating with a vendor's APIs where they've been bit by the GraphQL bug. They have a full featured, stable and easy to use REST API, and then a poorly implemented GraphQL solution that doesn't cover all the use cases of the original API, and new features only appear in the GraphQL schema, so you have to be stuck using both and it's a horrible experience. I'm also not personally a fan of having my API queries on the frontend span multiple lines for things that with a good REST design with OpenAPI are a single method call, but all too often the calls I would need to make to the vendor's GraphQL API were exactly this: did not make use of any of GraphQL's query features, and were effectively just RPC calls.