社区客户端 API 文档

概述

该文档主要面向社区客户端开发者,如果你想开发一个移动端 APP 的话请仔细阅读该文档。如果你喜欢写博客,想要将博客和社区进行联动的话请参考内容 API 开放,欢迎各位独立博客主进行连接

目前以下列出的 API 已经可用,大家有什么想补充的请跟帖。

使用原则

公共约定

对于请求和响应的一些公共约定在这里统一进行描述。

HTTP

User-Agent

不要使用 HTTP 客户端自带的 UA,请一定要自定义 UA,推荐格式 {App}/{Ver},比如 Solo/2.9.5。如果不自定义 UA,请求将会被社区的流量监控系统阻断,并且对发起请求的 IP 进行一定时间的拦截。

鉴权

列表分页

请求:

响应:

返回 pagination 对象,包含两个字段:

响应结构

响应中的 HTTP body 为 JSON 结构,固定包含 3 个字段:

{
    "sc": 0,
    "msg": "",
    "data": null
}

其中:

注意事项

帖子

获取最新帖子列表

GET 方法:

获取领域帖子列表

获取标签帖子列表

示例:

获取帖子详情

发布帖子

获取帖子详情用于更新

更新帖子

回帖

发布回帖

领域

获取领域列表

获取领域详情

标签

获取标签列表

获取标签详情

用户

根据用户名获取用户详情

根据用户序号获取用户详情

获取用户帖子列表

获取用户回帖列表

获取用户关注帖子列表

获取用户关注用户列表

获取用户关注标签列表

获取用户收藏帖子列表

获取用户关注者列表

通知

获取未读消息计数

获取收到的回帖消息列表

获取收到的评论消息列表

获取收到的回复消息列表

获取提及我的消息列表

获取我关注的消息列表

获取我的积分消息列表

获取同城广播消息列表

获取钱包消息列表

获取系统公告消息列表

标记消息列表为已读

其中 {type} 是消息类型:

同城广播、钱包和系统公告消息拉取后会被自动标记为已读状态,无需调用此 API 进行标记已读。

通知关联的数据类型说明

每条获取到的消息都会有 dataType 字段,表示与该消息关联的数据类型。

数据类型说明
dataType dataId 备注
-1 没有该字段 关联数据已被删除
0 暂未使用
1 暂未使用
2 帖子 id 或回帖 id 此处为设计缺陷,建议用 dataId 先查回帖,为空的话再查帖子
3 回帖 id
4 帖子 id 关注的用户发新贴
5 积分转账 id 转账记录会关联转账类型,目前暂时没有接口查询,下同
6 积分转账 id
7 打赏 id 打赏记录会关联打赏类型,目前暂时没有接口查询,下同
8 感谢 id 感谢记录会关联感谢类型,目前暂时没有接口查询,下同
9 帖子 id
10 积分转账 id
11 积分转账 id
12 感谢 id
13 回复 id
14 用户 id
15 帖子 id
16 帖子 id
17 用户 id
18 用户 id
19 老角色 id - 新角色 id
20 帖子 id
21 回帖 id
22 帖子 id
23 帖子 id - 用户 id
24 帖子 id - 用户 id
25 回帖 id - 用户 id
26 回帖 id - 用户 id
27 帖子 id - 用户 id
28 帖子 id - 用户 id
29 货币转账 id
30 货币转账 id
31 货币转账 id
32 货币转账 id
33 回帖 id
34 回帖 id 合并后所有的回帖 id 需要通过 data 字段获取
35 回帖 id 同 34
36 积分转账 id
37 聊天会话 id
38 评论 id - 用户 id
39 感谢 id
40 评论 id
41 评论 id
42 帖子 id
43 帖子 id
44 回帖 id
45 回帖 id
46 评论 id
47 评论 id
48 帖子 id
49 回帖 id
50 评论 id
51 帖子 id
52 回帖 id
53 评论 id
54 积分转账 id

榜单

获取新注册用户列表

获取粉丝榜

登录

密码验证

两步验证

登出

系统

获取系统当前时间

  • 黑客派

    黑客派是 B3log 开源社区的线上论坛,这里主要汇聚了程序员和设计师。HacPai 分别取 Hacker / Painter 的头三个字母组成,源自《黑客与画家》。

    我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

    更多细节请浏览黑客派简介

    378 引用 • 7621 回帖 • 523 关注
  • Sym

    Sym 是一个用 Java 实现的现代化社区(论坛/BBS/社交网络/博客)平台,“下一代的社区系统,为未来而构建”。

    479 引用 • 4402 回帖 • 651 关注
  • API

    应用程序编程接口(Application Programming Interface)是一些预先定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码,或理解内部工作机制的细节。

    61 引用 • 354 回帖
  • 客户端
    4 引用 • 111 回帖
1 操作
88250 在 2020-03-05 12:20:34 更新了该帖
优质回帖
  • lijp 1 1 赞同

    补充:

    1. 感谢、like、unlike、收藏、查看的接口;
    2. 相关帖子的列表接口;
    3. 搜索的接口;(不知道能不能直接在移动端集成 Algolia)
    4. 书单的接口;

    其他的一些很好玩,但我觉得暂时没必要(此刻、财富排行及消费排行)

  • Vanessa 1 赞同

    0e060c04352a4a4092e3fab5bab6b873-image.png

    这几个怕是要提供一下。还有消息推送哟。

  • Vanessa 1 赞同
    • 文章详情页面评论需要下拉刷新,重新给一个接口
    • 文章详情页面返回 HTML
98 回帖
请输入回帖内容...
  • 295524115

    这个 API 在社区版 symphony 上也有么

    1 回复
  • 88250

    没有。

  • mayi123

    这种 API 怎么开发的啊?是要重新写 servlet 吗?能不能提供个例子呢?
    为什么我在 doget()中调用 service 方法(例如 ArticleQueryService.getArticle("1521445097051"))报以下错误呢?菜鸟一枚,请大家指点指点

    Servlet.service() for servlet [TestServlet] in context with path [/symphony] threw exception
    java.lang.NullPointerException
    at org.b3log.symphony.service.ArticleQueryService.getArticle(ArticleQueryService.java:1087)

    1 回复
  • 88250

    用 Latke 框架开发,参考已有代码中的 Processor;报错是 NPE,请检查代码。

    1 回复
  • mayi123

    谢谢您的提示,调通了。🙏

  • zongdusir

    有 QQ 群吗?可以讨论一下,我也可以创一个

    1 回复
  • 88250

    没有,我们都在这里交流。

  • shuiniu

    太棒了,很专业

  • someone9891

    请教一下,API 对于获取的文章 除了 API 上加的参数,还有其他的过滤条件吗?

    我发现 优选排序的接口。获取到的数据,最新的是 9 月 4 号的那条,跟社区的数据不一致。

    1 回复
  • 88250

    User-Agent 一定要配置,你看下上面的介绍。

  • ronger

    @88250 需要一个优选文章的 API trollface

    2 回复
  • 88250

    收到,下午有空就添加。

  • 88250

    最新帖子按优选排序的 API 已经上线。

  • ronger

    帖子详情是不是应该提供未渲染前的文章内容数据(Markdown 语法格式),以满足想自己渲染的用户
    @88250

    1 回复
  • 88250

    原始文本可能存在不安全内容,比如 XSS 脚本。

  • ronger

    建议提供被关注排行 API,用于向用户推荐优质作者
    近期新用户 API,用于增加新用户曝光率

    2 回复
  • 88250

    收到,最迟下周一会上线。

  • 88250

    已经上线了,你看下正文中的 榜单 一节。

    1 回复
  • ronger

    好的

  • 88250

    增加根据用户编号获取用户详情的 API: https://hacpai.com/api/v2/user/n/1

    1 回复
  • YxxXlv0COaxl

    用户信息里的随机是拿来干啥的?

    1 回复
  • 88250

    用来让客户端区别不同请求的。

  • hahayi

    社区版是不是没有 API 功能?

    1 回复
  • 88250

    没有。Sym 商业版和社区版的对比请看这里

  • illn

    @88250 hackpai 有没有互联登陆使用的 API ?

    1 回复
  • 88250

    因为黑客派目前用户很少,所以暂时不考虑开放授权登录。

  • wangtao92

    你好,已经购买上商业版了,有创建用户的接口吗

    1 回复
  • 88250

    你好,请在技术支持群讨论。

  • yp

    请求 API,返回 401 时, sc 字段变成了布尔类型 @88250

    {"sc":false,"msg":"401"}
    
    1 回复
  • 88250

    感谢反馈,已经修复。

  • DASHU

    获取收到的回帖消息列表

    这个接口检查一下 感觉有问题

  • DASHU

    请提供标记某个消息为已读的接口

    消息列表接口中的 数据类型 字段请提供一下定义

    1 回复
  • 88250

    收到,之前你说的接口问题指的是?

    1 回复
  • DASHU

    这里有几个消息 全是空的 连 dataId 都没

    1 回复
  • 88250

    麻烦贴一个我查下看看。

  • DASHU

    image.png

    1 回复
  • 88250

    dataType 34 是合并回帖,可以不用管。稍后我把完整的消息类型整理一下贴出来。

    1 回复
  • DASHU

    但是我在 pc 端看到那个位置,是有一个回帖消息的。如果忽略的话,没地方可以看到那个回帖消息。

    1 回复
  • 88250

    也是,这块的逻辑我都已经忘记得差不多了 🤣 等后面统一处理吧。

  • DASHU

    脑壳一下。。。

    清风明月 加个评论功能,然后加个查询我所关注的用户的清风明月列表接口。

    一个简单微博出来了。

    @88250 什么时候有空把接口 🙏 实现一下。。。

    然后会员私信功能接口也发一下 😄

    1 回复
  • 88250

    清风明月不会加入太多交互功能,目前的计划是仅加入感谢。过两天先解决之前你提的问题,新的 API 要缓缓了。

  • 88250

    通知接口新增:

    • 获取收到的评论消息列表
    • 获取钱包消息列表
    • 标记消息列表为已读

    文档补充了通知关联的数据类型说明 @DASHU 请看下是否能够满足需求。

  • yp

    有个疑问

    • 欢迎用于 APP、插件、数据分析研究等
    • 禁止用于以内容填充为目的应用或站点

    例如我有开发 APP 的想法,但同时我也会开发服务器 数据的走向是这样的
    客户端-> 我的服务器-> HacPai 服务器
    帐号、内容 都是黑客派的 同时为了一些特性 加一点自己的东西,这算是以内容填充为目的吗?

    1 回复
  • 88250

    如果脱离社区 API 后应用依然能工作的话就算是内容填充目的了,比如在你服务器上拉取了社区的数据给 APP 伺服(如果仅是临时缓存数据的话不算)。

    1 回复
  • yp

    感谢解答。那如果 我的服务器是作为一个备份服务器的作用呢?
    例如
    在请求黑客派服务器数据时超时或响应异常的情况,使用之前存储的数据返回给客户端

    原则就是:黑客派数据第一

    1 回复
  • 88250

    作为缓存用的话没问题,但我还是不太建议这样,特别是用户账号这一块,这样实现的话用户账号的安全性会被降低。

  • yp

    明白了谢谢, 如果要做的话 帐号密码不做缓存也是一个方法

  • tjob

    很棒!

请输入回帖内容 ...