这里会显示出您选择的修订版和当前版本之间的差别。
后一修订版 | 前一修订版 | ||
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 通用请求及响应示例”。 | ||
+ | |||
+ | 具体的接口参见对应接口文档。 | ||
+ |