Forem API V1 文章接口详解与使用指南

Forem 是一个开源社区平台，其 API 提供了丰富的功能来管理平台内容。本文将深入解析 Forem API V1 中与文章相关的接口，帮助开发者更好地理解和使用这些接口。

文章接口概述

Forem API V1 提供了完整的文章管理功能，主要包括：

1. 创建新文章
2. 获取文章列表
3. 按发布时间排序获取最新文章

这些接口允许开发者以编程方式与 Forem 平台交互，实现自动化内容管理和集成。

创建文章接口

接口说明

POST /api/articles 接口用于在 Forem 平台上发布新文章。文章可以是博客帖子、讨论问题、帮助线程等各种形式的内容。

请求参数

请求体需要包含一个 JSON 对象，遵循 Article 模式定义。主要字段包括：

• title: 文章标题（必填）
• body_markdown: 文章内容（Markdown 格式）
• published: 是否立即发布（布尔值）
• tags: 文章标签数组

响应示例

成功创建文章后，API 会返回 201 状态码和包含文章详细信息的 JSON 响应：

{
  "type_of": "article",
  "id": 2,
  "title": "New article",
  "description": "New post example",
  "readable_publish_date": "Dec 15",
  "slug": "new-article-2io1",
  "path": "/username2/new-article-2io1",
  "url": "http://forem.test/username2/new-article-2io1",
  "comments_count": 0,
  "public_reactions_count": 0,
  "collection_id": 1,
  "published_timestamp": "2023-12-15T00:15:27Z",
  "positive_reactions_count": 0,
  "cover_image": "https://thepracticaldev.s3.amazonaws.com/i/5wfo25724gzgk5e5j50g.jpg",
  "body_html": "<p><strong>New</strong> body for the article</p>",
  "body_markdown": "**New** body for the article",
  "user": {
    "name": "Carmen \"Andre\" \\:/ Rodriguez",
    "username": "username2"
  }
}

错误处理

• 401 Unauthorized: API 密钥无效或缺失
• 422 Unprocessable Entity: 请求参数缺失或无效

获取文章列表接口

接口说明

GET /api/articles 接口用于获取文章列表，默认返回按受欢迎程度降序排列的特色已发布文章。

查询参数

该接口支持多种过滤和排序选项：

1. 分页参数：

   • page: 页码
   • per_page: 每页文章数（30-1000）

2. 标签过滤：

   • tag: 按单个标签过滤
   • tags: 按多个标签过滤（逗号分隔）
   • tags_exclude: 排除指定标签的文章

3. 用户/组织过滤：

   • username: 按用户名过滤

4. 文章状态：

   • state: 可取值 fresh（新鲜文章）、rising（上升趋势文章）、all（所有文章）

5. 时间范围：

   • top: 获取最近 N 天内最受欢迎的文章

6. 集合：

   • collection_id: 按集合 ID 过滤

响应示例

[
  {
    "type_of": "article",
    "id": 5,
    "title": "Let Us Now Praise Famous Men4",
    "description": "Street yr raw denim master...",
    "tags": "discuss",
    "user": {
      "name": "Lanette \"Marine\" \\:/ Stanton",
      "username": "username6"
    },
    "organization": {
      "name": "Spinka and Sons",
      "username": "org4"
    }
  }
]

获取最新文章接口

接口说明

GET /api/articles/latest 接口专门用于获取按发布时间降序排列的文章列表，适合需要展示最新内容的场景。

查询参数

• page: 页码
• per_page: 每页文章数（30-1000）

特点

与通用文章列表接口相比，此接口：

1. 只按发布时间排序
2. 不支持复杂的过滤条件
3. 响应速度通常更快

最佳实践

1. 认证：大多数接口需要 api-key 请求头进行认证
2. 分页：处理大量数据时务必实现分页逻辑
3. 错误处理：妥善处理 401 和 422 错误
4. 日期格式：所有日期时间字段使用 RFC 3339 格式
5. 缓存：对频繁访问的数据考虑实现缓存机制

常见问题

Q: 如何获取特定用户的全部文章？ A: 使用 username 参数并结合 state=all 参数。

Q: 如何获取特定标签的热门文章？ A: 使用 tag 参数结合 top 参数指定时间范围。

Q: 创建文章时如何设置封面图片？ A: 在创建请求中包含 cover_image 字段，值为图片 URL。

通过合理利用这些 API 接口，开发者可以构建强大的 Forem 平台集成应用，实现自动化内容管理和展示。