Restful 风格 API

约 1461 字大约 5 分钟

2025-03-15

RESTful API 是一种基于 HTTP 协议的 Web 服务架构风格，它以资源为中心，通过 HTTP 方法（如 GET、POST、PUT、DELETE）对资源进行操作。

使用清晰的资源命名：API 的端点应该使用名词，而不是动词。例如，使用"/users"来表示用户资源的集合，使用"/users/{id}" 来表示单个用户资源。
使用 HTTP 方法进行操作：使用 HTTP 的不同方法（GET、POST、PUT、DELETE）对资源进行不同的操作。GET 用于获取资源，POST 用于创建资源，PUT 用于更新资源，DELETE 用于删除资源。
使用 HTTP 状态码：正确使用 HTTP 状态码可以提供有关请求结果的信息。常见的状态码有 200 表示成功，201 表示资源创建成功，400 表示客户端请求错误，404 表示资源不存在等。
使用资源版本控制：在 API 中引入版本控制是一种良好的实践，可以确保对 API 进行更改时不会破坏现有的客户端应用程序。
使用合适的数据格式：常见的数据格式包括 JSON 和 XML，但根据需求也可以选择其他的格式。JSON 是当前最常用的格式，因为它是轻量级的、易于阅读和解析的。
使用正确的 HTTP 头部信息：使用合适的 Content-Type 头部信息来指示请求或响应中的数据格式，并使用合适的 Accept 头部信息来指示客户端期望的响应数据格式。
使用 URI 来表示关系：在 URL 中使用合适的路径表示资源之间的层次关系或关联关系，遵循 Restful 风格。
提供合适的错误处理：在 API 中，要提供清晰和有用的错误信息，包括错误代码、错误消息和可能的解决方案。
使用认证和授权机制：对于需要身份验证和授权的 API 操作，应该实施适当的安全措施，如使用 API 密钥、OAuth 等来保护资源的访问。

RESTful API 是一种基于 REST（Representational State Transfer，表述性状态转移） 架构风格设计的 Web API。它是一种设计规范，用于创建可扩展、可维护和易于理解的 Web 服务。RESTful API 的核心思想是通过 HTTP 协议的标准方法（如 GET、POST、PUT、DELETE 等）对资源进行操作。

以下是 RESTful API 的主要规范和原则：

1. 资源（Resources）

RESTful API 的核心是资源，每个资源都有一个唯一的标识符（URI/URL）。
资源可以是任何东西，如用户、订单、产品等。
示例：
- /users：表示用户集合。
- /users/123：表示 ID 为 123 的单个用户。

2. HTTP 方法（HTTP Methods）

RESTful API 使用标准的 HTTP 方法来操作资源：

GET：获取资源。
- 示例：GET /users 获取所有用户，GET /users/123 获取 ID 为 123 的用户。
POST：创建资源。
- 示例：POST /users 创建一个新用户。
PUT：更新资源（替换整个资源）。
- 示例：PUT /users/123 更新 ID 为 123 的用户。
PATCH：部分更新资源。
- 示例：PATCH /users/123 更新 ID 为 123 用户的部分信息。
DELETE：删除资源。
- 示例：DELETE /users/123 删除 ID 为 123 的用户。

3. 无状态（Stateless）

每次请求都必须包含所有必要的信息，服务器不会保存客户端的状态。
客户端需要自己管理状态（如通过 token 或 session）。

4. 统一接口（Uniform Interface）

RESTful API 的设计应该简单、一致，易于理解和使用。
包括：
- 资源的唯一标识（URI）。
- 通过标准 HTTP 方法操作资源。
- 资源的自描述性（如通过 JSON 或 XML 格式返回数据）。

5. 资源的表现层（Representation）

资源可以有多种表现形式（如 JSON、XML、HTML 等）。
客户端和服务器通过协商（如 Accept 和 Content-Type 头）决定使用哪种格式。
示例：
- 请求头：Accept: application/json。
- 响应头：Content-Type: application/json。

6. 状态码（Status Codes）

使用标准的 HTTP 状态码表示请求结果：
- 2xx：成功。
  - 200 OK：请求成功。
  - 201 Created：资源创建成功。
  - 204 No Content：请求成功，但无返回内容。
- 3xx：重定向。
  - 301 Moved Permanently：资源永久移动。
  - 302 Found：资源临时移动。
- 4xx：客户端错误。
  - 400 Bad Request：请求无效。
  - 401 Unauthorized：未授权。
  - 404 Not Found：资源不存在。
- 5xx：服务器错误。
  - 500 Internal Server Error：服务器内部错误。
  - 503 Service Unavailable：服务不可用。

7. 版本控制（Versioning）

API 的版本应该明确，以便在更新时不影响现有客户端。
常见的版本控制方式：
- URL 路径：/v1/users。
- 请求头：Accept: application/vnd.example.v1+json。

8. 过滤、排序和分页（Filtering, Sorting, Pagination）

对于返回大量资源的请求，应该支持过滤、排序和分页。
示例：
- 过滤：/users?age=25。
- 排序：/users?sort=name,asc。
- 分页：/users?page=2&limit=10。

9. 安全性（Security）

使用 HTTPS 加密通信。
使用身份验证和授权机制（如 OAuth、JWT）。
防止常见攻击（如 SQL 注入、XSS）。

10. HATEOAS（Hypermedia as the Engine of Application State）

在响应中提供相关资源的链接，使客户端能够动态发现和导航 API。

示例：

{
  "id": 123,
  "name": "John",
  "links": [
    { "rel": "self", "href": "/users/123" },
    { "rel": "orders", "href": "/users/123/orders" }
  ]
}

RESTful API 示例

获取用户列表

请求：GET /users

响应：

[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob" }
]

创建用户

请求：POST /users
```
{ "name": "Charlie" }
```
响应：
```
{ "id": 3, "name": "Charlie" }
```

更新用户

请求：PUT /users/3
```
{ "name": "Charlie Brown" }
```
响应：
```
{ "id": 3, "name": "Charlie Brown" }
```

删除用户

请求：DELETE /users/3
响应：204 No Content

总结

RESTful API 是一种基于 HTTP 协议的设计规范，强调资源的唯一标识、标准 HTTP 方法、无状态、统一接口等原则。遵循这些规范可以使 API 更易于理解、扩展和维护。

更新日志

2025/8/24 08:17

查看所有更新日志

e7112-1于 2025/8/24