typecho-plugin-Restful
typecho-plugin-Restful copied to clipboard
moefront
Yet another awesome Typecho plugin to make your blog RESTful.
Typecho Restful 插件
这是一个将 Typecho 博客 RESTful 化的插件。启用此插件，你可以通过请求 API 向站点请求或写入信息（获取文章内容、获取评论、添加评论等）。
食用方法
常规
下载插件并解压，将解压后的目录重命名为 Restful (区分大小写)，然后到后台插件管理页面启用并设置即可。
使用 Composer 安装
cd /path/to/typecho/usr/plugins
composer create-project moefront/typecho-plugin-restful Restful --prefer-dist --stability=dev
chown www:www -R Restful
API
下面假设您的站点已经开启了地址重写（伪静态）；如果没有的话，那么需要在下文列出的请求的 URI 前加上 /index.php，例如：/api/posts => /index.php/api/posts.
文章列表
GET /api/posts
| 参数 | 类型 | 描述 | |
|---|---|---|---|
| page | int | 当前页 | 可选 |
| pageSize | int | 分页数 | 可选 |
| filterType | string | category 或 tag 或 search | 可选 |
| filterSlug | string | 分类名或标签名或搜索关键字 | 可选 |
| showContent | bool | 是否显示文章具体内容 | 可选 |
| showDigest | string | 指定是否显示文章摘要及显示摘要的类型 | 可选 |
| limit | int | 当 showDigest 的类型为 excerpt 时，指定截断的字数 | 可选 |
PS： showDigest 有两个可选的值，分别为 more 和 excerpt. 当选用 more 模式时，插件将返回文章中 <!--more--> 标签前的内容解析后的 HTML；选用 excerpt 模式时，插件将对解析后的文章过滤 HTML 标签后，返回前 limit 个字符。默认 limit 的值为 200.
页面列表
GET /api/pages
分类列表
GET /api/categories
标签列表
GET /api/tags
文章/页面详情
GET /api/post
| 参数 | 类型 | 描述 | |
|---|---|---|---|
| cid | int | 文章/页面 ID | 二选一 |
| slug | string | 文章/页面别名 | 二选一 |
评论列表
GET /api/comments
| 参数 | 类型 | 描述 | |
|---|---|---|---|
| page | int | 当前页 | 可选 |
| pageSize | int | 分页数 | 可选 |
| order | string | 评论显示顺序(asc/desc) | 可选 |
| cid | int | 文章 ID | 二选一 |
| slug | string | 文章别名 | 二选一 |
PS: 如果带上 Cookie 请求，会显示当前 Cookie 记住的用户所发布的待审核的评论。
最近评论
GET /api/recentComments
| 参数 | 类型 | 描述 | |
|---|---|---|---|
| size | int | 最近评论的条数，默认为 9 | 可选 |
发表评论
POST /api/comment
| 参数 | 类型 | 描述 | |
|---|---|---|---|
| cid | int | 文章 ID | 二选一 |
| slug | string | 文章别名 | 二选一 |
| parent | int | 父级评论 ID | 可选 |
| text | string | 评论内容 | 必须 |
| author | string | 作者 | 必须 |
| string | 邮箱 | 必须 | |
| url | string | URL | 可选 |
| token | string | 文章/页面详情返回的 token | 必须 |
| uid | int | 已注册用户评论时，用户的 UID | 可选 |
| authCode | string | 已注册用户评论时，用户的 authCode | 可选 |
PS：此处Content-Type为application/json, 也就是说你应当以 JSON 格式提交数据。
PS2: uid 和 authCode 可以在 Cookie 中找到（形如 hash__typecho_uid 和 hash__typecho_authCode 的内容）。如果直接带上 Cookie 请求此 API 则不再需要带上 uid 和 authCode 参数。请求时需要带上合法的 User-Agent.
设置项
GET /api/settings
用户信息
GET /api/users
| 参数 | 类型 | 描述 | |
|---|---|---|---|
| uid | int | 用户 ID | 可选 |
| name | string | 用户的用户名或昵称 | 可选 |
归档
GET /api/archives
PS：默认按从新到旧 (desc) 顺序排列文章。
| 参数 | 类型 | 描述 | |
|---|---|---|---|
| order | string | 归档的排序方式 (asc / desc) | 可选 |
| showContent | bool | 是否显示文章内容 | 可选 |
| showDigest | string | 指定是否显示文章摘要及显示摘要的类型 | 可选 |
| limit | int | 当 showDigest 的类型为 excerpt 时，指定截断的字数 | 可选 |
PS: showDigest 和 limit 参数的使用参见 /api/posts 部分。
其它
自定义 URI 前缀
默认情况下 Restful 插件会占用 /api/* 用于不同的接口。如果该 URI 有其它用途，或与其它插件冲突，或者由于某些不可描述的原因用户不希望暴露该接口，可以选择通过修改 config.inc.php 自定义前缀。
例如，在 config.inc.php 文件中加入下列内容：
define('__TYPECHO_RESTFUL_PREFIX__', '/rest/');
重新启用插件，此时你可以通过 /rest/* 访问相关 API.
License
typecho-plugin-restful is MIT licensed.
Since it is a derivative of Typecho which is GPLv2 licensed, you may also need to observe GPLv2 when you are redistributing this plugin.
moefront