REST（Representational State Transfer）是一种软件架构风格，用于设计网络应用程序的接口。

REST API（Application Programming Interface）是基于 REST 原则构建的 Web 服务接口，它允许不同的系统通过 HTTP 协议进行通信和数据交换。

REST API 的核心特点包括：

  • 无状态性（Stateless）：每个请求都包含处理该请求所需的全部信息
  • 资源导向（Resource-based）：所有数据被视为资源，通过 URI 标识
  • 统一接口（Uniform Interface）：使用标准 HTTP 方法（GET、POST、PUT、DELETE 等）
  • 可缓存性（Cacheable）：响应可以明确标记为可缓存或不可缓存

REST API 的核心概念

1. 资源（Resource）

在 REST 中，资源是任何可以命名的信息，如用户、产品、订单等。每个资源都有一个唯一的标识符（URI）。

2. HTTP 方法

REST API 使用标准 HTTP 方法来定义对资源的操作：

HTTP 方法 描述 幂等性 安全性
GET 获取资源 是 是
POST 创建新资源 否 否
PUT 更新整个资源 是 否
PATCH 部分更新资源 否 否
DELETE 删除资源 是 否

3. 状态码

HTTP 状态码表示请求的处理结果：

状态码 类别 常见状态码
2xx 成功 200 OK, 201 Created
3xx 重定向 301 Moved Permanently
4xx 客户端错误 400 Bad Request, 404 Not Found
5xx 服务器错误 500 Internal Server Error

4. 数据格式

REST API 常用的数据交换格式：

  • JSON（JavaScript Object Notation）
  • XML（eXtensible Markup Language）
  • 有时也使用 YAML、CSV 等格式

REST API 设计最佳实践

1. URI 设计原则

  • 使用名词而非动词表示资源
    • 好：/users
    • 不好：/getUsers
  • 使用小写字母和连字符（-）
  • 避免文件扩展名
  • 使用复数形式表示集合
  • 分层次表示关系：/users/{id}/orders

2. 版本控制

建议在 URI 或请求头中包含 API 版本信息：

  • URI 路径：/v1/users
  • 请求头：Accept: application/vnd.myapi.v1+json

3. 过滤、排序和分页

对于集合资源，提供查询参数：

  • 过滤：/users?role=admin
  • 排序：/users?sort=-created_at
  • 分页：/users?page=2&limit=10

4. 安全性

  • 使用 HTTPS
  • 实施身份验证（OAuth2、JWT）
  • 限制请求频率
  • 验证输入数据

REST API 示例

用户管理 API 示例

实例

# 获取用户列表
GET /api/v1/users
Accept: application/json

# 创建新用户
POST /api/v1/users
Content-Type: application/json

{
  "name": "张三",
  "email": "zhangsan@example.com"
}

# 获取特定用户
GET /api/v1/users/123
Accept: application/json

# 更新用户信息
PUT /api/v1/users/123
Content-Type: application/json

{
  "name": "张三(更新)",
  "email": "new-email@example.com"
}

# 删除用户
DELETE /api/v1/users/123

响应示例

实例

// 成功响应
{
  "status": "success",
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com",
    "created_at": "2023-01-01T00:00:00Z"
  }
}

// 错误响应
{
  "status": "error",
  "message": "User not found",
  "code": 404
}

测试 REST API 的工具

  1. Postman：功能强大的 API 测试工具
  2. cURL：命令行工具
  3. Insomnia：轻量级 API 测试客户端
  4. Swagger/OpenAPI：API 文档和测试工具

cURL 示例

实例

# GET 请求
curl -X GET https://api.example.com/users/123 \
  -H "Accept: application/json"

# POST 请求
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"李四","email":"lisi@example.com"}'

REST API 开发框架

根据编程语言不同，有多种框架可用于开发 REST API：

语言 流行框架
JavaScript Express.js, NestJS
Python Django REST Framework, Flask
Java Spring Boot
PHP Laravel, Symfony
Ruby Ruby on Rails
Go Gin, Echo

总结

REST API 是现代 Web 开发的核心技术之一，掌握 REST 原则和最佳实践对于构建高效、可维护的 API 至关重要。通过本教程，您应该已经了解了：

  1. REST 的基本概念和原则
  2. HTTP 方法和状态码的使用
  3. API 设计的最佳实践
  4. 实际开发中的工具和框架选择