Restful API设计规范
前言
在尝试正式进行api文档编辑的过程当中，意图通过之前在写代码过程当中所积累到的接口设计经验编写一个高效清晰的api接口，但是若不经过一个api规范知识的摄取过程，效果可能不够好。在这里阅读了几份比较好的有关RestfulAPI的接口设计，结合自己的经验和风格，作出一些总结。
HTTP方法规范
查询数据使用
get，创建数据使用post，更新数据使用put。
但是往往在实际的工程当中使用put方法的比较少，建议以?method=put方式使用
如:
1 | POST /v1/users/<id> //创建用户 |
资源规范
资源命名的时候需要是名词并且采用复数（尽管资源可能只有一个）
如：
1 | /vi/users //获取用户信息集合 |
获取单个用户信息数据
1 | /v1/users/<id> |
在此过程当中url资源可能会层级很高，如：/v1/1/2/
此时可以转换为别的方式查询
如
1 | /v1/users/?id=200121228 |
请求头规范
Content-Type: application/json
采用json进行传输，不采用application/x-www-form-urlencoded、multipart/form-data
API 返回的数据格式，不应该是纯文本，而应该是一个 JSON 对象，因为这样才能返回标准的结构化数据。所以，服务器回应的 HTTP 头的Content-Type属性要设为application/json。
客户端请求时，也要明确告诉服务器，可以接受 JSON 格式，即请求的 HTTP 头的ACCEPT属性也要设成application/json。
API规范与鉴权机制
在前后端分离项目实际的接口鉴权当中，会遇到跨域的用户鉴权问题，一般通常采用以下两种方式
- Token机制
- cookie机制
- cookie机制
cookie机制一般的流程为
1、用户向服务器发送用户名和密码。
2、服务器验证通过后，在当前对话（session）里面保存相关数据，比如用户角色、登录时间等等。
3、服务器向用户返回一个 session_id，写入用户的 Cookie。
4、用户随后的每一次请求，都会通过 Cookie，将 session_id 传回服务器。
5、服务器收到 session_id，找到前期保存的数据，由此得知用户的身份。
但这样显然服务器的扩展性不好，单机当然没有问题，如果是服务器集群，或者是跨域的服务导向架构，就要求 session 数据共享，每台服务器都能够读取 session。
服务器保持无状态扩展性会更好
因此token就出现了
在这里引入Restful Api的JWT机制
简要概括就是在params（参数）处添加一个参数token，
token服务器保存一份，通常第一次请求服务器（登录）的时候产生，返回给客户端
因此客户端在后续的请求当中都需要携带上token，
1 | /v1/users?token=***** |
用于服务器校验
token可视为令牌，服务器里面蕴含了用户信息
每次请求的时候带上token，token里面也应该蕴含过期时间信息。
其他
- 版本信息
版本信息可以蕴含在api接口中，如
1 | /v1/users |
参考
【2】JWT机制