API Documentation

API ドキュメント作成スキル

目的

システム間（例：フロントエンドからバックエンド、またはサービス間）の円滑な通信を実現するため、連携要件を定義し、API 仕様を文書化します。

使用する場面

• 新しい API エンドポイントを設計するとき（例：バックエンド向け FRS）。
• サードパーティーサービスと連携するとき（例：Stripe、SendGrid）。
• パートナー向けの公開 API を文書化するとき。
• 開発者向けにペイロード構造を定義するとき。

BA 向けの主な API 概念

1. プロトコル

• REST（Representational State Transfer）：最も一般的です。リソースベースです。
• SOAP：比較的古く、XML ベースです。大規模なエンタープライズシステムで広く使われています。
• GraphQL：柔軟なクエリベースです。クライアントは必要なデータだけを指定して取得します。

2. HTTP メソッド（動詞）

• GET：データを取得します（読み取り）。
• POST：新しいデータを作成します（作成）。
• PUT：データ全体を更新／置換します（更新）。
• PATCH：データの一部を更新します（更新）。
• DELETE：データを削除します（削除）。

3. ステータスコード

• 200 OK：成功。
• 201 Created：成功（新しいリソースが作成されました）。
• 400 Bad Request：クライアントエラー（入力が無効です）。
• 401 Unauthorized：認証がない、または失敗しています。
• 403 Forbidden：認証済みですが、権限がありません。
• 404 Not Found：リソースが存在しません。
• 500 Internal Server Error：バックエンドでエラーが発生しました。

ドキュメントの構成（Swagger/OpenAPI 形式）

エンドポイントごとの必須セクション

1. タイトルとメソッド：GET /api/v1/users/{userId}
2. 概要：エンドポイントの機能を一行で説明します。
3. パラメーター：
   • パスパラメーター：URL 内の必須 ID（例：{userId}）。
   • クエリパラメーター：フィルター／並べ替えの制限（例：?limit=10&role=admin）。
   • ボディ：JSON ペイロード（POST／PUT 用）。
   • ヘッダー：認証トークン、Content-Type。
4. レスポンス例：
   • 成功時（200）の JSON ボディ。
   • エラー時（4xx／5xx）の JSON ボディ。
5. ビジネスルール：制約、ロジック、副作用。

API 仕様テンプレート（簡易版）

エンドポイント：新規注文の作成

メソッド：POST URL：/api/v1/orders 説明：新しい顧客注文を作成し、在庫を確保します。

リクエストヘッダー：

• Authorization：Bearer <token>
• Content-Type：application/json

リクエストボディ（JSON）：

{
  "customerId": "uuid-string",
  "items": [
    {
      "productId": "uuid-string",
      "quantity": 2
    }
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Startown"
  }
}

制約：

• quantity は 0 より大きい値である必要があります。
• customerId は有効な状態である必要があります。
• 1 件の注文につき最大 20 個の商品を指定できます。

成功レスポンス（201 Created）：

{
  "orderId": "ord-12345",
  "status": "PENDING",
  "totalAmount": 150.00,
  "createdAt": "2026-01-21T10:00:00Z"
}

エラーレスポンス：

• 400 Bad Request：「数量が無効です」または「商品が在庫切れです」。
• 401 Unauthorized：トークンの有効期限が切れています。

連携のマッピング（データマッピング）

システム A とシステム B を接続する際は、マッピングテーブルを作成します。

送信元フィールド（システム A）	型	変換	送信先フィールド（システム B）	型	備考
first_name	文字列	結合	FullName	文字列	A.first + " " + A.last
last_name	文字列	（上記）	-	-
dob	日付	YYYY-MM-DD 形式	BirthDate	文字列	B では文字列形式が必要です
status	列挙型	'Active' を 1 にマッピング	IsActive	ブール値	ロジックによるマッピング

ツール

• Swagger / OpenAPI：開発者向けドキュメントの標準です。
• Postman：API 呼び出しのテストに使います。
• Stoplight：ビジュアル API 設計に使います。
• Lark Docs / Markdown：BRD／FRS の仕様書作成に使います。

ベストプラクティス

• 一貫性を保つ：日付には ISO 8601（YYYY-MM-DDThh:mm:ssZ）を使用します。
• 認証：認証方式（API Key または OAuth）を明確に記載します。
• ページネーション：1,000,000 件のレコードを返さないようにします。デフォルトの上限（limit=20）を指定します。
• エラーメッセージ：人が理解しやすい明確なエラーメッセージを定義します。

参考資料

• RESTful API 設計ガイド。
• OpenAPI 仕様（OAS）。