API一覧

Mon, 01 Jan 0001 00:00:00 +0000

API一覧#

ID	メソッド	パス	概要
api001	POST	`/images/presigned-url`	S3アップロード用の署名付きURLを発行する
api002	POST	`/images`	画像メタデータを登録する
api003	GET	`/images`	アップロード済み画像の名前リスト取得
api004	GET	`/images/:id`	画像の閲覧用URL（Presigned）取得

API共通仕様

Mon, 01 Jan 0001 00:00:00 +0000

API共通仕様#

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

ベースURL#

/api/v1

共通ヘッダー#

リクエスト#

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

レスポンス#

ヘッダー名	説明
Content-Type	`application/json`

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

{
 "error": {
 "code": "string",
 "message": "string"
 }
}

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

共通ステータスコード#

コード	メッセージID	説明
429	MSG-API-C001	レート制限超過
500	MSG-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キー管理（将来的な外部連携向け）

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

認証チェックのオーバーヘッド測定
キャッシュ戦略との整合性
負荷テストでの性能検証

APIメッセージ一覧表

Mon, 01 Jan 0001 00:00:00 +0000

APIメッセージ一覧表#

APIレスポンスに含まれるエラーメッセージを管理する。{変数名} は動的に置換される。

共通メッセージ#

全APIで共通して使用するメッセージ。

メッセージID	ステータスコード	code	メッセージテンプレート	変数
MSG-API-C001	429	`RATE_LIMIT_EXCEEDED`	リクエスト数が上限（{limit}回/{window}）を超えました	`limit`: 上限回数（例: 10）、`window`: 時間窓（例: 1分）
MSG-API-C002	500	`INTERNAL_SERVER_ERROR`	サーバーエラーが発生しました	—

個別メッセージ#

メッセージID	ステータスコード	code	メッセージテンプレート	変数	発生条件
MSG-API-001	400	`INVALID_FILE_SIZE`	ファイルサイズが上限（{maxSize}）を超えています	`maxSize`: 上限サイズ（例: 5MB）	fileSize > 5,242,880 bytes
MSG-API-002	400	`INVALID_CONTENT_TYPE`	対応していないファイル形式です（許可形式: {allowedTypes}）	`allowedTypes`: 許可MIMEタイプ一覧（例: jpeg, png, gif, webp）	contentType が許可リスト外
MSG-API-003	409	`UPLOAD_LIMIT_EXCEEDED`	アップロード可能な枚数の上限（{maxCount}枚）に達しています	`maxCount`: 上限枚数（例: 5）	アップロード済み枚数 >= 上限
MSG-API-004	422	`INVALID_FILE_BINARY`	ファイルのバイナリ検証に失敗しました	—	マジックナンバー不一致
MSG-API-005	404	`FILE_NOT_FOUND_ON_S3`	S3上にファイルが存在しません	—	HeadObject で対象キーが見つからない
MSG-API-006	404	`IMAGE_NOT_FOUND`	指定された画像が存在しません（id: {id}）	`id`: リクエストされた画像ID	DBに対象IDが存在しない

API on 設計書

API一覧

API一覧#

API共通仕様

API共通仕様#

ベースURL#

共通ヘッダー#

リクエスト#

レスポンス#

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

共通ステータスコード#

レート制限#

トレーサビリティ#

ID の役割#

実装方針#

懸案事項#

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

Hono Middlewareへの影響#

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

TBD#

認証方式の技術選定#

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

認可モデルの設計#

セキュリティ強化項目#

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

APIメッセージ一覧表

APIメッセージ一覧表#

共通メッセージ#

個別メッセージ#