RESTful API规范 ❤

1. 使用资源名作为URI

URI应该表示资源的集合或单个资源。使用名词而不是动词，并且使用复数形式。

• 单个资源: /users/1
• 资源集合: /users

2. 使用HTTP动词

HTTP动词用于指示操作的类型：

• GET：获取资源
• POST：创建资源
• PUT：更新资源
• PATCH：部分更新资源
• DELETE：删除资源

3. 遵循HTTP状态码

使用标准的HTTP状态码来指示请求的结果：

• 200 OK：请求成功
• 201 Created：资源创建成功
• 204 No Content：请求成功但无返回内容（通常用于删除操作）
• 400 Bad Request：请求无效
• 401 Unauthorized：未授权
• 403 Forbidden：禁止访问
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器错误

4. 使用JSON格式

JSON是RESTful API的常见数据交换格式。确保API返回的数据是JSON格式，并在请求头中设置正确的Content-Type。

Content-Type: application/json

5. 实现过滤、排序和分页

提供过滤、排序和分页功能以处理大量数据：

• 过滤：GET /users?status=active
• 排序：GET /users?sort=created_at
• 分页：GET /users?page=2&limit=20

6. 包含关系

使用嵌套资源或链接表示资源之间的关系。

• 嵌套资源：GET /users/1/posts
• 链接关系：在返回的JSON数据中包含链接到相关资源

7. 提供描述性错误信息

确保API在返回错误时提供有用的错误信息，帮助客户端理解和解决问题。

{
  "error": {
    "message": "Resource not found",
    "code": 404
  }
}

8. 使用版本控制

在API的URL中包含版本号以便管理API的不同版本。

GET /v1/users
GET /v2/users

9. 安全性

使用HTTPS保护数据传输，并通过身份验证和授权机制确保API的安全性。

• 使用API Key、OAuth或JWT进行身份验证
• 使用CORS限制跨域请求

10. 使用HTTP缓存

利用HTTP缓存机制减少服务器负载和提高性能。

• 使用ETag和Last-Modified头
• 使用缓存控制头，如Cache-Control

示例：用户资源的RESTful API设计

获取所有用户

GET /users

响应：

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  ...
]

获取单个用户

http
复制代码
GET /users/1

响应：

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

创建新用户

POST /users

请求体：

{
  "name": "Jane Doe",
  "email": "jane@example.com"
}

响应：

{
  "id": 2,
  "name": "Jane Doe",
  "email": "jane@example.com"
}

更新用户

PUT /users/1

请求体：

{
  "name": "John Smith",
  "email": "john.smith@example.com"
}

响应：

{
  "id": 1,
  "name": "John Smith",
  "email": "john.smith@example.com"
}

删除用户

DELETE /users/1

响应：

204 No Content

通过遵循这些规范，你可以设计一个易于理解和使用的RESTful API。