RESTとGraphQLの基本と実践的な比較ガイド

REST APIとGraphQLは、どちらもクライアントとサーバー間の通信を実現する技術ですが、データ取得の仕組みに違いがあります。本ブログでは、それぞれの特徴や構造を比較し、適切な選択をするためのポイントを詳しく解説します。

REST API と GraphQL は、どちらも広く使われている API の構築・利用方法です。

REST API と GraphQL の概要

REST API と GraphQL は、どちらもクライアントとサーバー間の通信を可能にする技術です。 APIの設計やデータの取得方法に違いがあり、それぞれの特性に応じた使い分けが求められます。

REST API のイメージ

レストランを想像してください。メニューにある料理のみ注文でき、カスタマイズはできません。 ウェイターに注文すると、キッチンはその料理を提供します。REST API もこれと同じ仕組みで、事前に定義されたエンドポイントからデータを取得します。

GraphQL のイメージ

次に、ビュッフェ形式を想像してください。好きな料理だけを選び、不要なものは除外できます。 「もやしとネギ抜きのラーメンがほしい」と指定すると、その通りの内容で提供されます。GraphQL API は、クライアントのリクエストに応じて、必要なデータのみを返す仕組みです。

 

REST APIの構造

RESTful API は通常、リソースベースの設計で構成され、HTTPメソッドを使用します。

1. HTTPメソッド

REST APIでは、標準的なHTTPメソッドを使ってリソースとやり取りします。

GET：データを取得（例：GET /applicants）
POST：新しいデータを作成（例：POST /applicant/123）
PUT：既存のデータを更新（例：PUT /applicant/123）
DELETE：データを削除（例：DELETE /applicant/123）

2. エンドポイントの構造

REST APIでは、各リソースごとに固有のURL（エンドポイント）があります。

クライアントはこれらのエンドポイントにリクエストを送り、サーバーは構造化されたデータ（多くの場合JSON形式）で応答します。

例1 — サービスのリクエスト：

リクエスト：

GET https://api.example/services/

レスポンス:

[
 {
   "id": 123,
   "type": "HR_management_system"
 },
 {
   "id": 456,
   "type": "logistic_system"
 }
]

例2 — 商品のリクエスト：

リクエスト：

GET https://api.example/product/456

レスポンス：

{
  "id": 456,
  "name": "Wireless Keyboard",
  "price": 49.99,
  "availability": "in_stock"
}

このように、特定のエンドポイントにアクセスすることで、指定した商品情報がJSON形式で返されます。

3. RESTの基本原則

RESTは以下の原則に従って設計されます。

• ステートレス：各リクエストは独立しており、サーバーは過去のやり取りを記憶しません。
• 一貫したインターフェース：リソースベースの一貫性あるURL構造を使用します。
• キャッシュ可能：レスポンスをキャッシュすることでパフォーマンスを向上できます。

 

GraphQL APIの構造

1. HTTPメソッド　と　エンドポイントの構造

GraphQLも標準的なHTTPメソッドを使用しますが、GraphQLもHTTPメソッドを使いますが、基本的にはPOSTがメインです。GETが使われることもあります。RESTとは異なり、GraphQLでは通常単一のエンドポイント（例：/graphql）しか公開しません。

URLにリソース名を指定することはなく、代わりにリクエストボディ内で取得したい項目（フィールドやフィルター、ネストされたデータ）を明示的に指定します。

また、HTTPの機能（ヘッダー、ステータスコード、一部キャッシュなど）も引き続き使用されます。

 

2. スキーマ定義

APIリクエストを行うには、スキーマの定義が必要です。

スキーマ（Schema）とは、送受信されるデータの構造（型）のことです。

例：

ステップ1：スキーマ定義

# ユーザーの型（サーバーから返されるデータの構造）

type User {
  id: ID!
  name: String!
  email: String!
  phone: String
  address: String
}

# ユーザー作成時にクライアントが送るデータ（入力型）

input CreateUserInput {
  name: String!
  email: String!
}

# ユーザーを作成するミューテーション（データ変更）

type Mutation {
  createUser(input: CreateUserInput!): User
}

# IDでユーザー情報を取得するクエリ（データ取得）

type Query {
  user(id: ID!): User
}

ステップ2：クライアントが送信する内容

{
  "query": "mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { id name email } }",
  "variables": {
    "input": {
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}

ステップ3：サーバーからのレスポンス

サーバーは、スキーマに従ってUserオブジェクトを返します

{
  "data": {
    "createUser": {
      "id": "1",
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}

Note:

スキーマにこう書かれているとき：

type Query {
  user(id: ID!): User
}

これは以下のことを意味します：

IDでユーザー情報をリクエストする

サーバーは User タイプで定義されているすべてのフィールドを返すことができる

しかし、サーバーはクエリで明示的に指定したフィールドだけを返す

例：もしこうクエリしたら

{
  "query": "query GetUser($id: ID!) { user(id: $id) { id email } }",
  "variables": {
    "id": "1"
  }
}

返ってくるのは id と email のみです。

User に name や phone、address といった他のフィールドがあっても返りません。

Great! これがGraphQLの強み：

クライアントが欲しいデータを正確に指定できる

3. Apolloとは

Apolloは、GraphQLを実装するためのツールやライブラリを開発している会社およびエコシステムです。Apolloのツールを使うことで、バックエンドとフロントエンドの開発者が、GraphQL APIをより簡単に構築・運用・利用できるようになります。

Apollo Server

GraphQLのバックエンドサーバーを簡単に構築できるようにするツールです。

例：スキーマを定義する

type Query {
  user(id: ID!): User
}

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

Apollo Client

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      email
    }
  }`;

const { data, loading, error } = useQuery(GET_USER, {
  variables: { id: "1" },
});

 

RESTとGraphQLのスキーマ定義

GraphQLではスキーマの定義が必須ですが、REST APIでは技術的には必須ではありません。 しかし、最近のREST APIプロジェクトではOpenAPIを利用し、スキーマを定義するケースが増えています。

OpenAPIの主なメリット

• ドキュメント生成：人間にも機械にも読みやすいAPI仕様書を生成
• 一貫性のあるAPI設計：リクエスト・レスポンスのフォーマットを統一
• ツール連携：APIクライアント（例：TypeScriptのAPIファイル）を自動生成
• 型安全性の向上：フロントエンド開発者がTypeScriptの型補完機能を利用可能
• バリデーション機能：バックエンドでリクエストの検証が可能

結局のところ、RESTかGraphQLかを選択する際は、チームがAPIをどのように設計・運用・スケールさせるかが鍵となります。

 

まとめ

REST API と GraphQL は、それぞれ異なる特性を持ちます。 RESTはシンプルで分かりやすい設計、GraphQLは柔軟なデータ取得が可能です。 プロジェクトの要件や開発環境に応じて、適切な技術を選択することが重要です。