REST API设计参考

对于项目的开发和维护，私以为一致性是最重要的因素之一，甚至比一段牛逼的算法更能影响一个项目的成败。
一致性之于REST API的设计，那更是关键。无需追求最优方案，但希望大家API能够保持一致。

先上例子

1. Get /v1/users #获取所有用户
2. Get /v1/users/1 #获取id为1的用户信息(记得返回值去掉敏感信息)
3. Get /v1/users?departmentId=1 #获取部门id为1的用户
4. Get /v1/users?offset=0&limit=20 #分页获取20个用户
5. GET /v1/users/1/orders #获取id为1的用户拥有的订单
6. POST /v1/users #新建一个用户
7. PUT /v1/users/1 #修改id为1的用户信息
8. DELETE /v1/users/1 #删除id为1的用户

下面列出几条建议：

1. 永远携带版本号
   REST API是永久约定，不能修改，只能新增版本，所以从开始就考虑版本问题。

2. GET方法不允许修改数据
   HTTP约定GET方法不改变状态，可以对GET请求进行缓存处理。

3. 保证PUT请求的幂等性
   PUT与POST请求的差别就在于PUT是幂等的。幂等我的理解很简单，多次请求保证最多正常处理一次。
   无需幂等的，用POST。

4. 文档文档文档
   在公共地方(如wiki)留下文档，使得API调用者可以随时查看对应文档。

5. url主体部分字母全部小写
   paremeter部分用驼峰表示，如departmentId。