[PHP] API 开发规范

一、数据传输方式说明
GET（SELECT）：从服务器取出资源（一项或多项）
POST（CREATE）：在服务器新建一个资源
PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）
PATCH（UPDATE）：在服务器更新资源（客户端提供需要修改的资源数据）
DELETE（DELETE）：从服务器删除资源
★没有严格要求时，可以只用 GET 与 POST 两种方式。

二、状态码说明
当 GET, PUT 和 PATCH 请求成功时，要返回对应的数据，及状态码 200，即 SUCCESS
当 POST 创建数据成功时，要返回创建的数据信息，及状态码 201，即 CREATED
当 DELETE 删除数据成功时，不返回数据，状态码要返回 204，即 NO CONTENT
当 GET 不到数据时，状态码要返回 404，即 NOT FOUND
任何时候，如果请求有问题，如校验请求数据时发现错误，要返回状态码 400，即 BAD REQUEST
当 API 请求需要用户认证时，如果 request 中的认证信息不正确，要返回状态码 401，即NOT AUTHORIZED
当 API 请求需要验证用户权限时，如果当前用户无相应权限，要返回状态码 403，即FORBIDDEN

三、Header 设置
1、缓存设置
/ 示例，看情况，有些数据是允许被缓存一段时间的 /
if ($time) { // 单位：秒

header("Cache-Control: max-age=$time");
header("Date: " . date("r", time()));
header("Expires: " . date("r", time() + $time));
header("Pragma: cache");

} else {

header("Expires: " . date("r", time()));
header("Cache-Control: no-cache");
header("Pragma: no-cache");

}
2、跨域设置
/ 示例，看情况，不是所有接口都有跨域问题 /
if (isset($_SERVER['HTTP_ORIGIN']) && $_SERVER['HTTP_ORIGIN']) {

header('Access-Control-Allow-Origin: ' . $_SERVER['HTTP_ORIGIN']);
header('Access-Control-Allow-Methods: POST, GET, OPTIONS');
header('Access-Control-Allow-Credentials: true');
header('Access-Control-Allow-Headers: Content-Type');
header('Access-Control-Max-Age: 86400');

}
3、数据传输格式设置（json，推荐使用）
header('Content-Type: application/json; charset=utf-8');

四、数据校验
所有服务端接收到的参数，均需要在服务端进行校验，越严格越好，宁愿错杀，绝不放过！！
如果客户端发送的数据不正确或不合理，服务器端经过校验后直接向客户端返回400错误及相应的数据错误信息。

1、数据类型校验，最基本的判断，必不可少
如果字段类型是int，那么给字段赋「字符串」的值则报错
如果字段类型是bool，那么给字段赋 true 或 false 之外的值都报错
2、数据格式校验，特定数据，特殊判断
如邮箱或密码，其赋值必须满足相应的正则表达式，才是正确的输入数据
如日期，正则匹配或日期解析，不正确时都报错
3、数据逻辑校验，用得最多，要求也最严
如果数据包含出生日期和年龄两个字段，但是这两个字段的数据不一致，则数据校验失败
如果是当前登录人的年龄信息，但是范围不在 18~90 之间，则检验失败
如果是状态值只有 [-1,0,1] 三个状态，但是数据不在三值内，则检验失败

五、登录与权限验证
常用的认证机制是 Basic Auth 和 OAuth，API 开发中，除非 API 非常简单，且没有潜在的安全性问题，否则，认证机制是必须实现的，并应用到API中去。Basic Auth 即简单登录；OAuth 建议使用 CAS 实现单点登录机制。登录完成后，可使用 token 或 cookie 进行安全校验。

权限机制是对 API 请求更近一步的限制，只有通过认证的用户符合权限要求，才能访问API。一般是业务系统内部规划与分配权限，然后进一步的验证，关键性数据必须有严格的权限判定。

六、接口定义与数据规范
1、接口 URL 定义规则：全部统一用小写字母，多单词间以中划线「-」连接，不以「/」结尾
2、数据规范：
调用接口参数示例，注意传参字段类型，不可混淆使用。
/ 示例为搜索用户列表 /
{

"id": 1,
"username": "wang",
"nickname": "小王",
"realname": "云鹏",
"role_id": 2,
"group_id": 3,
"email": "@dxy.cn",
"phone": "136",
"status": 1,
"created_start": "2017-06-22 ",
"created_end": "2017-06-28",
"per_page": 20,
"page": 1

}
正确返回示例，数据列表必须是数组型，例如示例中的「items」。
★注意：PHP 中只有 key 为 0、1、2、… 的数组在 json_encode 时，会被转换成 json数组。
{

"code": 200,
"success": true,
"results": {
    "pager": {
        "page": 1,            # 当前是第几页
        "pages": 3,           # 总共多少页
        "per_page": 10,       # 每页多少数据
        "has_next": true,     # 是否有下一页数据
        "has_prev": false,    # 是否有前一页数据
        "total": 27           # 总共多少数据
    },
    "items": [
        {
            "id": "2",
            "username": "test",
            "nickname": "sSgysf",
            "realname": "",
            "email": "[e-mail]",
            "phone": "",
            "status": "1",
            "created": "2017-06-19 18:27:58",
            "modified": "2017-07-04 19:11:03",
            "roles": [],
            "groups": []
        },
        {
            "id": "3",
            "username": "aaa",
            "nickname": "sSgysf",
            "realname": "",
            "email": "",
            "phone": "",
            "status": "1",
            "created": "2017-06-20 14:16:58",
            "modified": "2017-06-20 18:06:02",
            "roles": [],
            "groups": []
        },
    ]
}

}
// 系统内还设置一个 per_page_max 字段，用于标记系统允许的每页最大记录数，当 per_page 值大于 per_page_max 值时，每页记录条数为 per_page_max。

错误信息返回示例
{

"code": 401,
"success": false,
"message": "id 参数错误"

}