外部システムやSaaSとAPI連携するWebシステムでは、正常にデータを取得できることだけを確認しても十分ではありません。
実際の運用では、
- 認証情報が無効になる
- 外部APIが一時的に停止する
- 通信がタイムアウトする
- リクエストは成功したがレスポンスを受信できない
- 同じ処理が複数回実行される
- APIの利用上限に達する
- 想定していないレスポンスが返ってくる
といったケースが発生します。
例えば、受注情報を外部の在庫管理システムへAPI連携している場合、
注文登録
↓
在庫APIを呼び出す
↓
在庫を引き当てる
↓
成功レスポンスを受信
という正常系だけを確認していても、本番運用では不十分です。
API呼び出し後に通信が切れ、
「外部システムでは在庫引当済みだが、自社システムでは失敗扱い」
になることも考えられます。
結論からいうと、API連携のテストでは、
正常に通信できるかだけでなく、失敗したときにシステムが正しい状態を維持できるかを確認することが重要です。
この記事では、API連携のテスト方法を、正常系・異常系・境界値・タイムアウト・再送・重複処理・レート制限などの観点から具体的に解説します。
API連携テストとは
API連携テストとは、自社システムと外部システムがAPIを通じて正しくデータをやり取りできるか確認するテストです。
例えば、
自社ECサイト
↓
決済API
↓
決済サービス
自社顧客管理システム
↓
会計API
↓
会計システム
予約システム
↓
メールAPI
↓
メール配信サービス
といった連携があります。
確認するのは単純な通信成功だけではありません。
主に、
- リクエスト
- 認証
- レスポンス
- データ変換
- エラー処理
- タイムアウト
- 再実行
- ログ
- 外部サービス障害時の挙動
まで確認します。
API単体テストとAPI連携テストの違い
APIテストには複数のレベルがあります。
API単体テスト
自社で作ったAPIの一つの処理を確認します。
例えば、
POST /customers
へ正常な顧客情報を送信したら、顧客が登録されるか確認します。
API結合・連携テスト
複数システムを実際につないで確認します。
例えば、
自社システム
↓
外部決済API
↓
決済成功
↓
自社DBの契約状態更新
まで一連の流れを確認します。
外部APIを利用するシステムでは、単体テストだけでなく連携全体を確認する必要があります。
API連携テストで最初に整理すること
テストケースを作る前に、API連携の仕様を整理します。
最低限、次の情報を確認します。
- エンドポイント
- HTTPメソッド
- 認証方式
- リクエスト項目
- 必須・任意項目
- レスポンス項目
- HTTPステータスコード
- タイムアウト
- レート制限
- 再送ルール
- エラーコード
- Webhookの有無
例えば顧客登録APIなら、
POST /customers
リクエスト：
- name：必須
- email：必須
- phone：任意
レスポンス：
- customer_id
- name
- created_at
などを整理します。
API仕様が曖昧な状態でテストを開始すると、「何が正しい結果なのか」を判断できません。
API連携テストの基本的な流れ
一般的には次のような順番で確認すると整理しやすくなります。
- 正常系
- 入力値異常
- 認証・認可
- 外部APIエラー
- タイムアウト
- 再送
- 重複処理
- レート制限
- データ整合性
- ログ・監視
最初から特殊なケースだけを確認するのではなく、基本動作から順番に確認します。
テスト1．正常系を確認する
まずは想定通りのデータを送信し、正常に処理できるか確認します。
例えば商品登録APIなら、
商品名：テスト商品
価格：1,000円
在庫：10
を送信します。
確認する内容は、
- HTTPステータスコード
- レスポンス内容
- DB登録結果
- 外部システム側の登録結果
- 日時
- ID
- ステータス
などです。
例えば、
HTTP 201 Created
が返っただけでテスト終了とは限りません。
実際に外部システムへデータが登録されているか、その内容が正しいかまで確認します。
正常系でも複数パターンを確認する
正常系は1パターンだけとは限りません。
例えば予約APIなら、
- 最小人数で予約
- 最大人数で予約
- 任意項目あり
- 任意項目なし
- 当日予約
- 翌月予約
などがあります。
「成功するデータを1件送ったら終わり」ではなく、業務上発生する代表的な正常パターンを確認します。
テスト2．必須項目がない場合を確認する
次に異常系です。
例えば顧客登録APIでemailが必須なら、
emailなし
のリクエストを送信します。
確認する内容は、
- 適切なエラーになるか
- エラーコードは正しいか
- エラーメッセージは適切か
- DBへ途中データが登録されていないか
です。
重要なのは、
「エラーになること」
だけではありません。
エラー後にシステムが中途半端な状態になっていないかも確認します。
テスト3．不正なデータ型を確認する
例えばpriceが数値であるAPIへ、
price = “abc”
を送信します。
ほかにも、
- 日付項目へ文字列
- 数値項目へ負数
- Booleanへ不正値
- 配列へ文字列
- 存在しないID
などをテストします。
APIではフロントエンド側で入力制御していても、直接APIへ不正な値を送信できます。
そのため、サーバー側でバリデーションされていることが重要です。
テスト4．境界値を確認する
API連携では境界値テストも重要です。
例えば商品数量の条件が、
1〜100
であれば、
- 0
- 1
- 100
- 101
を確認します。
文字数制限が100文字なら、
- 99文字
- 100文字
- 101文字
などです。
代表的な境界値には、
- 最小値
- 最大値
- 最小値の1つ下
- 最大値の1つ上
- 空文字
- NULL
があります。
正常系だけでは見つからない不具合を検出しやすくなります。
テスト5．認証エラーを確認する
外部APIではAPIキーやアクセストークンなどを利用することがあります。
例えば、
Authorization: Bearer xxx
のような認証です。
確認するケースには、
- トークンなし
- 不正なトークン
- 有効期限切れ
- 無効化されたAPIキー
- 必要な権限を持たないトークン
などがあります。
このとき、
401 Unauthorized
403 Forbidden
など、仕様に応じたレスポンスを正しく処理できるか確認します。
認証失敗時に無限リトライしないことも重要
認証情報が間違っている場合、何度再送しても基本的には成功しません。
それにもかかわらず、
認証失敗
↓
自動再送
↓
認証失敗
↓
自動再送
を繰り返すと、無意味な処理になります。
認証エラーなど「再実行しても改善しにくいエラー」と、通信障害など「再実行で成功する可能性があるエラー」を分けることが重要です。
テスト6．権限不足を確認する
APIキーやユーザーによって操作可能な範囲が異なる場合があります。
例えば、
閲覧権限のみ
のユーザーが、
DELETE /customers/123
を実行した場合です。
このとき削除できてはいけません。
業務システムでは、
- 閲覧
- 登録
- 編集
- 削除
- 承認
- CSV出力
など操作ごとに権限が異なる場合があります。
APIレベルでも認可が正しく機能するか確認します。
テスト7．存在しないデータを指定する
例えば、
GET /customers/999999
で、存在しないIDを指定します。
確認するのは、
- 404など適切なレスポンスになるか
- 500エラーにならないか
- 呼び出し元で正しく処理できるか
です。
存在しないデータは実運用でも発生します。
例えば別のユーザーが直前に削除したデータへアクセスすることもあります。
テスト8．外部APIが500エラーを返した場合を確認する
自社システムが正常でも、外部API側で障害が発生する可能性があります。
例えば、
POST /orders
↓
外部システム
↓
HTTP 500 Internal Server Error
となった場合です。
ここで確認したいのは、
- ユーザーへ適切なエラーを表示するか
- ログを記録するか
- 自動再送するか
- 管理者へ通知するか
- 自社DBが中途半端な状態にならないか
です。
外部サービスは自社で完全にコントロールできないため、失敗を前提に設計・テストする必要があります。
テスト9．タイムアウトを確認する
API連携で特に重要なのがタイムアウトです。
例えば外部APIを呼び出したものの、30秒経ってもレスポンスが返ってこないケースです。
このとき自社システムが永遠に待ち続ける設計では問題があります。
例えば、
API呼び出し
↓
10秒経過
↓
タイムアウト
↓
エラー記録
↓
必要に応じて再送
という処理を設計します。
テストでは、意図的にレスポンスを遅延させて確認します。
タイムアウト時は「外部処理が失敗した」とは限らない
ここがAPI連携で難しいポイントです。
例えば決済APIへ、
10,000円を決済
というリクエストを送りました。
外部決済サービス側では、
決済成功
しています。
しかし、その直後に通信が切れて、自社システムはレスポンスを受信できませんでした。
自社側では、
タイムアウト
＝
決済失敗？
となります。
しかし実際には決済済みです。
この状態で同じ決済を再実行すると、二重決済になる可能性があります。
そのため、タイムアウト時の挙動は特に慎重にテストする必要があります。
テスト10．再送処理を確認する
通信障害などでは、一定回数のリトライを行うことがあります。
例えば、
1回目
↓
失敗
1秒待機
↓
2回目
↓
失敗
2秒待機
↓
3回目
↓
成功
という処理です。
テストでは、
- 何回まで再送するか
- 再送間隔
- 再送対象エラー
- 上限到達時の処理
を確認します。
リトライはすべてのエラーで行わない
例えば、
400 Bad Request
は送信データ自体に問題がある可能性が高いため、同じデータを何度送っても成功しにくいエラーです。
一方、
500 Internal Server Error
503 Service Unavailable
タイムアウト
などは一時的な障害である可能性があります。
エラー種別に応じて再送するか判断します。
テスト11．重複リクエストを確認する
API連携では同じリクエストが複数回送信される可能性があります。
例えばユーザーが、
「注文する」
ボタンを2回押した場合です。
注文APIが2回実行されると、
同じ注文が2件登録
される可能性があります。
さらに自動リトライでも重複する可能性があります。
そこで重要になるのが冪等性です。
冪等性とは
同じ処理を複数回実行しても、結果が不必要に重複しない性質です。
例えば注文番号、
ORDER-12345
を一意なキーとして、
1回目
→ 注文作成
2回目
→ すでに存在するため新規作成しない
という処理にします。
決済APIなどではIdempotency Keyを利用できる場合もあります。
API連携テストでは、
同じリクエストを意図的に複数回送る
テストを入れておくことが重要です。
テスト12．レート制限を確認する
外部APIには利用回数制限が設定されていることがあります。
例えば、
1分間に100リクエストまで
という制限です。
上限を超えると、
429 Too Many Requests
などが返ることがあります。
確認したいのは、
- 429を正しく判定できるか
- 一定時間待ってから再送できるか
- ユーザーへ適切な表示をするか
- 大量再送によってさらに負荷を上げないか
です。
外部API仕様にRetry-Afterなどがある場合は、それも考慮します。
テスト13．レスポンス項目が欠けている場合を確認する
正常レスポンスでも、常にすべての項目が入っているとは限りません。
例えば、
{
“customer_id”: 123,
“name”: null
}
のようなケースです。
任意項目がNULLの場合にシステムがエラーにならないか確認します。
外部APIの仕様変更などによって想定外の値が返るケースも考慮します。
テスト14．想定外のレスポンス形式を確認する
例えば通常はJSONが返るAPIで、障害時にHTMLのエラーページが返ってくることがあります。
自社システムが無条件にJSONとして解析すると、
JSON parse error
になり、元の障害原因が分かりにくくなる可能性があります。
確認するポイントには、
- Content-Type
- HTTPステータス
- レスポンスボディ
- JSON解析失敗時の処理
があります。
テスト15．データ変換を確認する
API間でデータ形式が異なることがあります。
例えば自社システムでは、
status = “ACTIVE”
外部システムでは、
status = 1
としている場合です。
その場合、
ACTIVE
↓
1
INACTIVE
↓
0
という変換処理が必要です。
確認する対象には、
- ステータス
- 日付
- 時刻
- 金額
- 通貨
- Boolean
- コード値
などがあります。
日付・タイムゾーンは特に注意する
例えば、
2026-08-01T00:00:00Z
と、
2026-08-01 00:00:00
では意味が異なる可能性があります。
UTCなのか日本時間なのかによって日付が変わることもあります。
API連携では、
- タイムゾーン
- ISO形式
- 日付だけか日時か
- サマータイム
なども確認します。
テスト16．大きなデータを送信する
例えば1件のデータだけでは正常でも、
1,000件
10,000件
と増えると問題が発生する可能性があります。
確認する内容には、
- レスポンス時間
- タイムアウト
- メモリ使用量
- API制限
- 一括送信件数
- 分割処理
などがあります。
大量データ連携では、本番に近いデータ量で性能テストを行うことが重要です。
テスト17．同時実行を確認する
複数ユーザーやバッチが同時に同じデータを更新するケースもあります。
例えば在庫APIなら、
在庫残数：1
の状態で、
ユーザーA
↓
1個購入
ユーザーB
↓
同時に1個購入
すると、在庫がマイナスにならないか確認します。
APIそのものが正しくても、同時実行時にデータ不整合が発生する可能性があります。
Webhook連携では別のテストが必要
API連携では、自社から外部APIを呼び出すだけでなく、外部サービスからWebhookを受け取るケースもあります。
例えば決済サービスなら、
決済サービス
↓
決済成功Webhook
↓
自社システム
↓
契約状態更新
という流れです。
Webhookでは特に、
- 正常受信
- 署名検証
- 重複イベント
- 順不同
- 遅延
- 再送
- 不正リクエスト
を確認します。
Webhookの重複イベントを確認する
同じWebhookが複数回届く可能性があります。
例えば、
payment.completed
イベントが2回届いた場合です。
2回処理して、
契約期間を2か月延長
してしまってはいけません。
イベントIDを保存し、
すでに処理済みか確認
↓
未処理のみ実行
という設計が考えられます。
テストでも同じイベントを2回送信して確認します。
Webhookの順番が保証されないケースも考える
例えば、
subscription.updated
payment.completed
が必ず期待した順番で届くとは限らないサービスもあります。
そのため、
イベントA
↓
イベントB
だけでなく、
イベントB
↓
イベントA
でも整合性を保てるか確認する場合があります。
利用するAPI・Webhookの仕様を確認しましょう。
APIテストでモックを使う理由
外部APIを毎回実際に呼ぶと、
- API利用料金がかかる
- テストデータが外部サービスに登録される
- 外部サービスの状態にテストが依存する
- 障害状態を再現しにくい
という問題があります。
そこでモックを利用します。
モックとは、外部APIの代わりとなる疑似的なAPIです。
例えば、
正常時
→ HTTP 200
認証エラー
→ HTTP 401
障害
→ HTTP 500
タイムアウト
→ 30秒応答しない
などを意図的に再現できます。
異常系テストでは特に有効です。
モックテストだけでは終わらせない
モックは便利ですが、実際の外部APIと完全に同じとは限りません。
そのため、
開発中
モックを利用して細かな異常系を確認。
結合テスト
外部サービスのSandbox・テスト環境を利用。
リリース前
実際に近い構成でEnd-to-Endテスト。
というように使い分ける方法があります。
API連携テストで確認したいログ
API連携で障害が発生したとき、
「APIエラーになりました」
だけでは原因調査が困難です。
必要に応じて、
- API名
- 実行日時
- リクエストID
- 処理対象ID
- HTTPステータス
- エラーコード
- 処理時間
- 再送回数
などをログへ残します。
ただし、
- パスワード
- APIキー
- アクセストークン
- クレジットカード情報
- 個人情報
などを不用意にログへ記録しないよう注意が必要です。
リクエストIDを付けると障害調査しやすい
複数システムをまたぐAPI連携では、同じ処理を追跡できるIDがあると便利です。
例えば、
request_id = abc-123
として、
自社システム
↓
API Gateway
↓
外部連携処理
↓
バックグラウンドジョブ
まで共通のIDを利用します。
障害時にログ検索しやすくなります。
API連携テストの環境を分ける
可能であれば、
- 開発環境
- テスト環境
- 本番環境
を分けます。
決済サービスなどではSandboxやテストモードが提供されている場合があります。
本番APIをテストで直接利用すると、
- 実際に課金される
- 本番データが作られる
- 顧客へ通知される
などの問題につながる可能性があります。
環境ごとに、
- API URL
- APIキー
- Webhook URL
- DB
などを切り替えます。
APIテストで利用されるツール
APIの手動確認では、PostmanなどのAPIクライアントを利用する方法があります。
例えば、
- HTTPメソッド指定
- Header設定
- JSON送信
- 認証設定
- レスポンス確認
などを行えます。
また、curlなどを利用してコマンドラインからAPIを確認することもできます。
ただし、手動テストだけでは変更のたびに同じ確認を繰り返す必要があります。
重要なテストケースは自動化することを検討します。
APIテストはどこまで自動化する？
特に自動化しやすいのは、
- 正常系
- 必須チェック
- バリデーション
- 認証
- 権限
- ステータスコード
- レスポンス項目
などです。
一方、
- 外部サービス全体の障害
- 長時間タイムアウト
- 本番相当のネットワーク障害
などは別の方法で検証する場合があります。
単体テスト・結合テスト・E2Eテストを組み合わせます。
契約テストも検討する
API連携では、提供側と利用側でAPI仕様の認識がずれることがあります。
例えば提供側が、
customer_name
を、
name
へ変更した場合です。
呼び出し側が古い仕様のままなら連携が壊れます。
このような問題を減らすため、APIの入出力仕様を確認する契約テストを導入する方法があります。
特に複数チーム・複数サービスでAPI連携するシステムでは有効です。
【コピペ用】API連携テストチェックリスト
API連携をテストするときは、次の項目を確認してみてください。
正常系
- 正常なリクエスト：
- 正しいHTTPステータス：
- レスポンス内容：
- DB更新：
- 外部システム更新：
入力チェック
- 必須項目なし：
- NULL：
- 空文字：
- 不正なデータ型：
- 最小値：
- 最大値：
- 最大文字数超過：
認証・権限
- APIキーなし：
- APIキー不正：
- トークン期限切れ：
- 権限不足：
- 他ユーザー・他組織データ：
外部API障害
- 400：
- 401：
- 403：
- 404：
- 429：
- 500：
- 503：
通信
- タイムアウト：
- 接続エラー：
- 遅延：
- 再送：
- 最大再送回数：
重複
- 同一リクエスト2回：
- Idempotency Key：
- Webhook重複：
- 二重登録：
- 二重決済：
データ
- 日付：
- タイムゾーン：
- 金額：
- コード変換：
- NULL：
- 文字コード：
性能
- 大量件数：
- 同時アクセス：
- レート制限：
- レスポンス時間：
運用
- エラーログ：
- リクエストID：
- 再処理方法：
- 管理者通知：
- 障害復旧後の再実行：
API連携のテスト仕様書を作成する場合も、このような観点から整理すると漏れを減らしやすくなります。
API連携テストでよくある失敗
1．200が返れば正常と判断する
HTTPステータスが正常でも、レスポンス内容やDB状態が間違っている可能性があります。
システム全体の結果まで確認します。
2．正常系しか確認しない
API障害で問題になるのは、むしろ異常系です。
認証エラー、外部障害、タイムアウト、重複処理なども確認しましょう。
3．タイムアウト後に無条件で再送する
外部側では処理済みの可能性があります。
決済や注文登録などでは二重処理を防ぐ仕組みが必要です。
4．すべてのエラーをリトライする
不正入力や認証失敗を何度再送しても成功しない可能性があります。
再送対象を決めておくことが重要です。
5．モックだけでリリースする
モックと実際のAPIで細かな仕様が異なる可能性があります。
最終的にはSandboxなどを利用して実連携も確認します。
6．APIキーなどをログへ出力する
障害調査のためのログが、逆にセキュリティリスクになることがあります。
機密情報をマスクする設計が必要です。
7．障害後の復旧方法を決めていない
例えば会計APIが3時間停止した場合、
「停止中の100件をどう再送するのか」
を決めていなければ手作業が必要になります。
失敗データの再処理方法まで設計しておきましょう。
API連携に関するよくある質問
API連携では何をテストすればよいですか？
最低限、正常系、入力値異常、認証・認可、HTTPエラー、タイムアウト、再送、重複処理、データ整合性を確認します。
外部APIの仕様によって、レート制限やWebhookなども追加します。
APIテストはPostmanだけでできますか？
手動確認には便利ですが、繰り返し実行する重要なテストは自動化する方法もあります。
Postmanなどによる手動確認と、自動テストを目的に応じて使い分けます。
外部APIの500エラーはどうテストしますか？
モックAPIを利用して意図的に500レスポンスを返す方法があります。
外部サービスのSandboxでエラー状態を再現できる場合は、それを利用する方法もあります。
タイムアウトはどうテストしますか？
モック側でレスポンスを意図的に遅延させる方法があります。
設定したタイムアウト時間で処理を停止し、適切なエラー処理へ移行するか確認します。
API連携でリトライは必要ですか？
通信障害や一時的なサーバーエラーでは有効な場合があります。
ただし、400系エラーなど再送しても改善しにくいものまで無条件にリトライしないことが重要です。
APIの重複実行はどう防ぎますか？
処理IDやIdempotency Keyなどを利用し、同じリクエストが複数回送信されても二重登録・二重決済にならない仕組みを設計する方法があります。
WebhookもAPIテストに含めるべきですか？
Webhookを利用するシステムなら重要です。
正常受信だけでなく、署名検証、重複、再送、遅延、順不同なども確認します。
hiro-dev-labではAPI連携の設計・テスト設計から相談できます
API連携では、
「APIを呼び出して200が返った」
だけでは、安定したシステムとはいえません。
実際の運用では、
正常リクエスト
↓
外部API呼び出し
↓
成功
だけでなく、
外部API障害
↓
エラー記録
↓
再送判定
↓
復旧
↓
再処理
といった異常時の流れまで考える必要があります。
hiro-dev-labでは、Webシステム・業務システム開発の観点から、
- API連携の要求整理
- API仕様の整理
- 外部システム連携設計
- 認証・認可設計
- データマッピング
- エラーハンドリング設計
- タイムアウト・リトライ設計
- 冪等性設計
- Webhook設計
- APIテストケース作成
- ログ・監視設計
- API連携を含むWebシステム開発
など、必要な段階から相談できます。
例えば、
「外部サービスとAPI連携したいが、どこまでテストすればよいか分からない」
「正常時は動いているが、API障害時の挙動が不安」
「二重登録や二重決済を防ぎたい」
「API連携でエラーになったデータを自動で再処理したい」
といった場合は、まず連携処理の正常系と異常系を整理することで、必要なテスト項目が見えてきます。
API連携テストで重要なのは、正常に通信できることを証明するだけではありません。
外部サービスが遅い・止まる・同じ通知を複数回送るといった状況でも、自社システムのデータを壊さず、安全に復旧できることまで確認することが重要です。