RESTful RESTful的命名有什么讲究？

Question

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
比如以上3个API （RESTful API 设计指南 by 阮一峰）
1. 这个URL和服务器里的文件夹有关系么？是否网站根目录下需要有v1这个文件夹？
2. GET /zoos/ID 和 GET ID/zoos 两种实现在效果上有区别么？ 推荐前者的原因是什么？
谢谢！

Answer 1

RESTful 只是一种API的设计风格，当然我现在这么说，你可能还没有理解里面的含义，需要做过一些项目后，回头再想想，可能就有同感了。

既然是设计风格，那么你看到的许多这样文章，比如你提到的 “RESTful API 设计指南” 等等，网络上还很多前辈总结出来的最佳实践。也就是说 如何设计URI是没有官方标准的，当然，这不意味着就可以乱来。

REST 提倡面向资源地设计API，当然为了更好地体现语义化（易于理解）、统一规范（同样为了易于接受和理解）、以及表现资源的层级关系、资源与资源之间的关系等等，那么URI的设计应该就要有所讲究了。

那么，是否非要在URI上加上版本号v1、v2，或者说非要这样设计API GET /zoos/ID而不是这样设计GET ID/zoos。没有任何硬性的要求。这些都是从前辈们从长期和大量的设计中总结出来的经验。它的好处需要在你实践中，会慢慢地领悟。

我给的建议就是，如果能够按照 “设计指南”或“最佳实践”等等来做的，那尽量这样做。如果做不到的，没关系，自己以自己认为最为合适的方式实现就好了（大不了，回头改）。不过，千万不要被这些东西给教条化了。

REST的API，我看过一些国外和国内比较知名的网站的设计，大体上都差不多，应用场景不同，都会存在一些区别。这个可以自己对比一下，先看看别人的设计。

实际上，作为开发者，最关系的是你提供的API，用起来是否非常爽，易用等等。所以设计API的时候就要考虑资源粒度等等，不过刚开始写REST API，前期没有必要太关注这些了，这些问题会在你的实践中，慢慢会碰到。

最后，这里有一些自己认为比较好，有关于REST API设计的文章，收集在Github上面了，喜欢的可以看看，会对你有好处的。https://github.com/aisuhua/restful-api-design-references

Answer 2

/图书馆/书籍编号

/书籍编号/书名

restful只是为了实现更便于理解URL做的总结，

并没有具体的要求，你开心就好，

当然最好让用得到你的URL的人（协作的同事）也开心。

Answer 3

1，上面的v1应该是版本号，现在有的会推荐restful风格的url里带版本号，因为其本身一般用来做http风格的api，带上版本号可以保证旧版兼容性。
2，上面准确来说还是有区别的，因为rest风格就是对资源的定位，zoos/ID就是表示zoos资源集合下的ID资源，如果反过来就不好理解了。作为API，一定要便于理解。