快速开始

本文介绍 Ruby China API 的基础知识，以及用户认证的方式。

访问域名

OAuth 2 / API 认证

在使用 API 之前，你需要 注册应用 并获得可以 OAuth App 信息。并使用标准的 OAuth 2 实现登录，获得 access_token 信息。

OAuth 路径

  • /oauth/authorize
  • /oauth/token
  • /oauth/revoke

Response 说明

所有 Response 采用 JSON 格式返回，请求状态通过 HTTP Status 返回。

HTTP Status

错误的情况 Response Body 一定会是这样的格式: { "error" : "Error message" }

  • 200, 201 - 请求成功，或执行成功。
  • 400 - 参数不符合 API 的要求、或者数据格式验证没有通过，请配合 Response Body 里面的 error 信息确定问题。
  • 401 - 用户认证失败，或缺少认证信息，比如 access_token 过期，或没传，可以尝试用 refresh_token 方式获得新的 access_token。
  • 403 - 当前用户对资源没有操作权限。
  • 404 - 资源不存在。
  • 500 - 服务器异常。

资源权限描述

在部分 API 的 response 内容里面你会看到 abilities 节点，这是特别标识当前 access_token 对应的用户对此资源的权限。

请参考源代码，确定那些路径是需要用户认证的，需要用户认证的路径，你需要带上 access_token=? 参数。

例如：

{
  "topic": {
    "id": 256170,
    ....,
    "abilities": { "update": true, "destroy": true }
  }
}
  • update 是否有权限修改
  • destroy 是否有权限删除

演示

我们用 Ruby 演示一下访问 /api/v3/hello.json 这个路径，其中包含 OAuth 2 的流程。

*这里用到 RubyGem *oauth2

require "oauth2"client = OAuth2::Client.new('client id', 'secret', site: 'https://ruby-china.org')
access_token = client.password.get_token('username', 'password')
res = Faraday.get("https://ruby-china.org/api/v3/hello.json?access_token=#{access_token.token}")
puts res.statusputs res.body

最后输出

{ 'current_user' : 'username' }

基础 - Root

简单的 API 测试接口

简单的 API 测试接口，需要验证，便于快速测试 OAuth 以及其他 API 的基本格式是否正确

GET /api/v3/hello

Response

UserDetailSerializer

基础 - Root

简单的 API 测试接口

简单的 API 测试接口，需要验证，便于快速测试 OAuth 以及其他 API 的基本格式是否正确

GET /api/v3/hello

Response

UserDetailSerializer

账号 - Users

获取热门用户

GET /api/v3/users

Parameters

  • limit (Integer)  - default: 20, range: 1..100

Response

Array<UserSerializer>

获取某个用户的详细信息

获取 :id 用户的详细信息

GET /api/v3/users/:id

Response

UserDetailSerializer

获取当前用户的完整信息

用于个人设置修改资料

GET /api/v3/users/me

Response

UserDetailSerializer

用户回帖列表

获取某个用户的回帖列表

GET /api/v3/users/:id/replies

用户的话题列表

获取某个用户发布的话题列表

GET /api/v3/users/:id/topics

Parameters

  • order (String) - 排序方式，default: 'recent', range: %w(recent likes replies)
  • offset (Integer) - default: 0
  • limit (Integer) - default: 20, range: 1..150

Response

Array<TopicSerializer>

屏蔽用户

当前用户屏蔽 :id 的用户

POST /api/v3/users/:id/block

取消屏蔽用户

当前用户取消屏蔽 :id 的用户

POST /api/v3/users/:id/unblock

获取当前用户的屏蔽列表

获取当前用户的已屏蔽的人（只能获取自己的）

GET /api/v3/users/:id/blocked

Parameters

  • offset (Integer) - default: 0
  • limit (Integer) - default: 20, range: 1..150

Response

Array<UserSerializer>

关注用户

当前用户关注 :id 的用户

POST /api/v3/users/:id/follow

取消关注

当前用户取消对 :id 用户的关注

POST /api/v3/users/:id/unfollow

获取用户的关注列表

获取 :id 的用户的关注列表

GET /api/v3/users/:id/following

Parameters:

  • offset (Integer) - default: 0
  • limit (Integer) - default: 20, range: 1..150

Response

Array<UserSerializer>

获取用户的关注者列表

获取关注 :id 用户的人的列表

GET /api/v3/users/:id/followers

Parameters:

  • offset (Integer) - default: 0
  • limit (Integer) - default: 20, range: 1..150

Response

Array<UserSerializer>

获取某个用户的收藏列表

获取 :id 用户收藏的话题列表

GET /api/v3/users/:id/favorites

Parameters:

  • offset (Integer) - default: 0
  • limit (Integer) - default: 20, range: 1..150

Response

Array<TopicSerializer>

节点 - Nodes

获取节点列表

GET /api/v3/nodes

Response

Array<NodeSerializer>

节点详情

获取单个 Node 详情

GET /api/v3/nodes/:id

Response

NodeSerializer

话题 - Topics

获取话题列表

获取话题列表，类似 Ruby China 话题列表的内容，支持多种排序方式。

GET /api/v3/topics

Parameters:

  • type (String) - 排序类型，default: last_actived
    • 可选值：last_actived, recent, no_reply, popular, excellent
  • node_id (Integer) - 节点编号，如果有给，就会只去节点下的话题
  • offset (Integer) - default: 0
  • limit (Integer) - default: 20, range: 1..150

Response

Array<TopicSerializer>

话题详情

获取话题详情（不含回帖）

GET /api/v3/topics/:id

Response

TopicDetailSerializer

创建新话题

创建一篇新的话题

POST /api/v3/topics

Parameters:

  • title (String) — 标题，[required]
  • node_id (Integer) — 节点编号，[required]
  • body (Markdown) — 格式的正文，[required]

Response

TopicDetailSerializer

修改话题

修改话题内容

PUT /api/v3/topics/:id

Parameters

  • title (String) — 标题，[required]
  • node_id (Integer) — 节点编号，[required]
  • body (Markdown) — 格式的正文，[required]

Response

TopicDetailSerializer

删除话题

删除一篇话题

DELETE /api/v3/topics/:id

创建回帖

创建对 :id 话题的回帖

POST /api/v3/topics/:id/replies

Parameters

  • body (String) - 回帖正文

Response

ReplySerializer

话题的回帖列表

获取话题的回帖列表

GET /api/v3/topics/:id/replies

Parameters

  • offset (Integer) - default: 0
  • limit (Integer) - default: 20, range: 1..150

Response

Array<ReplySerializer>

关注话题

POST /api/v3/topics/:id/follow

取消关注话题

POST /api/v3/topics/:id/unfollow

收藏话题

POST /api/v3/topics/:id/favorite

取消收藏话题

POST /api/v3/topics/:id/unfavorite

话题动作接口

对 :id 这篇话题发起动作（屏蔽、加精华、结束讨论...）注意类型有不同的权限，详见 GET /api/v3/topics/:id 返回的 abilities

POST /api/v3/topics/:id/action?type=:type

Parameters:

  • type (String) — 动作类型，ban - 屏蔽话题，excellent - 加精华，unexcellent - 去掉精华，close - 关闭回复，open - 开启回复

回帖 - Replies

获取回帖的详细内容

获取回帖的详细内容（一般用于编辑回帖的时候）

GET /api/v3/replies/:id

Response

ReplyDetailSerializer

修改回帖

POST /api/v3/replies/:id

Parameters

  • body (String) - 回帖内容 [required]

Response

ReplyDetailSerializer - 更新过后的数据

删除回帖

DELETE /api/v3/replies/:id

图片附件 - Photos

上传附件

上传图片，请使用 Multipart 的方式提交图片文件。

POST /api/v3/photos

Parameters

  • file - 文件信息，[required]

Response

{
  image_url: '图片 URL',
}

点赞 - Likes

点赞可以针对 话题（topic）或回帖（reply) 发起。

点赞

对话题/回帖点赞

POST /api/v3/likes

Parameters

  • obj_type (String) — 类型 [topic, reply]
  • obj_id (Integer) — 对应数据的编号

Response

  • count [Integer] 已赞的数量

取消赞

取消之前的赞

DELETE /api/v3/likes

Parameters

  • obj_type (String) — 类型 [topic, reply]
  • obj_id (Integer) — 对应数据的编号

通知 - Notifications

获取用户的通知列表

GET /api/v3/notifications

Parameters

  • offset (Integer) - default: 0
  • limit (Integer) - default: 20, range: 1..150

Response

Array<NotificationSerializer>

批量将通知设成已读状态

将当前用户的一些通知设成已读状态

POST /api/v3/notifications/read

Parameters

  • ids (Array) - 需要设为已读的通知编号列表（只能是当前用户的） [required]

获取未读通知数量

获得未读通知数量

GET /api/v3/notifications/unread_count

删除某个通知

删除当前用户的某个通知

DELETE /api/v3/notifications/:id

清空通知

删除当前用户的所有通知

DELETE /api/v3/notifications/all

UserSerializer

用户 API 返回数据结构

attributes

  • id [Integer] 用户编号
  • login [String] 用户名
  • name [String] 用户姓名
  • avatar_url [String] 头像 URL

UserSerializer

用户 API 返回数据结构

attributes

  • id [Integer] 用户编号
  • login [String] 用户名
  • name [String] 用户姓名
  • avatar_url [String] 头像 URL

UserDetailSerializer

用户详细信息 API 返回数据结构

attributes

  • id [Integer] 用户编号
  • login [String] 用户名
  • name [String] 用户姓名
  • avatar_url [String] 头像 URL
  • location [String] 城市
  • company [String] 公司名称
  • github [String] GitHub ID
  • twitter [String] Twitter ID
  • website [String] 个人主页 URL
  • bio [String] 个人介绍
  • tagline [String] 一段话的简单个人介绍
  • email [String] Email 地址
  • topics_count [Integer] 用户创建的话题数量
  • replies_count [Integer] 用户创建的回帖数量
  • following_count [Integer] 关注了多少人
  • followers_count [Integer] 有多少个关注者
  • favorites_count [Integer] 收藏的话题数量
  • level [String] 用户级别
  • level_name [String] 用户级别 (用于显示)
  • created_at [DateTime] 注册时间 ISO 8601 格式

TopicSerializer

话题信息，一般在列表返回的时候出现。

attributes

  • id [Integer] 话题编号
  • title [String] 标题
  • node_name [String] 节点名称
  • node_id [Integer] 节点 ID
  • excellent [Boolean] 是否精华
  • deleted [Boolean] 是否已删除
  • replies_count [Integer] 回帖数量
  • likes_count [Integer] 赞数量
  • last_reply_user_id [Integer] 最后回复人用户编号
  • last_reply_user_login [String] 最后回复者 login
  • user UserSerializer 最后回复者用户对象
  • replied_at [DateTime] 最后回帖时间
  • created_at [DateTime] 创建时间
  • updated_at [DateTime] 更新时间

TopicDetailSerializer

完整话题详情 话题信息

attributes

  • id [Integer] 话题编号
  • title [String] 标题
  • node_name [String] 节点名称
  • node_id [Integer] 节点 ID
  • excellent [Boolean] 是否精华
  • deleted [Boolean] 是否已删除
  • replies_count [Integer] 回帖数量
  • likes_count [Integer] 赞数量
  • last_reply_user_id [Integer] 最后回复人用户编号
  • last_reply_user_login [String] 最后回复者 login
  • user UserSerializer 最后回复者用户对象
  • closed_at [DateTime] 结帖时间，null 表示正常帖子
  • replied_at [DateTime] 最后回帖时间
  • created_at [DateTime] 创建时间
  • updated_at [DateTime] 更新时间
  • body [String] 话题正文，原始 Markdown
  • body_html [String] 以转换成 HTML 的正文
  • hits [Integer] 阅读次数

ReplySerializer

回帖信息

attributes

  • id [Integer] 编号
  • body_html [String] 以转换成 HTML 的正文
  • topic_id [Integer] 话题编号
  • deleted [Boolean] 是否已删除
  • likes_count [Integer] 赞数量
  • user UserSerializer 最后回复者用户对象
  • created_at [DateTime] 创建时间
  • updated_at [DateTime] 更新时间

ReplyDetailSerializer

包含原始正文 Markdown 信息的回帖

attributes

  • id [Integer] 编号
  • body_html [String] 以转换成 HTML 的正文
  • topic_id [Integer] 话题编号
  • deleted [Boolean] 是否已删除
  • likes_count [Integer] 赞数量
  • user UserSerializer 最后回复者用户对象
  • created_at [DateTime] 创建时间
  • updated_at [DateTime] 更新时间
  • topic_title [String] 话题标题
  • body [String] 回帖正文，原始 Markdown

NodeSerializer

节点详情

attributes

  • id [Integer] 编号
  • name [String] 节点名称
  • summary [String] 简介，Markdown 格式
  • section_id [Integer] 大类别编号
  • section_name [String] 大类别名称
  • topics_count [Integer] 话题数量
  • sort Integer 排序优先级
  • updated_at [DateTime] 更新时间

NotificationSerializer

通知数据

attributes

  • id [Integer] 编号
  • type [String] 通知类型
  • read [Boolean] 是否已读
  • actor UserSerializer 动作发起者
  • mention_type [String] 提及的数据类型 Topic, Reply
  • created_at [DateTime] 创建时间
  • updated_at [DateTime] 更新时间