API設計

共通仕様

項目	値
ベースパス	/api
フォーマット	JSON
API仕様	OpenAPI準拠

フィールド命名規則

レイヤー	命名規則	例
DBカラム	snake_case	created_at, pet_id, breed_id
APIリクエスト/レスポンス	camelCase	createdAt, petId, breedId

• APIの入出力は camelCase を使用する（JavaScript/TypeScript クライアントの慣習に従う）
• DB カラム名は snake_case を使用する（PostgreSQL の慣習に従う）
• シリアライゼーション層で snake_case ↔ camelCase の変換を行う

レスポンス形式

成功レスポンス

{
  "data": { ... }
}

エラーレスポンス（RFC 9457準拠）

{
  "type": "https://sounya.example/errors/rate-limited",
  "title": "Rate Limited",
  "status": 429,
  "detail": "認証コードの再送は60秒後に可能です"
}

フィールド	説明
type	エラー種別を識別するURI
title	エラーの短い説明
status	HTTPステータスコード
detail	エラーの詳細説明（人間向け）

レートリミット

• 同一IPからのリクエスト制限: 1分あたり100リクエスト

認証

• セッションCookie（__Host-session）による認証
• 認証が必要なエンドポイントでCookieが無効/期限切れの場合は 401 Unauthorized を返す

ページネーション

エンドポイントの特性に応じて2方式を使い分ける。

カーソルベース

リアルタイムに追加されるデータや、一貫性が重要なリスト（通知一覧など）に使用する。

パラメータ	説明
cursor	前回レスポンスの最後のリソースID
limit	取得件数（エンドポイントごとにデフォルト値・上限を定義）

レスポンスに nextCursor を含める。次ページがない場合は nextCursor: null。

オフセットベース

時系列データの範囲取得や、総件数の表示が必要なリスト（体重記録・食事記録など）に使用する。

パラメータ	説明
limit	取得件数（エンドポイントごとにデフォルト値・上限を定義）
offset	スキップする件数（0始まり）

レスポンスに pagination オブジェクトを含める。

{
  "data": [...],
  "pagination": {
    "total": 30,
    "limit": 50,
    "offset": 0
  }
}

使い分けの基準

方式	適用先	理由
カーソルベース	通知一覧	リアルタイム追加・既読管理のため一貫性が重要
オフセットベース	体重記録・食事記録・投薬記録等	日付範囲フィルタとの併用、総件数表示が必要