RESTfulAPI定义及使用规范
RESTfulAPI定义及使⽤规范
RESTful API定义及使⽤规范
知⾜，感恩，乐观，进取，克制，豁达
⾸发于
RESTful本⾝是⼀种风格⽽不是规范，本⽂为该风格的规范实现的最佳实践，本⽂档详细说明了HTTP RESTful API的定义和使⽤规范，作为接⼝调⽤者和实现者的重要参考。
接⼝风格
遵循RESTful设计风格，同时控制复杂度及易于使⽤，仅遵循⼤部分原则。遵循原则：
使⽤https协议
版本号放⼊URL
只提供json返回格式
post,put上使⽤json作为输⼊
使⽤http状态码作为错误提⽰
Path（路径）尽量使⽤名词，不使⽤动词，把每个URL看成⼀个资源
使⽤HTTP动词（GET,POST,PUT,DELETE）作为action操作URL资源
过滤信息
limit：指定返回记录数量
offset：记录开始位置
direction：请求数据的⽅向，取值prev-上⼀页数据；next-下⼀页数据
page：第⼏页
per_page：每页条数
total_count：总记录数
total_pages：总页数，等于page时，表⽰当前是最后⼀页
sort：column1,column2排序字段
orderby：排序规则，desc或asc
q：搜索关键字（uri encode之后的）
返回结果
GET：返回资源对象
POST：返回新⽣成的资源对象
PUT：返回完整的资源对象
DELETE：返回⼀个空⽂档
速率限制
X-RateLimit-Limit: 每个IP每个时间窗⼝最⼤请求数
X-RateLimit-Remaining: 当前时间窗⼝剩余请求数
X-RateLimit-Reset: 下次更新时间窗⼝的时间（UNIX时间戳），达到下个时间窗⼝时，Remaining恢复为Limit
未遵循原则：
Hypermedia API（HATEOAS），通过接⼝URL获取接⼝地址及帮助⽂档地址信息
限制返回值的域，fields=id,subject,customer_name
缓存，使⽤ETag和Last-Modified
参考：
模块和版本说明
接⼝模块相互对⽴且有版本管理，模块名作为APP配置项进⾏存储，每个模块的版本号version和endpoint在应⽤初始化时调⽤api模块信息接⼝（通过传递客户端应⽤名称和版本号获取各个API模块的endpoint和version）获取并存储。
⽰例模块及最新版本号：
公共参数
Headers
公共请求参数是指每个接⼝都可能需要传递的参数，公共参数通过header传递。
Web应⽤通过cookies传递session id，user_id和token⽆需传递，接⼝会从session⾃动获取；
同⼀token值在App和Web各应⽤间通⽤（token即为session id）；
APP修改user-agent，在原有user-agent的尾部添加$app/$version和NetType/$value。如：
Dalvik/2.1.0 (Linux; U; Android 6.0.1; MI 4LTE MIUI/V7.5.3.0.MXGCNDE) $app-android/3.0.0 NetType/4G
Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_2 like Mac OS X) AppleWebKit/603.2.4 (KHTML, like Gecko) $app-ios/3.0.0 NetType/WIFI app取值及释义⽰例
Cookies
⽤于告知服务端是否⽀持Webp的Cookie：cookie name是supportWebp，取值是1（⽀持）和0（不⽀持），未传递时服务端默认取值为0。
Webview植⼊Session的Cookie：
JWT
连接apple id服务器时出错可⽤于替代session-cookie机制。但会存在⼀些问题，⽐如为过期token强制失效问题（⽤户修改了密码后，⽆法强制其他的终端token 全部失效）。
权限
权限分为
none：⽆需任何授权；
token：需要⽤户登录授权，可通过header Authorization和Cookie CoSID传递；
admintoken：需要管理员登录授权，可通过header Authorization和Cookie CoCPSID传递；
token || admintoken：⽤户登录授权或管理员登录授权都可以；
sign：需要签名，⼀般⽤于服务端内部相互调⽤，详见。
状态码说明
正确
接⼝正常访问情况下，服务器返回2××的HTTP状态码。
错误
当⽤户访问接⼝出错时，服务器会返回给⼀个合适的4××或者5××的HTTP状态码；以及⼀个application/json格式的消息体，消息体中包含错误码code和错误说明message。
5××错误(500=<status code)为服务器或程序出错，客户端只需要提⽰“服务异常，请稍后重试”即可，该类错误不在每个接⼝中列出。
4××错误(400=<status code<500)为客户端的请求错误，需要根据具体的code做相应的提⽰和逻辑处理，message仅供开发时参考，不建议作为⽤户提⽰。
部分错误⽰例：
参数传递
遵循RESTful规范，使⽤了GET, POST, PUT, DELETE共4种请求⽅法。
1. GET：请求资源，返回资源对象
2. POST：新建资源，返回新⽣成的资源对象
3. PUT：新建/更新资源，返回完整的资源对象
4. DELETE：删除资源，返回body为空
GET请求不允许有body，所有参数通过拼接在URL之后传递，所有的请求参数都要进⾏遵循的URL Encode。
DELETE删除单个资源时，资源标识通过path传递，批量删除时，通过在body中传递JSON。
POST, PUT请求，所有参数通过JSON传递，可选的请求参数，只传有值的，⽆值的不要传递，contentType为application/json。
4种请求动作中，GET、PUT、DELETE是幂等的；只有POST是⾮幂等的。幂等操作的特点是其任意多
次执⾏所产⽣的影响均与⼀次执⾏的影响相同。是⾮幂等是判断接⼝使⽤POST还是PUT的决定条件
注意： APP端获取json数据时，对于数值类型字段必须以数值类型转换，⽆论传递过来的值是否带引号。
速率限制Rate Limiting
为了防⽌API被恶意调⽤，对API调⽤进⾏速率限制。
速率限制为每IP每15分钟5000次（dev/qa为10W）调⽤（15分钟是⼀个时间窗⼝）。
限制是针对孩宝所有接⼝模块⼀起计算的（Redis key为APIRL:{IP}），暂时没有特殊的模块或单个接⼝（未来可能有）。
你可以通过每个接⼝返回的HTTP headers了解当前速率限制的情况:
X-RateLimit-Limit: 每个IP每个时间窗⼝最⼤请求数
X-RateLimit-Remaining: 当前时间窗⼝剩余请求数
X-RateLimit-Reset: 下次更新时间窗⼝的时间（UNIX时间戳），达到下个时间窗⼝时，Remaining恢复
为Limit 超出速率限制，返回以下错误
安全注意事项
⽤户登录后⽤户的token；aliyun OSS的bucket、AccessKey ID与AccessKey secret；微视频的appid、sign、bucket；这些关键数据通过调⽤接⼝获得，需要在客户端以安全的⽅式存储。
⾳频视频在APP内的存储，不允许被拷贝（即使越狱或root后拿⾛也⽆法使⽤）。
测试⼯具
推荐Chrome浏览器插件Postman作为接⼝测试⼯具，
⽂档⽣成⼯具
⽣成的⼯具为apidoc，详细阅读官⽅⽂档：
调⽤⽰例
伪代码
PHP
API模块信息获取
App配置⽂件中仅存储api模块名，App初始化时请求，获取各个api模块的信息（endpoint和version）。
编辑于 2017-11-22
REST
API

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。