ソフトウェア BA はバックエンド コードを記述する必要はありませんが、デジタル製品を作成する場合は、API とデータに関する次のような疑問が常に発生します。
- どのシステムがデータを送信しますか?
- どのフィールドが必須ですか?
- エラーが発生した場合、どのようなメッセージを返せばよいですか?
- データのソースは何ですか?
- ログを監査する必要はありますか?
- タイムアウトになった場合、API は再度呼び出されますか?
- イベントを複製することはできますか?
BA がこの部分を完全に回避すると、要件はビジネスとエンジニアリングの間の引き継ぎ領域にギャップが生じることになります。
1. API コントラクトとは何ですか?
API コントラクトは、呼び出し元と API プロバイダーの間の契約です。
通常、契約には次の内容が含まれます。
- エンドポイントまたはイベント名。
- メソッド: GET、POST、PUT、PATCH、DELETE。
- ペイロードを要求します。
- 応答ペイロード。
- 検証ルール。
- エラーコード/メッセージ。
- 認証/認可。
- レート制限または割り当て。
- バージョン管理。
- SLA/可用性。
BA はすべての技術的な決定を行う必要はありませんが、契約がビジネスを正確に反映していることを確認する必要があります。
2. データ契約とは何ですか?
データ契約は、交換または保存されるデータに関する契約です。
フィールドの例 appointmentStatus:
| 属性 | 値 |
|---|---|
| タイプ | 列挙型 |
| 許可される値 | 保留中、確認済み、キャンセル済み、完了済み、NoShow |
| 必須 | はい |
| 出典 | 予約サービス |
| オーナー | 製品運用 |
| 敏感 | いいえ |
| 保持 | 7年 |
| 使用者 | UI、レポート、通知、監査 |
フィールドに所有者がなく、不明なソース、不明な許容値がある場合、システムは UI、API、データベース、レポートの間に簡単に不一致を生じます。
3. BA 用の統合リクエスト テンプレート
# Integration Requirement
## 1. Business context
- Business process:
- Trigger:
- Actor/system:
- Success outcome:
## 2. Systems involved
- Source system:
- Target system:
- External dependency:
## 3. API / event
- Endpoint/event:
- Method:
- Authentication:
- Frequency:
- Idempotency requirement:
## 4. Request data
| Field | Type | Required | Validation | Source | Notes |
## 5. Response data
| Field | Type | Required | Meaning | UI/report usage |
## 6. Error handling
| Error | Cause | User message | Retry? | Escalation |
## 7. Non-functional requirements
- Performance:
- Availability:
- Security/privacy:
- Audit/logging:
- Monitoring:
## 8. Open questions
このテンプレートはアジャイルで使用するのに十分軽量ですが、開発と QA が自分で理解する必要がないほど明確です。
4. 例: 約束をする
要件:
患者がスロットを選択して確認をクリックすると、システムはスロットが利用可能な場合は予約を作成し、予約コードを返す必要があります。
推奨される API:
POST /appointments
リクエスト:
{
"patientId": "PAT-123",
"doctorId": "DOC-456",
"slotId": "SLOT-789",
"reason": "Follow-up consultation",
"channel": "WEB"
}
検証:
| フィールド | ルール |
|---|---|
| 患者ID | 必須、存在する必要がある、アクティブな患者 |
| 医師ID | 必須、存在する必要があります、予約を受け付けています |
| スロットID | 必須、送信時に利用可能でなければなりません |
| 理由 | オプション、最大 500 文字 |
| チャンネル | 必須、列挙型 WEB/MOBILE/CALL_CENTER |
応答成功:
{
"appointmentId": "APT-20260506-001",
"status": "Confirmed",
"confirmationCode": "XDA-8821"
}
エラー:
| コード | 原因 | ユーザーメッセージ | 3 つのメモ |
|---|---|---|---|
| スロット_使用不可 | スロットが取られました | このスロットは配置されたばかりです。別の時間を選択してください。 | 代替スロットを表示する必要があります |
| 患者をブロックしました | 患者は予約できません | 予約する前にアカウントがサポートされている必要があります。 | サポートへのルート |
| 検証_エラー | フィールドが欠落または無効です | 再度情報をご確認ください。 | フィールドを強調表示する |
| システムタイムアウト | サービスタイムアウト | システムがビジー状態です。もう一度試してください。 | 冪等性が必要 |
5. BA が開発/データ/QA に尋ねるべき質問
API を使用する場合:
- API は同期ですか、それとも非同期ですか?
- 重複を避けるために冪等キーが必要ですか?
- タイムアウトはどれくらいですか?
- 再試行はありますか?何回再試行しますか?
- どのエラーがユーザーに表示され、どのエラーがログに記録されるだけですか?
- API にはバージョンがありますか?
- 重要なリクエスト/レスポンスの監査ログはありますか?
データあり:
- フィールドの真実の情報源とはどのようなシステムですか?
- フィールドを null にすることはできますか?
- PII/PHI/財務データはありますか?
- 保存ルールと削除ルールとは何ですか?
- レポートはリアルタイム データまたはバッチ データを使用しますか?
- ソースからダッシュボードまでのデータの系統はありますか?
QA付き:
- 契約テストはありますか?
- 重複したリクエストに対するテスト ケースはありますか?
- 古いデータのテスト ケースはありますか?
- 権限テストはありますか?
- 下位互換性テストはありますか?
6. API/データ要件のチェックリスト
- エンドポイント/イベントの名前が明確になっています。
- ビジネストリガーを明確にします。
- リクエスト/レスポンスには、タイプ、必須、検証のフィールドがあります。
- エラー処理には、コード、原因、ユーザー メッセージ、再試行/エスカレーションが含まれます。
- 許可をクリアします。
- 機密データにはマークが付けられます。
- 監査/ログをクリアします。
- 測定可能なパフォーマンスと可用性。
- トランザクションがある場合の冪等性/重複処理をクリアします。
- 契約にはバージョンまたは変更ポリシーがあります。
7. よくあるエラー
エラー 1: データではなく画面のみを書き込みます
UIはほんの一部です。データがどこから来てどこへ行くのかが不明確であれば、レポート、通知、監査、統合は間違ったものになります。
エラー 2: エラーの説明がありません
幸せな道は通常は簡単です。新たなエラーは、ユーザー エクスペリエンスとサポート コストが急増する点にあります。
エラー 3: 冪等性を求めていない
注文の作成、支払い、スケジュール設定、およびトランザクションの再試行では、重複が発生する可能性があります。 BA は、ビジネス ルールと UX が欠落しないように、早めに質問する必要があります。
より完全な API コントラクトの例
エンドポイント:
PATCH /appointments/{appointment_id}/reschedule
ビジネスルール:
- ユーザーは、サポート権限を持つ所有者またはカスタマー サービスである必要があります。
- 予定は確認済み状態である必要があります。 ・販売開始時間は4時間以上となります。
- 新しいスロットが利用可能である必要があります。 ・ リクエストリトライは複数回作成できません。
リクエスト:
{
"new_slot_id": "SLOT-20260507-1000",
"reason": "Customer requested a later time",
"idempotency_key": "a9c6d2f0-7e2b-4b15-a4b9-118e6f21c001"
}
応答成功:
{
"appointment_id": "APT-20260506-001",
"old_slot_id": "SLOT-20260507-0900",
"new_slot_id": "SLOT-20260507-1000",
"status": "Confirmed",
"updated_at": "2026-05-06T10:30:00Z"
}
検証とエラー:
| コード | HTTP | 原因 | ユーザーメッセージ | 再試行 |
|---|---|---|---|---|
| 所有者ではありません | 403 | ユーザーは販売を所有していません | このスケジュールを変更する権利はありません。 | いいえ |
| 無効なステータス | 409 | 予約は確認されていません | この予定は変更できません。 | いいえ |
| カットオフ_期限切れ | 409 | 残り 4 時間未満 | スケジュールは近日公開予定です。ホットラインにお電話ください。 | いいえ |
| スロット_使用不可 | 409 | 新しいスロットが配置されました | このスロットは配置されたばかりです。別の時間を選択してください。 | はい、別のスロットを選択してください |
| 重複リクエスト | 200 | 同じ冪等性キー | 最初のリクエストの結果を返します。 | 安全 |
監査ログ:
| フィールド | 意味 |
|---|---|
| 俳優ID | 誰がスケジュールを変更したのか |
| 俳優の役割 | 顧客/顧客サービス/管理者 |
| 予定ID | スケジュール変更 |
| 古いスロット ID/新しいスロット ID | 前後 |
| 理由 | 変更理由 |
| タイムスタンプ | 時間 |
これは、開発者が実装するには十分な詳細であり、QA はコントラクト/ネガティブ テストを作成し、ビジネスはシステムが各ケースを拒否する理由を理解するのに十分です。
参照元
- IEEE/ISO/IEC 29148-2018: https://standards.ieee.org/ieee/29148/6937/
- OWASP ASVS: https://owasp.org/www-project-application-security-verification-standard/
- IIBA BABOK ガイド: https://www.iiba.org/standards-and-resources/babok/
結論
API/データ リテラシーは、ソフトウェア BA が統合段階で盲目的にならないようにするのに役立ちます。コードを記述する必要はありませんが、契約、検証、エラー、セキュリティ、監査、データの所有権について適切な質問をする方法を知る必要があります。これは、スライドの要件を作成する BA と実際のソフトウェアの要件を作成する BA を区別する機能です。