别再搞乱了！一文教你看懂RESTful API设计🚀

这个标题既通俗易懂，又符合中文的口语表达习惯，同时传达了文章的核心内容：关于如何设计清晰的RESTful API。

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

如果你还不了解什么是API，或者还没有掌握RESTful API的概念，花5分钟读一下。我会用简单明了的方式来解释所有内容。

• 一个简单的例子可以说明这一点：
• 在2000年，网上订票开始出现，但大多数人仍然依赖电话查询航班。最初，你需要打电话到当地的售票点询问航班或火车的时刻表。收到信息后，再去相应的售票点买票。

• 隨著科技的快速進步和智能手机的广泛使用，各种旅行应用程序层出不穷，教大家如何在这些应用里买票。

• 买票现在变得更加简单。只要在应用里输入出发地和目的地，你就可以看到所有相关的火车和航班。不仅有时间和座位的详情，还能看到航空公司的信息和预计的旅行时间，这些信息都一目了然。你可以根据自己的需求轻松下单。

• 连接是件美妙的事情。这在当今生活中显得尤为突出。在我们目前的生活里，我们能够轻松地通过各种App购物、阅读和观看直播，以前所未有的方式连接世界和人们。
• 那么这一切是如何实现的呢？是什么让一个App如此方便？信息是如何从点A传递到点B的，让我们只需轻轻一划手指便能完成所有事情？
• 使这一切成为可能的桥梁——互联网世界的幕后英雄——就是API。API的全称是Application Programming Interface，简单来说，它是品牌为其他开发者提供的一个接口，允许第三方创建额外的功能并将其集成到自己的产品中。

• 回到之前的例子：

• 在以前，如果我们想了解航班信息，我们需要一个信使。电话那头的操作员充当了这个信使的角色，就像我们所说的API一样。他们把你的请求传达给系统。例如，如果你想查询明天飞往纽约的航班，操作员会查询相关信息并反馈给你。

• 现在，当我们想要购买机票时，我们可以直接在预订系统中操作，可以选择日期、城市、舱位偏好。这个系统汇集了来自各大航空公司网站的数据，通过API来整合这些信息。
• 我们现在明白，正是这些API使我们能够使用这些旅行App，这一原理适用于应用程序、数据和设备在生活各方面的交互。每个系统都通过自己的API与其他系统相连。

• 在互联网早期，尚未完全普及且移动设备并不广泛使用的时候，对API的需求相对较低。那时，由于页面请求量和并发用户较少，因此采用了复杂的协议来进行数据操作和传输。
• 随着移动设备的增多，网页应用从这些设备访问变得日益重要。这一变化反映出用户行为和期望的巨大转变，需要更有效的客户端和服务器之间的沟通方式。此时，API的重要性愈发突出，它们成为了移动设备与网页应用之间无缝交互的桥梁。

因此，一套便于开发人员使用的、具有易于理解的结构、标准化、易于理解且易于扩展的 API 已经变得越来越重要，以实现被广泛接受和使用。RESTful API 风格完美地体现了这些特性，因此，它在开发人员和组织中越来越受欢迎。

REST

• REST，即表示状态传输（Representational State Transfer，简称 REST），是一种设计风格和软件架构模式，而不是一个严格的标准。它提供了一套设计原则和约束条件，指导创建网络应用程序。REST 的目标是利用网络特性，特别是 HTTP 协议的特点，来创建可扩展、高效的网络服务。

RESTful (即REST风格的)

• RESTful 一词仅仅是用来描述符合 REST 原则的 API 或服务的形容词。例如，RESTful 接口是指符合 REST 规定的特性和设计约束的接口。它确保 API 符合 REST 架构，提供了可预测且标准化的交互模式。

RESTful 接口

• 我们通常遇到的 API 通常看起来像这样：

然而，一个 RESTful API 却看起来像这样：

看看这张图片，挺有意思的。

💡 六大原则

• 罗伊·菲尔丁（Roy Fielding） 是 HTTP 协议的主要架构师之一。在他的博士论文中，他详细阐述了 REST 架构的思想，并概述了六条约束，通常称为六大原则。这些原则为构建 RESTful API 提供了指导，并有助于接口的功能和扩展性。让我们一一来看每个原则：

为了查看图片，请点击链接:

统一的界面:

• 与我们之前观察到的两个示例一样，最直观的 API 特性是它遵循 REST 架构的原则。统一的接口对 RESTful 服务来说至关重要。客户端只需关注实现接口，这不仅增强了 API 的可读性，还使用户能够方便地访问。

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

• GET：获取资源信息。
• POST：创建资源。
• PUT：更新资源。
• DELETE：移除资源。

• 在一个遵循RESTful原则的团队中，后端只需通知前端/users API，前端应理解以下操作：

• 获取所有用户：GET /users
• 获取特定用户：GET /users/{id}
• 创建新用户：POST /users
• 更新现有用户：PUT /users/{id}
• 删除用户：DELETE /users/{id}
• 随着API数量的增加和系统变得越来越复杂，RESTful架构的优势就更加明显了。这样可以通过关注一系列资源来简化理解，帮助记忆。

客户端/服务器架构

• 这意味着客户端和服务器是相互独立的，并且可以相互解耦。
• 客户端负责请求和处理数据，而服务器则负责存储数据和响应请求。
• 这两个组件按照一组约定进行协作，这可以确保客户端能够高效地获取所需的数据。

无国籍身份

• 这指的是每个请求都是独立的，与之前的任何请求都无关。服务器不维护任何客户端的状态信息，每个请求都必须包含处理该请求所需的所有必要信息。
• 这种方法的好处是简化了每个请求，使其易于理解和处理，并且也使扩展和维护更容易。
• 比如说，当你登录一个网站时，你输入用户名和密码，通过API来获取一个令牌。从那之后，所有后续的请求都必须携带这个令牌，而不是系统在第一次成功登录后继续跟踪你的登录状态。

缓存能力

• 客户端和服务器可以协商缓存哪些内容，通过设置适当的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。
• Accept 字段：使用请求头中的 Accept 字段来指示所需的 API 版本。
• 通过请求参数来指定版本：通过请求参数指定版本，例如 https://api.example.com/resources?version=1 和 https://api.example.com/resources?version=2。
• 不同的公司和团队在 API 设计上可能采取不同的方法，但我认为，使版本控制方法尽可能简单直观是非常重要的。将版本直接放在 URL 中，这种方式既简单又直观，方便开发人员理解和使用。

URLs：清楚地标示资源

• API 应该使用简洁清晰的 URL 来识别资源，并通过不同的 HTTP 方法来对同一资源进行不同的操作。

• 此设计让客户端可以轻松找到所需的资源，无需额外信息或详尽文档。清晰的URL让客户端可以轻松与API互动。

• 相比之下，非标准的URL可能形式多样，需要不同的开发人员查阅相关文档来理解如何与它们交互。非规范的URL可能会在开发过程中引起困惑并降低效率。

• 遵循标准化的 RESTful 风格的 URL 可以形成固定的格式，使得 URL 更加易读。通过使用清晰的名词和相应的 HTTP 动词，开发人员可以轻松地操作资源，这种方式让使用 API 的体验更加直观。

• 这里有个小建议给你：如果你发现自己想不出来一个合适的URL，你可以看看GitHub 开放 API。它有很多结构清晰、组织得当的URL可供参考。试试看。

HTTP 状态码

• HTTP 状态码是设计 RESTful API 的重要部分，用于表明 API 请求的结果，并告诉客户端请求是否成功，以及数据是否被正确处理了。下面是一些常用的 HTTP 状态码：

• 200 OK ：请求成功，已检索到请求的数据。
• 201 Created ：新资源已被创建。
• 204 No Content ：请求成功，但没有返回任何数据，表示操作已完成。
• 400 Bad Request ：因为格式错误或缺少必要参数，请求失败。
• 401 Unauthorized ：由于认证问题或缺乏授权，请求失败。
• 403 Forbidden ：请求失败，因为客户端没有权限访问该资源。
• 404 Not Found ：请求失败，因为找不到请求的资源。
• 500 Internal Server Error ：请求失败，因为服务器内部错误。
• 这些状态码帮助客户端理解请求的结果，并允许开发人员有效地处理错误和成功的场景。

统一的返回数据格式。

• 常用的 RESTful API 返回数据格式有 JSON 和 XML。

• JSON（JavaScript对象 notation，即“JSON”），由于其简单、轻量和易于解析的特点，目前是一种流行的数据格式。其易读性使其特别受到Web应用的青睐，因为在这些应用中，服务器和客户端之间频繁交换数据。
• XML（可扩展标记语言）也是一种广泛使用的数据格式。它的优势在于灵活性和对多种数据类型的支持。XML可以表示复杂的数据结构，在需要文档验证或更详细描述的场景中有时更受欢迎。##### 结构清晰且美观的API文档

• 在任何项目开发中，特别是当前后端分离时，API起着至关重要的作用。因此，这种对API的依赖自然延伸到维护更新且全面的API文档上。然而，许多程序员发现编写文档是一件繁琐的任务，我甚至见过一家公司用Word文档认真编写其API文档。

• 幸运的是，市场上有许多专门用于管理和文档化API的工具。每个开发人员或团队可能有他们自己的偏好，但我推荐一个名为Apidog的API管理工具。这个工具只需点击几次鼠标就能生成API文档。

• Apidog 最棒的一点是它大大简化了文档生成的过程。你不需要做很多操作——只需通过友好的可视化界面添加你的 API，工具就会自动生成相应的文档。

说明：这是一张示例图片。

• 总的来说，虽然RESTful风格的API确实有效且结构良好，但许多互联网企业却在设计API时并未严格遵循REST风格。这是因为REST更像是一种风格而非一成不变的规则；过于理想化的RESTful API实现可能会导致显著的成本和复杂程度。

• 如果你正在考虑使用 RESTful APIs，确保它们能满足你的业务需求。比如说，如果你的项目需要复杂的业务数据交互，你可能需要寻找更适合这些需求的API设计方法。

  因此，在选择API设计方法时，一定要仔细考虑您的业务需求。此外，确保RESTful API与您的系统架构和现有技术栈相兼容。这些考虑将帮助您更好地使用RESTful APIs，这将最终带来更高效和更可靠的API性能。

• 长远来看，API设计不应仅仅由后端团队负责；而应该是在整个产品设计流程中，整个团队的协作努力。这种方法可以确保从易用性到功能性，各个方面都被考虑到。

• 这个关于 API 和 RESTful API 的简短介绍强调了虽然严格遵守这些标准不是强制性的，但像 RESTful 指南这样的参考很有价值。这些指南可以提供宝贵的见解和最佳实践，可以显著提高你的 API 设计和效率。希望这些信息对大家在 API 开发和实现过程中有所帮助。

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