Z-Blog Wiki Z-Blog Wiki

Z-Blog官方文库

用户工具

站点工具


zblogphp:development:api:basic-design

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

后一修订版
前一修订版
zblogphp:development:api:basic-design [2020/08/11 21:50]
捷闪站长网 创建
zblogphp:development:api:basic-design [2020/09/01 18:36] (当前版本)
心扬
行 37: 行 37:
  
 ^ 消息头(Header) ​  ^ 是否必需 ​ ^ 示例值 ​                          ^ 说明 ​                                                       ^ ^ 消息头(Header) ​  ^ 是否必需 ​ ^ 示例值 ​                          ^ 说明 ​                                                       ^
-| Content-Type ​    | 可选 ​    | application/​json;​ charset=utf-8 | 客户端接受的消息格式。<br />不管怎样,服务端始终返回 JSON 格式内容。 |+| Content-Type ​    | 可选 ​    | application/​json;​ charset=utf-8 | 客户端接受的消息格式。不管怎样,服务端始终返回 JSON 格式内容。 |
 | Accept-Encoding ​ | 可选 ​    | gzip, deflate, br               | 客户端接受的压缩算法 ​                                          | | Accept-Encoding ​ | 可选 ​    | gzip, deflate, br               | 客户端接受的压缩算法 ​                                          |
 | User-Agent ​      | 可选 ​    | Mozilla/​5.0 ​                    | -                                                           | | User-Agent ​      | 可选 ​    | Mozilla/​5.0 ​                    | -                                                           |
 | Referer ​         | 可选 ​    | https://​example.com/ ​           | 来源地址 ​                                                    | | Referer ​         | 可选 ​    | https://​example.com/ ​           | 来源地址 ​                                                    |
 | Accept-Language ​ | 可选 ​    | zh-cn                           | 客户端接受的语言代码 ​                                          | | 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 通用请求及响应示例”。
 +
 +具体的接口参见对应接口文档。
 +
zblogphp/development/api/basic-design.1597153813.txt · 最后更改: 2020/08/11 21:50 由 捷闪站长网