Shopify GraphQL API Beginners Guide

Shopifyのストア構築やアプリ開発に携わっていると、いずれ直面するのが「APIをどう使うか」という問題です。Shopifyは長らくREST APIを提供してきましたが、現在は GraphQL APIが推奨 されています。

わたし自身、最初は「GraphQLって難しそう」と敬遠していました。でも実際に触ってみると、RESTで何度もリクエストを繰り返していた処理がたった1回のクエリで済むことに驚きました。

出典：Shopify公式ドキュメント - GraphQL API overview

この記事では、GraphQL APIの基本概念からクエリの書き方、開発ツールの使い方まで、 これからShopify GraphQLを始める開発者向け にわかりやすく解説します。

GraphQL APIとは何か

GraphQL

Facebookが2015年に公開したAPIクエリ言語。クライアント側が「どのデータがほしいか」を正確に指定でき、必要なデータだけを1回のリクエストで取得できる。Shopifyでは2018年からAdmin APIとStorefront APIの両方でGraphQLをサポートしている。

出典：GraphQL公式サイト、Shopify Dev - Why GraphQL

RESTの場合、商品情報を取得して、次にバリアント情報を取得して、さらに画像情報を取得して……とエンドポイントを何度も叩く必要があります。GraphQLなら、ほしいフィールドをひとつのクエリにまとめて書くだけ。 オーバーフェッチ（不要なデータの取得）もアンダーフェッチ（データ不足で再リクエスト）もなくなります 。

REST APIとGraphQL APIの違い

Shopifyは2025年1月以降、新機能を GraphQL APIにのみ 追加する方針を明確にしています。REST APIがすぐに廃止されるわけではありませんが、今後のアプリ開発やカスタマイズを考えると、GraphQLへの移行は避けて通れません。

出典：Shopify Dev - Migrating from REST to GraphQL

最初のGraphQLクエリを書いてみよう

まずはもっともシンプルな例として、ストアの商品一覧を取得するクエリを見てみましょう。

query {
  products(first: 5) {
    edges {
      node {
        id
        title
        handle
        priceRangeV2 {
          minVariantPrice {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

このクエリを送信すると、最初の5件の商品について id、title、handle、最低価格だけが返ってきます。RESTのように不要なフィールドがドカッと返ってくることはありません。

商品と画像を一括取得する実用例

RESTでは商品取得と画像取得が別リクエストになりがちですが、GraphQLなら一度に取得できます。

query {
  products(first: 3) {
    edges {
      node {
        title
        description
        images(first: 2) {
          edges {
            node {
              url
              altText
            }
          }
        }
        variants(first: 5) {
          edges {
            node {
              title
              price
              inventoryQuantity
            }
          }
        }
      }
    }
  }
}

商品情報、画像、バリアント（サイズ・色などのバリエーション）を たった1回のリクエスト で取得しています。RESTなら3回以上のAPIコールが必要だった処理が、GraphQLならこれだけで完結します。

Mutationでデータを更新する

データの取得（Query）だけでなく、更新（Mutation）もGraphQLで行えます。たとえば商品のタイトルを更新する場合は次のように書きます。

mutation {
  productUpdate(input: { id: "gid://shopify/Product/1234567890", title: "新しい商品名" }) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}

Shopify GraphiQL Appで試す

コードを書く前に、まずブラウザ上でクエリを試してみるのがおすすめです。Shopifyが公式に提供している GraphiQL App を使えば、管理画面からそのままクエリを実行できます。

1. 1

   GraphiQL Appをインストール

   Shopify App Store からGraphiQL Appをインストールします。無料で使えます。

2. 2

   APIバージョンを選択

   アプリを開いたら、画面上部でAdmin APIのバージョンを選択します。特に理由がなければ最新の安定版を使いましょう。

3. 3

   クエリを入力して実行

   左側のエディタにGraphQLクエリを入力し、再生ボタンをクリック。右側に結果がJSON形式で表示されます。

4. 4

   ドキュメントを参照

   画面右側の「Docs」パネルから、利用可能なフィールドや型の情報をリアルタイムで確認できます。オートコンプリートも効くので、フィールド名を暗記する必要はありません。

出典：Shopify Dev - GraphiQL app

APIレート制限を理解する

GraphQL APIにはREST APIとは異なるレート制限の仕組みがあります。

コストベースのレート制限

Shopify GraphQL APIでは、クエリの「コスト」（取得するデータ量に応じたポイント）でレート制限を管理する。1秒あたりの最大コストはプランによって異なり、Basicプランで50ポイント/秒、Plusプランで最大200ポイント/秒。

出典：Shopify Dev - Rate limits

クエリのコストは、レスポンスヘッダーの X-GraphQL-Cost-Include-Fields や extensions オブジェクトで確認できます。

{
  "extensions": {
    "cost": {
      "requestedQueryCost": 12,
      "actualQueryCost": 8,
      "throttleStatus": {
        "maximumAvailable": 2000,
        "currentlyAvailable": 1992,
        "restoreRate": 100
      }
    }
  }
}

よくある質問

GraphQL学習のチェックリスト

• GraphQLの基本概念（Query / Mutation / edges / node）を理解する
• Shopify GraphiQL Appをインストールして実際にクエリを実行する
• 商品一覧の取得クエリを自分で書いてみる
• Mutationで商品データを更新してみる（開発ストアで）
• レート制限の仕組みを理解し、コストを意識したクエリを書く
• ページネーション（cursor）を使った大量データの取得に挑戦する
• Webhookと組み合わせたリアルタイム連携を構築する

まとめ

Shopify GraphQL APIは、「必要なデータだけを、1回のリクエストで取得できる」という点で、REST APIに対する明確な優位性があります。Shopifyが新機能をGraphQLに集中させている以上、今から学んでおくことは将来の開発効率を大きく左右します。

まずはShopify GraphiQL Appをインストールして、この記事のクエリ例をそのままコピペして実行してみてください。画面上でレスポンスが返ってくる体験をするだけで、「なるほど、こういうことか」と理解が一気に深まるはずです。

Shopifyでのストア構築やアプリ開発に興味がある方は、まず無料体験でShopifyの管理画面に触れてみるのがおすすめです。

→ Shopifyの無料体験はこちら