设计 REST API的一些好文章

参考文章链接：
设计一套良好 REST API
理解OAuth 2.0
HTTP协议——->资源和URL
Web基础之使用URL访问资源
RESTful API 设计最佳实践

1. 基于业务领域的数据建模，而非基于功能建模。
示例：
取得所有的dog：GET /api/dogs
取得一个特定的dog：GET /api/dogs/{id}
取得特定名字的dogs：GET /api/dogs/?name=xxx
创建一个dog：POST /api/dogs
更改一个dog：PUT /api/dogs/{id}
删除一个dog：DELETE /api/dogs/{id}

8. Versioning 多版本

REST API的版本控制问题是一个非常有争议的话题，网上的提议有很多，在这里我们不是简单的给定具体的方法，而是提供几种可行的想法，具体的实施还需自己拿捏：
（1）不（显式）支持多版本
（2）使用Http Accept Header

第一种，什么都不做，不支持多版本的api。这个想法的背后依据是，根据调研发现，大多数的中小型规模的平台服务，客户规模都在一个可控的范围，api的升级不会很频繁，你只需通知你的客户，在某个时间点api会更新，然后再server端做一些兼容性的数据迁移，比如增加或删除某个数据库中的表的某个列的名字。大多数情况下，支持多版本api费力不讨好，测试和部署的成本很大，收益却很小。你要做就是保持唯一个可用api服务的兼容性，而不是提供多个版本的api让用户使用。

第二种，如果你一定要支持versioning，那么就在http的accept header中添加version信息，不要在url中使用version信息，千万不要用/api/v1/xxx。