Hey folks! I want to start off by echoing @Liam-Shopify here - we truly appreciate all the feedback and suggestions. We care deeply about our GQL API and strive for it to be the canonical example for performance and DX. We’ve made a bunch of improvements over the last year (Dev Assistant, enhanced docs, improvements to rate limits / query filters), but as this thread shows, we still have a ways to go.
Extremely difficult to build reusable functions that work with different types of data since the nodes (field names) vary widely. Many calls that are made to products, pages, articles and collections must be built totally separately.
Field names are different, missing and/or lacking coherent SYMMETRY and logic (with the rest api, and between end points WITHIN the graph api).
I was forced to build a “bridge” module to combine data from Rest and Graph (ie. body_html -><-- descriptionHtml). It is also a requirement to build a type of module that converts Graph data (particularly property names) to Rest data.
One of the constant trade offs we face is evolving the API to reflect our learnings while limiting breaking changes. When the GraphQL API was first introduced, we used it as a way to clean up the DX and and make the API more intuitive. However, this has led to further divergence between the REST and GQL APIs over the years, making migration a challenge.
We anticipated this, and have been investing in tooling to ease that transition from REST to GQL. In the REST documentation, we’ve mapped each of the fields to their GQL equivalents, and we’ve trained the Dev Assistant to convert REST APIs to GraphQL. If anyone has suggestions on how we can further simplify migration, we’re all ears!
The requirements of edges vs nodes vs node (or no explicit node) is beyond comprehension and can only be figured out by running specific tests.
Using Graph field naming as the new ground truth is highly problematic because it lacks consistency across different end points, unlike the Rest Api.
I think you will need to use GraphQL Fragments
Conditionals are definitely interesting. These concepts should be more easily found in the docs!
While we do document a lot of these concepts (connection edges, aliasing, fragments), I agree that they’re widely dispersed and hard to find.
I’ve flagged this to the relevant teams - we will work on better documenting these capabilities and making them more easily discoverable.
There are solutions that are possible using the Rest Api which are not possible with the Graph Api - and some may be possible but the workarounds are insane (such as the productsCount issue).
GraphQL and RestAPI are not at feature parity.
Agreed that the lack of parity for counts is disappointing. We have a team working on this, and we’re hoping to have a solution ready for the 2025-04 API release. To provide some context on why this is challenging - it is extremely complex to do count queries with dynamic filters at Shopify scale performantly. In the meantime, I’m not sure if this will suffice for your use case, but we did release an update to allow uncapped exact counts for products without filtering.
If there are other areas where you feel feature parity is lacking, please let us know. We attempted to address all known gaps before announcing REST as legacy, but there may be a few that slipped through the cracks.
The Graphql documentation is also poorly written compared to the Rest Api.
it says to use “originalSource” when updating an image. This is not correct, the actual field to use is “previewImageSource”. Your staff was made aware of this already and apparently its nobodys job to update the docs.
Could you share a code snippet of the specific mutation you were attempting? This will help me better understand the issue.
Additionally, if y’all have other examples where you feel the documentation quality is lacking, do share. We want to make sure the docs are clear and easy to use.