openpodcast/api

OpenPodcast API

镜像概述与主要用途

OpenPodcast API是Open Podcast系统的轻量级API层，核心功能是接收并存储POST请求的payload到主存储系统。作为Open Podcast生态的关键组件，它提供数据接收、听众反馈处理和系统状态查询等基础功能，支持Podcast平台的数据管理与交互需求。

核心功能与特性

数据接收与存储

• 支持按指定Connector格式接收结构化数据，包含provider、version、时间戳、元数据及原始数据等核心字段
• 实现数据持久化存储至数据库，确保数据完整性

听众反馈API

• 提供点赞/点踩功能端点：/feedback/:episodeID/upvote 和 /feedback/:episodeID/downvote
• 基于IP地址和User-Agent组合确保每个剧集的唯一投票记录

系统状态API

• 通过/status端点返回各数据端点的最后导入时间
• 响应包含账户ID及latestUpdates字段，展示各端点（如aggregate、detailedStreams）的最新更新时间

使用场景与适用范围

• Podcast数据收集：接收来自Spotify等平台的节目数据
• 用户互动分析：收集听众对剧集的反馈数据
• 系统监控：查询各数据端点的同步状态
• 开发与测试：提供完整的本地开发与测试工具链

使用方法与配置说明

开发环境设置

1. 初始化项目

   bash
   make install-init
   

2. 配置环境变量

   • 基于env.example创建.env文件
   • 配置数据库访问凭据等必要参数

3. 启动开发服务器

   bash
   make dev
   

4. 发送测试请求

   bash
   make send-api-req-local  # 向本地服务器发送测试请求并存储结果至数据库
   

Connector数据格式规范

javascript
{
    "provider": "spotify",  // 数据提供方，如spotify
    "version": 1,           // 数据格式版本
    "retrieved": "<timestamp ISO 8601>",  // 数据获取时间，如2022-07-21T09:35:31.820Z
    "meta": {
        "show": "<spotify_show_id>",      // 节目ID
        "episode": null || "<episode_id>", // 剧集ID，可为null
        "endpoint": "<endpoint_name>",    // 端点名称，如aggregate
    },
    "range": {
        "start": "<date>",  // 数据时间范围开始，如2022-01-01
        "end": "<date>"     // 数据时间范围结束
    },
    "data": <raw_json>      // 原始数据JSON
}

API端点使用

Feedback API

• 端点：/feedback/:episodeID/[upvote|downvote]
• 示例：/feedback/123456/upvote（为ID为***的剧集点赞）
• 功能：记录听众对特定剧集的投票，每个IP和User-Agent组合对同一剧集仅能投票一次

Status API

• 端点：/status
• 响应示例：

  json
  {
      "account_id": 1,
      "latestUpdates": [
          "aggregate": "2021-01-01 00:00:00",
          "detailedStreams": "2021-01-01 00:00:00"
      ]
  }
  

Docker部署

完整的Docker Compose配置可参考 https://github.com/openpodcast/stack 项目，包含API服务与数据库的完整部署方案。

开发与测试

测试命令

• 运行单元测试

  bash
  make test
  

• 运行端到端测试（含环境搭建）

  bash
  make e2e-tests
  

• 运行特定测试（需先启动开发服务器和数据库）

  bash
  make test-one-e2e-"test name here"
  

  示例：

  bash
  make test-one-e2e-"should return not be authenticated with random token"
  

数据库管理

• 启动数据库并初始化认证表

  bash
  make up-db
  

• 通过开发服务器创建数据表（自动执行迁移）

  bash
  make dev
  

• 初始化认证数据结构

  bash
  make init-auth-db
  

JSON Schema工具

• JSON to JSON Schema转换器
• JSON Schema生成器