RESTful API 设计，到底加不加 版本号？

觉得这个各说纷纭，到最后是怎么方便怎么来了，我是在 url 中保留版本号的，比如 v1，v2 是独立的模块，如果版本改动太多，就另起一个新 module 跟以前的区分开，互不干扰

也不尽然是方不方便的问题，在后端的设计里，URL 本身就是和 controller 挂钩的，而不同版本需要不同的 controller。所以把版本号放在 URL 里是很自然的一件事。况且也更直观。

原理都一样啊本质上没区别 可能时常需要 simple request 限制 header 吧

我一般扔 header 里面。干净一点

习惯放在 url 上
1.调用直观，写文档方便
2.不同版本的相同功能接口，可以在不同的包中使用相同的 url，便于代码管理（ maven 版本和 url 版本关联）。
3.不同版本接口可以分开部署，平滑升级，通过 nginx 简单规则匹配就分派到不同的服务器上。

不加
等改动的时候加，丢 header 比较麻烦

如果返回数据结构一样，个人觉得版本号在 header 会比较方便，客户端都不用改 api url，其它的倒是没什么可说的

我一般加路由里面

无论是对前后端来说，怎样都是一两个语句的事情。
这个真的是怎么方便怎么来

放在 url 里。
说请求头的，难道现在 url 不是请求头了么？
另外， 我不是很喜欢很纯粹的 restful 接口。

基本就是请求头和 url 两种方案比较流行。
不过个人感觉大多数的 API 设计都是 url 这种方案（很多大厂都是这种），这种设计更加直观，清晰。从开发方面看也是比较舒服的，不需要一直去判断请求头的版本去寻找处理函数。
ps：阮一峰也不一定都是对的。

这只是 opinion，有什么对错之分么

两种方式都用过，放 url 中别人更不会犯错，而且放请求头中有些木有经验的还得教他怎么做。
理论上放头中更漂亮些，但实际中还是放 url 省心些。

放 url 里 get 请求是可以缓存的， 阮老师的文章里错误不少或者在转达别人的观点因此有时候会有讲同一个内容的观点矛盾。

放头里最好有 api 网关

要。推荐楼主看看《 web api 的设计与开发》这本书。

放在 url 里+1

老版的 API 可能和新版的跑在不同的 server 上

看了好多大厂，比如说百度，知乎之类的网站都是版本号放 url 中，这样的话测试或者发起请求都更方便，程序里面不需要额外调用各种修改请求头的 api。

如果你把 URL 看作对象的 view，就很好理解版本号放在 URL 里面的想法。这相当于是张三还是李四来看这个对象，是老人还是年轻人看这个对象的问题。

放 uri 里是为了兼容性，放 header 里貌似还不好分析跟踪-。-

uri 就不是请求头了吗

github 不是已经不再使用 restful api 了吗

放头里要多几个字节（ x-api-version 这样），所以不放。

哪个方便用哪个，看你的架构是什么样的，以及 API 版本差异特点。

版本区分仅限于个别 API 的话就加在 Header 里；
版本区分是普遍的、整体的，就写在 URI 里；
如果版本差异巨大，以至于使用完全不同的服务和集群，就写在域名里。

通常不是做 SaaS 的话 API 版本的维护要求不是特别严格吧，所以也没必要做的冠冕堂皇，我们是每年出 1-2 个大版本，同时维护的版本只有 1-2 个，前端强制升级旧版本会直接抛弃，所以直接用域名区分了，简单有效，而且对云计算服务友好。

Facebook 的码农之前也纠结过这个问题，后来搞了一个 GraphQL 试图改善 RESTful API 的局限
现在 Github API v4 版本已经不再使用 RESTful API 了，改用 GraphQL 去构建 API
https://developer.github.com/v4/

@qiyuey V3 和 V4 共存，都能用

@zhangmiaoCHN V3 和 V4 共存，都能用

@ericgui 我的意思是，是不是你也该放弃 rest 了

@qiyuey RRES API 还是有很多人在用，哪能说不用就不用呢？

1. 在 header 里加 version
2. 在请求里加 version
3. 在 nginx 里根据 version 转发到对应的版本