概述

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

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

公共约定

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

HTTP

  • 数据使用 UTF-8 编码
  • 参数可能是查询字符串也可能是通过 body 传递
  • 响应的 Status Code 可能是 200 也可能是其他值,客户端需要校验
    • 401:需要登录
    • 403:权限不足

User-Agent

不要使用 HTTP Client 库自带的 UA,请一定要自定义 UA,推荐格式 {App}/{Ver},比如 Solo/2.9.5

鉴权

  • 服务端使用 HTTP Cookie symphony 进行身份验证

列表分页

  • 使用查询字符串 p 作为当前页号
  • 服务端固定页大小为 20

响应结构

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

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

其中:

  • sc:类型是 int,不会为 null,表示状态码,其值请参考 StatusCode.java
  • msg:类型是 string,不会为 null(默认是 "" 空字符串),表示消息提示
  • data:类型是 JSONObject 或者 JSONArray,可能为 null,表示返回的数据

注意事项

  • 使用 HTTPS 协议
  • 所有 API 都会做是否允许非登录请求的校验,如果返回 403 则请带上登录后合法的 Cookie 再请求,具体校验逻辑请参考代码 AnonymousViewCheck.java

帖子

获取最新帖子列表

GET 方法:

获取领域帖子列表

获取标签帖子列表

  • GET 方法:https://hacpai.com/api/v2/articles/tag/{tagURI}?p=1

示例:

获取帖子详情

发布帖子

  • POST 方法:https://hacpai.com/api/v2/article
  • Body:
     {
         "articleTitle": "",
         "articleTags": "", // 用英文逗号分隔
         "articleContent": "",
         "articleRewardContent": "" // 打赏区内容
         "articleRewardPoint": int // 打赏积分
     }

获取帖子详情用于更新

更新帖子

  • PUT 方法:https://hacpai.com/api/v2/article/{articleId}
  • Body:
     {
         "articleTitle": "",
         "articleTags": "", // 用英文逗号分隔
         "articleContent": "",
         "articleType": int, // 帖子类型,按获取帖子后的值传入即可
         "articleRewardContent": "" // 打赏区内容
         "articleRewardPoint": int // 打赏积分
     }

回帖

发布回帖

  • POST 方法:https://hacpai.com/api/v2/comment
  • Body:
     {
         "articleId": "",
         "commentContent": "",
         "commentOriginalCommentId": "", // 可选,如果是回复则传入原回帖 id
     }

领域

获取领域列表

获取领域详情

标签

获取标签列表

获取标签详情

用户

获取用户详情

获取用户帖子列表

获取用户回帖列表

获取用户关注帖子列表

获取用户关注用户列表

获取用户关注标签列表

获取用户收藏帖子列表

获取用户关注者列表

通知

获取未读计数

获取收到的回帖消息列表

获取收到的回复消息列表

获取提及我的消息列表

获取我关注的消息列表

获取我的积分消息列表

获取同城广播消息列表

获取系统公告消息列表

登录

  • POST 方法:https://hacpai.com/api/v2/login
  • Body:
     {
         "userName": "", // 用户名或者邮箱
         "userPassword": "", // 使用 MD5 哈希后的值 
         "captcha": "" // 正常登录不用带该字段,登录失败次数过多时必填
     }
  • 返回:
     {
         "sc": 0, // 0 为成功
         "msg": "",
         "token": "", // 成功时才有该值
         "userName": "" // 用户名
         "needCaptcha": "" // 登录失败次数过多会返回该值       
     }
    登录成功后会返回 token,后续请求需要将该值设置为 Cookie symphony 的值,用于鉴权。如果需要填验证码,则使用 needCaptcha 返回的值作为参数 GET 请求一次 /captcha/login?needCaptcha={needCaptcha},返回的图片就是验证码了。

登出

  • POST 方法:https://hacpai.com/api/v2/logout

活动

领取今日签到奖励

TBD

领取昨日活跃奖励

TBD

  • 黑客派

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

    212 引用 • 4614 回帖 • 964 关注
  • Sym

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

    313 引用 • 3636 回帖 • 609 关注
  • API
    31 引用 • 241 回帖 • 1 关注
  • 客户端
    5 引用 • 73 回帖
感谢    关注    收藏    赞同    反对    举报    分享