内容 API 开放,欢迎各位独立博客主进行连接

状态

B3log 构思

B3log 构思 目前已经基本实现, Solo黑客派现在已经可以稳定地进行帖子、回帖内容交互:

  • 使用 Solo 独立博客发布博文、评论会自动发布到黑客派社区
  • 在黑客派社区上发布帖子、回帖也会自动发布到 Solo 独立博客

这样可以为博主带来更多的关注和互动,同时社区通过内容聚合也能够吸引更多用户。

经过一段时间的实践验证,我们觉得内容交互的 API 可以不仅限于 Solo ,而应该开放给所有独立博客,让大家都加入进来共建这个生态!

内容 API

核心内容 API 一共有 4 个。前 3 个 APIs 由社区服务器实现,提供给博客进行调用;第 4 个 API 由博客实现,提供给社区进行调用:

  1. 博客发布博文 -> 社区发布帖子:在博客发布博文的同时调用社区的发帖,将博文内容同步到社区
  2. 博客更新博文 -> 社区更新帖子:在博客更新博文的同时调用社区的更新,将博文内容同步到社区
  3. 博客发布评论 -> 社区发布回帖:在博客发布评论的同时调用社区的回帖,将评论内容同步到社区
  4. 社区发布回帖 -> 博客发布评论:在社区回帖的同时调用博客的发布评论,将回帖内容同步到博客

通过这 4 个 APIs 就可以实现博客和社区的相互连接,理论上博客还需要实现两个帖子同步博客的 APIs,不过一般不常用,所以可以不必实现。

社区账号

要连接到社区前需要先到社区注册账号,其中最关键的是:

  • 注册时候使用的邮箱必须和博客用户的邮箱一致(调用 API 指定的实参),因为这个邮箱是用来鉴别连接身份的

另外,还需要进行一下设置,请参考 黑客派客户端同步设置

API 描述

上面我们介绍了基本原理,下面就是各个 API 的详细描述了:

发布 / 更新文章

发布文章和更新文章使用相同的 API,如果 article.id 已经存在则视为更新操作。

调用地址

参数

在 POST body 中指定 JSON 格式的实参:

{
    "article": {
        "id": "1165070220000", 
        "title": "这是一篇测试文章", 
        "permalink": "/test-post", 
        "tags": "tag1, tag2", 
        "content": "Test"
    }, 
    "client": {
        "title": "我的个人博客", 
        "host": "http://xxx.com", 
        "email": "test@hacpai.com", 
        "key": "xxxx"
    }
}
  • article.id:客户端的文章 id,如果该 id 文章在社区已经存在,则视为更新文章
  • article.title:文章标题
  • article.permalink:客户端固定链接
  • article.tags:文章标签,英文输入状态的逗号分隔
  • article.content:文章内容,HTML 或 Markdown 格式
  • client.title:客户端标题,比如博客的名字
  • client.host:客户端 URL
  • client.email:账号邮箱,需要和社区注册的账号邮箱一致
  • client.key:账号同步 Key,需要和社区中配置的一致

发布评论

调用地址

参数

在 POST body 中指定 JSON 格式的实参:

{
    "comment": {
        "id": "1165070220000", 
        "articleId": "1164070220000", 
        "content": "Test comment", 
        "authorName": "Daniel", 
        "authorEmail": "dl88250@gmail.com"
    }, 
    "client": {
        "title": "我的个人博客", 
        "host": "http://xxx.com", 
        "email": "test@hacpai.com", 
        "key": "xxxx"
    }
}
  • comment.id:客户端的评论 id
  • comment.articleId:该条评论所对应的客户端文章 id
  • comment.content:评论内容,HTML 或 Markdown 格式
  • comment.authorName:评论人名称,可选
  • comment.authorEmail:评论人邮箱,可选
  • client.title:客户端标题,比如博客的名字
  • client.host:客户端 URL
  • client.email:账号邮箱,需要和社区注册的账号邮箱一致
  • client.key:账号同步 Key,需要和社区中配置的一致

接收评论

接收评论的接口由客户端自己实现,这里给出的是社区去调用时候的规范。

调用地址

  • 调用用户在社区设置的 "客户端收评接口" 地址
  • 使用 POST 方法

参数

在 POST body 中指定 JSON 格式的实参:

{
    "comment": {
        "articleId": "", 
        "content": "",
        "contentHTML": "",
        "ua": "",
        "ip": "",
        "authorName": "", 
        "authorEmail": "", 
        "authorURL": "",
        "authorAvatarURL": "",
        "isArticleAuthor": true,
        "time": 1457784330398
    }, 
    "client": {
        "key": ""
    }
}
  • comment.articleId:该条评论所对应的客户端文章 id
  • comment.content:评论内容,Markdown 格式
  • comment.contentHTML:评论内容, HTML 格式
  • comment.ua:User-Agent,可能为空字符串 ""
  • comment.ip:IP,可能为空字符串 ""
  • comment.authorName:评论人名称
  • comment.authorEmail:评论人邮箱
  • comment.authorURL:评论人 URL
  • comment.authorAvatarURL:评论人头像 URL
  • comment.isArticleAuthor:评论人是否是文章作者
  • comment.time:评论时间,格式为时间毫秒
  • client.key:账号同步 Key,需要和社区中配置的一致

注意:从社区同步评论到博客时,收评接口实现评论保存后不能在走同步回社区的逻辑。

基础实现

我们会提供一些主流编程语言的 API 基础实现,方便博客主调整代码。

TBD


完整插件

欢迎大家来实现自己所用博客的插件 ~


OK,要做什么我应该已经介绍清楚了,大家怎么看呢?