REST API版本控制的三种方式

一、背景

在多版本同时运行的场景下（APP），会存在不同版本的接口，同时新版本也需要向下兼容，那么就需要客户端传递版本号信息

二、Version版本传递的方式

2.1 版本信息放在Path或RequestParam中

api.example.com/v3
api_v3.example.com
api.example.com/xxx?version=v3

优点：版本号清晰

缺点：版本号侵入了url中，业务无关的参数应该放在请求头中

2.2 在请求头中传递

Accept-version：v1
Accept-version：v2

优点：不侵入业务参数，在gateway或者灰度发布中传递更加方便

2.3 内容协商（Content negotiation）

Accept: application/vnd.example-com.foo+json;version=1.0

优点：在header之上支持协议转换，支持json、xml响应类型

缺点：需要在gateway层做协议转换

参考

[1] Versioning REST Service

[2] Best practices for API versioning?