RESTful API

RESTful API 是一种基于 REST 架构风格设计的网络 API。它允许不同的软件系统通过互联网进行通信和数据交换，是现代 Web 服务和移动应用后端的核心技术。

1. 核心概念：API 与 REST

• API：应用程序编程接口。它是一组预定义的规则和规范，允许一个软件应用程序与另一个软件应用程序进行交互。简单来说，API 就像一个餐厅的服务员，你（客户端）告诉服务员你想点什么菜（请求），服务员去厨房（服务器）下单，然后把做好的菜（响应）端给你。
• REST：表征状态转移。它是由 Roy Fielding 博士在其博士论文中提出的一种软件架构风格，而不是一个标准或协议。它描述的是一组设计原则和约束，符合这些原则的应用程序或设计就被称为“RESTful”。

2. REST 的六个核心约束
要理解 RESTful API，必须了解构成 REST 架构的六个基本约束：

• 客户端-服务器：架构必须明确区分客户端和服务器。客户端负责用户界面和用户体验，服务器负责数据处理和存储。这种分离允许两者独立进化。
• 无状态：服务器不会在多个请求之间保存任何客户端的状态信息。每一个从客户端到服务器的请求都必须包含理解该请求所需的全部信息。会话状态完全由客户端负责维护（例如，通过 Token 或 API Key）。
• 可缓存：响应必须被隐式或显式地标记为“可缓存”或“不可缓存”。这可以减少客户端-服务器之间的交互，提高性能和可扩展性。
• 统一接口：这是 REST 系统设计中最核心的约束。它简化了架构，并解耦了各个部分。统一接口包含以下几个子原则：
  • 资源标识：每个资源（如用户、订单）在系统中都有一个唯一的标识符，通常使用 URI（统一资源标识符）来实现，例如 /users/123。
  • 通过表征操作资源：客户端操作的不是资源本身，而是资源的“表征”（Representation）。例如，客户端不直接删除服务器上的一个用户数据，而是发送一个“删除”请求到该用户的 URI。同一个资源可以有多种表征（如 JSON、XML）。
  • 自描述的消息：每个消息（请求或响应）都包含足够的信息来描述如何处理自己。例如，HTTP 头中的 Content-Type 告诉对方消息体的格式。
  • 超媒体作为应用状态引擎（HATEOAS）：客户端通过与服务器返回的超媒体内容（包含链接）交互来改变应用的状态。例如，获取一个订单详情后，响应体中会包含指向“付款”、“取消订单”等操作的链接。
• 分层系统：架构可以由多个层次组成，每个层次只知道它相邻的层次。例如，你可以在客户端和服务器之间加入负载均衡器、代理、网关等，以提高系统的安全性、可扩展性和性能，而客户端无需知道这些中间层的存在。
• 按需代码（可选）：服务器可以通过向客户端传输可执行代码（如 JavaScript）来临时扩展或定制客户端的功能。这是唯一一个可选的约束。

3. RESTful API 的设计实践
基于以上理论，一个典型的 RESTful API 设计会体现在以下几个方面：

• 资源与 URI：将数据或服务抽象为“资源”。使用名词（而不是动词）来设计 URI，清晰地标识资源。
  • 示例：/books（所有书籍）， /books/1（ID 为 1 的书籍）
• HTTP 方法：利用 HTTP 协议定义的方法来对应资源的增删改查（CRUD）操作。
  • GET：检索资源。例如 GET /books/1 获取一本书。
  • POST：创建新资源。例如 POST /books 创建一本新书。
  • PUT：更新整个资源（全部替换）。例如 PUT /books/1 更新 ID 为 1 的书的所有信息。
  • PATCH：对资源进行部分更新。例如 PATCH /books/1 只更新书的标题。
  • DELETE：删除资源。例如 DELETE /books/1 删除一本书。
• HTTP 状态码：使用标准化的 HTTP 状态码来告知客户端请求的结果。
  • 200 OK：请求成功。
  • 201 Created：资源创建成功。
  • 400 Bad Request：客户端请求有错误。
  • 401 Unauthorized：未认证。
  • 403 Forbidden：无权限。
  • 404 Not Found：资源不存在。
  • 500 Internal Server Error：服务器内部错误。
• 数据格式：通常使用 JSON 作为数据交换的格式，因为它轻量、易读、且被广泛支持。HTTP 头的 Content-Type 会设置为 application/json。

4. 一个完整的交互示例
假设一个管理图书的 RESTful API，其根路径是 https://api.example.com。

1. 获取所有图书（GET 请求）

   • 客户端发送：GET https://api.example.com/books
   • 服务器响应：
     • 状态码：200 OK
     • 响应体（JSON）：

     [
       { "id": 1, "title": "深入理解计算机系统", "author": "Randal E. Bryant" },
       { "id": 2, "title": "设计模式", "author": "Erich Gamma" }
     ]
     

2. 创建一本新书（POST 请求）

   • 客户端发送：POST https://api.example.com/books
   • 请求头：Content-Type: application/json
   • 请求体（JSON）：

     { "title": "RESTful API 设计指南", "author": "张三" }
     

   • 服务器响应：
     • 状态码：201 Created
     • 响应头：Location: /books/3 （告知新创建资源的地址）
     • 响应体（可选，返回创建成功的完整对象）：

     { "id": 3, "title": "RESTful API 设计指南", "author": "张三" }
     

3. 更新一本书（PUT 请求）

   • 客户端发送：PUT https://api.example.com/books/3
   • 请求头：Content-Type: application/json
   • 请求体（JSON）：

     { "title": "RESTful API 最佳实践", "author": "张三" }
     

   • 服务器响应：
     • 状态码：200 OK
     • 响应体：返回更新后的完整资源。

通过这种统一、标准化的方式，RESTful API 使得不同平台（Web、iOS、Android）的客户端都能以一致、可预测的方式与后端服务进行交互，极大地促进了系统间的集成和前后端的分离开发。