什么是 API？

2025-06-07

什么是 API？

如果您读过Contentful 文档，您就会发现我们提供了 REST API 和 GraphQL API 来访问和管理您的内容。那么，什么是 API？

API 代表“应用程序编程接口”，是不同软件服务之间通信的一种方式。不同类型的 API 用于硬件和软件编程，包括操作系统 API、远程 API 和 Web API（例如 Contentful 提供的 API）。Web API 是一组工具，允许开发者向 Web 服务器发送和接收指令和数据（通常为 JSON 格式），以构建应用程序。在 MDN 上了解更多关于 JSON 的信息。

API 无处不在

为了了解 API 在日常生活中是如何工作的，我们来看一下帖子中涉及的 API。

  • 你在网上读到一篇文章
  • 当你进入该页面时，Web 应用程序会包含指令，通过 API 请求帖子的数据，使用唯一标识符（例如帖子的 URL 段）
  • 如果请求的数据存在，则通过 API 将数据以 JSON 格式从数据库发送回网页（例如标题、发布日期、文章正文等）
  • 然后，数据将按照开发人员的编程插入到适当的 HTML 结构中，以供您阅读

这篇文章将介绍 API 的基础知识以及 API 如何在互联网上进行通信。首先，让我们回顾一下 API 的起源。

这一切从何开始？

API 的概念自 1940 年第一台计算机诞生以来就已经存在，当时英国计算机科学家 Marice Wilkes 和 David Wheeler 致力于电子延迟存储自动计算器 (EDSAC) 的软件库的开发。

EDSAC 被编程为接受各种指令，包括加、减、打印、加载和存储。这类似于现代 Web API 与数据交互的方式，例如“添加博客文章”、“删除博客文章”或“获取博客文章信息”。EDSAC 的功能通过一个注释目​​录进行记录，其中包含有关其功能以及如何将其与其他程序集成的说明。这是我们今天所知的 API 文档类型的首个示例！

什么是 Web API？

Web API 是一组工具，允许 Web 开发者通过互联网连接向 Web 服务器发送和接收指令及数据。我们如今使用的许多现代网站和 Web 应用程序都由 API 提供支持。想想 Twitter、Instagram、Facebook 以及您最喜欢的购物网站。

在现代 Web 应用程序中，前端代码并不直接与数据库交互。相反，数据是通过API 层发送和接收的。API 充当后端逻辑和数据库操作与用户交互的前端应用程序之间的中间层或契约。

API 层：

  • 确保网页被允许发出发送或接收数据的请求
  • 在将请求发送到后端之前确认其格式正确
  • 以预期格式返回数据，以及一些附加信息
  • 告诉网页是否没有返回数据以及原因

这张图展示了 API 的工作原理。左侧是一台计算机的插图，上面有文字

到目前为止，我们已经讨论了 API 如何提供一个中间层，用于在后端数据库和前端应用程序之间来回发送数据。但是，是什么支撑着这种数据交换呢？让我们来看看 Web 上数据交换的基础：HTTP。

HTTP 概览

HTTP（超文本传输​​协议）的缩写，是一种允许通过互联网连接获取资源（例如 HTML 文档和 JSON 数据）的协议。协议被定义为一套规则系统，用于定义如何在计算机内部或计算机之间交换数据。HTTP 定义了一组请求方法，这些方法在调用时执行不同的操作。最常用的 HTTP 请求方法是 GET 和 POST。

正如 HTTP 方法的动词所描述的：

  • GET 请求允许您通过 URL 检索数据
  • POST 请求允许您通过 URL 发送附加信息以执行某些操作

本文不会探讨的其他 HTTP 方法包括 PUT、DELETE、HEAD、CONNECT、OPTIONS、TRACE 和 PATCH。要深入了解 HTTP，请查看 MDN 上的这篇文章。

在我们开始研究 GET 和 POST HTTP 方法之前，让我们先了解一些 HTTP 术语。

通过 HTTP 发送信息

当你从 API 请求数据时，你发出了一个请求。当你从 API 接收数据时，你收到一个响应。

请求和响应主体

在某些 HTTP 方法中，您将需要在请求正文中发送额外的数据。

成功的 HTTP 响应将包含一个响应主体，其中包含您通过 API 请求的数据。

HTTP 标头

除了使用不同的 HTTP 方法外，您通常还需要在请求中发送特定的 HTTP 标头，并且您可能会发现响应中也包含特定的 HTTP 标头。HTTP 标头允许前端（客户端）和后端（服务器）通过 HTTP 请求或响应传递附加信息。HTTP 标头的格式为以冒号分隔的键值对：

"case-insensitive-header-name": "value as a string"

向Contentful GraphQL API发出请求时，您需要随请求发送一个 HTTP 标头，如下所示：

authorization: "Bearer _your_contentful_access_token_value_"

此标头确保网页有权发出从 API 接收数据的请求，并在相关文档中有详细说明。

HTTP 响应状态代码

你见过显示“404，页面未找到”的网页吗？这个代码——404——是一个 HTTP 响应状态代码！在浏览器中，如果应用程序无法识别 URL，你会收到 404 响应状态代码。从 API 中，你会收到 404 响应状态代码，表示你请求的数据不存在。你可以在浏览器的“网络”选项卡中找到返回给浏览器的 HTTP 响应状态代码。

这是 Contentful 404 页面的浏览器窗口截图。网络选项卡已打开，黄色矩形突出显示了 HTTP 响应状态代码 404。

HTTP 响应状态代码以数字形式随 HTTP 响应一起提供。当使用 JavaScript 中的 fetch 从 Contentful GraphQL API 请求数据时，HTTP 状态代码将作为status响应的属性提供。

下面的示例代码请求获取我的Next.js + Contentful 入门博客上可用的博客文章总数。请注意随请求发送的 HTTP 标头和请求正文。运行以下代码时，您将收到 HTTP 200 响应，并将200日志记录到控制台。200 HTTP 响应代码表示请求成功——一切正常！

const data = await fetch(
  "https://graphql.contentful.com/content/v1/spaces/84zl5qdw0ore",
  {
    method: "POST",
    headers: {
      authorization: "Bearer _9I7fuuLbV9FUV1p596lpDGkfLs9icTP2DZA5KUbFjA",
      "content-type": "application/json",
    },
    body: '{"query":"{ blogPostCollection { total } }"}',
  },
).then((response) => {
  console.log(response.status); // 200
  return response.json();
});
Enter fullscreen mode Exit fullscreen mode

HTTP 响应状态代码有五组，按首位数字分类。

  1. 信息回复（100–199）
  2. 成功回应（200–299）
  3. 重定向（300–399）
  4. 客户端错误（400–499）
  5. 服务器错误（500–599）

打开浏览器的网络标签页，查找此网页的 200 HTTP 响应状态码。如果您想查看完整的 HTTP 响应状态码列表（包括那个傻傻的 418 🙈 响应状态码），请查看 MDN 上的这篇文章。

现在我们已经探讨了如何使用 HTTP 方法发送和接收，让我们更详细地了解两种最常见的 HTTP 方法 - GET 和 POST。

HTTP 获取

HTTP GET 请求允许您通过 URL 检索数据。GET 请求不会在调用 API 时发送请求正文。

这是 Contentful 内容交付 API 的 URL，用于请求单个 Contentful 空间的信息。Contentful 空间就像一个存储 Contentful 内容的存储桶，它具有名称和唯一 ID。请注意/spaces/URL 的一部分，它定义了我们请求的是空间信息。

https://cdn.contentful.com/spaces/{space_id}?access_token={access_token}

URL 需要两部分数据。URLspace_id的一部分是 ，它是我们想要从数据库中获取信息的空间的唯一标识符。URLaccess_token查询参数以 为前缀?，是一个身份验证令牌，用于告知 API 我们有权发出此请求。后端在收到请求时会验证此令牌。设置 Contentful 空间时，系统会指示您通过 Web 应用生成访问令牌，以便与 Contentful API 进行通信。您可能听说过身份验证令牌或类似的凭证，也称为 API 密钥。

通过在浏览器中导航到此 URL 来查看 Contentful Delivery API 的工作原理：https://cdn.contentful.com/spaces/84zl5qdw0ore ?access_token=_9I7fuuLbV9FUV1p596lpDGkfLs9icTP2DZA5KUbFjA

此特定 URL 使用相应的空间 ID 和访问令牌，请求有关支持Next.js 入门博客的Contentful 空间的信息。您应该会看到以下数据返回到您的浏览器。API 已成功以 JSON 格式返回您通过 URL 请求的数据。

{
  "sys": {
    "type": "Space",
    "id": "84zl5qdw0ore"
  },
  "name": "[Live] nextjs-blog-starter",
  "locales": [
    {
      "code": "en-US",
      "default": true,
      "name": "English (United States)",
      "fallbackCode": null
    },
    {
      "code": "fr",
      "default": false,
      "name": "French",
      "fallbackCode": "en-US"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

使用 JavaScript 发出 HTTP GET 请求

这是通过 JavaScript 中的 fetch 发出的与上述相同的 GET 请求。GET 是 fetch 中的默认 HTTP 方法，因此无需在代码中指定。

const response = await fetch( "https://cdn.contentful.com/spaces/84zl5qdw0ore?access_token=_9I7fuuLbV9FUV1p596lpDGkfLs9icTP2DZA5KUbFjA",
).then((data) => data.json());

console.log(response);
Enter fullscreen mode Exit fullscreen mode

这是浏览器控制台中的输出，与我们上面在浏览器中看到的内容一致。

浏览器控制台日志输出显示从 API 接收的数据空间数据。

正如 EDSAC 早期的例子一样，优秀的 API 应该有完善的文档。API 文档描述了每个 API URL（或端点）的功能、如何以正确的格式发送数据，以及 API 期望返回哪些数据。

这是来自 Contentful Content Delivery API 文档的屏幕截图，展示了如何请求有关 Contentful 空间的信息。

Contentful 文档的屏幕截图，显示了空间 GET 请求的代码示例、请求所需的参数以及示例响应。

请注意，文档指定：

  • 执行成功请求所需的参数
  • HTTP 请求的类型（GET、POST 等）
  • 请求的 URL
  • 成功呼叫的预期响应

本文档还提供了使用不同编程语言以及不同 Contentful 工具（例如 SDK 和客户端库）格式化请求的示例。您可以使用本文档页面上的下拉菜单查看您的选项。

HTTP POST

POST 请求要求数据通过请求正文发送，而不是作为 URL 参数发送。因此，无法使用浏览器的地址栏发出 POST 请求。这使得 POST 请求比 GET 请求更安全，并且应始终用于处理敏感数据的 API 操作，例如发送登录请求。

使用 JavaScript 发出 HTTP POST 请求

以下是一个使用 JavaScript 中的 fetch 函数的 POST 请求示例。此示例向 Contentful GraphQL API 发送一个请求，请求获取 Contentful 空间 ID 为 84zl5qdw0ore 的博客文章总数。

你可能觉得通过发送数据来请求数据很奇怪——但 GraphQL 允许你在单个 HTTP 调用中创建、更改和获取数据。这就是为什么 POST 方法是首选方式，因为你肯定不想用 GET 请求来更新数据！这也是一个使用 JavaScript fetch 在请求中发送额外 HTTP 标头的示例（请参阅下面示例中的授权和内容类型）。

const response = await fetch(
  `https://graphql.contentful.com/content/v1/spaces/84zl5qdw0ore`,
  {
    method: "POST",
    headers: {
      authorization: "Bearer _9I7fuuLbV9FUV1p596lpDGkfLs9icTP2DZA5KUbFjA",
      "content-type": "application/json",
    },
    body: '{"query":"{ blogPostCollection { total } }"}',
  },
).then((response) => response.json());

console.log(response);
Enter fullscreen mode Exit fullscreen mode

如果您想了解有关 GraphQL 如何工作的更多信息（它非常酷！） -请查看我们开发者门户上的 GraphQL 视频课程。

就这样结束了！

现在您知道了什么是 API、API 如何通过 HTTP 工作以及通过 GET 和 POST 请求发送和接收的内容，请尝试使用您喜欢的编程语言探索Contentful REST API和Contentful GraphQL API，将您的知识付诸实践。

如果您有任何疑问，请加入Contentful 社区 Slack，我们将很乐意为您提供帮助。

最后，如果你用 Contentful 构建了让你感到自豪的作品，请在 Twitter 上使用标签#BuiltWithContentful告诉我们。祝你构建愉快！

文章来源：https://dev.to/whitep4nth3r/what-is-an-api-587c
Devto 翻译
PREV
何时在 HTML 中使用 aria-labels
NEXT
什么是 REST API？