はじめに

Web開発では、システム同士を連携するために「API」が使われます。
代表的なAPIには

REST API
SOAP API
GraphQL

がありますが、「違いが分からないまま使っている」というケースも多いのではないでしょうか。

本記事では、それぞれの特徴と違いを整理します。

REST API

RESTはHTTPの仕組みに沿ったシンプルなAPI設計スタイルです。

特徴

リソース指向
データを「リソース」としてURLで表現する（例：/users/1）
ステートレス
リクエストごとに完結し、サーバーは状態を保持しない
HTTPメソッドで操作
操作はHTTPメソッドで表現する
- 取得：GET
- 作成：POST
- 置換：PUT
- 更新：PATCH
- 削除：DELETE

メリット

シンプルで理解しやすい
HTTP標準に乗るため学習コストが低い
スケーラブル（分散しやすい）
キャッシュが効く

デメリット

必要以上のデータ取得（オーバーフェッチ）
エンドポイントが増えがち
複雑な取得条件に弱い

サンプル

リクエスト

ユーザー取得

curl -X GET "https://example.com/users/1" \
     -H "Accept: application/json"

ユーザー更新

curl -X PATCH "https://example.com/users/1" \
     -H "Content-Type: application/json" \
     -d '{"name": "Taro Updated"}'

ユーザー削除

curl -X DELETE "https://example.com/users/1"

レスポンス

ユーザー取得

{
  "id": 1,
  "name": "Taro",
  "email": "taro@example.com"
}

SOAP API

SOAPは厳密な仕様に基づいたメッセージ通信プロトコルです。

特徴

XMLベース
すべてのメッセージをXML形式でやり取りする
厳密な契約（WSDL）
API仕様が事前に定義され、インターフェースが保証される
高い信頼性
セキュリティやトランザクションなどの標準仕様が用意されている

メリット

仕様が厳密で安全性が高い
トランザクションやセキュリティに強い
大規模・基幹システム向き

デメリット

XMLで冗長
実装が複雑
Webフロントとの相性が悪い

サンプル

リクエスト

ユーザー取得

curl -X POST "https://example.com/UserService" \
     -H "Content-Type: text/xml" \
     -d '
<Envelope>
  <Body>
    <GetUser>
      <Id>1</Id>
    </GetUser>
  </Body>
</Envelope>'

ユーザー更新

curl -X POST "https://example.com/UserService" \
     -H "Content-Type: text/xml" \
     -d '
<Envelope>
  <Body>
    <UpdateUser>
      <User>
        <Id>1</Id>
        <Name>Taro Updated</Name>
      </User>
    </UpdateUser>
  </Body>
</Envelope>'

ユーザー削除

curl -X POST "https://example.com/UserService" \
     -H "Content-Type: text/xml" \
     -d '
<Envelope>
  <Body>
    <DeleteUser>
      <Id>1</Id>
    </DeleteUser>
  </Body>
</Envelope>'

レスポンス

ユーザー取得

<Envelope>
  <Body>
    <GetUserResponse>
      <User>
        <Id>1</Id>
        <Name>Taro</Name>
        <Email>taro@example.com</Email>
      </User>
    </GetUserResponse>
  </Body>
</Envelope>

GraphQL

GraphQLはクライアントが必要なデータ構造を指定できるAPIのクエリ言語です。

特徴

必要なデータだけ取得
クエリで取得するフィールドを指定できる
単一エンドポイント
すべての操作を1つのURLで扱う
スキーマ駆動
型定義（スキーマ）に基づいてAPIが構築される

メリット

オーバーフェッチを回避しやすい
フロントエンド主導でデータ取得可能
APIの変更に強い

デメリット

キャッシュが難しい（HTTPキャッシュが効きにくい）
学習コストがやや高い
サーバー実装が複雑になりやすい

サンプル

リクエスト

ユーザー取得

curl -X POST "https://example.com/graphql" \
     -H "Content-Type: application/json" \
     -d '{"query": "query { user(id: 1) { name email }}"}'

ユーザー更新

curl -X POST "https://example.com/graphql" \
     -H "Content-Type: application/json" \
     -d '{"query": "mutation { updateUser(id: 1, name: \"Taro Updated\") { id name } }"}'

ユーザー削除

curl -X POST "https://example.com/graphql" \
     -H "Content-Type: application/json" \
     -d '{"query": "mutation { deleteUser(id: 1){success} }"}'

レスポンス

ユーザー取得

{
  "data": {
    "user": {
      "name": "Taro",
      "email": "taro@example.com"
    }
  }
}

比較

一覧表

観点	REST API	SOAP API	GraphQL
設計思想	リソース指向	プロトコルベース	クエリ言語
データ形式	JSON	XML	JSON
エンドポイント	複数	複数	1つ
データ取得	固定	固定	柔軟
学習コスト	低	高	中
パフォーマンス	良い（キャッシュ有効）	重い（XMLベース）	効率的（必要データのみ取得）
キャッシュ	しやすい	しにくい	難しい

ざっくりした使い分け

この軸で選べば、大きく外すことはありません。

とりあえず迷ったら… REST API

CRUD中心
Web / モバイルAPI

厳密性・信頼性を優先したいなら… SOAP API

金融
基幹システム
企業間連携

フロント主導・複雑なデータ取得が必要なら… GraphQL

SPA（React / Vue）
モバイル通信最適化

おわりに

重要なのは「どれが優れているか」ではなく、ユースケースに合っているかです。

シンプルさ → REST
厳密性 → SOAP
柔軟性 → GraphQL

という軸で選ぶと、大きく外しません。

またAPI選定は単なる技術選びではなく、設計思想の選択でもあります。
本記事が、その判断の軸になれば幸いです。