GraphQL and its benefits

GraphQL APIs offer several benefits over REST APIs.

What is GraphQL?

GraphQL is a query language and a runtime system. Clients form requests (called queries and mutations) by using the GraphQL query language, and the GraphQL server executes the request and returns the data in a response. Unlike REST APIs, which expose a different endpoint for each resource object, a GraphQL API makes all data available at a single endpoint. A client specifies exactly the data that it wants, and the server responds with only that data.

GraphQL looks similar to JSON. The following example shows a simple GraphQL query and the JSON response:

POST /admin/api/graphql.json

query {
  product(id: "gid://shopify/Product/10079785100") {
    title
    handle
    createdAt
  }
}

JSON Response

{
  "data": {
    "product": {
      "title": "The T-Shirt",
      "handle": "the-t-shirt",
      "createdAt": "2017-03-27T19:24:10Z"
    }
  }
}

When you ignore the top-level data key in the JSON response, the structure of the keys in the response is the same as the structure of the GraphQL request.

What are the benefits of using GraphQL instead of REST?

GraphQL addresses several problems that might sound familiar to anyone who’s worked with a REST API.

REST | Fetching associated data often requires multiple HTTP calls

REST APIs are built on the principle that every endpoint should return only one type of resource. For example, the request GET {shop_domain}/admin/products/1.json retrieves the information for product 1, but nothing more. This means that if you want a product’s variants, images, and metafields, then you need to make at least four HTTP calls.

REST | Apps receive more data than they need

To solve the above problem, we end up breaking away from true REST APIs by embedding certain associations to certain end-points when the need arises. For instance, GET /products/1 returns information about the product, but also its variants, images, and options. Ultimately we end up with one-size-fits-all responses where you cannot request less nor more than what we give you.

REST | Shopify doesn't know what data an app is using

When an app requests a REST endpoint, Shopify has no way of knowing if it's actually using every piece of data that's returned. It’s similar to doing a SELECT * to a SQL database. This is problematic because when Shopify needs to make breaking changes, such as remove an attribute from a response, it’s nearly impossible to know who it will affect. We know which clients call which endpoint, but we don’t know what subset of those clients are using the attribute that we're removing. Some attributes are also costly to compute. If we knew that the app doesn’t need a costly attribute, then we wouldn’t need to compute it in the first place.

REST | REST APIs are usually weakly-typed and lack machine-readable metadata

While there exists some solutions to the problem of not knowing which data is being used (like JSON Schema), the reality is that most REST APIs do not provide this sort of metadata. The result is that apps rely on documentation, which can become out of date or might be incomplete.

GraphQL | Everything is typed and part of a schema

Everything that's available through a GraphQL API is included in its schema. You can use the schema to build queries that return only the data that you need. This solves the problem of over-fetching data. It also means that we know which fields each app is using, making it easier for us to evolve our APIs over time.

GraphQL | Everything is available from a single endpoint

All GraphQL requests are sent to the /admin/api/graphql.json endpoint, which means that you can often retrieve all the data that you need in a single request. Using GraphQL features such as connections, variables, and aliases, you can make your queries incredibly efficient and retrieve data about many resource types in a single request.

GraphQL | Documentation is a first-class citizen

The documentation for a GraphQL API lives side-by-side with the code that constitutes it. Combined with the typed schema, this means that we can generate accurate and up-to-date documentation whenever something changes. Using GraphQL's introspection feature, you can query the schema itself to explore its contents and documentation.

GraphQL | Deprecation is a first-class citizen

We can easily mark a part of our schema as deprecated, and this will also be reflected in documentation. GraphQL tooling, such as client libraries, is also expected to communicate to the developer that they're using a deprecated tool.

Next steps

Sign up for a Partner account to get started.

Sign up