REST API 已成为 Web 上应用程序之间通信的标准。基于简单而强大的原则，REST API 为编程接口的设计、开发和使用提供了一种标准化且灵活的方法。通过采用客户端-服务器架构并适当使用 HTTP 方法，REST API 实现了分布式系统的平滑且高效的集成。
作为一种标准，API 生态系统近年来变得更加丰富，并逐步融入 DevOps 生态系统。它注入了敏捷性、CI/CD 和 FinOps，并继续自我发展。本文将汇总这些新的实践和工具，以帮助您了解“API 方法”可以实现的功能。
API 设计和文档
API 设计和文档阶段至关重要，因为它为后续开发奠定了基础。通过使用领域驱动设计（DDD）、事件风暴和 API 目标画布（表示什么、谁、如何、输入、输出和目标）等方法，可以理解业务需求并确定 API 的相关领域和目标。这些研讨会使业务和开发团队能够共同工作，定义 API 的目标和不同业务领域之间的交互。
在设计和记录 API 时，必须遵循 REST API 的基本原则。这包括识别资源并使用有意义的 URL 表示它们，适当地使用 HTTP 方法进行 CRUD（创建、读取、更新、删除）操作，以及以无状态的方式管理资源状态。通过采用面向资源的方法，开发团队可以为客户端开发人员设计直观且易于使用的 REST API。REST API 文档应突出显示可用的端点、支持的方法、接受和返回的数据格式，以及任何安全性或分页约束。
API 风格书籍在这一阶段发挥着关键作用。它们提供了设计指南和标准，以确保开发的 API 一致性和质量。这些样式书定义了 URI 结构、要使用的 HTTP 方法、数据格式、错误处理等规则，并可作为组织内 API 项目的通用参考。常用工具包括信号灯和 SwaggerHub，简单的 Wiki 工具也足够。
数据模型库通过提供可重用的数据模型，定义 API 中使用的标准数据结构，来完成这一阶段。数据模型库包括 JSON 模式、数据库定义、对象模型等，提供现成的资产，减少错误，加速开发。常用工具有 Apicurio 和 Signal Lights。
API 门户上的 API 经常缺少工作流 API 的描述，这带来了如下问题：
- 如何链接 API 调用？
- 如何描述这些调用的顺序？用图示还是文本？
- 如何确保最了解 API 的人能够读懂并定期更新？
理解 API 调用的顺序往往比较困难，但通常通过 API 门户上的附加文档进行补充。然而，这些文档与开发人员提供的代码分离。OpenAPI 规范允许定义链接和回调，但这在解释过程中有限制。因此，最近出现了 OpenAPI 工作流规范，用于定义 API 工作流，这些步骤用 JSON 描述，允许生成模式来解释调用顺序。
如果希望从 OpenAPI 规范描述工作流，可以使用 Swagger Editor 或 SwaggerHub。也可以使用 Swagger to UML 或 OpenAPI to PlantUML。例如，可以使用 PlantUml 或 LucidChart 从设计序列图开始。工具链的选择取决于是否偏好自顶向下还是自底向上的方法。像 Stolight Studio 和 Redocly 这样的工具，通常用于处理这些主题，Apicurio 也是如此。它们可以用于 API 设计，使团队能够使用用户友好的界面轻松创建和可视化 OpenAPI 规范，并自动生成交互式文档，确保文档始终是最新的，并且与 API 规范保持一致。
API 开发
一旦定义了 API 规范，下一步就是根据设计阶段制定的指导方针和模型来开发 API。敏捷软件开发方法、有效的协作以及版本管理是确保高效开发的关键实践。
对于版本控制，团队使用 Git 或 GitHub 等版本控制系统来管理 API 源代码。版本控制支持开发人员之间的无缝协作，并确保 API 随时间变化的完全可跟踪性。
在开发过程中，可以使用检查工具来确保 API 规范的质量。这些工具可以检查以下内容：
- 代码的语法和结构
- 遵守编码标准和命名约定
- 正确使用库和框架
- 是否存在死代码或冗余代码
- 潜在的安全问题
Swagger-Lint 和 Apicurio Studio 或 Stoltlight 可以用来执行这些检查，确保 API 规范的质量。这些检查也可以集成到 CI/CD 工具链中，以实现自动化和持续集成。
自动化在开发阶段非常关键，可以通过工具如 Postman 和 Newman 进行单元、安全性和负载测试，以确保 API 的质量和安全性。其他解决方案包括 REST Assured、Karate 和 K6。
支持 API REST 开发的框架非常常见，最流行的包括 Express.js（与 Node.js）、Spring Boot 和 Meteor。选择合适的框架不仅要考虑其 API 能力，还需要符合开发团队的需求和技术挑战。
模拟原型也很重要，它可以减少开发人员之间的相互依赖。Mock API 通常基于 API 的 OpenAPI 描述进行创建，API 管理门户通常会支持这一点。开源项目如 MockServer 和 WireMock 也是常用的模拟工具。
API 的安全
API安全性是开发和管理过程中的关键问题，涉及以下主要协议：
- API密钥：由于其易用性和低开销，API密钥仍广泛用于API访问。它们以一对唯一字符的形式存在，应像密码一样安全地存储。
- OAuth 2.0：一种基于令牌的身份验证方法，涉及三个参与者：用户、集成应用程序（通常是API网关）和目标应用程序。用户通过OAuth端点交换令牌，授予应用程序对服务提供者的访问权限。OAuth 2.0因其粒度访问控制和基于时间的限制而受到青睐。
- OpenID Connect：这是OAuth 2.0的扩展，增加了标准化的第三方标识和用户身份，适用于细粒度授权控制和管理多个身份提供者，尽管并非所有API提供者都需要它。
除了使用API密钥、OAuth 2.0 和 OpenID Connect，您还可以部署集中管理工具如 Keycloak 来管理身份和API访问。其替代品包括 OAuth2 Proxy、Gluu Server、WSO2 Identity Server 和 Apache Syncope。
不过，仅仅依赖这些工具和协议并不足以完全保障API安全。实现 OWASP 规则的前端 Web 应用程序防火墙 (WAF) 可以防止许多常见安全问题。为了更深入的安全管理，可以参考像 DZone Refcard 这样的资源，或采用 DevSecOps 方法来降低风险。
此外，自动化安全测试也是必不可少的，工具如 ZAP 可以进行自动化的安全测试，帮助识别和修复API中的潜在漏洞，确保API的稳健性。
API 生命周期管理
一旦开发了API，就需要在整个生命周期中有效地部署和管理它们。这包括版本管理、部署管理、性能监控，以及确保API的可用性和可靠性。API管理平台如Gravitee、Tyk、WSO2 API Manager、Google Cloud Apigee和Amazon API Gateway等，可以帮助进行API的部署、版本管理和监控。这些平台提供了一些高级特性，如缓存、速率限制、API安全性和配额管理。这些功能对于扩展规模非常重要。
为了确保符合设计阶段建立的标准和指导方针，使用诸如stolight的spectrum之类的工具对OpenAPI规范进行检查分析，识别潜在问题并确保API与设计标准的一致性。
当然，在链的最后，你需要记录你的API。现有的工具可以自动执行许多任务，例如Redocly，它可以根据OpenAPI规范生成交互式文档。额外的好处是，您可以确保您的文档始终是最新的，并且对于每个人（开发人员和业务分析人员）都始终是简单可读的。
API管理还包括持续监控API的性能、可用性和安全性，以及及时实施补丁和更新，以确保其顺利运行。
API 性能监控与优化
API的分析和监控对于确保其性能、可靠性和可用性至关重要。实时监控API性能、收集使用数据并及早发现潜在问题是关键。ELK Stack（Elasticsearch、Logstash、Kibana）常用于收集、存储和分析API访问日志，以监控性能和检测错误。OpenTelemetry也是监控端到端流程的好工具，特别是在包含API的复杂流程中。
在API性能指标方面，Prometheus和Grafana是常用的实时监控工具，能够提供关于使用趋势、瓶颈和性能问题的有价值信息。
总结
显然，您不需要一开始就准备好所有这些工具和实践来开始您的API开发之旅。您应该首先考虑您希望如何开展工作以及您的优先事项是什么。可能需要优先考虑设计工具，如检测工具，或定义您的API风格书和API设计工具。优先选择常用的工具，避免重新发明轮子，是一个明智的策略。实际上，我建议您从建立工具链的基础开始，因为这样在后续阶段的调整会更加容易。
希望这些要点能帮助您在确定API需求的优先级时，能够从容地开始您的工作。
原文链接：Get Some Rest! A Full API Stack
Keyword: 翻译api