This blog post is complimentary to the ShopifyDevs YouTube video. Chuck Kosman is a Shopify Plus Launch Engineer and walks you through the basics of Shopify’s GraphQL. We will cover:
- What is GraphQL?
- How to get started with GraphQL
- Tutorial on how to make GraphQL queries against a client’s shop
What is GraphQL?
Let’s begin by asking the question: What is GraphQL? This quote would be right at the top of GraphQL.org. GraphQL can be described as “A query language that allows APIs to be used and a runtime that executes those queries using your existing data.”
“GraphQL” is described as “A query language to APIs and a runtime that fulfills those queries with your existing data.”
Query languages are highly structured, expressive ways to request data. You might have used them in relation to databases.
This is about query languages being used for APIs. This would be a more functional definition of graphQL. It is an expressive and structured way to request data from other applications. The underlying system fetches the data.
RESTful APIs are a way to request data from another program. GraphQL, however, is being hailed as the best REST. While REST solved many of the problems of its predecessors but GraphQL was specifically created to address some of the weaknesses of REST for modern applications, GraphQL has some unique features. Modern REST applications have a problem with overfetching or underfetching. This means that they either get too many data or not enough in one request.
Let’s explore these concepts further by using a restaurant as an example.
Explore concepts related to APIs using the ice cream analogy
I will use this ice cream shop for my restaurant. I will start by overfetching.
Shopify allows me to access all information about orders by using this endpoint on the admin RESTAP. When I insert an order ID, it gives me everything I need about one order.
This could be a restaurant or ice cream shop that offers pre-made sundaes. It might also mean that there are no combinations that you want. They have spent a lot of time and effort to put the toppings on and arrange things exactly as they requested. If your client does not like or require something, it is up to you to take those items off. This can prove to be very inefficient for both of you.
Underfetching, on the other hand, is when you don’t get enough data for a single request. This is often the case when you are looking for deep nested data.
Here is an example from Shopify showing how I got to the metafields for a particular set of products. First, I issue a GET request for all products. However, that is not all I need.
Next, I needed to use another endpoint to plug in my IDs and finally find the metafields I wanted. This is sometimes called the n+1 problem. I made one request to obtain the entire product list. Then, I had to issue n requests to reach each resource I was interested in at the conclusion. This is similar to the ice-cream shop analogy where I order ice cream, and then I need to request a number of additional resources.
Inflexible, inefficient.
Enter GraphQL. Enter GraphQL. What’s interesting here is you’ll notice that I’m using a POST request to this end point on the admin/API/GraphQL.json, and along with it I’m supplying a body of this nested structure of data. This particular nested data structure is a pseudocode example that asks for certain fields on products by a specific product ID.
In this example, I would only want to look at the title and handle. Then, I would like to see the variants fields that are related to products I might be interested. These could be filled in the ... fields as shown below. The data I receive back is only what I requested.
In the context our ice cream shop analogy I would go to the counter and specify what flavors and toppings are desired. I receive exactly that in one efficient and flexible request.
By specifying exactly what data I need in every request, both the server and that which is answering the query as well as the client, myself, my coworkers, and all other users of the application know what data is being used. This allows for speed and clarity. Because there is only one endpoint, it allows front end iteration to be quick. As a front-end developer, I don’t need to manage a lot of endpoints. It’s the way I structure my request that determines what data I receive back and not which endpoints I must call in order.
You might also wonder, “If there is only one endpoint, then how can I even know what I can ask for?”
This transparent documentation of GraphQL’s capabilities through what is called a schema is the real heartbeat of GraphQL. It is which we call it. This means that the data patterns you receive back are determined by the underlying types. It’s easy to see, even while you type or format your request, if you are making an error.
All of these factors lead to an efficient, powerful, flexible successor to REST.
Shopify Tools for GraphQL Requests
We now know a bit more about GraphQL and how it compares with REST. Let’s talk about the tools you can use to make GraphQL requests for Shopify.
You could do it with a cURL query, but that would mean you’d lose the strongly-typed schema which is one of the strongest features of GraphQL. We can achieve this using the GraphiQL IDE (Integrated Development Environment). This is available for both the GraphQL admin and storefront APIs. We’ll discuss the differences between them in a moment but for now we’ll stick to the admin API implementation.
Here’s what you need to get started
The Shopify Admin API GraphiQL Explorator is a section of documentation. It’s possible to play around with it by reading the documentation. However, if you want to learn more, I suggest you download Shopify’s GraphiQL application.
To install this, you will need a store. If you don’t have one, it’s okay. This is a great tutorial. You will need to set up a shop and install it. There is another piece of documentation called Request in our Shopify tutorials.
There are only two steps you must follow from the three. The first is to create a partner account. These are the tools that our community uses to create merchant solutions. It is completely free.
You will use that partner account to create a development shop or log in to an existing one. This last part is not required for the tutorials using GraphiQL. However, you can optionally follow the instructions here if you prefer to use a standalone HTTP client. We’ll show you how that looks in a moment.
If you don’t already have a store, I recommend that you get one. Also, populate some test data to ensure that you get meaningful data back when you make queries. While you could limit your search to products and variants, you have the option of going as far as customers and orders. These are the main three.
Shopify GraphQL Integrated Development Environment, (IDE)
Anyway, I’m going back to the Shopify Admin API GraphiQL Explorer and I’m going install it on a store I already have. This link will allow me to install Shopify’s GraphiQL application. I happen to have a store already, getting-started-with-graphql.myshopify.com, and I’m going to select that from my browser’s autocomplete here.
This is where you will define the scopes that this app can access. You can select all scopes if the store isn’t being used for production. This app can read and write, so I recommend that you avoid using a production store. Be careful when selecting scopes.
This tutorial will only require products. I have chosen Select All to make things simpler. I have also chosen Install. It will prompt me to ask, “Does this app have all these scopes?” I’m going say Yes.
After it finishes installing, you will see this interface: a left column with the shop name JSON formatted thing, and a right column that is blank for now. This will be used for the tutorial. However, we’ll continue to use other methods of working in GraphQL for the foreseeable future.
The standalone HTTP client
A standalone HTTP client could also be used, as I already mentioned. We don’t need to specify the endpoint, which is why we are using the GraphiQL IDE. GraphQL has one endpoint, and that’s a wonderful advantage.
We don’t have to also set up headers. If this is the preferred method of working, I will show you how those headers look. Two headers are required. To authenticate under this header, you will need to create a private application. Also, you will need to indicate the content type as app/JSON.
Some people get confused about the application/GraphQL. There are subtle differences, so you will want to use application/JSON when using a standalone HTTP client. It doesn’t always work. You can switch to Application/GraphQL. You can refer to the Make your FirstGraphQL Request section of documentation if you need more information. They also cover how to use GraphiQL.
A great blog post on setting one up is called insomnia. There’s also a kit with preloaded queries you can use to get started right away. This document contains sample requests and the headers you will need. This document is a great resource that you can refer back to after the tutorial.
This will also be covered in detail. The GraphQL IDE will not work for you if you begin working at scale. This is a tool to help you test your code. You wouldn’t use an HTTP client to build a production app.
Building with GraphQL client library libraries: Working at scale
I recommend GraphQL client library when you are building a full-on application. You can layer a lot more developer tools over top of GraphQL’s strong-typed schema for fast and amazing development. Apollo and Relay are two popular client libraries. However, there are many others. It all depends on the languages, frameworks and platforms that you’re using.
“GraphQL’s strong-typed schema allows you to layer a lot more developer tools over it for fast and amazing development.
I briefly mentioned that there are two APIs you could use with GraphQL. These are both REST APIs and GraphQL admin APIs. They are used to develop apps and integrate with Shopify admin. If you think about it this way, it’s similar to extending Shopify’s back office. The storefront API serves a different purpose.
We also have software development kits (SDKs) to target iOS, Android, and the web. GraphQL is also the only available.
for storefront-to-storefront API, there are clearly advantages of using GraphQL over REST. You can actually do certain things with the GraphQL admin API that are not possible with the REST API.
Shopify is betting on GraphQL. We see the advantages of GraphQL over RESTful APIs.
What you can do with GraphQL admin APIs
You can do certain things only on the GraphQL admin API. These are listed in chronological order according to their release.
- The GraphQL admin API allows you to bulk-adjust inventory. This is a lot more efficient than the REST API for the same operation. This is a great way to manage inventory at scale.
- Only GraphQL is the translations API.
- Product media allows you to create images and videos as well as 3D models using GraphQL.
- Order editing is a feature that has been requested for a while. It can be done only via the admin API.
- The developer preview and APIs for duties and taxes are also available in GraphQL at the time of writing.
It is likely that more features will only be available on GraphQL in future. These features can be viewed on our developer update, if you wish to keep up-to-date with the latest Shopify API releases.
An example query with products
I will structure my query as I go and then compare it with the schema.
So you can see the whole picture. A visualization will also be shown that shows how these types are related in the schema.
I will get rid query, because removing query implicitly creates a query. You can get rid of everything but keep the curly braces. I’m here in queryRoot so I will likely be interested in products.
Okay, products are a bit more complex.
The field products are displayed. I then have this parentheses that say first, last, before, sortKey and all the rest. It eventually returns a type named ProductConnection.
There is a lot to be understood here. Let’s get started.
I could use products here to autocomplete and know that product is something that I can query on the QueryRoot. I will open the curly braces once more. It expects something else. What do we want from products?
Let’s suppose that I wanted their title. Oh, weird. It’s strange. What’s the deal?
When I press play the titles title won’t appear on product connection. Thank you, strongly-typed schema. That’s awesome. It’s not on ProductConnection. a edges appears, and I get an array [ProductEdge]!s. Let’s start with edges. Okay, it’s going to be a lot of fields so I’ll click [ProductEdge]. To see exactly what it does, click on [ProductEdge!
There is a cursor, and a notde. It seems that node returns an product kind, so that’s what I want. These are likely things that you’re more familiar about on node. Let’s assume I only need the ID, and the title.
GraphQL: Exploring the terminology
Let’s get back to the edges, node terminology. What does that mean? GraphQL is a way to visualize data connections.
Let’s now talk a bit about GraphQL terminology, and how it can help you navigate your work.
You’ll find nodess and edgess as soon as you start to work with lists of items. Let’s take a break and discuss what these are.
This is basically a simplified version of the query I just wrote. It includes both the code and a visual representation. I am entering the queryRoot into my browser and attaching the queryRoot onto our products. These products have properties. I am looking for title. These individual entities are what graph theory calls nodes, and the relationships between them edges.
When I reach the root level, and want to know products I must say, “Get all the relationships to product.” I mean, get all the edges. Next, at the ends edges tell me about entities at those edges. These are nodes.
When you begin working with plural requests (e.g., getting a list), you will notice that you are more likely to use edges and node before you get the item at the end.
Let’s go one step further. Deeply nested queries. Let’s say that I want all the variants for these 10 products. We have already discussed underfetching. You will see variants if you type the V. There are variants which correspond to products. I know I will have to say first so I’ll just use 10 again.
“GraphQL is a fascinating topic that can be learned from many great resources online.”
Shopify’s GraphQL Learning Kit is a great starting point if you are looking to set up a standalone HTTP client. You will find a blog post discussing GraphQL and a downloadable set preconfigured insomnia queries. Only you will need to create a private key for the app.
You can learn more about the storefront SDKs and how they will make your work with the API easier. Check out our Storefront App API Tools Library.
The “how to GraphQL” tutorials are amazing. These tutorials go deeper than the tutorial and provide great tutorials on how to use certain libraries and frameworks. If you are a React developer, and want to understand Apollo, a popular client library, here’s a step by step tutorial.
You can also visit the official GraphQL website. This site really lays out the specification of GraphQL in very clear language, and is a great resource to help you move forward.
