【第1回】GraphQL入門 - RESTとの違いと基本概念を完全解説

Web API開発の世界では、長らくRESTが主流でした。しかし、アプリケーションが複雑化し、多様なデバイスに対応する必要が出てくる中で、RESTが抱えるいくつかの課題が顕在化してきました。その解決策として登場したのが「GraphQL」です。

この連載では、GraphQLの基本から実践的な使い方までを5回にわたって解説していきます。第1回は、GraphQLとは何か、RESTとの違い、そしてその中心的な概念について学びます。

GraphQLとは？

GraphQLは、Facebook（現Meta）社が2012年に社内で開発を始め、2015年にオープンソースとして公開したAPIのためのクエリ言語であり、そのクエリを実行するためのサーバーサイドランタイムです。

最大の特徴は、クライアントが必要なデータの構造をクエリとして定義し、サーバーからその通りのレスポンスを受け取れる点にあります。これにより、APIの柔軟性と効率が劇的に向上します。

REST APIが抱える課題

GraphQLの利点を理解するために、まずは従来のREST APIが抱える代表的な課題を振り返ってみましょう。

1. オーバーフェッチング (Over-fetching)

「オーバーフェッチング」とは、APIから必要以上のデータを取得してしまう問題です。

例えば、ブログ記事のタイトル一覧だけが欲しいのに、記事の本文や投稿日、著者情報まで含まれた /posts エンドポイントを叩かなければならないケースです。クライアントは不要なデータを無視することになりますが、ネットワーク帯域の無駄遣いとなり、特にモバイル環境ではパフォーマンスの低下に繋がります。

2. アンダーフェッチング (Under-fetching)

「アンダーフェッチング」は、逆に1つのエンドポイントではデータが足りず、複数のリクエストを送信しなければならない問題です。

例えば、あるユーザーのプロフィール情報（/users/:id）と、そのユーザーが書いた記事一覧（/users/:id/posts）を取得したい場合、クライアントは2回のリクエストを送信する必要があります。これはアプリケーションの表示速度を遅くする原因となります。

GraphQLは、これらの問題を解決するために生まれました。

GraphQLの主な特徴とメリット

必要なデータだけを取得: クライアントがクエリで指定したデータだけが返されるため、オーバーフェッチングが起こりません。
一度のリクエストで完結: 関連するデータ（例：ユーザーとその投稿）を一度のリクエストでまとめて取得できるため、アンダーフェッチングが解消されます。
強力な型システム: スキーマ（後述）によってAPIの仕様が厳密に定義されます。これにより、クライアントとサーバー間のデータの食い違いを防ぎ、開発者はAPIの構造を容易に把握できます。
進化するAPI: エンドポイントが一つ（通常は /graphql）であるため、フィールドの追加や削除といったAPIの変更が容易です。古いバージョンのクライアントを壊すことなく、APIを進化させ続けることができます。

GraphQLの基本的な構成要素

GraphQLは主に3つの要素で構成されています。

1. クエリ (Query)

データの読み取りを行うためのリクエストです。クライアントは、欲しいデータとその構造をJSONによく似た形式で記述します。

【クエリの例】

graphql

query {
  post(id: "1") {
    title
    author {
      name
    }
  }
}

このクエリは、「IDが"1"の投稿の、タイトルと著者の名前」を要求しています。

【レスポンスの例】

json

{
  "data": {
    "post": {
      "title": "GraphQL入門",
      "author": {
        "name": "Jules"
      }
    }
  }
}

レスポンスは、クエリとそっくりな構造のJSONで返ってきます。

2. ミューテーション (Mutation)

データの書き込み（作成、更新、削除）を行うためのリクエストです。クエリと同様の構文で記述しますが、mutation キーワードで始めます。

【ミューテーションの例】

graphql

mutation {
  createPost(title: "新しい記事", content: "本文...") {
    id
    title
  }
}

このミューテーションは、新しい投稿を作成し、その結果として作成された投稿のidとtitleを返すよう要求しています。

3. スキーマ (Schema)

スキーマは、APIで送受信できるデータの構造を定義した「設計図」です。どのようなクエリが実行可能か、どのような型（文字列、数値、カスタムオブジェクトなど）が存在するかが、スキーマ定義言語（SDL: Schema Definition Language）を使って記述されます。

【スキーマの例】

graphql

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

type User {
  id: ID!
  name: String!
}

type Query {
  post(id: ID!): Post
  allPosts: [Post!]
}

このスキーマは、PostとUserという型が存在し、post(id: ...)というクエリで単一の投稿を取得できることなどを定義しています。!は、そのフィールドが必須（Non-Null）であることを示します。

まとめ

今回は、GraphQLの基本的な概念と、RESTとの違いについて解説しました。GraphQLは、クライアント主導で効率的なデータ取得を可能にする、モダンなAPI開発のための強力なツールです。

次回は、いよいよ手を動かして、Node.jsとApollo Serverを使ったGraphQLサーバーの構築に挑戦します。お楽しみに！

【第1回】GraphQL入門 - RESTとの違いと基本概念を完全解説 ​

GraphQLとは？ ​

REST APIが抱える課題 ​

1. オーバーフェッチング (Over-fetching) ​

2. アンダーフェッチング (Under-fetching) ​

GraphQLの主な特徴とメリット ​

GraphQLの基本的な構成要素 ​

1. クエリ (Query) ​

2. ミューテーション (Mutation) ​

3. スキーマ (Schema) ​

まとめ ​

【第1回】GraphQL入門 - RESTとの違いと基本概念を完全解説

GraphQLとは？

REST APIが抱える課題

1. オーバーフェッチング (Over-fetching)

2. アンダーフェッチング (Under-fetching)

GraphQLの主な特徴とメリット

GraphQLの基本的な構成要素

1. クエリ (Query)

2. ミューテーション (Mutation)

3. スキーマ (Schema)

まとめ