daren/apps/discovery

Discovery API 接口文档

简介

Discovery API是一个用于发现和搜索创作者的接口。它提供了创作者搜索、搜索会话管理等功能。所有API响应均遵循统一格式：

{
  "code": 200,  // 状态码，200表示成功
  "message": "操作成功",  // 操作提示消息
  "data": {  // 实际数据
    // 具体内容
  }
}

使用Apifox测试接口

1. 下载并安装Apifox: https://www.apifox.cn/
2. 创建新项目，命名为"Creator Discovery"
3. 导入API或手动创建以下接口

API 接口列表

1. 搜索创作者

• URL: http://localhost:8000/api/discovery/creators/search/
• 方法: POST
• 描述: 根据条件搜索创作者，并创建新的搜索会话
• 请求参数:

{
  "query": "创作者",
  "category": "Health",
  "ecommerce_level": "L5",
  "exposure_level": "KOL-2"
}

• 响应示例:

{
  "code": 200,
  "message": "搜索创作者成功",
  "data": {
    "id": 4,
    "creators": [
      {
        "id": 37,
        "name": "Mock Creator 5",
        "avatar": null,
        "category": "Health",
        "ecommerce_level": "L5",
        "exposure_level": "KOL-2",
        "followers": 162.2,
        "gmv": 534.1,
        "items_sold": 18.1,
        "avg_video_views": 1.9,
        "has_ecommerce": false,
        "tiktok_url": null,
        "session": 4
      }
    ],
    "session_number": 4,
    "creator_count": 1,
    "shoppable_creators": 0,
    "avg_followers": 162.2,
    "avg_gmv": 534.1,
    "avg_video_views": 1.9,
    "date_created": "2023-10-02"
  }
}

2. 获取搜索会话列表

• URL: http://localhost:8000/api/discovery/sessions/
• 方法: GET
• 描述: 获取所有搜索会话的历史记录
• 查询参数:
  • page: 页码，默认为1
  • page_size: 每页条数，默认为20，最大为100
• 响应示例:

{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "count": 3,
    "next": "http://localhost:8000/api/discovery/sessions/?page=2",
    "previous": null,
    "results": [
      {
        "id": 1,
        "session_number": 1,
        "creator_count": 42,
        "shoppable_creators": 24,
        "avg_followers": 162.2,
        "avg_gmv": 534.1,
        "avg_video_views": 1.9,
        "date_created": "2024-01-06"
      },
      {
        "id": 2,
        "session_number": 2,
        "creator_count": 53,
        "shoppable_creators": 13,
        "avg_followers": 162.2,
        "avg_gmv": 534.1,
        "avg_video_views": 1.9,
        "date_created": "2022-01-07"
      }
    ]
  }
}

3. 获取搜索会话详情

• URL: http://localhost:8000/api/discovery/sessions/{id}/
• 方法: GET
• 描述: 获取特定搜索会话的详细信息，包含该会话中的所有创作者
• 请求参数: 路径参数 id
• 响应示例:

{
  "code": 200,
  "message": "获取搜索会话详情成功",
  "data": {
    "id": 1,
    "creators": [
      {
        "id": 1,
        "name": "Creator 1 in Session 1",
        "avatar": null,
        "category": "Phones & Electronics",
        "ecommerce_level": "L2",
        "exposure_level": "KOC-1",
        "followers": 162.2,
        "gmv": 534.1,
        "items_sold": 18.1,
        "avg_video_views": 1.9,
        "has_ecommerce": true,
        "tiktok_url": null,
        "session": 1
      },
      {
        "id": 2,
        "name": "Creator 9 in Session 1",
        "avatar": null,
        "category": "Womenswear & Underwear",
        "ecommerce_level": "L3",
        "exposure_level": "KOL-3",
        "followers": 162.2,
        "gmv": 534.1,
        "items_sold": 18.1,
        "avg_video_views": 1.9,
        "has_ecommerce": false,
        "tiktok_url": null,
        "session": 1
      }
    ],
    "session_number": 1,
    "creator_count": 42,
    "shoppable_creators": 24,
    "avg_followers": 162.2,
    "avg_gmv": 534.1,
    "avg_video_views": 1.9,
    "date_created": "2024-01-06"
  }
}

4. 获取会话中的创作者

• URL: http://localhost:8000/api/discovery/sessions/{id}/results/
• 方法: GET
• 描述: 获取特定会话中的所有创作者
• 请求参数:
  • 路径参数 id
  • 查询参数 page、page_size（分页参数）
• 响应示例:

{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "count": 42,
    "next": "http://localhost:8000/api/discovery/sessions/1/results/?page=2",
    "previous": null,
    "results": [
      {
        "id": 1,
        "name": "Creator 1 in Session 1",
        "avatar": null,
        "category": "Phones & Electronics",
        "ecommerce_level": "L2",
        "exposure_level": "KOC-1",
        "followers": 162.2,
        "gmv": 534.1,
        "items_sold": 18.1,
        "avg_video_views": 1.9,
        "has_ecommerce": true,
        "tiktok_url": null,
        "session": 1
      },
      {
        "id": 2,
        "name": "Creator 9 in Session 1",
        "avatar": null,
        "category": "Womenswear & Underwear",
        "ecommerce_level": "L3",
        "exposure_level": "KOL-3",
        "followers": 162.2,
        "gmv": 534.1,
        "items_sold": 18.1,
        "avg_video_views": 1.9,
        "has_ecommerce": false,
        "tiktok_url": null,
        "session": 1
      }
    ]
  }
}

5. 获取所有创作者

• URL: http://localhost:8000/api/discovery/creators/
• 方法: GET
• 描述: 获取系统中的所有创作者
• 请求参数: 查询参数 page、page_size（分页参数）
• 响应示例:

{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "count": 150,
    "next": "http://localhost:8000/api/discovery/creators/?page=2",
    "previous": null,
    "results": [
      {
        "id": 1,
        "name": "Creator 1 in Session 1",
        "avatar": null,
        "category": "Phones & Electronics",
        "ecommerce_level": "L2",
        "exposure_level": "KOC-1",
        "followers": 162.2,
        "gmv": 534.1,
        "items_sold": 18.1,
        "avg_video_views": 1.9,
        "has_ecommerce": true,
        "tiktok_url": null,
        "session": 1
      },
      // 更多创作者...
    ]
  }
}

6. 获取创作者详情

• URL: http://localhost:8000/api/discovery/creators/{id}/
• 方法: GET
• 描述: 获取特定创作者的详细信息
• 请求参数: 路径参数 id
• 响应示例:

{
  "code": 200,
  "message": "获取创作者详情成功",
  "data": {
    "id": 1,
    "name": "Creator 1 in Session 1",
    "avatar": null,
    "category": "Phones & Electronics",
    "ecommerce_level": "L2",
    "exposure_level": "KOC-1",
    "followers": 162.2,
    "gmv": 534.1,
    "items_sold": 18.1,
    "avg_video_views": 1.9,
    "has_ecommerce": true,
    "tiktok_url": null,
    "session": 1
  }
}

在Apifox中设置环境变量

创建一个名为"本地开发环境"的环境，设置以下变量：

• baseUrl: http://localhost:8000/api

这样可以在所有请求中使用{{baseUrl}}/discovery/...来替代完整URL。

测试流程示例

1. 启动Django服务器：python manage.py runserver
2. 在Apifox中发送请求"获取搜索会话列表"
3. 在响应中选择一个会话ID
4. 使用该ID获取会话详情
5. 使用"搜索创作者"接口创建新的搜索会话
6. 验证新创建的会话是否出现在会话列表中

在Apifox中导入API

1. 在Apifox中，点击"导入"按钮
2. 选择"导入API"
3. 将本文档中的API信息整理成集合导入
4. 设置每个接口的请求和响应格式
5. 设置示例响应

注意事项

• 所有API响应均遵循统一的格式：code、message和data
• 分页接口返回格式为：{ "code": 200, "message": "获取数据成功", "data": { "count": 总数, "next": 下一页URL, "previous": 上一页URL, "results": [] } }
• 即使发生错误，HTTP状态码始终为200，错误信息在响应体的code和message中提供
• 接口不需要认证，可直接访问