API开发的版本控制技巧-阿里云开发者社区

开发者社区> 开发与运维> 正文
登录阅读全文

API开发的版本控制技巧

简介: 《API开发的版本控制技巧》 在设计和构建API时,API的版本控制是非常重要的。 必须确保新API对于现有的API不会造成破坏。 首先,也是最重要的,可以把版本号放入API的URL中。

《API开发的版本控制技巧》

在设计和构建API时,API的版本控制是非常重要的。
必须确保新API对于现有的API不会造成破坏。
首先,也是最重要的,可以把版本号放入API的URL中。这样可以把主要版本更新放入API。比如,我们在调用CHUser Center API时,可以在URL中使用/api-v1或/api-v2来指出所使用的API版本。这是很常见的做法。

在API版本控制中,还有一点也很重要。希望API能支持次要版本的更新。次要版本更新所造成的变化仍然会影响接口,因此有可能会影响当前API的使用者,但它们与主版本的URL和API的基本功能都在变化不同,URL和API基本功能仍然是相同的。比如在CHUser Center API,次要版本的修改是通过客户在API调用时发起请求的HTTP头部做指定的。
头部的版本元素看起来是这样的:
Element-Version: 1

再举一个API次要版本更新的例子,如果我们想修改响应的JSON字段的名称。假设我们有一个名为GET /people的API调用,它会返回以下JSON数据:

{
  “firstN”: “foo”
}

我们决定把JSON字段中的firstN改成firstName。很显然,这只是一个小改动,所以它属于API次要版本更新的范畴,无须做主版本的修改和不同的URL签名。因此,我们会创建另一个GET /people接口,要调用它还需要在HTTP头部加上
Element-Version: 2
然后就会返回以下JSON数据:

{
  “firstName”: “foo”
}

在CHUser Center API中,当一个新用户注册后,我们会设置此用户的HTTP头部默认为CHUser Center上最新的Elements-Version版本。这可以保证新用户总是使用我们提供的最新API服务,这样就无须在每次API调用时指定任何HTTP头部元素了。当然,也可以手动指定版本。

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
开发与运维
使用钉钉扫一扫加入圈子
+ 订阅

集结各类场景实战经验,助你开发运维畅行无忧

其他文章
最新文章
相关文章