理解 API：10 个 API 概念和示例

2025-05-25

理解 API：10 个 API 概念和示例

作为一名开发者或技术人员，您可能听说过“API”。听到这个术语可能会让您感到好奇。想象一下，您正在使用一项需要从另一台服务器获取数据的服务。API 通过充当数据和应用程序之间的桥梁来实现这一点。

本文将通过解释可应用于 API 开发周期的基本概念和实践来阐明 API。在开始使用 API 之前，您应该了解以下信息：😂👇

一个人不尝试模因

⭐️ 你会考虑在 GitHub 上给我们一个 star 吗？⭐️

您将从本文中学到什么？

  • 对 API、其关键概念及其在开发周期中的重要性有基本的了解。

  • API 的类型及其基本原理。

  • API 开发的最佳实践

  • 您可以在其中试验 API 的工具或平台。

介绍

API 是现代开发的基础组件之一。它们实现了应用程序与数据之间的无缝交互。使用 API，开发人员无需手动提供应用程序与数据之间的通信，即可轻松高效地进行交互。

无论您是构建 Web 应用程序、移动应用程序还是集成服务，API 对于允许应用程序中的不同组件无缝连接您的数据都至关重要。

什么是 API？

API（应用程序编程接口）是一个由一系列命令、函数和协议组成的框架，用于实现不同应用程序之间的交互。其主要目的是定义开发人员可以用来与其软件组件交互的方法和数据结构。

把 API 想象成餐厅里的服务员；你告诉服务员（API）你想要什么，他们会把食物（服务器）送到厨房，然后把食物（数据）送回给你。这就是它的工作原理！

服务器模因

API 作为链接，接收来自应用程序的请求，从服务器获取必要的数据，然后将处理后的数据返回给应用程序。

API 的类型

针对不同的用例和用途，API 的类型也有所不同。了解 API 的类型有助于开发人员根据自己的特定需求选择合适的 API。以下是最常见的 API 类型：

  • 公共或开放 API：这些 API 向任何开发人员公开开放，几乎没有或没有任何限制，使开发人员能够访问服务的数据和功能。

    一个很好的例子就是一些随机 API 平台，它提供了许多可以免费使用的 API 端点。

  • 内部或私有 API：其主要目的是团队协作。它们通常不向外部开发人员开放，用于集成团队或组织内部的系统和服务。只有获得 API 访问权限的开发人员才能使用它们。

    API 私有化的原因有很多。有些是为了保护敏感数据，有些是为了加速业务开发，有些是为了增强内部工作流程。如果您正在开发大型应用程序，最好通过私有化来保护您的 API。

  • 合作伙伴 API：这是私有 API 的示例；它们不对外开放。然而，它们是专门为外部合作伙伴设计的。访问权限通常通过合同协议授予，允许合作伙伴集成和访问某些功能或数据。

既然您已经了解了主要的 API 类型，最好了解它们如何应用以及在何处应用。不同类型的 API 有不同的用途，并且最适合某些特定的项目。

REST API

REST（表述性状态转移）或RESTful API 是构建和与 Web 应用程序交互的规则。它们依赖于标准 HTTP 方法和协议来实现客户端和服务器之间的通信。

REST API 的设计理念是简洁、可扩展且无状态，这使得它们在 Web 和移动应用中广受欢迎。与典型的 API 不同，RESTful API 并非一种协议，而是利用协议进行交互。

海绵宝宝表情包

当客户端请求时，服务器会响应请求的数据。就是这么简单！

REST API 的原则

RESTful API 遵循一些架构原则；其独特的架构构成了一切，确保其高效易用。以下是一些 REST API 的独特原则：

  • 无状态：客户端向服务器发出的每个请求都必须包含理解和处理该请求所需的所有必要信息。服务器不存储任何与客户端相关的会话状态。

    这有助于简化服务器架构，因为它无需管理和存储会话信息，从而提高应用程序的可扩展性。此外，它还有助于提供准确的信息。

  • 客户端-服务器架构：在 REST API 中，客户端和服务器是独立的组件，通过请求和响应进行交互。客户端负责用户界面和用户体验，而服务器负责管理数据存储。

  • 统一接口：REST API 遵循一致的方式访问资源。这包括使用 HTTP 方法（例如GET、POST、PUT和 ）DELETE访问和操作 URI（统一资源标识符）。这使得 REST API 更易于理解和访问，因为开发人员可以依赖他们熟悉的模式。

  • 可缓存性：这是大多数开发者都喜欢的 RESTful API 原则之一。使用 REST API，来自服务器的响应会被标记为可缓存或不可缓存。缓存可以减少客户端与服务器的交互次数并提高性能。

    这通过减少不必要的网络调用、降低延迟并提高整体性能来提高效率。

RESTful API 拥有完善的结构，在当今的开发周期中被广泛使用。其主要特征在于其原则，而这些原则正是 REST API 的本质所在。

骑自行车 Rest API meme
图片来源：Phil Sturgeon

SOAP API

SOAP（简单对象访问协议）API 是一种用于在 Web 应用程序中交换结构化信息的协议。与使用简单 HTTP 方法的 REST 不同，SOAP 利用 XML 作为其消息格式，并遵循更复杂的结构。

SOAP API 严格用于 Web 应用程序，并具有内置命令以确保消息的安全，使其适合安全性要求严格的应用程序。

REST 和 SOAP 之间的区别

从上面的定义可以看出， REST和SOAP之间存在明显的区别。虽然两者都用于 Web，但它们在架构、标准等方面仍然存在差异。以下是一些区别：

  • 协议 VS 架构风格：

    • SOAP：一种具有标准和规则的协议。
    • REST：一种使用标准 HTTP 方法和协议进行 Web 应用程序和数据之间交互的架构风格。

  • 消息格式：

    • SOAP：使用 XML 进行消息格式化。
    • REST：使用 JSON，但也可以使用 XML、HTML 或纯文本进行消息格式化。

  • 复杂性：

    • SOAP：由于其标准和 XML 消息传递，它变得更加复杂。
    • REST：更简单、更灵活、更易于实现。

  • 运输：

    • SOAP：可以使用各种协议（HTTP，SMTP等）。
    • REST：通常使用 HTTPS 进行通信。

嫉妒的女友表情包

通过了解该协议和架构风格之间的差异，开发人员可以根据其特定应用程序的需求选择合适的协议。

JSON 和 XML

JSON（JavaScript 对象表示法）和XML（可扩展标记语言）是标准的 API 通信数据格式。这些格式的主要用途相同：对服务器和客户端之间的数据结构进行编码，以便双方都能理解。

JSON

JSON是一种源自 JavaScript 的轻量级数据交换格式。它易于人类阅读和编写，也易于机器解析和生成。

XML

XML是一种标记语言，它定义了以人类和机器可读的格式编码文档的结构。XML 主要以其处理复杂数据结构的能力而闻名。

JSON 和 XML 之间的区别

  • 可读性：

    • JSON：语法更易读，适合快速交互，并且更方便开发人员访问。
    • XML：语法更复杂，最适合表示复杂的数据结构和文档。

  • 尺寸：

    • JSON：更紧凑、更轻量。数据传输更快，带宽占用更少。
    • XML：由于大量使用 markdown 标签而变得更大。

  • 数据类型：

    • JSON：支持字符串、数字、数组、对象等数据类型。
    • XML：所有数据都以文本形式编写，需要针对特定​​的数据类型进行解析。

  • 解析和性能：

    • JSON：由于兼容性，解析速度更快，特别是在 JavaScript 环境中。
    • XML：解析和处理速度较慢，需要更多资源。

  • 架构支持：

    • JSON：JSON 模式可用，但不如 XML 模式广泛。
    • XML：XML 模式对于验证文档结构和数据类型非常强大。

使用 API 时，您可以使用任何您想要的数据格式进行通信。最好了解各种格式的区别，因为在 API 开发中没有“完美”的数据格式。您可以根据自己的需求选择其中任何一种。

何时使用

在某些情况下，您可以使用 JSON 作为数据格式，有时也可以使用 XML。了解何时何地使用它们非常重要。

您可以在以下情况下使用JSON：

  • 您需要一种轻量级的数据格式。

  • 使用 Web API，尤其是在 JavaScript 环境中。

  • 简单和可读性至关重要。

  • 您正在处理更简单的数据结构，并且需要减少带宽使用。

您可以在以下情况下使用XML：

  • 您想要处理复杂的数据结构。

  • 需要验证数据格式和结构。

  • 使用需要大量元数据和描述性数据的应用程序。

  • 数据交换需要高度可扩展和自描述。

通过了解 JSON 和 XML 的优势和使用情况，开发人员可以根据其应用程序的需求决定使用哪种数据格式。

API 端点

在本文的这一点上，您可能想知道 API 端点是什么，因为您可能在本文中多次遇到过“API 端点”这个术语。

API端点是一个 URL，客户端可以通过该 URL 访问 API 并执行检索、更新或删除数据等操作。端点代表 API 提供的功能和服务。

端点允许 API 与您正在处理的应用程序进行交互，从而实现通信和信息交换。它们可以通过 HTTP 方法（例如GET、POST、PUT和DELETE）进行访问，这些方法定义了将要执行的操作类型。

API 端点示例

让我们考虑一个用于在 Web 应用程序中管理学生信息的 REST API 示例。该 API 的基本 URL 可以是https://api.example.com。现在，让我们看看其他端点和响应。

  • 检索学生名单：

    • 端点：https://api.example.com/students
    • HTTP 方法：GET
    • 目的：检索系统中所有注册学生的列表。

    • 要求：

      GET https://api.example.com/students

      以下是您收到的回复：

      [
  {
    "id": 1,
    "name": "Opemipo Disu",
    "email": "opemipo.disu@school.com"
  },
  {
    "id": 2,
    "name": "Ralf Endrick",
    "email": "ralf.endrick@school.com"
  }
]

      在此示例中，我们使用 GET 方法从系统中检索信息。之后，它以 JSON 格式返回我们从端点请求的数据。

另一个示例是用于在系统中注册学生的端点。让我们创建它并查看它的响应。

  • 添加新学生：

    • 端点：https://api.example.com/students
    • HTTP 方法: POST
    • 目的：向管理系统添加新学生。

    • 要求：

      POST https://api.example.com/students
Content-Type: application/json

{
  "name": "Opemipo Disu",
  "email": "opemipo.disu@student.com"
}

      回复：

      {
  "id": 1,
  "name": "Opemipo Disu",
  "email": "opemipo.disu@student.com"
}

      在这种情况下，您会注意到我们正在使用https://api.example.com/students端点，主要是因为我们想向系统添加一个新学生；访问用户的唯一方式是使用该端点，因为它应该包含与学生相关的信息。

现在，我们来考虑删除某个学生的信息。具体操作如下：

  • 删除学生信息

    • 端点：  https://api.example.com/students/{id}
    • HTTP 方法：DELETE
    • 目的：通过学生 ID 删除学生。

    • 要求：

        DELETE https://api.example.com/students/1

      回复：

        {
    "message": "Student deleted successfully."
  }

    当您想使用 API 删除学生信息时，通过 API 端点中的 ID 寻址特定数据可确保您定位到正确的记录。

通过了解端点的工作原理并查看一些示例，开发人员还可以使用 API 与 Web 应用程序交互并执行各种操作。

HTTP 方法

HTTP 方法定义了对 API 端点所标识的资源执行的操作。我们有近 40 种已注册的 HTTP 方法，但以下是最常见的四种：

  • 得到
  • 邮政
  • 放
  • 删除

现在，我们将深入介绍这些方法的用途，并为四种最常用的 HTTP 方法分别提供一个示例。

得到

GET方法  从服务器检索数据，但不对服务器数据进行任何更改。

之前在检索学生信息的端点中展示了其工作原理的一个示例。

再次举一个例子：

要求：

GET https://api.example.com/students
Enter fullscreen mode Exit fullscreen mode

回复：

[
  {
    "id": 1,
    "name": "Opemipo Disu",
    "email": "opemipo.disu@school.com"
  },
  {
    "id": 2,
    "name": "Ralf Endrick",
    "email": "ralf.endrick@school.com"
  }
]
Enter fullscreen mode Exit fullscreen mode

如上所示，GET 方法用于从端点检索以 JSON 格式显示的数据。

邮政

POST方法  将数据发送到服务器以创建新资源。与用于检索数据的 GET 方法不同，POST 方法将数据提交到服务器。GET 方法依赖于 POST 方法发送到服务器的数据。

前面已经解释了如何使用 POST 方法的一个例子。学生注册的例子就是一个使用 POST 方法的典型例子。

如果您错过了，请再看一遍。

要求：

POST https://api.example.com/students
Content-Type: application/json

{
  "name": "Opemipo Disu",
  "email": "opemipo.disu@student.com"
}
Enter fullscreen mode Exit fullscreen mode

我们使用 POST 方法发送了一个请求。因为我们想将学生的信息添加到服务器。

这是我们这样做得到的回应：

{
  "id": 1,
  "name": "Opemipo Disu",
  "email": "opemipo.disu@student.com"
}
Enter fullscreen mode Exit fullscreen mode

在上面的响应中，POST 方法自动创建并注册了新学生。这就是 POST 方法的工作原理。

放

此方法用于使用新数据更新现有资源，或如果资源不存在则创建新资源。它使用请求中提供的数据替换资源的当前信息。

让我们以使用 PUT 方法更新学生信息为例。

要求：

PUT https://api.example.com/students/1
Content-Type: application/json

{
  "name": "Opemipo Hay",
  "email": "opemipo.hay@student.com"
}
Enter fullscreen mode Exit fullscreen mode

回复：

{
  "id": 1,
  "name": "Opemipo Hay",
  "email": "opemipo.hay@student.com"
}
Enter fullscreen mode Exit fullscreen mode

在这种情况下，我们必须使用其 ID 来定位我们想要更新的信息。我们使用了 PUT 方法并添加了我们想要更新的数据。

删除

此方法用于删除现有资源。当发出 DELETE 请求时，服务器将删除 URI 所标识的资源。

为此，我们将以通过学生 ID 删除学生信息为例。

要求：

DELETE https://api.example.com/students/1
Enter fullscreen mode Exit fullscreen mode

回复：

{
  "message": "Student's information deleted successfully"
}
Enter fullscreen mode Exit fullscreen mode

在请求中，我们使用 DELETE 方法根据用户 ID 删除了用户信息。之后，我们收到了“学生信息删除成功”的响应。

HTTP 状态代码

HTTP 状态代码是服务器返回的响应，用于指示客户端请求的结果。它们通过向服务器显示客户端请求的结果，在 API 通信中发挥着至关重要的作用。

以下是一些常见的 HTTP 状态代码：

  • 200
  • 400
  • 500

200（正常）

当收到此响应时，表示请求成功，服务器返回请求的数据。

例如，当成功收到检索数据的 GET 请求时，您可以获取此响应。这会在 开发者控制台 的 “网络”标签页中指示 操作已成功，并且服务器已按预期处理该请求。

400（未找到）

当服务器找不到请求的资源或数据时，您会收到此响应。这可能是因为数据未正确获取，或者资源不存在。

举个例子，当你请求 GET 一个不存在的用户时，就可能会出现这个错误。我们来快速看一下：

要求：

GET https://api.example.com/users/583
Enter fullscreen mode Exit fullscreen mode

回复：

{
  "status": 404,
  "message": "Resource not found"
}
Enter fullscreen mode Exit fullscreen mode

由于假定的端点中没有资源，因此响应出现错误。

抄袭答案 meme

500（内部服务器错误）

当您收到此响应时，表示服务器遇到了意外情况，导致其无法完成请求。

当处理请求时发生服务器端错误时，您可能会收到此响应。

要求：

POST https://api.example.com/students
Content-Type: application/json

{
  "name": "Opemipo",
  "email": "opemipo.disu@example.com"
}
Enter fullscreen mode Exit fullscreen mode

回复：

{
  "status": 500,
  "message": "Internal server error"
}
Enter fullscreen mode Exit fullscreen mode

500内部服务器错误表示一般的服务器端错误。它表明服务器出现了问题，不一定是由于客户端的请求造成的。

虽然还有其他一些 HTTP 状态代码，但您可以阅读本文来了解更多信息。本文介绍的是最常见的状态代码。

身份验证和授权

虽然 API 安全至关重要，但身份验证和授权是 API 安全的关键组成部分。API 开发中的身份验证是验证用户或应用程序身份的过程，通常通过 API 密钥、OAuth 令牌或用户凭据等技术来实现。

另一方面，授权决定了经过身份验证的实体可以访问哪些资源或操作。

这些流程确保只有有效的用户或应用程序可以访问 API 并根据其权限执行操作。

API 密钥和 OAuth 的基本概念

API密钥是用于验证与项目或应用程序相关的请求的唯一标识符。

API 密钥包含在 API 请求中，用于识别调用项目或应用程序。它们通常用于跟踪和控制 API 的使用方式。API 密钥应妥善保管，不得在代码中暴露，以防止未经授权的访问。

但是，它们并不安全，应该与其他安全措施（例如环境变量）一起使用。

另一方面，OAuth（开放授权）是一个基于令牌的身份验证框架，允许第三方应用程序访问用户数据而无需暴露用户凭据。

它被 Google 和 GitHub 等平台广泛用于授予对用户数据的有限访问权限。它涉及一个流程：用户授权应用程序，应用程序收到可用于发出授权 API 请求的访问令牌。与 API 密钥相比，它提供了一种更灵活、更安全的方法。

API 安全的重要性

  • 防止未经授权的访问：身份验证确保只有用户和应用程序可以访问 API，从而防止未经授权访问敏感数据。

  • 速率限制：身份验证有助于跟踪 API 的使用情况，从而实现速率限制以防止数据滥用。

  • 监控：身份验证允许详细记录和监控 API 使用情况，这对于识别错误至关重要。

速率限制和节流

API 使用速率限制来确保稳定和安全。这意味着它们会限制用户或应用程序在一定时间内可以发出的请求数量。这有助于防止服务器过载。

它还确保应用程序中的所有用户都能平等分配 API 资源。

为了管理速率限制，应用程序应在达到限制时逐渐增加重试之间的等待时间。请监控您的 API 使用情况，以确保不超出这些限制。如果您存储了常用数据，则可以减少发出的请求数量。

使用页码和过滤器可以帮助您更快地管理大型数据集，从而减少 API 的负载。

测试 API

在 API 开发过程中，测试 API 至关重要，它可以确保您的应用程序与服务器正确通信并按预期处理数据。专用工具可让您在开发周期的早期发出 API 请求、检查和分析响应以及记录问题。

让我们探索一些用于测试 API 的最佳工具，并提供使用这些工具有效测试 API 的基本指南。

API 测试工具

  • Postman： Postman 是一款简化 API 开发的工具。它允许您构建和发送请求、将 API 组织成集合、自动化测试以及生成详细的报告。

    Postman 非常适合手动和自动测试，它支持各种 HTTP 方法，因此测试起来非常灵活。

  • cURL ：此命令行技术支持通过 URL 进行数据传输。

    使用 cURL 主要是因为它的可访问性和灵活性，特别是对于熟悉命令行的开发人员来说。

  • Swagger： Swagger 提供了一套用于 API 文档和测试的工具。它允许您可视化并与 API 资源进行交互，而无需手动创建请求。

API 测试指南

  1. 定义端点和方法

    • 确定您想要测试的 API 端点和要使用的 HTTP 方法（GET、POST、PUT、DELETE）。

    • 示例：要获取用户数据，您可以使用：

        GET https://api.example.com/users

  2. 设置请求

    • Postman：打开 Postman，创建一个新的请求，输入端点 URL，并选择 HTTP 方法。添加必要的标头，例如 API 密钥和参数。

      对于检索用户的 GET 请求，只需设置 URL https://api.example.com/users 并包含任何所需的标头或参数。

  3. 发送请求

    • 在 Postman 中单击“发送”以执行请求并观察响应。

  4. 分析响应

    • 状态代码：表示请求的成功或失败（例如，200 OK、404 Not Found）。
    • 标题：提供有关响应的元数据。
    • Body：包含 API 返回的数据，通常为 JSON 或 XML 格式。
    • 示例：成功的 GET 请求可能会返回状态代码 200 和包含用户数据的 JSON 主体。

  5. 处理错误

    • 如果请求失败，请分析状态代码和错误消息来诊断问题。
      • 示例：  404 状态代码 表示端点不正确或资源不存在。
    • 相应地调整请求并重试。

  6. 自动化测试

    • Postman 支持脚本自动化测试。您可以编写预请求脚本来设置条件，也可以编写测试脚本来验证响应。

      • 示例：要验证响应是否成功，请在 Postman 的“测试”选项卡中添加以下脚本：

          pm.test("Status code is 200", function () {
      pm.response.to.have.status(200);
  });

通过利用 Postman、cURL 和 Swagger 等工具，您可以简化 API 测试流程，确保您的应用程序可靠、高效地与外部服务交互。

结论

对于任何刚入门的开发者来说，了解 API 都至关重要。它们是现代开发的重要组成部分，能够实现应用程序之间的无缝通信和数据交换。

本文介绍了 API 的基本概念，包括其类型、REST 和 SOAP API 的关键原则、JSON 和 XML 等数据格式，以及 API 端点和 HTTP 方法的重要性。

此外，我们还通过身份验证和授权探索了 API 安全性的各个方面，以及速率限制和节流的重要性。

如果您觉得本文有帮助，请考虑在 GitHub 上给我们一个 star

⭐ 您考虑在 GitHub 上给我们一个 Star 吗？⭐

谢谢你

您的支持有助于我们不断改进，并为开发者社区提供有价值的内容。感谢您阅读本文至此💙！

文章来源：https://dev.to/latitude/understanding-apis-10-api-concepts-and-examples-23cn
Devto 翻译
PREV
无术语指南 – 文章 1 – Git 和 GitHub 真正有趣的东西……
NEXT
面向开发人员的快速工程：11 个概念和示例🎯🧙‍♂️⚡