restful最佳实践

版本:
1，项目的结构一定会随着时间和需求发生变化；
2，在提供新的版本的时候，要保证老版本的路径同样可以访问；
3，在版本更新的时候，要有明确的提示给老版本用户新版本发布的消息；
4，监控老版本路径，如果确定没人使用了，再取消；
5，如果只是增加了新的API，不需要更新版本号；
6，可以通过请求头添加版本号，也可以通过 URL
添加版本号，URL 的方式更简单；
http://xxx/order/id/v2

Hypermedia Api:
RESTful API 最好做到 Hypermedia，即返回结果中提供链接，连向其他 API 方法，使得用户不查文档，也知道下一步应该做什么。
https://api.github.com/

根路径:
1，根路径对于 API 的设计非常重要；
2，一般根路径会单独提供一个二级域名，
比如：https://example.org/api/v1/* 针对大型 API；
或者：https://api.example.com/v1/* 如果 API 变化不大，或者规模较小；
3，在 API 根路径上放置好 API 文档是一个最佳实践；
4，把 API 放在 HTTPS 下是一个最佳实践；

数据过滤:
1，让查询返回的数据适量的限制（比如列表查询，一定需要做返回条数的限制）
2，常见的过滤设计：
?limit=10；限制只查询10条；
?offset=10；从第11条查询；
?animal_type_id=1；条件过滤；
?sortby=name&order=asc；排序；
3，在代码中为可以过滤或排序的列做好安全限制；

访问授权:
1，一些情况下，可以让 API 作为公开的资源访问，但是在大多数情况下，需要监控每一个请求是由谁发出的；
2，采用 OAuth2.0 来完成认证是一个最佳实践；