精通 API 设计：开发高性能 API 的关键策略

本文由我们的社区成员贡献，已由 DataCamp 编辑以提高清晰度与准确性。

想要分享您的专业见解？我们非常期待！欢迎通过我们的社区投稿表单提交您的文章或想法。

您在网约车和外卖应用中看到的地图，多亏了开发者使用 Google Maps API 来实现相关功能。Google Maps API 是网站和应用展示实时地图的默认选择。若想知道确切数字，目前有5,567,291 个正在运行的网站在使用该 API。

那么，Google Maps API 为何如此成功？固然有其来自 Google 的因素，但更重要的是其 API 设计，使开发者能够轻松将其集成到产品中。

Google Maps API 只是一个例子，市面上还有无数广受欢迎的 API，如 PayPal、Stripe 等。事实上，这些公司的部分成功可归功于其 API。

如今，任何网站或应用都可以通过 API 对外提供其核心功能。然而，API 是否被采用，归根结底取决于其设计得是否出色。本文将探讨 API 设计的基础知识及最佳实践，帮助您构建让开发者喜爱的 API。

什么是 API 设计？

API 设计是指定义应用程序用于请求与交换信息的方法和数据格式的过程。它包括明确开发者可使用的端点或 URL、应发送与接收的数据格式，以及 API 的预期行为。

虽然这些是 API 的技术层面，但 API 设计最终由其目的所决定——也就是“为什么要做这个 API”。理解 API 的目的能理顺开发流程中的诸多细节，因为这会提供关于预期行为、限制条件和潜在后续演进的洞见。如今，API 设计被纳入更广义的API 管理范畴，以确保规划设计与实际实现的一致性。

如果您想提升 API 集成与管理能力，欢迎查看 DataCamp 的课程使用 OpenAI API，助您打造 AI 驱动的应用。

如何设计一个 API

每个 API 因其目的与所承载的功能不同而各异。但仍有一些通用原则，值得每位开发者遵循，以构建健壮且对开发者友好的 API。您可以这样着手：

步骤 1：明确您的 API 目的

在绘制 API 蓝图之前，先确保所有利益相关方都清楚 API 将实现什么。与业务负责人紧密合作，明确总体目标与诉求，理解 API 如何融入更大的业务版图。如有可能，直接与将使用该 API 的终端用户或开发者沟通，收集他们的需求、痛点与期望，从而洞察 API 的实际用例。

API 的目的将决定其功能、特性、文档编写方式、所需安全实施，以及您将选择的 API 规范。

选择合适的 API 规范

常见的 API 规范各自适用于不同场景。以下是几个最流行的选项：

OpenAPI（Swagger）

OpenAPI 是描述 RESTful API 的广泛采用标准。其简洁易用，便于生成文档，并为开发者理解与交互 API 提供了标准化方式。OpenAPI 使用 JSON 或 YAML 指定 API 的端点、请求与响应格式以及认证方式。它适用于基于 HTTP 的无状态通信，也是面向广泛受众 API 的良好选择。

GraphQL Schema

GraphQL 是 RESTful API 的替代方案，其规范通常以模式语言定义。GraphQL 模式概述可查询的数据类型以及查询结构。它适用于客户端需要对所取数据进行精确控制的场景。

扩展您将机器学习模型以 API 形式提供的知识，基于 Flask 构建。参阅 DataCamp 的详尽教程用 Python 构建机器学习模型 API。

RAML（RESTful API 建模语言）

RAML 是一种基于 YAML 的 RESTful API 描述语言。它以人类可读的方式定义 API 的结构、端点和数据类型。当您优先考虑可读性与简洁性时可使用它。

SOAP（简单对象访问协议）

OAP 是用于在 Web 服务中交换结构化信息的协议。它常用于需要标准化通信的企业级应用。当您处于遗留环境中时，这是最佳选择。

WSDL（Web 服务描述语言）

WSDL 常用于描述 SOAP（简单对象访问协议）Web 服务。它定义了 Web 服务的操作、消息和数据类型，支持不同系统之间的标准化通信。最适合需要严格契约与标准化通信的企业级应用。

AsyncAPI

它类似于 OpenAPI，但专为异步 API 设计。AsyncAPI 关注消息驱动架构，描述不同组件之间如何交换消息。用于无需 API 实时响应的场景。

通过 DataCamp 的教程FastAPI 入门更深入学习 API 开发。了解如何借助现代框架创建健壮的 API。

步骤 2：定义端点与资源

下一步是定义端点与资源。端点定义开发者可与 API 交互的具体 URL（统一资源定位符）或 URI（统一资源标识符）。每个端点通常对应特定的操作或动作。常见的 HTTP 方法如 GET、POST、PUT 和 DELETE 用于在这些端点上执行操作。示例如下：

• GET /users：获取用户列表。
• GET /users/{id}：使用用户 ID 获取特定用户详情。
• POST /users：创建新用户。
• PUT /users/{id}：更新特定用户详情。
• DELETE /users/{id}：删除特定用户。

资源代表您的 API 所管理的实体或对象。可以是用户、产品、评论，或系统中任何相关实体。每个资源通常有唯一标识，并关联一个或多个端点。例如：

资源：users

属性：ID、username、email 等。

端点：

/users（GET - 列出所有用户，POST - 创建新用户），

/users/{id}（GET - 获取用户详情，PUT - 更新用户详情，DELETE - 删除用户）

资源：products

属性：ID、name、description、price 等。

端点：

/products（GET - 列出所有产品，POST - 创建新产品），

/products/{id}（GET - 获取产品详情，PUT - 更新产品详情，DELETE - 删除产品）

步骤 3：确定命名约定

若想让开发者喜爱您的 API，请务必使用清晰一致的命名约定。为端点、资源与参数命名时切忌过度“创意”，而应以清晰与简洁为先。以下是一些建议：

1. 对资源使用名词：
• 为资源选择清晰、具描述性的名词。例如：/users、/products、/orders。
• 避免含糊或过于通用的词。尽量具体，以便传达资源的用途。
2. 对动作使用动词：
• 使用 HTTP 方法（GET、POST、PUT、DELETE）表示对资源的操作。
• 在各端点间保持动词使用一致。例如，用 GET 获取用户，用 POST 创建新用户。
3. 在复数形式上保持一致：
• 决定资源名称使用单数还是复数，并在整个 API 中保持一致。例如，坚持使用 /user 或 /users 其中之一。

步骤 3：优化请求与响应负载

设计 API 契约的另一关键点是明确请求与响应负载，即请求中发送的数据与响应中期望返回的数据。首先需要为 API 选择标准数据格式，如 JSON 或 XML。更推荐选择 JSON，因为其简洁且可读性强。您可在 DataCamp 的课程使用 pandas 高效摄取数据中学习如何使用 JSON。

请务必保持负载精简，因为它会直接影响 API 的效率。您可以这样做：

1. 尽量实现负载压缩（如 gzip），以减少传输中的请求大小。

2. 如适用，支持批量请求，将多个操作合并为一次请求。

3. 使用查询参数或请求头参数来设计端点，仅返回客户端所需的数据。

步骤 4：实现认证与授权

在 API 设计中务必考虑安全性。可从认证与授权两方面入手。

在认证方面，您可以实现 OAuth 和 API 密钥。API 密钥是一种简单、常见的方法，即在请求头中包含唯一密钥。但此类认证并不够安全。

相比之下，OAuth 更加健壮且灵活，适用于第三方应用需要访问的场景。至于授权，应清晰定义用户或应用可拥有的访问级别与作用域。

步骤 5：采用 API 版本控制

用户需求与技术都会随时间变化，API 也必须随之演进。版本控制可让您在不破坏现有系统的前提下对 API 进行改动。可采用多种版本控制方式，如 URL 版本、查询参数版本、请求头版本等。

例如，

URL 版本：https://example-api.com/v1/resource

查询参数版本：https://example-api.com/resource?version=v1。

步骤 6：定义恰当的错误信息

API 的生命周期中难免出现错误，关键在于如何处理。在响应体中给出清晰简明的错误信息，帮助开发者理解问题所在。

包括错误代码、描述，以及解决建议。使用标准 HTTP 状态码指示请求的成功或失败（如 200 OK 表示成功，404 Not Found 表示资源未找到，500 Internal Server Error 表示服务器问题）。

步骤 7：应对非预期行为

还需确保 API 能处理终端用户的非预期行为与请求。例如，终端用户可能会对同一资源发出多次请求，导致并发问题。

另一方面，您这边也可能出现超时、响应缓慢，或服务器返回了客户端不需要的格式等情况。您的 API 应能以优雅的方式处理这些非预期操作，并返回合适的错误信息。

步骤 8：文档编写

当上述都完成后，最后一步是文档编写。文档就像一本手册，告诉其他开发者您的 API 如何工作。它是影响 API 采用与使用的关键因素之一。因此，请确保文档清晰、简洁、易懂。以下是一些最佳实践：

• 避免不必要的技术术语，以免让开发者困惑。
• 以逻辑、分层的方式组织文档。使用章节、小节与标题，帮助用户快速找到所需信息。
• 加入交互式示例或 API 沙盒，让开发者可直接在文档中试用 API。
• 考虑使用 Swagger 或 OpenAPI 等工具生成交互式 API 文档。

API 先设计还是先编码

构建 API 时，通常有两种路径：先设计 API 或先编码。

我们刚讨论的策略属于先设计 API，即在编写实现这些规范的实际代码之前，先定义 API 的规范，包括端点、数据格式、认证机制与整体架构。其目标是建立清晰、周密的 API 设计，以满足系统需求，并便于开发者理解与使用。

先编码的方式则相反，先写代码而不预先定义规范或文档。开发者会根据实现经验与测试反馈调整 API，设计也会随着编码过程逐步演进。

哪种方式更好？

可以说，先编码方式在开发上更灵活、更迅速，便于快速原型开发。但也伴随诸多挑战：若没有前期明确定义的规范，API 各部分实现可能出现误解或不一致。归根结底，选择取决于项目需求与团队偏好。

探索 API 的创意潜能，请参阅 DataCamp 关于DALL-E 3 API的指南，了解如何利用 AI 打造创新解决方案。

结语

API 设计涉及诸多技术细节。但您应将 API 视作一款产品，目的是解决终端用户的痛点。当您的 API 设计以这些痛点为驱动时，往往更容易被快速采纳。

通过 DataCamp 课程使用 pandas 高效摄取数据，提升借助 API 进行数据摄取的能力，获得高效处理数据的实战经验。