实际上就是用RESTful风格来包装HTTP协议，并用json或xml格式实现数据交互。
RESTful风格: 网络资源实体化，CURD对资源进行操作。
好的规范评判标准：直观、扩展、优雅
1.数据交互格式
推荐json, 紧凑、易于读写、占用带宽小、各种编程语言支持。以下均已json格式为例。
HTTP 请求头:
## 客户端接受数据类型，服务端根据Accept字段调整返回消息的数据格式
Accept:application/json; charset=UTF-8 # >>>推荐
# 或 :application/xml; charset=UTF-8 # xml
# 或 :application/json,application/xml; charset=UTF-8 # xml或者json
## 客户端发送数据类型
Content-Type:application/json; charset=UTF-8 # >>>推荐
# 或 :application/x-www-form-urlencoded; charset=UTF-8 # 不推荐
# 或 :multipart/form-data; charset=UTF-8 # >>>推荐用于上传文件
# 或 :application/xml; charset=UTF-8 # xml
HTTP 消息头:
## 服务端端返回消息数据类型
Content-Type:application/json; charset=UTF-8 # >>>推荐
# 或 :application/xml; charset=UTF-8 # xml
2.授权认证
由于HTTP是无状态协议，所以客户端需要携带一串经过加密的不易重复的密码串来追踪用户。web中的session机制，OAuth2.0中的tooken。
比如：md5 36^32=6.3＋E49 100亿用户重复的概率是亿亿亿亿分之一
2.1 针对web客户端设计
由于web应用开发已经有成熟的用户追踪解决方案，即Session-Cookie，API设计可以延用这一方案。当客户端请求Session不存在或过期的时候，接口返回响应错误码要求用户登陆；客户端登陆成功后把session ID和其他用户信息放在Cookie里，客户端再次请求时携带该信息。
HTTP 消息头:
Cookie:sessionId=39rkgbkm2qqt0k9d9qmnr68difn9bs9q;userId=1;userRole=admin; # "sessionId"键名可以由服务端自定义
HTTP 请求头:
Cookie:sessionId=39rkgbkm2qqt0k9d9qmnr68difn9bs9q;userId=1;userRole=admin; # "sessionId"键名可以由服务端自定义
2.2 针对纯API客户端设计
客户端不是浏览器时或客户端不支持Cookie时，另起一个头字段“User”，当然可以是其他字段甚至可以是“Cookie”，纯粹习惯问题。客户端获取数居前需要解析下这个请求头字段（浏览器会自动解析Cookie字段）。
HTTP 消息头:
User:token=39rkgbkm2qqt0k9d9qmnr68difn9bs9q;userId=1;userRole=admin; # "token"键名可以由服务端自定义
HTTP 请求头:
User:token=39rkgbkm2qqt0k9d9qmnr68difn9bs9q;userId=1;userRole=admin; # "token"键名可以由服务端自定义
2.3 通用型
如果以上2.1和2.2两种情况都用“Cookie”头字段，省事了没有这一步；2.2用“User”的话就需要做个判断处理。
2.4 个人推荐
User:tooken=39rkgbkm2qqt0k9d9qmnr68difn9bs9q;userId=1;userRole=admin;
3.API命名
API指的是服务端的资源实体，它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。所以API名称一定是名称，通常以复数居多，对应数据库中的一张表，比如“users、goods、orders”。“转账”就可以当作一种服务:
GET http://.../transfer?from=a&to=b&amount=100。
递进从属关系表达,如：
http://.../orders/1/goods/1,表示订单ID为1的订单下面商品ID为1的商品。
3.请求
一次请求就是对服务的资源的一次操作，操作即增、删、改、查，对应HTTP四种请求方法：GET(查)、POST(增)、PUT(改)、DELETE(删)。
另有PATCH(打补丁)方法，指局部跟新，PUT指全量更新；但一般PUT当全量更新用，而PATCH方法不用。
还有OPTIONS方法，是对该接口参数和功能的说明，类似于命令行中的"--help",建议使用。
## 建议在消息头说明
Allow:GET, POST, PUT, DELETE, OPTIONS
3.1 CURD举例
GET http://.../goods # 列表 ?page=1&page_size=10&order_by=price&desc=1&filters={"price":{"min":10,"max":20}}
GET http://.../goods/1 # 详情
POST http://.../goods # 新增 -d '{"name":"番茄","price":"3.00"}'
POST http://.../goods # 批量新增 -d '[{"name":"番茄","price":"3.00"}, ...]'
PUT http://.../goods/1 # 更新 -d '{"name":"番茄","price":"3.50"}'
PUT http://.../goods # 批量更新 -d '[{"id":1,name":"番茄","price":"3.00"}, ...]'
DELETE http://.../goods/1 # 删除
DELETE http://.../goods/1,2 # 批量删除
3.2 辅助参数
某种特殊情况下，需要对接口行为作出调节，需要客户端额外的传参；为了防止冲突，这种参数通常以"_"开头。比如深度链接唤起应用、分享链接
# 模拟请求方法
_method=GET/POST/PUT/DELETE
# 标记码
_token=39rkgbkm2qqt0k9d9qmnr68difn9bs9q
# 防止跨域攻击标记码
_CSRF_token=39rkgbkm2qqt0k9d9qmnr68difn9bs9q
# 格式化输出
_format=json
4.消息体
标准的消息体由三个部分组成：
{
"code":200, // 状态码，参考http状态码，建议二者保持一致, 见[6.错误码]
"msg":"SUCCESS", // 简短消息，可供客户端直接打印输出
"data":{}, // 数据包
}
4.1 列表
GET http://.../goods
{
"code":200,
"msg":"SUCCESS",
"data":{
"list":[{...}, {...}],
"count":12,
"page":1,
"page_size":10
},
}
4.2 详情
GET http://.../goods/1
{
"code":200,
"msg":"SUCCESS",
"data":{
"detail":{"name":"番茄","price":"3.50"},
"comments":[{"rank:5, "content":"五星好评"},{...}]
},
}
4.3 POST或PUT验证失败
POST http://.../goods -d '{"name":"番茄","price":"3.50"}'
{
"code":406,
"msg":"验证失败, 请检查是否按要求提交数据",
"data":{
"raw":{"name":"番茄","price":"3.50元"}, // 建议返回客户端
"errors":[{"price":["请输入数字类型"]}]
},
}
5.文件上传与下载
上传文件 HTTP 请求头:
Content-Type:multipart/form-data
下载文件 HTTP 请求头:
Content-Type:参见http://www.runoob.com/http/http-content-type.html
6.错误码
200 OK # 成功处理
400 Bad Request # 客户端请求有语法错误，例如Content-Type与请求体不符或请求体无法解析
401 Unauthorized # 请求未经授权，例如需要登陆
403 Forbidden # 禁止操作该资源，例如权限不够等
404 Not Found # 请求资源不存在
405 Method Not Allowed # 方法未允许
406 Not Acceptable # 不可接受，未通过验证，不符合要求
408 Request Timeout # 请求超时
500 Internal Server Error # 服务器发生不可预期的错误
503 Server Unavailable # 服务器当前不可用，一段时间后可能恢复正常，例如并发问题
