共通ガイドライン

本ガイドラインの目的

本ドキュメントは、REST/gRPC/GraphQL/メッセージング等、プロジェクトで扱う各種API設計に共通する基本方針・記述ルール・推奨例をまとめたものです。 各API仕様書テンプレートの該当セクションは本ガイドラインに準拠してください。

1. 認証・認可

• 方式例: OAuth2, JWT, API Key, mTLS, Cookie認証 など
• 記述例:
  • どの方式を採用するか、トークンの発行・検証フロー、スコープ設計、認可エラー時のレスポンス例
  • gRPCの場合はmetadata、GraphQLの場合はHTTPヘッダやcontextでの伝搬方法も明記

2. エラー設計

• 共通方針:
  • エラーは一貫した構造・コード体系で返す
  • REST: HTTPステータス＋エラーボディ（code, message, details等）
  • gRPC: status code＋details、GraphQL: errors配列
• 記述例:
  • エラーコード表、共通エラーレスポンス例
  • 例外的なエラー（バリデーション、認可、システム障害等）の扱い

3. バージョニング

• 方針:
  • URLパスによるバージョニングを採用する。APIのバージョンはURLパスに含める（例: /v1/users）。
  • 破壊的変更（既存のAPI利用者への影響がある変更）を伴う場合は、メジャーバージョンを上げる（例: /v1 から /v2）。
  • 後方互換性のある変更（例: 新しいフィールドの追加、新しいエンドポイントの追加）の場合は、既存のバージョン内で対応する。
  • メッセージスキーマの変更も、破壊的変更の場合はバージョンアップの対象とする。
• バージョンアップ手順・互換性維持方針:
  • 新しいバージョンのAPIをリリースする際は、一定期間、旧バージョンとの並行稼働を保証する。
  • 旧バージョンのAPIの廃止（Deprecation）ポリシーを明確にし、事前に利用者へ通知する。

4. 共通レスポンス構造

• 成功時:
  • 必須フィールド（data, meta, status等）を統一
  • ページング・メタ情報の表現方法
• 失敗時:
  • エラー構造（上記参照）

5. ロギング・監査・トレーシング

• 推奨:
  • 重要操作・エラー時のログ出力方針
  • 監査証跡の記録（ユーザーID、操作内容、タイムスタンプ等）
  • 分散トレーシング:
    • リクエストの開始から終了まで、複数のサービスを横断して処理を追跡できるよう、トレースID（trace-id）とスパンID（span-id）を伝搬させる。
    • HTTPヘッダには、OpenTelemetryやW3C Trace Contextに準拠した形式（例: traceparent, tracestate）を使用する。
    • gRPCの場合は、metadataを通じて伝搬させる。

6. セキュリティ

6.1. 入力バリデーション

• 全てのAPI入力（パスパラメータ、クエリパラメータ、リクエストボディ）に対して、型、必須/任意、値の範囲、正規表現、最大長などの厳格なバリデーションをサーバーサイドで実施する。
• クライアントサイドでのバリデーションはUX向上のためであり、セキュリティ対策としてはサーバーサイドバリデーションを必須とする。

6.2. レートリミット

• APIごとに、一定時間あたりのリクエスト数に制限を設ける。
• 制限を超過した場合は、適切なHTTPステータスコード（例: 429 Too Many Requests）を返す。
• 認証エンドポイントやパスワードリセットエンドポイントなど、ブルートフォース攻撃の対象となりやすいAPIには、より厳格なレートリミットを適用する。

6.3. CORS (Cross-Origin Resource Sharing)

• 許可するオリジン、HTTPメソッド、ヘッダを明確に設定し、最小限のアクセスを許可する。
• ワイルドカード（*）の使用は、開発環境など限定的な場合を除き、本番環境では避ける。

6.4. CSRF (Cross-Site Request Forgery) 対策

• 状態を変更するAPI（POST, PUT, DELETEなど）には、認証方式に応じたCSRF対策を適用する。特にCookie認証の場合は、CSRFトークン（Synchronizer Token Pattern）やSameSite Cookie属性（Lax/Strict）が重要となる。
• Refererヘッダの検証も補助的に行う。

6.5. XSS (Cross-Site Scripting) 対策

• APIからのレスポンスに含まれるユーザー入力由来のデータは、クライアントサイドで表示する際に適切にエスケープ処理を行う。
• Content-Security-Policy (CSP) ヘッダを適切に設定し、インラインスクリプトの実行や不正なリソースの読み込みを制限する。

6.6. SQLインジェクション対策

• データベースへのアクセスには、必ずプリペアドステートメント（パラメータ化クエリ）を使用し、SQL文とユーザー入力を分離する。
• ORM (Object-Relational Mapping) を使用する場合も、SQLインジェクション対策が適切に行われていることを確認する。

6.7. セキュリティヘッダ

• HSTS (Strict-Transport-Security), X-Content-Type-Options, X-Frame-OptionsなどのHTTPセキュリティヘッダを適切に設定する。

6.8. 機密データの保護

• パスワードやAPIキーなどの機密データは、平文で保存せず、強力なハッシュ関数（例: bcrypt, Argon2）を用いてハッシュ化して保存する。
• データベースやファイルシステムに保存される機密データは、暗号化を検討する。
• ログに機密情報が出力されないように注意する。

7. ドキュメント・スキーマ管理

• OpenAPI/Swagger, Protobuf, GraphQL SDL等の利用推奨
• 自動生成・バージョン管理の運用ルール

8. その他

• 用語・命名規則: 一貫した命名（キャメル/スネーク等）
• タイムゾーン・日付形式: 全てのAPIにおいて、日付と時刻はISO 8601形式（例: YYYY-MM-DDTHH:mm:ssZ）で表現し、タイムゾーンはUTCに統一する。
• 国際化・多言語対応: 必要に応じて、Accept-Languageヘッダの解釈や、ロケールに合わせたメッセージ返却の方針などを定義します。