API連携を計画する
このページで学ぶこと
Section titled “このページで学ぶこと”- API連携を要件・画面・システム・運用の四つに分ける方法
- 認証と認可、APIキー、OAuth等の基本的な違い
- CORS、レート制限、タイムアウト、再試行の意味
- 正常時だけでなくエラー・停止・仕様変更を設計する方法
- テスト環境、SLA、費用、契約、個人情報の確認事項
API連携は「URLへアクセスしてデータを取得する」だけの作業ではありません。
flowchart TD
B[業務・画面要件] --> S[API仕様]
S --> A[認証・権限]
S --> L[件数・速度・利用制限]
S --> E[エラー・停止時]
S --> T[テスト環境]
S --> O[監視・変更管理]
S --> C[契約・費用・データ]
正常に一度動かすだけなら短期間でも、実運用ではアクセス増加、外部障害、仕様変更、誤入力、二重送信等が起きます。
API連携の見積とスケジュールは、これらをどこまで扱うかで変わります。
最初に業務・画面要件を整理する
Section titled “最初に業務・画面要件を整理する”API仕様書を読む前に、Webサイト側で必要なことを明確にします。
何をしたいか
Section titled “何をしたいか”- 一覧を表示したい
- 条件検索したい
- 詳細を表示したい
- 申し込みたい
- 更新したい
- 状態を確認したい
- 外部システムへ通知したい
利用者へ何を見せるか
Section titled “利用者へ何を見せるか”- 読み込み中
- 結果
- 0件
- 入力エラー
- 一時的な障害
- 利用不可
- 再試行
- 完了
- 取消・変更
いつ最新である必要があるか
Section titled “いつ最新である必要があるか”- 常に最新
- 数分遅れてもよい
- 1日一回でよい
- 公開時点の情報でよい
- 申込時だけ再確認する
この整理がないと、APIから取得できる項目を並べただけの画面になります。
API仕様の適合性を確認する
Section titled “API仕様の適合性を確認する”APIが存在しても、Webサイトの要件に合うとは限りません。
| 要件 | 確認例 |
|---|---|
| 検索 | AND・OR、部分一致、並び順、距離検索が可能か |
| 一覧 | 最大件数、ページング、合計件数が返るか |
| 詳細 | 必要項目、関連データ、公開状態が返るか |
| 更新 | 作成・変更・削除が可能か、承認が必要か |
| 最新性 | 更新後いつ取得できるか |
| 多言語 | 言語別項目、フォールバックがあるか |
| 画像 | サイズ、形式、URL期限、加工機能 |
| 履歴 | 更新日時、変更者、監査ログ |
| 個別情報 | ログイン利用者だけ取得できるか |
不足機能をWebサイト側で補えるか、API側改修が必要かを切り分けます。
API側の改修が別会社の場合、見積・スケジュール・責任を分けます。
認証は「誰・どのシステムかを確認すること」、認可は「何をしてよいかを決めること」です。
flowchart LR
R[APIリクエスト] --> A{認証情報は正しいか}
A -->|いいえ| X[拒否]
A -->|はい| P{その操作を許可されているか}
P -->|いいえ| Y[権限不足]
P -->|はい| O[処理を実行]
発行された文字列をリクエストへ付け、利用プロジェクト等を識別します。
- 実装が比較的単純
- 読み取り専用・書き込み可能等の権限がある場合
- ブラウザ公開可否を確認
- 流出時の再発行・無効化が必要
- 環境ごとに分ける
利用者が外部サービス上で許可し、アクセストークンを使って処理する方式です。
- 利用者本人のデータへアクセスする連携
- 有効期限・更新
- 許可範囲
- ログアウト・連携解除
- 同意画面
等の設計が必要です。
サービス間認証
Section titled “サービス間認証”サーバー同士で証明書、署名、トークン等を使います。
秘密情報を安全に保存し、定期更新・漏えい時の交換手順を用意します。
APIキーやアカウントには、必要な操作だけを許可します。
記事取得だけのWebサイトに、コンテンツ削除や管理者操作の権限は不要です。
- 読み取りと書き込みを分ける
- 本番と検証を分ける
- 機能ごとにキーを分ける
- 利用元IP・ドメインを制限する
- 有効期限・ローテーションを決める
- 退場者・終了システムの権限を削除する
一つの高権限キーを複数案件・環境で共有すると、影響範囲が大きくなります。
ブラウザには、異なるオリジンへの通信を制限する仕組みがあります。
オリジンは、概念的にはスキーム、ホスト、ポートの組み合わせです。
たとえばWebサイトとAPIのドメインが異なると、API側がそのWebサイトからのアクセスを許可するCORS設定が必要になる場合があります。
sequenceDiagram
participant B as ブラウザ
participant A as 別ドメインのAPI
B->>A: このサイトから呼んでよいか確認
A-->>B: 許可するオリジン・方法を回答
alt 許可
B->>A: APIリクエスト
A-->>B: レスポンス
else 不許可
B-->>B: ブラウザが利用を遮断
end
CORSエラーは、API自体が停止しているとは限りません。
サーバー同士の通信では成功する一方、ブラウザからだけ失敗することがあります。
CORSは認証の代わりではありません。許可されたオリジンからでも、不正利用への認証・権限・入力検証は必要です。
レート制限とクォータ
Section titled “レート制限とクォータ”APIは一定時間内のリクエスト数や、月間利用量を制限することがあります。
- 1秒あたり
- 1分あたり
- 1日あたり
- 同時接続数
- 1回の取得件数
- 月間利用回数
- データ転送量
制限を超えると、エラー、待機、追加料金等が発生します。
- キャッシュする
- 入力のたびではなく確定時に検索する
- リクエストをまとめる
- ページングする
- 再試行間隔を設ける
- アクセス集中時の上限を見積もる
- 利用量アラートを設定する
無限スクロール、リアルタイム入力検索、地図移動ごとの検索等は、API呼び出し数を増やします。
画面仕様と利用制限を一緒に設計します。
タイムアウト
Section titled “タイムアウト”APIが返るまで無制限に待つと、画面が止まったように見え、サーバー資源も消費します。
一定時間で待機を打ち切るタイムアウトを設定します。
タイムアウト時間は一律ではありません。
- 検索候補：短い応答が求められる
- ファイル生成：長くかかる場合がある
- 決済：結果確認が重要
- 夜間バッチ：画面操作より長く待てる
タイムアウト後に、処理が本当に失敗したのか、提供側では完了しているのか確認が必要な処理もあります。
一時的な通信エラーでは、再試行で成功する場合があります。
しかし、すべてを無条件に再送してはいけません。
同じ取得を再試行しても、データを重複作成しないため比較的扱いやすいです。
登録・決済系
Section titled “登録・決済系”同じリクエストを再送すると、二重登録・二重決済になる可能性があります。
重複を防ぐ識別子や、処理結果を照会するAPIが必要です。
flowchart TD
A[登録APIを送信] --> B{応答を受信したか}
B -->|はい| C[結果を表示]
B -->|いいえ| D{提供側で処理済みか確認できるか}
D -->|はい| E[状態照会]
D -->|いいえ| F[手動確認・安全な再送設計]
PMは「再試行するか」だけでなく、「再試行して安全な処理か」を確認します。
APIはHTTPステータスや独自エラーコードで結果を返します。
大きくは次のように考えられます。
| 分類 | 概要 | 画面・運用例 |
|---|---|---|
| 成功 | 処理完了 | 結果を表示 |
| 入力・権限エラー | 要求内容や認証に問題 | 入力修正、再ログイン |
| 見つからない | 対象がない | 0件・404表示 |
| 利用制限 | 回数・容量超過 | 待機、案内、運用通知 |
| 提供側エラー | API内部の問題 | 代替表示、再試行、連絡 |
| タイムアウト | 規定時間内に応答なし | 再試行・状態確認 |
利用者へ技術的なエラー全文や秘密情報を表示しません。
運用ログには調査に必要な識別子・時刻・対象・エラー分類を残し、個人情報や秘密キーを不必要に記録しません。
複数システムを連携すると、一部だけ成功する場合があります。
例：
- フォーム内容を保存
- CRMへ登録
- 確認メール送信
- Slackへ通知
CRM登録だけ失敗した場合、利用者へ完了と表示してよいか、後から再送できるかを決めます。
flowchart LR
F[フォーム送信] --> D[自社保存]
D --> C[CRM登録]
C --> M[メール送信]
C --> N[担当通知]
各工程の成功・失敗を個別に把握し、整合を取る設計が必要です。
検証環境・テストデータ
Section titled “検証環境・テストデータ”API提供側に本番以外の環境があるか確認します。
- 開発環境
- ステージング
- サンドボックス
- モックAPI
- テストアカウント
- テスト用決済
- ダミーデータ
本番APIしかない場合、誤登録、誤メール、実在会員への影響、課金等のリスクがあります。
検証環境が本番と同じ仕様・データ量・認証かも確認します。
SLA・サポート・障害情報
Section titled “SLA・サポート・障害情報”SLAはサービス品質についての合意・目標を示すものです。
確認例：
- 稼働率
- サポート時間
- 問い合わせ手段
- 重大障害の連絡
- 復旧目標
- 計画メンテナンス
- 補償条件
- 対象プラン
SLAがあっても、Webサイトの復旧を制作会社が何もしなくてよいわけではありません。
ステータスページ、代替表示、一次切り分け、クライアント報告を決めます。
API利用料には次の形があります。
- 月額固定
- リクエスト数
- 利用者数
- 取得件数
- データ転送
- 保存容量
- 高度機能
- サポート
- 超過料金
画面仕様によって呼び出し回数が変わるため、想定利用者数と操作回数から概算します。
無料枠だけを前提に本番設計しないようにします。
仕様変更とバージョン
Section titled “仕様変更とバージョン”APIは将来変更されます。
- 項目追加
- 項目廃止
- 型変更
- 認証変更
- URL変更
- バージョン終了
- 利用制限変更
- 料金改定
互換性のない変更では、Webサイト側の改修が必要です。
確認すること：
- バージョン表記
- 廃止予告期間
- 変更通知の受信先
- テスト環境
- 移行ガイド
- 保守契約の範囲
- 改修予算
担当者個人のメールだけで通知を受けると、退職時に見落とします。共有アドレスや管理台帳を使います。
データ・個人情報
Section titled “データ・個人情報”APIで扱うデータについて確認します。
- 個人情報を含むか
- どの国・地域へ送られるか
- 保存されるか
- ログに残るか
- 暗号化されるか
- 削除依頼へ対応できるか
- 再委託先があるか
- 利用規約上の二次利用
- 取得目的と同意
- 本番データを検証に使うか
技術的に送信できることと、契約・法務上送信してよいことは別です。
実案件ではどう考えるか
Section titled “実案件ではどう考えるか”外部の施設検索API
Section titled “外部の施設検索API”- 1文字入力ごとに呼ぶのか
- 検索ボタンで呼ぶのか
- 最大結果件数
- 並び順
- キャッシュ
- 地図移動時
- 月間利用料
- 0件・遅延時
を画面設計と一緒に決めます。
- 二重決済防止
- 3Dセキュア等の認証
- 決済成功後の注文登録
- Webhook
- タイムアウト時の状態照会
- 取消・返金
- 本番・テスト環境
- 個人情報・カード情報の責任範囲
を確認します。
クライアント内製API
Section titled “クライアント内製API”仕様書が未完成、担当者しか仕様を知らない、検証環境がない場合があります。
制作着手前に、モック、サンプルデータ、項目確定日、変更凍結日、問い合わせ窓口を合意します。
PMチェックリスト
Section titled “PMチェックリスト”- 業務要件と画面要件を先に整理している
- APIが必要な検索・更新機能を持つか確認している
- 認証と権限を環境・機能ごとに分けている
- 秘密情報の保存・更新・失効方法を決めている
- CORSが必要な構成か確認している
- 最大件数、ページング、レート制限を把握している
- タイムアウト時間と再試行条件を決めている
- 二重登録・二重決済を防ぐ設計がある
- エラー・空データ・部分成功の画面を定義している
- 本番以外の検証環境とテストデータがある
- SLA、障害情報、問い合わせ窓口を把握している
- 通常時・最大時の利用料を試算している
- 仕様変更通知を共有先で受け取る
- 個人情報・ログ・データ保存の扱いを確認している
よくある誤解・失敗
Section titled “よくある誤解・失敗”「APIの仕様が決まるまで、画面だけ先に作ればよい」
Section titled “「APIの仕様が決まるまで、画面だけ先に作ればよい」”項目、件数、検索方法、応答時間、エラーによって画面仕様が変わります。モックで進める場合も前提を明記します。
「CORSエラーはフロントエンドのバグ」
Section titled “「CORSエラーはフロントエンドのバグ」”API側の許可設定や呼び出し構成に原因がある場合があります。ブラウザから呼ぶか、サーバー経由にするかも含めて判断します。
「失敗したら自動で再送すればよい」
Section titled “「失敗したら自動で再送すればよい」”登録・決済等は二重処理の危険があります。処理識別子や状態照会が必要です。
「200が返れば業務処理も成功」
Section titled “「200が返れば業務処理も成功」”HTTPとして成功でも、レスポンス内部に業務エラーが含まれるAPIがあります。成功条件を仕様で確認します。
「本番公開後に利用制限を確認すればよい」
Section titled “「本番公開後に利用制限を確認すればよい」”レート制限や料金は画面操作・キャッシュ・アクセス設計へ影響するため、要件段階で確認します。
理解度チェック
Section titled “理解度チェック”Q1. 認証と認可の違いを説明してください。
Section titled “Q1. 認証と認可の違いを説明してください。”回答と解説
認証は誰・どのシステムかを確認し、認可はその主体がどのデータや操作を許可されているかを決めます。Q2. 検索欄で文字入力のたびにAPIを呼ぶ設計では、何を確認しますか。
Section titled “Q2. 検索欄で文字入力のたびにAPIを呼ぶ設計では、何を確認しますか。”回答と解説
レート制限、料金、応答速度、入力待ち時間、リクエスト取消、キャッシュ、短すぎる検索語、アクセス集中等を確認します。Q3. 予約登録APIがタイムアウトしました。すぐ同じ内容を再送してよいでしょうか。
Section titled “Q3. 予約登録APIがタイムアウトしました。すぐ同じ内容を再送してよいでしょうか。”回答と解説
提供側では登録済みの可能性があるため、無条件再送は危険です。識別子による重複防止や状態照会を使います。Q4. API提供側の検証環境がない場合、どのような対策が考えられますか。
Section titled “Q4. API提供側の検証環境がない場合、どのような対策が考えられますか。”回答と解説
モックAPI、ダミーアカウント、本番で影響しないデータ、操作制限、試験時間、削除手順、提供側立会い等を合意します。Q5. API仕様変更の見落としを防ぐには何をしますか。
Section titled “Q5. API仕様変更の見落としを防ぐには何をしますか。”回答と解説
共有メールで通知を受け、バージョン・廃止日を台帳管理し、保守担当と改修予算を決め、検証環境で事前確認します。- Google Cloud「REST API の基本と実装」
https://cloud.google.com/discover/what-is-rest-api?hl=ja - OpenAPI Initiative「OpenAPI Specification」
https://spec.openapis.org/
API仕様を人間とツールが理解できる標準形式の公式仕様。 - MDN「HTTP response status codes」
https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status
HTTPレスポンスの成功・クライアントエラー・サーバーエラー等の分類を確認する公式リファレンス。 - MDN「Cross-Origin Resource Sharing (CORS)」
https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS
ブラウザから異なるオリジンへ通信する際の許可方式を確認する公式解説。