在 Amazon Gate API way 中使用自定义域名实现基于路径的版本控制 API - AWS Prescriptive Guidance
摘要先决条件和限制架构工具最佳实践操作说明故障排除相关资源其他信息

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

在 Amazon Gate API way 中使用自定义域名实现基于路径的版本控制 API

由 Corey Schnedl (AWS)、Anbazhagan Ponnuswamy ()、Marcelo Barbosa ()、Gaurav Samudra (AWS)、Mario Lopez Martinez (AWS) 和 Abhilash Vinod () 创作 AWS AWS AWS

摘要

此模式演示了如何使用自定义域的API映射功能为 Amazon Gateway 实施基于路径的API版本控制解决方案。API

Amazon API Gateway 是一项完全托管的服务，您可以使用它来创建、发布、维护、监控和保护APIs任何规模。通过使用该服务的自定义域名功能，您可以创建更简单、更直观的自定义域名URLs，以便提供给API用户。您可以使用API映射将API阶段连接到自定义域名。创建域名并配置DNS记录后，您可以使用API映射APIs通过自定义域名向您的发送流量。

公开发行后，消费者API就会使用它。API随着公众的发展，其服务合同也在不断演变，以反映新的特性和功能。但是，更改或移除现有功能是不明智的。任何重大更改都可能影响消费者的应用程序并在运行时中断它们。 API版本控制对于避免破坏向后兼容性和破坏合约非常重要。

你需要一个明确的API版本控制策略来帮助消费者采用它们。使用基于路径APIs的版本控制URLs是最直接和最常用的方法。在这种类型的版本控制中，版本被明确定义为的一部分。API URIs以下示例URLs显示消费者如何使用URI为其请求指定API版本：

https://api.example.com/api/v1/orders

https://api.example.com/api/v2/orders

https://api.example.com/api/vX/orders

此模式使用为您构建、部署和测试基于路径的可扩展版本控制解决方案的示例实现。 AWS Cloud Development Kit (AWS CDK) API AWS CDK 是一个开源软件开发框架，用于使用熟悉的编程语言对云应用程序资源进行建模和配置。

先决条件和限制

先决条件

  • 活跃 AWS 账户的.

  • 使用此模式的示例存储库和使用 Amazon API Gateway 自定义域名功能需要拥有域的所有权。您可以使用 Amazon Route 53 为您的组织创建和管理您的域名。有关如何使用 Route 53 注册或转移域的信息，请参阅 Route 53 文档中的注册新域名。

  • 在为设置自定义域名之前API，必须准备好 SSL/TLS证书 AWS Certificate Manager。

  • 您必须创建或更新DNS提供商的资源记录才能映射到您的API终端节点。如果没有这样的映射，绑定到自定义域名的API请求将无法到达 API Gateway。

限制

  • 私有域名不支持自定义域名APIs。

  • 自定义域名在所有域名中必须是 AWS 区域 唯一的 AWS 账户。

  • 要配置多个级别的API映射，必须使用区域自定义域名并使用 TLS 1.2 安全策略。

  • 在API映射中，自定义域名和映射的域名APIs必须相同 AWS 账户。

  • API映射必须仅包含字母、数字和以下字符：$-_.+!*'()/

  • API映射中路径的最大长度为 300 个字符。

  • 每个域名可以有 200 个具有多个级别的API映射。

  • 您只能使用 TLS 1.2安全策略映射HTTPAPIs到区域自定义域名。

  • 您不能映射 WebSocket APIs到与HTTPAPI或相同的自定义域名RESTAPI。

  • 有些 AWS 服务 并非全部可用 AWS 区域。有关区域可用性，请参阅按地区划分的AWS 服务。有关特定终端节点，请参阅服务终端节点和配额，然后选择服务的链接。

产品版本

  • 此示例实现在 2.149.0 TypeScript 版本AWS CDK 中使用。

架构

下图显示了架构工作流程。

使用API映射和自定义域实现基于路径的API版本控制解决方案的工作流程。

该图阐释了以下内容：

  1. API用户使用自定义域名向 Amazon API Gateway 发送请求。

  2. APIGateway 根据请求中指示的路径，动态地将用户的请求路由到 API Gateway URL 的相应实例和阶段。下表显示了一个示例，说明如何针对不同的 API Gat URL eway 实例将不同的路径路由到特定阶段。

    API

    舞台

    路径

    默认端点

    C alculationAPIv 1

    api

    apiv1

    已启用

    C alculationAPIv 2

    api

    apiv2

    已启用

    C alculationAPIv X

    api

    apiVX

    已启用

  3. 目标 API Gateway 实例处理请求并将结果返回给用户。

自动化和扩缩

我们建议您为每个版本使用单独的 AWS CloudFormation 堆栈。API通过这种方法，您可以在自定义域API映射功能APIs可以路由到的后端之间实现完全隔离。这种方法的一个优点是，API可以独立部署或删除你的不同版本，而不会带来修改其他版本的风险API。这种方法通过隔离 CloudFormation 堆栈来提高弹性。此外，它还为您提供了不同的后端选项 AWS Lambda，API例如、 AWS Fargate、HTTP端点和操作。 AWS 服务

您可以将 Git 分支策略（例如 Gitflow）与隔离 CloudFormation 堆栈结合使用，来管理部署到不同版本的源代码。API通过使用此选项，您可以维护不同的版本，API而无需为新版本复制源代码。使用 Gitflow，您可以在执行发布时为 git 存储库中的提交添加标签。因此，您可以获得与特定版本相关的源代码的完整快照。由于需要执行更新，您可以查看特定版本中的代码，进行更新，然后将更新的源代码部署到与相应主版本一致的 CloudFormation 堆栈中。这种方法降低了破坏另一个API版本的风险，因为的每个版本都有独立的API源代码并部署到不同的 CloudFormation 堆栈中。

工具

AWS 服务

  • Amazon API Gateway 可帮助您以任何规模创建、发布RESTHTTP、维护、监控和 WebSocket APIs保护。

  • AWS Certificate Manager (ACM) 帮助您创建、存储和续订用于保护您的 AWS 网站和应用程序的公共和私有SSL/TLSX.509 证书和密钥。

  • AWS Cloud Development Kit (AWS CDK)是一个开源软件开发框架，用于在代码中定义您的云基础架构并通过它进行配置 AWS CloudFormation。此模式的示例实现使用 AWS CDK in TypeScript。在 in AWS CDK 中 TypeScript 使用熟悉的工具，包括 Microsoft TypeScript 编译器 (tsc)、Node.js 和节点包管理器 (npm)。如果你愿意，你可以使用 Yarn，尽管此模式中的示例使用npm了。构成AWS 构造库的模块通过npm 存储库 npm js.org 分发。

  • AWS CloudFormation帮助您设置 AWS 资源，快速一致地配置资源，并在和的整个 AWS 账户 生命周期中对其进行管理 AWS 区域。

  • AWS Lambda 是一项计算服务，可帮助您运行代码，无需预置或管理服务器。它仅在需要时运行您的代码，并且能自动扩缩，因此您只需为使用的计算时间付费。

  • Amazon Route 53 是一项高度可用且可扩展的DNS网络服务。

  • AWS WAF是一种 Web 应用程序防火墙，可帮助您监控HTTPS请求HTTP并将其转发到受保护的 Web 应用程序资源。

其他工具

  • Bruno 是一款开源、Git 友好的测试客户端API。

  • cdk-nag 是一个开源实用程序，它使用规则包检查 AWS CDK 应用程序的最佳实践。

代码存储库

此模式的代码可在 GitHub path-based-versioning-with-api- gateway 存储库中找到。

最佳实践

  • 使用强大的持续集成和持续交付 (CI/CD) 管道，自动测试和部署使用构建的 CloudFormation 堆栈。 AWS CDK有关此建议的更多信息，请参阅 Well-Architect AWS ed 指南 DevOps 。

  • AWS WAF 是一款托管防火墙，可轻松与 Amazon API Gateway 等服务集成。尽管 AWS WAF 这不是此版本控制模式起作用的必要组件，但我们建议将其作为安全最佳实践包含在 API Gatew AWS WAF ay 中。

  • 鼓励API消费者定期升级到您的最新版本，API以便API可以高效地弃用和删除您的旧版本。

  • 在生产环境中使用此方法之前，请为您实施防火墙和授权策略API。

  • 使用最低权限访问模式实现对 AWS 资源管理的访问权限。 AWS 账户

  • 要对使用构建的应用程序强制执行最佳实践和安全建议 AWS CDK，我们建议您使用 cdk-na g 实用程序。

操作说明

任务描述所需技能

克隆存储库。

要克隆示例应用程序存储库，请运行以下命令：

git clone https://github.com/aws-samples/path-based-versioning-with-api-gateway
应用程序开发人员

导航到克隆的存储库。

要导航到克隆的存储库文件夹位置，请运行以下命令：

cd api-gateway-custom-domain-versioning
应用程序开发人员

安装所需的依赖项。

要安装所需的依赖项，请运行以下命令：

npm install
应用程序开发人员
任务描述所需技能

启动路由堆栈的部署。

要启动 CloudFormation 路由堆栈的部署CustomDomainRouterStack，请运行以下命令，example.com替换为您拥有的域名：

npx cdk deploy CustomDomainRouterStack --parameters PrerequisiteDomainName=example.com
注意

在成功执行以下域DNS验证任务之前，堆栈部署不会成功。

应用程序开发人员
任务描述所需技能

验证您的域名的所有权。

在您证明关联域的所有权之前，证书将一直处于 “待验证” 状态。

要证明所有权，请将CNAME记录添加到与该域关联的托管区域。有关更多信息，请参阅 AWS Certificate Manager 文档中的DNS验证。

添加适当的记录可以使CustomDomainRouterStack部署成功。

应用程序开发者、AWS系统管理员、网络管理员

创建别名记录以指向您的 API Gateway 自定义域。

成功颁发并验证证书后，创建一条指向您的 Amazon API Gateway 自定义域的DNS记录URL。

自定义域名URL由配置自定义域名时唯一生成，并指定为 CloudFormation 输出参数。以下是该记录的示例：

路由策略：简单路由

记录名称：demo.api-gateway-custom-domain-versioning.example.com

别名：是

记录类型：指向 AWS 资源的类型为 “A” 的DNS记录

值：d-xxxxxxxxxx.execute-api.xx-xxxx-x.amazonaws.com

TTL（秒）：300

应用程序开发者、AWS系统管理员、网络管理员
任务描述所需技能

部署 ApiStackV1 堆栈。

要部署ApiStackV1堆栈，请使用以下命令：

npm run deploy-v1

以下CDK代码添加了API映射：

var apiMapping = new CfnApiMapping(this, "ApiMapping", {
      apiId: this.lambdaRestApi.restApiId,
      domainName: props.customDomainName.domainName,
      stage: "api",
      apiMappingKey: "api/v1",
    });
应用程序开发人员

部署 ApiStackV2 堆栈。

要部署ApiStackV2堆栈，请使用以下命令：

npm run deploy-v2
应用程序开发人员

调用API.

要使用 Bruno 调用API和测试API端点，请参阅其他信息中的说明。

应用程序开发人员
任务描述所需技能

清理资源。

要销毁与此示例应用程序关联的资源，请使用以下命令：

npx cdk destroy --all
注意

请务必清理为域所有权验证过程手动添加的所有 Route 53 DNS 记录。

应用程序开发人员

故障排除

事务解决方案

部署超CustomDomainRouterStack时，因为无法验证证书。

确保按照之前的任务中所述添加了正确的DNS验证CNAME记录。添加验证记录后，您的新证书可能会在 30 分钟内继续显示待DNS验证状态。有关更多信息，请参阅 AWS Certificate Manager 文档中的DNS验证。

相关资源

其他信息

和 Bruno API 一起测试你的

我们建议您使用开源API测试工具 Bruno 来验证示例应用程序中基于路径的路由是否正常运行。此模式提供了样本集合，便于测试您的样本API。

要调用和测试您的API，请使用以下步骤：

  1. 安装布鲁诺。

  2. 打开 Bruno。

  3. 在此模式的代码存储库中，选择 Bruno/Sample API-，Gateway-Custom-Domain-Versioning 然后打开该集合。

  4. 要查看用户界面 (UI) 右上角的 “环境” 下拉列表，请选择集合中的任何请求。

  5. 在 “环境” 下拉列表中，选择 “配置”。

  6. 用您的自定义域名替换该REPLACE_ME_WITH_YOUR_DOMAIN值。

  7. 选择 “保存”，然后关闭 “配置” 部分。

  8. 对于沙盒环境，请确认已选中 “活动” 选项。

  9. 使用API所选请求的 -> 按钮调用您的。

  10. 请注意与 V2 相比，V1 中如何处理验证（传入非数字值）。

要查看示例API调用屏幕截图以及 V1 和 V2 验证的比较，请参阅在此模式的代码存储库API中的README.md文件中测试您的示例。