レコメンドAPI仕様書

基本情報

API名: レコメンドAPI
バージョン: 1.0.0
説明: ユーザー属性に基づいてレコメンドタイトルを取得するAPI
開発チーム: dev@example.com

サーバー情報

環境	URL
本番環境	https://api.example.com/v1
開発環境	https://api-dev.example.com/v1

認証

認証方式: API Key認証
ヘッダー: X-API-Key

エンドポイント

POST/recommend

ユーザーの属性情報（年代、性別、配偶者有無、子供有無）を元に、おすすめのタイトルをランキング形式で3位まで取得します。

リクエスト

Content-Type: application/json

パラメータ

パラメータ名	型	必須	説明	例
age_group	string	✓	年代	"20代"
gender	string	✓	性別	"女"
spouse	boolean	✓	配偶者有無	true
has_children	boolean	✓	子供有無	false

age_group 許可値

10代
20代
30代
40代
50代
60代以上

gender 許可値

男
女

リクエスト例

{
  "age_group": "20代",
  "gender": "女",
  "spouse": true,
  "has_children": false
}

レスポンス

成功時 200

Content-Type: application/json

レスポンス構造

フィールド名	型	説明
status	string	処理ステータス
data	object	レコメンドデータ
data.rank1_title_code	string	1位タイトルコード
data.rank2_title_code	string	2位タイトルコード
data.rank3_title_code	string	3位タイトルコード
timestamp	string	レスポンス生成日時 (ISO 8601)

レスポンス例

{
  "status": "success",
  "data": {
    "rank1_title_code": "TITLE_001",
    "rank2_title_code": "TITLE_002",
    "rank3_title_code": "TITLE_003"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

エラー時 400, 500

Content-Type: application/json

エラーレスポンス構造

フィールド名	型	説明
status	string	処理ステータス ("error")
error_code	string	エラーコード
message	string	エラーメッセージ
timestamp	string	エラー発生日時 (ISO 8601)

バリデーションエラー例 400

{
  "status": "error",
  "error_code": "VALIDATION_ERROR",
  "message": "年代は必須パラメータです",
  "timestamp": "2024-01-15T10:30:00Z"
}

サーバーエラー例 500

{
  "status": "error",
  "error_code": "INTERNAL_SERVER_ERROR",
  "message": "レコメンド処理でエラーが発生しました",
  "timestamp": "2024-01-15T10:30:00Z"
}

ステータスコード

コード	説明
200	レコメンド取得成功
400	リクエストパラメータエラー
401	認証エラー
500	サーバー内部エラー

使用例

cURLでのテスト例

curl -X POST https://api.example.com/v1/recommend \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "age_group": "20代",
    "gender": "女",
    "spouse": true,
    "has_children": false
  }'

JavaScriptでの実装例

const fetchRecommendations = async (userProfile) => {
  try {
    const response = await fetch('https://api.example.com/v1/recommend', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY'
      },
      body: JSON.stringify(userProfile)
    });
    
    const data = await response.json();
    
    if (data.status === 'success') {
      console.log('1位:', data.data.rank1_title_code);
      console.log('2位:', data.data.rank2_title_code);
      console.log('3位:', data.data.rank3_title_code);
    } else {
      console.error('エラー:', data.message);
    }
  } catch (error) {
    console.error('通信エラー:', error);
  }
};

// 使用例
fetchRecommendations({
  age_group: "20代",
  gender: "女",
  spouse: true,
  has_children: false
});

注意事項

データ検証: 全てのリクエストパラメータは必須です
API制限: レート制限やクォータ制限がある場合があります
タイムアウト: リクエストタイムアウトは30秒です
エラーハンドリング: エラーレスポンスを適切に処理してください

作成日: 2024年
更新日: 2024年