告别混乱的 API！这里有一份你的整洁代码指南🚀

API和RESTful API是每个程序员都应该熟悉的基本概念。在设计 API 时，需要满足一些基本要求，以确保系统之间高效、有效的交互。

如果您还不熟悉API是什么，或者还没有掌握 RESTful API 的概念，请花 5 分钟继续阅读。我会用简单易懂的方式解释一切。

❓ 什么是 API？

• 一个简单的例子就可以清楚地说明这一点：
  • 2000年，网上购票开始兴起，但当时大多数人还是依靠电话查询航班。最初，人们会打电话到当地车站询问航班或火车时刻表。收到信息后，再去相应的车站购票。

• 随着科技的快速进步和智能手机的广泛使用，各种旅行App纷纷涌现，教大家如何通过这些App购买机票。

• 现在，购票变得简单多了。只需在App中输入出发地和目的地，即可查看所有相关的火车和航班选项。您不仅可以获得时刻表和座位信息，还能获得航空公司、预计行程时间等详细信息，这些信息都以清晰简洁的方式呈现。您可以根据自己的具体需求轻松购票。

• 连接是一件很奇妙的事情。在当下的生活中，我们可以通过各种App轻松购物、阅读、观看直播，以前所未有的方式与世界、与人建立联系。
• 那么这一切是如何实现的呢？是什么让一个应用程序如此便捷？信息是如何从A点传递到B点，让我们只需轻轻一划就能完成所有事情的？
• 实现这一切的桥梁——互联网世界的无名英雄——是 API。API 的全称是应用程序编程接口 (API)。简单来说，它是由品牌开发的接口，允许第三方创建附加功能并将其集成到自己的产品中。
• 回到前面提供的例子：
  • 过去，如果我们想了解航班信息，就需要一个信使。电话接线员就充当了这个信使，或者我们称之为 API。他们会将您的请求传达给系统。例如，如果您询问第二天飞往纽约的航班，接线员就会检索该信息并将其转发给您。
  • 现在，当我们需要购买机票时，只需与预订系统交互，即可选择日期、城市和舱位偏好。该系统从各家航空公司网站收集数据，并通过与航空公司交互的 API 来汇总这些信息。
• 我们现在明白，正是 API 使我们能够使用这些旅行应用程序，并且这一原则普遍适用于生活各个方面应用程序、数据和设备之间的交互。每个系统都使用自己的 API 来相互建立连接。

❓ 什么是 RESTful API？

• 在互联网发展的早期，当它尚未完全成为主流，移动设备也尚未普及时，对 API 的需求相对较低。当时，由于页面请求量和并发用户数有限，Web 应用程序主要在服务器端运行，使用复杂的协议进行数据操作和传输。
• 随着移动设备使用量的激增，通过这些设备访问 Web 应用程序的需求变得至关重要。这种转变标志着用户行为和期望的重大变化，需要客户端和服务器之间更高效的通信方式。此时，API 的作用变得至关重要，因为它们充当了移动设备与 Web 应用程序无缝交互的桥梁。

• 因此，一套开发简化、结构清晰、标准化、易于理解、可扩展的 API 对于获得广泛的接受度和可用性变得日益重要。RESTful API 风格完美地体现了这些特性，并因此逐渐在开发者和组织中兴起和流行。

休息

• REST 代表表述性状态转移 (Representational State Transfer)，它是一种设计风格和软件架构风格，而非严格的标准。它提供了一套设计原则和约束，用于指导网络应用程序的创建。REST 的目标是利用 Web 的特性（特别是 HTTP 协议）来创建可扩展且高效的服务。

REST 风格的

• RESTful 一词只是一个形容词，用来描述遵循 REST 原则的 API 或服务。例如，RESTful API 是一种能够体现 REST 所概述的特征和设计约束的 API。它确保 API 模仿 REST 架构，提供可预测且标准化的交互模式。

RESTful API

• 我们通常遇到的常见API是这样的：

• 然而，RESTful API 看起来像这样：

💡 六项原则

• Roy Fielding是 HTTP 协议的主要架构师之一。在他的论文中，他详细阐述了 REST 架构的概念，并概述了其六个约束，通常称为六大原则。这些原则可作为构建 RESTful API 的指南，并有助于提升其功能性和可扩展性。让我们仔细看看每个原则：

统一接口

• 正如我们之前看到的两张图，API 最直观的特征就是它遵循 REST 架构的原则。对于 RESTful 服务来说，统一的接口至关重要。客户端只需要关注接口的实现，这增强了 API 的可读性，方便用户访问。

• RESTful API 通过 URL 定位资源，并通过 HTTP 方法操作这些资源。对资源的操作包括获取、创建、更新和删除，这些操作直接对应于 HTTP 协议的 GET、POST、PUT 和 DELETE。

  • GET：检索资源信息。
  • POST：创建一个新资源。
  • PUT：更新现有资源。
  • 删除：删除现有资源。

• 在完全遵循 RESTful 原则的团队中，后端只需要告知前端有关 /users API 的信息，而前端应该固有地理解以下操作：

  • 获取所有用户：GET /users
  • 检索特定用户：GET /users/{id}
  • 创建新用户：POST /users
  • 更新现有用户：PUT /users/{id}
  • 删除用户：DELETE /users/{id}

• 随着 API 数量的增长和系统日益复杂，RESTful 架构的优势愈发凸显。通过关注一系列资源，可以简化对系统的理解，从而提高理解力和记忆力。

客户端-服务器

• 这意味着客户端和服务器是独立的并且可以彼此分离。
• 客户端负责请求和处理数据，而服务器负责存储数据和处理请求。
• 这两个组件通过一组约定进行协作，以确保客户端能够有效地获取所需的数据。

无国籍

• 这是指每个请求都是独立的，与之前的请求没有任何关系的原则。服务器不维护任何关于客户端的状态信息，每个请求必须包含处理该请求所需的所有信息。
• 这种方法的好处是它简化了每个请求，使其易于理解和处理，并且更容易扩展和维护。
• 例如，假设您正在登录一个网站。您在登录界面输入用户名和密码，并通过 API 获取一个 token。从那时起，所有后续请求都必须携带此 token，而不是系统在第一次成功登录后就一直跟踪您的登录状态。

可缓存性

• 客户端和服务器可以协商可缓存的内容，从而允许服务器通过设置适当的 HTTP 状态代码来通知客户端是否可以缓存特定数据。
• 例如，HTTP 响应可能包含 Cache-Control 标头，用于告知客户端数据可以缓存多长时间。这可以提高数据传输效率，减少网络带宽占用，并加快数据访问速度。通过有效管理缓存内容，应用程序可以为用户提供更快的响应时间和更流畅的体验。

分层系统

• 客户端无需担心请求会经过多少个中间层；他们的主要关注点应该放在请求的结果上。一个设计良好的架构可以划分为多个层，每个层独立负责完成其特定的任务。这种分层方法可以使系统更易于维护，并允许独立替换或增强各个层。

• 例如，数据库存储层可以独立于架构中的其他层运行。这种独立性使开发人员能够在不影响其他层运行的情况下替换或扩展数据库层。这种模块化不仅简化了开发流程，还增强了系统的整体弹性和可扩展性。

按需编码

• 客户端不应该关心请求经过了多少个中间层；他们只需要关注请求的结果。

• 系统的架构可以分为多个层次，每个层次负责完成各自的任务。这种分层结构使得系统更易于维护，并且允许独立替换不同的层。

• 例如，数据存储层可以独立于其他层运行。这意味着它可以被替换或扩展，而不会影响其他层的功能。这种模块化设计有助于提高应用程序架构的可维护性和可扩展性。

🔥 RESTful API 设计指南

• 讨论了 RESTful API 的理论方面之后，现在是时候将注意力转向实际方面了：我们如何设计最简单的 RESTful 风格 API？

HTTP 方法

• HTTP 设计了各种动词来表示不同的动作，并且每种 HTTP 请求方法都有其自身的含义。如上所示，RESTful API 应该使用 HTTP 方法（例如 GET、POST、PUT 和 DELETE）来描述对资源的操作。

版本控制

• 版本控制是指在不影响现有客户端应用程序的情况下更新 RESTful API。常见的版本控制方法包括：

  • URL 方式：通过改变 URL 来表示不同的版本，例如https://api.example.com/api/v1/resources和https://api.example.com/api/v2/resources。
  • 接受标头：使用请求标头中的接受字段来指示所需的 API 版本。
  • 请求参数：通过请求参数指定版本，例如https://api.example.com/resources?version=1和https://api.example.com/resources?version=2。

• 不同的公司和团队可能会采用不同的 API 设计方法，但我认为保持版本控制方法尽可能简单直观至关重要。将版本信息直接放在 URL 中既直观又清晰，方便开发人员理解和使用。

  URL 清晰地标识资源

• API 应该使用简洁、清晰的 URL 来标识资源，同时使用不同的 HTTP 方法对同一资源执行各种操作。

• 这种设计使客户端无需额外信息或大量文档即可找到所需资源。清晰的 URL 为客户端提供了一种直接有效的 API 交互方式。

• 相比之下，不规则的 URL 形式多样，需要不同的开发人员深入研究文档才能理解如何与它们交互。非结构化的 URL 可能会导致开发过程中的混乱和效率低下。

• 遵循标准化的 RESTful URL 样式，可以形成固定的格式，从而增强可读性。通过清晰的名词和对应的 HTTP 动词，开发者可以轻松操作资源，从而在使用 API 时获得更直观的体验。

• 这里有一个小提示：如果你发现自己很难想出一个合适的 URL，你可以参考GitHub Open API。它拥有大量结构良好、组织有序的 URL 设计。

  HTTP 状态代码

• HTTP状态码是设计中至关重要的一部分RESTful API，它用于指示请求的状态API，并告知客户端请求是否成功以及数据是否被正确处理。一些常用的HTTP状态码包括：

  • 200 OK：请求成功，已检索请求的数据。
  • 201 Created：请求成功，导致新资源的创建。
  • 204 No Content：请求成功，但是没有数据返回，表明操作完成。
  • 400 错误请求：由于格式不正确或缺少必需参数，请求失败。
  • 401 未授权：由于身份验证问题或缺乏授权，请求失败。
  • 403 Forbidden：请求失败，因为客户端没有访问资源的权限。
  • 404 Not Found：请求失败，因为请求的资源不存在。
  • 500 内部服务器错误：由于内部服务器错误，请求失败。

• 这些状态代码可帮助客户端了解其请求的结果，并允许开发人员有效地处理错误和成功情况。

统一返回数据格式

• 常用的返回数据格式为RESTful APIsincludeJSON和XML。

  • JSON（JavaScript 对象表示法）目前是一种流行的数据格式，因为它简单、轻量且易于解析。其可读性使其在服务器和客户端之间频繁交换数据的 Web 应用程序中尤其受欢迎。
  • XML（可扩展标记语言）是另一种广泛使用的数据格式。它的优势在于灵活性和对各种数据类型的支持。XML 可以表示复杂的数据结构，有时在需要文档验证或更具描述性的格式的情况下更受欢迎。##### 结构良好且美观的 API 文档

• 在任何项目开发中，尤其是在实现前后端分离时，API 都扮演着至关重要的角色。因此，对 API 的依赖自然延伸到了维护更新且全面的 API 文档的重要性。然而，许多程序员发现创建文档非常繁琐，我甚至遇到过一些公司使用 Word 文档精心编写 API 文档的情况。

• 幸运的是，市面上有很多专门用于管理和记录 API 的工具。每个开发人员或团队可能都有自己的偏好，但我推荐一款名为 Apidog 的出色 API 管理工具。这款工具允许你只需单击几下即可生成 API 文档。

• Apidog最大的优点在于它显著简化了文档编写流程。您无需执行繁琐的操作，只需通过用户友好的可视化界面添加 API，该工具就会自动为您生成文档。

🌟 最后的想法

• 总而言之，虽然RESTful样式化 API 确实有效且结构良好，但许多互联网公司在设计 API 时并没有严格遵循其准则。这是因为REST它更像是一种风格，而非一套僵化的规则；过于理想化的实现RESTful APIs可能会导致巨大的成本和复杂性。

• 如果您正在考虑使用RESTful APIs，请确保它们符合您的业务需求。例如，如果您的项目需要复杂的数据交互，您可能需要探索能够更好地满足这些需求的其他 API 设计方法。

• 因此，在选择 API 设计方法时，务必充分考虑您的业务需求。此外，请确保RESTful API与您的系统架构和技术堆栈兼容。这些考虑将有助于确保 的正确使用RESTful APIs，最终实现更高效、更可靠的 API 性能。

• 从长远来看，API 设计不应被视为后端团队的专属职责；它应该是一项协作工作，需要整个产品团队在产品设计过程中的协调配合。全面的方法能够确保 API 使用的各个方面（从可用性到功能性）都得到充分考虑。

• 本文简要概述了 API，并RESTful APIs强调虽然严格执行这些标准并非强制性要求，但拥有RESTful指南之类的参考资料至关重要。这些指南可以提供重要的见解和最佳实践，从而显著提升 API 的设计和效率。希望这些信息能够帮助每个人在 API 开发和实施的道路上取得进步。

📖 参考文献

[1]GitHub 开放 API：https://docs.github.com/en/rest/actions/artifacts
[2]Apidog：https://apidog.com/