API共通仕様#

全APIエンドポイントに共通して適用される仕様を定義する。

ベースURL#

/api/v1

共通ヘッダー#

リクエスト#

ヘッダー名必須説明
X-Trace-ID✓トレーサビリティID（UUID v4）。フロントエンドで生成し全リクエストに付与する
X-Request-ID✓リクエスト識別ID（UUID v4）。フロントエンドで生成し、冪等性制御とキャンセルに使用する
Content-Type△リクエストボディがある場合は application/json

レスポンス#

ヘッダー名説明
Content-Typeapplication/json

共通エラーレスポンス形式#

{
  "error": {
    "code": "string",
    "message": "string"
  }
}
フィールド名説明例
codeエラーコードINVALID_FILE_SIZE
messageエラーメッセージファイルサイズが上限（5MB）を超えています

共通ステータスコード#

コードメッセージID説明
429MSG-API-C001レート制限超過
500MSG-API-C002サーバー内部エラー

レート制限#

同一IPアドレスから1分間に10リクエストを超えた場合、429 Too Many Requests を返す。

トレーサビリティ#

ID の役割#

  • X-Trace-ID: セッション全体の横断的トレーサビリティを確保するためのID
  • X-Request-ID: 単一操作の冪等性制御とキャンセルに使用するID

実装方針#

  • フロントエンドは UUID v4 の X-Trace-ID を生成し、全リクエストヘッダーに付与する。
  • フロントエンドは UUID v4 の X-Request-ID を生成し、各操作のリクエストヘッダーに付与する。
  • バックエンドは両方のIDをリクエストヘッダーから受け取り、全レイヤのログに引き継ぐ。
  • X-Request-ID は冪等性チェックに使用し、DBには保存しない（メモリ内で管理）。
  • ログは Pino で構造化（JSON）出力し、CloudWatch Logs に集約する。

懸案事項#

認証・認可方式の未確定#

  • 現状: API共通仕様に認証機構が定義されていない
  • 影響:
    • ユーザー識別が不可能で、アップロード枚数上限がグローバル制約となる
    • アクセス制御ができず、全ユーザーが全画像にアクセス可能
    • 監査証跡が不完全で、誰がどの操作を行ったか追跡不可
  • 対応方針:
    • JWTトークンまたはセッションベース認証の選定
    • Authorizationヘッダーの必須化
    • ユーザーIDの全リクエストへの引き継ぎ

Hono Middlewareへの影響#

  • 現状: 認証ミドルウェアが未実装
  • 影響:
    • 各APIエンドポイントで個別に認証チェックが必要
    • コード重複とメンテナンス性の低下
    • セキュリティポリシーの統一が困難
  • 対応方針:
    • 認証ミドルウェアの共通化
    • ユーザー情報のContextへの格納
    • 認可エラーハンドリングの統一

トレーサビリティと認証の連携#

  • 現状: trace_idのみでユーザー情報が紐づかない
  • 影響: ユーザー単位の障害調査や監査が困難
  • 対応方針:
    • trace_idとuser_idの両方をログに記録
    • ユーザー操作のエンドツーエンド追跡を可能にする

TBD#

認証方式の技術選定#

  • JWTトークン方式:
    • メリット: ステートレス、スケーラビリティ高、SPA親和性
    • デメリット: トークン失効・リフレッシュ処理の複雑化
  • セッション方式:
    • メリット: 実装シンプル、サーバー側制御容易
    • デメリット: ステートフル、スケーラビリティ制約
  • 選定基準: セキュリティ要件、運用要件、パフォーマンス要件を考慮

ミドルウェアアーキテクチャ設計#

  • 認証ミドルウェアの実装順序（レート制限→認証→認可）
  • エラーハンドリングの共通化
  • Context情報の型定義と引き継ぎ仕様

認可モデルの設計#

  • リソースベース認可: 画像所有者のみアクセス許可
  • ロールベース認可: 管理者権限の定義（将来拡張）
  • スコープ制御: 読み取り専用・書き込み専用アクセスの制御

セキュリティ強化項目#

  • トークン有効期限の最適設定
  • リフレッシュトークンの導入検討
  • CSRF対策の実装方針
  • APIキー管理（将来的な外部連携向け）

パフォーマンスへの影響評価#

  • 認証チェックのオーバーヘッド測定
  • キャッシュ戦略との整合性
  • 負荷テストでの性能検証
Backward API一覧 APIメッセージ一覧表 Forward