Ruily blog

more reading more happiness

Ruily Zhu's avatar Ruily Zhu

RESTful之API版本控制

在日常移动端开发中,随着业务需求的不断变化,我们的接口返回的数据就会有各种变动,但由于native语言开发的应用无法动态更新api,在修改接口返回数据改变接口逻辑的同时还要确保旧版本的兼容,因此就用到了接下来要说的API版本控制。

RESTful架构

RESTful全称Representational State Transfer,其架构特性为

  1. 每个url代表某种资源
  2. 资源通过特定的形式展现例如json
  3. 使用http协议的get、post、delete、put等操作服务器资源

想要具体了解参考理解RESTful架构


版本控制方式

  1. 强制使用统一API版本

    整个项目使用一个API版本,不考虑兼容性,缺点

  2. URI中显式添加版本号

    把版本号嵌入到API中,例如developer.github.com/v3/media/,
    访问操作对应版本号下的资源。这种显示的表示版本号的好处是可以很直观的
    展示当前api版本号。缺点是违背RESTful架构的原则,理论上一个URI对应服
    务器一个特定的资源,添加版本号则会混淆版本和资源的概念,而且会让整个
    架构变得混乱,增加日后维护的成本。 还有一种是把版本号作为参数请求api
    获取操作对应版本号的资源,例如www.demo.com/list?version=2。

  3. 添加头信息控制版本

    在API请求header中添加Accept字段。
    Accept的作用是客户端指出响应可以接受的媒体类型
    如Accept:application/json; version=v2
    具体格式也可以参考下面。

    1
    Accept: application/vnd.xxxx[.version].param[+json]

    例如Accept: application/vnd.demo.app-v2+json
    优点:遵循了REST的原则
    缺点:不够直观

总结

通过上述简单的分析,每种版本控制都有不同的优缺点,我们可以选择合适自己的版本控制方式,个人认为小版本的更新可通过把版本号作为参数的方式或者通过accept字段标示版本号的方式判断,大的版本更新则通过URL上添加版本号控制

API Versioning

Media Types

Versioning with REST framework