一步一步演进RESTful API版本 - frankel


设计一个直观、用户友好的 RESTful API 是一项艰巨的工作。如果这是您的第一次尝试,这可能已经是一项艰巨的任务。规划 API 的生命周期管理可能是事后才想到的。但无论如何都是有可能的:在这篇文章中,我想提出一种严肃的方法来发展你的 API,即使它没有计划。
 
让我们假设一个在使用时说“Hello”的示例应用程序:

> curl http://org.apisix/hello
Hello world

> curl http://org.apisix/hello/Joe
Hello Joe

 
使用 API 网关
第一步也是最关键的一步是停止将应用程序直接暴露在互联网上,并在它们之间建立一个 API 网关。
 
版本化 API
演进 API 意味着 API 的多个版本需要在某个时候共存。
三种方法:

curl http://org.apisix/hello?version=1
curl http://org.apisix/hello?version=2
 
curl -H 'Version: 1' http://org.apisix/hello
curl -H 'Version: 2' http://org.apisix/hello
 
curl http://org.apisix/v1/hello
curl http://org.apisix/v2/hello

在这个阶段,我们已经配置了两条路由,一条是版本化的,另一条是非版本化的:
> curl http://org.apisix/hello 
Hello world 

> curl http://org.apisix/v1/hello 
Hello world

 
将用户从非版本化路径迁移到版本化路径
我们已经对 API 进行了版本控制,但我们的用户可能仍在使用旧的非版本控制 API。我们希望他们迁移,但我们不能只删除旧路由,因为我们的用户不知道它。幸运的是,301 HTTP 状态码是我们的朋友:我们可以让用户知道资源已经从 http://org.apisix/hello 移动到了 http://org.apisix/v1/hello。它需要在初始路由上配置重定向插件:
curl http://apisix:9080/apisix/admin/routes/1 -H 'X-API-KEY: xyz' -X PATCH -d '
{
  "plugins": {
    "redirect": {
      "uri": "/v1$uri",
      "ret_code": 301
    }
  }
}'

结果很有趣:
要么用户将透明地使用新端点,因为他们将跟随,要么他们的集成中断,他们会注意到 301 状态和要使用的新 API 位置。
 
了解你的用户
您可能已经注意到,到目前为止,我们不知道谁在使用我们的 API。当我们不得不引入改变时,我们必须要有创意,不要破坏用户的使用。其他变化可能并不那么容易应对。因此,我们应该努力了解我们的用户,以便在必要时与他们联系。
 
创建用户
您可能应该开始看到您的用户访问注册页面,具体取决于您限制未经身份验证的使用量。注册有很多方面;有可能:
  • 自动化或需要尽可能多的手动验证步骤
  • 免费或付费
  • 就像在没有进一步验证的情况下询问电子邮件一样简单,或者像需要更多数据一样复杂
  • 等等。

这取决于您的具体情况。
 
生产测试
在这个阶段,我们现在准备让用户了解我们的 Hello world API 的改进版本。我假设我们的团队对其进行了彻底的测试,但新代码总是有风险的。部署现有应用程序的漏洞百出的新版本可能会对 API 提供商的形象(以及收入!)产生负面影响。
 
弃用旧版本
大多数用户可能会迁移到新版本以从中受益,但其中一小部分会留在 v1.1 上。这可能有多种原因:没有合适的时间(提示:它永远不会)、太贵、没有足够的迁移动力,等等。但作为 API 提供者,每个部署的版本都有一定的成本。您可能需要在某个时候停用 v1。
 
结论
在这篇文章中,我们描述了一个简单的分步流程来管理 API 的生命周期:
  1. 不要直接暴露你的 API;前面设置一个API网关
  2. 使用路径、查询参数或请求标头对现有 API 进行版本控制
  3. 将用户从未版本化端点迁移到具有 301 状态代码的版本化端点
  4. 轻轻推动您的用户注册
  5. 在生产中进行测试,首先复制流量,然后将一小部分用户转移到新版本
  6. 正式发布新版本
  7. 通过标准响应标头传达旧版本的弃用

详细点击标题
这篇文章的完整源代码可以在Github上以 maven 格式找到。

API版本控制相关文章: