如何构建 API

什么是 API？

什么是 API？成功构建 API 的准则是什么？应用编程接口 (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 可能被用于不当用途，例如代码注入和数据盗窃。

在解决这些宏观问题后，企业可以制定开发准则，开发人员可以更深入地了解从零构建 API 的整个过程。

SOAP 与 REST API 对比

设计 API 时的一个关键决策是定义应用如何访问 Web 服务。对此，简单对象访问协议 (SOAP) 和表述性状态传递 (REST) 都是设计 API 的有效路径。两者各有优缺点，哪个更适合项目需求取决于使用情况和上下文。一般来说，Web 服务应支持 SOAP 或 REST（二者之一），因此，一种理想方法是基于在实现项目目标上的表现来为 Web 服务选择 SOAP 或 REST。

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

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

选择 REST 还是 SOAP？
哪一个标准更适合您的应用？这取决于您的需求。对于大多数提供面向用户的简单消息（例如共享媒介或数据库查询输出）的应用，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 响应，确保结果透明。测试可能是一个漫长而艰巨的过程，当面对大量测试工作时，想要舍弃一些测试结果是难免的。但是，认真记录测试数据可确保清晰记录 API 的功能、行为、测试结果和有效性。
• 检查安全性和性能。API 的功能无疑十分重要，但在验证 API 能够正常运转后，安全性（数据和访问风险）和性能（资源用量、扩展性和处理效率）测试同样不可或缺。

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