API 设计

使用编辑器设计您的 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 的所有属性，例如其名称、所有者以及对其所属事件的引用。List all Calendars 操作返回 Calendar 数据类型的列表。
组件是可以在整个 API 定义中重复使用的元素。例如，如果您需要在多个操作中使用相同的查询参数，则可以将其创建为组件，并在需要时在尽可能多的操作中引用它。

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

端点是您的 API 在 Web 上的主要入口点。端点由 HTTPS 等方案和 www.calendar-api.com 等主机组成。
文本块可用于自由输入任何文本（包括 markdown），这些文本可以放置在 API 设计中的任何位置。使用文本块来解释身份验证和错误处理等横向主题。
部分用于将资源和数据类型有意义地组合在一起。使用这些可以使您的 API 设计更清晰、对开发人员更友好。您可以将元素拖放到左侧面板的部分中，也可以在部分之间重新排序。

在 API Designer 中，您将能够从右上角的新建菜单中创建这些元素。

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

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