APIとは何か——RESTとGraphQLの設計思想の違い

現代のWebアプリケーションはフロントエンドとバックエンドが分離した構成が主流だ。この2つをつなぐのがAPI（Application Programming Interface）だ。APIの設計方針にはさまざまなアプローチがあるが、Webの世界で長らく標準として使われてきたRESTと、Facebookが開発し急速に普及したGraphQLは、根本的に異なる思想に基づいている。

APIとは何か

APIはシステムが外部から機能を呼び出すためのインターフェースだ。WebのAPIでは通常、HTTPプロトコルを使ってリクエストを送り、JSON形式のデータをレスポンスとして受け取る。スマートフォンアプリがサーバーのデータを取得する、複数のマイクロサービスが連携する、外部サービスと統合するといった場面でWebAPIは不可欠な役割を果たす。

RESTの設計原則

REST（Representational State Transfer）は2000年にRoy Fieldingが博士論文で提唱したアーキテクチャスタイルだ。厳密な仕様ではなく、一連の設計原則の集合体として定義されている。

リソース指向

RESTの中心概念は「リソース」だ。データの実体（ユーザー、記事、注文など）を「リソース」として捉え、それぞれに一意のURL（エンドポイント）を割り当てる。

GET    /users          ユーザー一覧取得
GET    /users/123      ユーザー123の取得
POST   /users          ユーザー作成
PUT    /users/123      ユーザー123の更新
DELETE /users/123      ユーザー123の削除

HTTPメソッド（GET/POST/PUT/DELETE）がCRUD操作（Create/Read/Update/Delete）に対応する。この設計により、URLを見ればどのリソースに何をしているかが直感的にわかる。

ステートレス

RESTのもう一つの重要な原則がステートレス性だ。各HTTPリクエストは独立しており、サーバーはクライアントのセッション状態を保持しない。認証情報やコンテキストはリクエストごとに送信する必要がある。

この設計はスケールアウトに適している。どのサーバーインスタンスがリクエストを処理しても同じ結果が得られるため、ロードバランサーで複数サーバーに分散させることができる。

HTTPステータスコードの活用

RESTはHTTPのステータスコードを意味のある形で活用する。200 OK（成功）、201 Created（作成成功）、404 Not Found（リソース未存在）、401 Unauthorized（認証エラー）など、標準的なコードを使うことでクライアントが状態を判断しやすくなる。

RESTの課題：オーバーフェッチとアンダーフェッチ

REST APIには構造的な課題がある。エンドポイントが返すデータ構造はサーバー側で固定されているため、クライアントが必要とするデータと実際に返されるデータが一致しないケースが頻発する。

オーバーフェッチ（Over-fetching）: クライアントが不要なデータまで受け取ってしまう問題だ。ユーザーの名前だけが必要なのに、GET /users/123 が誕生日、住所、プロフィール画像URLなど全フィールドを返す場合、余分なデータ転送が発生する。

アンダーフェッチ（Under-fetching）: 必要なデータを取得するために複数回のAPIコールが必要になる問題だ。記事一覧を取得し（GET /posts）、各記事の著者情報を取得し（GET /users/456）、コメント数を取得する（GET /posts/789/comments）といった連続的なリクエストが発生する。これをN+1問題と呼ぶ。

GraphQLの設計思想

GraphQL（Graph Query Language）はFacebookが2012年に社内で開発し、2015年にオープンソース化したAPIクエリ言語だ。RESTの課題を解決するために設計された。

クライアント主導のデータ取得

GraphQLの最大の特徴は「クライアントが必要なデータを明示的に指定できる」点だ。

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

このクエリを送ると、ユーザーの name と email、そのユーザーの投稿の title と createdAt だけが返される。他のフィールドは含まれない。オーバーフェッチを根本的に解決できる。

また、1回のリクエストで関連データをまとめて取得できるため、アンダーフェッチも解消される。上記の例では user と posts を1回のリクエストで取得している。

単一エンドポイント

RESTがリソースごとに複数のエンドポイントを持つのに対し、GraphQLは通常 POST /graphql という単一のエンドポイントを使う。リクエストのボディにクエリを含めて送信する。これによりAPIのバージョニング管理が大幅に簡素化される。

型システム

GraphQLはスキーマ定義言語（SDL）によって強力な型システムを持つ。

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

type Post {
  id: ID!
  title: String!
  createdAt: String!
}

! は必須フィールドを示す。スキーマがAPIの仕様として機能するため、クライアントは型安全なクエリを書ける。GraphQL Playgroundなどのツールでスキーマを探索しながら開発できる点も生産性に寄与する。

Mutation（変更操作）とSubscription（購読）

GraphQLはクエリ（読み取り）以外に Mutation（作成・更新・削除）と Subscription（リアルタイム更新）をサポートする。SubscriptionはWebSocketを使ってサーバーからのリアルタイム通知を受け取るための仕組みだ。

RESTとGraphQLの選択基準

どちらを採用すべきかは、プロジェクトの性質によって異なる。

RESTが向いているケース: シンプルなCRUD操作が中心のAPI、パブリックAPIの公開（HTTPキャッシュが重要）、チームのGraphQL習熟度が低い場合。

GraphQLが向いているケース: 複数のクライアント（Web・モバイル・IoT）が異なるデータを必要とする場合、頻繁に変化するデータ要件への対応、高度な型安全性が必要なフロントエンド開発。

AIアプリケーションとAPI設計

LLMを使うアプリケーションでは、APIの選択がパフォーマンスとコストに影響する。LLMのAPIレスポンスは長大になることが多く、不要なフィールドを含むオーバーフェッチはトークン消費にも影響する場合がある。また、AIエージェントが複数のAPIを連携して使う際、GraphQLのような柔軟なクエリ言語は必要なデータを1回で取得しやすく効率的だ。一方、単純なLLM呼び出しのラッパーAPIにはRESTのシンプルさが適している。

まとめ

RESTはリソース指向とステートレス性を原則とし、HTTPのメソッドとステータスコードを活用した設計標準だ。シンプルで学習コストが低い一方、オーバーフェッチとアンダーフェッチという構造的な課題がある。GraphQLはクライアントが必要なデータを指定できる柔軟なクエリ言語であり、単一エンドポイントと型システムによってフロントエンド開発の生産性を高める。どちらを選ぶかはプロジェクトの要件と規模に依存する。両者の設計思想を理解したうえで、目的に応じて適切なAPIスタイルを選択することが重要だ。