# **懒人帮移动端api接口**
当前版本v1
基础URL:`http://xhigh123.gicp.net`
版本基础URL:`http://xhigh123.gicp.net/v1`
加密种子字符串:`lrb123brlapi888`
该文档测试默认机器码为:`310995000000000 `
和Web应用不同，RESTful APIs 通常是无状态的， 也就意味着不应使用sessions 或 cookies， 因此每个请求应附带某种授权凭证，因为用户授权状态可能没通过sessions 或 cookies维护， 常用的做法是每个请求都发送一个秘密的access-token来认证用户， 由于access-token可以唯一识别和认证用户，
* * * * *
[TOC]
* * * * *
###1. 接口机制
* 采用RESTful API模式
* 增加了file缓存机制 默认缓存时间30秒(栏目列表 文章列表 文章详情)
* 采用自定义返回数据格式,目前支持json和xml格式 格式需要在header头信息里面指定Accept信息
~~~
Accept:application/json //xml格式为application/xml
~~~
* 采用设备唯一性标识符限制速率模式 格式需要在header头信息里面指定DeviceId信息
~~~
DeviceId:310995000000000 //设备唯一性标识符
~~~
设备限制速率模式,默认为600秒内最多100次 超过设置的速率返回对应状态码代码(429)
~~~
{
"success": false,
"data": {
"name": "Too Many Requests",
"message": "速率超过限制",
"code": 0,
"status": 429,
"type": "yii\\web\\TooManyRequestsHttpException"
}
}
~~~
* 为了防止非法程序调用接口,采用Sign签名验证方式,格式需要在header头信息里面指定Sign信息(Sign加密方式为:MD5(DeviceId+加密种子字符串))
~~~
Sign:e67ce2f83ca715552c7040c6801e020f //Sign签名
~~~
* 用户登录相关操作采用access-token 签名验证机制(签名可放在url里,也可放在header头信息里面)
~~~
http://www.url.com/v1/user/pwd?access-token=8fd8845bebee7096c6f7655c1b076ff6
~~~
~~~
access-token:8fd8845bebee7096c6f7655c1b076ff6 //用户签名
~~~
签名验证失败返回对应状态码代码(401)
~~~
{
"success": false,
"data": {
"name": "Unauthorized",
"message": "access-token是一个无效的凭证.",
"code": 0,
"status": 401,
"type": "yii\\web\\UnauthorizedHttpException"
}
}
~~~
* 在url中采用版本控制机制 目前为v1版本
~~~
http://www.url.com/v1/user v1表示v1版本
http://www.url.com/v1/user v2表示v2版本
~~~
* * * * *
## 2.完整请求headers头信息演示：
每个api请求头信息都应该包含以下信息
下面测试接口中都默认包含了此头信息
~~~
Accept:application/json //xml格式为application/xml 默认json
DeviceId:310995000000000 //设备唯一性标识符
Sign:e67ce2f83ca715552c7040c6801e020f //Sign签名
access-token:8fd8845bebee7096c6f7655c1b076ff6 //用户签名 可放入url 不存在用户登录操作则不需要该参数
~~~
* * * * *
## 3. 通用数据返回格式
返回成功：
~~~
{
"success": true,
"data": {
//相关数据
}
}
~~~
返回失败：
~~~
{
"success": false,
"data": {
"name": "错误名称",
"message": "错误信息",
"code": 0,
"status": 401, //详细状态码可在4中查看
"type": "错误类型"
}
}
~~~
* * * * *
## 4. 返回状态码
~~~
200: OK。一切正常。
201: 响应 POST 请求时成功创建一个资源。Location header 包含的URL指向新创建的资源。
204: 该请求被成功处理，响应不包含正文内容 (类似 DELETE 请求)。
304: 资源没有被修改。可以使用缓存的版本。
400: 错误的请求。可能通过用户方面的多种原因引起的，例如在请求体内有无效的JSON 数据，无效的操作参数，等等。
401: 验证失败。
403: 已经经过身份验证的用户不允许访问指定的 API 末端。
404: 所请求的资源不存在。
405: 不被允许的方法。 请检查 Allow header 允许的HTTP方法。
415: 不支持的媒体类型。 所请求的内容类型或版本号是无效的。
422: 数据验证失败 (例如，响应一个 POST 请求)。 请检查响应体内详细的错误消息。
429: 请求过多。 由于限速请求被拒绝。
500: 内部服务器错误。 这可能是由于内部程序错误引起的。
~~~
