MENU
  1. ホーム
  2. 技術解説
  3. GraphQL入門：REST APIとの違い

GraphQL入門：REST APIとの違い

技術解説
目次

この記事で分かること：GraphQLがREST APIの課題を解決する理由

Webアプリケーション開発において、フロントエンドとバックエンドをつなぐAPIの設計は、開発効率やパフォーマンスに直結する重要な要素です。長年にわたりRESTful APIが標準的な選択肢として使われてきましたが、アプリケーションの複雑化とともに、RESTが抱えるいくつかの課題が表面化するようになりました。その課題を解決する選択肢として注目されているのがGraphQLです。

この記事では、関連コースも活用しながら、、GraphQLとREST APIの特徴を丁寧に比較しながら、GraphQLの基礎概念からApollo Serverを使った実装方法までを順序立てて解説します。

GraphQLとREST APIそれぞれの特徴を端的に整理

まず、2つのアプローチの基本的な特徴を整理しておきましょう。

比較項目 REST API GraphQL
エンドポイント リソースごとに複数用意する 原則として単一エンドポイント
データ取得の柔軟性 サーバー側が返すデータ構造に依存する クライアントが必要なフィールドを指定できる
型システム 標準仕様には含まれない（OpenAPI等で補完） スキーマによる強力な型定義が標準装備
バージョニング /v1/、/v2/ のようなURLバージョニングが一般的 スキーマの進化で対応し、URL変更が不要
キャッシュ HTTPキャッシュをそのまま活用できる 独自のキャッシュ戦略が必要になる
学習コスト 比較的低い スキーマ設計やリゾルバの理解が必要

REST APIは「リソース指向」の設計思想に基づいており、URLとHTTPメソッド（GET・POST・PUT・DELETE）の組み合わせでCRUD操作を表現します。シンプルで理解しやすい反面、クライアントの要求が多様化するにつれて、一つのエンドポイントでは対応しきれない場面が増えてきます。

一方GraphQLは「クエリ言語」であり、クライアントが取得したいデータの形を自ら定義してリクエストを送ります。サーバーは定義されたスキーマに従ってデータを返すため、フロントエンドとバックエンドの役割分担が明確になります。

どんな開発者・プロジェクトにGraphQLが向いているか

GraphQLはすべてのプロジェクトに適しているわけではありません。以下のような状況では、GraphQLの採用を検討する価値があります。

  • 複数のクライアント（Web・モバイル・IoT）が同じAPIを利用しており、それぞれ必要なデータが異なる
  • フロントエンドチームとバックエンドチームが並行して開発を進めており、スキーマを契約として共有したい
  • データ間のリレーションが複雑で、複数のRESTエンドポイントを連続して呼び出す必要がある
  • リアルタイム通信（チャット・ライブ更新など）をサブスクリプションで実装したい
  • APIの進化を重ねる長期プロジェクトで、破壊的変更を最小限に抑えたい

逆に、シンプルなCRUDアプリや小規模なプロジェクト、あるいはパブリックAPIとして広く公開するケースでは、RESTの方がシンプルで扱いやすい場面もあります。この点については後の章で詳しく触れます。

記事全体のロードマップ

この記事は以下の流れで解説を進めます。どのセクションから読んでも理解できるよう構成していますが、GraphQL初学者の方には順番に読み進めることを推奨します。

  • 第1章（本章）：GraphQLとREST APIの違いの概観と、この記事の読み方
  • 第2章：GraphQLの基礎概念（スキーマ・クエリ・ミューテーション・サブスクリプション・型システム）
  • 第3章：REST APIとGraphQLの違いを具体的な問題（オーバーフェッチ・Nリクエスト問題）を通じて比較
  • 第4章：Apollo Serverの概要と、React + Apollo Clientを使ったフロントエンド実装

GraphQL基礎：クエリ言語の仕組みをゼロから理解する

GraphQLを正しく活用するには、その設計思想と基本概念を押さえておくことが重要です。まずGraphQLが「何者なのか」という定義から始め、誕生の背景、そして中核となる概念を一つひとつ丁寧に確認していきます。

GraphQLの定義と誕生背景

GraphQL（グラフキューエル）は、Facebookが2012年に社内向けに開発し、2015年にオープンソースとして公開したAPI向けのクエリ言語および実行エンジンです。Facebookがモバイルアプリ（Facebookアプリ）のパフォーマンス問題に悩まされていたことが、開発の直接的なきっかけとなりました。

当時のFacebookは、モバイルクライアントがRESTful APIを介してニュースフィード・友達リスト・通知などの多様なデータを取得する構造になっていました。しかしモバイル端末の通信速度や処理性能の制約から、「必要なデータだけを1回のリクエストで効率よく取得したい」という要求が高まりました。この課題を解決するために設計されたのがGraphQLです。

GraphQLの名前にある「Graph」は、データ間の関係性（グラフ構造）を表現できることに由来しています。ユーザーが投稿を持ち、投稿にはコメントがあり、コメントには「いいね」がある——このような複雑なリレーションをひとつのクエリで横断的に取得できる点が、GraphQLの大きな特徴です。

スキーマ・クエリ・ミューテーション・サブスクリプションの概念

GraphQLを構成する主要な概念は次の4つです。

  • スキーマ（Schema）：APIで扱えるデータの型と操作の全体定義。クライアントとサーバーの「契約書」にあたる
  • クエリ（Query）：データを取得するための読み取り操作。HTTPのGETに相当
  • ミューテーション（Mutation）：データを作成・更新・削除するための書き込み操作。HTTPのPOST・PUT・DELETEに相当
  • サブスクリプション（Subscription）：WebSocketなどを通じてサーバーからリアルタイムにデータを受け取るための操作

これらの操作はすべてスキーマの上で定義され、クライアントはスキーマで許可された操作のみを実行できます。この制約がAPIの安全性と予測可能性を高めます。

型システム（Type System）の役割

GraphQLの強力な特徴のひとつが、厳密な型システムです。スキーマに定義されたすべてのフィールドは特定の型を持ち、実行時にその型に従ったデータのみが返されることが保証されます。

型システムの主な恩恵は以下のとおりです。

  • 開発時にIDEの補完や型チェックが機能し、コーディングの効率が上がる
  • クライアントとサーバーの間でデータ構造の食い違いが起きにくくなる
  • スキーマ自体がドキュメントの役割を果たすため、API仕様書を別途作成する手間が減る
  • GraphQL Introspection（自己問い合わせ）機能により、クライアントがスキーマを動的に確認できる

GraphQLの3大操作：Query／Mutation／Subscription

ここでは3つの操作それぞれの役割と構文を具体的なコード例で確認します。

Query（データ取得）

Queryはデータの読み取り専用操作です。クライアントが必要なフィールドだけを列挙してリクエストを送ります。以下は、ユーザーIDを指定してユーザー情報と投稿タイトルを取得する例です。

query GetUserWithPosts {
  user(id: "1") {
    id
    name
    email
    posts {
      id
      title
    }
  }
}

このクエリでは、userオブジェクトのうちid・name・emailのみを要求し、さらにネストされたpostsからidとtitleだけを取得します。不要なフィールドはレスポンスに含まれません。

Mutation（データ書き込み）

Mutationはデータの作成・更新・削除を行います。副作用を伴う操作は必ずMutationとして定義するのがGraphQLの規約です。

mutation CreatePost {
  createPost(input: {
    title: "GraphQL入門"
    body: "GraphQLはFacebookが開発したクエリ言語です。"
    authorId: "1"
  }) {
    id
    title
    createdAt
  }
}

Mutationでも、実行後に返ってくるデータのフィールドをクライアント側で指定できます。上記の例では、作成された投稿のid・title・createdAtを受け取っています。

Subscription（リアルタイム通信）

SubscriptionはWebSocketを通じてサーバーとの持続的な接続を確立し、サーバー側で特定のイベントが発生したときにリアルタイムでデータを受け取ります。

subscription OnCommentAdded {
  commentAdded(postId: "42") {
    id
    body
    author {
      name
    }
  }
}

上記の例では、投稿ID「42」の記事に新しいコメントが追加されるたびに、そのコメントの内容と投稿者名がクライアントにプッシュ配信されます。チャットアプリやライブ通知機能の実装に適した操作です。

スキーマ定義言語（SDL）で型を設計する

GraphQLのスキーマはSDL（Schema Definition Language）という専用の記法で記述します。SDLはシンプルで読みやすい構文を持ち、バックエンドの実装言語（JavaScript・Python・Goなど）に依存しない共通言語として機能します。

SDL記法の基本要素

SDLで使用する主な要素を以下に示します。

  • typeキーワード：オブジェクト型を定義する。フィールドの集まりを表す
  • フィールド：型の各プロパティ。

Apollo Serverのアーキテクチャを図解する

Apollo ServerはNode.js上で動作するGraphQLサーバーの実装ライブラリです。クライアントからリクエストが届いてからレスポンスが返るまでのデータフローを正確に理解することで、デバッグや最適化が大幅に行いやすくなります。

リクエストからレスポンスまでのデータフロー

Apollo Serverにおけるリクエストの処理フローは、大きく以下の順序で進みます。

  • ①クライアントがHTTP POSTでGraphQLクエリを送信：クエリ文字列はJSONのqueryフィールドに格納され、単一エンドポイント（通常は/graphql）に送信されます。
  • ②パースとバリデーション：Apollo ServerはGraphQL仕様のパーサーでクエリをAST（抽象構文木）に変換し、スキーマと照合してバリデーションを行います。型の不一致やフィールドの存在確認がこの段階で完了します。
  • ③リゾルバの実行：バリデーションを通過したクエリはリゾルバチェーンを通じて実行されます。各フィールドに対応するリゾルバ関数が呼び出され、データが解決されていきます。
  • ④レスポンスの組み立て：すべてのリゾルバの戻り値を集約し、クエリで要求されたフィールドだけを含むJSONレスポンスを生成してクライアントに返します。
処理ステージ 担当コンポーネント 主な役割
受信・パース Apollo Server本体 クエリ文字列をASTに変換
バリデーション graphql-jsライブラリ スキーマ適合性の検証
実行 リゾルバ関数群 各フィールドのデータ取得
レスポンス生成 Apollo Server本体 JSONフォーマットでクライアントへ返却

リゾルバ（Resolver）がデータを解決する仕組み

リゾルバはGraphQLの中核概念です。スキーマで定義された各フィールドに対して「そのデータをどこから・どのように取得するか」を記述する関数です。リゾルバ関数は以下の4つの引数を受け取ります。

  • parent（root）：親フィールドのリゾルバが返したオブジェクト。ネストされたフィールドの解決に使います。
  • args：クライアントがクエリに渡した引数のオブジェクト。
  • context：リクエスト全体で共有されるオブジェクト。認証情報やDBコネクション、DataLoaderインスタンスなどを格納します。
  • info：実行中のクエリのAST情報。高度な最適化に使用します。

重要な点として、GraphQLはフィールドごとに独立したリゾルバを持つため、「必要なフィールドだけ解決する」という動作が自然に実現されます。クライアントがリクエストしていないフィールドのリゾルバは実行されないため、REST APIのようなオーバーフェッチが構造的に防止されます。

Apollo ClientでフロントエンドとGraphQLをつなぐ

フロントエンドからGraphQL APIを利用する際、Apollo Clientは状態管理・キャッシュ・クエリ実行をまとめて提供してくれるライブラリです。Reactとの統合が特に充実しており、宣言的なデータフェッチが実現できます。

React + Apollo Clientの基本セットアップ

Apollo ClientをReactプロジェクトに導入する手順は次の通りです。まず必要なパッケージをインストールします。

npm install @apollo/client graphql

次に、ApolloClientインスタンスを作成し、ApolloProviderでReactアプリ全体をラップします。これにより、コンポーネントツリー全体でApollo Clientの機能が利用可能になります。

import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client';

const client = new ApolloClient({
  uri: 'http://localhost:4000/graphql',
  cache: new InMemoryCache(),
});

function App() {
  return (
    <ApolloProvider client={client}>
      <MyComponent />
    </ApolloProvider>
  );
}

InMemoryCacheはApollo Clientの正規化キャッシュです。同じIDを持つオブジェクトは自動的に重複排除されるため、複数コンポーネントが同じデータを参照する場合のパフォーマンスが向上します。

useQueryフックで宣言的にデータ取得する方法

useQueryフックはApollo Clientの中でも最も頻繁に使われるAPIです。コンポーネント内でGraphQLクエリを宣言するだけで、ローディング状態・エラー状態・データの管理が自動化されます。

import { useQuery, gql } from '@apollo/client';

const GET_POSTS = gql`
  query GetPosts {
    posts {
      id
      title
      author {
        name
      }
    }
  }
`;

function PostList() {
  const { loading, error, data } = useQuery(GET_POSTS);

  if (loading) return <p>読み込み中...</p>;
  if (error) return <p>エラーが発生しました</p>;

  return (
    <ul>
      {data.posts.map(post => (
        <li key={post.id}>{post.title} - {post.author.name}</li>
      ))}
    </ul>
  );
}

useQueryが返すloading・error・dataの3つの値で、UI表示の分岐が簡潔に記述できます。また、variablesオプションを使えばクエリに動的な引数を渡すことも可能です。REST APIのaxiosやfetchを使った命令的なデータ取得と比べ、コード量が削減され可読性も高まります。

Apollo Serverで実装例：ブログAPIをステップで作る

ここからは実際にApollo Serverを使ってブログAPIを構築する手順を解説します。記事（Post）と著者（Author）のデータを扱うシンプルなAPIを通じて、スキーマ定義からリゾルバ実装・テストまでの全体像を把握できます。

今回構築するAPIの全体像は以下の通りです。

  • 投稿一覧の取得（Query: posts）
  • 単一投稿の取得（Query: post(id: ID!)）
  • 新規投稿の作成（Mutation: createPost）
  • 既存REST APIとの接続（DataSource活用）

ステップ1：プロジェクトセットアップとスキーマ定義

npm installコマンドと必要パッケージの解説

Node.jsプロジェクトを初期化し、必要なパッケージをインストールします。

mkdir blog-graphql-api
cd blog-graphql-api
npm init -y
npm install @apollo/server graphql
npm install --save-dev nodemon

各パッケージの役割は以下の通りです。

パッケージ名 役割
@apollo/server Apollo Server 4のコアライブラリ。GraphQLサーバーの実装基盤
graphql GraphQL仕様のJavaScript実装。パース・バリデーション・実行を担う
nodemon 開発時のファイル変更を検知して自動再起動するツール

※本記事執筆時点の情報です。最新情報は公式サイトでご確認ください。

package.jsonに以下のscriptを追加しておくと開発がスムーズです。

"scripts": {
  "start": "node src/index.js",
  "dev": "nodemon src/index.js"
}

Post・Authorタイプをスキーマに定義するコード例

src/schema.jsを作成し、GraphQLスキーマをSDL（Schema Definition Language）で記述します。

export const typeDefs = `#graphql
  type Author {
    id: ID!
    name: String!
    email: String!
    posts: [Post!]!
  }

  type Post {
    id: ID!
    title: String!
    content: String!
    publishedAt: String
    author: Author!
  }

  type Query {
    posts: [Post!]!
    post(id: ID!): Post
    authors: [Author!]!
  }

  type Mutation {
    createPost(title: String!, content: String!, authorId: ID!): Post!
    deletePost(id: ID!): Boolean!
  }
`;

スキーマ設計のポイントをいくつか挙げます。

  • !（Non-null）を適切に付けることで、nullが返らないフィールドを明示できます。これにより型の安全性が高まります。
  • Postタイプにauthor: Author!を持たせることで、投稿から著者情報へのナビゲーションをクライアントが自由に要求できます。
  • QueryとMutationはそれぞれ読み取り操作・書き込み操作に対応します。REST APIのGET/POST/PUT/DELETEのような動詞の使い分けとは異なり、GraphQLではすべてのクエリを型で表現します。

ステップ2：リゾルバを実装してデータを返す

Queryリゾルバでデータソースから記事一覧を返す実装

実際のアプリケーションではデータベースから取得しますが、ここではインメモリのサンプルデータを使って動作を確認します。src/resolvers.jsを作成します。

const authors = [
  { id: '1', name: '山田太郎', email: 'yamada@example.com' },
  { id: '2', name: '鈴木花子', email: 'suzuki@example.com' },
];

const posts = [
  { id: '1', title: 'GraphQL入門', content: 'GraphQLの基礎を解説...', authorId: '1', publishedAt: '2024-01-15' },
  { id: '2', title: 'Apollo Server実践', content: 'Apollo Serverの使い方...', authorId: '2', publishedAt: '2024-02-01' },
];

export const resolvers = {
  Query: {
    posts: () => posts,
    post: (_, { id }) => posts.find(p => p.id === id),
    authors: () => authors,
  },
  Post: {
    author: (parent) => authors.find(a => a.id === parent.authorId),
  },
  Author: {
    posts: (parent) => posts.filter(p => p.authorId === parent.id),
  },
};

Post.authorリゾルバに注目してください。parent引数には

まとめ

本記事では、REST APIが抱えるオーバーフェッチやアンダーフェッチといった課題を起点に、GraphQLの基本概念と設計思想を解説しました。GraphQLはクライアントが必要なフィールドを自ら指定できる柔軟なデータ取得、強力な型システムによるスキーマ定義、そして単一エンドポイントによるシンプルな構成という特徴を持ちます。REST APIと単純に優劣を比較するものではなく、プロジェクトの規模・チーム構成・フロントエンドの多様性といった条件に応じて、適切な選択肢を見極めることが重要です。

Apollo Serverの実装面では、スキーマ定義（SDL）・リゾルバ・コンテキストの3要素が中心的な役割を担うことを確認しました。クライアントからのリクエストがパース・バリデーション・リゾルバ実行・レスポンス組み立てという順序で処理されるデータフローを理解しておくと、デバッグや最適化の際に迷いが少なくなります。N+1問題への対策としてDataLoaderを活用することも、実運用を見据えた設計において押さえておきたいポイントです。

GraphQLの導入を検討する際は、まず小規模なサービスや既存プロジェクトの一部エンドポイントに限定して試験的に導入し、チームがスキーマ設計やリゾルバの実装パターンに慣れるところから始めるアプローチが現実的です。一度にすべてを移行しようとするのではなく、段階的に適用範囲を広げていく方針が、リスクを抑えながら知見を蓄積するうえで有効です。

次のアクションとして、以下のステップを参考にしてください。

  • 公式ドキュメント（Apollo Server Docs・GraphQL.org）でスキーマ設計のベストプラクティスを確認する
  • ローカル環境にApollo Serverをセットアップし、サンプルスキーマとリゾルバを実際に動かしてみる
  • Apollo Sandboxを使ってクエリの動作確認とイントロスペクションを体験する
  • DataLoaderを組み込んだN+1対策の実装を試み、パフォーマンスへの効果を測定する
  • 既存のREST APIと並行運用する「ストラングラーフィグ」パターンによる段階的移行を検討する
技術解説
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！
目次