软件应用程序在许多方面使我们的生活变得更轻松、更美好。我们几乎每天都在使用它们，有些人发现自己使用应用程序的频率甚至超过了与他人交互的频率。

但是，应用程序之间是如何交互的呢？那么，它们是通过 API（应用程序编程接口）来实现的。在本文中，您将了解什么是 API。

什么是 Web API？

Web API 是一种设计用于网络的 API。换句话说，基于网络的软件应用程序、系统和服务使用 Web API 在互联网上交换信息。它们通常以 JSON 或 XML 等格式发送请求和接收响应。

Web API 在现代软件开发中发挥着至关重要的作用，原因如下：

  1. 互操作性：API 与技术无关，这意味着它们允许不同的软件系统相互通信，而不受技术堆栈的限制。这使开发人员能够无缝集成各种应用程序。
  2. 可扩展性：Web API 支持模块化开发，使应用程序的不同组件能够独立构建、调试和扩展。这大大提高了系统的可扩展性。

  3. 灵活性和可扩展性: 通过遵循标准实践和明确定义的规则，Web API 帮助应用程序扩展其功能。它们足够灵活，允许开发人员创建动态应用程序。

开发 Web API 的方法

基于需求，可以采用各种方法开发 Web API。以下是一些常见的开发方法：

  • REST – 代表性状态转换（REST）API 使用 HTTP 协议执行操作。它们以无状态方式运行，意味着每个请求都必须包含接收者处理和响应所需的所有必要信息。

  • SOAP – 简单对象访问协议（SOAP）使用 XML 以结构化方式交换信息。

  • GraphQL – 用于查询和操作 API。
  • gRPC – 远程过程调用框架，使用 HTTP/2 传输信息。

在接下来的章节中，我们将探讨 API 的设计和开发，重点讨论 REST API 这一核心协议。

了解需求和目标

在任何软件开发过程中，在开始之前了解需求和预期用例至关重要。这有助于您计划和估算项目所需的成本、时间和其他资源。

在构建 RESTful API 时也是如此。您需要确定应用程序是否将以无状态的方式交换信息，所涉及的实体是否可以表示为资源，以及服务是否足够灵活以处理不同的数据格式。

定义资源和端点

REST API 围绕 资源展开，资源是表示系统中数据或对象的实体。每个资源由一个称为 资源标识符的唯一 URI 标识。这些资源可通过 端点进行访问和操作，端点是接收和处理客户端请求的特定 URL。

最佳实践建议在端点中使用名词来表示资源，而不是可能表示对资源进行操作的动词。

请看下面的示例：https://api.example.com/products

该端点遵循使用名词表示资源的最佳做法（在本例中为 products）。注意到我是如何使用复数形式 – 产品的吗？如果您处理的是对象集合，使用复数形式也是明智的。

但是，不建议使用下面的端点 https://api.example.com/add-product ，因为它使用了动词，并试图描述对资源的操作。

标准端点命名约定的另一个重要方面是使用分层结构。这有助于清晰地表示资源之间的关系。

例如：https://api.example.com/categories/{categoryId}/products/{productId}。
在这里，我们定义了一个在 category 和 product 资源之间保持清晰层次结构的端点。

使用 HTTP 方法和状态代码

在 REST API 中，HTTP 用于客户端和服务器之间的通信。HTTP 具有标准方法，主要用于对资源执行操作。下面列出了这些方法及其用途：

  • GET – 获取资源的详细信息。服务器会在响应消息正文中返回这些详细信息。

  • POST – 创建一个新资源。要创建的资源详细信息在请求消息体中发送。

  • PUT – 根据可用性创建或更新资源。要创建或更新的资源详细信息在请求消息体中发送。

  • DELETE – 删除一个资源。

  • PATCH – 部分更新资源。对资源所做的更改在请求消息体中发送。

开发定义良好的REST API的建议方法是正确使用这些HTTP方法来执行对应资源的CRUD（创建、读取、更新、删除）操作。同时，您还需要确保API在响应消息体中对客户端返回适当的HTTP状态码。

状态码反映了请求的结果。以下是一些您可以使用的常见HTTP状态码：

  • 200 OK

  • 201 Created

  • 204 No Content

  • 400 Bad Request

  • 401 未授权

  • 403 禁止访问

  • 404 未找到

  • 500 服务器内部错误

  • 503 服务不可用

  • 504 网关超时

请使用合适的HTTP状态码准确地表示API端点处理请求的结果。您还可以实现自定义HTTP状态码来描述特定于应用程序的行为。

版本控制策略

随着时间的推移，您开发的API将发生变化，您将对其进行修改。这就是版本控制策略变得重要的地方。您必须确保已经使用您的API的客户端不会受到您所做的更改的影响。

维护不同版本将使您的API向后兼容，并允许客户端根据他们的需求使用他们偏好的API版本。Postman网站上的这篇有益的博客文章解释了何时版本化您的API是理想的：

“你应该在每次更改API，需要消费者修改他们的代码库以继续使用API时，为API进行版本控制。这种类型的更改称为“破坏性更改”，它可能涉及到API的输入和输出数据结构、成功和错误反馈以及安全机制的更改。

API版本控制可以通过不同的方式进行。以下是一些方法：

  • URI版本控制：在URL路径中包含版本号。例如，https://api.example.com/v1/products。

  • 查询参数版本控制：在URL中将版本号指定为查询参数。例如，https://api.example.com/products?version=1。

  • 头部版本控制：在请求的HTTP头中包含版本号。例如，使用自定义头如X-API-Version: 1。

  • 内容协商：在请求的Accept头部指定版本，通常使用媒体类型。例如，Accept: application/vnd.example.v1+json。

  • 嵌入式版本控制：在响应的媒体类型中嵌入版本号。例如，application/vnd.example.product-v1+json。

安全考虑

在开发API时考虑安全性的另一个重要方面。以下是一些关键点：

  1. 实现HTTPS以加密客户端和服务器之间交换的信息。

  2. 实现认证和授权，以确保只有具有适当权限的用户可以对资源执行操作。常见方法包括基本认证、令牌认证（Bearer或Token）、JWT和OAuth 2.0。还应实现基于角色的访问控制来管理资源访问。

  3. 实现输入验证和清理，以防止SQL注入和跨站脚本攻击（XSS）等漏洞攻击。

  4. 实现速率限制和节流，以控制客户端在特定时间框架内对服务器发起的请求数量。这有助于防止服务器过载。

文档

API开发的一个关键但常被忽视的方面是文档。确保API文档化对于用户理解其功能和实用性至关重要。

文档必须全面、易于理解，并遵循标准实践。包括请求和响应体的示例、使用的HTTP状态代码等。您可以遵循Open API规范来描述您的RESTful API。

排序、过滤和分页策略

如果您开发的 API 返回的记录过多，可能会导致性能问题。

要解决这个问题，您应该启用记录的排序和筛选功能。

监控使用情况、日志和健康状况

记录 API 请求和响应以帮助调试是一个好主意。监控 API 的使用情况将有助于您了解应用程序的整体性能和行为。定期进行健康检查可帮助您在出现任何问题时采取必要的措施。

结论

API（特别是 Web API）对于软件应用程序通过 Internet 进行通信至关重要。

本文介绍了什么是 Web API、为什么它们很重要以及开发它们的不同方法，重点是 REST API。您还了解了一些关键主题，如定义资源和端点、使用标准 HTTP 方法和状态代码、版本管理策略、安全注意事项、文档等。

如果您对本文感兴趣，请随时查看我在 freeCodeCamp 上的其他文章，并在 LinkedIn 上与我联系。