设计一个直观、用户友好的 RESTful API 是一项艰巨的工作。如果这是您的第一次尝试,这可能已经是一项艰巨的任务。规划 API 的生命周期管理可能是事后才想到的。但无论如何都是有可能的:在这篇文章中,我想提出一种严肃的方法来发展你的 API,即使它没有计划。
让我们假设一个在使用时说“Hello”的示例应用程序:
> curl http://org.apisix/hello |
使用 API 网关
第一步也是最关键的一步是停止将应用程序直接暴露在互联网上,并在它们之间建立一个 API 网关。
版本化 API
演进 API 意味着 API 的多个版本需要在某个时候共存。
三种方法:
curl http://org.apisix/hello?version=1 |
在这个阶段,我们已经配置了两条路由,一条是版本化的,另一条是非版本化的:
> curl http://org.apisix/hello |
将用户从非版本化路径迁移到版本化路径
我们已经对 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 ' |
结果很有趣:
要么用户将透明地使用新端点,因为他们将跟随,要么他们的集成中断,他们会注意到 301 状态和要使用的新 API 位置。
了解你的用户
您可能已经注意到,到目前为止,我们不知道谁在使用我们的 API。当我们不得不引入改变时,我们必须要有创意,不要破坏用户的使用。其他变化可能并不那么容易应对。因此,我们应该努力了解我们的用户,以便在必要时与他们联系。
创建用户
您可能应该开始看到您的用户访问注册页面,具体取决于您限制未经身份验证的使用量。注册有很多方面;有可能:
- 自动化或需要尽可能多的手动验证步骤
- 免费或付费
- 就像在没有进一步验证的情况下询问电子邮件一样简单,或者像需要更多数据一样复杂
- 等等。
这取决于您的具体情况。
生产测试
在这个阶段,我们现在准备让用户了解我们的 Hello world API 的改进版本。我假设我们的团队对其进行了彻底的测试,但新代码总是有风险的。部署现有应用程序的漏洞百出的新版本可能会对 API 提供商的形象(以及收入!)产生负面影响。
弃用旧版本
大多数用户可能会迁移到新版本以从中受益,但其中一小部分会留在 v1.1 上。这可能有多种原因:没有合适的时间(提示:它永远不会)、太贵、没有足够的迁移动力,等等。但作为 API 提供者,每个部署的版本都有一定的成本。您可能需要在某个时候停用 v1。
结论
在这篇文章中,我们描述了一个简单的分步流程来管理 API 的生命周期:
- 不要直接暴露你的 API;前面设置一个API网关
- 使用路径、查询参数或请求标头对现有 API 进行版本控制
- 将用户从未版本化端点迁移到具有 301 状态代码的版本化端点
- 轻轻推动您的用户注册
- 在生产中进行测试,首先复制流量,然后将一小部分用户转移到新版本
- 正式发布新版本
- 通过标准响应标头传达旧版本的弃用
详细点击标题
这篇文章的完整源代码可以在Github上以 maven 格式找到。
API版本控制相关文章:
- https://stripe.com/blog/api-versioning
- https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis
- https://apigility.org/documentation/api-primer/versioning