api规范PHP,[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": "vXfxM@qq.com",

"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 参数错误"

}