外部IF REST API 仕様

目的: 外部システムとの連携に使用するREST APIの仕様を明確に定義し、システム間のインターフェース設計の一貫性を確保し、開発・テスト・運用における認識齟齬を防ぐ
スコープ: 外部システムとの間でやり取りするREST APIのエンドポイント、リクエスト/レスポンス形式、認証方式、エラーハンドリング、性能要件をカバーする。内部API設計や詳細な実装仕様は対象外
推奨する実施タイミング: 外部システムとの連携要件が確定し、システムアーキテクチャ設計が完了した後、基本設計の中盤で実施する
関連するステークホルダー: システムアーキテクト、アプリケーション開発担当、外部システム担当者、セキュリティチーム、テスト担当

📥 重要な前提知識・インプット

前提知識: REST API設計原則（リソース指向、HTTPメソッドの適切な使用）、HTTP仕様（ステータスコード、ヘッダー）、JSON/XML形式、認証・認可方式（OAuth2.0、JWT、APIキー等）、APIバージョニング戦略、OpenAPI Specification (Swagger)
インプット: 外部システム連携要件書、システム間インターフェース一覧、既存外部システムのAPI仕様書、セキュリティポリシー（認証方式、暗号化要件）、非機能要件（性能目標値、タイムアウト時間、可用性目標）、システムアーキテクチャ設計書

📄 成果物の定義

ドキュメントテンプレート: 📄[テンプレ]外部IF REST API 仕様
必須要素: 外部インターフェース一覧、API仕様書（各エンドポイントの詳細）、リクエスト/レスポンス定義、エラーコード一覧、認証・認可仕様、性能要件・タイムアウト設定

✅ 品質基準・レビュー観点

✅ 品質チェックリスト:

チェック項目	チェック内容
エンドポイント設計	リソース指向のURL設計になっているか、HTTPメソッドが適切に使用されているか
データ形式の明確性	リクエスト/レスポンスのデータ型、必須/任意が明確に定義されているか
エラーハンドリング	全ての想定エラーケースとエラーコードが定義されているか
認証・認可	セキュリティポリシーに準拠した認証方式が定義されているか
性能要件	タイムアウト時間、レート制限、レスポンスタイム目標値が明記されているか
バージョニング	API バージョン管理の方針が定義されているか

👁️‍🗨️ レビュー観点:

要件との整合性: 外部システム連携要件が漏れなく API 仕様に反映されているか
セキュリティ: 認証・認可・暗号化・データ保護の要件が満たされているか
可用性・性能: タイムアウト、リトライ、エラーハンドリングが適切に設計されているか
実装可能性: 外部システム側と自システム側の双方で実装可能な仕様か
保守性: API ドキュメントが第三者にも理解可能で、将来の変更に対応できる設計か

🧪成果物のサンプル

# IF-001: ユーザー情報取得API

**概要:**
認証基盤からユーザーの基本情報（ID、氏名、メールアドレス、ステータス等）を取得するためのREST APIインターフェース。ユーザー認証後の画面表示や権限チェックに使用する。

**エンドポイント:**
```
GET /api/v1/users/{user_id}
```

**リクエストヘッダー:**
```
Authorization: Bearer {access_token}
Content-Type: application/json
```

**リクエストパラメータ:**
| パラメータ名 | 型 | 必須 | 説明 |
|------------|-----|-----|------|
| user_id | string | ○ | ユーザーID |

**レスポンス例（正常時）:**
```json
{
  "user_id": "user_12345",
  "name": "山田太郎",
  "email": "yamada@example.com",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z"
}
```

**レスポンス例（エラー時）:**
```json
{
  "error_code": "USER_NOT_FOUND",
  "message": "指定されたユーザーが見つかりません",
  "request_id": "req_abc123"
}
```

**ステータスコード:**
- 200: 成功
- 400: リクエスト不正
- 401: 認証エラー
- 404: ユーザー不存在
- 500: サーバーエラー

**タイムアウト:** 10秒

---

🔄 設計の進め方・プロセス

🏗️ プロセス1: 外部インターフェース一覧の整備

設計対象:

外部システムとの連携に必要な REST API の全体像を把握し、インターフェース一覧を作成する。

具体例:

どの外部システムと連携するか（認証基盤、決済サービス、通知サービス等）
各システムとの間でどのようなデータをやり取りするか
連携のタイミング（リアルタイム／バッチ／イベント駆動）
連携の方向（自システム→外部、外部→自システム、双方向）

設計原則:

全体俯瞰の実施: 外部システム連携要件を網羅的に洗い出し、漏れがないように一覧化する
優先順位の明確化: 必須の連携と任意の連携を区別し、開発の優先順位を明確にする
影響範囲の把握: 各インターフェースの障害時の影響範囲とリトライ要否を整理する
バージョン管理の方針: 将来の API 変更に備え、バージョニング戦略を初期段階で定める

文書化の推奨表現:

インターフェース一覧表の作成: IF-ID、連携先システム名、API 名、連携方向、連携タイミング、優先度を一覧化する
連携フロー図の作成: システム間のデータフロー全体を視覚的に表現する
依存関係の明記: どのインターフェースが他のインターフェースに依存しているかを記録する

🏗️ プロセス2: API エンドポイント設計とリクエスト/レスポンス定義

設計対象:

各 REST API のエンドポイント、HTTP メソッド、リクエスト/レスポンス形式を詳細に定義する。

具体例:

エンドポイント URL の設計（例: GET /api/v1/users/{user_id}）
HTTP メソッドの選定（GET／POST／PUT／DELETE）
リクエストパラメータ（パスパラメータ、クエリパラメータ、ボディ）の定義
レスポンス形式（JSON／XML）とデータ項目の定義
ページネーション、ソート、フィルタリングの方式

設計原則:

REST 原則の遵守: リソース指向の URL 設計とし、HTTP メソッドを適切に使い分ける
データ型の明確化: 各項目のデータ型（string／number／boolean 等）、必須／任意、制約条件を明記する
拡張性の考慮: 将来の項目追加に備え、柔軟な JSON 構造とする
一貫性の確保: プロジェクト全体で命名規則やデータ形式を統一する
外部システムとの合意: 外部システム担当者と仕様をレビューし、認識齟齬がないことを確認する

文書化の推奨表現:

API 仕様書の作成: 各エンドポイントごとに、概要、URL、メソッド、パラメータ、レスポンス例を記載する
OpenAPI Specification の活用: Swagger 等のツールで API 仕様を記述し、ドキュメント生成とモックサーバー構築を容易にする
サンプルリクエスト/レスポンスの提示: 具体的な JSON サンプルを記載し、実装者が直感的に理解できるようにする

🏗️ プロセス3: 認証・認可方式とセキュリティ仕様

設計対象:

REST API へのアクセスを保護するための認証・認可の仕組みとセキュリティ要件を定義する。

具体例:

認証方式の選定（OAuth2.0、JWT、API キー、Basic 認証等）
認可の仕組み（ロールベースアクセス制御、スコープ管理）
アクセストークンの取得方法とライフサイクル
HTTPS 通信の必須化と証明書管理
レート制限（Rate Limiting）の設定

設計原則:

セキュリティポリシーの遵守: 組織のセキュリティ標準に従い、承認された認証方式を採用する
最小権限の原則: API ごとに必要最小限のアクセス権限を設定する
通信の暗号化: 全ての通信を HTTPS で保護し、機密情報を平文で送信しない
トークンの適切な管理: アクセストークンの有効期限を設定し、リフレッシュトークンの運用を定める
攻撃への対策: SQLインジェクション、XSS、CSRF 等の一般的な攻撃への対策を実施する

文書化の推奨表現:

認証フローの図示: トークン取得から API 呼び出しまでのシーケンス図を作成する
セキュリティ要件一覧: 暗号化方式、トークン有効期限、レート制限値等を一覧化する
エラーハンドリング: 認証失敗時のエラーコードとメッセージを明記する

🏗️ プロセス4: エラーハンドリングと例外処理

設計対象:

API 呼び出し時に発生しうるエラーケースを洗い出し、エラーコードとエラーメッセージを定義する。

具体例:

HTTP ステータスコードの使い分け（200／400／401／404／500 等）
アプリケーション固有のエラーコード体系
エラーレスポンスの形式（エラーコード、メッセージ、詳細情報）
リトライ可能なエラーと不可能なエラーの区別
タイムアウト発生時の挙動

設計原則:

網羅的なエラー定義: 想定されるエラーケースを漏れなく洗い出し、適切なステータスコードを割り当てる
利用者にわかりやすいメッセージ: エラーメッセージは問題の原因と対処方法が理解できる内容とする
セキュリティへの配慮: エラーメッセージから内部実装やデータベース構造が推測できないようにする
ログとの連携: エラー発生時には request_id 等を返し、ログとの紐付けを可能にする
リトライポリシーの明確化: どのエラーでリトライすべきか、リトライ間隔と回数を定める

文書化の推奨表現:

エラーコード一覧表の作成: エラーコード、HTTP ステータス、メッセージ、原因、対処方法を一覧化する
エラーレスポンス例の提示: 各エラーケースのレスポンス JSON サンプルを記載する
リトライフロー図: リトライロジックをフローチャートで表現する

🏗️ プロセス5: 性能要件とタイムアウト設定

設計対象:

各 API の性能目標値、タイムアウト時間、レート制限を定義する。

具体例:

レスポンスタイム目標値（例: 95パーセンタイルで 500ms 以内）
スループット目標値（例: 1000リクエスト/秒）
タイムアウト時間（接続タイムアウト、読み取りタイムアウト）
レート制限（例: 1ユーザーあたり 100リクエスト/分）
データサイズ制限（リクエストボディの最大サイズ）

設計原則:

非機能要件との整合: システム全体の性能要件に基づき、各 API の性能目標を設定する
現実的な目標設定: 外部システムの性能特性やネットワーク遅延を考慮した達成可能な目標とする
タイムアウトの適切な設定: 長時間待たせすぎず、かつ正常処理が完了できる余裕を持った時間を設定する
負荷対策: レート制限により、過負荷や DDoS 攻撃からシステムを保護する
監視との連携: 性能目標値を監視項目として設定し、継続的にパフォーマンスを追跡する

文書化の推奨表現:

性能要件一覧表: API ごとにレスポンスタイム目標、スループット、タイムアウト時間を一覧化する
負荷試験計画: 性能要件を検証するための負荷試験シナリオを記載する
性能劣化時の対応: 性能目標未達時のエスカレーション手順を定める

🚨 よくある失敗と予防策　

🚧 実例収集後、追記予定

📚 参考資料・関連リンク

参考文献: 『RESTful Web APIs』（Leonard Richardson / Mike Amundsen）、『Web API: The Good Parts』（水野貴明）、RFC 9110（HTTP Semantics）
関連する他のガイド: システムアーキテクチャ設計、セキュリティ仕様・方式、非機能要件の実現方式、アプリケーション共通処理方式
ツール・テンプレート: OpenAPI Specification (Swagger)、Postman、draw.io、Mermaid（シーケンス図）

テンプレートサイト: 📄テンプレート集