All Tutorials

Build a Shopify App with Node and React

Learn the GraphQL Admin API

GraphQL is a relatively new query language that uses fields and types to load data from a client. The Shopify Admin API is available through GraphQL, and can be used to query and mutate shop data.

GraphQL vs. REST APIs

Shopify APIs have previously been available through REST, but more recently the Admin API was made available through GraphQL. Unlike REST APIs, which use multiple endpoints to return large sets of data, GraphQL uses a single endpoint with fields that can be queried to specify the data you need. This generally improves the speed of your app because it’s not asking for data it doesn’t intend to use. Instead of using a variety of different methods to request and modify data, GraphQL uses queries to read data and mutations to write data.

GraphQL is a strongly typed language. Because GraphQL APIs are built directly from the type definitions in the data structure, it’s easier for GraphQL documentation to be standardized and somewhat self-documented.

If you’re more comfortable using REST APIs, then see Migrating from REST to GraphQL to learn more.

Play in the sandbox

You can write test queries and mutations in Shopify’s graphql explorer. Use the app to get a sense of the type of data that your app can manipulate.

Install the GraphiQL app

Shopify’s GraphiQL app installs on your development store and lets you query your store’s data. You can also test mutations by giving the GraphiQL app access to write product data to your development store.

  1. Go to the Shopify GraphQL Explorer.
  2. Add your development store URL, but don’t click the install button yet.
  3. In the acesss scopes section, give the app access to the write products scope (and to any other scopes that you might want to test later).
  4. In the shop url section, click install.
  5. Click install app on the app install page.

This final app install page is very similar to the form merchants see before they install your app. Your app’s access permissions are clearly labeled so that it’s easy to understand the type of actions your app can perform.

Write some queries

Queries are objects that hold fields. The field property is used to ask for specific items in an object. You can ask GraphQL for whatever data structure you need, but it must start at the QueryRoot.

  1. In the GraphQL explorer app, add the following query and press play
    query { shop { name primaryDomain { url host } } }
    As you can see, the GraphQL API returns only the data that you asked for

    The extensions in the response contain information about the query itself. These extensions can be used to throttle the requests you’re making to the API.

    { "data": { "shop": { "name": "Dev Tools Education", "primaryDomain": { "url": "https://dev-tools-education.myshopify.com", "host": "dev-tools-education.myshopify.com" } } }, "extensions": { "cost": { "requestedQueryCost": 2, "actualQueryCost": 2, "throttleStatus": { "maximumAvailable": 1000, "currentlyAvailable": 998, "restoreRate": 50 } } } }
  2. Click the Docs button in the top-right corner of the screen to access the documentation helper.
  3. Under root types, choose QueryRoot
  4. Search for the shop object and select it from the results. From here, you can view all of the different fields that make up the shop object. You can use any of these fields when building queries.
  5. Search for the Plan field and select it. Some fields, like the Plan field, also have subfields or types.
  6. Query your development store’s Plan with the partnerDevelopment subfield
    query { shop { name plan { partnerDevelopment } } }

As it says in the documentation helper, the partnerDevelopment field returns a boolean that determines whether the shop is a partner development shop. In this case, you should see true.

Perform a mutation

At some point you’ll also want to write data with GraphQL. For example, you might want to build a feature that adds new products or updates inventory on existing products in a store. To do this, you need to use GraphQL mutations.

You can learn about mutations by trying to perform one in the GraphiQL app. Try out the ProductCreate mutation, which lets you create and edit a store’s products

  1. Go back to the documentation helper in the top-right corner of the GraphiQL app.
  2. Use the breadcrumb to navigate out of the shop object and back to the main schema page.
  3. Under root types, choose Mutations.
  4. Search for the ProductCreate mutation and select it.

    Here you’ll find the input fields that are required to build a ProductCreate mutation. You’ll also need to specify what you want the API to return after it executes the mutation.

    All available mutations are listed under the MutationRoot in alphabetical order.

  5. In the main GraphiQL app input, add the following ProductCreate mutation example

    Remember to always include the userErrors field to get feedback from the API when queries or mutations fail.

    mutation exampleProductCreate($input: ProductInput!) { productCreate(input: $input) { userErrors { field message } product { id title productType } } }
  6. Drag open the Query Variables window from the bottom of the main window.
  7. Pass in the following title and productType variables, which will define your example product

    The Query Variables window might be closed and hard to notice. You might need to drag your browser up from the bottom of your screen to see it.

    { "input": {"title": "test product", "productType": "test type"} }
  8. Press the play button.

You should see information about your new product in the response, including the product ID. You’ll also be able to view the new product in the Products section of your development store. You can update existing products with the same method by providing their ID in the input.

For a more in-depth tutorial on GraphQL, check out our GraphQL learning kit.

Continue to Fetch data with Apollo