设计符合RESTful规范的API端点，支持多功能操作。
在设计一个支持创建、读取、更新、删除（CRUD）操作的RESTful API时，我们需要定义 URL 模式、HTTP 方法、请求和响应格式，以及管理员访问权限认证。以下是一个示例 API 的设计：
---
### 假设你的资源是 "用户"（Users）
#### URL 模式
- 基础 URL: `/api/users`
### API 端点设计
#### 1. **创建用户（Create）**
- **HTTP 方法**: `POST`
- **URL**: `/api/users`
- **请求头**:
- `Authorization: Bearer {token}` （管理员权限的认证 Token）
- `Content-Type: application/json`
- **请求体**:
```json
{
"name": "John Doe",
"email": "john@example.com",
"password": "password123",
"role": "user"
}
```
- **响应**:
- 成功:
- 状态码: `201 Created`
- 响应体:
```json
{
"id": 1,
"name": "John Doe",
"email": "john@example.com",
"role": "user",
"created_at": "2023-10-01T12:00:00Z"
}
```
- 失败:
- 无权限：`403 Forbidden`
- 缺少字段：`400 Bad Request`
- **访问权限**: 仅管理员可以访问。
---
#### 2. **读取用户（Read）**
##### 获取所有用户
- **HTTP 方法**: `GET`
- **URL**: `/api/users`
- **请求头**:
- `Authorization: Bearer {token}`
- **响应**:
- 成功:
- 状态码: `200 OK`
- 响应体:
```json
[
{
"id": 1,
"name": "John Doe",
"email": "john@example.com",
"role": "user",
"created_at": "2023-10-01T12:00:00Z"
},
{
"id": 2,
"name": "Jane Smith",
"email": "jane@example.com",
"role": "user",
"created_at": "2023-10-02T08:00:00Z"
}
]
```
- 无权限：`403 Forbidden`
- 数据库错误：`500 Internal Server Error`
- **访问权限**: 仅管理员可以访问所有用户。
##### 获取单个用户
- **HTTP 方法**: `GET`
- **URL**: `/api/users/{id}`
- **请求头**:
- `Authorization: Bearer {token}`
- **响应**:
- 成功:
- 状态码: `200 OK`
- 响应体:
```json
{
"id": 1,
"name": "John Doe",
"email": "john@example.com",
"role": "user",
"created_at": "2023-10-01T12:00:00Z"
}
```
- 未找到用户：`404 Not Found`
- **访问权限**:
- 管理员可以读取所有用户信息。
- 普通用户只能读取自己的信息。
---
#### 3. **更新用户（Update）**
- **HTTP 方法**: `PUT`
- **URL**: `/api/users/{id}`
- **请求头**:
- `Authorization: Bearer {token}`
- `Content-Type: application/json`
- **请求体**:
```json
{
"name": "John Doe Updated",
"email": "updated@example.com",
"role": "admin" // 仅管理员可以修改角色
}
```
- **响应**:
- 成功:
- 状态码: `200 OK`
- 响应体:
```json
{
"id": 1,
"name": "John Doe Updated",
"email": "updated@example.com",
"role": "admin",
"updated_at": "2023-10-03T10:00:00Z"
}
```
- 权限不足：`403 Forbidden`
- 未找到用户：`404 Not Found`
- **访问权限**:
- 管理员可以更新所有用户。
- 普通用户只能更新自己的信息，但不能修改角色。
---
#### 4. **删除用户（Delete）**
- **HTTP 方法**: `DELETE`
- **URL**: `/api/users/{id}`
- **请求头**:
- `Authorization: Bearer {token}`
- **响应**:
- 成功:
- 状态码: `204 No Content` （无内容返回）
- 权限不足：`403 Forbidden`
- 未找到用户：`404 Not Found`
- **访问权限**: 仅管理员可以删除用户。
---
### 认证与授权
1. **认证**: 使用 `Bearer Token` 进行认证。所有受保护的端点必须包含头部：
```
Authorization: Bearer {token}
```
- Token 应通过登录 API 获取，并验证其有效期和权限。
- 示例登录响应：
```json
{
"access_token": "{token}",
"expires_in": 3600
}
```
2. **授权**:
- 管理员：可以访问所有端点和操作。
- 普通用户：只能读取和更新自己的信息，无法删除或更改角色。
---
### 其他约定
1. **错误处理**:
- API 响应需要统一格式：
```json
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "The requested user was not found."
}
}
```
2. **分页支持**:
- 对需要返回列表的端点（如 `GET /api/users`），支持分页：
- 请求参数：`?page=1&limit=10`
- 响应格式：
```json
{
"data": [ /* 用户数据 */ ],
"pagination": {
"current_page": 1,
"total_pages": 5,
"total_items": 50
}
}
```
通过上述设计，就可以满足用户管理功能的基本需求，并确保安全性和扩展性。
以下是一个关于订单管理的RESTful API设计，支持读取和更新操作:
---
### 1. API 基础信息
- 基础 `URL`: `https://api.example.com`
- 资源路径: `/orders`
- 数据格式: JSON
- 用户认证: 通过 `Bearer Token` 发送授权头进行认证 (`Authorization: Bearer <token>`)
---
### 2. API 端点设计
#### (1) 获取订单详情
- **URL**: `/orders/{orderId}`
- **HTTP 方法**: `GET`
- **功能**: 根据订单 `orderId` 获取订单详细信息。
- **请求头**:
```plaintext
Authorization: Bearer <token>
```
- **请求参数**:
- 路径参数: `orderId` (表示特定订单的ID, 必须)
- **响应**:
- **成功** (状态码: `200 OK`):
```json
{
"status": "success",
"data": {
"orderId": "12345",
"userId": "67890",
"status": "completed",
"items": [
{
"productId": "111",
"quantity": 1,
"price": 100
},
{
"productId": "222",
"quantity": 2,
"price": 200
}
],
"totalPrice": 500
}
}
```
- **失败**:
- 未授权 (状态码: `401 Unauthorized`):
```json
{
"status": "error",
"message": "Authentication token is missing or invalid"
}
```
- 无权限访问 (状态码: `403 Forbidden`):
```json
{
"status": "error",
"message": "You are not authorized to access this order"
}
```
- 未找到订单 (状态码: `404 Not Found`):
```json
{
"status": "error",
"message": "Order not found"
}
```
---
#### (2) 更新订单
- **URL**: `/orders/{orderId}`
- **HTTP 方法**: `PUT`
- **功能**: 更新指定订单信息，普通用户仅可更新特定字段(如收货地址)。
- **请求头**:
```plaintext
Authorization: Bearer <token>
```
- **请求参数**:
- 路径参数: `orderId` (表示特定订单的ID, 必须)
- **请求体** (示例): 用户更新其订单中“地址”字段：
```json
{
"address": {
"street": "123 Main St",
"city": "New York",
"zipCode": "10001"
},
"status": "pending"
}
```
- 用户只能更新允许的字段，例如: 收货地址(`address`)或自定义字段。禁止更新付款状态或敏感字段。
- **响应**:
- **成功** (状态码: `200 OK`):
```json
{
"status": "success",
"data": {
"orderId": "12345",
"status": "updated",
"address": {
"street": "123 Main St",
"city": "New York",
"zipCode": "10001"
}
}
}
```
- **失败**:
- 未授权 (状态码: `401 Unauthorized`):
```json
{
"status": "error",
"message": "Authentication token is missing or invalid"
}
```
- 无权限访问 (状态码: `403 Forbidden`):
```json
{
"status": "error",
"message": "You are not authorized to update this order"
}
```
- 请求格式错误或含有有禁止字段 (状态码: `400 Bad Request`):
```json
{
"status": "error",
"message": "Invalid input data or you are trying to update restricted fields"
}
```
---
### 3. 用户权限要求
- **普通用户**:
- 可以读取自己账户相关的订单 (`GET /orders/{orderId}`)。
- 只能更新允许字段，如订单地址 (`PUT /orders/{orderId}`)。
- **认证**: 必须使用有效的 `Bearer Token`。
- **管理员**:
- 可以读取和更新所有订单。
- 在更新订单时没有字段限制，但需要额外的管理员认证机制（如角色权限验证）。
---
### 小结
以上就是一个简洁的RESTful API设计，支持订单的读取与更新操作，并对用户权限进行了限制，保证了数据安全性且满足了普通用户的基本使用需求。
以下是一个为产品设计的 RESTful API 的详细说明，该 API 支持创建和读取操作，提供 URL 模式、HTTP 方法、请求/响应格式，并包含管理员访问权限的认证要求：
---
### **设定假设**
1. 产品的资源名称为 `Product`。
2. RESTful API 需要支持创建（Create - POST）和读取（Read - GET）操作。
3. 只有拥有管理员权限的用户才能创建新产品（通过 `admin` 权限进行认证检查）。
4. 读取操作对所有用户公开，不需要身份验证。
5. API 返回的响应采用 JSON 格式。
---
## **1. API 端点说明**
### **1.1 创建产品**
- **URL 模式**: `/api/products/`
- **HTTP 方法**: `POST`
- **请求头**:
- `Content-Type: application/json` （请求体为 JSON 格式）
- `Authorization: Bearer <token>` （只有管理员权限用户才能创建）
- **请求体格式**:
提供新产品的信息，例如产品名称、描述、价格等：
```json
{
"name": "string", // 产品名称（必填）
"description": "string", // 产品描述（选填）
"price": "float" // 产品价格（必填，正值）
}
```
- **响应格式**:
- 成功创建：
**状态码**: `201 Created`
```json
{
"id": "uuid", // 产品的唯一标识
"name": "string", // 产品名称
"description": "string",
"price": "float",
"created_at": "ISO 8601 timestamp",
"status": "success"
}
```
- 失败（如权限不足或无效请求体）：
**状态码**: 例如 `401 Unauthorized` 或 `400 Bad Request`
```json
{
"error": "string", // 错误描述
"status_code": 401
}
```
### **1.2 获取产品列表**
- **URL 模式**: `/api/products/`
- **HTTP 方法**: `GET`
- **请求头**: 可选 `Authorization: Bearer <token>`
- **查询参数**:
可用的查询选项用于过滤返回的产品列表:
- `?name=<部分名称>`: 按名称进行模糊搜索
- `?price_min=<金额>`: 最低价格过滤
- `?price_max=<金额>`: 最高价格过滤
- **响应格式**:
- 成功：
**状态码**: `200 OK`
```json
[
{
"id": "uuid", // 产品的唯一标识符
"name": "string", // 产品名称
"description": "string",
"price": "float",
"created_at": "ISO 8601 timestamp"
},
...
]
```
- 无数据时：
```json
[]
```
- 查询错误：
**状态码**: `400 Bad Request`
```json
{
"error": "string",
"status_code": 400
}
```
### **1.3 获取单个产品**
- **URL 模式**: `/api/products/{id}/`
- **HTTP 方法**: `GET`
- **请求头**: 可选 `Authorization: Bearer <token>`
- **路径参数**:
- `{id}`: 产品的唯一标识符（UUID 格式）
- **响应格式**:
- 成功：
**状态码**: `200 OK`
```json
{
"id": "uuid", // 产品的唯一标识
"name": "string", // 产品名称
"description": "string",
"price": "float",
"created_at": "ISO 8601 timestamp"
}
```
- 产品未找到：
**状态码**: `404 Not Found`
```json
{
"error": "Product not found",
"status_code": 404
}
```
---
## **2. 权限控制**
### **创建操作的管理员权限验证**
- **认证方式**: 基于 Token 的 Bearer 身份认证
- 通过 `Authorization` 请求头传递 Token：
```http
Authorization: Bearer <token>
```
- 在服务器端校验 Token 是否有效，解码后检查用户是否拥有 `admin` 权限。
### **读取操作的公开权限**
- 不需要身份认证，任何用户都可以访问。
- 如果某些敏感信息需要保护（如定价策略的查看限制），应增加对某些字段访问的控制。
---
## **3. 用于测试的示例**
### **示例 1: 创建新产品**
**请求**
```http
POST /api/products/ HTTP/1.1
Host: api.example.com
Authorization: Bearer abc123token
Content-Type: application/json
{
"name": "Wireless Headphones",
"description": "Noise cancelling over-ear headphones.",
"price": 199.99
}
```
**响应**
```http
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "e217b630-21a3-11ee-be56-0242ac120002",
"name": "Wireless Headphones",
"description": "Noise cancelling over-ear headphones.",
"price": 199.99,
"created_at": "2023-10-31T12:00:00Z",
"status": "success"
}
```
### **示例 2: 获取产品列表**
**请求**
```http
GET /api/products/?price_min=100 HTTP/1.1
Host: api.example.com
```
**响应**
```http
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": "e217b630-21a3-11ee-be56-0242ac120002",
"name": "Wireless Headphones",
"description": "Noise cancelling over-ear headphones.",
"price": 199.99,
"created_at": "2023-10-31T12:00:00Z"
},
{
"id": "f318c740-21a3-11ee-be56-0242ac120002",
"name": "Bluetooth Speaker",
"description": "Portable speaker with high-quality sound.",
"price": 149.99,
"created_at": "2023-10-30T15:00:00Z"
}
]
```
---
通过以上设计，你可以实现一个支持创建和读取产品的 RESTful API，同时包含管理员权限验证的具体逻辑。
快速获取标准化API设计方案，加速产品开发周期，确保输出符合行业规范的技术产品。
通过自动生成的RESTful API设计，减少重复性脑力劳动，提高工作效率和专注度。
无需技术背景，也能快速定义API需求，帮助团队实现精准开发对齐与明确分工。
为学生或受训者提供RESTful API设计范例与参考，助力快速掌握核心技能。
为企业提供敏捷技术解决方案，通过自动化的API设计提高实施效率，助推数字化项目落地。
帮助开发者快速设计符合RESTful规范的API端点，使其能够高效规划URL结构、明确HTTP方法、定义数据请求与响应格式，同时涵盖访问权限的认证要求，简化开发流程并提升API设计质量。
将模板生成的提示词复制粘贴到您常用的 Chat 应用（如 ChatGPT、Claude 等），即可直接对话使用，无需额外开发。适合个人快速体验和轻量使用场景。
把提示词模板转化为 API，您的程序可任意修改模板参数，通过接口直接调用，轻松实现自动化与批量处理。适合开发者集成与业务系统嵌入。
在 MCP client 中配置对应的 server 地址，让您的 AI 应用自动调用提示词模板。适合高级用户和团队协作，让提示词在不同 AI 工具间无缝衔接。
免费获取高级提示词-优惠即将到期
