对于项目的开发和维护,私以为一致性是最重要的因素之一,甚至比一段牛逼的算法更能影响一个项目的成败。
一致性之于REST API的设计,那更是关键。无需追求最优方案,但希望大家API能够保持一致。
先上例子
- Get /v1/users #获取所有用户
- Get /v1/users/1 #获取id为1的用户信息(记得返回值去掉敏感信息)
- Get /v1/users?departmentId=1 #获取部门id为1的用户
- Get /v1/users?offset=0&limit=20 #分页获取20个用户
- GET /v1/users/1/orders #获取id为1的用户拥有的订单
- POST /v1/users #新建一个用户
- PUT /v1/users/1 #修改id为1的用户信息
- DELETE /v1/users/1 #删除id为1的用户
下面列出几条建议:
永远携带版本号
REST API是永久约定,不能修改,只能新增版本,所以从开始就考虑版本问题。GET方法不允许修改数据
HTTP约定GET方法不改变状态,可以对GET请求进行缓存处理。保证PUT请求的幂等性
PUT与POST请求的差别就在于PUT是幂等的。幂等我的理解很简单,多次请求保证最多正常处理一次。
无需幂等的,用POST。文档文档文档
在公共地方(如wiki)留下文档,使得API调用者可以随时查看对应文档。url主体部分字母全部小写
paremeter部分用驼峰表示,如departmentId。