REST API 基础：定义、示例及使用方法

引言

REST 是互联网上计算机之间通信的最常见标准。什么是 REST？为什么它如此流行？让我们来一探究竟。

什么是 API？

API（Application Programming Interface，应用程序编程接口）是两种计算机之间通信的方式。大多数移动和 Web 应用程序与服务器通信时使用的常见 API 标准就是 REST。REST 代表“Representational State Transfer”（代表性状态转移），听起来有点拗口。

它并不是一个具体的规范，而是一套自 2000 年代初以来成为构建 Web API 共同标准的新规则。遵循 REST 标准的 API 被称为 RESTful API。一些实际的例子包括 Twilio、Stripe 和 Google Maps。

REST API 基础

RESTful API 的基本概念

RESTful API 将资源组织成一组独特的 URI（Uniform Resource Identifiers，统一资源标识符）。URI 用于区分服务器上的不同资源类型。以下是一些示例：

• 资源应该按名词而非动词分组。例如，获取所有产品的 API 应该是 /products，而不是 /getAllProducts。

• 客户端通过 HTTP 向资源的端点发送请求来与资源交互。请求具有非常特定的格式，如下所示：

  • URI：我们想要访问的资源的 URI。
  • HTTP 动词：告诉服务器我们想要对资源执行什么操作。例如：
  • POST：创建新资源。
  • GET：读取现有资源的数据。
  • PUT：更新现有资源。
  • DELETE：删除现有资源。

你可能听说过 CRUD（Create、Read、Update、Delete），这就是它的含义。

请求正文

请求的正文中可以包含一个可选的 HTTP 请求正文，其中包含自定义数据负载，通常以 JSON 格式编码。

服务器响应

服务器接收到请求后，会处理它并将结果格式化为响应。响应的第一行包含 HTTP 状态码，用于告知客户端请求的结果：

• 200 级代码：请求成功。
• 400 级代码：请求有误，例如请求包含错误的语法。
• 500 级代码：服务器出错，例如服务不可用。

表现良好的客户端可以选择重试带有 500 级状态码的失败请求。我们说“可以选择重试”，是因为某些操作不是幂等的，重试时需要格外小心。当 API 是幂等的，多次发送相同的请求与发送一次请求的效果相同。通常，创建新资源的 POST 请求不是幂等的。

响应正文是可选的，可以包含数据负载，通常以 JSON 格式呈现。

REST 的关键特性

无状态

REST 实现应该是无状态的。这意味着双方不需要存储彼此的任何信息，每个请求和响应（周期）都与其他所有请求和响应独立。这使得 Web 应用程序易于扩展且表现良好。

分页

如果 API 端点返回大量数据，应使用分页。常见的分页方案使用“limit”和“offset”作为参数。例如：

GET /products?limit=10&offset=20

如果未指定这些参数，服务器应假设合理的默认值。

版本控制

API 的版本控制非常重要。版本控制允许实现提供向后兼容性，以便在从一个版本引入破坏性更改到另一个版本时，消费者有足够的时间迁移到下一个版本。有许多方法可以对 API 进行版本控制，最直接的方法是在 URI 上为资源前缀添加版本号。例如：

GET /v1/products

总结

RESTful API 在合理应用时简单且有效。它可能不是所有公司的最佳选择，但它简单且足够好，这就是它被广泛使用的原因。还有其他流行的 API 选项，如 GraphQL 和 gRPC，我们将在单独的文章中讨论它们并进行比较。

原文引自YouTube视频：https://www.youtube.com/watch?v=-mN3VyJuCjM