Migrating from REST to GraphQL
In this section we’ll take a look at how certain concepts are handled in GraphQL.
Nodes represent objects such as Order, and contain data in fields.
Edges are links between two related nodes. These allow you to make nested queries, gathering information from multiple nodes by traversing the edges in a single GraphQL call.
Connections are lists of similar edges. These let you refer to and access sets of edges related to a node such as orders on a shop.
Cursors are a unique reference to an node’s position in a connection. This lets you query for results from a starting point, enabling efficient pagination. This is similar to REST’s
With the introduction of new ways to access the same object, it's important to clarify how and where to use these different IDs.
Translating from REST IDs to GraphQL IDs
To help with migrating from our REST to the GraphQL, REST responses now include the GraphQL Admin API ID field,
The ID in this field can be used to query the object directly using the GraphQL Admin API.
The following example queries a product variant in REST, and then uses the
admin_graphql_api_id to query it in GraphQL.
GraphQL Request using
GraphQL IDs are opaque
GraphQL ID generation is implementation dependent, and as such does not follow any convention other than being a URI. There is no guarantee that GraphQL IDs will follow a similar "structure" (gid -> shopify -> resource -> rest_id) as the previous example, and therefore you should avoid generating IDs manually.
The following example shows how
admin_graphql_api_id does not follow an expected structure:
Always treat the
admin_graphql_api_id string as an opaque ID.
Storefront API IDs
The Storefront API is also queried using GraphQL, and uses its own separate IDs.
The GraphQL Admin API provides the
storefrontId field which enables you to get that object's Storefront API ID.
The following example shows how to request the
storefrontId field on a product.
Using connections, you can get information from related objects with a single request. For example, in the case of an order, you might want to know the total price, the customer's name, metafields, as well as the title of other variants belonging to the product in the order.
Using REST, we'd query the following endpoints and filter excess information.
Using GraphQL, you can make a single request using connections to get the desired data.
In REST, you paginate via the query parameters. Using
limit, you can split the total entries into manageable groups and paginate through them with
In GraphQL, you can apply similar concepts with cursor based pagination.
When using connections, you'll want to provide the
last argument, which specifies the number of items you want returned. This is equivalent to
Requesting the cursor field lets you get a reference to the position of a node within the connections. You can use that reference to obtain the next set of items. This is equivalent to
page, but with more precision, robustness, and flexibility.
Finally, request the pagInfo field to determine if there are any more pages to request. The nested fields “hasNextPage” and “hasPreviousPage” are boolean fields which let us know if we'll be able to paginate forwards or backwards. If both are
false, there are no more results or pages.
Tying it all together
This example query explores the connection between shops and orders. In our request, we’ll explore the connection between shops and orders, and how we can get only the fields we’re interested in.
This query asks for the first three elements on the orders connection. On each of these orders, the
pageInfo fields to handle pagination.
The query returns the data for the first three orders. In order to get the next 3 orders, we’ll have to add the cursor value to our connection arguments.
The data returned indicates that each node has a cursor. Using the last cursor that was returned allows you to continue from that point.
Continue paginating using the same method until