GraphQL入門｜REST APIとの違い・基本クエリ・実装パターンを解説

関連記事：API入門ガイド

GraphQLは、Facebookが開発したAPI向けのクエリ言語です。クライアントが必要なデータだけを指定して取得できるため、REST APIの課題を解決する選択肢として広く採用されています。

GraphQLとは

GraphQLでは、クライアントが取得したいデータの形を自分で指定します。サーバーはその指定に合わせたデータだけを返すため、不要なデータの転送を減らせます。

REST APIとの比較

基本概念

スキーマ定義

GraphQLでは、サーバー側で型を定義します。

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

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

type Query {
  user(id: ID!): User
  posts: [Post!]!
}

type Mutation {
  createPost(title: String!, content: String!): Post!
}

! は非nullを意味し、必ず値が返ることを保証します。

Query：データの取得

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

1回のリクエストで、ユーザー情報と関連する投稿を同時に取得できます。REST APIでは複数のリクエストが必要になるケースです。

Mutation：データの変更

mutation {
  createPost(title: "GraphQL入門", content: "GraphQLの基本を学ぼう") {
    id
    title
  }
}

Subscription：リアルタイム通信

WebSocketを使い、サーバーからのリアルタイムなデータ配信を受け取ります。チャットアプリや通知機能で活躍します。

フロントエンドでの実装（Apollo Client）

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

const GET_USERS = gql`
  query GetUsers {
    users {
      id
      name
      email
    }
  }
`;

function UserList() {
  const { loading, error, data } = useQuery(GET_USERS);

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

  return (
    <ul>
      {data.users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

バックエンドでの実装（Node.js）

const { ApolloServer } = require('@apollo/server');

const typeDefs = `
  type Query {
    hello: String
  }
`;

const resolvers = {
  Query: {
    hello: () => 'Hello, GraphQL!',
  },
};

const server = new ApolloServer({ typeDefs, resolvers });

リゾルバがスキーマの各フィールドに対するデータ取得ロジックを担当します。

GraphQLを使うべき場面

• 複数のリソースを同時に取得したい場合
• モバイルアプリなど帯域幅が限られる環境
• マイクロサービスの統合レイヤーとして
• フロントエンドとバックエンドの開発速度を独立させたい場合

GraphQLが向かない場面

• シンプルなCRUD APIで十分な場合
• ファイルアップロードが主要な機能の場合
• キャッシュ戦略がHTTPキャッシュに依存する場合

学習ロードマップ

1. スキーマ定義の基本を理解する（1〜2日）

Web開発技術マップも参考にしてください。

2. Query・Mutationを実際に書いてみる（2〜3日）
3. Apollo Clientでフロントエンドから呼び出す（3〜5日）
4. Apollo Serverでバックエンドを構築する（3〜5日）
5. 認証やエラーハンドリングなど実務的な課題に取り組む

まとめ

GraphQLは万能ではありませんが、複雑なデータ要件を持つアプリケーションでは大きなメリットがあります。まずはQuery・Mutationの基本を理解し、小さなプロジェクトで試してみましょう。

あわせて読みたい

• API入門ガイド｜REST・GraphQL・認証の基礎を理解する
• Node.js入門ガイド
• TypeScript入門ガイド
• Next.js入門ガイド