《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头部元素了。当然，也可以手动指定版本。