API 设计

上次更新日期：2026/10/9

使用编辑器设计您的 API。

从需求到 API

与大多数技术一样，API 是针对问题的解决方案。为了设计出合适的 API，您需要通过回答以下问题来确保要解决的问题已明确定义：

例如，如果您是一家外卖配送公司，您可能希望为您的合作伙伴网络构建一个 API，使他们能够浏览和搜索您为其提供配送服务的餐厅数据库。

在本例中，您的 API 面向您公司的合作伙伴。他们需要处理餐馆相关数据，并对这些数据执行搜索查询，同时具备一定的筛选和排序功能。

另一个例子：如果您是一家日历 SaaS 公司，您可能希望构建一个 API，以便全球其他前端开发者能够基于您的日历系统创建新的移动和 Web 应用程序。

考虑 API 的使用者是为他们提供良好开发者体验的第一步。这将有助于您的 API 脱颖而出并提高参与度。

设计 API 时会用到四个关键概念：

资源是您的使用者通过您的 API 与之交互的元素。资源由路径唯一标识，该路径与 API 的端点相结合，为 Web 上的资源提供了唯一地址。例如，Calendars 是对应于日历列表的资源的名称，其路径为 /calendars。
操作是指可以对您的资源执行的动作。最常见的操作是 GET（读取）、POST（创建）、PUT（更新）和 DELETE。例如，List all Calendars 是对 Calendars 资源使用 GET 方法的操作名称。
数据类型是对通过网络交换的实际数据的描述。例如，Calendar 是一个数据类型的名称，用于描述 Calendar 的所有属性，例如其名称、所有者以及对其所属事件的引用。“列出所有日历”操作返回 Calendar 数据类型的列表。
组件是一个可以在整个 API 定义中复用的元素。例如，如果您需要在多个操作中使用相同的查询参数，可以将其创建为组件，并根据需要在任意多个操作中引用它。

构成 API 的还有其他有用元素：

端点是您的 API 在 Web 上的主要入口点。端点由协议（例如 HTTPS）和主机（例如 www.calendar-api.com）组成。
文本块可用于自由输入任何文本（包括 Markdown），并可放置在 API 设计的任意位置。使用文本块来说明身份验证和错误处理等通用主题。
分节用于对资源和数据类型进行有意义的分组。使用这些可以让您的 API 设计更清晰、对开发者更友好。您可以将元素拖放到左侧面板的分区中，也可以调整各个分区之间的顺序。

在 API 契约中，您可以从右上角的新建菜单创建这些元素。

服务器 URL 在常规信息屏幕中创建。服务器 URL 可以是已发布或未发布。如果已发布，它将显示在实时文档中。

如果您发现此页面或其内容有任何问题 – 打字错误、遗漏步骤或技术错误 – 请告诉我们！