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

[ericgui]

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

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

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

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

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

[zhoulouzi]

uri 就不是请求头了吗

[qiyuey]

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

[ETiV]

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

[libook]

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

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

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

[zhangmiaoCHN]

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

[ericgui]

@qiyuey V3 和 V4 共存，都能用

[ericgui]

@zhangmiaoCHN V3 和 V4 共存，都能用

[qiyuey]

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

[ericgui]

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

[derrickT]

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