如何构建 API

什么是 API？

什么是 API？成功构建 API 的准则是什么？应用编程接口 (API) 是一组编程函数、工具和协议，允许外部应用访问平台、操作系统、应用或服务的功能或数据并与之交互。高效的 API 为更大的数据共享和协作打开了大门，创建了一个生态系统，让不同的软件可以相互通信以提供业务功能。API 是现代应用和基于微服务的云原生架构的核心组件；它们为不同的服务创建主要渠道，以相互通信并提供现代体验。

设计、开发和分发成功的 API 需要利用一系列优秀实践。通过遵循这些优秀实践，该流程可确保开发人员和应用的安全访问和轻松使用。这些优秀实践包括：

• 简单而优雅的设计，确保具有不同技能和经验的开发人员可以使用 API
• 高级别的安全性，可根据需要限制对数据的访问
• 精益设计原则，确保访问 API 不会影响源或外部应用
• 相关服务，以确保对现有 API 进行监管、安全和使用监视

如何从零开始开发 API

构建 API 在很大程度上取决于与源和将要与此源连接的外部应用相关的特定因素。以下是规划 API 开发流程时需要问的一些问题。

您的目标是什么？
对于任何类型的项目，您都可以从全局出发：定义和理解您的目标。API 的用途是指导您完成此项目。将通过 API 交换哪些信息？它将如何被使用或呈现？要考虑的其他因素包括了解应用的目标受众及其需求。

您的限制是什么？
项目目标的另一面是项目限制。将实用的视角应用于开发是必要的一步，因此您应该充分了解自己的资源和时间表的限制。需要考虑的另一个因素是：任何技术限制，如安全问题、对硬件资源的影响以及性能需求都应该考虑可扩展性。

您的架构是什么？
在从零开始设计 API 时，开发人员有许多可以选择的起点。Python、Java、JavaScript、C# 和其他语言都是开发 API 的可行选择。设计注意事项中需要考虑的其他因素包括可用性、可扩展性（与资源需求结合）和安全性。最后一点特别重要，因为 API 充当应用之间的桥梁。在这样做时，双方必须妥善保护其数据。具有安全漏洞的 API 可能会被攻击，例如代码注入和数据泄露。

通过这些宏观问题，可以定义准则，开发人员可以更深入地从零开始构建 API 的过程。

SOAP 与 REST API

设计 API 时的一个关键决策取决于应用将如何访问 Web 服务。简单软件架构样式对象访问协议 (SOAP) 和表示状态传输 (REST) 都可以作为设计 API 的有效路径。两者各有优缺点，哪个更适合项目则取决于使用情况和上下文。一般来说，Web 服务将支持 SOAP 或 REST，因此，决定 API 的 Web 服务很可能是由 SOAP 或 REST 为您的目标更好地工作定义的。

什么是 SOAP？
SOAP 是一种基于 XML 的协议，最初由 Microsoft 设计。SOAP 基于一组规则构建，在消息传递中创建标准，这些标准支持大量扩展（WS-coordination 和 WS-security）、自动化和内置错误处理。SOAP 在分布式环境中效果更好，但其对 XML 结构的依赖可能会使代码过于复杂。

什么是 REST？
REST 是作为 SOAP 的一个更简单、更轻量级的替代方案而开发的，该替代方案在点对点级别运行。作为一种专为高效可扩展性而构建的软件架构风格，REST 提供了一系列标准化约束，能够尽量减少处理工作量，同时提供灵活性。REST 的快速响应可充分减少应用使用的各种输出消息格式（包括 JSON 和 CSV）的延迟。

是否应将 REST 或 SOAP 用于 API？
哪一个标准更适合您的应用？这取决于您的需求。对于大多数应用启用面向用户的简单消息（例如共享介质或数据库查询的输出）的情况，REST API 是理想选择。SOAP 具有更严格的学习和使用曲线，但这种固有的复杂性使其能够处理更复杂的事务，例如安全支付。

选择 API 设计工具

构建 API 的具体细节取决于开发团队选择的工具。Oracle Cloud Infrastructure (OCI) 的 API 解决方案支持您基于 OpenAPI 规范，使用完整的工具包轻松设计和开发 API，实现快速原型设计和验证。借助 OCI，用户可以访问 API Blueprint 或 Swagger 来设计其 API。此外，API 可以从头开始构建，也可以从模板开始构建，以加快开发过程。

让我们详细了解 OCI 上的 API 开发流程。对于此示例，我们将使用 OCI 控制台创建 API 资源（可选择使用从上传的 API 说明文件创建的 API 说明）。请自行注册免费 OCI 账户，按照步骤操作。

1. 在控制台中，打开导航菜单，然后单击“Developer Services”。在“API Management”下，单击“Gateways”。
2. 在“API”页上，单击“Create API Resource”并指定其名称。上载 API 说明文件（包含支持的语言的 API 说明）和标签。
3. 单击“Create”，创建新的 API 资源。
4. 编写后端代码。使用您首选的编程语言和框架，创建可为您的 API 提供支持的后端代码。这可以是包括其他协作者在内的迭代过程。
5. 测试后端代码。Oracle API 开发服务包含各种工具，可用于在本地和通过各种连续集成 (CI) 服务进行测试。
6. 部署。启动 API 并使其可供开发人员生态系统、合作伙伴、客户和内部开发人员访问。Oracle API Gateway 支持对 API 连接、安全性和监管进行使用监视和管理。

如需更深入地了解使用 Oracle 基于云技术的 API 解决方案进行 API 开发，请查看 Oracle API 开发人员指南 (PDF)。

测试 API 的优秀实践

全面测试 API 是确保顺利启动和持续运行的关键步骤。为了帮助您部署可满足业务需求的 API，下面简要介绍了有效的 API 优秀实践：

• 使用 API 烟雾测试验证代码（基本测试验证 API 的基本功能是否正常工作）。烟雾测试应检查可重复的错误。
• 在与生产环境相似的条件下使用真实数据。使用不能反映真实世界用例的数据只会延长您排除不同场景故障的能力，并且可能产生不可靠的测试。因此测试应该尽可能地复制真实世界的情况。
• 执行正面和负面的测试。由于测试需要全方位的预期结果和使用场景，开发人员必须将正面（预期的功能结果）和负面（计划中的错误造成意外结果）测试都纳入其计划中。
• 使用全面的 API 响应跟踪实现透明结果。测试可能是一个漫长而艰巨的过程，当存在大量测试时，放弃测试结果的冲动是自然的。但是，认真记录这些数据可确保清晰记录功能、行为、测试结果和有效性。
• 检查安全性和性能。功能显然是关键，但一旦测试被证明有效，检查安全性（数据和访问风险）和性能（资源使用、扩展和高效处理）也同样重要。

准备好构建和测试您的 API 了吗？免费试用 Oracle Cloud Infrastructure API 管理服务，体验完整的 API 生命周期管理解决方案。