${$defaultVersion := $.Config.api.defaultVersion}
- 本文供前端开发工程师使用
- 接口请求地址统一格式为:
${.Config.api.protocol}://${.request.Host}/api/v1/user/get
其中:
v
: 版本号,非必填,如:v1 , 默认为${$defaultVersion}
m
: 调用的接口模块,如:user
a
: 调用的接口方法,如:get
- 支持的请求动作有
GET
/POST
/GET,POST
等三种情况
- 认证,接口需要用户登录认证授权,流程如下:
- 用户通过接口登录,获取Token,Token是用户唯一标识,每次登陆Token都会不一样
- 对于需要认证授权的接口,通过参数token进行授权认证
- 签名,接口需要安全签名验证,以防传输数据过程中被篡改,流程如下:
- 向服务接口索取appkey和secretkey,两者是一对一的关系。
- 对需要签名的接口添加参数 t(时间戳,自 1970 年 1 月 1 日(08:00:00 GMT)至当前时间的总秒数,也被称为 Unix 时间戳)以及appkey,t 被用作请求有效时间,默认为600秒。
- 对所有传输参数(
'sign','appkey','token'
以及注明排除的例外)的参数字典升序排列。
- 将以上排序后的参数表进行字符串连接,如key1=value1&key2=value2&key3=value3...keyN=valueN;记作params
- secretkey作为后缀,对该字符串进行md5计算,并转换成小写,截取前8位,如:sign=toLowerCase(md5(params+secretkey)).substring(0,8)
- 对于需要签名验证的接口,通过参数sign进行签名验证
php加密算法
public function encrypt($data,$appSecure)
{
//排序
ksort($data);
//拼接
$params = http_build_query($data);
//md5加密
$sign = md5($params.$appSecure);
//转小写
$sign=strtolower($sign);
//截取前8位
return substr($sign,0,8);
}
- 返回格式仅支持json格式,下面是几个完整的json示例:
{
"code": 200,
"data": {
"title": "Default Api",
"content": "PHPer您好,欢迎使用PhalApi!",
"version": "1.1.0",
"time": 1423142802
},
"msg": ""
}
{"code":200,"msg":"success","data":null}
{"code":500,"msg":"请传入xx字段","data":""}
{"code":501,"msg":"登陆错误","data":""}
{"code":200,"msg":"success","data":[]}
{"code":200,"msg":"success","data":[{a:1,b:2},{a:3,b:4}]}
其中返回的字段:
-
code:整数,状态码。其中200表示成功(http协议状态码为200);其他非200,如500,表示出现错误(http协议状态码为500)
状态码描述
- 1xx 应用自定义错误
-
2XX 成功
- 200: OK。一切正常。(正常用这个即可)
- 201: 响应 POST 请求时成功创建一个资源。Location header 包含的URL指向新创建的资源。
- 202: 已接受用于处理,但处理尚未完成。
- 203: 部分信息 — 返回的信息只是一部分。
- 204: 该请求被成功处理,响应不包含正文内容 (类似 DELETE 请求)。
-
3XX 重定向,接口修改时适用
- 304: 资源没有被修改。可以使用缓存的版本。
- 302: 请求的数据临时具有不同 URI。
- 306: 不再使用,保留此代码以便将来使用。
- 4XX 客户机中出现的错误,影响服务器处理
- 400: 错误的请求。可能通过用户方面的多种原因引起的,例如在请求体内有无效的JSON 数据,无效的操作参数,等等。
- 401: 验证失败。
- 403: 已经经过身份验证的用户不允许访问指定的 API 末端。
- 404: 所请求的资源不存在。
- 405: 不被允许的方法。 请检查 Allow header 允许的HTTP方法。
- 415: 不支持的媒体类型。 所请求的内容类型或版本号是无效的。
- 422: 数据验证失败 (例如,响应一个 POST 请求)。 请检查响应体内详细的错误消息。
- 429: 请求过多。 由于限速请求被拒绝。
- 5XX 服务器中出现的错误
- 500: 内部服务器错误。 这可能是由于内部程序错误引起的。
- 501: 请求还没有被实现。比如说,我们请求一个接口来自动拒绝项目经理的要求,但是这个接口只是美好的想象,并没有被实现,这时候可以返回 501。
- 502: 网关错误。比如说,我们向服务器 A 请求下载葫芦娃,但是 A 其实只是一个代理服务器,他得向 B 请求葫芦娃,但是不知道为啥 B 不理他或者给他错误,这时候哦可以 A 返回 502 用来表示 B 这家伙傲娇了。
- 503: 服务暂时不可用。比如说,服务器正好在更新代码重启。
- 504:网关超时,类似 502,但是这时候是 B 不理 A,超时了 。
- 505:HTTP 版本不受支持,服务器不支持请求中所使用的 HTTP 协议版本。
- msg:字符串,返回的提示消息
- data:返回的具体数据