API 生命周期管理

一、API 创建

• 基于 API 设计器生成 API。
Swagger Editor 可以在浏览器中使用 YAML 编写服务 OpenAPI 规范的 API 文档，并能够实时预览文档以及自动化生成代码。

• 从代码扫描生成。
该方法主要在项目中后期使用。在项目迭代过程中，会不断更新现有的 API 接口和增加新 API 接口。
目前常用的工具也是Swagger，可以在项目中添加依赖和配置即可生成。

二、API 测试
API 的测试包含几个部分：API 的接口逻辑、API 文档和 API 的性能测试。

• API 接口逻辑
API 接口定义了客户端和服务器端通信的契约。包含所需的输入参数和 API 的预期响应。在进行 API 接口测试时要测试不同参数的组合对结果的影响，包含正确和错误的情况。

• API 文档的测试
API 测试时需要验证 API 接口文档是否是正确且最新的。
当发布新版本的 API 时，应更新 API 文档到当前版本。
API 文档应该和 API 一样是有版本控制的，并且 API 文档应该是自动化生成，这样既能保证 API 文档与代码的一致性，也能保证 API 文档的正确性。目前常用的 API 文档生成工具，还是 Swagger。
如果要想检查每次提交有没有 API 接口的变更，可以参考微软 Azure 的一个开源项目 openapi-diff。

• API 性能测试
大多数情况下，应用程序的整体性能取决于为应用程序提供基础的 API 性能。因此，API 的性能和负载测试就显得非常重要。

• 第一步：收集有关API的性能要求数据，包含以下信息：
每个 API 每秒请求数的平均吞吐量；

在给定的峰值处理请求的最大数量；
客户端应用程序预期的并发用户数，能够预测 API 在负载下预期处理的并发连接总数。

在决定 API 测试的性能要求后，在实际测试时就要以该要求为标准进行验证。
如果未达到该要求，就要调整和优化 API 平台的参数，从而获得更好的吞吐量。如果通过优化仍然未达到要求，就应该考虑更高配置的硬件设施。

• 第二步：选择性能测试的方法。
1.基线测试：该测试的目的是找出系统在正常预期负载下的表现，测试结果用于分析 API 响应时间的平均值和峰值。

2.负载测试：在负载测试期间，增加负载，以研究在不断增长的流量下 API 的性能。
可以查看的指标有响应时间、吞吐量等。该测试的目的是了解预期的系统行为和处理预期峰值负载的能力。

3.压力测试：该测试的目的是找到平台的临界点，确定系统可以处理的最大吞吐量。
当随着流量逐渐增加，直到性能开始下降或 API 调用的错误开始增加时便到达临界点。

4.浸泡测试：该测试的目的是指当系统长时间测试时是否有任何系统不稳定的问题。

• 第三步：选择合适的工具或平台进行测试。比较常用的有 JMeter 和 LoadUI 等。  

三、API 发布
API 经过测试达到可发布的要求后即可发布，发布后的 API 可以被其他客户端使用。

四、API 版本的管理方法。

• 使用 URL 管理：API 通常由 URL 标识，所以在URL中加入版本控制是有意义的，也是目前最常用的方法。
比如：https://api.devops.com/v1/products https://api.devops.com/2018/products 等；

• 使用 HTTP Header 管理：在 Header 中指定 API 的版本，比如使用 X-API-Version 的 header 标识。
使用查询参数管理：在查询条件中指定版本，比如 https://api.devops.com/products?version=2