Last year my team started developing a Shopify app and one of the technologies we were required to use was GraphQL. I had never used GraphQL before so I had to learn it from scratch. In this blog post I will talk about what I have learned about this powerful technology.
We used GraphQL to send requests to Shopify’s server and also to implement our own internal server. In the first part of this blog post, after explaining what exactly GraphQL is, I will explain what it took to implement the former. The latter will be explained in the upcoming second part.
So what exactly is GraphQL? And why would you even consider using it instead of a more popular alternative such as REST?
GraphQL is a query language for APIs and a runtime for executing those queries against a data source. It was developed by Facebook and is now maintained as an open-source project. GraphQL allows clients to request only the data they need and enables the creation of complex queries with multiple nested fields, making it a more efficient alternative to REST APIs.
So we use GraphQL for the same thing as REST, but how are they different? And why would someone choose GraphQL over REST? One of the key differences between the two is that REST APIs have a fixed structure and a fixed set of endpoints that return a fixed set of data. In contrast, GraphQL allows the client to request only the data they need by specifying the fields they want in a query in a single endpoint, by just sending a POST HTTP request. This means that a single GraphQL query can retrieve multiple resources in a single request, while in REST it would require multiple requests to different endpoints. Because of the flexibility of GraphQL to ask for only the data you need, it can be more efficient than REST API’s in terms of network usage and over-fetching. It reduces the number of network roundtrips and the amount of data transferred over the network, leading to a better user experience.
Versioning is also different on GraphQL. With REST, versioning is typically handled by using different URL routes, such as adding a version number to the URL or using different subdomains. With GraphQL, versioning can be managed by just specifying the version in the query. This allows the client to specify the version of the API they want to use in the query, rather than in the URL. Also, adding new fields on a GraphQL API can be relatively simple and straightforward too. In GraphQL, the schema defines the structure of the data that can be queried, so adding new fields or changing existing ones can be done by updating the schema. This can be done without affecting existing clients because the clients are able to request only the fields they need and ignore the new or changed fields. With REST, a new version of the API typically involves a complete overhaul of the endpoints and data structures, which can be a breaking change for clients (we’ve all been there). If you use GraphQL, the likelihood of introducing breaking changes diminishes greatly.
Hopefully after reading all the things that make GraphQL you are all onboard the GraphQL train. Let’s take a look at a simple GraphQL query you would make while developing a Shopify app:
While using this simple query, you can get all the information that you need from a shop who installs your app (name, email, description, url) while not over-fetching fields you do not need (such as billing information). Note that this request is of type query, used to retrieve data from the server.
There are other types like mutation and subscribe. Mutations are used to change things on the backend (basically write operations). Subscriptions are used to fetch data from the server, just like queries, while maintaining an active connection. Since we can specify all these different operations in a single request, there is no need to use different HTTP methods (GET, POST, UPDATE, etc..) like we do on REST APIs.
In order to retrieve shop data, Shopify provides many different GraphQL and REST APIs. While usually you can use the GraphQL and REST versions of the same API interchangeably, sometimes there are some features present in one which are not present in the other; so in some instances you’ll end up using both. Nevertheless, Shopify encourages the usage of their GraphQL APIs whenever possible.
While there are several APIs in Shopify’s repertoire, you may not end up using all of them. The ones you are most likely to use are their Admin API and Storefront API. The former is Shopify’s go-to API, you can use it for a wide variety of purposes. From querying shop information (like products, orders, customers) to subscribing to webhooks or process payments; this is Shopify’s most powerful API.
Shopify limits the usage of the Admin API via rate limits. For each request, query costs are calculated, measured in cost points. Each field returned by a query costs a set number of points. The total cost of a query is the sum of all the fields it returns, so more complex queries cost more to run. Each combination of app and store is given a bucket of 1000 cost points, with a leak rate of 50 cost points per second. This means that the total cost of your queries cannot exceed 1,000 points at any given time, and that room is created in the app’s bucket at a rate of 50 points per second. By making simpler, low-cost queries, you can make more queries over time. This means that developers must be careful not to over-fetch unnecessary fields.
Error codes are handled differently when using a GraphQL API as well. The GraphQL API can return a 200 OK response code in cases that would typically produce 4xx or 5xx errors in REST. You must check the body of the response and check if there is a non-null error field. In this case, you will find the error message inside the response’s body.
When you make a request to the Shopify server, you must include an access token for authorization. This token is created when a merchant installs your app and goes through an OAuth process. It authorizes you to get information about the shop. Not including it will result in your request failing.
Getting started with Shopify is a daunting task if you have never done it before, even if you are a GraphQL expert. Here are a couple of tips that have made my developing process easier.
Shopify provides some boilerplate code for apps, so you can mostly skip past all the set-up and get to what’s important: developing your application. We intended to implement our project using Node.js so our team used the boilerplate in the repo shopify-marketplaces-admin-app which gave us some functionalities already developed such as OAuth, which you’ll need to have if you wish to publish the app on Shopify’s app store. There’s even a method called ‘callShopifyGraphqlAPI’ so you can start making GraphQL requests right away.
GraphiQL is a tool for interacting with GraphQL APIs. It allows developers to easily explore the schema of a GraphQL API and send queries and mutations to the server to retrieve or update data. You can use GraphiQL on Shopify’s website to get a sense of their API but I recommend installing the Shopify GraphiQL app on your development store. It will speed up development since you can design the query there and see what you will get.
GraphQL is an essential tool for developing a Shopify app. If you have never used it before it may seem discouraging, but rest assured the tool is easy to learn and an invaluable tool to have in your dev stack. In the next part we will explore how to implement a GraphQL server using Apollo and how Shopify goes the extra mile to make it easier for you.
If you found part one of this blog post interesting, then you won’t want to miss out on part two.
Last year my team started developing a Shopify app and one of the technologies we were required to use was GraphQL. I had never used GraphQL before so I had to learn it from scratch. In this blog post I will talk about what I have learned about this powerful technology.
We used GraphQL to send requests to Shopify’s server and also to implement our own internal server. In the first part of this blog post, after explaining what exactly GraphQL is, I will explain what it took to implement the former. The latter will be explained in the upcoming second part.
So what exactly is GraphQL? And why would you even consider using it instead of a more popular alternative such as REST?
GraphQL is a query language for APIs and a runtime for executing those queries against a data source. It was developed by Facebook and is now maintained as an open-source project. GraphQL allows clients to request only the data they need and enables the creation of complex queries with multiple nested fields, making it a more efficient alternative to REST APIs.
So we use GraphQL for the same thing as REST, but how are they different? And why would someone choose GraphQL over REST? One of the key differences between the two is that REST APIs have a fixed structure and a fixed set of endpoints that return a fixed set of data. In contrast, GraphQL allows the client to request only the data they need by specifying the fields they want in a query in a single endpoint, by just sending a POST HTTP request. This means that a single GraphQL query can retrieve multiple resources in a single request, while in REST it would require multiple requests to different endpoints. Because of the flexibility of GraphQL to ask for only the data you need, it can be more efficient than REST API’s in terms of network usage and over-fetching. It reduces the number of network roundtrips and the amount of data transferred over the network, leading to a better user experience.
Versioning is also different on GraphQL. With REST, versioning is typically handled by using different URL routes, such as adding a version number to the URL or using different subdomains. With GraphQL, versioning can be managed by just specifying the version in the query. This allows the client to specify the version of the API they want to use in the query, rather than in the URL. Also, adding new fields on a GraphQL API can be relatively simple and straightforward too. In GraphQL, the schema defines the structure of the data that can be queried, so adding new fields or changing existing ones can be done by updating the schema. This can be done without affecting existing clients because the clients are able to request only the fields they need and ignore the new or changed fields. With REST, a new version of the API typically involves a complete overhaul of the endpoints and data structures, which can be a breaking change for clients (we’ve all been there). If you use GraphQL, the likelihood of introducing breaking changes diminishes greatly.
Hopefully after reading all the things that make GraphQL you are all onboard the GraphQL train. Let’s take a look at a simple GraphQL query you would make while developing a Shopify app:
While using this simple query, you can get all the information that you need from a shop who installs your app (name, email, description, url) while not over-fetching fields you do not need (such as billing information). Note that this request is of type query, used to retrieve data from the server.
There are other types like mutation and subscribe. Mutations are used to change things on the backend (basically write operations). Subscriptions are used to fetch data from the server, just like queries, while maintaining an active connection. Since we can specify all these different operations in a single request, there is no need to use different HTTP methods (GET, POST, UPDATE, etc..) like we do on REST APIs.
In order to retrieve shop data, Shopify provides many different GraphQL and REST APIs. While usually you can use the GraphQL and REST versions of the same API interchangeably, sometimes there are some features present in one which are not present in the other; so in some instances you’ll end up using both. Nevertheless, Shopify encourages the usage of their GraphQL APIs whenever possible.
While there are several APIs in Shopify’s repertoire, you may not end up using all of them. The ones you are most likely to use are their Admin API and Storefront API. The former is Shopify’s go-to API, you can use it for a wide variety of purposes. From querying shop information (like products, orders, customers) to subscribing to webhooks or process payments; this is Shopify’s most powerful API.
Shopify limits the usage of the Admin API via rate limits. For each request, query costs are calculated, measured in cost points. Each field returned by a query costs a set number of points. The total cost of a query is the sum of all the fields it returns, so more complex queries cost more to run. Each combination of app and store is given a bucket of 1000 cost points, with a leak rate of 50 cost points per second. This means that the total cost of your queries cannot exceed 1,000 points at any given time, and that room is created in the app’s bucket at a rate of 50 points per second. By making simpler, low-cost queries, you can make more queries over time. This means that developers must be careful not to over-fetch unnecessary fields.
Error codes are handled differently when using a GraphQL API as well. The GraphQL API can return a 200 OK response code in cases that would typically produce 4xx or 5xx errors in REST. You must check the body of the response and check if there is a non-null error field. In this case, you will find the error message inside the response’s body.
When you make a request to the Shopify server, you must include an access token for authorization. This token is created when a merchant installs your app and goes through an OAuth process. It authorizes you to get information about the shop. Not including it will result in your request failing.
Getting started with Shopify is a daunting task if you have never done it before, even if you are a GraphQL expert. Here are a couple of tips that have made my developing process easier.
Shopify provides some boilerplate code for apps, so you can mostly skip past all the set-up and get to what’s important: developing your application. We intended to implement our project using Node.js so our team used the boilerplate in the repo shopify-marketplaces-admin-app which gave us some functionalities already developed such as OAuth, which you’ll need to have if you wish to publish the app on Shopify’s app store. There’s even a method called ‘callShopifyGraphqlAPI’ so you can start making GraphQL requests right away.
GraphiQL is a tool for interacting with GraphQL APIs. It allows developers to easily explore the schema of a GraphQL API and send queries and mutations to the server to retrieve or update data. You can use GraphiQL on Shopify’s website to get a sense of their API but I recommend installing the Shopify GraphiQL app on your development store. It will speed up development since you can design the query there and see what you will get.
GraphQL is an essential tool for developing a Shopify app. If you have never used it before it may seem discouraging, but rest assured the tool is easy to learn and an invaluable tool to have in your dev stack. In the next part we will explore how to implement a GraphQL server using Apollo and how Shopify goes the extra mile to make it easier for you.
If you found part one of this blog post interesting, then you won’t want to miss out on part two.
Lorem ipsum dolor sit amet consectetur. Sit sit vel eu sed proin. Arcu bibendum in mauris urna erat magna volutpat eget. Lectus commodo consectetur egestas quis ut lobortis nunc.
.png)
Lorem ipsum dolor sit amet consectetur. Sit sit vel eu sed proin. Arcu bibendum in mauris urna erat magna volutpat eget. Lectus commodo consectetur egestas quis ut lobortis nunc.
.jpg)
.jpeg)
