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

[ericgui]

http://www.ruanyifeng.com/blog/2011/09/restful 阮一峰认为，版本号应该放在 HTTP 请求头中

https://juejin.im/post/59826a4e518825359c5e72d1 这个认为，API 版本号应该区分

而且 github API，也是 URI 中带有版本号的，难道说 github 的 API 设计的不好？

所以我怀疑 阮一峰这个问题上搞错了。

能分享一些实际的设计 API 的经验吗？谢谢

[acoldfox]

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

[cuebyte]

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

[gigantic222]

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

[sampeng]

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

[danielmiao]

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

[lslqtz]

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

[leky]

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

[xiaozizayang]

我一般加路由里面

[Kilerd]

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

[jarlyyn]

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

[dracarysX]

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

[lightening]

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

[jameshuazhou]

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

[sunjourney]

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

[janxin]

放头里最好有 api 网关

[mikulch]

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

[lrh3321]

放在 url 里+1

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

[changwei]

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

[geelaw]

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

[sobigfish]

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