====== 基本设计 ======

===== 概要 =====

以 Z-BlogPHP 的 **功能模块（Module）** 为划分依据，可以分为以下十个模块：

  * 用户模块
  * 文章模块（包括页面）
  * 应用模块（包括插件和主题）
  * 侧栏模块
  * 附件模块
  * 评论模块
  * 标签模块
  * 分类模块
  * 系统模块
  * 设置模块

**接口行为（Action）** 简单来说就是实现某个模块的数据增删改查操作，比如用户模块的新增用户、用户登录、用户信息的获取与修改等操作。

ZBP API 的整体思想是：服务端根据客户端发送的请求，针对 **模块** 进行相应的 **行为** 操作， 并将执行结果返回给客户端。本质上跟原有的网页版差别不大，就是同一套业务逻辑下的不同输出形式，网页版返回的是 HTML，API 返回的是 JSON。

===== 统一入口 =====

规定接口入口为：<code>http[s]://<域名>/api.php</code>

===== 请求方法 =====

客户端主要使用 GET 和 POST 这两种 HTTP 请求方法来请求服务端资源。

其中，GET 表示“获取”操作，对应数据库中的操作为 SELECT。如：获取某篇文章。

POST 表示“新增”、“修改”和“删除”操作，对应数据库中的操作为 INSERT、 UPDATE 和 DELETE。如：新增一个用户。

为保证对大量参数的支持，对于“获取/查询”类型的接口，同时支持 GET 和 POST 两种请求方式；对于“增删改”类型的接口，只支持 POST 请求方式。

===== 公共请求消息头 =====

^ 消息头（Header）   ^ 是否必需  ^ 示例值                           ^ 说明                                                        ^
| Content-Type     | 可选     | application/json; charset=utf-8 | 客户端接受的消息格式。不管怎样，服务端始终返回 JSON 格式内容。 |
| Accept-Encoding  | 可选     | gzip, deflate, br               | 客户端接受的压缩算法                                           |
| User-Agent       | 可选     | Mozilla/5.0                     | -                                                           |
| Referer          | 可选     | https://example.com/            | 来源地址                                                     |
| Accept-Language  | 可选     | zh-cn                           | 客户端接受的语言代码                                           |
| Authorization     | 可选     | emhvdXppc2h1fHx8ZWQyZTk2OG...   | 用于鉴权                                                 |

===== URI 命名 =====

==== 规定 ====

  * URI 对大小写不敏感（不区分大小写）。
  * POST 的 HTTP Body 中，JSON 内容的属性名一律使用小写。

==== 模块命名 ====

^ 模块                       ^ 命名     ^
| 用户模块                   | member     |
| 文章模块（包括页面）       | post  |
| 应用模块（包括插件和主题） | app      |
| 侧栏模块                   | sidebar  |
| 附件模块                   | atta     |
| 评论模块                   | comment  |
| 标签模块                   | tag      |
| 分类模块                   | category |
| 系统模块                   | system   |
| 设置模块                   | setting  |

==== URL 通用格式 ====

<code>
http[s]://<域名>/api.php?mod=<模块名>[&act=<行为名>][&其他...]
</code>

由于是单一入口，因此不同的模块不能用路径表示，需要用 URL 参数表示。参数排序不分先后。

主要参数有两个：模块名和行为名。

**模块名**

模块名就是功能模块的英文名。

**行为名**

行为名代表操作，比如 ''act=post'' 表示新增资源，''act=update'' 表示修改/更新资源，''act=delete'' 表示删除资源。

  * 行为名缺省机制

在请求方法为 GET 的前提下，因为 GET 语义即为“获取”，故不指定行为名时，默认进行的操作即为 ''act=get'' 这一行为。

因此，“获取某个用户的信息”这一操作的接口为 ''mod=user&act=get&id=123'' ，可以省略掉 ''act=get''，直接用 ''mod=user&id=123'' 也可以正常请求。

POST 请求不支持行为名缺省机制，必须指定行为名。

  * 多语义行为名

多语义行为名可以表示针对更为具体的资源对象进行操作，多个语义的行为名词之间用英文下划线“_”分隔。

如：对于侧栏模块（mod=sidebar），存在两种资源对象，一是侧栏本身，二是侧栏当中的“模块”。''mod=sidebar&act=get&id=1'' 这一接口表示 “获取 ID 为 1 的侧栏的信息”，若要实现“获取侧栏中的模块的信息”，则需要更为详细的语义 ''act=get_module'' ，即 ''mod=sidebar&act=get_module&id=name''。其他的存在多个资源对象的情况均以此类推。

**其他参数**

表示一些附加内容，比如约束条件、授权信息的  Token 这些，或者其他第三方开发者自定义的内容。

==== GET 示例 ====

例如，请求获取 ID 为 123 的用户的信息。

GET ''https://example.com/api.php?mod=user&id=123''

==== POST 示例 ====

例如，请求修改用户信息。

规定：模块名和行为名用 URL 参数传递，其他信息以 HTTP Body 传递：

POST ''https://example.com/api.php?mod=user&act=update''

<code>
{
    "id": 123,
    "nickname": "Chris",
    "email": "123@example.com"
}
</code>

===== 约束与过滤 =====

约束过滤器（Filter）一般用于列表类的资源，比如文章列表这种。

具体支持的约束条件由该功能模块的数据表决定。

多个约束条件默认使用“AND”（与）逻辑。

^ 参数         ^ 类型   ^ 示例值       ^ 说明                            ^
| limit        | int    | 10          | 指定返回记录的数量              |
| offset       | int    | 10          | 指定返回记录的开始位置          |
| page         | int    | 2           | 指定第几页                      |
| perpage     | int    | 100         | 每页的记录数                    |
| sortby       | string | name        | 指定返回结果按照哪个属性排序，大小写敏感，必须与数据表列名一致    |
| order        | string | asc 或 desc | 排序顺序，asc：升序，desc：降序 |

概览：

  * limit=10：指定返回记录的数量
  * offset=10：指定返回记录的开始位置
  * page=2&perpage=100：指定第几页，以及每页的记录数
  * sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序

===== 权限认证 =====


要使用发出经过身份验证的请求，需要设置如下 ''authorization'' 头：

<code>
Authorization: Bearer {yourtokenhere}
</code>

当然，也可以在请求参数中附加，如：

<code>
https://example.com/api.php?mod=setting&act=get&token={yourtokenhere}
</code>

===== 公共消息响应头 =====

^ 消息头（Header） ^ 说明 ^ 示例值                          ^ 说明                                             ^
| Content-Type     | 必需 | application/json; charset=utf-8 | 目前默认只支持返回 JSON 格式                     |
| Content-Encoding | 可选 | gzip                            | 内容压缩方式，根据客户端选择，默认启用 gzip 压缩 |
| Date             | 可选 | Sun, 23 Feb 2020 07:03:41 GMT   | 服务端响应时间，有些时候可以用来测试延迟         |

===== 通用返回格式 =====

服务端响应的 Body 内容为 JSON 字符串，统一为如下格式：

^ 参数名   ^ 类型   ^ 说明     ^
| message | string | 响应描述 |
| data    | object | 主要数据 |
| error   | object | 错误信息 |
| runtime | object | 调试信息 |

详细的错误信息和调试信息仅在启用了调试模式的情况下输出。

属性名一律使用小写，如有需要，多个单词之间使用英文下划线”_“分隔，如”new_data“。

示例一，没有权限：

<code>
{
    "code": 401,
    "message": "没有权限",
    "data": null,
    "error": {
        "code": 6,
        "type": 0,
        "message": "没有权限"
    }
}
</code>

示例二，成功请求某个用户的信息：

<code>
{
    "code": 200,
    "message" : "OK",
  	"data": {
      	"id": 123,
      	"username": "Chris",
  	"email": "123@example.com"
    },
    "error": null
}
</code>

===== 具体接口 =====

请先阅读“ZBP API 通用请求及响应示例”。

具体的接口参见对应接口文档。