一杯茶的时间，搞懂 RESTful API

前言

• API 和 RESTful API 是每个程序员都应该了解并掌握的基本知识，我们在开发过程中设计 API 的时候也应该至少要满足一些最基本的要求。
• 如果你还不了解什么是 API 或你没有了解 RESTful API，你可以选择花 5 分钟时间看下去，我会最通俗易懂地帮你普及这一切。

什么是 API

举个简单的例子你就会明白：

• 早在 2000 年我们还在用小灵通的时代，网上购票已经慢慢兴起，但是绝大部分人出行还是通过电话查询航班来去选择购票，我们首先需要打电话到附近的站台根据时间询问航班或车次，得到结果后再去到对应站台进行购票。  

• 随着时代的飞速发展和智能手机的普及，各种旅游 App 也映入眼帘，大家也学会了如何在 App 上进行购票。  
• 这时候我们买票就没有以前那么麻烦了，在  App 输入你的起点和终点后，会展现所有符合条件的车次，航班，不仅仅只有时间、座位，还有航空公司、预计时间等等等等详细信息一目了然，你只需要根据你的需求购买即可。

• 连接是一件很棒的事情，在我们现在的生活中，我们可以很轻松的通过 App 进行购物、阅读、直播，我们以前所未有的方式和世界与人们相连接。
• 那这些是怎么做到的？为什么一个 App 能够这么便利？这些资料为什么会可以从到 A 达 B，为什么我们只需要动动手指就可以达到这一切？
• 而这个桥梁，这个互联网世界的无名英雄就是 API。API，全名 Application Programming Interface (应用程式界面)，简单来说，是品牌开发的一种接口，让第三方可以额外开发、应用在自身的产品上的系统沟通界面。
• 简单来说，你可以把它比喻成古人的鸽子，通过飞鸽传书来传达你的需求，而接收方再把回应通过鸽子传达给你。

再说回上面举的例子。

• 旧时代我们需要知道航班的信息，我们就需要一个信差，而这个电话员就是这个信差，也就是我们说的 API，他传达你的要求到系统，而站台就是这个系统，比如告诉它查询明天飞往广州的飞机，那么他就会得出结果，由电话员传递给你
• 而现在我们需要购买机票等，只需要通过购票系统选择日期，城市，舱位等，他会从不同的航空公司网站汇集资料，而汇集资料的手段就是通过 API 和航空公司互动。

我们现在知道是 API 让我们使用这些旅游 App ，那么这个道理也一样适用于生活中任何应用程序、资料和装置之间的互动，都有各自的 API 进行连接。

什么是 RESTful API

• 在互联网并没有完全流行的初期，移动端也没有那么盛行，页面请求和并发量也不高，那时候人们对接口（API）的要求没那么高。
• 当初的 web 应用程序主要是在服务器端实现的，因此需要使用复杂的协议来操作和传输数据。然而，随着移动端设备的普及，需要在移动端也能够访问 web 应用程序，而客户端和服务端就需要接口进行通信，但接口的规范性就又成了一个问题。

• 所以一套简化开发、结构清晰、符合标准、易于理解、易于扩展让大部分人都能够理解接受的接口风格就显得越来越重要，而 RESTful 风格的接口 (RESTful API) 刚好有以上特点，就逐渐应运而生。

REST

• REST，全名 Representational State Transfer (表现层状态转移)，他是一种设计风格，一种软件架构风格，而不是标准，只是提供了一组设计原则和约束条件。

RESTful

• RESTful 只是转为形容詞，就像那么 RESTful API 就是满足 REST 风格的，以此规范设计的 API。

RESTful API

• 我们常见的 API 一般都长这样子：

• 而 RESTful 风格的 API 却长这样子：

六大原则

• Roy Fielding 是 HTTP 协议的主要设计者之一，他在论文中阐述了 REST 架构的概念并给出了 REST 架构的六个限制条件，也就是六大原则。

Uniform Interface（统一接口）

• 就像我们上面两幅图看到的 API，这是最直观的特征，是 REST 架构的核心，统一的接口对于 RESTful 服务非常重要。客户端只需要关注实现接口就可以，接口的可读性加强，使用人员方便调用。
• RESTful API 通过 URL 定位资源，并通过 HTTP 方法操作该资源，对资源的操作包括获取、创建、修改和删除，这些操作正好对应 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 的好处会越来越明显。理解系统时，可以直接围绕一系列资源来理解和记忆。

Client-Server（客户端和服务端分离）

• 它意味着客户端和服务器是独立的、可以分离的。
• 客户端是负责请求和处理数据的组件，服务器是负责存储数据和处理请求的组件。
• 这两个组件之间通过一组约定来协作，以便客户端能够获取所需的数据。

Statelessness（无状态）

• 它指的是每个请求都是独立的，没有前后关系。服务器不保存客户端的状态信息，并且每个请求都必须包含所有所需的信息。
• 这样做的好处是可以使每个请求变得简单，容易理解和处理，并且可以更容易地扩展和维护。
• 例如，假设你在登录一个网站，你需要在登录界面输入用户名和密码通过接口获取到了 token 。接下来的所有请求都需要携带上这个 token 而不是系统在第一次登录成功之后记录了你的状态。

Cacheability（可缓存）

• 客户端和服务端可以协商缓存内容，通过设置 HTTP 状态码，服务器可以告诉客户端这个数据是否可以被缓存。
• 例如，一个 HTTP 响应头中包含一个 Cache-Control 字段，用于告诉客户端该数据可以缓存多长时间。这样可以提高数据传输的效率，从而降低网络带宽的开销，加速数据的访问速度。

Layered System（分层）

• 客户端不应该关心请求经过了多少中间层，只需要关心请求的结果。
• 架构的系统可以分为多个层次，每一层独立完成自己的任务。这样的架构结构使得系统更容易维护，并且允许独立替换不同层次。
• 例如，数据库存储层可以独立于其他层，在不影响其他层的情况下进行替换或扩展。

Code on Demand（可选的代码请求）

• 它提倡服务器可以将客户端代码下载到客户端并执行。这样，客户端可以根据服务器发送的代码来扩展它的功能。
• 这个限制可以使客户端代码变得更加灵活，并且可以通过服务器提供的代码来解决问题，而不必再等待下一个版本。
• Code on Demand 是可选的，但它可以使 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 字段来表示版本。  

请求参数：通过请求中的参数来表示版本，例如 https://api.example.com/resources?version=1 和 https://api.example.com/resources?version=2。

• 不同公司，不同的团队所设计的 API 都各有不同，但我觉得 RESTful API 版本控制的方法要尽可能的简单，易于理解和使用直接将版本放到 URL 中，直截了当，简单明了。

URL 明确标识资源

• API 应该使用简洁明了的 URL 来标识资源，并且在同一个资源上使用不同的 HTTP 方法来执行不同的操作。
• 这样的设计使得客户端在无需任何额外信息的情况下就可以找到所需的资源。
• 不规范的的 URL，形式千奇百怪，不同的开发者还需要了解文档才能调用。
• 规范后的 RESTful 风格的 URL，形式固定，可读性强，根据名词和 HTTP 动词就可以操作这些资源。

• 给大家一个小 tips，如果你遇到了实在想不到的 URL ，你可以参考 github 开放平台 ，这里面有很多很规范的 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：请求失败，表示服务器内部错误

统一返回数据格式

• 常用的返回数据格式有 JSON 和 XML。
• JSON 是现在比较流行的数据格式，它是简单、轻量、易于解析，并且它有很好的可读性。
• XML 也是一种常用的数据格式，它的优点是比较灵活，并且支持各种数据类型。

合格美观的 API 文档

• 项目开发离不开前后端分离，离不开 API，当然也就离不开 API 文档，但是文档的编写又成为程序员觉得麻烦事之一，甚至我还看到有公司的的 API 文档是用 Word 文档手敲的。
• 市面上有很多可以管理 API 的软件，每个人都有自己的选择，我给大家推荐一款 API 管理神器 Apifox，可以一键生成 API 文档。
• 不需要你过多的操作，只需要你在可视化的页面添加你的 API 即可生成，现在也支持了多种导航模式、亮暗色模式、顶部自定义 Icon 、文案可跳转到你的官网等地址。

• 对于独立开发者和团队来说都是一大利好福音，本文就不做过多介绍，感兴趣的可以去试试～

写在最后

• 总的来说 RESTful 风格的 API 固然很好很规范，但大多数互联网公司并没有按照或者完全按照其规则来设计，因为 REST 是一种风格，而不是一种约束或规则，过于理想的 RESTful API 会付出太多的成本。
• 如果您正在考虑使用 RESTful API，请确保它符合您的业务需求。例如，如果您的项目需要实现复杂的数据交互，您可能需要考虑使用其他 API 设计方法。
• 因此，请确保在选择 API 设计方法时充分考虑您的业务需求。此外，您还需要确保 RESTful API 与您的系统架构和技术栈相兼容。通过这些考虑，您可以确保 RESTful API 的正确使用，并且可以实现更高效和可靠的 API。
• 长期来看，API 设计也不只是后端的工作，而是一个产品团队在产品设计上的协调工作，应该整个团队参与。
• 这次简单分享了 API 与 RESTful API，在实际运用中，并不是一定要使用这种规范，但是有 RESTful 标准可以参考，是十分有必要的，希望对大家有帮助。