Ruby China API 目录

OAuth 2 / API 认证

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

OAuth 路径
  • https://codingstyle.cn/oauth/authorize
  • https://codingstyle.cn/oauth/token
  • https://codingstyle.cn/oauth/revoke

Response 说明

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

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

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

资源权限描述

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

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

例如
{ 
  "topic": {
    "id": 256170,
    ....,
    "abilities": { "update": true, "destroy": true }
  }
}

  • update - 是否有权限修改
  • destroy - 是否有权限删除

API 路由

下面是简单的 API 路由列表, 具体请参考源代码 app/api

URL 基本路径:https://codingstyle.cn/api/v3

/hello.json

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

Returns:

{
    "user": {
        "id": 2,
        "login": "huacnlee",
        "name": "李华顺",
        "avatar_url": "http://ruby-china-files-dev.b0.upaiyun.com/user/large_avatar/2.jpg"
    },
    "meta": {
        "time": "2015-05-18T23:06:49.874+08:00"
    }
}

Params
参数名 类型 必填 默认值 值范围 说明
limit Integer false 0..100
/likes.json


这是一个多态的接口,支持赞 topicreply,你可以将赞的函数设计成和 API 一样

例如:

# 赞编号为 1234 的话题
Faraday.post("/api/v3/likes.json", { obj_type: "topic", obj_id: 1234 })
Params
参数名 类型 必填 默认值 值范围 说明
obj_type String true ["topic", "reply"]
obj_id Integer true
/likes.json

取消之前的赞

Params
参数名 类型 必填 默认值 值范围 说明
obj_type String true ["topic", "reply"]
obj_id Integer true
/nodes.json

获取所有节点列表

Returns:

{
    "nodes": [
        {
            "id": 1,
            "name": "Ruby",
            "topics_count": 1692,
            "summary": "Ruby 是一门优美的语言",
            "section_id": 1,
            "sort": 0,
            "section_name": "Ruby",
            "updated_at": "2015-03-01T22:35:21.627+08:00"
        },
        {
            "id": 2,
            "name": "Rails",
            "topics_count": 3160,
            "summary": "Ruby on Rails, 也称 Rails, 是一个使用 Ruby 语言写的开源 Web 开发框架。",
            "section_id": 1,
            "sort": 98,
            "section_name": "Ruby",
            "updated_at": "2015-03-01T22:35:21.657+08:00"
        },
        ...
    ]
}

/nodes/:id.json

获取单个 Node 的详情,结构类似 /api/v3/nodes.json 里面 Hash 的结构

此接口的使用场景:

需要获取单个 Node 的话题总数,介绍等信息的时候,你无须再拉取 Node 列表。

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

/notifications.json

获取当前用户的通知列表。
NOTE:(此接口不会将取到的通知设成已读,你需要调用一下 /notifications/read)

Returns:

{
    "notifications": [
        {
            "id": 394354,
            "type": "Topic",
            "read": true,
            "actor": {
                "id": 35,
                "login": "monster",
                "name": null,
                "avatar_url": "http://gravatar.com/avatar/dba7c3f68c94ec5f7ac96d0a5e7db205.png?s=120"
            },
            "mention_type": null,
            "mention": null,
            "reply": null,
            "created_at": "2015-05-12T22:08:53.542+08:00",
            "updated_at": "2015-05-18T20:50:26.393+08:00"
        },
        {
            "id": 394251,
            "type": "TopicReply",
            "read": true,
            "actor": {
                "id": 35,
                "login": "monster",
                "name": null,
                "avatar_url": "http://gravatar.com/avatar/dba7c3f68c94ec5f7ac96d0a5e7db205.png?s=120"
            },
            "mention_type": null,
            "mention": null,
            "reply": {
                "id": 256170,
                "body_html": "<p>asdgasdgasdgasdgasdg</p>",
                "created_at": "2015-05-12T16:24:07.284+08:00",
                "updated_at": "2015-05-12T16:24:07.284+08:00",
                "deleted": false,
                "topic_id": 25261
            },
            "created_at": "2015-05-12T16:24:07.319+08:00",
            "updated_at": "2015-05-18T20:50:26.393+08:00"
        },
    ]
}

Params
参数名 类型 必填 默认值 值范围 说明
offset Integer false 0
limit Integer false 20 1..150
/notifications/:id.json

删除当前用户的某个通知

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

/notifications/all.json

删除当前用户的所有通知

/notifications/read.json

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

Params
参数名 类型 必填 默认值 值范围 说明
ids Array true
/photos.json

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

Params
参数名 类型 必填 默认值 值范围 说明
file true

Image file.

/replies/:id.json

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

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

/replies/:id.json

更新回帖

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

body String true
/replies/:id.json

删除回帖

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

/topics.json

获取话题列表

Returns:

{
    "topics": [
        {
            "id": 25262,
            "title": "Rails 中自动布署工具 mina 的经验谈",
            "created_at": "2015-05-12T22:08:53.509+08:00",
            "updated_at": "2015-05-12T22:09:10.772+08:00",
            "replied_at": "2015-05-12T22:09:10.005+08:00",
            "replies_count": 1,
            "node_name": "Sinatra",
            "node_id": 43,
            "last_reply_user_id": 2,
            "last_reply_user_login": "huacnlee",
            "user": {
                "id": 35,
                "login": "monster",
                "name": null,
                "avatar_url": "http://gravatar.com/avatar/dba7c3f68c94ec5f7ac96d0a5e7db205.png?s=120"
            },
            "deleted": false,
            "excellent": true,
            "abilities": {
                "update": true,
                "destroy": true
            }
        },
        {
            "id": 25253,
            "title": "旧爱 Bootstrap,新欢 Materialize",
            "created_at": "2015-04-22T18:12:53.160+08:00",
            "updated_at": "2015-05-18T20:50:44.486+08:00",
            "replied_at": "2015-05-12T21:59:13.520+08:00",
            "replies_count": 10,
            "node_name": "分享",
            "node_id": 26,
            "last_reply_user_id": 2,
            "last_reply_user_login": "huacnlee",
            "user": { ... },
            "deleted": false,
            "excellent": false,
            "abilities": {
                "update": true,
                "destroy": true
            }
        },
        ...
    ]
}

Params
参数名 类型 必填 默认值 值范围 说明
type String false last_actived ["last_actived", "recent", "no_reply", "popular", "excellent"]
  • last_actived - 最近更新的(社区默认排序)
  • recent - 最新创建(会包含 NoPoint 的)
  • no_reply - 还没有任何回帖的
  • popular - 热门的话题(回帖和赞超过一定的数量)
  • excellent - 精华帖
node_id Integer false

如果你需要只看某个节点的,请传此参数

offset Integer false 0
limit Integer false 20 1..150
/topics.json

创建话题

Params
参数名 类型 必填 默认值 值范围 说明
title String true

话题标题

body String true

话题内容, Markdown 格式

node_id Integer true

节点编号

/topics/:id.json

更新话题

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

title String true

话题标题

body String true

话题内容, Markdown 格式

node_id Integer true

节点编号

/topics/:id.json

获取完整的话题内容

Returns:

{
    "topic": {
        "id": 25209,
        "title": "Rails 4.2 中 ActiveJob 的使用",
        "created_at": "2015-04-20T13:01:24.262+08:00",
        "updated_at": "2015-04-23T20:00:09.008+08:00",
        "replied_at": "2015-04-23T19:47:28.173+08:00",
        "replies_count": 10,
        "node_name": "Rails",
        "node_id": 2,
        "last_reply_user_id": 2,
        "last_reply_user_login": "huacnlee",
        "user": {
            "id": 10547,
            "login": "jicheng1014",
            "name": "哥有石头",
            "avatar_url": "http://gravatar.com/avatar/ac312b6f8e75f1e2db5026b7a67078ba.png?s=120"
        },
        "deleted": false,
        "abilities": {
            "update": false,
            "destroy": false
        },
        "body": "## 初探ActiveJob",
        "body_html": "<h4>初探ActiveJob</h4>",
        "hits": 19,
        "likes_count": 10,
        "suggested_at": "2015-04-23T19:47:28.173+08:00"
    },
    "meta" : {
      "followed": true,
      "liked": false,
      "followed": true
    }
}

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

/topics/:id/favorite.json

收藏话题

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

/topics/:id/follow.json

关注话题

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

/topics/:id/replies.json

获取某个话题的回帖列表

Returns:

{
    "replies": [
        {
            "id": 248607,
            "body_html": "<p>在我刚毕业的时候读过这一篇, 收获颇丰.</p>",
            "created_at": "2015-02-23T14:14:52.043+08:00",
            "updated_at": "2015-02-23T14:14:52.043+08:00",
            "deleted": false,
            "topic_id": 24325,
            "user": {
                "id": 121,
                "login": "lyfi2003",
                "name": "windy",
                "avatar_url": "http://ruby-china-files-dev.b0.upaiyun.com/user/large_avatar/121.jpg"
            },
            "abilities": {
                "update": false,
                "destroy": false
            }
        },
        {
            "id": 248608,
            "body_html": "<p>投精华和置顶!</p>",
            "created_at": "2015-02-23T14:41:32.977+08:00",
            "updated_at": "2015-02-23T14:41:32.977+08:00",
            "deleted": false,
            "topic_id": 24325,
            "user": { ... },
            "abilities": {
                "update": false,
                "destroy": false
            }
        },
        ...
    ],
    "meta": {
      "user_liked_reply_ids": [上面列表里面,用户喜欢过的回复编号]
    }
}

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

offset Integer false 0
limit Integer false 20 1..150
/topics/:id/replies.json

创建回帖

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

body String true

回帖内容, Markdown 格式

/topics/:id/unfavorite.json

取消收藏话题

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

/topics/:id/unfollow.json

取消关注话题

Params
参数名 类型 必填 默认值 值范围 说明
id String true

主键

/users.json

获取活跃会员列表

Returns:

{
    "users": [
        {
            "id": 1,
            "login": "rei",
            "name": "Rei",
            "avatar_url": "http://ruby-china-files-dev.b0.upaiyun.com/user/large_avatar/1.jpg"
        },
        {
            "id": 2,
            "login": "huacnlee",
            "name": "李华顺",
            "avatar_url": "http://ruby-china-files-dev.b0.upaiyun.com/user/large_avatar/2.jpg"
        },
        ...
    ]
}

Params
参数名 类型 必填 默认值 值范围 说明
limit Integer false 20 1..150
/users/:login.json

获取用户详细资料

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

/users/:login/block.json

屏蔽用户

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

/users/:login/blocked.json

用户屏蔽的用户

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

offset Integer false 0
limit Integer false 20 1..150
/users/:login/favorites.json

用户收藏的话题列表

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

offset Integer false 0
limit Integer false 20 1..150
/users/:login/follow.json

关注用户

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

/users/:login/followers.json

用户的关注者列表

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

offset Integer false 0
limit Integer false 20 1..150
/users/:login/following.json

用户正在关注的人

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

offset Integer false 0
limit Integer false 20 1..150
/users/:login/replies.json

获取用户创建的回帖列表

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

order String false recent ["recent"]
offset Integer false 0
limit Integer false 20 1..150
/users/:login/topics.json

获取用户创建的话题列表

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

order String false recent ["recent", "likes", "replies"]
offset Integer false 0
limit Integer false 20 1..150
/users/:login/unblock.json

取消屏蔽用户

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

/users/:login/unfollow.json

取消关注用户

Params
参数名 类型 必填 默认值 值范围 说明
login String true

主键

Example

我们用 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')
=> Faraday.get("https://ruby-china.org/api/v3/hello.json?access_token=#{access_token.token}").body
{ 'current_user' : 'username' }